skip to main content
OpenEdge Development: ADM Reference
Container Objects and Their Methods and Properties : Base methods for container objects
 
Base methods for container objects
This section describes the base methods for Container Objects.
applyContextFromServer
Applies context returned from the server after a server call.
Location: containr.p
Parameters: None
Returns: LOGICAL
Notes: None
assignContainedProperties
Function that returns properties in contained objects that use the returned value of containedProperties.
Location: containr.p
Parameters:  
INPUT pcPropValues AS CHARACTER
A CHR(3)-separated list of properties and values from the containedProperties function. The first entry is a header that defines to which properties the remaining entries in the list apply. The header has two possible formats:
*Comma separated list of properties when all objects are SmartDataObjects (SDOs).
*A paired semicolon lists with object type and a comma delimited list of properties. THIS is used instead of ObjectType for this container instance. For example:
 
SmartBusinessObject;Prop1;SmartDataObject;propA,propB,propC
*The remaining CHR(3) entries are a paired list of objectNames and a CHR(4)-delimited list of property values, where each CHR(4) entry corresponds to the comma separated property list for the object's Object type.
*A blank objectname indicates this container is an instance.
*ObjectNames is qualified with ':' to specify container relationships.
INPUT pcReplace AS CHARACTER
A comma separated pair of replacement properties not qualified by ObjectTypes.
Returns: LOGICAL
Notes: None
assignPageProperty
Procedure that assigns a property in all objects on the CurrentPage of a SmartContainer. If an object on the page does not have a property, it is ignored without error.
Location: containr.p
Parameters:  
INPUT pcProp AS CHARACTER
The property to set.
INPUT pcValue AS CHARACTER
The value to assign to that property.
Notes:  
*This variation on assignLinkProperty is necessary because the notion of paging does not fit well with PUBLISH/SUBSCRIBE. This is because there is a single property (PageNTargets) that stores the handles of all of a SmartContainer’s objects that are not on page 0 in a specially delimited list.
*Although the pcValue parameter is specified in CHARACTER form, you can use these parameters to assign values to noncharacter properties.
*All objects in a Container subscribe to initializeObject, and so on, but the paging performs the operation on subsets of those objects at a time. That is, the container does not publish initializeObject to objects on a page other than zero until that page is first viewed. So properties such as HideOnInit, which are set as part of initialization, must be set page-by-page.
Example:  
/* Sets the DataModified property to "no" */
RUN assignPageProperty (‘DataModified’:U, ‘no’:U).
cancelObject
Procedure that cancels an object.
Location: containr.p
Parameters: None
Notes:  
*If this is the window container or a virtual container then override and do not call SUPER. If not a window/virtual container, cancel and undo all container targets and then destroy. Published from containerTargets or called directly.
*There is a slight overhead in this construct as destroyObject (called from exitObject apply close) does a publish confirmExit, which really is unnecessary after this has published confirmCancel. The reason is that destroyObject might be called directly.
*We currently have to call exitObject as AppBuilder’s WAIT-FOR complains if we destroy the object directly. Even apply close to target-procedure does not trigger the WAIT-FOR. It seems as this has to be fired from the actual instance. (exitObject should be local in all container instances) This might very well be a problem for application WAIT-FOR as well.
changePage
Procedure that views (and creates if necessary) objects on a newly selected page in a Container when CurrentPage is reset.
Location: containr.p
Parameters: None
Notes:  
*The changePage procedure is normally used internally and called from either selectPage or viewPage. Although you can customize changePage to perform some application-specific task each time a page is changed, if it is called from selectPage (the standard methods for switching pages within a Container), the previous page will have already been hidden.
*The changePage procedure expects the CurrentPage property to have been set to the new page before it is called.
*The changePage procedure does not hide the previously selected page. This is done before it is called from selectPage. If it is called from viewPage, the previous page is not hidden first. This would be the case if the new page is a SmartWindow to be viewed in addition to the current page in its container.
*The changePage procedure first publishes changeFolderPage to let the associated SmartFolder visualization, if any, know about the page change.
*If the new page is not page zero (which is always initialized at startup), and the objects on the page have not yet been created, changePage runs createObjects to create all the SmartObjects on the new page. If the SmartContainer itself has been initialized, it also publishes initializeObject to initialize the new objects, and publishes “viewObject” to view them.
Example:  
/* Display the current page number in a fill-in field whenever the page is
   changed.*/
PROCEDURE changePage:
  RUN SUPER. /* Perform the standard code first. */
  FILL-IN-1:SCREEN-VALUE IN FRAME {&FRAME-NAME} =
    STRING(DYNAMIC-FUNCTION("getCurrentPage":U)).
