## CBasePropertyPage Class

Property pages can be implemented on filters to provide access to custom properties on the filter. This can be useful for developing and debugging the filter, because the Filter Graph Editor displays these property pages. Also, the Microsoft® ActiveMovie Control queries filters in its underlying filter graph for the property pages they support and exposes them to the user. A good example is the video renderer, which exposes quality management information (such as frame rate) through a property page.

This class provides the framework for a property page associated with a filter and implements the IPropertyPage interface. A property page is a Component Object Model (COM) object, which should be created with a resource ID for a dialog box that will be loaded when required. It should also be given a resource ID for a title string when created.

In addition to implementing the IPropertyPage interface methods, this class provides several virtual member functions that can be overridden and specialized by the derived class (they return NOERROR by default). These virtual member functions are called at specific events, such as when the property page is activated or deactivated, connected or disconnected, when the changes to properties are to be applied, or when messages to the dialog box are received.

A filter exposing custom property pages should also expose the same functionality to an application through a custom interface. Otherwise, an application has no way to control the filter without displaying the property page. For example, the video renderer supports the IQualProp interface to access the same quality management information. In fact, the renderer property page uses that interface to get the information for its property page. To make it easier for applications to access their custom interfaces, filters should also implement their custom interfaces in a plug-in distributor (PID), which is an object that is aggregated with the filter graph manager. Typically, the PID implements its associated filter's interface by simply passing calls through from the application to the filter interface.

Protected Data Members

Name | Description
m_bDirty | Flag to determine whether anything has changed.
m_DialogId | Resource identifier for the dialog box.
m_Dlg | Dialog box window handle for the property page.
m_hwnd | Window handle for the property page.
m_pPageSite | IPropertyPage interface pointer used to access the filter's property information.
m_TitleId | Resource identifier for the property page title.

Member Functions

Name | Description
CBasePropertyPage | Constructs a CBasePropertyPage object.

Overridable Member Functions

Name | Description
OnActivate | Called when the property page is activated.
OnApplyChanges | Called when the user applies changes to the property page.
OnConnect | Called when the property page is connected to the filter.
OnDeactivate | Called when the property page is dismissed.
OnDisconnect | Called when the property page is disconnected from the owning filter.
OnReceiveMessage | Called when a message is sent to the property page dialog box window.

Implemented INonDelegatingUnknown Methods

Name | Description
NonDelegatingAddRef | Default implementation increments the owning filter's reference count.
NonDelegatingQueryInterface | Called to retrieve CBasePropertyPage interfaces. Override this member function to pass out pointers to any interfaces added by the derived class.
NonDelegatingRelease | Default implementation decrements the owning filter's reference count.

Implemented IPropertyPage Methods

Name | Description
Activate | Creates a dialog box window for the property page.
Apply | Applies current property page values to the underlying object.
Deactivate | Destroys the window created with CBasePropertyPage::Activate.
GetPageInfo | Returns information about the property page.
Help | Invokes Help in response to user request.
IsPageDirty | Indicates whether the property page has changed since activated or since the most recent call to CBasePropertyPage::Apply.
Move | Positions and resizes the property page dialog box within the frame.
SetObjects | Provides the property page with an array of IUnknown pointers for objects associated with this property page.
SetPageSite | Initializes a property page and provides the page with a pointer to the IPropertyPageSite interface through which the property page communicates with the property frame.
Show | Makes the property page dialog box visible or invisible.
TranslateAccelerator | Provides a pointer to an MSG structure that specifies a keystroke to process.

###

CBasePropertyPage::Activate

CBasePropertyPage Class

Creates the property page dialog box.

HRESULT Activate(
HWND hwndParent,
LPCRECT prect,
BOOL fModal
);

##### Parameters

hwndParent
  Handle to the parent window of the dialog box.
prect
  Pointer to the RECT structure that contains the dialog box's screen position.
fModal
  Value that specifies a modal dialog box if TRUE, or a modeless dialog box if FALSE.

##### Return Values

