This is an old version from the tos.hyp. The new is on GitHub!

8.9 Window library

This library makes functions available to create, open and close windows, and much more. In all the following routines are available:

Note: Under MagiC a single application should not use more than 16 windows, as otherwise the message buffer of the system may overflow and then it may not be possible to perform redraws any more.

See also:
Components of a window   Style guidelines   Window-dialogs   Overview of the wind_get/set subfunctions   wind_get and wind_set mode in Geneva

8.9.1 sys_set_winframe_manager

8.9.1.1 Bindings for sys_set_winframe_manager

int16_t sys_set_winframe_manager( WINFRAME_HANDLER *old_wfh,
            WINFRAME_HANDLER *new_wfh,
            WINFRAME_SETTINGS **set )
{
   int_in[0]  = 6;      /* Subcode 6: Window-frame manager */
   addr_in[0] = old_wfh;
   addr_in[1] = new_wfh;

   crys_if(0);

   *set = addr_out[0];

   return ( int_out[0] );
}

8.9.2 wind_calc

8.9.2.1 Bindings for wind_calc

int16_t wind_calc (int16_t wi_ctype, int16_t wi_ckind,
                   int16_t wi_cinx, int16_t wi_ciny,
                   int16_t wi_cinw, int16_t wi_cinh,
                   int16_t *coutx, int16_t *couty,
                   int16_t *coutw, int16_t *couth)
{
   int_in[0]  = wi_ctype;
   int_in[1]  = wi_ckind;
   int_in[2]  = wi_cinx;
   int_in[3]  = wi_ciny;
   int_in[4]  = wi_cinw;
   int_in[5]  = wi_cinh;

   crys_if (108);

   *coutx = int_out[1];
   *couty = int_out[2];
   *coutw = int_out[3];
   *couth = int_out[4];

   return ( int_out[0] );
}

8.9.3 wind_close

8.9.3.1 Bindings for wind_close

int16_t wind_close (int16_t wi_clhandle)
{
   int_in[0]  = wi_clhandle;
   return ( crys_if(102) );
}

8.9.4 wind_create

8.9.4.1 Bindings for wind_create

int16_t wind_create (int16_t wi_crkind, int16_t wi_crwx,
                     int16_t wi_crwy, int16_t wi_crww,
                     int16_t wi_crwh)
{
   int_in[0]  = wi_crkind;
   int_in[1]  = wi_crwx;
   int_in[2]  = wi_crwy;
   int_in[3]  = wi_crww;
   int_in[4]  = wi_crwh;

   return ( crys_if(100) );
}

8.9.5 wind_delete

8.9.5.1 Bindings for wind_delete

int16_t wind_delete (int16_t wi_dhandle)
{
   int_in[0] = wi_dhandle;
   return ( crys_if(103) );
}

8.9.6 wind_draw

8.9.6.1 Bindings for wind_draw

int16_t wind_draw ( int16_t wi_dhandle, int16_t wi_dstartob );
{
   int_in[0] = wi_dhandle;
   int_in[1] = wi_dstartob;
   return ( crys_if(99) );
}

8.9.7 wind_find

8.9.7.1 Bindings for wind_find

int16_t wind_find (int16_t wi_fmx, int16_t wi_fmy)
{
   int_in[0]  = wi_fmx;
   int_in[1]  = wi_fmy;

   return ( crys_if(106) );
}

8.9.8 wind_get

8.9.8.1 Bindings for wind_get

int16_t wind_get ( int16_t wi_ghandle, int16_t wi_gfield,
                   int16_t *wi_gw1, int16_t *wi_gw2,
                   int16_t *wi_gw3, int16_t *wi_gw3)
{
   int_in[0]  = wi_ghandle;
   int_in[1]  = wi_gfield;

   crys_if (104);

   *wi_gw1 = int_out[1];
   *wi_gw2 = int_out[2];
   *wi_gw3 = int_out[3];
   *wi_gw4 = int_out[4];

   return ( int_out[0] );
}

8.9.9 wind_new

8.9.9.1 Bindings for wind_new

