Copyright (c) Hyperion Entertainment and contributors.

Difference between revisions of "Intuition Windows"

From AmigaOS Documentation Wiki
Jump to navigation Jump to search
 
(14 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
{{WIP}}
  
 
== Intuition Windows ==
  
== Intuition Windows ==
   
−
This chapter provides a general description of windows: how to open windows and define their characteristics; how to get the system gadgets for shaping, moving, closing, and depth arranging windows; how to handle window I/O; and how to preserve the display when windows get overlapped.
 +
This article provides a general description of windows: how to open windows and define their characteristics; how to get the system gadgets for shaping, moving, closing, and depth arranging windows; how to handle window I/O; and how to preserve the display when windows get overlapped.
   
 
== About Windows ==
  
== About Windows ==
Line 34: Line 33:
 
There is only one window in the system active at any time. The active window receives all user input, including keyboard and mouse events. This is also known as the ''input focus'', as all input is focused at this single point.
  
There is only one window in the system active at any time. The active window receives all user input, including keyboard and mouse events. This is also known as the ''input focus'', as all input is focused at this single point.
   
−
Some areas of the active window are displayed more boldly than those on inactive windows. The active window's borders are filled in with a color which is designed to stand out from the background while inactive windows have their borders filled with the background color. The specific coloring of active and inactive windows is dependent on the screen on which the window is opened. See the section "DrawInfo and the 3D Look" in the "Intuition Screens" chapter for more information.
 +
Some areas of the active window are displayed more boldly than those on inactive windows. The active window's borders are filled in with a color which is designed to stand out from the background while inactive windows have their borders filled with the background color. The specific coloring of active and inactive windows is dependent on the screen on which the window is opened. See the section [[Intuition_Screens#DrawInfo_and_the_3D_Look|DrawInfo and the 3D Look]] for more information.
   
 
Windows have two optional titles: one for the window and one for the screen. The window title appears in the top border of the window, regardless of whether the window is active or inactive. The window's screen title appears in the screen's title bar only when the window is active. This gives the user a secondary clue as to what application is active in the screen.
  
Windows have two optional titles: one for the window and one for the screen. The window title appears in the top border of the window, regardless of whether the window is active or inactive. The window's screen title appears in the screen's title bar only when the window is active. This gives the user a secondary clue as to what application is active in the screen.
Line 42: Line 41:
 
Each window may also have its own mouse-pointer image. Changing the active window will change the pointer to the one currently set for the new active window.
  
Each window may also have its own mouse-pointer image. Changing the active window will change the pointer to the one currently set for the new active window.
   
−
=== Window Types ===
 +
=== More Details ===
   
  +
The following sections describe Windows in more detail:
−
There are several types of windows which are described in [[Window Types]].
  
   
  +
* [[Window Types]] - Describes all the types of Windows available.
−
== Preserving the Window Display ==
  
  +
* [[Window Structures and Functions|Structures and Functions]] - Detailed description of structures and functions.
−  
  +
* [[Window Communication|Communicating with Intuition]] - How to communicate with a Window.
−
The layers library is what allows the display and manipulation of multiple overlapping rectangles, or ''layers''. Intuition uses the layers library to manage its windows, by associating a layer to each window.
  
  +
* [[Window Display Preservation|Display Preservation]] - How to preserve the display of a Window.
−  
−
Each window is a virtual display. When rendering, the application does not have to worry about the current size or position of its window, and what other windows might be partly or fully obscuring its window. The window's RastPort is the handle to the its virtual display space. Intuition and graphics library rendering calls will recognize that this RastPort belongs to a layer, and act accordingly.
  
−  
−
As windows are moved, resized, rearranged, opened, or closed, the on-screen representation changes. When part of a window which was visible now needs to appear in a new location, the layers library will move that imagery without involving the application. However, when part of a window that was previously obscured is revealed, or when a window is made larger, the imagery for the newly-visible part of the window needs to be redrawn. Intuition, through layers, offers three choices for how this is managed, trading off speed, memory usage, and application complexity.
  
−  
−
* The most basic type of window is called ''Simple Refresh''. When any graphics operation takes place in this kind of window, the visible parts are updated, but rendering to the obscured parts is discarded. When the window arrangement changes to reveal a previously obscured part of such a window, the application must refresh that area.
  
−  
−
* Alternately, a window may be made ''Smart Refresh'', which means that when rendering occurs, the system will not only update the visible parts of the window, but it will maintain the obscured parts as well, by using off-screen buffers. This means that when an obscured part of the window is revealed, the system will restore the imagery that belongs there. The application needs only to refresh parts of the window that appear when the window is made bigger. Smart Refresh windows use more memory than Simple Refresh windows (for the storage of obscured areas), but they are faster.
  
−  
−
* The third kind of window is called ''SuperBitMap''. In such a window, the system can refresh the window even when it is sized bigger. For this to work, the application must store a complete bitmap for the window's maximum size. Such a window is more work to manage, and uses yet more memory. SuperBitMap windows are used less often than the other two types.
  
−  
−
Intuition helps your application manage window refresh. First, Intuition will take care of redrawing the window border and any system and application gadgets in the window. Your application never has to worry about that. Second, Intuition will notify your application when it needs to refresh its window (by sending the IDCMP_REFRESHWINDOW event). Third, Intuition provides functions that restrict your rendering to the newly-revealed (damaged) areas only, which speeds up your refresh rendering and makes it look cleaner.
  
−  
−
The Intuition, layers, and graphics libraries work together to make rendering into and managing windows easy. You obtain your windows through Intuition, which uses the Layers library to manage the overlapping, resizing, and re-positioning of the window layers. The layers library is responsible for identifying the areas of each window that are visible, obscured but preserved off-screen, or obscured and not preserved. The rendering functions in the graphics library and Intuition library know how to render into the multiple areas that layers library establishes.
  
−  
−
Note that you may not directly manipulate layers on an Intuition screen. You cannot create your own layers on an Intuition screen, nor can you use the layers movement, sizing, or arrangement functions on Intuition windows. Use the corresponding Intuition calls instead. Some other Layers library calls (such as the locking calls) are sometimes used on Intuition screens and windows.
  
−  
−
=== Damage Regions ===
  
−  
−
The layers library and Intuition maintain a ''damage region'' for each window, which is the part of the window whose imagery is in need of repair, or refreshing. Several things can add areas of the window to the damage region:
  
−  
−
* Revealing an obscured part of a Simple Refresh window adds that area to the damage region
  
−
* Sizing a Simple or Smart Refresh window bigger along either axis adds the new area to the damage region
  
−
* Resizing a Simple or Smart Refresh window (smaller or bigger) adds the old and new border areas, and the areas occupied by certain gadgets (those whose position or size depend on window size) to the damage region.
  
−  
−
=== Refreshing Intuition Windows ===
  
−  
−
When the user or an application performs an Intuition operation which causes damage to a window, Intuition notifies that window's application. It does this by sending a message of the class IDCMP_REFRESHWINDOW to that window's IDCMP.
  
−  
−
In response to this message, your application should update the damaged areas. Rendering proceeds faster and looks cleaner if it is restricted to the damaged areas only. The BeginRefresh()/EndRefresh() pair achieve that. The application should call BeginRefresh() for the window, and then do its rendering. Any rendering that would have gone into undamaged areas of the window is automatically discarded; only the area in need of repair is affected. Finally, the application should call EndRefresh(), which removes the restriction on rendering, and informs the system that the damage region has been dealt with. Even if your application intends to do no rendering, it must at least call BeginRefresh()/EndRefresh(), to inform the system that the damage region is no longer needed. If your application never needs to render in response to a refresh event, it can avoid having to call BeginRefresh()/EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the WA_NoCareRefresh tag in the OpenWindowTagList() call.
  
−  
−
Note that by the time that your application receives notification that refresh is needed, Intuition will have already refreshed your window's border and all gadgets in the window, as needed. Thus, it is unnecessary to use any of the gadget-refreshing functions in response to an IDCMP_REFRESHWINDOW event.
  
−  
−
Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple rendering. All of the rendering functions in Intuition library and Graphics library are safe. Avoid RefreshGList() or RefreshGadgets(), or you risk deadlocking the computer. Avoid calls that may lock the LayerInfo or get complicated in Intuition, since BeginRefresh() leaves the window's layer or layers locked. Avoid AutoRequest() and EasyRequest(), and therefore all direct or indirect disk related DOS calls. See the [[Intuition_Gadgets|Intuition Gadgets]] section for more information on gadget restrictions with BeginRefresh() and EndRefresh().
  
−  
−
==== Simple Refresh ====
  
−  
−
For a Simple Refresh window, only those pixels actually on-screen are maintained by the system. When part of a Simple Refresh window is obscured, the imagery that was there is lost. As well, any rendering into obscured portions of such a window is discarded.
  
−  
−
When part of the window is newly revealed (either because the window was just made larger, or because that part used to be obscured by another window), the application must refresh any rendering it wishes to appear into that part. The application will learn that refresh is needed because Intuition sends an IDCMP_REFRESHWINDOW event.
  
−  
−
==== Smart Refresh ====
  
−  
−
If a window is of the Smart Refresh type, then the system will not only preserve those pixels which are actually on-screen, but it will save all obscured pixels that are within the current window's size. The system will refresh those parts of the window revealed by changes in the overlapping with other windows on the screen, without involving the application. However, any part of the window revealed through the sizing of the window must be redrawn by the application. Again, Intuition will notify the application through the IDCMP_REFRESHWINDOW event.
  
−  
−
Because the obscured areas are kept in off-screen buffers, Smart Refresh windows are refreshed faster than Simple Refresh windows are, and often without involving the application. Of course, for the same reason, they use more display memory.
  
−  
−
==== SuperBitMap Refresh ====
  
−  
−
The SuperBitMap refresh type allows the application to provide and maintain bitmap memory for graphics in the window. The bitmap can be any size as long as the window sizing limits respect the maximum size of the bitmap.
  
−  
−
SuperBitMap windows have their own memory for maintaining all obscured parts of the window up to the size of the defined bitmap, including those parts outside of the current window. Intuition will update all parts of the window that are revealed through changes in sizing and changes in window overlapping. The application never needs to redraw portions of the window that were revealed by sizing or positioning windows in the screen.
  
−  
−
SuperBitMap windows require the application to allocate a bitmap for use as off-screen memory, instead of using Intuition managed buffers. This bitmap must be as large as, or larger than, the inner window's maximum dimensions (that is, the window's outside dimensions less the border sizes).
  
