Class Documentation

Name:Window
Version:1.0
ID:ID_WINDOW
Status:Beta
Category:GUI
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems, 2003-2004. All rights reserved.
Short:  The Window class is used to create desktop windows and screen areas.



Description

The Window class provides a control system for the creation and management of application windows within the user interface. Because the Window class acts as a control system only, the window itself is virtual and physically represented as a Render drawable. The characteristics of the Render class are inherited by the window system, thereby allowing you to read and manipulate render fields (such as x, y, width and height) through the window object.

By default, new windows are created in the desktop area with the dimensions that you specify. If desirable, you can create full-screen windows by setting the Screen field to TRUE. Full-screen windows have a different set of specifications that keep them maximised to the display area at all times. They are borderless but still maintain a title bar and optional menu bar if required. If your application creates a full-screen window then all future windows will open within that screen space by default rather than on the desktop.

Window definitions are loaded by default from the environment file "templates:windowdef.xml". You can change the template file prior to initialisation by setting the Template field, however this is not recommended except under exceptional circumstances. See the Template field for details on how to design your own windows for custom environments.

Windows are publicly shared objects as standard and may not be allocated privately. This is automatically managed when using windows in scripts. If programming a window object directly, remember to grab its unique ID and access/release the window object correctly as you make use of it.

Actions

The Window class supports the following actions:

Activate  Shows the window.
Disable  Disables the user's ability to interact with the window.
Enable  Enables user interactivity after prior disablement.
Focus  Sets the user focus to the window's drawable.
GetUnlistedField  Pass-through arguments can be retrieved through this action.
Hide  Removes the window from the display.
MoveToBack  Moves the window to the back of the display area.
MoveToFront  Moves the window to the front of the display area.
Redimension  Changes the size and position of the window.
Resize  Alters the size of the window.
SetUnlistedField  Pass-through arguments can be set by using this action.
Show  Puts the window on display.

Methods

The Window class implements the following methods:

CloseWindow  Closes the window according to application requirements.
Maximise  Maximises the window to its available display area.
Minimise  Minimises the size of the window.

Structure

The Window object consists of the following public fields:

Center  Displays the window in the center of the display on initialisation.
Close  Operator for the window's close gadget.
CloseObject  The drawable that controls the Close gadget.
Drawable  The window's drawable.
Flags  Optional flags may be set here.
Focus  May be set to FALSE if you wish to open the window without giving it the focus.
Hide  Set on initialisation to keep the window hidden.
Icon  A graphical icon to be applied to the window.
InsideBorder  Enables a custom graphics border that surrounds the internal window.
Maximise  Operator for the window's maximise gadget.
MaximiseObject  The drawable that controls the maximise gadget.
Menu  References the location of an XML menu file to be applied to the window.
MenubarObject  The drawable that controls the window's menu bar.
Minimise  Operator for the title bar's minimise gadget.
MinimiseObject  The drawable that controls the minimise gadget.
MoveToBack  Operator for the title bar's move-to-back gadget.
MoveToBackObject  The drawable that controls the move-to-back gadget.
Quit  Set to FALSE to prevent application termination when the window is closed.
Resize  Determines what sides of the window are resizable.
ResizeBorder  Defines the extent of the resize area at the sides of the window.
RestoreHeight  Controls the height of the window when restoring to its previous state.
RestoreWidth  Controls the width of the window when restoring to its previous state.
RestoreX  Controls the horizontal position of the window when restoring to its previous state.
RestoreY  Controls the vertical position of the window when restoring to its previous state.
Screen  Enables full-screen mode.
ScreenMargin  Defines the minimum amount of margin space if the window is in full-screen mode.
ScriptArgs  Readable field for template usage only, retrieves custom arguments in DML format.
StickToFront  Forces the window to stick to the front of the display.
Template  Defines the makeup of the window using a pre-defined template.
Title  The title string to display in the window's title bar.
TitleObject  The object that controls the window title is referenced here.
Method:CloseWindow()
Synonym:Close
Short:Closes the window according to application requirements.

