Chapter 19 - Object Subroutine

The built-in subroutine OBJECT provides access to the creation and manipulation of windows, controls, and selected graphics objects. A single calling sequence is used:

CALL Object (method, id, attributes$, values$, values())
Method is a number between 0..13 and 20..26 (usually represented by a variable) and denotes the method to be applied to the object or control. The argument id is the identification number of the object or control. Attributes$ is a string expression that contains one or more attributes for which values need to be set (SET method) or interro- gated (GET method); if there is more than one, the items in the list are separated by vertical bars “|”. Additional string information is communicated through values$; again, multiple items are separated by vertical bars “|”. Additional numeric information is communicated through a numeric list values().
———————————–––————————————————————————————
[ ! ] Note: The descriptions in this chapter use the public variable names to refer to methods, etc. They
are defined in a module at the end of the file containing True Controls (TrueCtrl.tru).
————————————————–––———————————————————————
Physical windows can be created with or without borders, title bars, close boxes, resize boxes, scroll bars, etc. All con- trols and graphics objects will be created to belong to a certain window (the current physical window.)

The controls include: Push buttons
Radio buttons and radio button groups
Check boxes
Horizontal and vertical scroll bars
Edit fields
Static text fields
List boxes
List buttons
List edit buttons
Group boxes
Text editors
Icons (not available on all platforms) The graphics objects include:
Circles
Lines Rectangles Arcs
Pie segments Arrowed lines Round rectangles Polygons
308 True BASIC Language System

Polylines
Images (from a file or from box keep strings)

Push buttons can contain a short piece of text. Under certain conditions they can be outlined and activated by pressing the Enter or Return key.

Radio buttons are round, and can come with identifying text to their right. If established in a group of radio but- tons, no more than one radio button in the group can be “on” at a time. (Radio buttons that are “on” have a dark cir- cle in their middle.)

Check boxes are small squares, and can come with identifying text to their left. A check box is “on” if an “X”
appears in it. On some platforms a check mark may appear instead of an “X”.

Horizontal and vertical scroll bars are equipped with arrows at each end, a slider region or trough, and a so- called thumb or slider. Usually, clicking in one of the arrows causes the thumb to move one unit up or down. Clicking in the gray area of the slider region causes the thumb to move several units up or down. Clicking and dragging on the thumb can cause it to move as you direct.

Edit fields are one-line editable text regions. The OBJECT routine lets you store a format for each region so that you may later check the text for consistency with the format.

Static text fields display a single text string, which may occupy several lines if the field is high enough. They can not be edited.

List boxes are boxes that contain a possibly scrollable list of choices. Selections are made by clicking. Multiple selections are allowed on some platforms. Selection list boxes can be combined with other controls to build, say, a modeless File Open dialog box. (For modal dialog boxes, see the TBD subroutine and the section on True Dials.)

List buttons are small rectangular regions that, when selected, open up into a scrollable list. Selecting an item from the list moves that item to the button area.
List edit buttons are like list buttons including the scrollable list, but the user may edit the button area.

Group boxes are merely rectangular figures, possibly with a title. They can be used to visually organize a set of controls, such as a radio group. They do not actually “combine” elements.
Text editors are complex controls that can be used to construct a wide variety of editors. Features can include: horizontal and vertical scrolling, wrapping of text at a margin, selecting subsets of the text, adding and deleting characters, etc.
Icons are not available.

Methods
The methods include:
Method Numeric value Function
OBJM_CREATE 0 Create an object or control OBJM_COPY 1 Create a copy of an object or control OBJM_SET 2 Set one or more attributes OBJM_GET 3 Get one or more attributes
OBJM_SHOW 4 Show (make visible) an object or control
OBJM_ERASE 5 Hide an object or control
OBJM_FREE 6 Remove an object or control and free the memory OBJM_SELECT 7 Select a physical window to be active, or to select a control OBJM_UPDATE 8 Redraw the contents of a physical window OBJM_SYSINFO 9 Obtain certain system information
OBJM_PRINT 10 Print the contents of a physical window
Object Subroutine