END PROCEDURE.
confirmExit
Procedure that passes this event on to its descendents, to check whether it is OK to exit (that is, there are no unsaved changes).
Location: containr.p
Parameters:  
INPUT-OUTPUT plCancel AS LOGICAL
If field values have been modified and not saved, it returns TRUE and the destroyObject is cancelled.
Note: Invoked from destroyObject.
confirmOk
Procedure that verifies that unsaved changes are saved and uncommitted data is committed before allowing its container to initiate a destroy operation.
Location: containr.p
Parameters:  
INPUT-OUTPUT plError AS LOGICAL
TRUE if the destroyObject is to be cancelled.
Notes:  
*This routine is named ‘confirm’ because it is similar to the other confirm methods, though this one does not ask any questions.
*Invoked at the top by okObject.
*Only republished if the container is non-virtual and non-window.
constructObject
Procedure that runs from adm-create-objects to RUN a SmartObject to establish its parent and initial property settings.
Location: containr.p
Parameters:  
INPUT pcProcName AS CHARACTER
The procedure name to run.
INPUT phParent AS HANDLE
Handle to its parent.
INPUT pcPropList AS CHARACTER
Property list to set.
OUTPUT phObject AS HANDLE
The new procedure handle.
Notes: None
containedProperties
Returns a CHR(3)-delimited list where the first entry is the passed query parameter. The rest of the entries consists of paired objectNames and CHR(4)-delimited properties. For plDeep queries, the ObjectName is colon separated to uniquely identify levels in the tree. The second in each pair is a CHR(4)-separated list of values where each entry corresponds to the Propertlist for that object.
Location: containr.p
Parameters:  
INPUT pcQueryProps AS CHARACTER
Comma-separated lists of properties to retrieve from SmartDataObjects (SDOs). You can optionally use paired semicolon lists to query different Object types.
INPUT plDeep AS LOGICAL
Determines the level at which a query should run. If TRUE, continue query in children of children. If FALSE, query only one level down.
Returns: CHARACTER
Notes:  
*The FORMAT of the returned string is INTERNAL and intended to be transported as is (across servers) to be passed into assignContainedProperties.
*If the ClientNames property is defined, the ObjectName entry in the returned list is replaced with the corresponding entry in the ClientNames list. This information is used to enable communication among clients with different container structures.
Example:  
<pcQueryProps>CHR(3)<ObjectName1>CHR(3)<PropAvalue>CHR(4)<PropBvalue>CHR(3)<ObjectName2>CHR(3)<PropAvalue>CHR(4)<PropBvalue>.
ContextandDestroy
Server-side procedure to run after new data has been requested by the client.
Location: containr.p
Parameters: None
Notes: None
createObjects
Standard procedure for running objects in a Container. This procedure runs the AppBuilder-generated procedure named adm–create–objects for compatibility with Version 8.
Location: containr.p
Parameters: None
Notes:  
*This procedure runs adm–create–objects, the AppBuilder-generated procedure that creates and initializes all the SmartObjects in a Container. This allows both the AppBuilder-generated code and any customization of it to exist in the same SmartContainer procedure, because the customization is called using createObjects.
*This can be customized to add application-specific behavior to the creation of SmartObjects in a Container. createObjects runs once for each page as it is initialized, so code in a custom version should always check the CurrentPage property to verify that the custom code is executed for the proper page (0 for general code to be executed exactly once).
Examples:  
PROCEDURE createObjects:
/* Purpose: Add some extra objects to key pages. Because these objects are
            being created by custom code, they will not appear in the
            AppBuilder at design time. */
  DEFINE VARIABLE hWin AS HANDLE NO-UNDO.
 
  RUN SUPER.  /* Get the other objects on this page created. */
 
  /* Now create a child window which appears when page 100 is selected. */
  IF DYNAMIC-FUNCTION(‘getCurrentPage’:U) = 100 THEN DO:
    RUN constructObject (INPUT ‘wChild.w’:U,    /* Master file to run */
                         INPUT {&WINDOW-NAME},  /* Parent handle */
                         INPUT ‘’:U,            /* No Instance Properties */
                         OUTPUT hWin).          /* New object handle */
    /* Add a custom link. The Container link is created automatically. */
    RUN addLink (THIS-PROCEDURE, ‘Custom’:U, hWin).
  END.
 
  RETURN.