When terminating a window, it is recommended that you call the CloseWindow() method, as opposed to forcibly removing it with the Free action. By using the Close method, the application will have the opportunity to respond in a way that is appropriate for the window in question. When the Close method is typically called, the application will terminate entirely if the Quit field has been set to a value of TRUE. If this option is not set then the window will terminate quietly without affecting the core application.

If you would like to write a customised routine for window closure, set the MANUALCLOSE flag for the window and then subscribe to the Close method (or set the Quit field and wait for a quit message on the message queue). This will allow you to receive close notifications and you can respond in a way that suits the current situation.


Method:Maximise()
Short:Maximises the window to its available display area.
Arguments:
LONG Toggle  Set to TRUE to toggle the window back to its original dimensions if the window is already maximised.

Executing the Maximise method will run the maximise procedure for the window. The specifics of the maximisation process may be environment specific, but typically maximisation will result in the window being expanded to the maximium dimensions allowed by its container. The process will take into account the hints provided by the margin settings of the parent drawable (so if the margins are all set to 10, the window will be maximised to the size of the container minus 10 pixels from its edge).

An optional Toggle argument allows you restore the window to its original position if the method routine discovers that the window is already maximised.

Result
ERR_Okay  The window was maximised successfully.
ERR_AccessObject  Failed to access the window's parent drawable.

Method:Minimise()
Short:Minimises the size of the window.

Executing the Minimise method will run the minimise procedure for the window. The specifics of the minimisation process are defined by the window template of the current environment. It is typical for the window to iconify itself to the desktop in some way, so that it is removed from the sight of the user.

Result
ERR_Okay  Success.

Field:Center
Short:Displays the window in the center of the display on initialisation.
Type:BOOLEAN
Status:Read/Init

The Center field may be set to TRUE on initialisation for the window to be automatically centered before it is shown for the first time.


Field:Close
Short:Operator for the window's close gadget.
Type:BOOLEAN
Status:Read/Set

The Close field controls the activity of the close gadget, which is typically found in the window title bar. The default value for the close gadget is TRUE and may be switched off at any time by setting this field to FALSE.


Field:CloseObject
Short:The drawable that controls the Close gadget.
Type:OBJECTID
Status:Read/Init

The drawable that represents the window's close gadget may be referenced through this field. If no close gadget is available then this field will be empty.

Theme Developers: Your window code must set this field with the ID of the drawable that you have created for the close gadget.


Field:Drawable
Short:The window's drawable.
Type:struct Render *
Status:Read

The drawable that represents the window on the display can be retrieved through this field. The reference is a direct pointer to the Render object in question. It is possible to manipulate the drawable without encountering adverse effects with the window object, although it is wise to refrain from doing so where functionality is duplicated in the Window class. For instance, Hide and Show actions may not be called on the drawable object as this functionality is already controlled by the window system.


Field:Flags
Short:Optional flags may be set here.
Type:LONG
Prefix:WNF
Status:Read/Init

Optional flags that may be set against a window object are as follows:

FlagDescription
SMARTLIMITSEnables smart-limit settings, a special feature that prevents the window from completely leaving the display no matter where the user tries to move the window. This mode will ensure that enough of the title bar is visible so as to allow the user to drag the window back into the display area.
MANUALCLOSEThis option is used for controlling the behaviour taken when the window is asked to close. You must match this flag with a subscription to the Close method so that you can respond to window close signals.
BACKGROUNDThis option will guarantee that the background of the window will always be cleared to a neutral colour (probably grey). Background clearing occurs automatically for desktop windows, but not for windows that are in full-screen mode. You should always set this flag if you do not intend to define the window background yourself.
VIDEOEnables video buffering of the the window instead of software buffering. The success of this option is dependent on whether or not video RAM is available.

Field:Focus
Short:May be set to FALSE if you wish to open the window without giving it the focus.
Type:BOOLEAN
Status:Read/Write