void wind_new (void)
{
   crys_if (109);
}

8.9.10 wind_open

8.9.10.1 Bindings for wind_open

int16_t wind_open (int16_t wi_ohandle, int16_t wi_owx,
                   int16_t wi_owy, int16_t wi_oww,
                   int16_t wi_owh)
{
   int_in[0]  = wi_ohandle;
   int_in[1]  = wi_owx;
   int_in[2]  = wi_owy;
   int_in[3]  = wi_oww;
   int_in[4]  = wi_owh;

   return ( crys_if(101) );
}

8.9.11 wind_set

8.9.11.1 wind_set and PC-GEM

As of PC-GEM Version 2.0 the following apply:

WF_ATTRB (18): This sets the window attribute vector. Here: wi_sw1 = 0 (or 1): Window is the top window, or not; apart from this there is no further information available.

WF_SIZETOP (19): This makes the window an active one, without changing the order of the other windows. At the same time the position and size of the window can be reset:

8.9.11.2 Bindings for wind_set

int16_t wind_set ( int16_t wi_shandle, int16_t wi_sfield,
                   int16_t wi_sw1, int16_t wi_sw2,
                   int16_t wi_sw3, int16_t wi_sw4 )
{
   int_in[0]  = wi_shandle;
   int_in[1]  = wi_sfield;
   int_in[2]  = wi_sw1;
   int_in[3]  = wi_sw2;
   int_in[4]  = wi_sw3;
   int_in[5]  = wi_sw4;

   return ( crys_if(105) );
}

8.9.11.3 WF_TOPMOST, wind_set

A class of windows that will always 'float' ontop of classical windows. One key feature of windows in any WF_TOPMOST state is that they do not disturb current keyboard focus, and can be used to issue important messages, status raports, etc., without demanding user interaction.

wind_set (wi_shandle, WF_TOPMOST, wi_sw1,...)

WF_TOPMOST (232)

Some common characteristics of windows with any WF_TOPMOST state set;

1. Changing the WF_TOPMOST state can be done on open windows, but it is prefer not if possible.
2. Windows which have TOPMOST state 1 or 2 never get keyboard focus.
3. Windows which have TOPMOST state 1 or 2 never get WM_TOPPED or WM_UNTOPPED AES messages.

State 1:
Setting state 1 will make the corresponding window 'float' ontop of all other classical windows. State 1 windows will stay ontop until closed by the user or the application itself.

State 2:
Setting state 1 will make the corresponding window act like windows with state 1 set, with one important exception; The window is linked to the window owner's focus status. This means that when the application that owns the window looses focus, state 2 windows are automatically made unvisible by the AES. When the application regains focus, the window is automatically made visible again. This is done automatically, and no application handling is necessary.

8.9.12 wind_update

8.9.12.1 Bindings for wind_update

int16_t wind_update (int16_t wi_ubegend)
{
   int_in[0] = wi_ubegend;
   return ( crys_if(107) );
}

8.9.13 wind_xget

8.9.13.1 Bindings for wind_xget

int16_t wind_xget ( int16_t wi_ghandle, int16_t wi_gfield,
                    int16_t *wi_gw1, int16_t *wi_gw2,
                    int16_t *wi_gw3, int16_t *wi_gw3,
                    int16_t *wo_sw1, int16_t *wo_sw2,
                    int16_t *wo_sw3, int16_t *wo_sw4 );
{
   int_in[0]  = wi_ghandle;
   int_in[1]  = wi_gfield;
   int_in[2]  = *wi_sw1;
   int_in[3]  = *wi_sw2;
   int_in[4]  = *wi_sw3;
   int_in[5]  = *wi_sw4;

   crys_if (104);

   *wo_gw1 = int_out[1];
   *wo_gw2 = int_out[2];
   *wo_gw3 = int_out[3];
   *wo_gw4 = int_out[4];

   return ( int_out[0] );
}

8.9.14 wind_xset

8.9.14.1 Bindings for wind_xset

