How to create property pages and property sheets


Summary
This topic shows how to use the ArcGIS item template to create a property page for ArcGIS for Desktop applications. This topic also shows how to display a property sheet.


Creating a property page

For .NET developers, property pages are components within a class library that implement the IComPropertyPage interface from the ESRI.ArcGIS.Framework assembly. Although there are many property page-related component categories, a property page is only registered in the component category for the object that it is designed to apply against. For example, ArcMap layer property pages are registered in Esri Layer Property Pages and data frames in Esri Map Property Pages; ArcScene layers register in Esri Sx Layer Property Pages, while ArcGlobe layers register in Esri GMx Layer Property Pages. The Esri Property Pages category is for general page registration.
A property page is implemented in .NET by creating a user control that contains the user interface for the property page and implements the required property page interfaces.
Follow theses steps to add a property page implementation to an existing project:
  1. Create a property page class using the Property Page (Desktop) item template:
    1. The item template is included as part of ArcGIS Visual Studio integration development environment (IDE) Integration Framework in the ArcObjects .NET software development kit (SDK). On the Add New Item dialog box, locate it under ArcGIS, then Extending ArcObjects. See Using item templates to extend ArcObjects for details.
    2. Choose Generic property page in the ArcGIS New Item Wizard Options dialog box. The newly created class inherits System.Windows.Forms.UserControl and implements the IComPropertyPage interface.
  2. Implement the Applies and SetObjects methods by going through the objects inside the incoming ISet parameter:
    1. Applies—This method is called when the property sheet loads, before the dialog box appears. A reference to an ISet object is passed in, which is a collection containing references to the objects to be edited by the property page. The property page is responsible for checking if the objects in this set can be edited by the page. Iterate through the set to check the objects by type using the (C#) or TypeOf (VB .NET) keyword. If all the objects required for the page are present, then return true; otherwise, return false.
    2. SetObjects—References to the objects to be edited are passed to the page by the SetObjects method in the incoming ISet parameter. Save these objects as class variables (for example, a dictionary class variable m_objectBag is provided by the item template). Later, when called to Apply, you can implement the changes specified by the user to the objects passed in.
  3. Add controls to the user control, as required, to allow users to edit the members of your custom class:
    1. Handle the appropriate control events (for example, a button click).
    2. Validate user input (for example, alphabetic character versus numeric character in a text box).
    3. Use a class variable (for example, m_dirtyFlag) to track any changes made to the controls, and return the dirty flag in the IsPageDirty property to indicate if any changes have not been applied to the object.
    4. Use the reference that is passed in the PageSite property, and call IComPropertyPageSite.PageChanged to inform the page site that something has changed and the Apply button should be enabled.
  4. Implement the Activate and Deactivate methods to perform setup and teardown of the property page:
    • Activate—Called before the Show method when the user selects the property page, making it the current page in the property sheet. Return the window handle of the user control.
    • Deactivate—Called when the property sheet exits. Do final cleanup and dispose of the user control in this method.
  5. Implement the Apply and Cancel methods:
    • Apply—This method can be used to read the settings from the property page and apply them to the objects you are manipulating with the page (those received in SetObjects) if those changes are not already applied and the IsPageDirty property returns true. This method is called when the user clicks either OK or Apply or changes the active property page on the property sheet.
    • Cancel—Called when the Cancel button is clicked on the property sheet.
  6. Implement other interface members:
    • The item template has already added code to Title, Height, and Width properties.
  7. If necessary, implement IComPropertyPage2, IComEmbeddedPropertyPage, or any specialist property page interfaces such as IRendererPropertyPage and ISymbolPropertyPage:
    • IComPropertyPage2.QueryCancel—This method is called when the property page is the currently displayed page and the user clicks the Cancel button before the property sheet is closed. Use this method to perform any checks or changes before a user closes a property page. Return true to allow the dialog box to close when the user clicks Cancel, or return false to prevent the Cancel operation.
    • IComEmbeddedPropertyPage.CreateCompatibleObject—This method is called when the user changes the embedded property page that is selected. Create a new object based on the properties of a template object, which is passed in to this method. The object returned does not have to be the same type as the template or the objects specified in the SetObjects method, or it can be NULL.
    • IComEmbeddedPropertyPage.QueryObject—The property page container calls this method, passing in a reference to an object that applies to the property page. This provides the means for setting the changes from the property page to the object being edited. Set the properties of that object based on the values currently on the property page. The type of object does not have to match that object passed to the SetObjects method.
  8. Register the property page class with the appropriate component category or categories:
    • The Generic property page option of the item template adds the class to the Esri Property Page category by default.
    • Use the ArcGIS Component Category Registrar dialog box and select from the categories in the Property Pages group.
The Layer property page option of the item template creates a class tailored for layers. If you did not install ArcGIS item templates, add a new user control to your project and implement the IComPropertyPage interface in the newly created class. Expose this class to the component object model (COM) and stub out all the interface members.

Displaying a property sheet

To display a property sheet, follow these steps:
  1. Use IComPropertySheet and ComPropertyPageClass to create the property sheet.
  2. Instantiate a SetClass object to hold the objects to edit.
  3. Obtain the objects to edit and add to the set.
  4. Specify the pages that you want to show using the IComPropertySheet methods:
    1. Specify a particular component category using the AddCategoryID method. The component category should contain a list of property page classes. Before the property sheet appears, each page in the category is created and has its Applies method called. Every page in the category that applies to the object will be shown in the property sheet.
    2. Add individual property pages by creating the pages required and passing them to the AddPage method.
By default, if no other pages are specified, the property sheet class automatically checks the Esri Property Pages category for pages that apply to the objects passed to the EditProperties method. All ArcObjects property pages are registered with this category by default.
However, each property page has to be created, checked, and destroyed when verifying this entire category. If you use either or both of the previous ways to specify particular property pages, this can improve the display speed of the property sheet.
  1. Display the property sheet using IComPropertySheet.EditProperties, passing the object set as the input parameter.
See the following code example:
[C#]
//Step 1.
IComPropertySheet myPropertySheet = new ComPropertySheetClass();
myPropertySheet.Title = "My Property Sheet";
myPropertySheet.HideHelpButton = true;

//Step 2 and Step 3: Pass in layer, active view, and the application.
ISet propertyObjects = new SetClass();
IBasicDocument basicDocument = m_application.Document as IBasicDocument;

propertyObjects.Add(basicDocument.ActiveView);
propertyObjects.Add(basicDocument.SelectedLayer);

//Step 4 - Bullet item a: Add by component category; all pages registered in the layer property page.
UID layerPropertyID = new UIDClass();
layerPropertyID.Value = "{1476c782-6f57-11d2-a2c6-080009b6f22b}";
myPropertySheet.AddCategoryID(layerPropertyID);

//Step 4 - Bullet item b: Add page by page. 
myPropertySheet.ClearCategoryIDs();
myPropertySheet.AddCategoryID(new UIDClass()); //A dummy empty UID.
myPropertySheet.AddPage(new ESRI.ArcGIS.CartoUI.LayerDrawingPropertyPageClass()); 
    //Feature layer symbology.

//Step 5 - Show the property sheet.
if (myPropertySheet.CanEdit(propertyObjects))
    myPropertySheet.EditProperties(propertyObjects, m_application.hWnd);
[VB.NET]
'Step 1.
Dim myPropertySheet As IComPropertySheet = New ComPropertySheetClass()
myPropertySheet.Title = "My Property Sheet"
myPropertySheet.HideHelpButton = True

'Step 2 and Step 3: Pass in layer, active view, and the application.
Dim propertyObjects As ISet = New SetClass()
Dim basicDocument As IBasicDocument = DirectCast(m_application.Document, IBasicDocument)

propertyObjects.Add(basicDocument.ActiveView)

    propertyObjects.Add(basicDocument.SelectedLayer)
        
        'Step 4 - Bullet item a: Add by component category; all pages registered in the layer property page.
        Dim layerPropertyID As New UIDClass()
        layerPropertyID.Value = "{1476c782-6f57-11d2-a2c6-080009b6f22b}"
        myPropertySheet.AddCategoryID(layerPropertyID)
        
        'Step 4 - Bullet item b: Add page by page.
        myPropertySheet.ClearCategoryIDs()
        myPropertySheet.AddCategoryID(New UIDClass()) 'A dummy empty UID.
        myPropertySheet.AddPage(New ESRI.ArcGIS.CartoUI.LayerDrawingPropertyPageClass()) 'Feature layer symbology.
        
        'Step 5 - Show the property sheet.
        If myPropertySheet.CanEdit(propertyObjects) Then
            myPropertySheet.EditProperties(propertyObjects, m_application.hWnd)
        End If


See Also:

Creating property pages
Sample: Layer property page and property sheet




To use the code in this topic, reference the following assemblies in your Visual Studio project. In the code files, you will need using (C#) or Imports (VB .NET) directives for the corresponding namespaces (given in parenthesis below if different from the assembly name):
Development licensing Deployment licensing
ArcGIS for Desktop Basic ArcGIS for Desktop Basic
ArcGIS for Desktop Standard ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced ArcGIS for Desktop Advanced