skip to main content
OpenEdge Development: ADM and SmartObjects
SmartObject Interactions : General structure of a SmartObject
 
General structure of a SmartObject
This section discusses the following topics:
*Directory and file structure
*Support include files
*Super procedures
*Property and prototype include files
Directory and file structure
The ADM directory structure includes:
*Primary include files for SmartObjects and their super procedures, located in %DLC%\src\adm2 (Windows) or $DLC/src/adm2 (UNIX)
*Templates, located in %DLC%\src\adm2\template (Windows) or $DLC/src/adm2/template (UNIX)
*Support procedures, located in %DLC%\src\adm2\support and compiled into %DLC%\gui\adm2\support (Windows), or located in $DLC/src/adm2/support and compiled into $DLC/gui/adm2/support (UNIX)
*Super procedures and prebuilt objects such as the SmartPanels and SmartFolders, also located in %DLC%\src\adm2 and compiled into %DLC%\gui\adm2 (Windows), or located in $DLC/src/adm2/support and compiled into $DLC/gui/adm2/support (UNIX)
Many SmartObjects are constructed from template (.w) files. These templates contain a minimum of executable code to minimize maintenance problems if general changes need to be made to a class of objects after many specific masters are already built from a template. Some SmartObjects do not have template files; they have only master files that can be customized at design time.
Support include files
As noted in Chapter 1, “Overview,” a SmartObject template generally includes a single support include file: the primary include file for the class on which the SmartObject is based. This include file has the same name as the template (but a different extension). For example, the SmartDataViewer template viewer.w includes the primary include file viewer.i. A primary include file such as viewer.i does not directly contain most of the code needed to support the SmartObject. It contains only those program elements required to compile a master built from that template:
*Any variable or other definitions needed by all masters of that type
*A reference to the next support include file up the chain (for example, a SmartDataViewer is a visual object that displays data, so it includes datavis.i; if there is no other intermediate object above this type, it includes smart.i), and its own property include file, which defines those properties stored in the ADMProps temp-table for the object
*Initialization code in the main block for this object type’s properties and any other generic object startup code
*Any routine that requires compile‑time resolution of preprocessors or for some other reason must be part of the master’s compilation unit (.r file)
Super procedures
All support code for an object type, other than the code in its primary include file, is in a separately compiled super procedure built as a structured .p file. For example, the super procedure for SmartDataViewers is viewer.p.
During startup, the .p file is run and established as a super procedure for each of its SmartObjects running in that session. Its routines use TARGET-PROCEDURE to get the procedure handle of the appropriate SmartObject and can then get property values from that procedure to get handles or other data needed to act on behalf of the SmartObject. These SmartObjects can run any internal procedure or function implemented in one of the object’s super procedures as if it were implemented in the SmartObject itself. This allows these separately compiled procedure objects to do the following:
*Support standard behavior for all SmartObjects of a given type running in a Progress session.
*Enable the customization or overriding of these procedures and functions in individual SmartObjects.
For an overview of super procedures, see OpenEdge® Getting Started: ABL Essentials. For descriptions of super procedures and TARGET-PROCEDURE, see OpenEdge Development: ABL Reference.
Figure 5–1 illustrates this relationship.
Figure 5–1: Super procedures and master interactions
The smart.p code uses TARGET-PROCEDURE to reference the two masters. For master1.w, the xyz procedure in the smart.p super procedure is run because master1.w does not have its own xyz procedure. For master2.w, its own xyz procedure is run and then, because it executes RUN SUPER, the xyz procedure in smart.p also is run.
As this example illustrates, using super procedures to provide most of the support code for a SmartObject provides these advantages:
*Encapsulation of routines into a super procedure where they are accessible from all SmartObjects associated with that super procedure.
*The ability to use the same procedure or function name in multiple layers when defining the behavior for a particular SmartObject.
Each super procedure must define a getpropname function for each object property that can be retrieved from objects of that type and a setpropname function for each settable property. For more information on these properties, see the “Get and set functions for object properties” section.
Super procedures are not SmartObjects in themselves and are not directly seen or manipulated in the AppBuilder during application assembly. They do not have SmartLinks, nor do they have properties of their own.
The super procedures for SmartObjects are designed to be shared and stateless. This means a given super procedure such as viewer.p is run only once in a session. No matter how many SmartDataViewers there are, each SmartDataViewer designates the same instance of viewer.p as its super procedure. This means whenever a routine is invoked in viewer.p as a super procedure, it queries whatever properties of its TARGET-PROCEDURE are needed for it to act. The next routine invoked in viewer.p is not assumed to come from the same TARGET-PROCEDURE.
Property and prototype include files
The property include file for a SmartObject defines its basic properties, references the its prototype file, and, if necessary, starts its super procedure. It also can define instance properties and the instance properties dialog box and may reference certain custom class files as needed. For more information on properties, see the “ADM properties” section.
Prototype include files
The prototype include file for a SmartObject defines prototypes for all internal entries (functions and internal procedures) of the super procedure for the class.
SmartObject file relationships
Within the overall SmartObject class hierarchy, the class files described in the “General structure of a SmartObject” section relate to other files of the same type in certain very specific ways. These relationships establish what characteristics and properties a specific SmartObject type inherits. Figure 5–2, which is based on the SmartDataViewer, illustrates these relationships.
Figure 5–2: Include file structure for SmartDataViewer
In Figure 5–2, note the following:
*The smrtprop.i file (lower left) defines an ADMProps temp-table that in turn defines the basic properties that apply to all SmartObjects. Each include file above the smrtprop.i file adds properties specific to the class with which it is associated. For details, see the “ADMProps temp-table and object properties” section.
*The viewer.w file includes only viewer.i.
*The viewer.i file includes datavis.i, because a SmartDataViewer is a data visualization object. It also includes viewprop.i, which includes the prototype include file viewprto.i.
*The datavis.i file includes visual.i because a SmartDataViewer is a visual object. It also includes dvisprop.i, which includes dvisprto.i.
*The visual.i file includes smart.i, because a visual object is a SmartObject. The visual.i file also includes visprop.i, which includes visprto.i.
*The smart.i file includes only smrtprop.i (which includes smrtprto.i).
When SmartObject code is preprocessed, the preprocessors limit the full expansion of the include files to exactly one branch of the class hierarchy, to avoid duplication of the SmartObject code.
Each SmartObject type uses a different part of the class hierarchy (different branches), but the The tree for any SmartObject type always ends with smart.i.
Figure 5–3 expands on Figure 5–2 to illustrate how super procedures are started.
Figure 5–3: Super procedure schematic for SmartDataViewer
In Figure 5–3, note the following:
*The smart.i file starts smart.p (if it is not already running) and adds it as a super procedure for the SmartDataViewer. The smart.p file should be the top‑level super procedure for all SmartObjects.
*The visual.i file starts visual.p, if it is not already running, and adds it as a super procedure for the SmartDataViewer.
*The datavis.i file then starts datavis.p (if it is not already running) and adds it as a super procedure for the SmartDataViewer.
*The viewer.i file starts viewer.p (if it is not already running) and adds it as a super procedure.
Note: The object’s own super procedure always must be added last. This is because super procedures are searched in last‑in, first‑out (LIFO) order, so the interpreter searches in viewer.p first for needed routines and in smart.p last. This ensures that more general behavior is executed last and more object‑specific behavior is executed first.