309

OBJM_PAGESETUP 11 Display a page setup box
OBJM_REALIZE 12 Realize or append True BASIC’s color mix table to the system color mix table.
OBJM_SCROLL 13 Scroll contents of a window

There are additional methods that apply only to text edit controls: OBJM_TXE_SUSPEND 20 Suspend activity for the text edit control OBJM_TXE_RESUME 21 Resume activity for the text edit control OBJM_TXE_ADD_PAR 22 Add a paragraph of text OBJM_TXE_DEL_PAR 23 Delete a paragraph of text OBJM_TXE_APPEND_PAR24 Append a paragraph of text OBJM_TXE_VSCROLL 25 Scroll the text vertically OBJM_TXE_HSCROLL 26 Scroll the text horizontally

Remember that the above identifiers are actually variable names that are assigned numeric values in the module CONSTANT.TRU located in the TBLIBS directory. If you wish to use these variable names, you must include CONSTANT.TRU in a LIBRARY statement and you must DECLARE each variable name. The variable names may be used in upper, lower, or mixed case. (See that file for the numeric equivalents and definitions of other vari- ables that can be used.)

The methods can be specified by numeric value, or (recommended) by the value of the publicly-declared variables OBJM_CREATE, etc., when using either TrueCtrl.trc (True Controls) or Constant.trc. In what follows, we do not include the equivalent numeric value; see Constant.tru for these.

The Create Method
When the OBJECT subroutine is used to create a new object or control, the attribute and string value parameters are not used. The type of object is passed in values(1). Possible types are:
OBJT_GRAPHIC Create a graphic object OBJT_WINDOW Create a window OBJT_CONTROL Create a control OBJT_MENU Create a menu OBJT_GROUP Create a (radio button) group

For graphics objects, the type of the object must be established using the OBJM_SET method. Use “GRAPHIC TYPE” as the attribute, and pass the type as the value of values(1). The types of graphics objects are:
GRFT_CIRCLE Circle or ellipse GRFT_LINE Straight line GRFT_RECTANGLE Rectangle GRFT_ARC Arc
GRFT_PIE Pie segment
GRFT_ALINE Line with arrows at either end GRFT_ROUNDRECT Rectangle with rounded corners GRFT_POLYGON Closed polygon GRFT_POLYLINE Open polygon (ends not joined) GRFT_IMAGE Graphical image (from a file)
Additional attributes are established using the OBJM_SET method.

For windows, many attributes are possible. They can be established using the OBJM_SET method.

For controls, the type of control must be established. This is done using the OBJM_SET method with the attribute
“CONTROL TYPE”. The type of control is passed as the value of values(1). Possible types are:
310 True BASIC Language System

CTLT_PUSHBUTTON Push button CTLT_RADIOBUTTON Radio button CTLT_CHECKBOX Check box CTLT_HSCROLL Horizontal scroll bar CTLT_VSCROLL Vertical scroll bar CTLT_EDIT Editable text field CTLT_TEXT Static text field CTLT_LBOX List box CTLT_LISTBUTTON List button CTLT_LISTEDIT List edit button CTLT_GROUPBOX Group box rectangle CTLT_TXED Text editor CTLT_ICON Icon
Menus are always associated with windows. Each menu and menu item must be created separately. Values(1)
contains the value OBJT_MENU. The type of menu is passed as the value of values(2). Possible types are:
MENT_BAR A new menu bar item
MENT_ITEM A new menu item

You must also pass, in values(3), the ID of the parent of the menu or menu item. For menus, the parent ID is the ID of the window. For menu items, the parent ID is the ID of the menu in which the item falls. For hierarchi- cal menus, the parent ID is the ID of the menu item to which the sub-menu is associated.

