Persist Settings Using IPersistStream


This sample illustrates how you can persist settings through an extension by having it implement the IPersistStream interface. The methods on this interface get called when ArcMap saves a document. When this document is later opened, the extension gets an opportunity to load its settings.

If the user of your extension opens a template, your extension has an opportunity to store settings in the template when it is saved.

This extension stores a default map background color setting applied when a document opens and when dataframes are added or deleted. It also stores default views for the TOC and the map that are applied when a document opens. The extension does this by listening to IDocumentEvents.

The 'Command Using Persisted Settings' sample has a command button that lets you change these settings. The command becomes enabled when this extension is registered and enabled.

The extension has default settings that it imposes on every document opened when the extension is registered and enabled. If the user changes the default settings through the above-mentioned command button, and saves those settings in a document, the changed settings will be applied when that document is opened. Similarly, when changed settings are saved in a template, the new settings will apply to all documents created from that template.

As IPersistStream inherits from an interface other than IUnknown, it cannot be implemented in Visual Basic. IPersistVariant can be used as an alternative. For an illustration, have a look at the 'Persist Settings Using IPersistVariant' sample.

How to use:

    Register the extension:

  1. Open this sample's workspace and change the paths to esriCore.olb and ArcCATIDs.h in StdAfx.h so that they point to your ArcGIS installation.
  2. Build this sample's dll. This also registers the dll and adds it to the appropriate component categories.
  3. Unregister the 'Persist Settings Using IPersistVariant' sample's dll, if you already have that sample's dll registered.
  4. Close and re-start ArcMap.
  5. Go to Tools > Extensions, and check the box next to 'Persist Settings Extension' in order to enable the extension.

    Use the extension:

  1. Open a new document. Notice that the dataframe has a background color. Also notice that the TOC is in the Source view and the map is in the Layout view. This is due to the settings applied by this extension.
  2. Add a new data frame by going to the 'Insert' menu. Notice that this dataframe has a background color too.
  3. Add the command button from the 'Command Using Persisted Settings' sample to a toolbar. Refer to that sample's documentation for more info.
  4. Using this command, you can change these settings for the document/template that you have open.
  5. After changing settings, save the document and open it again. Notice that the settings have persisted.
  6. Open a new document. Notice that it uses the default settings of the extension.
  7. Try doing the same with a template.
  8. When you are done, remove the extension. To do this, unregister this sample's DLL by typing "regsvr32 /u <path_to_this_sample's_dll>" at a DOS prompt.


Difficulty: Intermediate

Visual C++
File Description
PersistExt.cpp Implementation file for the Persist Settings extension.
PersistExt.h Header file for the Persist Settings extension.
PersistExt.rgs Registry script file for the Persist Settings extension.
PersistSettings_Stream.dsp Project file.
PersistSettings_Stream.dsw Workspace file.
PersistSettings_Stream.dll Compiled DLL for project.
PersistSettings_Stream.cpp Implementation of DLL Exports.
PersistSettings_Stream.def Module Definition file, listing exported functions.
PersistSettings_Stream.idl The IDL file for the sample.
PersistSettings_Stream.rc Resource file.
PersistSettings_Stream.mak Make file for Project.
PersistSettings_Streamps.def Module definition file for proxy-stub Code. Make file for proxy-stub code.
resource.h Resource file.
StdAfx.h Header file that includes standard system include files.
StdAfx.cpp Source file that includes just the standard includes.

Key CoClasses: ObjectStream, RgbColor, SymbolBackground, SimpleFillSymbol
Key Interfaces: IPersistStream, IStream, IObjectStream, IExtension, IExtensionConfig, IDocumentEvents, IDocument, IMxDocument, IPageLayout, IGraphicsContainer, IActiveView, IContentsView, IMaps, IMap, IFrameElement, IBackground, ISymbolBackground, IFillSymbol, IRgbColor, IClone