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-File
                                GEM  Windows



A window is a viewport through which all or part of an application's
document may be viewed. Windows are modeless forms of input. This means
that they do not restrict the user from switching to another window or
executing a command.

Normal document windows should have a title bar and should be moveable
(these characteristics are set with the wind_create() function - see
Chapter 6: AES ). The following illustration shows a window with all
window components identified:



Here are some other basic rules to use when creating windows:

   ∙ Windows should almost always have the MOVE characteristic set.

   ∙ If it is possible that the contents of the information displayed in
     the window might overflow, provide sliders (horizontal and/or vertical)
     as appropriate. The sliders should be updated as necessary to ensure
     that they are proportional in size and position to the amount of
     information viewable in the window versus the size of the entire
     document.

   ∙ Generally, all document windows will include all window elements
     (with the possible exception of the information line). Only exclude
     an element if its use would be inappropriate in the current context.

Window Messages

An application's use of windows depends on either the evnt_mesag() or
evnt_multi() functions of the AES. These functions return messages which in
turn must be responded to by the application for any changes to occur. The
following list illustrates all messages that a window may receive along
with an appropriate action(s) that should be taken.

Message       Action

WM_REDRAW     Redraw the rectangular portion of the window which was
              dirtied (as specified in the message). Always use
              wind_get() with WF_FIRSTXYWH and WF_NEXTXYWH to walk the
              rectangle list and enable clipping to the appropriate
              regions. If the window had a SMALLER gadget, check prior
              to drawing whether you are drawing the actual window
              contents or an iconified representation. If the window has
              an attached toolbar that requires special redrawing, use
              wind_get() with WF_FTOOLBAR and WF_NTOOLBAR as parameters
              to walk the rectangle list and enable clipping to the
              returned regions. In some situations you may want to
              redraw the entire window upon each WM_REDRAW call. You
              must still walk the rectangle list as specified above.

WM_TOPPED     Call wind_set() with a parameter of WF_TOP to actually
              top the window. Do not redraw the window. Your
              application will receive WM_REDRAW messages for portions
              of the window uncovered by the call. Also, set the mouse
              form as desired.

WM_SIZED      Call wind_set() with a parameter of WF_CURRXYWH to
              actually change the current size of the window. Update
              slider positions as necessary to reflect the new size of
              the window. Applications will automatically receive
              a redraw message if any portion of the window was
              uncovered. If you need to redraw the entire window each
              time the window size changes, send your own application
              a WM_REDRAW message with appl_write() to cause a redraw.

WM_MOVED      Call wind_set() with a parameter of WF_CURRXYWH to
              actually change the current size of the window. This
              message and the message WM_SIZED are usually handled by
              common code.

WM_ARROWED    Scroll the contents of the document window as necessary
              and redraw the window (using the rectangle list). When an
              arrow indicator is clicked, scroll the window by one
              'line' (a small increment in a non-text oriented
              application). When the exposed area of the slider bar is
              clicked, scroll the contents of the document window by
              one 'page' (current viewable portion of the document)
              minus one 'line'.

WM_VSLID      Scroll the contents of the document window in proportion
              with the new position of the slider elevator.

WM_HSLID      Scroll the contents of the document window in proportion
              with the new position of the slider elevator.

WM_FULLED     Restore the size of the window using wind_get() with
              a parameter of WF_PREVXYWH. Update slider bars as
              necessary.

WM_CLOSED     Close the window. If the window context required
              a positive or negative answer from the user ('Yes/No' or
              'OK/Cancel'), assume positive. If the window contains
              a document which has been altered since the last time it
              was saved to disk, it is appropriate to ask the user if
              the document should be saved before proceeding.

WM_BOTTOMED   Call wind_set() with a parameter of WF_BOTTOM to send the
              window to the bottom of the window stack.

WM_ICONIFY    See below.

WM_UNICONIFY  See below.

WM_ALLICONIFY See below.

WM_TOOLBAR    Respond as necessary to the toolbar event.

WM_ONTOP      Set the mouse form appropriately for your application.

WM_UNTOPPED   No action is mandated by this message.

Clipping Rectangles

In every instance where text or graphics are rendered in a window, you
should walk the rectangle list in order to ensure that the screen is
properly updated. This includes all instances when the contents of the
window are updated as a response to a user command (as opposed to
a WM_REDRAW message) or dynamic interaction (i.e. selection or
animation).

Window Titles

The title bar of a window should accurately reflect its basic contents.
If a window contains a document the title bar should contain the filename
of the document or 'Untitled' if it is a new document that has not been
saved yet. If the window does not contain a document, the title bar should
serve to clearly explain the purpose of the menu. For example, if you were
to implement a find and replace dialog in a window window, the window
should be titled "Find & Replace."

In some cases you may wish to provide an option (though a menu or
keystroke) which allows the user to open a duplicate copy of the document
in another window. This allows the user to select separate views in each
open window yet changes in one window are reflected in others.  In this
case, suffix the document name with a colon and the window number such as
"FILENAME.DOC:1". The numbering should only be present when more than one
document window actually exists.

Iconified Windows

AES versions 4.1 and above support the SMALLER gadget for window
iconification. The basic rules for iconification follow:

Action             ∙Is A 'program group iconified window already open?
          Response

User wishes to     No         Iconify the single window.
iconify a single
window.

User wishes to     Yes        Close the window the user wishes to iconify
iconify a single              and add it to those represented by the 'program
window.                       group' window.

User wishes to     No         Create a new, iconified window as a 'program
iconify all                   group' and close all other windows
windows.

User wishes to     Yes        Add all open windows to those represented by the
iconify all                   'program group' window and close all other
windows.                      windows.

User wishes to     N/A        Uniconify the window.
uniconify
a single
window.

User wishes to     Yes        Close the iconified window and open all of the
uniconify                     windows in the 'program group'.
a 'program
group' window.

Here are some other hints that are helpful when dealing with
iconification:

   ∙ Due to the smaller size of the window title line, it may be
     desirable to adjust the title text when a window is iconified.

   ∙ Draw an icon which represents the contents of the window when drawing
     a single iconified window. When drawing a 'program group' iconified
     window, draw an icon which represents the application.

   ∙ Use graf_growbox() and graf_shrinkbox() to graphically show the user
     the iconification/uniconification process.

Window Information Line

When appropriate, the addition of the INFO component of a window
should serve to provide additional information about the objects
visible in the window. This information should change to provide the
most useful information. A vector graphics editor might display the
document size, statistics, and zoom factor normally, but provide
information on the number and extent of selected objects when at least
one object is selected.

Window Colors

AES versions 3.0 and above allow the color of each window component to
be modified. An application should never modify the global settings.
Allow the user to use the Window Colors CPX to choose global colors of
his/her choice.

If your application wants to draw a visual distinction between windows
by displaying them in different colors, provide a dialog where the user
may choose color preferences or (at least) enable/disable this option.