END PROCEDURE.
confirmCancel
Procedure that verifies that unsaved changes are cancelled and uncommitted data are undone before allowing its container to initiate a destroy operation.
Location: containr.p
INPUT-OUTPUT plError AS LOGICAL
TRUE if the destroyObject is to be cancelled.
Notes:  
*The name confirm is used as it is in family with the other confirm methods, but this does not ask any questions Invoked at the top by cancelObject.
*Only republished if the container is non-virtual and non-window.
deletePage
Procedure that deletes all the objects on the specified page.
Location: containr.p
Parameters:  
INPUT piPageNum AS INTEGER
Number of page to be purged.
Notes:  
*The deletePage procedure is not run from any standard ADM code; it can be run from application code to delete a page when no longer needed, or for other reasons.
*The deletePage procedure publishes deleteFolderPage to remove the folder tab for the page, if any.
Examples:  
ON CHOOSE OF Btn_Delete_Page DO:
  DEFINE VARIABLE iPage   AS INTEGER NO-UNDO.
  DEFINE VARIABLE lAnswer AS LOGICAL NO-UNDO.
 
  /* Get the current page number and delete it. */
  iPage = getCurrentPage().
  MESSAGE "OK to delete page" STRING(iPage) + "?"
    VIEW-AS ALERT-BOX QUESTION BUTTONS YES-NO UPDATE lAnswer.
  IF lAnswer THEN
    RUN deletePage(iPage).
END.
destroyObject
Procedure that destroys a container object.
Location: containr.p
Parameters: None
Notes: None
disablePagesInFolder
Disables the specified folder pages.
Location: containr.p
Parameters:  
INPUT pcPageInformation AS CHARACTER
The pages to be disabled.
Returns: LOGICAL
Notes: None
enablePagesInFolder
Enables the specified folder pages.
Location: containr.p
Parameters:  
INPUT pcPageInformation AS CHARACTER
The pages to be enabled.
Returns: LOGICAL
Notes: None
fetchContainedData
Client-side procedure that retrieves a set of data from the server for the client.
Location: containr.p
Parameters:  
INPUT pcObject AS CHARACTER
Name of the client-side query object for which data is being retrieved. If the name is:
*Unknown, then result sets are fetched for all QueryObjects in this container and all QueryObjects in all contained containers
*Specified, then result sets are fetched from that Object down following only that data link
Notes:  
*The data links are followed when preparing and retrieving data for all objects in containers.
*The data links can go across containers but it cannot go into a container that is not a descendant of that container.
hidePage
Procedure that cycles through all objects on a page, hiding them.
Location: containr.p
Parameters: None
Notes: None
initializeObject
Procedure that does container‑specific initialization. If the container is a SmartFrame or nonvisual container, createObjects is run at this time. It is not run for a SmartFrame when it is first created to avoid creating objects that are not needed until after startup. If there is a StartPage (a first page to position to other than page 0), it is selected. If the HideOninit or DisableOnInit property is set for the Container, it is propagated to all contained objects before they are initialized. Then the container publishes “initializeObject” to initialize all its contents. Finally it does RUN SUPER to execute the initialization code in smart.p.
Location: containr.p
Parameters: None
Notes: None
initializeVisualContainer
Procedure that translates window title and tab folder page labels and checks security for page labels.
Location: containr.p
Parameters: None
Notes: None
initPages
Procedure that initializes one or more pages, which are not yet being viewed, in order to establish links or to prepare for the pages being viewed.
Location: containr.p
Parameters:  
INPUT pcPageList AS CHARACTER
A comma‑separated list of page numbers.
Notes:  
*The initPages procedure can be run by application code to initialize more pages than those that are initially viewed, either in order to reduce the startup time for pages later on, or to communicate with objects on pages not yet selected.
*If a SmartObject on one page in a SmartContainer is a link target of a SmartObject on another page other than page 0, the AppBuilder detects this during the design process and automatically generates an appropriate call to initPages as part of adm–create–objects. This assure that when the dependent page is initialized, the pages it depends on are initialized as well.
*Ordinarily only objects on page 0 and on the StartPage (if any) are created when the SmartContainer is created. Objects on other pages are created when the page they are on is first selected.
*In some cases a SmartDataObject can be an Update Target for a SmartDataViewer or Browser, which can be on a later page in the Container. This might cause more pages to be created at startup than is desired. If this is the case, the design time Update link can be removed, and created instead by application code in a local createObjects, as in the second example below.
isUpdateActive
Procedure that is received from container source to check if contained objects have unsaved or uncommitted changes (including addMode).
Location: containr.p
Parameters:  
INPUT-OUTPUT plActive AS LOGICAL
Note: This is published thru the container link and used mainly to validate that a FALSE value received in updateActive can be used to set UpdateActive. This is NOT intended to be called directly, but part of the logic that updates UpdateActive. These are the steps: (1) Updating objects publishes updateActive (TRUE or FALSE) to their container targets. (2) If the value is FALSE the container then publishes this to ALL ContainerTargets before it is stored in UpdateActive. This way the value is only stored as FALSE if ALL contained objects are inactive.
Examples:  
PROCEDURE initializeObject:
/* Purpose: Initialize the current SmartContainer and initialize some
            frequently used pages at the same time. */
 
  RUN SUPER.   /* Execute standard page creation first. */
 
  /* Initialize pages 2, 8, and 106 at startup. This will create the pages
     but not view them. */
  RUN initPages (‘2,8,106’:U).