Returns E_OUTOFMEMORY if the dialog box creation fails, or E_UNEXPECTED if a property page already exists.

##### Remarks

This member function implements the COM IPropertyPage::Active method, which creates a dialog box for the property page (without a frame, caption, system menu, or controls) using hwndParent as the parent window and prect as the positioning rectangle.

The property page maintains the window handle created in this process, which it uses to destroy the dialog box within CBasePropertyPage::Deactivate.

###

CBasePropertyPage::Apply

CBasePropertyPage Class

Applies current property page values to the underlying object.

HRESULT Apply(void);

##### Return Values

Returns E_UNEXPECTED if CBasePropertyPage::SetObjects has not been called or if the m_pPageSite data member has not been initialized with a pointer to the filter's property page.

##### Remarks

This member function implements the COM IPropertyPage::Apply method. The object to be changed is provided through a previous call to CBasePropertyPage::SetObjects. This should be the filter's IUnknown interface. Therefore, this member function should not fail because of nonexistent interfaces.

This member function sets the m_bDirty data member to FALSE and calls the virtual CBasePropertyPage::OnApplyChanges member function, which should be overridden in the derived class to apply the changes to the properties.

###

CBasePropertyPage::CBasePropertyPage

CBasePropertyPage Class

Constructs a CBasePropertyPage object.

CBasePropertyPage(
TCHAR *pName,
LPUNKNOWN pUnk,
int DialogId,
int TitleId
);

##### Parameters

pName
  Name of the property page object for debugging purposes.
pUnk
  Pointer to the COM delegating object.
DialogId
  Resource ID for the dialog box.
TitleId
  Resource ID for the dialog box title.

##### Remarks

This constructor sets the CBasePropertyPage data members as follows:

- m_DialogId is set to DialogId.
- m_TitleId is set to TitleId.
- m_hwnd is set to NULL.
- m_Dlg is set to NULL.
- m_pPageSite is set to NULL.
- m_bDirty is set to FALSE.

###

CBasePropertyPage::Deactivate

CBasePropertyPage Class

Destroys the window created with CBasePropertyPage::Activate.

HRESULT Deactivate(void);

##### Return Values

Returns E_UNEXPECTED if the data member m_hwnd does not contain a Window handle for the property page.

##### Remarks

This member function implements the COM IPropertyPage::Deactivate method. It calls the virtual CBasePropertyPage::OnDeactivate member function and then destroys the property page dialog box.

###

CBasePropertyPage::GetPageInfo

CBasePropertyPage Class

Returns information about the property page.

HRESULT GetPageInfo(
LPPROPPAGEINFO pPageInfo
);

##### Parameters

pPageInfo
  Pointer to the caller-allocated PROPPAGEINFO structure in which the property page stores its page information. All allocations stored in this structure become the caller's responsibility.

##### Return Values

Returns E_OUTOFMEMORY if the function cannot allocate memory for the property page title.

##### Remarks

This member function implements the COM IPropertyPage::GetPageInfo method. It calls the GetDialogSize function to obtain the dialog box size and sets it to a default value in case this call fails.

###

CBasePropertyPage::Help

CBasePropertyPage Class

Invokes Help in response to user request.

HRESULT Help(
LPCWSTR lpszHelpDir
);

##### Parameters

lpszHelpDir
  Pointer to the string under the HelpDir key in the property page's CLSID information in the registry. If HelpDir does not exist, this will be the path found in the InProcServer32 entry minus the server file name.

##### Return Values

Returns E_NOTIMPL by default.

##### Remarks

This member function implements the COM IPropertyPage::Help method, but only as a placeholder. The function does nothing but return E_NOTIMPL.

Calls to this member function must occur between calls to CBasePropertyPage::Activate and CBasePropertyPage::Deactivate.

If the page fails this member function (such as E_NOTIMPL), the frame will attempt to use the pszHelpFile and dwHelpContext fields of the PROPPAGEINFO structure obtained through CBasePropertyPage::GetPageInfo. Therefore, the derived class should either implement CBasePropertyPage::Help or return Help information through CBasePropertyPage::GetPageInfo.

