Windows

OBJECTS

  typedef drawing  window;

  typedef void (*actionfn)(window w);
  typedef void (*drawfn)(window w, rect r);

FUNCTIONS

  window newwindow(char *name, rect r, long flags);
  void   del(window w);				/* destroy window */

  void   settext(window w, char *newname);	/* set window title */
  rect   getrect(window w);			/* drawable area */
  int    getdepth(window w);			/* screen resolution */

  void   show(window w);	/* make window visible, frontmost */
  void   hide(window w);	/* hide but do not destroy window */

  void   addto(window w);	/* add new controls to this window */

  void   setredraw(control c, drawfn fn);	/* window redrawn */
  void   setresize(control c, drawfn fn);	/* window resized */
  void   setclose(control c, actionfn fn);	/* window closed */

CONSTANTS

  #define SimpleWindow		0x00000000
  #define StandardWindow	0x000003E0

  #define Menubar		0x00000010
  #define Titlebar		0x00000020
  #define Closebox		0x00000040
  #define Resize		0x00000080
  #define Maximize		0x00000100
  #define Minimize		0x00000200

  #define Modal			0x00001000
  #define Floating		0x00002000
  #define Centered		0x00004000
  #define Centred 		0x00004000

  #define Workspace		0x00010000
  #define Document		0x00020000

  #define UsePalette      	0x00100000

NOTES

A window is a rectangular area displayed on a screen. A window has a zero origin in its own co-ordinate system, but may have various structures built around its drawable area, such as titlebars, borders and menubars. A window is also a drawing, and as such can be used with all of the drawing operations (see later sections for details).

The newwindow function creates a window with the given name. The rectangle specifies where the window's drawable area should appear on the screen, with zero being the top-left point of the screen. The flags parameter is usually the constant StandardWindow. If an error occurs the function returns NULL.

The flags field in newwindow is a bit-field. Various constants can be combined using the plus or bitwise-or operators to specify how the window should look. Here is a list of those constants and their meanings:

• The Titlebar flag gives the window a titlebar which can be used for moving it around the screen and also for displaying the window's name.
• The Menubar flag can be used to reserve space for a menubar on the window, if the platform allows this.
• Closebox gives the user a way of closing the window.
• Maximize gives the user a way of increasing the size of the window to its maximum, and
• Minimize allows the window to be shrunk to an icon.
• Resize gives the user a method of changing the size of the window.
• The Centered or Centred flag causes the window to appear at the centre of the screen.
• Adding the Modal flag means the window will be in front of all other application windows when it is displayed, and no events will be sent to the other windows until it is hidden.
• Floating windows will appear in front of all other application windows even when not active.
• The Visible constant is used to make the window visible as soon as it is created. If this flag is not specified, the window will be invisible until explicitly made visible using the show function (see below).
• A Workspace window can contain many Document windows. The appearance of these windows depends on the platform. Any number of Document windows can appear within a single Workspace window. On the Macintosh, a Workspace window will just be the screen and will have no window structure, but under Windows it is an MDI main window. Document windows automatically have the following flags set: Titlebar, Closebox, Maximize, Resize, Visible.
• The UsePalette flag causes a window to have a private colour palette, on platforms which allow this (currently only X-Windows). In practice this means the first 250 or so colours drawn to that window will be displayed perfectly when that window is active.
• A SimpleWindow is a window with no 'decorations' at all.
• The StandardWindow constant is defined as having the following flags set: Titlebar, Resize, Closebox, Minimize, Maximize. It is provided as a convenience, and is sufficient for most uses of newwindow.

The del function destroys the specified window, hiding it first if necessary. If a window can be re-used, it is more efficient to hide it and then show it later on, rather than del the window and recreate it every time the user needs the window.

The settext function changes the name of the window as shown in the window's titlebar.

The getrect function returns the window's drawable rectangle in window co-ordinates; hence the top-left point will be zero. The getdepth function returns the pixel-depth of the screen on which the window is displayed.

The show function makes the specified window visible on the screen and ensures it is the frontmost application window. The hide function causes the specified window to vanish from the screen.

The addto function can be used to specify which window is to receive any newly created controls. Normally, controls are added to the most recently created window. The addto function provides a way of choosing a destination window instead.

The setredraw function is used to attach a call-back function to a window, which will be called every time that window needs to be redrawn. There is no need for this call-back to clear the window since this will automatically be done by the window manager.

The setresize function sets the call-back to be used when a window is resized by the user. The window is always resized before being redrawn, in circumstances where both of these events must be occur.

The setclose function sets the call-back to be used when the user tries to close the window using the window's close-box. If this call-back is not set, the window will simply be hidden. If the call-back is supplied, it will be called instead, and the window will not be hidden. It is then up to the programmer to achieve the desired effect.