−  
−
SuperBitMap windows are almost always WFLG_GIMMEZEROZERO, which renders the borders and system gadgets in a separate bitmap. If the application wishes to create a SuperBitMap window that is not GimmeZeroZero, it must make the window borderless with no system gadgets, so that no border imagery is rendered by Intuition into the application's bitmap.
  
−  
−
=== Intuition Refresh Events ===
  
−  
−
When using a Simple Refresh or a Smart Refresh windows, the program may receive refresh events, informing it to update the display. See the above discussion for information on when refresh events are sent.
  
−  
−
A message of the class IDCMP_REFRESHWINDOW arrives at the IDCMP, informing the program of the need to update the display. The program must take some action when it receives a refresh event, even if it is just the acceptable minimum action described below.
  
−  
−
On receiving a refresh event, BeginRefresh() must be called, then the program should redraw its display, and, finally, call EndRefresh(). The minimum required action is to call the BeginRefresh()/EndRefresh() pair. This allows Intuition and the Layers library keep things sorted and organized.
  
−  
−
=== Optimized Window Refreshing ===
  
−  
−
Bracketing the display updating in the BeginRefresh()/EndRefresh() pair automatically restricts all rendering to the "damaged" areas.
  
−  
−
<syntaxhighlight>
  
−
VOID BeginRefresh( struct Window *window );
  
−
VOID EndRefresh ( struct Window *window, LONG complete );
  
−
</syntaxhighlight>
  
−  
−
These functions makes sure that refreshing is done in the most efficient way, only redrawing those portions of the window that really need to be redrawn. The rest of the rendering commands are discarded.
  
−  
−
Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple rendering. All of the rendering functions in Intuition library and Graphics library are safe. Calls to RefreshGadgets() are not permitted. Avoid calls that may lock the LayerInfo, or get complicated in Intuition, since BeginRefresh() leaves the window's layer or layers locked. Avoid AutoRequest(), and therefore all direct or indirect disk related DOS calls. See [[Intuition_Gadgets|Intuition Gadgets]] for more information on gadget restrictions with BeginRefresh()/EndRefresh().
  
−  
−
Certain applications do not need to receive refresh events, and can avoid having to call BeginRefresh() and EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the WA_NoCareRefresh tag in the OpenWindowTagList() call.
  
−  
−
The EndRefresh() function takes a boolean value as an argument (complete in the prototype above). This value determines whether refreshing is completely finished. When set to FALSE, further refreshing may be performed between subsequent BeginRefresh()/ EndRefresh() pairs. Set the boolean to TRUE for the last call to EndRefresh().
  
−  
−
It is critical that applications performing multiple BeginRefresh() and EndRefresh() pairs using EndRefresh(win,FALSE) hold layers locked through the entire process. The layer lock may only be released after the final call to EndRefresh(win,TRUE). See [[Layers_Library|Layers Library]] for more details.
  
−  
−
The procedures outlined in this section take care of refreshing what is inside the window. Another function named RefreshWindowFrame() refreshes window borders, including the title region and gadgets:
  
−  
−
<syntaxhighlight>
  
−
VOID RefreshWindowFrame( struct Window *window );
  
−
</syntaxhighlight>
  
−  
−
Applications can use this function to update window borders after overwriting them with graphics.
  
−  
−
=== Setting up a SuperBitMap Window ===
  
−  
−
SuperBitMap windows are created by setting the WFLG_SUPER_BITMAP flag, or by specifying the WA_SuperBitMap tag in the OpenWindowTagList() call. A pointer to an allocated and initialized BitMap structure must be provided.
  
−  
−
A SuperBitMap window requires the application to allocate and initialize its own bitmap. This entails allocating a BitMap structure, initializing the structure and allocating memory for the bit planes.
  
−  
−
Allocate a BitMap structure with the Exec AllocMem() function. Then use the graphics function InitBitMap() to initialize the BitMap structure:
  
−  
−
<pre>
  
−
VOID InitBitMap( struct BitMap *bitMap, LONG depth, LONG width, LONG height );
  
−
</pre>
  
−  
−
InitBitMap() fills in fields in the BitMap structure describing how a linear memory area is organized as a series of one or more rectangular bit-planes.
  
−  
−
Once you have allocated and initialized the BitMap structure, use the graphics library function AllocRaster() to allocate the memory space for all the bit planes.
  
−  
−
<pre>
  
−
PLANEPTR AllocRaster( ULONG width, ULONG height );
  
−
</pre>
  
−  
−
The example listed in the next section shows how to allocate a BitMap structure, initialize it with InitBitMap() and use AllocRaster() function to set up memory for the bitplanes.
  
−  
−
==== Graphics and Layers Functions for SuperBitMap Windows ====
  
−  
−
The portion of the bitmap showing within a SuperBitMap window is controlled by the application. Initially, the window shows the bitmap starting from its origin (0,0) and clipped to fit within the window layer. The visible portion of the bitmap can be scrolled around within the window using the layers library ScrollLayer() function:
  
−  
−
<pre>
  
−
VOID ScrollLayer(LONG unused, struct Layer *layer, LONG dx, LONG dy)
  
−
</pre>
  
−  
−
Pass this function a pointer to the window's layer in layer and the scroll offsets in dx and dy. (A pointer to the window's layer can be obtained from Window.RPort-&gt;Layer.)
  
−  
−
When rendering operations are performed in a SuperBitMap window, any rendering that falls outside window boundaries is done in the application's bitmap. Rendering that falls within window bounds is done in the screen's bitmap. Before performing an operation such as a save on the application bitmap, the graphics library function SyncSBitMap() should be called:
  
−  
−
<pre>
  
−
VOID SyncSBitMap(struct Layer *layer)
  
−
</pre>
  
−  
−
Pass this function a pointer to the window's layer. SyncSBitMap() copies the window contents to the corresponding part of the application bitmap, bringing it up to date. (If no rendering operations have been performed this call is not necessary.)
  
−  
−
Similarly, after making any changes to the application bitmap such as loading a new one, the window's layer should be locked and the CopySBitMap() function should be called.
  
−  
−
<pre>
  
−
VOID CopySBitMap(struct Layer *)
  
−
</pre>
  
−  
−
This function copies the new information in the appropriate area of the underlying bitmap to the window's layer.
  
−  
−
For more information about bitmaps and layers, see the [[Graphics_Primitives|Graphics Primitives]] and [[Layers_Library|Layers Library]]. Also see the &lt;graphics/clip.h&gt;, &lt;graphics/gfx.h&gt;, &lt;graphics/layers.h &gt; files in the SDK.
  
−  
−
==== SuperBitMap Window Example ====
  
−  
−
This example shows how to implement a superbitmap, and uses a host of Intuition facilities. Further reading of other Intuition and graphics chapters may be required for a complete understanding of this example.
  
−  
−
<pre>
  
