Handles

A handle is a reference to an object, such as a synchronous component instance, entity, occurrence, or field. Handles can be used to call operations on the referenced object, or to pass these objects as variables and parameters.

For component instances of forms, reports, and services, handles provide an alternative to the activate statement when calling component operations. For the handles are the only way in which you can call their operations.

Note:  Handles cannot be use for asynchronous communication. They cannot be used for components that are started asynchronously, and they cannot be used for dynamic or static server pages. These must be activated using the component instance name.

You can obtain handles using ProcScript functions, and call operations on the referenced object using the -> operator. For example, the following instruction obtains a handle to the current occurrence of the ADDRESS entity and calls an occurrence operation called setColor:

$occhandle(ADDRESS)->setColor("red")

The handle data type makes it possible to assign handles to parameters and variables (local, component, and global), as well as to non-database fields.

Component Instance Handles

The newinstance command provides an option for using a handle when creating the component instance, instead of an instance name.

In this case, the component instance uses a reference count mechanism to control its life span—when there are no more handles referencing the component instance (the reference count is set to 0), it is automatically deleted. In contrast, a component instance that has been created using an instance name (either by newinstance or activate) must be explicitly deleted.

; A trigger
variables
  handle hOrder
endvariables

newinstance "ORDER",hOrders
hOrder->newOrder()
; end

For more information, see Reference Counting .

Collection and Occurrence Handles

Collection and occurrence handles enable you to manipulate entity occurrences, either as collection or individually. They make it possible for one component to access an entity and occurrences of another component.

The primary way to do so is to define operations in the Collection Operations and Occurrence Operations ProcScript containers, and then call the operations using the corresponding handle. Uniface also provides some built-in operations for occurrence selection.

The following ProcScript instructions are available for using with entity collection and occurrences:

  • $collhandle—get a handle to a collection of entity occurrences
  • $occhandle—get a handle to the current occurrence of the specified entity
  • $occhandle(Entity)->$selected=1 | 0—add or remove the current occurrence in the collection of selected occurrences
  • $collhandle(Entity)->$selectedoccs—returns a Struct in which each member is a handle to a selected occurrence
  • $collhandle(Entity)->$clearselection—clear the selection of all occurrences in the collection

You can use an entity with an field of data type handle to act as a reference collection, by filling multiple occurrences with handles and by exposing a set of collection operations.

Field Handles

Although fields do not have operations, some widgets do. The only way to call these widget operations is to obtain a field handle (using $fieldhandle) and invoke the widget operations using $widgetoperation.

For example, the following ProcScript statement calls the loadURL widget operation on the F_HTML field:

$fieldhandle(F_HTML)->$widgetoperation("loadURL","http://www.uniface.com/")

OCX Handles

To interact with an ActiveX control, you need to use a dedicated OCX handle to activate the extended triggers of the control it contains. For example, the following code calls extended triggers for a media player control to set some of its properties:

;$vOCXHandle$ is a component variable of type handle
$vOCXHandle$ = $ocxhandle("OCX_FLD")
$vOCXHandle$->set_AutoStart("true")
$vOCXHandle$->SetWantMouseEvents("true")
$vOCXHandle$->setWantErrors("true")
$vOCXHandle$->get_AutoStart(CHK_AUTOPLAY)

Related Topics