CBasePropertyPage Class

CBasePropertyPage class hierarchy

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® Windows Media™ Player 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

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

CBasePropertyPage Constructs a CBasePropertyPage object.

Overridable Member Functions

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

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

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 Retrieves 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.

Syntax

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 Value

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.

Syntax

HRESULT Apply(void);

Return Value

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.

Syntax

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

Parameters

pName
Pointer to the 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.

Syntax

HRESULT Deactivate(void);

Return Value

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

Retrieves information about the property page.

Syntax

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 Value

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.

Syntax

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 Value

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.

Syntax

HRESULT IsPageDirty(void);

Return Value

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.

Syntax

HRESULT Move(
    LPCRECT prect
    );

Parameters

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

Return Value

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.

Syntax

ULONG NonDelegatingAddRef(void);

Return Value

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

Retrieves an interface and increments the reference count.

Syntax

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

Parameters

riid
Reference identifier.
ppv
Address of a pointer to the interface.

Return Value

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.

Syntax

ULONG NonDelegatingRelease(void);

Return Value

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.

Syntax

virtual HRESULT OnActivate(void);

Return Value

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.

Syntax

virtual HRESULT OnApplyChanges(void);

Return Value

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.

Syntax

virtual HRESULT OnConnect(
    IUnknown *pUnknown
    );

Parameters

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

Return Value

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.

Syntax

virtual HRESULT OnDeactivate(void);

Return Value

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.

Syntax

virtual HRESULT OnDisconnect(void);

Return Value

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 you 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.

Syntax

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 Value

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.

Syntax

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
Address of a pointer to a single IUnknown interface 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 Value

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.
The caller must provide the property page with this object before calling CBasePropertyPage::Activate, and should call 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.

Syntax

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 Value

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.

Syntax

HRESULT Show(
    UINT nCmdShow
    );

Parameters

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

Return Value

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.

Syntax

HRESULT TranslateAccelerator(
    LPMSG lpMsg
    );

Parameters

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

Return Value

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.

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.

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.

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.

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	Retrieves 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.