−
;/* lines.c - Execute me to compile me with SAS C 5.10
  
−
LC -b1 -cfistq -v -y -j73 lines.c
  
−
Blink FROM LIB:c.o,lines.o TO lines LIBRARY LIB:LC.lib,LIB:Amiga.lib
  
−
quit
  
−  
−
** lines.c -- implements a superbitmap with scroll gadgets
  
−
** This program requires V37, as it uses calls to OpenWindowTags(),
  
−
** LockPubScreen().
  
−
*/
  
−  
−
/* Enforces use of new prefixed Intuition flag names */
  
−
#define INTUI_V36_NAMES_ONLY
  
−  
−
#include &lt;exec/types.h&gt;
  
−
#include &lt;exec/memory.h&gt;
  
−
#include &lt;intuition/intuition.h&gt;
  
−  
−
#include &lt;clib/exec_protos.h&gt;
  
−
#include &lt;clib/layers_protos.h&gt;
  
−
#include &lt;clib/graphics_protos.h&gt;
  
−
#include &lt;clib/intuition_protos.h&gt;
  
−  
−
/* Random number function in amiga.lib (see amiga.lib.doc) */
  
−
UWORD RangeRand( unsigned long maxValue );
  
−  
−
#ifdef LATTICE
  
−
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
  
−
int chkabort(void) { return(0); } /* really */
  
−
#endif
  
−  
−
#define WIDTH_SUPER (800)
  
−
#define HEIGHT_SUPER (600)
  
−  
−
#define UP_DOWN_GADGET (0)
  
−
#define LEFT_RIGHT_GADGET (1)
  
−
#define NO_GADGET (2)
  
−  
−
#define MAXPROPVAL (0xFFFFL)
  
−  
−
#define GADGETID(x) (((struct Gadget *)(msg-&gt;IAddress))-&gt;GadgetID)
  
−  
−
#define LAYERXOFFSET(x) (x-&gt;RPort-&gt;Layer-&gt;Scroll_X)
  
−
#define LAYERYOFFSET(x) (x-&gt;RPort-&gt;Layer-&gt;Scroll_Y)
  
−  
−
/* A string with this format will be found by the version command.
  
−
** This will allow users to give version numbers with error reports.
  
−
*/
  
−
UBYTE vers[] = &quot;$VER: lines 37.2&quot;;
  
−  
−
struct Library *GfxBase;
  
−
struct Library *IntuitionBase;
  
−
struct Library *LayersBase;
  
−  
−
struct Window *Win = NULL; /* window pointer */
  
−
struct PropInfo BotGadInfo = {0};
  
−
struct Image BotGadImage = {0};
  
−
struct Gadget BotGad = {0};
  
−
struct PropInfo SideGadInfo = {0};
  
−
struct Image SideGadImage = {0};
  
−
struct Gadget SideGad = {0};
  
−  
−  
−
/* Prototypes for our functions */
  
−
VOID initBorderProps(struct Screen *myscreen);
  
−
VOID doNewSize(void);
  
−
VOID doDrawStuff(void);
  
−
VOID doMsgLoop(void);
  
−
VOID superWindow(struct Screen *myscreen);
  
−  
−  
−
/*
  
−
** main
  
−
** Open all required libraries and get a pointer to the default public screen.
  
−
** Cleanup when done or on error.
  
−
*/
  
−
VOID main(int argc, char **argv)
  
−
{
  
−
struct Screen *myscreen;
  
−  
−
/* open all of the required libraries for the program.
  
−
**
  
−
** require version 37 of the Intuition library.
  
−
*/
  
−  
−
if (IntuitionBase = OpenLibrary(&quot;intuition.library&quot;,37L))
  
−
{
  
−
if (GfxBase = OpenLibrary(&quot;graphics.library&quot;,33L))
  
−
{
  
−
if (LayersBase = OpenLibrary(&quot;layers.library&quot;,33L))
  
−
{
  
−
/* LockPubScreen()/UnlockPubScreen is only available under V36
  
−
** and later... Use GetScreenData() under V34 systems to get a
  
−
** copy of the screen structure...
  
−
*/
  
−
if (NULL != (myscreen = LockPubScreen(NULL)))
  
−
{
  
−
superWindow(myscreen);
  
−
UnlockPubScreen(NULL,myscreen);
  
−
}
  
−
CloseLibrary(LayersBase);
  
−
}
  
−
CloseLibrary(GfxBase);
  
−
}
  
−
CloseLibrary(IntuitionBase);
  
−
}
  
−
}
  
−  
−  
−
/*
  
−
** Create, initialize and process the super bitmap window.
  
−
** Cleanup if any error.
  
−
*/
  
−
VOID superWindow(struct Screen *myscreen)
  
−
{
  
−
struct BitMap *bigBitMap;
  
−
WORD planeNum;
  
−
WORD allocatedBitMaps;
  
−  
−
/* set-up the border prop gadgets for the OpenWindow() call. */
  
−
initBorderProps(myscreen);
  
−  
−
/* The code relies on the allocation of the BitMap structure with
  
−
** the MEMF_CLEAR flag. This allows the assumption that all of the
  
−
** bitmap pointers are NULL, except those successfully allocated
  
−
** by the program.
  
−
*/
  
−
if (bigBitMap = AllocMem(sizeof(struct BitMap), MEMF_PUBLIC | MEMF_CLEAR))
  
−
{
  
−
InitBitMap(bigBitMap, myscreen-&gt;BitMap.Depth, WIDTH_SUPER, HEIGHT_SUPER);
  
−  
−
allocatedBitMaps = TRUE;
  
−
for (planeNum = 0;
  
−
(planeNum &lt; myscreen-&gt;BitMap.Depth) &amp;&amp; (allocatedBitMaps == TRUE);
  
−
planeNum++)
  
−
{
  
−
bigBitMap-&gt;Planes[planeNum] = AllocRaster(WIDTH_SUPER, HEIGHT_SUPER);
  
−
if (NULL == bigBitMap-&gt;Planes[planeNum])
  
−
allocatedBitMaps = FALSE;
  
−
}
  
−  
−
/* Only open the window if the bitplanes were successfully
  
−
** allocated. Fail silently if they were not.
  
−
*/
  
−
if (TRUE == allocatedBitMaps)
  
−
{
  
−
/* OpenWindowTags() and OpenWindowTagList() are only available
  
−
** when the library version is at least V36. Under earlier
  
−
** versions of Intuition, use OpenWindow() with a NewWindow
  
−
** structure.
  
−
*/
  
−
if (NULL != (Win = OpenWindowTags(NULL,
  
−
WA_Width, 150,
  
−
WA_Height, 4 * (myscreen-&gt;WBorTop + myscreen-&gt;Font-&gt;ta_YSize + 1),
  
−
WA_MaxWidth, WIDTH_SUPER,
  
−
WA_MaxHeight, HEIGHT_SUPER,
  
−
WA_IDCMP, IDCMP_GADGETUP | IDCMP_GADGETDOWN |
  
−
IDCMP_NEWSIZE | IDCMP_INTUITICKS | IDCMP_CLOSEWINDOW,
  
−
WA_Flags, WFLG_SIZEGADGET | WFLG_SIZEBRIGHT | WFLG_SIZEBBOTTOM |
  
−
WFLG_DRAGBAR | WFLG_DEPTHGADGET | WFLG_CLOSEGADGET |
  
−
WFLG_SUPER_BITMAP | WFLG_GIMMEZEROZERO | WFLG_NOCAREREFRESH,
  
−
WA_Gadgets, &amp;(SideGad),
  
−
WA_Title, &amp;vers[6], /* take title from version string */
  
−
WA_PubScreen, myscreen,
  
−
WA_SuperBitMap, bigBitMap,
  
−
TAG_END)))
  
−
{
  
−
/* set-up the window display */
  
−
SetRast(Win-&gt;RPort,0); /* clear the bitplanes */
  
−
SetDrMd(Win-&gt;RPort,JAM1);
  
−  
−
doNewSize(); /* adjust props to represent portion visible */
  
−
doDrawStuff();
  
−  
−
/* process the window, return on IDCMP_CLOSEWINDOW */
  
−
doMsgLoop();
  
−  
−
CloseWindow(Win);
  
−
}
  
−
}
  
−  
−
for (planeNum = 0; planeNum &lt; myscreen-&gt;BitMap.Depth; planeNum++)
  
−
{
  
−
/* free only the bitplanes actually allocated... */
  
−
if (NULL != bigBitMap-&gt;Planes[planeNum])
  
−
FreeRaster(bigBitMap-&gt;Planes[planeNum], WIDTH_SUPER, HEIGHT_SUPER);
  
−
}
  
−
FreeMem(bigBitMap,sizeof(struct BitMap));
  
−
}
  
−
}
  