###

CBasePropertyPage::IsPageDirty

CBasePropertyPage Class

Indicates whether the property page has changed since activated or since the most recent call to CBasePropertyPage::Apply.

HRESULT IsPageDirty(void);

##### Return Values

Returns S_OK if the value state of the property page is dirty, that is, it has changed and is different from the state of the objects. Returns S_FALSE if the value state of the page has not changed and is current with that of the objects.

##### Remarks

This member function implements the COM IPropertyPage::IsPageDirty method. It returns the value of the m_bDirty data member.

###

CBasePropertyPage::Move

CBasePropertyPage Class

Positions and resizes the property page dialog box within the frame.

HRESULT Move(
LPCRECT prect
);

##### Parameters

prect
  Pointer to the RECT structure containing the positioning information for the property page dialog box.

##### Return Values

Returns E_UNEXPECTED if the m_hwnd data member does not contain a Window handle for the property page.

##### Remarks

This member function implements the COM IPropertyPage::Move method by calling the Microsoft® Win32® MoveWindow function. This member function is called from the CBasePropertyPage::Activate member function to position the property page dialog box.

###

CBasePropertyPage::NonDelegatingAddRef

CBasePropertyPage Class

Increments the reference count for an interface.

ULONG NonDelegatingAddRef( );

##### Return Values

Returns the object's reference count.

##### Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingAddRef method. It increments the owning filter's reference count.

###

CBasePropertyPage::NonDelegatingQueryInterface

CBasePropertyPage Class

Returns an interface and increments the reference count.

HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);

##### Parameters

riid
  Reference identifier.
ppv
  Pointer to the interface.

##### Return Values

Returns E_POINTER if ppv is invalid. Returns NOERROR if the query is successful or E_NOINTERFACE if it is not.

##### Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingQueryInterface method and passes out references to the IPropertyPage interface. It then calls the CUnknown::NonDelegatingQueryInterface base class member function. Override this class to return other interfaces on the object in the derived class.

###

CBasePropertyPage::NonDelegatingRelease

CBasePropertyPage Class

Decrements the reference count for an interface.

ULONG NonDelegatingRelease( );

##### Return Values

Returns the reference count.

##### Remarks

This member function implements the INonDelegatingUnknown::NonDelegatingRelease method. It releases a reference count to the owning filter.

###

CBasePropertyPage::OnActivate

CBasePropertyPage Class

Called when the property page is activated.

virtual HRESULT OnActivate(void);

##### Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

##### Remarks

This member function is called from the CBasePropertyPage::Activate member function to notify the derived class when the property page is displayed. Override this member function to initialize values in the dialog box. This can be done by calling the Win32 SetDlgItemText function with data member values previously initialized when the property page was connected (in the overridden CBasePropertyPage::OnConnect member function).

