Persist Settings Using IPersistVariant

Last Modified:5/3/2001

This sample illustrates how you can persist settings through an extension by having it implement the IPersistVariant 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.

How to use:

    Initial Setup (Visual Basic):

  1. Register this sample's dll by compiling the sample or by using Regsvr32.exe.
  2. Double-click on this sample's .reg file. This adds the Persist Settings Extension to the 'ESRI Mx Extensions' category.
  3. Close and re-start ArcMap.
  4. Go to Tools > Extensions, and check the box next to 'Persist Settings Extension (VB)' in order to enable the extension.
  5. Add the command button from the 'Command Using Persisted Settings (VB)' sample to a toolbar. Refer to that sample's documentation for more info.

    Initial Setup (Visual C++):

  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 IPersistStream' 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.
  6. Add the command button from the 'Command Using Persisted Settings' sample to a toolbar. Refer to that sample's documentation for more info.

    Using 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. You can change these settings for the document/template that you have open by using the previously added command.
  4. Click on the command, change settings, save the document and open it again. Notice that the settings have persisted.
  5. Open a new document. Notice that it uses the default settings of the extension.
  6. Try doing the same with a template.
  7. 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 Basic Visual C++
File Description
clsPersistExt.cls Class file that implements the extension.
IPersistExtVB.cls Class file that defines the interface implemented by the extension. Using this interface, commands, toolbars, etc. can integrate with this extension.
PersistSettings_VariantVB.reg Registry file generated by the ESRI Compile and Register Add-In. You can double-click this to register this component in the 'ESRI Mx Extensions' category instead of using Categories.exe.
PersistSettings_VariantVB.vbp VB Project File for sample.
PersistSettings_VariantVB.dll Compiled project DLL.

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