−  
−
/*
  
−
** Set-up the prop gadgets--initialize them to values that fit
  
−
** into the window border. The height of the prop gadget on the side
  
−
** of the window takes the height of the title bar into account in its
  
−
** set-up. note the initialization assumes a fixed size &quot;sizing&quot; gadget.
  
−
**
  
−
** Note also, that the size of the sizing gadget is dependent on the
  
−
** screen resolution. The numbers given here are only valid if the
  
−
** screen is NOT lo-res. These values must be re-worked slightly
  
−
** for lo-res screens.
  
−
**
  
−
** The PROPNEWLOOK flag is ignored by 1.3.
  
−
*/
  
−
VOID initBorderProps(struct Screen *myscreen)
  
−
{
  
−
/* initializes the two prop gadgets.
  
−
**
  
−
** Note where the PROPNEWLOOK flag goes. Adding this flag requires
  
−
** no extra storage, but tells the system that our program is
  
−
** expecting the new-look prop gadgets under 2.0.
  
−
*/
  
−
BotGadInfo.Flags = AUTOKNOB | FREEHORIZ | PROPNEWLOOK;
  
−
BotGadInfo.HorizPot = 0;
  
−
BotGadInfo.VertPot = 0;
  
−
BotGadInfo.HorizBody = -1;
  
−
BotGadInfo.VertBody = -1;
  
−  
−
BotGad.LeftEdge = 3;
  
−
BotGad.TopEdge = -7;
  
−
BotGad.Width = -23;
  
−
BotGad.Height = 6;
  
−  
−
BotGad.Flags = GFLG_RELBOTTOM | GFLG_RELWIDTH;
  
−
BotGad.Activation = GACT_RELVERIFY | GACT_IMMEDIATE | GACT_BOTTOMBORDER;
  
−
BotGad.GadgetType = GTYP_PROPGADGET | GTYP_GZZGADGET;
  
−
BotGad.GadgetRender = (APTR)&amp;(BotGadImage);
  
−
BotGad.SpecialInfo = (APTR)&amp;(BotGadInfo);
  
−
BotGad.GadgetID = LEFT_RIGHT_GADGET;
  
−  
−
SideGadInfo.Flags = AUTOKNOB | FREEVERT | PROPNEWLOOK;
  
−
SideGadInfo.HorizPot = 0;
  
−
SideGadInfo.VertPot = 0;
  
−
SideGadInfo.HorizBody = -1;
  
−
SideGadInfo.VertBody = -1;
  
−  
−
/* NOTE the TopEdge adjustment for the border and the font for V36.
  
−
*/
  
−
SideGad.LeftEdge = -14;
  
−
SideGad.TopEdge = myscreen-&gt;WBorTop + myscreen-&gt;Font-&gt;ta_YSize + 2;
  
−
SideGad.Width = 12;
  
−
SideGad.Height = -SideGad.TopEdge - 11;
  
−  
−
SideGad.Flags = GFLG_RELRIGHT | GFLG_RELHEIGHT;
  
−
SideGad.Activation = GACT_RELVERIFY | GACT_IMMEDIATE | GACT_RIGHTBORDER;
  
−
SideGad.GadgetType = GTYP_PROPGADGET | GTYP_GZZGADGET;
  
−
SideGad.GadgetRender = (APTR)&amp;(SideGadImage);
  
−
SideGad.SpecialInfo = (APTR)&amp;(SideGadInfo);
  
−
SideGad.GadgetID = UP_DOWN_GADGET;
  
−
SideGad.NextGadget = &amp;(BotGad);
  
−
}
  
−  
−  
−
/*
  
−
** This function does all the work of drawing the lines
  
−
*/
  
−
VOID doDrawStuff()
  
−
{
  
−
WORD x1,y1,x2,y2;
  
−
WORD pen,ncolors,deltx,delty;
  
−  
−
ncolors = 1 &lt;&lt; Win-&gt;WScreen-&gt;BitMap.Depth;
  
−
deltx = RangeRand(6)+2;
  
−
delty = RangeRand(6)+2;
  
−  
−
pen = RangeRand(ncolors-1) + 1;
  
−
SetAPen(Win-&gt;RPort,pen);
  
−
for(x1=0, y1=0, x2=WIDTH_SUPER-1, y2=HEIGHT_SUPER-1;
  
−
x1 &lt; WIDTH_SUPER;
  
−
x1 += deltx, x2 -= deltx)
  
−
{
  
−
Move(Win-&gt;RPort,x1,y1);
  
−
Draw(Win-&gt;RPort,x2,y2);
  
−
}
  
−  
−
pen = RangeRand(ncolors-1) + 1;
  
−
SetAPen(Win-&gt;RPort,pen);
  
−
for(x1=0, y1=0, x2=WIDTH_SUPER-1, y2=HEIGHT_SUPER-1;
  
−
y1 &lt; HEIGHT_SUPER;
  
−
y1 += delty, y2 -= delty)
  
−
{
  
−
Move(Win-&gt;RPort,x1,y1);
  
−
Draw(Win-&gt;RPort,x2,y2);
  
−
}
  
−
}
  
−  
−
/*
  
−
** This function provides a simple interface to ScrollLayer
  
−
*/
  
−
VOID slideBitMap(WORD Dx,WORD Dy)
  
−
{
  
−
ScrollLayer(0,Win-&gt;RPort-&gt;Layer,Dx,Dy);
  
−
}
  
−  
−
/*
  
−
** Update the prop gadgets and bitmap positioning when the size changes.
  
−
*/
  
−
VOID doNewSize()
  
−
{
  
−
ULONG tmp;
  
−  
−
tmp = LAYERXOFFSET(Win) + Win-&gt;GZZWidth;
  
−
if (tmp &gt;= WIDTH_SUPER)
  
−
slideBitMap(WIDTH_SUPER-tmp,0);
  
−  
−
NewModifyProp(&amp;(BotGad),Win,NULL,AUTOKNOB | FREEHORIZ,
  
−
((LAYERXOFFSET(Win) * MAXPROPVAL) /
  
−
(WIDTH_SUPER - Win-&gt;GZZWidth)),
  
−
NULL,
  
−
((Win-&gt;GZZWidth * MAXPROPVAL) / WIDTH_SUPER),
  
−
MAXPROPVAL,
  
−
1);
  
−  
−
tmp = LAYERYOFFSET(Win) + Win-&gt;GZZHeight;
  
−
if (tmp &gt;= HEIGHT_SUPER)
  
−
slideBitMap(0,HEIGHT_SUPER-tmp);
  
−  
−
NewModifyProp(&amp;(SideGad),Win,NULL,AUTOKNOB | FREEVERT,
  
−
NULL,
  
−
((LAYERYOFFSET(Win) * MAXPROPVAL) /
  
−
(HEIGHT_SUPER - Win-&gt;GZZHeight)),
  
−
MAXPROPVAL,
  
−
((Win-&gt;GZZHeight * MAXPROPVAL) / HEIGHT_SUPER),
  
−
1);
  
−
}
  
−  
−
/*
  
−
** Process the currently selected gadget.
  
−
** This is called from IDCMP_INTUITICKS and when the gadget is released
  
−
** IDCMP_GADGETUP.
  
−
*/
  
−
VOID checkGadget(UWORD gadgetID)
  
−
{
  
−
ULONG tmp;
  
−
WORD dX = 0;
  
−
WORD dY = 0;
  
−  
−
switch (gadgetID)
  
−
{
  
−
case UP_DOWN_GADGET:
  
−
tmp = HEIGHT_SUPER - Win-&gt;GZZHeight;
  
−
tmp = tmp * SideGadInfo.VertPot;
  
−
tmp = tmp / MAXPROPVAL;
  
−
dY = tmp - LAYERYOFFSET(Win);
  
−
break;
  
−
case LEFT_RIGHT_GADGET:
  
−
tmp = WIDTH_SUPER - Win-&gt;GZZWidth;
  
−
tmp = tmp * BotGadInfo.HorizPot;
  
−
tmp = tmp / MAXPROPVAL;
  
−
dX = tmp - LAYERXOFFSET(Win);
  
−
break;
  
−
}
  
−
if (dX || dY)
  
−
slideBitMap(dX,dY);
  
−
}
  
−  
−
/*
  
−
** Main message loop for the window.
  
−
*/
  
−
VOID doMsgLoop()
  