By default the window will be given the focus whenever it is shown on the display via the Show action. You turn off this behaviour and take control of the window focus manually by setting the Focus field to FALSE.


Field:Hide
Short:Set on initialisation to keep the window hidden.
Type:BOOLEAN
Status:Read/Init

This field is for use when creating windows in scripts, such as DML. By default, windows are shown following creation in scripts. You can turn off this behaviour and manually show the window when you are ready by setting the Hide value to TRUE.


Field:Icon
Short:A graphical icon to be applied to the window.
Type:STRING
Status:Get/Set

A suitable icon that you would like to apply to the window may be specified here. The window theme will choose how the icon is used and displayed to the user. It is common for windows to use the referenced icon in the window title bar and when iconifying the window.

It is preferred that you use an icon from the existing icon database (if you have a customised icon that you would like to use, you should install it to the icon database on installation). The window system will automatically scale the icon graphic to the required dimensions when it is loaded.


Field:InsideBorder
Short:Enables a custom graphics border that surrounds the internal window.
Type:BOOLEAN
Status:Read/Init

Set the InsideBorder field to TRUE to create a simple graphics border around the edges of the drawable window area. The benefit of using this field to create a graphics border instead of a customised border is that it maintains consistency with the other window graphics for the loaded environment.


Field:Maximise
Short:Operator for the window's maximise gadget.
Type:BOOLEAN
Status:Read/Set

The Maximise field controls the activity of the maximise gadget, which is typically found in the window title bar. The default value for the gadget is TRUE (environment dependent) and may be switched off at any time by setting this field to FALSE.


Field:MaximiseObject
Short:The drawable that controls the maximise gadget.
Type:OBJECTID
Status:Read/Init

The drawable that represents the window's maximise gadget may be referenced through this field. If no maximise gadget is available then this field will be empty.

Theme Developers: Your window code must set this field with the ID of the drawable that you have created for the maximise gadget.


Field:Menu
Short:References the location of an XML menu file to be applied to the window.
Type:STRING
Status:Get/Set

To load a menu bar into the window you will need to set this field with the location of a menu file that you want to use for the window. The file must be in XML format and contain at least one menu tag. Each menu tag that you specify will create a new menu option in the menu bar that is owned by the window. Non-menu tags will be ignored.

Any unlisted arguments that you have specified for the window will be passed on to each created menu.

For information on the specifics of menu customisation, please refer to the Menu class.


Field:MenubarObject
Short:The drawable that controls the window's menu bar.
Type:OBJECTID
Status:Read/Init

If you have created a menu for the window then this field will reference the menu bar's drawable area.

Theme Developers: Your menu bar creation code must set this field with the ID of the drawable that you have created for menu bar representation.


Field:Minimise
Short:Operator for the title bar's minimise gadget.
Type:BOOLEAN
Status:Read/Init

The Minimise field controls the activity of the minimise gadget, which is typically found in the window title bar. The default value for the gadget is TRUE (environment dependent) and may be switched off at any time by setting this field to FALSE.


Field:MinimiseObject
Short:The drawable that controls the minimise gadget.
Type:OBJECTID
Status:Read/Init

Field:MoveToBack
Short:Operator for the title bar's move-to-back gadget.
Type:BOOLEAN
Status:Read/Init

The MoveToBack field controls the activity of the move-to-back gadget, which is typically found in the window title bar. The default value for the gadget is TRUE (environment dependent) and may be switched off at any time by setting this field to FALSE.


Field:MoveToBackObject
Short:The drawable that controls the move-to-back gadget.
Type:OBJECTID
Status:Read/Init

The drawable that represents the window's move-to-back gadget may be referenced through this field. If no move-to-back gadget is available then this field will be empty.

Theme Developers: Your window code must set this field with the ID of the drawable that you have created for the move-to-back gadget.


Field:Quit
Short:Set to FALSE to prevent application termination when the window is closed.
Type:BOOLEAN
Status:Read/Write

