Skip to content

LoadEnvironment - cCJCommandBarSystem

Loads layout information and applies it to the commandbar system object

Type: Procedure

Syntax

Procedure LoadEnvironment

Call Example

Send LoadEnvironment

Description

LoadEnvironment loads layout information and applies it to the commandbar system object. This is used to restore a user's menu/toolbar configuration. LoadEnvironment is called when a cCJCommandBarSystem object is activated (see CreateCommandBars). By default, LoadEnvironment does the following:

  1. If a cApplication object does not exist or that application object's pbPreserveEnvironment property is false, it returns and does nothing.

  2. It determines what should be loaded by checking the peRestoreLayout property.

  3. It determines the registry location of the stored data be calling the cApplication object's RegistryKeyString function.

  4. If loads the layout by calling LoadLayoutFromRegistry passing the layout and registry key data.

Loading from the Registry

By default LoadEnvironment loads from the registry and you do not need to make any changes. As a reference the source for this method is:

Procedure LoadEnvironment
        Handle eLayout
        String sKey
        Boolean bOk bPreserveEnvironment

        If (ghoApplication=0) Begin
            Procedure_Return
        End
        Get pbPreserveEnvironment of ghoApplication to bPreserveEnvironment
        If bPreserveEnvironment Begin
            Get peRestoreLayout to eLayout
            Get RegistryKeyString of ghoApplication to sKey
            Get LoadLayoutFromRegistry eLayout sKey to bOk
        End
   End_Procedure

Note that you do not need to create this code. This is what LoadEnvironment does by default.

Loading from an XML File

You may wish to augment and override this method to support custom loading behaviors. For example, if you wished to load data from an XML file, you could make change the above function to call LoadLayoutFromXML instead of LoadLayoutFromRegistry. This would be done as follows:

Procedure LoadEnvironment
        Handle eLayout
        String sFileName
        Boolean bOk bPreserveEnvironment

        If (ghoApplication=0) Begin
            Procedure_Return
        End
        Get pbPreserveEnvironment of ghoApplication to bPreserveEnvironment
        If bPreserveEnvironment Begin
            Get peRestoreLayout to eLayout

            // create a file name for the XML file.
            Move "C:\MyLayout\Layout1.xml" to sFileName
            // Get the layout from the xml file.
            Get LoadLayoutFromXML eLayout sFileName to bOk
        End
   End_Procedure

Detecting Changes in Source Layout

When source code changes are made in a commandbar system, the restored layout may interfere with those changes. When this happens, changes made to the commandbar system will not appear because the old settings are being restored. The commandbar system attempts to recognize when such a change has occurred by checking if the number of toolbars and items have changed. If it has, the previous setting will not be restored. In some cases, it will not recognize that a change has actually occurred. If this happens, you must tell the system that the menu layout has changed. You can do this by changing (i.e., incrementing) the build number of the commandbar system by setting the piLayoutBuild property.

See Also

SaveEnvironment