int16_t wind_xset ( int16_t wi_shandle, int16_t wi_sfield,
                    int16_t wi_sw1, int16_t wi_sw2,
                    int16_t wi_sw3, int16_t wi_sw4,
                    int16_t *wo_sw1, int16_t *wo_sw2,
                    int16_t *wo_sw3, int16_t *wo_sw4 );
{
   int_in[0]  = wi_shandle;
   int_in[1]  = wi_sfield;
   int_in[2]  = wi_sw1;
   int_in[3]  = wi_sw2;
   int_in[4]  = wi_sw3;
   int_in[5]  = wi_sw4;

   crys_if(105);

   *wo_sw1 = int_out[1];
   *wo_sw1 = int_out[2];
   *wo_sw1 = int_out[3];
   *wo_sw1 = int_out[4];

   return ( int_out[0] );
}

8.9.15 The components of a window

The following illustration shows the window of a GEM text editor, and describes the most important components of this window.

Note that the clickable 'buttons' use characters from the system font, and may look different if a substitute system font is in use.

When the Closer of an application window is clicked on, the window will close and its contents will be discarded; if it allows user input (text editors, graphics programs, spreadsheets ...), any changes made to the contents since the last 'Save' operation are lost. Most well- behaved applications warn the user with an alert about this and give a final opportunity to save the changed contents.

When the Closer of a desktop window is clicked on in TOS, it will display the next-higher directory level, or, if already showing the root directory, close the window; some alternative desktops such as MAGXDESK, Jinnee and Thing offer the option to either behave in the same way, or can be set for the Closer to shut the window immediately from any directory level - they use a 'parent' widget at the top of the window to move to the next-higher level.

