PropExchange Object

Description

The PropExchange object is used for reading and writing CommandBar, Docking Pane, Task Panel, and Grid Control layout information to/from an XML file, the registry, or a binary file.

For a list of all members defined in this module, see PropExchange Members.

Remarks

The PropExchange object provides a universal solution to save the layout and state of the CommandBars, Docking Pane, Task Panel, and Grid Controls to a single file or the system registry with support to write/load directly to/from a file or registry.

In addition to saving the layout and state of the controls, additional String and Integer values can be saved to the same file using the ExchangeInt and ExchangeString methods. It is important to note that both methods require a variable reference to store the data.

Note: When working with XML data, there cannot be any spaces in the name given to the data.

More than one layout for each object can be saved to the same file. This allows multiple layouts to be saved to a single location. The GetSection method will create a new "section" in the file/registry in which a new layout can be saved/loaded.

There are three ways to save and load layout/state information to a PropExchange object. You can load and save information to the system registry, an XML file, or a binary file. The CreateAsBinary, CreateAsRegistry, and CreateAsXML methods are used to specify whether to save or load the layout/state information and the location of the layout/state information (path to XML or Bin file, Registry Key).

Note: This does not actually load/save the information; it just indicates the location to load/save the information to/from and if it will be loaded/saved.

When using any of the CreateAs methods, the Loading parameter is used to specify whether the layout information is currently Loading or saving. The Loading property will be True until set to False by calling a CreateAs method and passing False as the Loading parameter. The Loading property can be used to determine if you are currently loading layout information.

The DoPropExchange method is used to actually load or save the information to a file or the registry.

When saving information, the Valid property should be used after a call to one of the CreateAs methods to verify that the layout information was correctly saved to the PropExchange object.

When loading information, the LoadFromFile method can be used to verify and load the information at the same time.

The Encoding property is provided for Unicode support when working with XML files.

The Value property is used when working with XML data. The Value will always contain the layout and state of the control in XML format. The Value is intended to be used to manually create or get the layout in XML format. This can be used to manually read/write the layout information directly to/from the Value property if you don't want to save to a file.

What layout information is saved?

CommandBars: Toolbar position, theme, any of the options that are displayed in the Customization Dialog, and anything that is specified in the StateOptions object.
Grid Control: Column order, sort order, group order, column visibility, GroupBox visibility, Column Width, and Alignment.
TaskPanel: Group order, item position and order, expand state of group, item and group state, item and group state captions, item and group state icons, and item and group state order.
Docking Pane: Saves the DockingPaneLayout object. The DockingPaneLayout object contains all panes positions, captions, visibility state, size, group membership if applicable, and icons.

Example

ExchangeInt and ExchangeString Sample (Visual Basic)

This sample illustrates how to use the ExchangeInt and ExchangeString methods to load and save a Long and String to/from a file.

Private Sub LoadData()  
    Dim pxRead As New PropExchange  

    ' Specifies to load information from a node named "CustomerInformation"  
    pxRead.CreateAsXML True, "CustomerInformation"  

    ' Specifies the name of the file to search for the "CustomerInformation" node.  
    If pxRead.LoadFromFile("c:\test.xml") Then  
        ' Declares a String object to store information read from the test.xml file.  
        Dim StrName As String  
        StrName = ""  

        ' Searches for a node named "CustomerName", if found, then the information  
        ' will be stored in the StrName object.  
        pxRead.ExchangeString "CustomerName", StrName, ""  
        Debug.Print StrName  

        Dim IntAge As Long  
        IntAge = 0  
        pxRead.ExchangeInt "CustomerAge", IntAge, 0  
        Debug.Print IntAge  
    End If  
End Sub  

Private Sub SaveData()  
    Dim pxWrite As New PropExchange  

    ' Specifies that a node named "CustomerInformation" will be created.  
    ' The XML string is currently stored in the Value property of the pxWrite PropExchange object.  
    pxWrite.CreateAsXML False, "CustomerInformation"  

    ' Verify that the "CustomerInformation" node was successfully written to the object.  
    If pxWrite.Valid Then  
        ' Declare a String object to pass in as a reference to the ExchangeString method.  
        Dim StrName As String  
        StrName = "Mr. Smith"  

        ' Important - There can be no spaces in the name of the node when using XML  
        ' This will create a node named "CustomerName" under the "CustomerInformationNode"  
        pxWrite.ExchangeString "CustomerName", StrName, ""  

        Dim IntAge As Long  
        IntAge = 32  
        pxWrite.ExchangeInt "CustomerAge", IntAge, 0  

        ' Writes the XML string stored in the Value property to an XML file named test.xml.  
        pxWrite.SaveToFile "c:\test.xml"  
    End If  
End Sub

Loading and Saving to/from a file (Visual Basic)

This sample illustrates how to load and save layout/state information to/from a file.

Sub ExchangeState(px As PropExchange)  
    On Error Goto Error  

    ' PropExchange object to save and load information to/from.  
    Dim pxSection As PropExchange  

    ' Creates a section called "GridControl" if saving or retrieves data from the "GridControl" node of loading.  
    Set pxSection = px.GetSection("GridControl")  

    ' Loads or Saves the settings of the GridControl  
    GridControl.DoPropExchange pxSection  

Error:  
End Sub  

Private Sub Form_Load()  
    ' Loads the CommandBars from Designer Data.  
    ' This data was added by specifying an .xcb file when right-clicking the CommandBar object  
    ' and selecting "Load CommandBars(*.xcb).  
    CommandBars.LoadDesignerBars  
End Sub  

Private Sub LoadData()  
    Dim pxRead As New PropExchange  

    ' Load data from a binary file  
    ' If (pxRead.CreateAsBinaryFile(True, "c:\file.out")) Then  
    '     ExchangeState pxRead  
    ' End If  

    ' Load data from an XML file  
    pxRead.CreateAsXML True, "Settings"  
    If pxRead.LoadFromFile("c:\file.xml") Then  
        ExchangeState pxRead  
    End If  

    ' Load data from a binary file  
    ' pxRead.CreateAsRegistry True, "HKEY_CURRENT_USER\Software\Codejock Software\Project1\Sample"  
    ' ExchangeState pxRead  
End Sub  

Private Sub SaveData()  
    Dim pxWrite As New PropExchange  

    ' Save data to a binary file  
    ' pxWrite.CreateAsBinaryFile False, "c:\file.out"  
    ' ExchangeState pxWrite  

    ' Save data to an XML file  
    pxWrite.CreateAsXML False, "Settings"  
    If pxWrite.Valid Then  
        ExchangeState pxWrite  
        pxWrite.SaveToFile "c:\file.xml"  
    End If  

    ' Save data to the registry  
    ' pxWrite.CreateAsRegistry False, "HKEY_CURRENT_USER\Software\Codejock Software\Project1\Sample"  
    ' ExchangeState pxWrite  
End Sub