About property pages
Property pages allow you to interact with objects by changing the values of their properties without writing code. A property page for a custom object also allows you to link online help files to a particular object and can even be used to brand the object as your third-party object. Property pages are found throughout the entire framework, although they are not often found on object diagrams. Many examples are described in this topic including a property page implementation that allows you to view and change the properties of a custom object.
A property page is not always essential for every custom object, even if other similar objects have property pages. For example, every ArcObjects symbol has an accompanying property page, but a custom symbol can be created without a property page. In this case, the symbol can be used programmatically as required and functions as expected. The lack of a property page, however, limits user interaction with the symbol and also highlights the symbol as a nonstandard object to the user.
Creating property pages and property sheets
Property pages are found throughout many applications, development environments, and technologies. Developing a property page for the ArcGIS framework requires the implementation of a certain set of standard interfaces. This may be different from techniques you have used previously.
In ArcObjects, there are different techniques used by different development environments to create property pages. ArcObjects uses a standard Component Object Model (COM) design whereby one or many property pages are contained by a property sheet. The property sheet is a dialog box that relates to a certain object or set of objects. Each property page on the property sheet contains controls to view and change the values of a set of related properties or to execute related methods on the object or objects.
The element Properties dialog box in the following screen shot for a FillShapeElement is a property sheet containing many property pages, each providing access to a related set of properties of a FillShapeElement:
The range of property pages displayed on a particular property sheet is generally determined dynamically, using a combination of mechanisms. Sometimes a property sheet contains a list of the class identifiers (CLSIDs) for all the property pages it needs to display at run time. This list of pages can be built dynamically at run time by reading a component category. In the previous example, the property sheet for a FillShapeElement class checks which property pages to display by reading the ESRI Element Property Pages component category.
Many property sheets determine their member property pages at run time by using component categories. For example, in the following screen shot, the possible property pages for elements are found in the ESRI Element Property Pages component category:
The same element property sheet is used for all the element classes and is, therefore, context sensitive. The ESRI Element Property Pages category shows a number of property pages displayed according to context—that is, depending on the type of element selected.
So how does the element property sheet determine which particular property pages apply to the type of element selected? The answer lies in the property pages themselves. The property sheet queries each property page whether or not it applies to a particular object and displays only the pages that apply. For more information on how this mechanism works, see the Property page interfaces section.
This model of property sheets and pages is applicable to many customization tasks. In many cases, it is likely that a property sheet already exists for the kind of class you are creating, and you simply need to create a property page to be displayed in this property sheet by ensuring your property page is registered with the appropriate component category and applies to the appropriate kind of object.
When creating custom objects, you can create a custom property page to be displayed on an existing property sheet.
You can also instantiate a new property sheet and add any required property pages to it. For more information see the Displaying a property sheet section.
Embedded property pages
In the model thus far, many property pages all apply to a given class. For example, the property sheet for an instance of the LineElement class displays both the Symbol and the Size and Position property pages, as both apply to the LineElement class.
In some cases, the display of property pages is more complex. A property sheet may display one of a number of property pages, which are mutually exclusive and depend on the underlying class type.
For example, in the Color Browser property sheet (on the Select Color dialog box) shown in the following screen shot, a combo box is displayed from which you can select different color models. Each color model is represented in ArcObjects by a different color class: CMYKColor, GrayColor, HLSColor, HSVColor, and RGBColor. Each class has an applicable property page, which is displayed when the appropriate color model is selected in the Color Browser property sheet.
When you select a different color model on the Color Browser property sheet, a different embedded property page is displayed, and the Color Browser creates a new class of the selected type. The properties of the new color object are set to the nearest approximation of the last selected color. When you click OK in the Select Color dialog box, this new color object is applied to the object being edited.
Embedded property pages are used to handle such situations—these property pages are designed to be contained inside other property pages or property sheets. Creating an embedded property sheet requires a bit more coding than a standard property sheet, as described in the following sections.
Generally, embedded property pages for use on a particular page or sheet are registered to a particular component category. For example, on the Color Browser, embedded property pages found in the ESRI Color Property Pages category are displayed. All property pages in such a category are considered mutually exclusive.
The Color Browser is a property sheet on which a number of embedded property pages are displayed. When a different color model in the top combo box is selected, one of a number of embedded property pages is displayed. When you select a new color model and the new page is displayed, the visual characteristics of the color from the previous page are preserved.
In most cases, certain properties from the object being edited by one property page can be transferred to the object being edited by the new property page—for example, the Color Browser sets an approximation of the last selected color to the newly selected property page.
Another example of an embedded property page is found on the Symbology property page of a layer. In this case, the embedded property pages are displayed within another property page. A different embedded property page is displayed, depending on the type of renderer selected on the containing property page.
Property page interfaces
There are five interfaces you can use when creating a property page, all of which are defined in the ESRI.ArcGIS.Framework assembly. For .NET development, focus on the following interfaces:
- IComPropertyPage—This ArcObjects interface was designed specifically for non-C++ developers. It includes similar functionality to the standard property page interface defined by Microsoft for COM implementation in Windows.
- IComPropertyPage2—This ArcObjects interface provides extra functionality that gives the property page the ability to cancel the property sheet. Implementing this interface is optional, depending on whether or not this functionality is required. If you choose to implement it, you must also implement IComPropertyPage. Since most members of IComPropertyPage and IComPropertyPage2 are common, you can delegate the work of these methods to secondary functions.
- IComEmbeddedPropertyPage—This ArcObjects interface provides additional functionality required by embedded property pages in ArcObjects.
The remaining two interfaces, IPropertyPage and IPropertyPageContext, are generally used along with the Active Template Library (ATL) implementation in Visual C++.
The interfaces you implement to create a property page will vary according to the development environment and the type of property page being created.
Throughout ArcObjects property sheets, the use of IPropertyPage and IPropertyPageContext is superseded by the use of IComPropertyPage and IComEmbeddedPropertyPage, as they are more flexible for third-party developers. However, you may come across property sheets that expect a property page to implement IPropertyPage and IPropertyPageContext. In this case, you may want to implement both sets of interfaces. Since the IPropertyPage, IPropertyPageContext, IComPropertyPage, and IComEmbeddedPropertyPage interfaces share many members, you can write generic functions that can be called from all interfaces.
In addition to the interfaces noted here, there are a few specialist property page interfaces to consider implementing if you're creating certain types of property pages. See the following:
- Implement IRendererPropertyPage if you're creating a property page for a custom renderer.
- Implement ISymbolPropertyPage if you're creating a property page for a custom symbol.
Do not implement IDataConnectionPropertyPage, IDataConnectionPropertyPage2, or IQueryPropertyPage, as these interfaces do not indicate a complete property page and are designed for internal use only.
Property sheet passes a cloned object
A property sheet will clone its target object before passing it to a property page. This allows the property sheet to discard the changes made by all the property pages to the target object if you cancel the property sheet.
Your application may require a customized property sheet. This may be because you created a component for which no suitable property sheet exists in the ArcGIS framework, or you need to display a number of property pages together and you want your custom property sheet to be extensible.
The ArcObjects ComPropertySheetClass allows you to create a property sheet, and it gives the sheet an editable object.
See Also:
How to create property pages and property sheetsSample: Layer property page and property sheet
| 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 |