Resource Files and the Resource Editor

Overview

Although Visual PRO/5 provides the ability to create graphical objects on the fly through program code, the language also supports the use of resource files. Each resource file defines one or more windows, called resources. The resource file may include all the graphical objects to be used in the window, or it may define a partial resource to which objects are added by the program. The program can also manipulate objects defined in the resource as though they had been defined with program code. These files may be created through the BASIS Resource Editor.

The BASIS Resource Editor offers a graphical interface that enables the programmer to quickly and easily create windows and dialogs for applications. An intuitive point-and-click interface with a convenient snap-to grid allows placement of graphical controls where wanted and size adjustment without having to count pixels.

Without the Resource Editor, a typical window containing several buttons, list objects, text objects, text objects, scroll bar, and a menu bar would require a command for each object created in the window, as well as a mnemonic to create the window itself. However, if the window is designed with a Resource Editor and saved in a resource file instead, only three commands are required to open the resource file, retrieve the resource, and display the window with all of its controls.

Resource files are retrieved in Visual PRO/5 programs via the RESOPEN and RESGET commands, and the resources are passed to the SYSGUI device through the 'RESOURCE' mnemonic. Although windows can be built through more specific commands passed to the SYSGUI device, using resource files speeds development and reduces the chance for errors slipping into hard-coded screen designs. In addition, an element of standardization is easily added to an application that makes extensive use of resource files.

Defining Graphical Objects

In Visual PRO/5, the base object is the window, which is used to contain other graphical objects. All graphical objects in Visual PRO/5, including windows, possess attributes, known in some languages as properties, which specify the behavior of the object. Attributes are set when objects are created, and in many cases can be changed dynamically at run time.

Visual PRO/5 applications may make use of various standard graphical objects such as edit boxes, list edits, list boxes, list buttons, push buttons, tool buttons, plotting surfaces, radio buttons, check boxes, group boxes, dialogs and child windows.

Each of these windows has a standardized behavior that is controlled by the Windows system. For example, when a pushbutton is clicked, the button will move downward and then back up as though it had been pressed and released. The Windows system provides this button animation and places the button-press event in the event queue. Some aspects of the standard behavior can be influenced by the selection of attributes for the control.

Several of the window attributes may be controlled through mnemonics (i.e., 'MOVE', 'SIZE', 'DISABLE', 'ENABLE', 'HIDE', 'SHOW', 'FOCUS', 'MINIMIZE', 'MAXIMIZE', etc.), which allow application programs to change their appearance dynamically. The individual controls may also be affected by many of these mnemonic commands.

Controls are the graphical objects that are placed within windows and dialogs to provide functionality. Visual PRO/5 supports the following controls:

• Check box

• Custom edit control

• Edit box

• Group box

• List box

• List button

• List Edit

• Menu

• Push button

• Radio button

• Scroll bars

• Status bar

• Static text control

• Tool button

Menus and cues are also available and along with controls, may be placed freely within the windows, dialogs, and/or child windows

Like the window objects, controls possess attributes that are set when these objects are created but which also may be changed at run time. All windows contain an event mask, which filters the type of events that are passed to the event queue for evaluation by the application program. The event mask is set when the window is created, and it is the developer's responsibility to ensure that the mask will pass all the event types that are desired from that window. Like attributes, the event mask can be modified dynamically at run time.

To alter the event filter at run-time, the `EVENTMASK' mnemonic is used to pass a new mask to the current window within the SYSGUI device.

If it becomes necessary for an application to assume detailed responsibility for responding to user events (e.g., clicks on list box items), the application programmer may take over such tasks for as long as desired by altering the event mask, and then return control and responsibility to the SYSGUI device when the need is fulfilled.

All graphical windows and child windows in Visual PRO/5 are created through the 'WINDOW' and 'CHILD' mnemonics. The syntax for the 'WINDOW' mnemonic is:

'WINDOW' (x,y,w,h,title,flags,{eventmask})

Where:

x,y	Specifies the coordinates of the upper-left corner of the window in currently scaled CONTROL units.
w,h	Defines the width and height of the window in currently scaled CONTROL units.
title	A string value displayed in the Title Bar of the window. It may be an empty string.
flags	A hexadecimal string that selects which attributes are to be set in the window upon creation.
eventmask	A hexadecimal string that indicates which optional events are to be reported from this window. If none are needed, a null string, $$, can be entered. Mask bits are listed in the Event Driven Programming documentation.

The flag bits for the flags parameter above are passed in the form of a 4-byte string. The hexadecimal values are provided because these are bit flags. Hexadecimal sums must be used to indicate combinations of attributes. The flag bits are:

Attribute	Flag Bit
Close Box	$00000002$
Gravity	$00100000$
Horizontal scroll bar	$00000004$
Initially disabled	$00000020$
Initially invisible	$00000010$
Initially maximized	$00001000$
Initially minimized	$00000100$
Keyboard navigation	$00010000$
Menu bar	$00000800$
Minimizable	$00000080$
Modal dialog style border	$00040000$
Modal dialog behavior	$00080000$
Stays on top	$00020000$
User sizable	000000001$
Vertical scroll bar	$00000008$

Most combinations of these attributes are valid, but not all. For instance, using the "Modal dialog style border" attribute precludes use of all window decorations except scroll bars. Therefore, use of this attribute automatically turns off or negates the attributes for "User sizable", "Close box", "Minimizable", "Menu bar", "Initially minimized", and "Initially maximized." Other attributes may be used freely.

Colors and Fonts

While PRO/5 offers the ability to change the colors and fonts used in nearly every type of graphical object, the behavior of colors and fonts may vary widely from one platform to the next. Every attempt has been made to provide consistent behavior, but the variation in monitors, graphics drivers, installed fonts, and the like, makes it impossible to make guarantees. For best results on all platforms, use contrasting colors and avoid using exotic RGB values.

There are five standard font family names that are guaranteed to behave reliably. These five standard font family named are "fixed", "helvetica", "courier", "system", and "times" which must be specified in lower-case. Any valid font family name for the GUI system in use may be specified (e.g., "Courier New" in Windows), but these may not work properly without modification when moved to other platforms supporting PRO/5. A list of available font families on the system may be retrieved with CTRL() function 9.

Expect to see slightly different shades of color or slight font variations when using custom colors or custom fonts with generic controls. The same colors or fonts may appear slightly different in generic control ('BUTTON', 'LISTBOX', etc.) as compared to the way they look when used with special purpose controls ('TXEDIT', 'TBUTTON', 'STATBAR') or with the drawing commands.