Handle Reference

This section contains reference entries that describe the ABL handle-based objects (other than widgets). Handle-based objects represent built-in object types in ABL that you can reference using object handles.

These objects include widgets, which encapsulate user interface capabilities, and other object types that provide access to a variety of ABL session capabilities. Object handles are essentially addresses that provide access to handle-based objects in memory. These handles allow you to access attributes and methods that ABL defines for each object that you can use to interact with an object’s state and behavior.

Note:

Handle-based objects are conceptually analogous to but different from class-based objects. The types and capabilities of handle-based objects are defined entirely by ABL. However class-based objects represent instances of classes whose capabilities you can define as user-defined data types. For more information on class-based objects, see the CLASS statement reference entry.

You can define static or create dynamic instances of many handle-based object types using appropriate DEFINE and CREATE statements. You can reference a static instance by the defined object name or its handle, and you can reference a dynamic instance only by its handle. ABL also automatically creates instances of certain other handle-based object types in various ways, including system objects that you can access using an appropriate keyword-defined system handle.

Thus, ABL makes object handles available in two ways:

Directly, as system handle values. A system handle is an ABL keyword that evaluates to an object handle whose object type is implied by the keyword. For example, the CURRENT-WINDOW system handle is a handle to a particular window widget. To access the attributes and methods of a system handle, you can use the keyword directly, or you can assign the keyword value to a HANDLE variable and use the variable to reference the attributes and methods:

 

DEFINE VARIABLE hHandle AS HANDLE NO-UNDO.   hHandle = THIS-PROCEDURE.          /* Procedure object handle */   DISPLAY THIS-PROCEDURE:GET-SIGNATURE(""). /* Displays the same */ DISPLAY hHandle:GET-SIGNATURE(""). /* Signature as this statement. */

Indirectly, as values output from various CREATE and other ABL statements, including other handle attributes and methods. You can access the attributes and methods of any object by assigning its handle to a HANDLE variable, which can hold handle values of any type. You can then use this variable to reference the attributes and methods of the object:

 

DEFINE VARIABLE hHandle AS HANDLE NO-UNDO.   CREATE SERVER hHandle. /* Create a handle to a server object */ hHandle:CONNECT(). /* Execute a server object method */

The reference entries throughout this section include both system handles and handles for object types not necessarily referenced using system handles. Each system handle is listed by its keyword (all upper case, for example: SESSION system handle), and each handle for other object types is listed by its object type (upper and lower case, for example: Server object handle).

Each entry lists the attributes and methods supported by the handle or refers you to a more general entry with the same list. For example, the attributes and methods of the CURRENT-WINDOW system handle appear under the WINDOW widget entry. Widgets share a common set of user interface capabilities as well as capabilities unique to each widget type. For a list of the attributes and methods supported by each widget, see the “Widget Reference” section.

For more information on how to use the list attributes and methods for all handle-based object types, see the “Handle Attributes and Methods Reference” section, which includes a complete reference entry for each attribute and method.

Note:

You may consider an object handle to be supported for all interfaces, on all operating systems, and for SpeedScript unless otherwise indicated in the reference entry.

The following descriptions refer to both compile-time and run-time behavior, features that the language generally supports and determines at compile time and actions directed by using these features at run time. When describing compile-time features or actions, this section references ABL or the ABL compiler. When describing ABL-directed actions taken at run time, this section references the ABL Virtual Machine (AVM).