Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

> ## Useful object handles

> The properties described in this section return useful object handles to you.

> ##### ContainerHandle

> This `HANDLE` property, available for all SmartObjects, is only meaningful for objects that have a window or frame. For a frame-based object, such as a browser or viewer, it returns the frame handle. For a window-based object, such as a SmartWindow, it returns the window handle. Use this handle when you must query or manipulate the attributes of the container widget itself.

> ##### BrowseHandle

> This `HANDLE` property returns the browser widget handle for a SmartBrowser. Use this handle when you must query or manipulate the attributes of the browse itself.

> ##### BufferHandles and QueryHandle

> These two properties return handles from the database query that is used to populate an SDO. The `BufferHandles` `CHARACTER` property is a comma-separated list of the handles of the database record buffers the framework uses to populate the SDO temp-table.

> The `QueryHandle` `HANDLE` property is the handle of the database query. Note that these handles are the database object handles, not SDO temp-table or buffer handles. They are valid only on the server side of a divided SDO, and should be used only in cases where your code must reference the database data as the framework loads it into the temp-table.

> ##### QueryRowObject

> This `HANDLE` property returns the buffer handle to the SDO’s temp-table buffer (the `RowObject` buffer in other words) that holds the data values for the currently selected row in a browser. This can be useful when you must query those values within the `ROW-DISPLAY` trigger for the browser, for example. The `SCREEN-VALUEs` of the individual cells cannot be queried within this 4GL event, so in order to write logic that reacts to a cell’s value, by changing the background color or some other attribute of the cell or the row, you must be able to refer back to the underlying data buffer and its fields. See Chapter 1 "Writing Super Procedures for Progress Dynamics Objects" for more information.

> Note that the `WIDGET-HANDLE` is implemented to hide this complexity.

> As an example, look at this code from the widgetValue function that is part of the proposed client-side API for retrieving and setting values in dynamic objects from custom super procedures. The variable `hField` holds the handle to a field from the `FieldHandles` list, as shown:

>     IF CAN-QUERY(hField, "FILE-NAME") THEN
>               /* This is a SmartDataField. Return its DataValue property.
>                  Note that this is the underlying "key" value that is meaningful
>                  to the code, not the "DisplayValue" shown to the user. */
>               {get DataValue cValue hField}.
>             ELSE IF CAN-QUERY(hField, "SCREEN-VALUE") THEN
>                   cValue = hField:SCREEN-VALUE.
>             ELSE DO:
>                 {get QueryRowObject hBuffer} NO-ERROR.
>                 IF VALID-HANDLE(hBuffer) THEN
>                     ASSIGN hField = hBuffer:BUFFER-FIELD(cField)
>                            cValue = STRING(hField:BUFFER-VALUE) NO-ERROR.
>             END.  /* END ELSE DO IF NOT CAN-QUERY SCREEN-VALUE (Browse) */

Copyright © 2005 Progress Software Corporation www.progress.com Voice: (781) 280-4000 Fax: (781) 280-4095