There are several attributes that may be set for menus and menu items. They include the text of the menu or menu item, the so-called mnemonic or hot key equivalent, whether the menu item is to be a separator, whether the menu item is enabled or not (i.e., dimmed if disabled), whether it is checked or not, and whether it is indeed checkable at all. These attributes are discussed in a later section.

Hierarchical menus may be established by passing, in values(3), the ID number of a menu item (rather than a menu header) that is to serve as the start of the hierarchical menu.

Groups can be created only for groups of radio buttons. To create the group, you must have previously created all the radio buttons in the group. You then create the group using the OBJM_CREATE method with values(1) = OBJT_GROUP and with values(2) through values(n+4) containing, respectively: 0, 1, n (the number of but- tons), ID of button 1, ..., ID of button n. You then can add items to the group using the SET method. (See the attrib- utes for a group, later in this chapter.)
The CREATE method assigns a value to the second argument, id, as follows:

Value of id Element
0-99 windows
101-9999 controls and graphic objects
10001-14999 menus
15001-19999 group

The Copy Method

The COPY method can be used to make a copy of an existing object or control, to assign to the copy a new ID. The new ID is returned in values(1). Even if the original object or control is visible, the new copy will not be shown until the programmer uses the SHOW method with it.

For example, if pbid is the ID number of an existing push button, then

CALL Object (OBJM_COPY, pbid, “”, “”, values()) LET pbidnew = values(1)
Object Subroutine

311

will generate an identical push button but with ID number pbidnew.

All attributes that make sense will be copied. For example, the new object or control will be in the same location as the original. The programmer will almost certainly want to use the SET method with the RECTANGLE attribute to specify a new location for the object or control, which can be done before showing it.

The Set and Get Methods
The SET and GET methods specify attributes parameters, or obtain the current state or value of these parame- ters.

To set an attribute, use:
CALL Object (OBJM_SET, id, attributes$, values$, values())
OBJM_SET is an integer number (see the module CONSTANT in the file TRUECTRL.TRU for details.) Id is the ID number for the object or control. Attrlist$ is a list of attribute names; if there are more than one, they are separated by vertical bars “|”. Value$ is a string variable that will pass string information in either direction. Values() is a numeric array that will pass numeric information in either direction.

To get the current value of an attribute, use:
CALL Object (OBJM_GET, id, attributes$, values$, values())
The GET method works exactly like the SET method. If an attribute has a string value, that value is passed in the string variable values$, for both the SET and the GET method. If the attribute has one or more numeric values, those values are passed in the numeric array values(), for both set and get.

For the SET method and for the GET method you can set the values of several attributes with one call to the OBJECT subroutine. Just include the names of all the attributes, separated by vertical bars “|”, in a single string. Then provide the values in the same order to the values$ string and the values() array. As an exam- ple, suppose you wished to establish a Push Button in a certain location, provide its text, and center the text.
You might use:
MAT Redim v(5) LET v(1) = left LET v(2) = right LET v(3) = bottom LET v(4) = top
LET text$ = “My Button”
LET v(5) = 1 ! The code for center justification
CALL Object (OBJM_SET, pbid, “RECTANGLE|TEXT|TEXT JUSTIFY”, text$, v())

The Show and Erase Methods
All objects and controls are invisible when they are created. The SHOW method can make them visible:
CALL Object (OBJM_SHOW, id, “”, “”, values())
where id is the ID number of the object or control that is to be made visible. Values() is ignored. To hide an object or control, use the ERASE method.
CALL Object (OBJM_ERASE, id, “”, “”, values())
This simply makes the object or control invisible; it still exists, and may be manipulated in all ways behind the scenes. Values() is ignored.

You should be aware of several special conventions. If you erase a window (i.e., make it invisible), all the controls within that window also become invisible. Thus, you don’t have to erase the controls individually. When you later show the window, all the controls in it will also become visible. In other words, the visibility of a window overrides the visibility of objects and controls in it.

Of course, during the time that a window is invisible (erased) you can erase any given object or control in it. Then
312 True BASIC Language System

