CBasePropertyPage Class


		Index Topic Contents
	Previous Topic: CBasePin Class Next Topic: CBaseReferenceClock Class

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.
© 1998 Microsoft Corporation. All rights reserved. Terms of Use.
Top of Page

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.

Name	Description
CBasePropertyPage	Constructs a CBasePropertyPage object.

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.

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.

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.