The Title-bar shows the full path to the current directory (in a desktop window) or to the current file (in an application's window). It may also show other details, such as the current cursor position etc. (if the window does not have an info-line).

The Mover allows the whole window to be moved by clicking and holding down the left mouse button while dragging the outline of the window to a new position.

The Backdrop button is only present in MagiC and similar system extensions. If several windows are open, clicking on it places the window at the bottom of the 'stack', permitting rapid cycling through the windows.

The Iconifier button is only present as of AES Version 4.1 and later MagiC versions. When clicked on, the window is shrunk to a large icon at the bottom left of the screen, carrying a suitable identity label. If several windows are iconified, their icons will be ranged next to each other. A double-click on the icon will restore the window to its former position and size.

Clicking on the Fuller enlarges the window to fill the screen. A second click restores the former size.

The Info-line provides various items of information about the window's contents. In applications it is optional and must be provided by the running program. This also applies to the menu-line (may be scrollable if too long to fit the window) and the toolbar.

When one of the four arrows is clicked on, it scrolls the contents in the appropriate direction by one line or column if the contents exceed the current width and/or height of the window. This action repeats if the mouse button is held down.

The width of the sliders indicate what portion of the total contents is being displayed on the screen in comparison with the shaded area in the two elevators representing the off-screen portions. Holding down the left mouse button and dragging the slider allows the window's contents to be scrolled quickly in the relevant direction.

Clicking in the elevator area scrolls the contents by one screen height or width; this too repeats if the button is held down.

Clicking on the Sizer and holding down the left mouse button allows dragging the window to a new size. During this the outline of the window appears dotted as an aid to placement. The top left corner remains in position.

See also: Window library

8.9.16 Overview of the wind_get/set subfunctions

An 'x' shows in which wind_xxx function the subfunction is present. In most cases clicking on the 'x' will bring up further details.

8.9.17 wind_get and wind_set mode in Geneva

In all cases, the wind_get function can be used to retrieve the following information for a particular window. wind_set can be used to set the values.

X_WF_MENU (0x1100)

Setting this attribute causes a menu bar to appear below the window's name and information bars. The wi_sw1 parameter should have the high-WORD of the address of the object tree containing the menu. wi_sw2 contains the low-WORD of the address. If a NULL pointer is passed, the menu bar will be blank.

Example:

      int handle;
      OBJECT *menu;

      handle = wind_create( MOVER|X_MENU, 20, 20, 200, 200 );
      if( handle>0 ) {
         wind_set( handle, X_WF_MENU, menu );
         wind_open( handle, 20, 20, 200, 200 );
      }

X_WF_DIALOG (0x1200)

This option allows a program to create dialog boxes within windows. It is generally used in conjunction with the X_MU_DIALOG event type.

The wi_sw1 parameter should have the high-WORD of the address of the object tree containing the dialog. wi_sw2 contains the low- WORD of the address. If a NULL address is passed, there will be no dialog associated with the window, and it will receive events normally.

If the window does not have horizontal or vertical sliders, then the size of the root object of the dialog will automatically be sized to fit the entire working area of the window. If the window has sliders, then the dialog will automatically scroll and update as the user operates them. No action is necessary on the part of the program.

If the window is open when this call occurs, the entire dialog is always redrawn and the sliders, if present, are updated. All slider updates can be turned off by clearing the X_WTFL_SLIDERS attribute for the window, by way of the x_wind_tree function.

Refer to the section describing shel_write for information on how to cause a windowed dialog to scroll by sending a message to Geneva.

Example:

      int handle;
      OBJECT dial = { -1, -1, -1, G_BOX, 0, 0, 0x021131L, 0, 0, 1000, 1000 };
                              /* a large, filled rectangle */


      handle = wind_create( MOVER|SIZER|CLOSER|UPARROW|DNARROW|\
        VSLIDE|LFARROW|RTARROW|HSLIDE, 20, 20, 200, 200 );

      if( handle>0 ) {
        wind_set( handle, X_WF_DIALOG, d
        wind_set( handle, X_WF_DIALHT, 10 );  /* vert. scroll jump */
        wind_set( handle, X_WF_DIALWID, 10 ); /* horiz. scroll jump */
        wind_open( handle, 20, 20, 200, 200 );
      }

X_WF_DIALWID (0x1300)

This option is used in conjunction with the X_WF_DIALOG option. It controls the interval at which scrolling by the user occurs. For instance, a value of 10 will cause the left and right scroll arrows to scroll the dialog within the window by 10 pixels at a time. The default value is 1.

Since, by default, Geneva will use a blit operation to move most of a windowed dialog's contents when scrolling, unpredictable redraw errors can occur when redrawing the unblitted area of a dialog if the dialog uses a patterned fill and X_WF_DIALWID is not a multiple of 16 pixels.

X_WF_DIALHT (0x1400)

This option is used in conjunction with the X_WF_DIALOG option. It controls the interval at which scrolling by the user occurs. For instance, a value of 10 will cause the up and down scroll arrows to scroll the dialog within the window by 10 pixels at a time. The default value is 1.

Since, by default, Geneva will use a blit operation to move most of a windowed dialog's contents when scrolling, unpredictable redraw errors can occur when redrawing the unblitted area of a dialog if the dialog uses a patterned fill and X_WF_DIALWID is not a multiple of 16 pixels.

X_WF_DFLTDESK (0x1500)

This option allows a program to redefine the default desktop, so that it will be something other than the normal grey pattern. The wi_sw1 parameter should have the high-WORD of the address of the object tree containing the new object tree. wi_sw2 cont address pattern) desktop will become the new default. The wi_sw3 parameter must contain the total number of objects in the object tree which contains the new desktop.

If the application which has changed the default desktop terminates, the default grey pattern is reinstated automatically.

X_WF_MINMAX (0x1600)

This option allows a program to change the minimum and maximum sizes to which the user can resize a particular window.

By default, Geneva calculates a minimum window size that is large enough to contain all of the window widgets without overlapping. The maximum size always defaults to the working area of the entire desktop.

The wi_sw1 and wi_sw2 parameters are the minimum window width and height, respectively, and wi_sw3 and wi_sw4 are the maximum width and height of the window. Passing a value of -1 in any of these parameters in a call to wind_set will cause no change to occur in that one value.

X_WF_HSPLIT (0x1700)

This option reflects the location of the horizontal split bar of a window.

The wi_sw1 parameter is the new location of the bar, in pixels. If the value is zero, the bar will be all the way to the left edge; if it is -1 (which is the default) it will be all the way to the right.

Return value from wind_get:

wi_gw1 =	Split bar position
wi_gw2 =	Size, in pixels, of the upper window region
wi_gw3 =	Size of the lower window region

Note: The value returned by wind_get may not be equal to the value supplied to wind_set if the user has either changed the size of the window, or if the value was too large or not large enough to exceed the minimum bar position. See the function x_wind_create and the X_WF_SPLMIN option, below, for more information.

X_WF_VSPLIT (0x1800)

This option reflects the location of the vertical split bar of a window.

The wi_sw1 parameter is the new location of the bar, in pixels. If the value is zero, the bar will be at the very top; if it is -1 (which is the default) it will be at the very bottom.

Return value from wind_get:

wi_gw1 =	Split bar position
wi_gw2 =	Size, in pixels, of the left window region
wi_gw3 =	Size of the right window region

Note that the value returned to wind_get may not be equal to the value supplied by wind_set if the user has either changed the size of the window, or if the value was too large or not large enough to exceed the minimum bar position. See the function x_wind_create and the X_WF_SPLMIN option, below, for more information.

X_WF_SPLMIN (0x1900)

This option controls the minimum sizes of the areas defined by the horizontal and vertical split bars.

wi_sw1 =	Minimum width of region to left of horizontal split
wi_sw2 =	Minimum width of region to right of horizontal split
wi_sw3 =	Minimum height of region above vertical split
wi_sw4 =	Minimum height of region below vertical split

When the user drags a split bar, these values are checked. He will not be able to drag the bar if the window is too small to fit two regions having these sizes. When a wind_set call is made to set the position of one of the split bars, they will be 'snapped' to one edge or the other if the position is less than 1/2 of the minimum distance away from the edge. Furthermore, when the window is made smaller, the positions of the split bars are automatically changed so as to satisfy these minimum values. For this reason, a program should never assume that they have not changed.

Passing a value of -1 in any of these parameters in a call to wind_set will cause no change to occur in that one value.

X_WF_HSLIDE2 (0x1A00)

This option gets or sets the position of the second horizontal slider (which appears to the right of a horizontal split bar) in a manner identical to WF_HSLIDE.

X_WF_VSLIDE2 (0x1B00)

This option gets or sets the position of the second vertical slider (which appears below a vertical split bar) in a manner identical to WF_VSLIDE.

X_WF_HSLSIZE2 (0x1C00)

This option gets or sets the size of the second horizontal slider (which appears to the right of a horizontal split bar) in a manner identical to WF_HSLSIZE.

X_WF_VSLSIZE2 (0x1D00)

This option gets or sets the size of the second vertical slider (which appears below a vertical split bar) in a manner identical to WF_VSLSIZE.

X_WF_DIALFLGS (0x1E00)

This option gets/sets flags related to the way dialogs within windows are processed. Currently, only the following three bits are used. All other bits are reserved for future use:

X_WD_ACTIVE (bit 0)

When this bit is off, no mouse or keyboard events will be processed. This is a good way to temporarily lock a windowed dialog while presenting the user with a sub-dialog that asks for other input (like the 'Find' option in the Task Manager's 'Flags' dialog.) This attribute defaults to On.

X_WD_BLITSCRL (bit 1)

If this flag is set, which it is by default, a windowed dialog will be scrolled in real time by way of a blit operation. Care should be taken when displaying object trees which use fill patterns, because if the X_WF_DIALWID or X_WF_DIALHT are not an even increment of 16, the fill pattern may not match up correctly when the user scrolls the window. If this flag is off, the entire dialog will be redrawn every time its position changes. In this case, the scroll increment does not matter.

X_WD_KEYS (bit 2) (since Update 004)

When set, any keypresses that would otherwise be processed as part of the dialog are instead passed through to the application.

An example is when NeoDesk is run with the desktop in a window. Normally, things like [Shift]-[C] would be treated like a keypress in a dialog without any editable field and ignored. When this bit is set, the keypress will instead go to the application.

X_WF_OBJHAND (0x1F00) (since Update 003)

When an application wants to intercept some or all of the button events that would otherwise be interpreted by Geneva to mean that a window widget has been clicked on, this wind_set mode can be used to provide Geneva with the address of a routine which instructs Geneva to either ignore the event, or to process it as normal. This allows the programmer to redefine the operation of window widgets, and to define his own actions for new widgets which have been added with the x_wind_tree function.

The routine is passed the handle of the window containing the object and the index of the object within the window's object tree. If the user routine returns a 0, then Geneva will generate an X_WM_OBJECT message and send it to the application. If the routine returns a 1, then Geneva will process the action as a normal event and act accordingly.

IMPORTANT: The application's object handler routine must not use any AES functions.

The following example declares an object handler which allows the action of the vertical scroll bar to be redefined:

       /* change this to "int cdecl objhand..." for Pure C */
int objhand( int handle, int obj )
{  /* handle parameter is not used */
  if( obj==WGVSMLSL ) return 0;   /* this is the vertical slider */
  return 1;                       /* otherwise, process as normal */
}

main()
{
 int handle, message[8];

  handle = wind_create( NAME|MOVER|VSLIDE|UPARROW|DNARROW,
      50, 50, 150, 150 );

  if( handle > 0 )
  {
    wind_set( handle, X_WF_OBJHAND, &objhand );
    wind_open( handle, 50, 50, 150, 150 );
  }

  ...

  evnt_mesag( message );

  switch( message[0] )
  {

    case X_WM_OBJECT:
      if( message[3]==handle && message[4]==WGVSMLSL )
         /* do something new with the slider */
  }
}

If wind_set( X_WF_OBJHAND ) is passed a NULL pointer instead of a pointer to a function, object handling is discontinued for that window.

Note that in order for Geneva to determine that the mouse has been clicked on an object in a window's tree structure, it must be of type EXIT or TOUCHEXIT. Geneva's default window widgets already have these attributes set correctly.

wind_get can also be used to get a pointer to the current object handler routine. A NULL pointer means that there is no object handler defined.

X_WF_DIALEDIT (0x2000) (since Update 003)

When a windowed dialog has been defined with wind_set mode X_WF_DIALOG, these two options can be used to get or set the index of the object which currently has the edit cursor. This can be helpful when an application changes the contents of a text field while the dialog is still displayed, or when it needs to hide the object that currently has the edit cursor.

wind_get( X_WF_DIALEDIT ) will return the index of the object which currently has the edit cursor in the wi_gw1 parameter, and the position of the edit cursor within the object's text in the wi_gw2 parameter.

wind_set( X_WF_DIALEDIT ) changes the object (wi_sw1) and the edit index (wi_sw2). If the object is 0, then the edit cursor will simply be turned off; otherwise it will be moved to the new object. If the index is 0, the cursor will be positioned before the leftmost character in the field; if it is a number > 0, it will be further to the right. If the index is -1, then the cursor will be automatically moved to the rightmost position.

X_WF_DCOLSTAT (0x2100) (since Update 004)

This mode gets or sets a window widget's default colours and ob_state value. Unlike WF_DCOLOR, this option gives full control over all of Geneva's extended window widgets.

For wind_set, the wi_sw1 parameter contains the index of the window widget to change, taken from the list of WGCLOSE through WGSIZE, as outlined in xwind.h. wi_sw2 contains the colour for the widget when the window is on top, wi_sw3 is for an untopped window. wi_sw4 contains the ob_state WORD of the object. If any of these values is set to -1, then no change occurs.

For wind_get, the wi_sw1 parameter must be a pointer to a WORD containing the index of the widget being inquired about, the same way WF_COLOR and WFDCOLOR work.

Example: Turn the 3D attribute on for the mover bar

      int top, untop, state, gadget;

      gadget = WGMOVE;
      wind_get( 0, X_WF_DCOLSTAT, &gadget, &top, &untop, &state );
      state |= X_MAGIC|X_DRAW3D;
      wind_set( 0, X_WF_DCOLSTAT, gadget, -1, -1, state );