when the window is made visible again, that particular object or control will remain invisible. With menus, it is nec- essary only to show or erase one single menu item to show or erase the entire menu structure.

It is not possible to erase a single menu or menu item. However, if part of the menu structure is changed, you must
“show” one of the menus or items to display the entire revised menu structure.

The Free Method
If you no longer need a window, control, or graphical object, you can eliminate it entirely with the FREE method. For example:
CALL Object (OBJM_FREE, id, “”, “”, values())
will cause the object or control to disappear and will release the ID number for possible reuse. All internal storage associated with the object or control is also released.

Using the FREE method on a window will automatically free all graphics objects and controls within that window. Freeing any one particular menu item with the negative of its ID will free the entire menu structure.

If a menu item is freed, the menu items following it will be moved up. Freeing a menu header will free it and all of its items.

Note how this terminology differs from that used in regular True BASIC statements. In this context, show means to make visible, erase means to make invisible, and free renders the object or control non-existent. Recall that the ERASE statement used with files in True BASIC removes part or all of the contents of the file, and the UNSAVE statement deletes file and its contents from the operating system.

The Select Method
The SELECT method can be applied to windows and to certain controls within windows. When applied to win- dows, the value of values(1) specifies whether the window should become merely the front-most (active) win- dow, or should be the one that responds to True BASIC INPUT and PRINT statements (target), or both.
LET v(1) = 1 ! Target (responds to input and output) LET v(1) = 2 ! Make active (move to the front)
LET v(1) = 3 ! Both
CALL Object (OBJM_SELECT, wid, “”, “”, v())
Note that for physical windows, target means the same as current. Remember also that the choice of the target (or current) physical window is under the sole control of the program, while the user may make any visible window active merely by clicking in it.
When the SELECT method is applied to controls, values$ and values() are ignored. This method is mean- ingful for push buttons, radio buttons, check boxes, edit fields, list edit buttons, and text edit controls. When applied to an edit field or a text edit control, that control becomes active and absorbs keystrokes. When applied to a push button, that button becomes selected and will be deselected when the Enter or Return key is pressed. When applied to a radio button or check box, the result will be as if the user clicked on the button or box. Generally, the effect of applying this method is the same as if the user had clicked on the window or control. In either case, a SELECT or CONTROL SELECT event will occur.
The SELECT method is ignored if applied to other types of objects or controls.

The Update Method
If the value of method is OBJM_UPDATE, the OBJECT subroutine invokes the UPDATE method to redraw the contents of the physical window whose ID is specified as id. The UPDATE method is applicable only to WINDOW objects; any attempt to invoke it for an object that is not a window will result in an error.
The purpose of the UPDATE method is to redraw a specified portion of the contents of a physical window, refresh- ing its earlier contents. The rectangular region of the window’s contents that will be updated should be specified as values(2), values(3), values(4), and values(5) representing the left, right, bottom, and top coordi-
Object Subroutine

313

nates of the update region, respectively.

These coordinates may be specified in either pixel coordinates or user coordinates, as determined by the value of values(1). If values(1) equals 0, they will be interpreted as pixel coordinates. If values(1) equals 1, they will be interpreted in the user coordinate system of the logical window that is currently in effect within the speci- fied physical window.
In general, the UPDATE method will not be necessary for immune windows, since immune windows are updated automatically by True BASIC. However, the UPDATE method can be extremely useful when working with WIN- DOW objects that have not been defined as immune.

The Sysinfo Method
The SYSINFO method is used to obtain (get) certain True BASIC system information, and to obtain (get) or change
(set) certain operating system parameters.

The attributes (value of the variable attributes$) that are possible with this method are given below. All numeric values are in pixels, and are returned in the values() numeric vector. String values are returned in the values$ string variable. The attribute names can be in upper, lower, or mixed case, but exactly one space must separate the words.

Attributes with OB JM_SYSINFO Method
—————————————————————————————————————— Attribute$ Value returned