−
{
  
−
struct IntuiMessage *msg;
  
−
WORD flag = TRUE;
  
−
UWORD currentGadget = NO_GADGET;
  
−  
−
while (flag)
  
−
{
  
−
/* Whenever you want to wait on just one message port */
  
−
/* you can use WaitPort(). WaitPort() doesn't require */
  
−
/* the setting of a signal bit. The only argument it */
  
−
/* requires is the pointer to the window's UserPort */
  
−
WaitPort(Win-&gt;UserPort);
  
−
while (msg = (struct IntuiMessage *)GetMsg(Win-&gt;UserPort))
  
−
{
  
−
switch (msg-&gt;Class)
  
−
{
  
−
case IDCMP_CLOSEWINDOW:
  
−
flag = FALSE;
  
−
break;
  
−
case IDCMP_NEWSIZE:
  
−
doNewSize();
  
−
doDrawStuff();
  
−
break;
  
−
case IDCMP_GADGETDOWN:
  
−
currentGadget = GADGETID(msg);
  
−
break;
  
−
case IDCMP_GADGETUP:
  
−
checkGadget(currentGadget);
  
−
currentGadget = NO_GADGET;
  
−
break;
  
−
case IDCMP_INTUITICKS:
  
−
checkGadget(currentGadget);
  
−
break;
  
−
}
  
−
ReplyMsg((struct Message *)msg);
  
−
}
  
−
}
  
−
}
  
−
</pre>
  
−  
−
== The Window Structure ==
  
−  
−
The Window structure is the main Intuition data structure used to represent a window. For the most part, applications treat this structure only as a handle. Window operations are performed by calling system functions that take Window as an argument instead of directly manipulating fields within the structure. However, there are some useful variables in a Window structure which are discussed in this section.
  
−  
−
<syntaxhighlight>
  
−
struct Window
  
−
{
  
−
struct Window *NextWindow;
  
−
WORD LeftEdge, TopEdge, Width, Height;
  
−
WORD MouseY, MouseX;
  
−
WORD MinWidth, MinHeight;
  
−
UWORD MaxWidth, MaxHeight;
  
−
ULONG Flags;
  
−
struct Menu *MenuStrip;
  
−
UBYTE *Title;
  
−
struct Requester *FirstRequest, *DMRequest;
  
−
WORD ReqCount;
  
−
struct Screen *WScreen;
  
−
struct RastPort *RPort;
  
−
BYTE BorderLeft, BorderTop, BorderRight, BorderBottom;
  
−
struct RastPort *BorderRPort;
  
−
struct Gadget *FirstGadget;
  
−
struct Window *Parent, *Descendant;
  
−
UWORD *Pointer;
  
−
BYTE PtrHeight, PtrWidth;
  
−
BYTE XOffset, YOffset;
  
−
ULONG IDCMPFlags;
  
−
struct MsgPort *UserPort, *WindowPort;
  
−
struct IntuiMessage *MessageKey;
  
−
UBYTE DetailPen, BlockPen;
  
−
struct Image *CheckMark;
  
−
UBYTE *ScreenTitle;
  
−
WORD GZZMouseX, GZZMouseY, GZZWidth, GZZHeight;
  
−
UBYTE *ExtData;
  
−
BYTE *UserData;
  
−
struct Layer *WLayer;
  
−
struct TextFont *IFont;
  
−
ULONG MoreFlags;
  
−
};
  
−
</syntaxhighlight>
  
−  
−
; LeftEdge, TopEdge, Width and Height
  
−
: These variables reflect current position and size of the window. If the user sizes or positions the window, then these values will change. The position of the window is relative to the upper left corner of the screen.
  
−  
−
; MouseX, MouseY, GZZMouseX, GZZMouseY
  
−
: The current position of the Intuition pointer with respect to the window, whether or not this window is currently the active one. For GimmeZeroZero windows, the GZZ variables reflect the position relative to the inner layer (see "Window Types" below). For normal windows, the GZZ variables reflect the position relative to the window origin after taking the borders into account.
  
−  
−
; ReqCount
  
−
: Contains a count of the number of requesters currently displayed in the window. Do not rely on the value in this field, instead use IDCMP_REQSET and IDCMP_REQCLEAR to indirectly determine the number of open requesters in the window.
  
−  
−
; WScreen
  
−
: A pointer to the Screen structure of the screen on which this window was opened.
  
−  
−
; RPort
  
−
: A pointer to this window's RastPort structure. Use this RastPort pointer to render into your window with Intuition or graphics library rendering functions.
  
−  
−
; BorderLeft, BorderTop, BorderRight, BorderBottom
  
−
: These variables describe the actual size of the window borders. The border size is not changed after the window is opened.
  
−  
−
; BorderRPort
  
−
: With GimmeZeroZero windows, this variable points to the RastPort for the outer layer, in which the border gadgets are kept.
  
−  
−
; UserData
  
−
: This pointer is available for application use. The program can attach a data block to this window by setting this variable to point to the data.
  
−  
−
For a commented listing of the Window structure see &lt;intuition/intuition.h&gt; in the SDK.
  
−  
−
== Window Attributes ==
  
−  
−
This section discusses all window attributes. As mentioned earlier, a window's attributes may be specified with either TagItems, NewWindow or ExtNewWindow depending on how the window is opened.
  
−  
−
Attributes are listed here by their TagItem ID name (TagItem.ti_Tag). For each tag item, the equivalent field setting in the NewWindow structure is also listed if it exists. Some window attributes specified with tags have no NewWindow equivalent.
  
−  
−
=== Extended New Window ===
  
−  
−
Of the three functions for opening a window, only OpenWindow() is present in all versions of the OS. This function takes a NewWindow structure as its sole argument. In order to allow applications to use the OpenWindow() call with TagItem attributes, an extended version of the NewWindow structure has been created named ExtNewWindow.
  
−  
−
Setting WFLG_NW_EXTENDED in the NewWindow.Flags field specifies to the OpenWindow() call that this NewWindow structure is really an ExtNewWindow structure. This is simply a standard NewWindow structure with a pointer to a tag list at the end. Since WFLG_NW_EXTENDED is ignored prior to V36, information provided in the tag list will be ignored by earlier versions of Intuition. Note that WFLG_NW_EXTENDED may not be specified in the WA_Flags tag.
  
−  
−
=== Window Attribute Tags ===
  
−  
−
; WA_Left, WA_Top, WA_Width and WA_Height
  
−
: Describe where the window will first appear on the screen and how large it will be initially. These dimensions are relative to the top left corner of the screen, which has the coordinates (0,0).
  
−  
−
: WA_Left is the initial x position, or offset, from the left edge of the screen. The leftmost pixel is pixel 0, and values increase to the right. Equivalent to NewWindow.LeftEdge.
  
−  
−
: WA_Top is the initial y position, or offset, from the top edge of the screen. The topmost pixel is pixel 0, and values increase to the bottom. Equivalent to NewWindow.TopEdge.
  
−  
−
: WA_Width is the initial window width in pixels. This Tag is equivalent to NewWindow.Width.
  
−  
−
: WA_Height is the initial window height in lines. This Tag is equivalent to NewWindow.Height.
  
−  
−
; WA_DetailPen and WA_BlockPen
  
−
: WA_DetailPen specifies the pen number for the rendering of window details like gadgets or text in the title bar. WA_BlockPen specifies the pen number for window block fills, like the title bar. These pens are also used for rendering menus. Equivalent to NewWindow.DetailPen and NewWindow.BlockPen.
  
−  
−
: The specific color associated with each pen number depends on the screen. Specifying -1 for these values sets the window's detail and block pen the same as the screen's detail and block pen.
  
−  
−
: Detail pen and block pen have largely been replaced starting with V36 by the pen array in the DrawInfo structure. See the section on "DrawInfo and the 3D Look" in [[Intuition_Screens|Intuition Screens]] for more information.
  
−  
−
; WA_IDCMP
  
−
: IDCMP flags tell Intuition what user input events the application wants to be notified about. The IDCMP flags are listed and described in the OpenWindowTagList() description in the SDK and in [[Intuition_Input_and_Output_Methods|Intuition Input and Output Methods]]. Equivalent to NewWindow.IDCMPFlags.
  
−  
−
: If any of these flags are set, Intuition creates a pair of message ports for the window (one internal to Intuition and one used by the application). These ports are for handling messages about user input events. If WA_IDCMP is NULL or unspecified, no IDCMP is created for this window.
  
−  
−
: The ModifyIDCMP() function can be used to change the window's IDCMP flags after it is open.
  
−  
−
; WA_Gadgets
  
−
: A pointer to the first in the linked list of Gadget structures that are to be included in this window. These gadgets are application gadgets, not system gadgets. See [[Intuition_Gadgets|Intuition Gadgets]] for more information. Equivalent to NewWindow.FirstGadget.
  
−  
−
; WA_Checkmark
  
−
: A pointer to an Image structure, which is to be used as the checkmark image in this window's menus. To use the default checkmark, do not specify this tag or set this field to NULL. Equivalent to NewWindow.CheckMark.
  
−  
−
; WA_Title
  
−
: A pointer to a NULL terminated text string, which is used as the window title and is displayed in the window's title bar.
  