By default this field is set to TRUE, which will force the program to quit when the window is closed (the application will be sent a QUIT message). You can turn off this behaviour by setting this flag to FALSE.


Field:Resize
Short:Determines what sides of the window are resizable.
Type:STRING
Status:Init

This field defines what sides of the window are resizable. It can only be set from the template script that is defined for the window. The string format is defined as a series of flags separated with the OR character. Valid options are:

   TOP, BOTTOM, LEFT, RIGHT
   TOPLEFT, TOPRIGHT, BOTTOMLEFT, BOTTOMRIGHT

Field:ResizeBorder
Short:Defines the extent of the resize area at the sides of the window.
Type:LONG
Status:Init

If you have set the Resize field then you can optionally define the size of the border to use for each window edge. Recommended values range between 4 and 8 pixels.

This field can only be set from the template script that is defined for the window.


Field:RestoreHeight
Short:Controls the height of the window when restoring to its previous state.
Type:LONG
Status:Read/Write

This field assists in the restoration of the window when it is minimised, maximised or has its dimensions changed in a customised way. The value that you set here will reflect the new height of the window when it is restored to its 'previous' state. This field is provided for control purposes and should only be used from the window's template script.


Field:RestoreWidth
Short:Controls the width of the window when restoring to its previous state.
Type:LONG
Status:Read/Write

This field assists in the restoration of the window when it is minimised, maximised or has its dimensions changed in a customised way. The value that you set here will reflect the new width of the window when it is restored to its 'previous' state. This field is provided for control purposes and should only be used from the window's template script.


Field:RestoreX
Short:Controls the horizontal position of the window when restoring to its previous state.
Type:LONG
Status:Read/Write

This field assists in the restoration of the window when it is minimised, maximised or has its dimensions changed in a customised way. The value that you set here will reflect the new horizontal coordinate of the window when it is restored to its 'previous' state. This field is provided for control purposes and should only be used from the window's template script.


Field:RestoreY
Short:Controls the vertical position of the window when restoring to its previous state.
Type:LONG
Status:Read/Write

This field assists in the restoration of the window when it is minimised, maximised or has its dimensions changed in a customised way. The value that you set here will reflect the new vertical coordinate of the window when it is restored to its 'previous' state. This field is provided for control purposes and should only be used from the window's template script.


Field:Screen
Short:Enables full-screen mode.
Type:BOOLEAN
Status:Get/Init

Set the Screen field to TRUE in order to launch the window in full-screen mode when it is opened. Full-screen windows use a different window template to that used as standard and thus have their own behavioural conditions that may differ significantly to the default. At a minimum, full-screen windows will cover the entire display area and be locked to that size. Resizing of the window is not possible unless the user changes the desktop's screen resolution.

When your application opens a full-screen window, it will serve as the default display area when you open further windows. If you would like to open new windows in other drawables, you will need to set the Target field to alter the default opening behaviour.


Field:ScreenMargin
Short:Defines the minimum amount of margin space if the window is in full-screen mode.
Type:LONG
Status:Get/Init

If a window opens in full-screen mode (i.e. if you set the Screen field to TRUE) then it will typically be created without any margins on the left, right and bottom sides of the window space. This will mean that all created graphics will be flush against the screen area. If you would like a small amount of white-space to be added to the screen border then you will need to set the ScreenMargin field. A value between 4 and 6 is usually appropriate.


Field:ScriptArgs
Short:Readable field for template usage only, retrieves custom arguments in DML format.
Type:STRING
Status:Get

For template usage only. This field will return a string that contains all unlisted arguments as a DML string series. For instance, if you pass two unlisted arguments 'A' and 'B' with values of '1' and '0' respectively, reading the ScriptArgs argument will return the following:

   &A="1" &B="0"

This feature is typically used in the template definition file for passing custom parameters to objects such as menus.


Field:StickToFront
Short:Forces the window to stick to the front of the display.
Type:BOOLEAN
Status:Set