For example, the Vidprop.cpp file in the sample video renderer, SampVid, does this as follows:

    // Set the text fields in the property page

    HRESULT CQualityProperties::OnActivate()
    {
        SetEditFieldData();
        return NOERROR;
    }

    // Initialize the property page fields

    void CQualityProperties::SetEditFieldData()
    {
        ASSERT(m_pQualProp);
        TCHAR buffer[50];

        wsprintf(buffer,"%d", m_iDropped);
        SendDlgItemMessage(m_Dlg, IDD_QDROPPED, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
        wsprintf(buffer,"%d", m_iDrawn);
        SendDlgItemMessage(m_Dlg, IDD_QDRAWN, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
        wsprintf(buffer,"%d.%02d", m_iFrameRate/100, m_iFrameRate%100);
        SendDlgItemMessage(m_Dlg, IDD_QAVGFRM, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
        wsprintf(buffer,"%d", m_iFrameJitter);
        SendDlgItemMessage(m_Dlg, IDD_QJITTER, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
        wsprintf(buffer,"%d", m_iSyncAvg);
        SendDlgItemMessage(m_Dlg, IDD_QSYNCAVG, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
        wsprintf(buffer,"%d", m_iSyncDev);
        SendDlgItemMessage(m_Dlg, IDD_QSYNCDEV, WM_SETTEXT, 0, (DWORD) (LPSTR) buffer);
    }

###

CBasePropertyPage::OnApplyChanges

CBasePropertyPage Class

Called when the user applies changes to the property page.

virtual HRESULT OnApplyChanges(void);

##### Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

##### Remarks

Override this member function if your property page allows users to set property values. When this member function is called, process the changed properties. For example, set appropriate data members in the derived class to the new values, or call methods in the filter to set the properties. The overriding member function is responsible for calling CBasePropertyPage::IsPageDirty to set the m_bDirty data member to TRUE if the properties in the object do not reflect those in the property page when this member function exits.

###

CBasePropertyPage::OnConnect

CBasePropertyPage Class

Called when the property page is connected to the filter.

virtual HRESULT OnConnect(
IUnknown *pUnknown
);

##### Parameters

pUnknown
  IUnknown interface of the filter associated with the property page.

##### Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

##### Remarks

This member function is called from the CBasePropertyPage::SetObjects member function with the ppUnk parameter of that member function, which should be the filter's IUnknown interface. Override this member function to acquire property values to be sent to the property page dialog box later (in CBasePropertyPage::OnActivate).

The following excerpt from the sample video renderer (SampVid) Vidprop.cpp file illustrates the use of this member function.

    // Give us the filter to communicate with

    HRESULT CQualityProperties::OnConnect(IUnknown *pUnknown)
    {
        ASSERT(m_pQualProp == NULL);

        // Ask the renderer for its IQualProp interface

        HRESULT hr = pUnknown->QueryInterface(IID_IQualProp,(void **)&m_pQualProp);
        if (FAILED(hr)) {
            return E_NOINTERFACE;
        }

        ASSERT(m_pQualProp);

        // Get quality data for the page

        m_pQualProp->get_FramesDroppedInRenderer(&m_iDropped);
        m_pQualProp->get_FramesDrawn(&m_iDrawn);
        m_pQualProp->get_AvgFrameRate(&m_iFrameRate);
        m_pQualProp->get_Jitter(&m_iFrameJitter);
        m_pQualProp->get_AvgSyncOffset(&m_iSyncAvg);
        m_pQualProp->get_DevSyncOffset(&m_iSyncDev);
        return NOERROR;
    }

###

CBasePropertyPage::OnDeactivate

CBasePropertyPage Class

Called when the property page is dismissed.

virtual HRESULT OnDeactivate(void);

##### Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

##### Remarks

This member function is called from the CBasePropertyPage::Deactivate member function when the user closes the property page. Override this member function to handle any special requirements at that time.

###

CBasePropertyPage::OnDisconnect

CBasePropertyPage Class

Called when the property page is disconnected from the owning filter.

virtual HRESULT OnDisconnect(void);

##### Return Values

Returns NOERROR by default. The overriding member function should return a valid HRESULT value.

##### Remarks

This member function is called from the CBasePropertyPage::SetObjects member function when the property page is disconnected from the filter. Override this member function to handle any special requirements at that time, such as releasing reference counts on underlying property interfaces.

The following example, from the Vidprop.cpp file in the sample video renderer, SampVid, demonstrates an implementation of this member function in a derived class.

    // Release any IQualProp interface we have

    HRESULT CQualityProperties::OnDisconnect()
    {
        // Release the interface

        if (m_pQualProp == NULL) {
            return E_UNEXPECTED;
        }

        m_pQualProp->Release();
        m_pQualProp = NULL;
        return NOERROR;
    }

###

CBasePropertyPage::OnReceiveMessage

CBasePropertyPage Class

Called when a message is sent to the property page dialog box.

virtual BOOL OnReceiveMessage(
HWND hwnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);

##### Parameters

hwnd
  Window procedure that received the message.
uMsg
  Message.
wParam
  Additional message information. This parameter's content depends on the value of the uMsg parameter.
lParam
  Additional message information. This parameter's content depends on the value of the uMsg parameter.

##### Return Values

By default, returns the value returned by the Win32 DefWindowProc function.

##### Remarks

The default implementation of this member function calls DefWindowProc with the supplied parameters. Override this member function for special handling of messages.

###

CBasePropertyPage::SetObjects

CBasePropertyPage Class

Provides the property page with an IUnknown pointer for objects associated with this property page.

HRESULT SetObjects(
ULONG cObjects,
LPUNKNOWN *ppUnk
);

##### Parameters

cObjects
  Number of IUnknown pointers in the array pointed to by ppUnk. This number should be 1 or 0. If it is 0, the property page must release any pointers previously passed to this method.
ppUnk
  Pointer to a single IUnknown interface pointer identifying a unique object affected by the property sheet in which this (and possibly other) property page is displayed. The property page must cache this pointer by calling IUnknown::AddRef.

##### Return Values

Returns E_POINTER if ppUnk is null, E_UNEXPECTED if cObjects is greater than 1, and otherwise returns the value returned by the CBasePropertyPage::OnConnect or CBasePropertyPage::OnDisconnect member function that it calls.

##### Remarks

This member function implements the COM IPropertyPage::SetObjects method. This member function calls the virtual CBasePropertyPage::OnConnect member function when the cObjects value is 1, or the virtual CBasePropertyPage::OnDisconnect member function when the cObjects value is 0. Override these virtual member functions to acquire (by calling IUnknown::AddRef) or release (by calling IUnknown::Release) interfaces to which the property page applies.

Note that the caller must provide the property page with this object before calling CBasePropertyPage::Activate, and should call CBasePropertyPage::SetObjects with 0-v as the parameter when deactivating the page or when releasing the object entirely.

This member function allows only one object to be associated with the property page.

###

CBasePropertyPage::SetPageSite

CBasePropertyPage Class

Initializes a property page and provides the page with a pointer to the IPropertyPageSite interface through which the property page communicates with the property frame.

HRESULT SetPageSite(
LPPROPERTYPAGESITE pPageSite
);

##### Parameters

pPageSite
  Pointer to the IPropertyPageSite interface of the page site that manages and provides services to this property page within the entire property sheet.

##### Return Values

Returns E_UNEXPECTED if if the m_pPageSite data member has not been initialized with a pointer to the filter's property page.

##### Remarks

This member function implements the COM IPropertyPage::SetPageSite method. When passed an IPropertyPageSite interface, it reference counts the interface and assigns it to m_pPageSite. When passed a null value, it releases the reference count on the IPropertyPageSite interface.

###

CBasePropertyPage::Show

CBasePropertyPage Class

Makes the property page dialog box visible or invisible.

HRESULT Show(
UINT nCmdShow
);

##### Parameters

nCmdShow
  Command describing whether to become visible. Only SW_SHOWNORMAL, SW_SHOW, and SW_HIDE are accepted.

##### Return Values

Returns E_UNEXPECTED if the data member m_hwnd does not contain a Window handle for the property page. Returns E_INVALIDARG if the nCmdShow parameter is not equal to SW_SHOW or SW_SHOWNORMAL (show) or SW_HIDE (hide).

##### Remarks

If the page is made visible, the page should set the focus to itself, specifically to the first property on the page. This member function implements the COM IPropertyPage::Show method. This is called just before exiting the CBasePropertyPage::Activate member function with the nCmdShow SHOW_NORMAL value.

###

CBasePropertyPage::TranslateAccelerator

CBasePropertyPage Class

Provides a pointer to an MSG structure that specifies a keystroke to process.

HRESULT TranslateAccelerator(
LPMSG lpMsg
);

##### Parameters

lpMsg
  Pointer to the MSG structure describing the keystroke to process.

##### Return Values

Returns E_NOTIMPL by default.

##### Remarks

This member function implements the COM IPropertyPage::TranslateAccelerator method. Calls to this member function must occur after a call to CBasePropertyPage::Activate and before the corresponding call to CBasePropertyPage::Deactivate. Override this member function to implement keyboard accelerators for the property page.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.