END PROCEDURE.
 
PROCEDURE createObjects:
/* Purpose: Local version to add an Update link between a SmartDataObject on
   page 0 and a SmartDataViewer on page 2; not done until page 2 is created. */
 
  RUN SUPER. /* Do the standard creation for each page first. */
  IF getCurrentPage() = 2 THEN
    RUN addLink(h_Vcust, ‘Update’:U, h_Dcust).
END PROCEDURE.
notifyPage
Procedure that invokes the specified procedure in all objects on the CurrentPage of A SmartContainer.
Location: containr.p
Parameters:  
INPUT pcProc AS CHARACTER
The internal procedure to run.
Notes:  
*This procedure is necessary because paging does not work well with PUBLISH/SUBSCRIBE. For example, although all objects in a Container subscribe to initialize (and so on), the paging performs the operation on subsets of those objects.
*The notifyPage procedure uses the PageNtargets property values to run an event procedure in all the objects on the current page.
Example:  
/* This code fragment from changePage causes initializeObject to be run in
   each newly created object on a page selected for the first time. NotifyPage
   effectively does a PUBLISH to each object on the current page. */
 
{get ObjectInitialized lInitted}. /* Is the container itself initialized? */
IF lInitted THEN
  RUN notifyPage In TARGET-PROCEDURE (“initializeObject”:U).
obtainContextForServer
Function used to obtain the context properties to pass to the server.
Location: containr.p
Parameters: None
Returns: CHARACTER
Note: The server must know whether or not this is the first call. Determining whether or not it is the first call can be done using either one of the following:
 
Client: AsHasStarted = no until a response from server
 
Server: serverFirstCall = no unless client passes YES
Two similar properties are provided to support different defaults on client and server.
Note: This function is always called before an Appserver call and is used to send context in initializeServerObject as well as in all data requests.
okObject
Procedure that saves and closes an object (OK action).
Location: containr.p
Parameters: None
Notes:  
*If this is the window container or a virtual container then override and do not call SUPER. If not, then save and commit all Container-Targets and destroy if no errors occurred. Published from containerTargets or called directly.
*There is a slight overhead in this construct as destroyObject (called from exitObject -> apply close) does a publish confirmExit, which really is unnecessary after this has published confirmOk. The reason is that destroyObject might be called directly.
*We currently have to call exitObject as the appbuilder wait-for protests if we destroy directly. Even apply ‘close’ to target-procedure does not trigger the wait-for. It seems as this has to be fired from the actual instance. (exitObject should be local in all container instances) This might very well be a problem for application wait-for as well.
pageNTargets
Returns a comma-separated list of the objects on the specified page for this container.
Location: containr.p
Parameters:  
INPUT phTarget AS HANDLE
INPUT piPageNum AS INTEGER
Returns: CHARACTER
Notes:  
*The actual property pageNTarget keeps track of SmartObject page assignments within a Container. It is stored as a comma-separated list of entries, where each entry consists of an object handle in string format and its page number, separated by a vertical bar. The Target-Procedure is passed as a parameter because this function is only invoked locally, not in the Target-procedure.
*This function is only used internally by the ADM paging code.
passThrough
Procedure that acts as an intermediary for dynamic links that need the pass‑through mechanism to either get an event from an object outside a container to an object inside a container or to get an event from and object inside a container to an object outside a container.
Location: containr.p
Parameters:  
INPUT pcLinkName AS CHARACTER
The link (event) name to be passed on.
INPUT pcArgument AS CHARACTER
A single character‑string argument.
Note: To use this for single pass-through events, define a PassThrough link from the Source to the intermediate container, and define the actual dynamic link from the container to the Target. Then PUBLISH PassThrough (LinkName, Argument) to send the event.
removePageNTarget
Procedure that removes an object from the list of Targets on a page.
Location: containr.p
Parameters:  
INPUT phTarget AS HANDLE
The handle of the object to be removed.
INPUT piPage AS INTEGER
The page number of the object to be removed.
Note: Run from removeAllLinks for objects not on Page 0. Not intended to be run from application code.
resizeWindow
Procedure that respond to a resize event from user event or container targets.
Location: containr.p
Parameters: None
Note: The current functionality just resizes the frame according to the window size. This was added to make the call from the toolbar’s resizeObject after it expands a window have some default functionality, but this is mostly a placeholder for logic to resize all contained objects, currently implemented in ry/uib/rydyncontw.w.
selectPage
Procedure that changes the currently selected page. If the previous current page is not page 0 (the background page that is always visible), then hideObject is run in all the objects on the CurrentPage. Then the CurrentPage is changed to the new page number of piPageNum, and the changePage procedure is run to view and, if necessary, create the objects on the new page.
Location: containr.p
Parameters:  
INPUT piPageNum AS INTEGER
Notes:  
*This procedure switches from one page on a single frame to another page so that objects on the previous page are hidden and objects on the new page are viewed. If the new page is a separate SmartWindow, in most cases you should use the viewPage procedure to view the objects on the new page without hiding the current page.
*The selectPage procedure runs when a user presses a tab on the SmartFolder. It can also run from application code when some other mechanism is used to change pages.
Example:  
 
