How to create property pages and property sheets

In this topic

• Creating a property page
• Displaying a property sheet

Creating a property page

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.

Displaying a property sheet

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.

5. Display the property sheet using IComPropertySheet.EditProperties, passing the object set as the input parameter.

//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);

'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:

• ESRI.ArcGIS.System (ESRI.ArcGIS.esriSystem)
• ESRI.ArcGIS.Framework
• ESRI.ArcGIS.ArcMapUI
• ESRI.ArcGIS.CartoUI