Accessing handle attributes and methods

A handle attribute is a value that defines a visible, functional, and other characteristic of an ABL handle-based object. System handles also have attributes that describe and control certain handle-based object or system states. Attributes can be readable, writeable, or both. Readable means that your code can assign the value of the attribute to a variable or reference its value in an expression. Writeable means that your code can change the value of an attribute and thereby change the associated characteristic of the object or system state. Whether or not an attribute is readable or writeable depends on a number of factors (for example, the widget type, system handle type, widget realization, etc.).

A handle method is a specialized function associated with an ABL handle-based object that performs an action on the object, or alters the behavior of the object. Some system handles also have methods that affect certain widget and system behaviors. All methods return a value and some methods require parameters. The return value usually is a logical value specifying whether or not the execution of the method was successful. However, some methods return other types of information.

Handle-based references

You must access all handle attributes and methods with reference to a handle-based object or its handle using this general syntax:

Syntax
`handle-based-reference` : `attribute-or-method-access` [ IN `container-widget-name` ]

Syntax
{ `object-name-reference` \| `handle-reference` }

An object-name-reference is a name reference to a static handle-based object, such as the defined name of a frame or window, or of another static handle-based object, such as a temp-table or buffer. For more information, see the "Object name references" section. A handle-reference can be a handle value that references any handle-based object (static or dynamic), or it can be a system handle. For more information, see the "Handle references" section.

The attribute-or-method-access identifies a given attribute or method associated with the specified handle-based-reference.

The container-widget-name is a name reference to a static container widget for the static widget referenced by object-name-reference. You need it only if the static widget reference is ambiguous.

The following sections provide more information on the object-name-reference and handle-reference options.

Object name references

An object-name-reference can have the following syntax, depending on the static handle-based object:

Syntax
[ `object-type` ] `object-name`

The object-type is the type of the static handle-based object specified in the DEFINE statement for the handle-based object, such as FRAME in the DEFINE FRAME statement or TEMP-TABLE in the DEFINE TEMP-TABLE statement. For a data representation widget associated with a field or variable, object-type is the widget specified using the VIEW-AS phrase, such as COMBO-BOX for VIEW-AS COMBO-BOX.

The object-name is the name that you specify for the static handle-based object using the DEFINE statement for the handle-based object. For a data representation widget, it is the name of the field or variable associated with the widget.

For static frame fields, you only need to provide the object-name (field or variable name) to reference the associated widget, and ABL looks for its data representation widget in a frame. However, for most other static handle-based objects, you must qualify the object-name with the object-type, for example, BUFFER Customer, QUERY qCust, or TEMP-TABLE ttCust.

For example, in this code fragment, the handle to a frame field (dDate) and the handle to a buffer object (bCust) are both returned and assigned to handle variables using the HANDLE attribute of each handle-based object:

DEFINE VARIABLE hField AS HANDLE NO-UNDO. DEFINE VARIABLE hObject AS HANDLE NO-UNDO. DEFINE VARIABLE `dDate` AS DATE NO-UNDO VIEW-AS FILL-IN. DEFINE `BUFFER bCust` FOR Customer. DEFINE FRAME AFrame `dDate` bCust.Name. hField = `dDate`:HANDLE `/* Widget name found in frame AFrame */`. hObject = `BUFFER bCust`:HANDLE.

DEFINE VARIABLE hField  AS HANDLE NO-UNDO. 
DEFINE VARIABLE hObject AS HANDLE NO-UNDO. 
DEFINE VARIABLE dDate   AS DATE   NO-UNDO VIEW-AS FILL-IN. 
DEFINE BUFFER bCust FOR Customer. 
DEFINE FRAME AFrame 
  dDate 
  bCust.Name. 
hField  = dDate:HANDLE /* Widget name found in frame AFrame */. 
hObject = BUFFER bCust:HANDLE.

Handle references

