Programming Reference: ODSettingsExtension

# Programming Reference

## ODSettingsExtension

Class Definition File | Settings.idl
Class C++ Binding | Settings.xh

Class Hierarchy

    SOMObject
       ODObject
          ODExtension
             ODSettingsExtension

Description

An object of the ODSettingsExtension class represents a set of Properties notebook that a part editor can create and display.

The Properties notebook provides access only to the standard information properties that all OpenDoc parts have. To allow the user to access properties specific to your parts, you can create a settings extension object to add additional pages to the notebook.

You use a subclass of ODSettingsExtension to create and insert additional pages into the Properties notebook by overriding the ShowSettingsPages method. Once you implement it, OpenDoc accesses your settings extension object by calling your part's AcquireExtension method, which returns a reference to the extension object.

For more information related to extension objects, see the class description for "ODExtension".

Methods

The methods defined by the ODSettingsExtension class include:

- AddNotebookSheet (OS/2)
- InitSettingsExtension
- ShowSettingsPages (AIX)
- ShowSettingsPages (OS/2)
- ShowSettingsPages (Windows)

Overridden Methods | There are no methods overridden by the ODSettingsExtension class.

### AddNotebookSheet (OS/2)

This method stores information for sheets added to the property notebook for an application part.

Signature

    void AddNotebookSheet (HWND pageHwnd,
                           ULONG pageId)

Parameters

pageHwnd (HWND) - input

  A handle to the newly created page.

pageId (ULONG) - input

  A page id for the newly created page.

Remarks

A part developer uses this method to notify ODInfo about additional pages that will be added to the property notebook. For each sheet added, the part is required to pass the handle to the page and its id. On OS/2, ODInfo needs this information so it can propagate global messages from the property notebook to each sheet.

### InitSettingsExtension

This method initializes this settings extension object.

Signature

    void InitSettingsExtension (ODPart *owner)

Parameters

owner (ODPart *) - input

  A reference to this settings extension's base object.

Returns

None.

Remarks

This method is not called directly to initialize this settings extension object, but is called by a subclass-specific initialization method. By convention, every subclass of ODSettingsExtension should have an override method that is called when an instance of that subclass is created. The override method may have additional parameters beyond those of the inherited InitSettingsExtension method. The override method should call the inherited InitSettingsExtension method at the beginning of its implementation. The inherited InitSettingsExtension method in turn calls the InitExtension method associated with this settings extension's base object ( "ODExtension") to prepare this settings extension for use.

If you subclass ODSettingsExtension, your subclass-specific initialization method, rather than its somInit method, should handle any initialization code that can potentially fail. For example, your initialization method may attempt to allocate memory for your settings extension.

Override Policy

If you subclass ODSettingsExtension, you must override this method. Your override method must call its inherited method at the beginning of your implementation.

Related Methods

- ODExtension::InitExtension

### ShowSettingsPages (AIX)

This method provides the interface for the part developer to add additional pages to the property notebook.

Signature

    void ShowSettingsPages (ODFacet *facet,
                            ODNotebook *notebook)

Parameters

facet (ODFacet *) - input

  A pointer to the facet associated with the part.

notebook (ODNotebook *) - input

  A handle to the property page notebook.

Remarks

A part developer can add additional pages to the property page notebook as follows:

- Derive from ODPropertyPage and override the GetName, CreateWidget, Ok, Help, and Cancel methods.
- Pass an instance of the derived class to the notebook->AddPage method.

Override Policy

If you subclass ODSettingsExtension, you must override this method. Your override method must call its inherited method at the beginning of your implementation.

### ShowSettingsPages (OS/2)

This method provides the interface for the part developer to add additional pages to the property notebook.

Signature

    void ShowSettingsPages (ODFacet *facet,
                            HWND parent,
                            ULONG *notebookID)

Parameters

facet (ODFacet *) - input

  A pointer to the facet associated with the part.

parent (HWND) - input

  A handle to the property dialog.

notebookID (ULONG) - input

  The resource id of the property dialog's notebook child.

Remarks

A part developer can add additional pages to the property page notebook as follows:

- Add the platform specific code to create a new page and associate it with the property notebook.
- Call the AddNotebookSheet method to save the new page information.

Override Policy

If you subclass ODSettingsExtension, you must override this method. Your override method must call its inherited method at the beginning of your implementation.

### ShowSettingsPages (Windows)

This method provides the interface for the part developer to add additional pages to the property notebook.

Signature

    void ShowSettingsPages (ODFacet *facet,
                            HWND hPropSheetDlg)

Parameters

facet (ODFacet *) - input

  A pointer to the facet associated with the part.

hPropSheetDlg (HWND) - input

  A handle to the property sheet dialog.

Remarks

A part developer can add additional pages to the property page notebook as follows:

- Add the platform specific code to create a new page and add it to the property notebook.

Override Policy

If you subclass ODSettingsExtension, you must override this method. Your override method must call its inherited method at the beginning of your implementation.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]