/* This trigger code allows the user to select a page by typing the number
   into a field. */
 
ON LEAVE OF PageNum DO:
  RUN SelectPage (INTEGER(PageNum:SCREEN-VALUE)).
END.
targetPage
Returns the ADM page number associated with some object.
Location: containr.p
Parameters:  
INPUT phObject AS HANDLE
The object of interest.
Returns: INTEGER
Notes: None
toolbar
Procedure that is a generic event handler for toolbar events.
Location: containr.p
Parameters:  
INPUT pcValue AS CHARACTER
The string used by the handler’s CASE statement to determine behavior. Valid values are:
*EnableData — Activates data links by publishing ToggleData
*DisableData — Deactivates data links by publishing ToggleData
*Notepad — Launches the Notepad application by calling launchExternalProcess
*Wordpad — Launches the Wordpad application by calling launchExternalProcess
*Calculator — Launches the Calculator application by calling launchExternalProcess
*Internet — Launches the Internet Explorer browser by calling launchExternalProcess
*Email — Runs sendEmail
*Word — Launches the Word word-processor application
*Excel — Launches the Excel spreadsheet application
*PrintSetup — Opens the system’s printer-setup dialog box
*Suspend — Runs af/cod2/aftemsuspd.w
*Re-Logon — Runs relogon
*Preferences — Launches the preferences applet rydynpref.w
*Translate — Launches the translation applet rydyntran.w
*Help — Runs contextHelp
*HelpAbout — Runs helpabout
*HelpTopics — Runs helptopics
*HelpContents — Runs helpcontents
*HelpHelp — Runs helphelp
*Spell, Audit, Comments, History, Status — Currently trapped, but undefined.
Notes: None
updateActive
Procedure that is published from ContainerTargets when they change state as a result of, for example, setDataModified, setNewRecord, or setRowObjectState.
Location: containr.p
Parameters:  
INPUT plActive AS LOGICAL
TRUE if some update is known active and ContainerTargets need not be surveyed
Note: This is part of the logic to make the UpdateActive property reflect the containers state.
viewObject
Procedure this is container-specific code for viewObject. If the HideOnInit property has been set during initialization to allow this object and its contents to be initialized without being viewed, turn that off here and explicitly view all contents.
Location: containr.p
Parameters: None
Notes:  
*This Container-specific version of viewObject checks the HideOnInit property for the Container. If it was TRUE, then the container was not viewed when first initialized. Now that it is being viewed, it turns off the HideOnInit property in itself and its contents, and explicitly visualizes its contents.
*See viewObject for visual.p for more general information on using and customizing this event procedure.
viewPage
Procedure that views a new page without hiding the current page. You should run this from application code when you want a user to view a new page that is a separate SmartWindow. viewPage runs changePage to view (and if necessary create) the new SmartWindow, but does not hide the objects on the current page, since they are in a separate window that can be viewed at the same time.
Location: containr.p
Parameters:  
INPUT piPageNum AS INTEGER
Notes:  
*Because the previous page is not hidden, the CurrentPage property is reset only temporarily so that changePage knows the new page number; then it is reset to its previous value.
*Use the procedure selectPage to hide the current page in a container and view a different one.
Example:  
/* In this example, a SmartWindow has been placed onto page 5 of a containing
   SmartWindow. When a button is pressed, viewPage views the subwindow without
   hiding anything or changing the current page on the main SmartWindow. */
 
ON CHOOSE OF Btn_SubWin DO:
  RUN viewPage(5).
END.