Set this field to TRUE to force the window to stay at the front of its display. This option should be used leniently. It is recommended for use in small windows and presenting warning or error messages to the user.


Field:Template
Short:Defines the makeup of the window using a pre-defined template.
Type:STRING
Status:Init

Setting the Template field allows a window definition to be loaded from a pre-defined template file. Changing to a customised template is not recommended, as the user environment will have already defined a preferred template file for you. Use of customised templates may cause problems with consistency in the user interface. If you would like to define a window template for a new environment, we recommend defining a new templates:windowdef.xml file rather than setting this field directly.

Template files are defined in XML and are split into a number of segments that control specific parts of the window. The first definable tag is 'values', which defines the default values for newly created windows. It is typical to define preferred values for the window coordinates and set the resize parameters. The window margins should also be configured so that it is clear how much space around the edges of the window is for custom graphics. Here is an example:

<values>
  <resize value="left|bottomleft|bottom|bottomright|right"/>
  <xcoord value="=[[self.parent].leftmargin]+10"/>
  <ycoord value="=[[self.parent].topmargin]+10"/>
  <resizeborder value="4"/>
  <topmargin value="22"/>
  <leftmargin value="6"/>
  <rightmargin value="6"/>
  <bottommargin value="6"/>
</values>

The bulk of the window graphics are defined in the 'graphics' tag. You are expected to create graphics objects that will be initialised directly to the window's drawable. The drawable can be referenced via the {owner} argument and the window referenced through the {window} argument. Your script should also take note of the InsideBorder field and create a window border if the border has a value of 1. The following example illustrates:

<graphics>
  <box colour="[gl_colours.colour]" shadow="[gl_colours.shadow]"
    highlight="[gl_colours.highlight]" raised/>

  <if statement="[{window}.insideborder] = 1">
    <box sunken x="=[owner.leftmargin]-1" y="=[owner.topmargin]-1"
      xoffset="=[owner.rightmargin]-1" yoffset="=[owner.bottommargin]-1"
      highlight="#dfdfdf" shadow="#202020"/>

    <box sunken x="=[owner.leftmargin]-2" y="=[owner.topmargin]-2"
      xoffset="=[owner.rightmargin]-2" yoffset="=[owner.bottommargin]-2"
      highlight="#ffffff" shadow="#808080"/>
  </if>
</graphics>

The window title bar is configured in the 'titlebar' tag. The title bar should allow the user to drag the window around the display and provide a series of gadgets that control the window (such as minimise and maximise buttons). You should also define an object that will control the window title. You will need to communicate with the window object for the purpose of determining the titlebar configuration, plus you will need to set certain window fields for communication purposes. For examples on how to generate the titlebar, please refer to your templates:windowdef.xml file.

You will need to define a 'menubar' tag so that a menu strip can be created for the window if the user requests one. The requirements for this are similar to the title bar definition. An {xml} parameter will be provided that refers to an XML object that is to be used for configuring the menu bar. By scanning the object you will be able to extract the names of each menu option that you need to create. Please refer to your templates:windowdef.xml file to observe how this should be done.

Finally, a number of optional tags may be used for window control purposes. These tags can contain DML scripts that will be executed when certain actions occur to the window. The following table describes the available tags:

TagDescription
MaximiseExecuted when the Maximise method is called on the window.
MinimiseExecuted when the Minimise method is called on the window.

Field:Title
Short:The title string to display in the window's title bar.
Type:STRING
Status:Get/Set

The Title field controls the text that is displayed in the window's title bar. You may set this field at any time in order to change the title that is displayed inside the window. A standard UTF-8 text string is acceptable and will be trimmed if it exceeds the maximum number of possible characters.


Field:TitleObject
Short:The object that controls the window title is referenced here.
Type:OBJECTID
Status:Read/Init

The object that controls the window's title bar text is referenced through this field. If no title bar is configured then this field will be empty.

Theme Developers: Your window code must set this field with the ID of the object that manages the title bar. A Text object is typically used for this purpose.