Topic : The ATARI Compendium
Author : Scott Sanders / JAY Software
Version : 1.25 (20/6/2003)
Subject : Documentation
Nodes : 1117
Index Size : 32614
HCP-Version : 6
Compiled on : Atari
@charset : UTF-8
@lang : en
@default :
@help : %About
@options : +g -i -t4 +y +z
@width : 100
View Ref-FileWindowsGEMapplications usually maintain most user-interaction in windows.
Windows are workspaces created with wind_create() with any of several
predefined gadgets (controls) illustrated in the diagram and table below:
Name Mask Meaning
NAME 0x0001 Using this mask will cause the AES to display the window
with a title bar containing a name that the application
should set with wind_set( WF_NAME, ... ).
CLOSER 0x0002 This mask will attach a closer box to the window which,
when pressed, will send a WM_CLOSED message to the
application.
FULLER 0x0004 This mask displays a fuller box with the window which,
when pressed, will cause a WM_FULLED message to be sent
to the application.
MOVER 0x0008 This mask allows the user to move the window by clicking
and dragging on the window's title bar. This action will
generate a WM_MOVED message.
INFO 0x0010 This mask creates an information line just below the
title bar which can contain any user-defined information
as set with wind_set( WF_INFO, ...).
SIZER 0x0020 This mask attaches a sizer object to the window which,
when clicked and dragged to a new location, will generate
a WM_SIZED message.
UPARROW 0x0040 This mask attaches an up arrow object to the window
which, when pressed, will generate a WM_ARROWED message
to the application.
DNARROW 0x0080 This mask attaches a down arrow object to the window
which, when pressed, will generate a WM_ARROWED message
to the application.
VSLIDE 0x0100 This mask attaches a vertical slider object to the window
which, when clicked and dragged, will generate a WM_VSLID message. Clicking on the exposed area of the slider will
also generate this message.
LFARROW 0x0200 This mask attaches a left arrow object to the window
which, when pressed, will generate a WM_ARROWED message
to the application.
RTARROW 0x0400 This mask attaches a right arrow object to the window
which, when pressed, will generate a WM_ARROWED message
to the application.
HSLIDE 0x0800 This mask attaches a horizontal slider object to the
window which, when clicked and dragged, will generate
a WM_HSLID message. Clicking on the exposed area of the
slider will also generate this message.
SMALLER 0x4000 This mask attaches a smaller object which, when clicked,
will generate a WM_ICONIFY message. If the object is
ctrl-clicked, a WM_ALLICONIFY message will be
generated. This object is only valid in AES v4.1 and
higher.
wind_create() returns a window handle which should be stored as it must
be referenced on any further calls that open, alter, close, or delete the
window. wind_create() may fail if too many windows are already open.
Different versions of the AES impose different limits on the number of
concurrently open windows.
Calling wind_create() does not automatically display the window.
wind_open() displays a window named by its window handle. Any calls needed
to initialize the window (such as setting the window title, etc.) should
be made between the wind_create() and wind_open() calls.
wind_set() and wind_get() can be used to set and retrieve many various
window attributes. Look for their documentation in the function reference
for further details.
wind_close() may be used to remove a window from the screen. The window
itself and its attributes are not deleted as a result of this call,
however. A subsequent call to wind_open() will restore a window to the
state it was in prior to the wind_close() call. The wind_delete() function
is used to physically delete a window and free any memory it was using.
Two other utility functions for use in dealing with windows are provided
by the AES. wind_calc() will return the border rectangle of a window given
the desired work area or the work area of a window given the desired
border area. The call takes into account the sizes of the various window
gadgets.
wind_find() returns the handle of the window currently under the mouse.
The Desktop WindowThe desktop window encompasses the entire screen. It has a constant
window handle of DESK (0) so information about it can be inquired with
wind_get(). Calling wind_get() with a parameter of WF_CURRXYWH will return
the size of the screen. Calling wind_get() with a parameter of
WF_WORKXYWH will return the size of the screen minus the size of the menu
bar.
The desktop draws a custom OBJECT tree in its work area. This tree
results in the fill pattern and color seen on screen. An application may
create its own custom desktop object tree by using wind_set() with
a parameter of WF_DESKTOP. The OBJECT tree specified should be the exact
size of the desktop work area.
MultiTOS will switch between these object trees as applications are
switched. The desktop's object tree will be visible whenever an
application doesn't specify one of its own.
The Rectangle ListWhenever a window receives a redraw message or needs to update its window
because of its reasons, it should always constrain output to its current
rectangle list. The AES will calculate the size and position of a group of
rectangles that compromise the area of your window not covered by other
overlapping windows.
wind_get() with parameters of WF_FIRSTXYWH and WF_NEXTXYWH is used to
return the current rectangle list. Redrawing inside a window should also
only be attempted when the window semaphore is locked with wind_update(
BEG_UPDATE ). This prevents the rectangle list from changing during the
redraw and prevents the user from dropping down menus which might be
overwritten. The following code sample illustrates a routine that
correctly steps through the rectangle list:
.
.
. Application Event Loop
.
case WM_REDRAW:
RedrawWindow( msg[3], (GRECT *)&msg[4] );
break;
.
.
VOID
RedrawWindow( WORD winhandle, GRECT *dirty )
{
GRECT rect;
wind_update( BEG_UPDATE );
wind_get( winhandle, WF_FIRSTXYWH, &rect.g_x, &rect.g_y, &rect.g_w, &rect.g_h);
while( rect.g_w && rect.g_h )
{
if( rc_intersect( dirty, &rect ) )
{
/*
* Do your drawing here...constrained to the rectangle in g.
*/
}
wind_get( winhandle, WF_NEXTXYWH, &rect.g_x, &rect.g_y, &rect.g_w, &rect.g_h);
}
wind_update( END_UPDATE );
}
Window ToolbarsAESversions 4.1 and later support window toolbar attachments. Toolbarsare OBJECT trees containing a number of TOUCHEXITobjects. They are
attached to a window using wind_set() with a parameter of WF_TOOLBAR. The
following diagram shows a window with a toolbar:
Window toolbars are automatically redrawn whenever necessary and their
ROOT objects are automatically repositioned and resized with the window.
If any special redrawing is necessary (ex: changing the visual state of an
object after a click), the application may obtain a special toolbar
rectangle list by using wind_get() with parameters of WF_FTOOLBAR and
WF_NTOOLBAR.
If toolbar objects must be modified on WM_SIZED events, simply modify
them prior to calling wind_set( handle, WM_CURRXYWH, ... ).
A special note about windows with toolbars concerns the usage of
wind_calc(). wind_calc() doesn't understand the concept of toolbars. The
information it returns must be modified by adjusting the height of its
output rectangles according to the current height of the toolbar object
tree.