This document gives a general explanation about all the types which are always available in each ProWesS distribution. It only gives information about the general purpose and use of each type. Links are available to the definitions and tags for the objects of the type.
The system is not a type, but is can be queried or changed through any
object which is part of that system.
An outline is intended to be the first object when a window is constructed, with all other objects as children. An outline consists of a title item (which by default displays the program name), with a separator line below that.
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 to be activated). All items have their standard keypresses by which they can be activated.
The quit item can automatically ask for a confirmation request before exiting 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 PWObject 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.
A loose item is an object which can be "indicated". When the pointer appears inside a loose item, a border is drawn around the item (if the item type is used, the behaviour is different when using itemp). The item normally contains some text, although a routine can be provided to draw an icon in it.
A loose item reacts to both HIT and DO events. If you want
you can also attach a keypress to it, which will be the same as a HIT
event. A loose item can have one of three statusses : available,
selected or unavailable. When an item is unavailable, it
can't be indicated (and thus will not get a border). A HIT on
the item will toggle between available and selected, and a DO will
select the item. Optionally, a user defined function can also be called on a
HIT or DO event (not when the item is unavailable). The
designer of the window can also choose that the status of the item can never
change, and that a DO event can be propagated to the window.
This is a type which should be used to display a title. It displays the
title centred in a bar (which is at least slightly wider than the title). The
bar is usually displayed in a different colour to make the title stand out a
little. The title is there for information only, it does not react to any
events.
To seperate two (or more) objects, you often want to put a line between them. A separator does exactly that.
In some cases you don't just want a line somewhere, but you want a box
around an item. In that case you can use a container object and put the items
which should be in the box inside.
A direction is a region object which can be used as a container to put other regions inside. The use of this type can be necessary if you want to control the positioning of the objects in the window exactly, and the default scale factor or windowfitting do not suffice for your purposes.
Glue (which is in fact the same as a direction, but the name better fits the purpose) can be used to create some "special" effects for positioning objects. Glue is an invisible region which can be used for spacing out other objects. For example, if you have two objects, one of which should appear at the left of the window and the other one at the right, then you can put some glue in between, and that glue will stretch to eat unused space (according to the scale factor).
A keypress object is not visible in the window. It will react to a keypress in the window. The keypress which it should react to can be set with PW_KEYPRESS (like any object which belongs to the keypress group). A function can be set which should be called when the given key is pressed. If a keypress object does not have an action assigned to it, it will be handled as a HIT event in the owner (as set when creating the keypress object).
In ProWesS, keypresses are case dependant. However, if there is no object
which reacts to a particular keypress, then the case is changed and another
attempt is made to match that keypress. If there is still no match, than a
PW_EVENT_CATCH can be generated to an object which is designated to
catch all unmatched keypresses (this object is selected using
PW_CATCH_OBJECT).
A label object is normally used to indicate the purpose of another object (e.g. to tell what is being edited in an edline). A label assumes that it is positioned either left or above the object to which it refers.
When the label is displayed to the left of another object, the name in the
label will be displayed at the top right. If the label is positioned above
another object, then the text will be displayed at the bottom left.
The edline object is designed to allow the user to edit one or more lines of text (strings). The maximum length of each line can be set when you create the edline (or a default maximum length will be used). As an edline can not reasonably determine its width, that also can be given (or a default will be used).
An edline is available in two variants. The normal edline has to be indicated first to start editing the string. While the string is being edited, the pointer cannot be used in the window.
There is also a direct edline. This variant uses the keypress catching mechanism. To make sure that you can move the cursor, a direct edline will make sure that PW_CURSOR_SEPARATE is TRUE. A direct edline doesn't have to be indicated to start typing, but it has to be selected in some way as current catch object. If there is no catch object when a direct edline is created, then that direct edline will designate itself as such.
An edline can have an action which has to be executed when the user stops editing (presses <enter>). Also the programmer can set some objects which can be navigated to (using <tab>, <shift tab>, <up>, <down> or <enter>). The objects which can be moved to have to be able to work as a catch object.
Edline objects can handle the edited text being larger than the object can display (thanks to PROforma). The edline will also always try to assure that the cursor is visible with its surrounding characters. The cursor will therefore never hit the right end of the object, and the left end will only be touched when the cursor is at the start of the string.
Although you can choose between normal and direct edline, it is possible for
the users to configure their setup to always use either. To allow the
users to choose where they want to input their text, it should always be
possible to navigate to all the other edline objects in the window without
using the mouse.
These two types are quite similar to each other. They both display a text (lines separated by '\n', '\0' terminated) for information only. These objects don't react to any events.
An infostring object is always completely visible. When the text is changed, the size of the object will change (as with many other types, but this can be switched off).
Infotext objects have a size which is determined by the designer of the
window. Scroll bars are displayed to allow the user to scroll invisible parts
into view.
A Menu is a special purpose application window (explained later). It provides a scrollable list of loose items. The contents of each loose item is a string.
A menu is always vertically scrollable. The number of visible lines and the minimum width can be chosen by the designer of the window (the minimum width can be the maximum width of an item in the menu).
The items in the menu can be sorted using a compare routine as provided. When a menu is displayed, the items are all displayed in rows. Each row contains as many items as can be completely visualised (i.e. the width of the menu is divided by the itemwidth to get the number of items on each row). The menu is only scrollable vertically.
A menu can have no selectable items, at most one selected item, or
all items can be selected and deselected at will. The programmer can also query
all selected, all available or just all items (returning a pointer to the
string). Also the status of each item can be changed at will (normally an item
is just available when it is selected).
A canvas is a general purpose region object. It is a gateway for the application programmer to have direct access to all events which occur in it, for example to be used as the drawing area in a graphics program.
The canvas does not know what is in it. The contents has to be drawn using a user supplied routine. Therefore the size of the canvas has to be given explicitly. To allow for scrolling etc. the canvas also has an origin, which is the coordinate at the top left corner of the canvas. The origin is there only for information (to be used by the action routines) and is not used by the canvas type itself.
A canvas can react to the events which can occur inside it. A user supplied routine can be called when the pointer enters or exits the canvas, when a timeout occurs inside the region, or when the pointer is moved. Other events which can be reacted upon are a HIT, DO, or dragging (see next paragraph). An action routine can also be called when the canvas is resized.
Dragging is a HIT or DO which lasts longer than is normal,
usually while moving the pointer. A difference is made between dragging with a
HIT and dragging with a DO. An event is generated both when
the dragging starts and when it ends. During dragging, the pointer is not
allowed to move outside the canvas region. It the user does attempt to move
outside, the pointer position will be adjusted to stay inside the canvas. This
can also be trapped, for example to automatically scroll the canvas when it
occurs.
This object is a scrollbar. It is specially designed to interact with a canvas. The scrollbar allows vertical scrolling when it is positioned in a row (usually left or right of the canvas), and it allows horizontal scrolling when it is in a column. The scrollbar should be attached to a canvas. That canvas can then be queried for its size and origin, so that the scrollbar can display that info.
The scrollbar normally contains arrows and a bar to indicate the visible part in the whole. On creation, the designer of the window can choose not to display that bar (then arrows will then be larger). The minimum and maximum origin can be set. This will allow the bar to be displayed accurate and the scrolling can be restricted to stay between these two extremes. Because the origin may be in any user defined unit, it may be necessary to provide a routine to convert a size (of the canvas) into the unit used for the origin of the canvas.
The user can scroll the canvas by indicating the scroll arrows. The designer
of the window can set the distances which should be scrolled in the case of a
HIT (minimum scroll distance), or a DO (maximum scroll
distance) on the scroll arrows.
An application window is a composite object. It provides a canvas together with some scrollbars if you want them. It is very basic, all you can do is tell the application window to allow horizontal or vertical scrolling (with or without bar).
It is intended that you never directly use the scroll type, but if you want
a canvas with a scrollbar, that you always use an application window.
This is an object which allows you to select a directory in a directory select window. However, as there is no special method to have a window type of object, it is implemented as a keypress object. If the associated key is pressed, the window is activated, but you can also explicitly active the window. (Note that if you don't attach a keypress to the dirselect object (which is done with the PW_KEYPRESS tag), the window can't be activated with a keypress).
A directory select window consists of an edline where the directory can be edited directly, a list of devices and a menu which contains both the subdirectories to the current directory, and possibly some directories which have been configured because they are often used.
The devices which are displayed are the devices which have been configured as being the accessible (or most used) devices on your system (using DIRSELECT-DEVICE). The often-used directories can be configured using DIRSELECT-DIRECTORY).
The directory which should be used as default in the dirselect window can be
set explicitly (it defaults to "", which is converted to the data default (as
in DEVDataGet) when the window is activated). The title of the window
can also be set. When the directory has been selected (the window is exited),
a user-defined action is called, which can use the selected directory to poor
it into a parent window or do some other operation.
This is an object which allows you to select one or more files in a file select window. However, as there is no special method to have a window type of object, it is implemented as a keypress object. If the associated key is pressed, the window is activated, but you can also explicitly activate the window. (Note that if you don't attach a keypress to the fileselect object (which is done with the PW_KEYPRESS tag), the window can't be activated with a keypress).
A fileselect window normally allows the user to select just one file, but it can also be created to allow the user to select multiple files (in that case there is no edline to enter the filename, and the All item appears).
A fileselect window always displays a directory (of which the subdirectories and the files in it are also visible). The directory can be edited (with a HIT on the edline), or changed via the directory select window (a DO on the edline). The fileselect window also contains an edline in which you can set some file extensions (separated by a semicolon (;)). Only files which end in one of the extension will be displayed in the menu (or if Not is indicated, only files which do not end in any of these extensions will be displayed).
Of course the directory which has to be displayed, and the default extensions, the status of the Not item and the window name can be set explicitly. If only one file can be indicated, the default filename can also be set (note that all these values are preserved across activations of the window).
The designer of the window should pass a routine which has to perform some action with the selected file(s), otherwise the fileselect window serves no purpose to the user (this routine can for example load that file).
The fileselect window will by default use up the entire possible height. It contains a wake and quit item, but will also quit in case of a DO inside the window.
The fileselect can be customized to a large extent. You can insert some
extra objects in the window in a box between the title bar (the outline) and
the rest of the window. You can also change the title bar itself. Thus you
could add a sleep item, redefine Do etc. This way you don't have to
worry about the file selection etc. features in some applications.
This is not a general purpose type. It is a support type which is used for example by the loose item and the edline types. It is used to draw the border around an item, normally when the pointer is indicating that item. It is a separate type because it is common to more than one type, which prevents both duplication of code and strange configurations (the borders should always be equally thick, no mather what kind of object it is around).
This type should normally only be accessed from within other types. It
therefore only contains some of the handlers, only the Draw,
Entry, Exit and DetermineSize routines are provided.
The Draw routine may draw a permanent border (as is the case for the
itemp variant). The Entry routine will draw the border, and
the Exit routine will remove it. The DetermineSize should be
used to increase the total size of the region to include the border and to set
the widths of the margins around the hit area.
A listselect object is a very compact way to allow the user to make a choice
from a selection of things. It looks like a loose item which displays its
current value and starts with a pointing down arrow to indicate that there are
more choices. When the item is indicated, you get a submenu from which you can
choose a new value.