DISPLAY SIZE The size of the entire physical screen is returned in values(1) .. values(4). Values(1) contains the leftmost pixel, which is 0. Val- ues(2) contains the rightmost pixel. Values(3) contains the bottom- most pixel. Values(4) contains the topmost pixel, which is 0. The num- ber of pixels available for use will be values(2)-values(1)+1 hori- zontally and values(4)-values(3)+1 vertically.
MACHINE The platform; one of MAC, WIN32, OS/2, or UNIX. NATIVE WID (Not implemented; for Unix only.)
PIPE IN (Not implemented; for Unix only.) PIPE OUT (Not implemented; for Unix only.) BLOCKING (Not implemented; for Unix only.) PIPE ID (Not implemented; for Unix only.) BOX KEEP ID (Not implemented; for Unix only.) NO MENUS (Not implemented; for Unix only.)
STATIC TEXT HEIGHT The height of a static text field is returned in values(1) BUTTON HEIGHT The height of a push button is returned in values(1) EDIT TEXT HEIGHT The height of an edit text field is returned in values(1)
CHECK BOX HEIGHT The height (and width) of a check box is returned in values(1) HORZ SBAR HEIGHT The height of the horizontal scroll bar is returned in values(1) RADIOBUTTON HEIGHT The height of a radio button field is returned in values(1) VERT SBAR WIDTH The width of a vertical scroll bar is returned in values(1)
ENV See below.
DEFAULT BACKGROUND COLOR values(1) .. values(3) are the r-, g-, and b- values, respectively, of the background color
VERSION The XVT version the current implementation is based upon
314 True BASIC Language System

KEY CODES See below.
MENU HEIGHT The height of the menu bar is returned in values(1).
APPLICATION NAME Value$ will contain the complete application name, including the path- name. This is ignored by True BASIC; it is only for the convenience of the programmer.
FONTS AVAILABLE The names of the available fonts are returned in value$, separated by vertical bars.
LANGUAGE “US English”or “Japanese” is returned in value$ GRAB CURSOR See below.
TITLE BAR HEIGHT The height of the title bar, in pixels, is returned in values(1). BORDER WIDTH The width of a full border, in pixels, is returned in values(1). BORDER HEIGHT The height of a full border, in pixels, is returned in values(1). DOUBLE BORDER WIDTH The width of a double border, in pixels, is returned in values(1). DOUBLE BORDER HEIGHT The height of a double border, in pixels, is returned in values(1). RESIZE BORDER WIDTH The width of a full border with resize box is returned in values(1). RESIZE BORDER HEIGHT The height of a full border with resize box is returned in values(1). PREFFOLDER (Macintosh only) The system-defined preferences folder is returned in
value$.
TMP (Macintosh only) The system-defined temporary folder is returned in
value$.
——————————————————————————————————————
W You can both set and get the values of the following attribute, but on the Windows platform only:
KEY CODES

To set the key code conventions, set values(1)=1 and values(2) to 0 (for cross-platform compatible codes; the default) or to 1 (for True BASIC for DOS compatible codes.) To get the key code conventions, set values(1)=0. Upon return, values(2)=0 if cross-platform codes are in effect, and values(2)=1 if DOS 4.0 compatible codes are in effect. Note that the cross-platform-compatible codes may not correspond to the codes on any particular plat- form. Some typical values are:

F1 .. F15 331 .. 345 up arrow 301
down arrow 302 right arrow 303 left arrow 304 page up 305 page down 306 home 309 end 310

These may not be available on all platforms. Also, some platforms may offer additional key codes. You may have to write a simple program using GET KEY key to find out.

The attribute, ENV, is used to obtain or change certain operating system parameters. For example, to get the
PATH parameter, you might use:

LET parameter$ = “PATH”
LET values(1) = 0 ! Get
Object Subroutine

315

CALL Object (OBJM_SYSINFO, 0, “ENV”, parameter$, values()) PRINT parameter$
You might see something like “C:\;C:\WINDOWS;C:\TBSILVER”.

