Release 10.1A: OpenEdge Development:
Progress Dynamics Advanced Development

> ## SmartObject SupportedLinks and the addLink procedure

> There are standard links associated with each SmartObject class. The `SupportedLinks` ADM property for the class names these links. Each link is defined with a set of ADM property values and functions to support getting and setting those properties and are described in this section.

> SmartLinks are established when a SmartObject is created at run time, when the `createobjects` procedure runs `addLink`. All these supporting elements are already present for all of the standard shipped SmartObjects. This description is here to help developers understand how the ADM link mechanism works and how it can be extended for new SmartObject types.

> SmartLinks are typically established when you define links in the Container Builder while assembling SmartWindows or other containers. When you define a template container in the Container Builder, you also define links between the objects in the template. When you define a specific window using that template, you can add additional links. For example, you can add a link that connects objects on different pages that you assemble. For each link, a record is added to the Repository to define the link. At run time, the dynamic window procedure runs `addLink` to create those links, as shown:

>     PROCEDURE addLink:
>       Parameters:
>         (INPUT phSource /* HANDLE – Source procedure handle */,
>          INPUT pcLink   /* CHARACTER – Link name */,
>          INPUT phTarget /* HANDLE – Target procedure handle */).
>       Candidate for: calling
>         If you need to create your own additional links at runtime based on
>     application requirements, you do this by running addLink.

> The `addLink` procedure requires that three basic properties and supporting functions for those properties be predefined in the SmartObject support files (its include files and super procedures). In the source procedure for the link, there must be a property that holds the handle or handles of the targets for each supported link. In the target for the link, there must be a property that holds the handle or handles of the link source for each supported link. These source and target procedures use functions that set property values in linked SmartObjects or return the handles of those linked objects when needed. At startup time, `addLink` sets these properties to the appropriate procedure handles. The names of the properties must be `<LinkType>``Target` in the source SmartObject, and `<LinkType>``Source` in the target object.

> In addition, `addLink` requires that a property must be in the target SmartObject listing the events that the target object wants to be notified of when those events are published by the source. The name of this property must be `<LinkType>``SourceEvents`, and must be a comma-separated list of event names. If the source of the link also wants to be notified of events in the target, then there must be a `<LinkType>``TargetEvents` property in the source SmartObject.

> The `addLink` procedure looks at the `propertyType` of the `<LinkType>``Target` and `<LinkType>``Source` properties (which returns the data-type of the property) to determine whether the link supports a single object or multiple objects. Typically a SmartLink supports only a single source, but can support more than one target. For example, a container can contain many other SmartObjects, which are its `Container-Targets`, but each of those objects has a single `Container-Source`. Likewise, a SmartObject, such as a SmartDataObject or SmartDataViewer, can have only a single `Data-Source`, but an SDO can have multiple `Data-Targets`. Additional user-defined SmartLinks for new SmartObjects can be defined to support single or multiple sources and single or multiple targets. This is done in the definition of the properties where the handles are stored.

> If the data type of the property is `HANDLE` (which is typically the case for the `<LinkType>``Source` property), then this tells `addLink` that only a single object is permitted on that end of the link, and it runs the `set``<LinkType>``Source` function to assign the property value to the source procedure handle.

> If the data type of the property is `CHARACTER` (which is typically the case for the `<LinkType>``Target` property), then this tells addLink that multiple objects are permitted on that end of the link, and it runs the `modifyListProperty` procedure to add the target procedure handle to the list of handles of objects that are targets of that link (or the source if the source supports multiple SmartObjects). See the "Special functions that manage properties" section for a description of `propertyType` and `modifyListProperty`.

> The `addLink` procedure then looks at the `<LinkType>``SourceEvents` property in the target SmartObject, and subscribes the target procedure to each of those events in the source procedure handle. This causes the event procedure of the same name as the event to be run in the target each time the source publishes that event. In some cases the source of a link also receives messages from the target. In this case, there is also a `<LinkType>``TargetEvents` property in the source SmartObject, and `addLink` subscribes the source to those events in the target.

> The lists of the events to which source events and target events of each standard supported link are subscribed are in a series of tables in the SmartLinks chapter of the ProgressVersion 9 ADM documentation.

> To look at a specific example, examine the `Container` link. This link is not on the list of `SupportedLinks` for any SmartObject because every SmartObject can be a `Container-Target`, and every SmartContainer™ can be a `Container-Source`, so this link is created automatically when a SmartContainer is run and its contents are started (the `addLink` call to establish the `Container` link is in `constructObject`).

> Because every SmartObject can be a `Container-Target`, the properties that define the `source` handle and events are in the property include file that all SmartObjectss share, smrtprop.i. They are, of course, also defined in the Repository. The `ContainerSource` property is defined as data type `HANDLE`, to indicate that there can be only a single `Container-Source` for a SmartObject. The `ContainerSourceEvents` property lists the events to which each SmartObject is subscribed in its parent container. This list includes `initializeObject`, `hideObject`, `viewObject`, `destroyObject`, `enableObject`, and `confirmExit`. When a container is initialized, for example, it publishes `initializeObject`, which causes each of its child SmartObjects to be initialized as they receive that event and run their own `initializeObject` procedure. The supporting functions `getContainerTarget`, `setContainerTarget`, `getContainerTargetEvents,` and `setContainerTargetEvents` are defined in `smart.p`, the super procedure used by all SmartObjects.

> Only a container can be a `Container-Source`, so the properties describing the target are defined in the property include file for containers, cntnprop.i, and also in the Repository. There is a `ContainerTarget` property (of type `CHARACTER`), and a `ContainerTargetEvents` property, because each container subscribes to a single event in each of its child objects, `exitObject`. The super procedure for containers, `containr.p`, contains the `get` and `set` functions for these properties.

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