The Outline type
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)