Note that the fourth argument must be a string variable as it is used as both an input and an output parameter. If there is an error, the null string will be returned.

To set the PATH parameter, you might use something like this:

LET parameter$ = “PATH= .... “ LET values(1) = 1 ! Set
CALL Object (OBJM_SYSINFO, 0, “ENV”, parameter$, values())
It may not be possible to set environment variables using this method on all systems.
M The Macintosh operating system does not use environment variables. However, you can obtain the path
names of the system-defined preferences folder and the system-defined temporary folder as follows:
LET v$ = "PREFOLDER" LET v(1) = 0
CALL Object (OBJM_SYSINFO, 0, "ENV". v$, v)

Upon return, v$ = “PREFOLDER|”, give it a stop code of 3.

KEY EVENTS If values(1)=0 (default), all key events, except those specified as TRAP CHARs, will be absorbed by the text edit control, and will not be returned by the Sys_Event subrou- tine. If values(1)=1, then all key events will be returned by the Sys_Event subrou- tine, as well as being acted on by the text edit control.

MOUSE EVENTS If values(1)=0 (default), all mouse events within the text edit control will be absorbed by the text edit control, and not returned by the Sys_Event subroutine. If val- ues(1)=1, mouse events will be acted on by the text edit control and also returned by the Sys_Event subroutine.

Text Editor Auxiliary Attributes
VSCROLL Values(1) = the ID number of an attached vertical scroll bar, if any. True BASIC does not use this value; it is provided only for the convenience of the programmer.

HSCROLL Values(1) = the ID number of an attached horizontal scroll bar, if any. True BASIC
does not use this value; it is provided only for the convenience of the programmer.

Exceptions
These exceptions apply in general.
Unknown or invalid object ID. (-11220) Cannot reference a freed object ID. (-11221) Attribute not used for specified object. (-11223) Unknown or invalid group method. (-11224) Unknown or invalid attribute in SET/GET. (-11225) Unknown or invalid font name. (-11226)
Unknown in invalid font style. (-11227)
Font size must be greater than zero. (-11228) Can’t set FONT METRICS. (-11249)
Object ID out of range. (-11236) Unknown window method. (-11237)
336 True BASIC Language System

Unknown object method. (-11238) Unable to SHOW window. (-11239)
Unknown or invalid object type specification in CREATE. (-11240) Too many EXIT CHARS for Edit Field. (-11241)
Can’t set ACTIVE until object is visible. (-11242) Color must be >= 0. (-11251)
Unknown or invalid menu item type specification. (-11254) Can’t check a menu separator. (-11255)
Menu separators are not checkable. (-11256) Unknown or invalid control object type. (-11257) Unknown or invalid graphic object type. (-11258) Unknown or invalid window object type. (-11259) Unknown or invalid group object type. (-11260) Can’t check a menubar item. (-11261)
Can’t make menubar item a separator. (-11262) Menu parent incorrect for menu type. (-11263) Can’t SELECT an unSHOWn window. (-11264) Unknown or invalid brush pattern. (-11265) Unknown or invalid pen pattern. (-11266) RECTANGLE minimum = maximum. (-11271) No Help File opened. (-11272)
Not enough values for attribute list in SET/GET. (-11273)

These exceptions apply only to the Text Edit control.
TextEdit method passed to non-TextEdit object. (-11229) Can’t SUSPEND TextEdit object when not visible. (-11230) Can’t RESUME TextEdit object when not visible. (-11231) Error adding paragraph. (-11232)
Paragraph number is too large. (-11233) Error deleting paragraph. (-11234)
Error appending paragraph. (-11235) Can’t set NUM LINES. (-11243)
Can’t set NUM PARS. (-11244) Can’t set NUM CHARS. (-11245) Can’t set LINES IN PAR. (-11246) Can’t set MAX WIDTH. (-11248)
Too many trap chars for TextEdit. (-11250) Paragraph out of range for GET LINE. (-11252) Line out of range for GET LINE. (-11253)