A handle-reference allows you to directly reference a handle-based object using a handle value. You can set this handle value by assigning the HANDLE attribute of a static handle-based object (see the "Object name references" section), by creating a dynamic handle-based object, by assigning the handle value provided by a system handle, or from any other source of handle values, such as method or function return values. Examples of handle references include CURRENT-WINDOW and BUFFER bCust:HANDLE (from the previous example).

You can access the handle to a static handle-based object using a HANDLE data type (field or variable) that you set to the value of the HANDLE attribute on the static object name reference.

You can access the handle for a dynamic handle-based object through a HANDLE data type (field or variable) whose value is initially set using the CREATE statement for the specified handle-based object. You can also access the handle value to some dynamic handle-based objects, as in the case of a procedure object, that you initially obtain using an appropriate RUN statement or system handle.

The HANDLE attribute of a given object handle can also provide a valid handle value that references the same handle-based object as the given object handle, itself. For example, the following assignment statements set both hProc1 and hProc2 to the same running procedure object using the THIS-PROCEDURE system handle and its HANDLE attribute, and the MESSAGE statement displays the FILE-NAME attribute for the same procedure object:

DEFINE VARIABLE hProc1 AS HANDLE NO-UNDO. DEFINE VARIABLE hProc2 AS HANDLE NO-UNDO. /* hProc1 equals hProc2 */ hProc1 = `THIS-PROCEDURE`. hProc2 = `THIS-PROCEDURE:HANDLE`. MESSAGE `hProc1`:FILE-NAME SKIP `hProc2`:FILE-NAME VIEW-AS ALERT-BOX.

DEFINE VARIABLE hProc1 AS HANDLE NO-UNDO. 
DEFINE VARIABLE hProc2 AS HANDLE NO-UNDO. 
/* hProc1 equals hProc2 */ 
hProc1 = THIS-PROCEDURE. 
hProc2 = THIS-PROCEDURE:HANDLE. 
MESSAGE hProc1:FILE-NAME SKIP hProc2:FILE-NAME VIEW-AS ALERT-BOX.

Handle attribute access

Syntax
`widget-reference` : `attribute-name` [ IN `container-widget-name` ]

The widget-reference is a reference to a handle-based object (see the "Handle-based references" section). The attribute-name specifies the ABL-defined name of a handle-based object attribute. The container-widget-name is a name reference to a static container for a static widget. You need it only if the static widget reference is ambiguous without it, as shown in the following example. For more information on accessing attributes, see the "Accessing handle attributes and methods" section.

To read an attribute value, assign the attribute value to a field or variable of a compatible data type, pass the attribute as an input parameter to some procedure, function, or method, or include the attribute in an expression. To write an attribute value, assign the value to the attribute or pass the attribute as an output parameter to some procedure, function, or method.

The following example repositions a selection list (Select-1) to another row in the specified frame (SelectFrameA):

DEFINE VARIABLE Select-1 AS CHARACTER NO-UNDO VIEW-AS SELECTION-LIST SIZE 50.0 BY 10.0. DEFINE FRAME SelectFrameA Select-1. DEFINE FRAME SelectFrameB Select-1. Select-1:ROW IN FRAME SelectFrameA = Select-1:ROW + 2.

DEFINE VARIABLE Select-1 AS CHARACTER NO-UNDO 
  VIEW-AS SELECTION-LIST SIZE 50.0 BY 10.0. 
DEFINE FRAME SelectFrameA Select-1. 
DEFINE FRAME SelectFrameB Select-1. 
Select-1:ROW IN FRAME SelectFrameA = Select-1:ROW + 2.

Note that ABL assumes that the second reference to Select-1 within the same assignment statement is in the same frame that is specified for the first reference.

Handle method calls

Syntax
`widget-reference` : `method-name` ( [ `parameter-list` ] ) [ IN `container-widget-name` ]

The widget-reference is a reference to a handle-based object (see the "Handle-based references" section). The method-name specifies the ABL-defined name of a handle method, and parameter-list specifies any parameter list for the method. The container-widget-name is a name reference to a static container for a static widget. You need it only if the static widget reference is ambiguous, as shown in the following example. To execute a handle method, you can assign the return value directly to a variable, include the method in an expression, or directly invoke the method as a statement (terminated with a period), ignoring its return value. For more information on calling handle methods, see the "Accessing handle attributes and methods" section.