−  
−
: Intuition draws the text using the colors defined in the DrawInfo pen array (DrawInfo.dri_Pens) and displays as much as possible of the window title, depending upon the current width of the title bar. Equivalent to NewWindow.Title. See "DrawInfo and the 3D Look" in [[Intuition_Screens|Intuition Screens]] for more information on the pen array.
  
−  
−
: The title is rendered in the screen's default font.
  
−  
−
: A title bar is added to the window if any of the properties WA_DragBar (WFLG_WINDOWDRAG), WA_DepthGadget (WFLG_WINDOWDEPTH), WA_CloseGadget (WFLG_WINDOWCLOSE) or WA_Zoom are specified, or if text is specified for a window title. If no text is provided for the title, but one or more of these system gadgets are specified, the title bar will be blank. Equivalent to NewWindow.Title.
  
−  
−
; WA_ScreenTitle
  
−
: A pointer to a NULL terminated text string, which is used as the screen title and is displayed, when the window is active, in the screen's title bar. After the screen has been opened the screen's title may be changed by calling SetWindowTitles() (which is the only method of setting the window's screen title prior to V36).
  
−  
−
; WA_CustomScreen
  
−
: A pointer to the Screen structure of a screen created by this application. The window will be opened on this screen. The custom screen must already be opened when the OpenWindowTagList() call is made. Equivalent to NewWindow.Screen, also implies NewWindow.Type of CUSTOMSCREEN.
  
−  
−
; WA_MinWidth, WA_MinHeight, WA_MaxWidth and WA_MaxHeight
  
−
: These tags set the minimum and maximum values to which the user may size the window. If the flag WFLG_WINDOWSIZING is not set, then these variables are ignored. Values are measured in pixels. Use (~0) for the WA_MaxWidth (WA_MaxHeight) to allow for a window as wide (tall) as the screen. This is the complete screen, not the visible part or display clip.
  
−  
−
: Setting any of these variables to 0, will take the setting for that dimension from its initial value. For example, setting MinWidth to 0, will make the minimum width of this window equal to the initial width of the window.
  
−  
−
: Equivalent to NewWindow.MinWidth, NewWindow.MinHeight, NewWindow.MaxWidth and NewWindow.MaxHeight. Use the WindowLimits() function to change window size limits after the window is opened.
  
−  
−
; WA_InnerWidth and WA_InnerHeight
  
−
: Specify the dimensions of the interior region of the window, i.e., inside the border, independent of the border widths. When using WA_InnerWidth and WA_InnerHeight an application will probably want to set WA_AutoAdjust (see below).
  
−  
−
; WA_PubScreen
  
−
: Open the window as a visitor window on the public screen whose address is in the ti_Data field of the WA_PubScreen TagItem. To ensure that this screen remains open until OpenWindowTagList() has completed, the application must either be the screen's owner, have a window open on the screen, or use LockPubScreen(). Setting this tag implies screen type of PUBLICSCREEN.
  
−  
−
; WA_PubScreenName
  
−
: Declares that the window is to be opened as a visitor on the public screen whose name is pointed to by the ti_Data field of the WA_PubScreenName TagItem. The OpenWindowTagList() call will fail if it cannot obtain a lock on the named public screen and no fall back name (WA_PubScreenFallBack) is specified. Setting this tag implies screen type of PUBLICSCREEN.
  
−  
−
; WA_PubScreenFallBack
  
−
: A Boolean, specifies whether a visitor window should "fall back" to the default public screen (or Workbench) if the named public screen isn't available This tag is only meaningful when used in conjunction with WA_PubScreenName.
  
−  
−
; WA_Zoom
  
−
: Pointer to an array of four WORDs, the initial LeftEdge, TopEdge, Width and Height values for the alternate zoom position and size. It also specifies that the application wants a zoom gadget for the window, whether or not it has a sizing gadget.
  
−  
−
: A zoom gadget is always supplied to a window if it has both depth and sizing gadgets. This tag allows the application to open a window with a zoom gadget when the window does not have both the depth and sizing gadgets.
  
−  
−
; WA_MouseQueue
  
−
: An initial value for the mouse message backlog limit for this window. The SetMouseQueue() function will change this limit after the window is opened.
  
−  
−
; WA_RptQueue
  
−
: An initial value of repeat key backlog limit for this window.
  
−  
−
; WA_NewLookMenus
  
−
: Indicates that the window should use 3D menus or not. Defaults to FALSE for compatibility.
  
−  
−
=== Boolean Window Attribute Tags ===
  
−  
−
These boolean window tags are alternatives to the NewWindow.Flags bit fields with similar names. Unlike the tags discussed above, the ti_Data field of these TagItems is set to either TRUE or FALSE.
  
−  
−
; WA_SizeGadget
  
−
: Specifying this flag tells Intuition to add a sizing gadget to the window. Intuition places the sizing gadget in the lower right corner of the window. By default, the right border is adjusted to accommodate the sizing gadget, but the application can specify one of the following two flags to change this behavior. The WFLG_SIZEBRIGHT flag puts the sizing gadget in the right border. The WFLG_SIZEBBOTTOM flag puts the sizing gadget in the bottom border. Both flags may be specified, placing the gadget in both borders. Equivalent to NewWindow.Flags WFLG_SIZEGADGET.
  
−  
−
; WA_SizeBRight
  
−
: Place the size gadget in the right border. Equivalent to NewWindow.Flags WFLG_SIZEBRIGHT.
  
−  
−
; WA_SizeBBottom
  
−
: Place the size gadget in the bottom border. Equivalent to NewWindow.Flags WFLG_SIZEBBOTTOM.
  
−  
−
; WA_DragBar
  
−
: This flag turns the entire title bar of the window into a drag gadget, allowing the user to position the window by clicking in the title bar and dragging the mouse. Equivalent to NewWindow.Flags WFLG_DRAGBAR.
  
−  
−
; WA_DepthGadget
  
−
: Setting this flag adds a depth gadget to the window. This allows the user to change the window's depth arrangement with respect to other windows on the screen. Intuition places the depth gadget in the upper right corner of the window. Equivalent to NewWindow.Flags WFLG_DEPTHGADGET.
  
−  
−
; WA_CloseGadget
  
−
: Setting this flag attaches a close gadget to the window. When the user selects this gadget, Intuition transmits a message to the application. It is up to the application to close the window with a CloseWindow() call. Intuition places the close gadget in the upper left corner of the window. Equivalent to NewWindow.Flags WFLG_CLOSEGADGET.
  
−  
−
; WA_ReportMouse
  
−
: Send mouse movement events to the window as x,y coordinates. Also see the description of the IDCMP flag IDCMP_MOUSEMOVE, in [[Intuition_Input_and_Output_Methods|Intuition Input and Output Methods]]. Equivalent to NewWindow.Flags WFLG_REPORTMOUSE.
  
−  
−
: The WFLG_REPORTMOUSE flag in the Flags field of the Window structure may be modified on the fly by the program. Changing this flag must be done as an atomic operation. Most compilers generate atomic code for operations such as window->flags |= WFLG_REPORTMOUSE or window->flags &= ~WFLG_REPORTMOUSE. If you are unsure of getting an atomic operation from your compiler, you may wish to do this operation in assembler, or bracket the code with a Forbid()/Permit() pair.
  
−  
−
: The use of the ReportMouse() function is strongly discouraged, due to historic confusion over the parameter ordering.
  
−  
−
; WA_NoCareRefresh
  
−
: This window does not want IDCMP_REFRESHWINDOW events. Set this flag to prevent the window from receiving refresh window messages. Equivalent to NewWindow.Flags WFLG_NOCAREREFRESH. Intuition will manage BeginRefresh() and EndRefresh() internally.
  
−  
−
; WA_Borderless
  
−
: Open a window with no borders rendered by Intuition. Equivalent to NewWindow.Flags WFLG_BORDERLESS.
  
−  
−
: Use caution setting this flag, as it may cause visual confusion on the screen. Also, some borders may be rendered if any of the system gadgets are requested, if text is supplied for the window's title bar, or if any of application gadgets are in the borders.
  
−  
−
; WA_Backdrop
  
−
: Make this window a Backdrop window. Equivalent to NewWindow.Flags WFLG_BACKDROP.
  
−  
−
; WA_GimmeZeroZero
  
−
: Set this tag to create a GimmeZeroZero window. GimmeZeroZero windows have the window border and border gadgets rendered into an extra layer. This extra layer slows down window operations, thus it is recommended that applications only use GimmeZeroZero windows when they are required. For clipping graphics to the area within the borders of a window, see the discussion of "Regions" in [[Layers_Library|Layers Library]]. Equivalent to NewWindow.Flags WFLG_GIMMEZEROZERO.
  
−  
−
; WA_Activate
  
−
: Activate the window when it opens. Equivalent to NewWindow.Flags WFLG_ACTIVATE. Use this flag carefully, as it can change where the user's input is going.
  
−  
−
; WA_RMBTrap
  
−
: Catch right mouse button events for application use. Set this flag to disable menu operations for the window. When set, right mouse button events will be received as IDCMP_MOUSEBUTTONS with the MENUUP and MENUDOWN qualifiers. Equivalent to NewWindow.Flags WFLG_RMBTRAP.
  
−  
−
: The WFLG_RMBTRAP flag in the Window structure Flags field may be modified on the fly by the program. Changing this flag must be done as an atomic operation, as Intuition can preempt a multistep set or clear operation. An atomic operation can be done in assembler, using 68000 instructions that operate directly on memory. If you are unsure of generating such an instruction, place the operation within a Forbid()/Permit() pair. This will ensure proper operation by disabling multitasking while the flag is being changed.
  
−  
−
; WA_SimpleRefresh
  
−
: The application program takes complete responsibility for updating the window. Only specify if TRUE. Equivalent to NewWindow.Flags WFLG_SIMPLE_REFRESH.
  
−  
−
; WA_SmartRefresh
  
−
: Intuition handles all window updating, except for parts of the window revealed when the window is sized larger. Only specify if TRUE. Equivalent to NewWindow.Flags WFLG_SMART_REFRESH.
  
−  
−
: WA_SmartRefresh windows without a sizing gadget will never receive refresh events due to the user sizing the window. However, if the application sizes the window through a call like ChangeWindowBox(), ZipWindow() or SizeWindow(), a refresh event may be generated. Use WA_NoCareRefresh to disable refresh events.
  
−  
−
; WA_SuperBitMap
  
−
: This is a pointer to a BitMap structure for a SuperBitMap window. The application will be allocating and maintaining its own bitmap. Equivalent to NewWindow.BitMap. Setting this tag implies the WFLG_SUPER_BITMAP property.
  
−  
−
: For complete information about SuperBitMap, see "Setting Up a SuperBitMap Window".
  
−  
−
; WA_AutoAdjust
  
−
: Allow Intuition to change the window's position and dimensions in order to fit it on screen. The window's position is adjusted first, then the size. This property may be especially important when using WA_InnerWidth and WA_InnerHeight as border size depends on a user specified font.
  
−  
−
; WA_MenuHelp
  
−
: Enables IDCMP_MENUHELP: pressing Help during menus will return IDCMP_MENUHELP message. See the [[Intuition_Menus|Intuition Menus]] for more information.
  
−  
−
; WA_Flags
  
−
: Multiple initialization of window flags, equivalent to NewWindow.Flags. Use the WFLG_ constants to initialize this field, multiple bits may be set by '''OR'''ing the values together.
  
−  
−
; WA_BackFill
  
−
: Allows you to specify a backfill hook for your window's layer. See the description of CreateUpFrontHookLayer() in [[Layers_Library|Layers Library]].
  
−  
−
== Other Window Functions ==
  
−  
−
This section contains a brief overview of other Intuition functions that affect windows. For a complete description of all Intuition functions, see the SDK.
  
−  
−
=== Menus and the Active Window ===
  
−  
−
Menus for the active window will be displayed when the user presses the menu button on the mouse. Menus may be disabled for the window by not providing a menu strip, or by clearing the menus with ClearMenuStrip(). Similarly, if the active window has WFLG_RMBTRAP set, the menu button will not bring up the menus.
  
−  
−
Two other functions, SetMenuStrip() and ResetMenuStrip(), are used to attach or update the menu strip for a window.
  
−  
−
<pre>
  
−
VOID ClearMenuStrip( struct Window *window );
  
−
BOOL SetMenuStrip( struct Window *window, struct Menu *menu );
  
−
BOOL ResetMenuStrip( struct Window *window, struct Menu *menu );
  
−
</pre>
  
−  
−
If SetMenuStrip() has been called for a window, ClearMenuStrip() must be called before closing the window. After ClearMenuStrip() has been called, the user can no longer access menus for this window. See [[Intuition_Menus|Intuition Menus]], for complete information about setting up menus.
  
−  
−
=== Requesters in the Window ===
  
−  
−
Requesters are temporary sub-windows, usually containing several gadgets, used to confirm actions, access files, or adjust the options of a command the user has just given. Request() creates and activates a requester in the window. EndRequest() removes the requester from the window.
  
−  
−
<syntaxhighlight>
  
−
BOOL Request( struct Requester *requester, struct Window *window );
  
−
VOID EndRequest( struct Requester *requester, struct Window *window );
  
−
</syntaxhighlight>
  
−  
−
For simple requesters in a format that matches system requesters, two new functions have been added to Release 2:
  
−  
−
<syntaxhighlight>
  
−
LONG EasyRequestArgs( struct Window *window, struct EasyStruct *easyStruct,
  
−
ULONG *idcmpPtr, APTR args );
  
−
LONG EasyRequest( struct Window *window, struct EasyStruct *easyStruct,
  
−
ULONG *idcmpPtr, APTR arg1, ... );
  
−
</syntaxhighlight>
  
−  
−
The EasyRequest() functions support requesters with one or more gadgets automatically providing a layout that is sensitive to the current font and screen resolution. See [[Intuition_Requesters|Intuition Requesters]] for more information on using requester functions.
  
−  
−
=== Program Control of Window Arrangement ===
  
−  
−
MoveWindow(), SizeWindow(), WindowToFront() and WindowToBack() allow the program to modify the size and placement of its windows. These calls are available in all versions of the operating system.
  
−  
−
MoveWindowInFrontOf(), ChangeWindowBox() and ZipWindow() provide more flexible control over the size and placement of windows.
  
−  
−
All of these functions are asynchronous. The window will not be affected by them immediately, rather, Intuition will act on the request the next time it receives an input event. Currently this happens at a minimum rate of ten times per second, and a maximum of sixty times per second. There is no guarantee that the operation has taken place when the function returns. In some cases, there are IDCMP messages which will inform the application when the change has completed (for example, an IDCMP_NEWSIZE event indicates that a resize operation has completed).
  
−  
−
Use the MoveWindow() function to move a window to a new position in the screen. Use SizeWindow() to change the size of the window:
  
−  
−
<syntaxhighlight>
  
−
VOID MoveWindow( struct Window *window, LONG dx, LONG dy );
  
−
VOID SizeWindow( struct Window *window, LONG dx, LONG dy );
  
−
</syntaxhighlight>
  
−  
−
Note that both MoveWindow() and SizeWIndow() take the amount of change in each axis (delta values instead of absolute coordinates). To specify the coordinates as absolute numbers, use ChangeWindowBox(). The SizeWindow() function will respect the window's maximum and minimum dimensions only if the window has a sizing gadget.
  
−  
−
ChangeWindowBox() allows an application to change the window size and position in a single call:
  
−  
−
<syntaxhighlight>
  
−
VOID ChangeWindowBox( struct Window *window, LONG left, LONG top, LONG width, LONG height );
  
−
</syntaxhighlight>
  
−  
−
Note that the position and size values are absolutes and not deltas. The window's maximum and minimum dimensions are always respected.
  
−  
−
To depth arrange windows under program control, use WindowToFront() and WindowToBack():
  
−  
−
<syntaxhighlight>
  
−
VOID WindowToFront( struct Window *window );
  
−
VOID WindowToBack( struct Window *window );
  
−
</syntaxhighlight>
  
−  
−
WindowToFront() depth arranges a given window in front of all other windows on its screen. WindowToBack() depth arranges a given window behind all other windows on its screen.
  
−  
−
To move a window in front of a specific, given window (as opposed to all windows), use MoveWindowInFrontOf():
  
−  
−
<syntaxhighlight>
  
−
VOID MoveWindowInFrontOf( struct Window *window, struct Window *behindWindow );
  
−
</syntaxhighlight>
  
−  
−
To toggle the window size between its two zoom settings use ZipWindow(). This performs the same action that occurs when the user selects the zoom gadget:
  
−  
−
<syntaxhighlight>
  
−
VOID ZipWindow( struct Window *window );
  
−
</syntaxhighlight>
  
−  
−
The two zoom settings are the initial size and position of the window when it was first opened and the alternate position specified with the WA_Zoom tag. If no WA_Zoom tag is provided, the alternate position is taken from the window's minimum dimensions, unless the window was opened at its minimum dimension. In that case, the alternate position is taken from the window's maximum dimension.
  
−  
−
=== Changing the Window or Screen Title ===
  
−  
−
Each window has its own window title and local screen title. The window title, if specified, is always displayed in the window. The local screen title, if specified, is only displayed in the screen's title bar when the window is active. If the window does not specify a local screen title, then the default screen title is used in the screen title bar when this window is active.
  
−  
−
<pre>
  
−
VOID SetWindowTitles( struct Window *window, STRPTR windowTitle,
  
−
STRPTR screenTitle );
  
−
</pre>
  
−  
−
This function changes the window title or local screen title for the given window. Both windowTitle and screenTitle can be set to -1, NULL or a NULL terminated string. Specifying -1 will not change the title from the current value. Specifying NULL will clear the window title or reset the screen title to the default title for the screen.
  
−  
−
=== Changing Message Queue Limits ===
  
−  
−
Windows have limits on the number of mouse movement and repeat key messages that may be waiting at their IDCMP at any time. These queue limits prevent the accumulation of these messages, which may arrive at the IDCMP message port in large numbers.
  
−  
−
Once a queue limit is reached, further messages of that type will be discarded by Intuition. The application will never hear about the discarded messages; they are gone forever. (Note that only mouse move and key repeat messages are limited this way. Other types of messages will still be added to the port.) Messages of the limited type will arrive at the port again after the application has replied to one of the messages in the queue.
  
−  
−
The queue limits are independent of each other. Having reached the limit for one type of message does not prevent other types of messages (that have not yet reached their queuing limits) from being added to the IDCMP. Note that the queues apply only to the IDCMP and not to messages received directly via an input handler or from the console device.
  
−  
−
Order of event arrival is not a factor in the message count. Messages may be sequential or interspersed with other events-only the number of messages of the specific type waiting at the IDCMP matters.
  
−  
−
The WA_RptQueue tag allows setting an initial value for the repeat key backlog limit for the window. There is no function to change this value. The default value for WA_RptQueue is 3.
  
−  
−
The WA_MouseQueue tag allows setting an initial value for the mouse message backlog limit for the window. The default value for WA_MouseQueue is 5. The number may later be changed with a call to SetMouseQueue():
  
−  
−
<pre>
  
−
LONG SetMouseQueue( struct Window *window, ULONG queueLength );
  
−
</pre>
  
−  
−
Note that real information may be lost if the queue fills and Intuition is forced to discard messages. See [[Intuition_Mouse|Intuition Mouse]] for more information.
  
−  
−
=== Changing Pointer Position Reports ===
  
−  
−
Pointer position messages to a window may be turned on and off by simply setting or clearing the WFLG_REPORTMOUSE flag bit in Window-&gt;Flags, in an atomic way, as explained for the WA_RMBTrap tag in the "Window Attributes" section above. Using this direct method of setting the flag avoids the historic confusion on the ordering of the arguments of the ReportMouse() function call.
  
−  
−
Mouse reporting may be turned on even if mouse movements were not activated when the window was opened. The proper IDCMP flags must be set for the window to receive the messages. See [[Intuition_Mouse|Intuition Mouse]] for more details on enabling mouse reporting in an application.
  
−  
−
=== Custom Pointers ===
  
−  
−
The active window also has control over the pointer. If the active window changes the image for the pointer using the functions SetPointer() or ClearPointer(), the pointer image will change:
  
−  
−
<syntaxhighlight>
  
−
VOID SetPointer( struct Window *window, UWORD *pointer, LONG height,
  
−
LONG width, LONG xOffset, LONG yOffset );
  
−  
−
VOID ClearPointer( struct Window *window );
  
−
</syntaxhighlight>
  
−  
−
SetPointer() sets up the window with a sprite definition for a custom pointer. If the window is active, the change takes place immediately. The pointer will not change if an inactive window calls SetPointer(). In this way, each window may have its own custom pointer that is displayed only when the window is active.
  
−  
−
ClearPointer() clears the custom pointer from the window and restores it to the default Intuition pointer, which is set by the user. Setting a pointer for a window is discussed further in [[Intuition_Pointer|Intuition Pointer]].
  
   
 
== Function Reference ==
  
== Function Reference ==

Latest revision as of 21:41, 3 November 2015

Intuition Windows

This article provides a general description of windows: how to open windows and define their characteristics; how to get the system gadgets for shaping, moving, closing, and depth arranging windows; how to handle window I/O; and how to preserve the display when windows get overlapped.

About Windows

Windows are rectangular display areas that open on screens. The window acts as a virtual terminal allowing a program to interact with the user as if it had the entire display all to itself.

Each window opens on a specific screen and takes certain characteristics, such as resolution, colors and display attributes, from that screen. These values cannot be adjusted on a window by window basis. Other window characteristics such as the text font are inherited from the screen but can be changed.

An application may open several windows at the same time on a single screen. The Workbench and other public (shareable) screens allow windows opened by different applications to coexist on the same screen.

Windows are moveable and can be positioned anywhere within the screen on which they exist. Windows may also have a title and borders containing various gadgets for controlling the window.

Window System Gadgets

Each window may have a number of system gadgets which allow the user to control window size, shape and arrangement. These gadgets are: the drag bar, the depth gadget, the sizing gadget, the zoom gadget and the close gadget.

The drag bar allows the user to change the position of the window with respect to the screen. The drag bar is in the top border of a window and occupies any space in the top border that is not used by other gadgets. The window may be dragged left, right, up and down on the screen, with the limitation that the entire window must remain within the screen's boundaries. This is done by positioning the pointer over the title bar, selecting the window and dragging to the new position. Window drag may be cancelled by pressing the right mouse button before the drag is completed.

A Window with System Gadgets

The depth gadget allows the user to depth arrange a window with respect to other windows on the screen. The depth gadget is always positioned in the upper right corner of the window. Clicking the depth gadget will move the front-most window behind all other windows. If the window is not the front-most, it will be moved to the front. Selecting the depth gadget with the Shift qualifier always moves the window to the back (behind other windows).

The sizing gadget allows the user to change the size of the window. Sizing is subject to minimum and maximum values set by the application. Width and height are independent in a sizing operation. The sizing gadget is always positioned in the lower right corner of the window. It allows the user to drag this corner of the window to a new position relative to the upper left corner of the window, thus changing the width and height of the window. Window sizing using the sizing gadget may be cancelled by pressing the right mouse button before the size is completed.

The zoom gadget allows the user to quickly alternate between two preset window size and position values. The zoom gadget is always placed immediately to the left of the depth gadget. If there is no depth gadget on the window, the zoom gadget will still appear next to where the depth gadget would have been.

The close gadget performs no direct action on the window, rather it causes Intuition to send a message to the application to close the window. This allows the application to perform any required processing or to warn the user before it closes the window. The close gadget is always positioned in the upper left corner of the window.

The Active Window

There is only one window in the system active at any time. The active window receives all user input, including keyboard and mouse events. This is also known as the input focus, as all input is focused at this single point.

Some areas of the active window are displayed more boldly than those on inactive windows. The active window's borders are filled in with a color which is designed to stand out from the background while inactive windows have their borders filled with the background color. The specific coloring of active and inactive windows is dependent on the screen on which the window is opened. See the section DrawInfo and the 3D Look for more information.

Windows have two optional titles: one for the window and one for the screen. The window title appears in the top border of the window, regardless of whether the window is active or inactive. The window's screen title appears in the screen's title bar only when the window is active. This gives the user a secondary clue as to what application is active in the screen.

The active window's menus are displayed on the screen when the right mouse button (the menu button ) is pressed. If the active window has no menus, then none will be displayed.

Each window may also have its own mouse-pointer image. Changing the active window will change the pointer to the one currently set for the new active window.

More Details

The following sections describe Windows in more detail:

Function Reference

The following are brief descriptions of the Intuition functions that relate to the use of Intuition windows. See the SDK for details on each function call.

Functions for Intuition Windows
Function Description
OpenWindowTagList() Open a window.
OpenWindowTags() Alternate calling sequence for OpenWindowTagList().
OpenWindow() Obsolete way to open a window.
CloseWindow() Close a window.
BeginRefresh() Turn on optimized window refresh mode.
EndRefresh() Turn off optimized window refresh mode.
RefreshWindowFrame() Redraw the borders and border gadgets of an open window.
ActivateWindow() Make an open window active.
SizeWindow() Change the size of an open window.
MoveWindow() Change the position of an open window.
ChangeWindowBox() Change the size and position of an open window.
WindowLimits() Change the minimum and maximum sizes of an open window.
WindowToBack() Move a window behind all other windows.
WindowToFront() Move a window in front of all other windows.
MoveWindowInFrontOf() Move a window in front of another window.
ZipWindow() Change the size of window to its alternate size.
SetWindowTitles() Change the window titles for the window and the screen.
SetPointer() Set up a custom pointer to display whenever the window is active.
ClearPointer() Restore the mouse pointer to its default imagery.
Retrieved from "http://wiki.amigaos.net/w/index.php?title=Intuition_Windows&oldid=8268"