The Outline type

Purpose

An outline is intended to be the first object when a window is constructed, with all other objects as children (i.e. owned by that outline). An outline consists of a title item (which by default displays the program name), with below that a separator line.

Optionally there can be some items at the sides, like a Quit, Sleep, Help, Do, Wake, Info item. The info item can be defined by the programmer (both text and action). The other items have their standard use.

The sleep item should only be used for primary windows (the first one which is activated). Indeed, it doesn't make much sense to put to sleep a window pulled down over the main window...All items have their standard keypresses by which they can be activated.

The quit item can automatically ask for a confirmation request before exitting the program. If you want, you can also attach a keypress to the quit item.

The outline also contains two empty boxes at the left and right. The Object ID of these objects can be queried for, and some objects can be created inside these objects. Thus the functionality of the outline can also be extended. These boxes are created with a zero scale factor.

The Type Word

When creating this type of object, the type parameter is:

PW('TYPE_OUTLINE')

The tags

Here are the tags for this object. As usual, change tags are also used when creating the object, but query tags are only used for queries.

The change (and creation) tags
PW('OUTLINE_SLEEP')
This indicates that the outline is to contain a sleep item which, when actioned by the user, puts the program to sleep as a button. This tag needs no parameters. By default, the sleeping program will display its name. You should only use this tag in the primary window of your application. Also, you should not have any screen channel open when this is called, other than those opened by ProWesS.
PW('OUTLINE_SLEEP_TEXT')
This also makes sure that the outline contains a sleep item. This tag needs one parameter, a string, which is the text to be is displayed by the button. You should only use this tag in the primary window of your application.
PW('OUTLINE_QUIT')
This makes sure that the outline has a quit item. By default, the action of the quit item depends on the quit confirm status (see below).
PW('OUTLINE_ACTION_QUIT')
Attach a user defined action to the quit item. The outline should already have a quit item. The parameter should be an action routine, preferrably QUIT_ROUTINE. Please note that, in this case, the object returned will be the QUIT object, not the outline object. You can query the outline to obtain the quit object with one of the queries.
PW('OUTLINE_QUIT_CONFIRM')
Set the quit confirm status. The parameter is either 1 (=TRUE) or 0 (=FALSE). The default quit action uses this status to determine whether a confirmation request should be popped up before quitting. If this status is set to 0 (i.e. FALSE), then the window will be exited as soon as the user has actioned the Quit item, otherwise, a window will pop up to query whether the user is really sure he/she wants to quit the window. This tag has no parameter.
PW('OUTLINE_QUIT_KEYPRESS')
Attach a keypress to the quit item. The outline should already have a quit item. The parameter should be of type CODE (character$). By default the quit item has no keypress attached to it.
PW('OUTLINE_INFO_TEXT')
This indicates that an info item is included in the outline, and it sets the text for this info item. The parameter, a string, is the text which will be displayed in the item. There is only one info item per outline (but, of course, you can create a loose item with the text set to "Info" if you want).
PW('OUTLINE_ACTION_INFO')
This also indicates that an info item object is to be included in the outline and it sets the action routine for this object. If no info item existed already, the text in it will be "info", else this will apply to the info item already created (probably with PW('OUTLINE_INFO_TEXT'). The parameter is an action routine. It should be INFO_ROUTINE, and is the action routine for the info item.
PW('OUTLINE_ACTION_DO')
Make sure the outline contains a do item (object), which can be activated also by a DO keypress. The parameter should be DO_ROUTINE, and is the action routine for the do item. You must have queried the outline to obtain the object ID of the DO object.
PW('OUTLINE_ACTION_WAKE')
Make sure the outline contains a wake item, which can be activated also by a keypress. The parameter should be WAKE_ROUTINE.
PW('OUTLINE_TITLE_TEXT')
Set the title for the outline. The parameter is a string. By default, i.e. if this tag is not used, the title will be the program name.
PW('OUTLINE_HELP')
Make sure a help item is included in the window. The default action for the help item is to execute the ProWesS reader (which should be loaded as resident extension - to make it into an executable thing). The file which has to be displayed, the directory where it can be found and the position in the file can be specified by the PW('OUTLINE_HELP_xxx') tags (see below). This tag requires no parameters.
PW('OUTLINE_ACTION_HELP')
Assign your own action routine to the help item in the outline. If there was no help item yet, then it will be created. The parameter should be HELP_ROUTINE.
PW('OUTLINE_HELP_FILE')
Specify which help file should be loaded when the help item is indicated. This will automatically reset the position in the file (so the file will be displayed from the start). The parameter is a string with the filename.
PW('OUTLINE_HELP_POSITION')
Specify the position in the current help file which should be displayed when the help item is indicated by the user. The parameter is a string (i.e. the reader will go to that string).
PW('OUTLINE_HELP_DIRECTORY')
Specify the directory where the help file should be searched. The parameter is a string.

The query tags

The query tags allow you to get at some implicit objects, i.e. some objects which are created at the same time as the outline:

PW('OUTLINE_BOX_LEFT')
To allow the user to modify the behaviour and look of the outline object, there is always an empty box at the left in the outline. This empty box is an object itself, and you can may put some other objects in it. The box object is returned by this query (i.e. you say box_left=PWquery (outline, PW('OUTLINE_BOX_LEFT') ), box_left is then the object, or Object ID.
PW('OUTLINE_BOX_RIGHT')
Likewise, there is also always an empty box at the right in the outline. The user may put some objects in this box. The object is returned by this query.

There are also some other objects, which you can create explicitly when creating (or changing) the outline, such as a Quit item etc... Here again, these objects are not returned by the creation or change operation, so you can query for the object IDs, so that later you can SELect on these objects:

PW('OUTLINE_OBJECT_QUIT')
This returns the quit object in the outline.
PW('OUTLINE_OBJECT_INFO')
This returns the info object in the outline.
PW('OUTLINE_OBJECT_DO')
This returns the DO object in the outline.
PW('OUTLINE_OBJECT_WAKE')
This returns the wake object in the outline.
PW('OUTLINE_OBJECT_HELP')
This returns the help object in the outline.

PROGS, Professional & Graphical Software
last edited 1996 June 05 (wl)