The following example executes the ADD-FIRST( ) method for a selection list (Select-1) in two different ways—assigning the return value to a logical variable (methRtn) and invoking it directly, without assigning a value:

DEFINE VARIABLE Select-1 AS CHARACTER NO-UNDO VIEW-AS SELECTION-LIST SIZE 50.0 BY 10.0. DEFINE VARIABLE methRtn AS LOGICAL NO-UNDO. DEFINE FRAME SelectFrameA Select-1. DEFINE FRAME SelectFrameB Select-1. methRtn = `Select-1:ADD-FIRST("BLUE")` IN FRAME SelectFrameA. `Select-1:ADD-FIRST("GREEN")` IN FRAME SelectFrameB.

DEFINE VARIABLE Select-1 AS CHARACTER NO-UNDO 
  VIEW-AS SELECTION-LIST SIZE 50.0 BY 10.0. 
DEFINE VARIABLE methRtn  AS LOGICAL   NO-UNDO. 
DEFINE FRAME SelectFrameA Select-1. 
DEFINE FRAME SelectFrameB Select-1. 
methRtn = Select-1:ADD-FIRST("BLUE") IN FRAME SelectFrameA.
Select-1:ADD-FIRST("GREEN") IN FRAME SelectFrameB.

Error handling for handle method calls

Traditionally, ABL handle methods treat errors as warnings and do not raise the ERROR condition. Therefore, statements calling handle methods should use the NO-ERROR option to capture error messages in the ERROR-STATUS system handle. If an error occurs in the handle method and NO-ERROR is in effect, the ERROR-STATUS:ERROR attribute is not set, but you can test to see if ERROR-STATUS:NUM-MESSAGES is greater than zero.

However, if a handle method error occurs in a block that contains a CATCH end block, the AVM does raise the ERROR condition. The error then needs to be handled by a CATCH block, with an appropriate ON ERROR phrase or ROUTINE-LEVEL ON ERROR UNDO, THROW statement to override the default error handling for the block type, if necessary.

When a statement contains the NO-ERROR option and resides in a block with a CATCH end block, the NO-ERROR option takes precedence over the CATCH block. That is, an error raised on the statement with the NO-ERROR option will not be handled by a compatible CATCH end block. The error is redirected to the ERROR-STATUS system handle as normal.

If an error object is thrown to a statement that includes the NO-ERROR option, the information and messages in the error object will be used to set the ERROR-STATUS system handle. This interoperability feature is important for those integrating code that uses the traditional NO-ERROR technique with the newer, structured error handling that features error objects and CATCH end blocks.

Chained handle references

Syntax
`widget-reference` : `attribute-or-method-reference` [ : `attribute-or-method-reference` ] ...

A chained handle reference allows you to reference multiple object handles in a series that terminates with a final handle attribute or method. The widget-reference specifies a handle-based object (see the "Handle-based references" section). The attribute-or-method-reference can be any appropriate attribute or method of the referenced handle-based object immediately preceding it. When you use this syntax, the middle handle attributes and methods must return a data type of HANDLE in order to allow an additional handle reference in the chain, until the final handle attribute or method is accessed, which can return any ABL data type.


DEFINE VARIABLE hBuff AS HANDLE NO-UNDO. CREATE BUFFER hBuff FOR TABLE "Customer". MESSAGE `hBuff:BUFFER-FIELD(3):NAME`.

Widget color, font, and measurement values

Some entries in this section refer to color and font values (for example, BGCOLOR and FONT). These values are color and font numbers established for your system. Some entries in this section also refer to character units, an ABL unit of measure for specifying portable widget sizes and positions in graphical environments. For more information on color and font values, or character units and their relationship to pixels, see OpenEdge Development: Programming Interfaces.

Note: When you assign a decimal value to an attribute representing a measurement in character units, ABL automatically rounds the assigned value to the nearest decimal value that corresponds to whole pixel units.