SaveConfigToFile/LoadConfigFromFile
Saving and restoring your docking config is crucial for a good user experience. Typically when you close down an application you want to store the current layout so that at restart you can restore that layout. This allows a smooth experience for the end user. You can do this easily with the docking system by using the file variations of the save/load methods.

SaveConfigToXml/LoadConfigFromXml
SaveConfigToArray/LoadConfigFromArray
SaveConfigToStream/LoadConfigFromStream
To allow maximum flexibility you can also persist configurations to xml streams, bytes arrays and arbitrary streams. Using byte arrays is really useful if you want to store configs inside a database. You can easily convert a byte array to and from base64 and so have it stored as a string.

GlobalSaving/GlobalLoading
Extensibility is provided via a set of events. Use these two events to add your own custom data into the configuration data. Adding your own custom arbritary information into the docking config might serve as the only persistence mechanism needed for your entire application.

PageSaving/PageLoading
Store per-page custom information using this pair of events. For example, your page might represent a file and so you could use the PageSaving event to store the name of the file the page is displaying. On loading you use the PageLoading to associate the file with a page and  initialize the page contents.

When a docking configuration is being loaded the process begins by creating a list of all the current pages inside the docking hierarchy. Then the entire contents of the hierarchy are reset. So all floating windows are killed, auto hidden groups wiped and docked windows removed. Now the config is loaded to create new floating window, auto hidden groups and so forth as defined in the config.

Each time a page definition is found in the config it attempts to reuse any existing page with that same unique name. So if the page existed at the time of the load operation and the config refers to that page it will simply be reused. The PageLoading event is fired so the existing page can be modified if required by event handlers based on any custom data that is stored with the page config.

RecreateLoadingPage
If the configuration contains details of a page that does not exist in the current hierarchy at load time then this event is fired so that an appropriate page can be created. If you want the config page ignored then you can cancel the event.

OrphanedPages
Once the config has been reloaded there might be pages that were in the hierarchy before the load but were not inside the config itself. These are orphan pages in that they are no longer part of the docking system as they were removed but never added back again. This event is fired at the end of the load process and gives a list of all these orphan pages. This event is useful if you need to perform extra processing for a page that is no longer needed, such as closing file handles or releasing other resources.

The above set of events allows two common scenarios to be handled. Applications that have a constant set of docking pages can easily be saved and reloaded without needing to handle any events. As the loading config will always refer to every docking page it means that all the pages are preserved after loads. Applications that have a dynamic set of pages are handled easily by using the RecreateLoadingPage and OrphanedPages events.

This entry was posted on Thursday, July 9th, 2009 at 9:08 pm and is filed under Krypton Docking. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.