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_pPageSite | IPropertyPage interface pointer used to access the filter's property information. |
| m_hwnd | Window handle for the property page. |
| m_Dlg | Dialog box window handle for the property page. |
| m_bDirty | Flag to determine whether anything has changed. |
| m_TitleId | Resource identifier for the property page title. |
| m_DialogId | Resource identifier for the dialog box. |
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. |
Creates the property page dialog box.
HRESULT Activate(
HWND hwndParent,
LPCRECT prect,
BOOL fModal
);
Returns E_OUTOFMEMORY if the dialog box creation fails, or E_UNEXPECTED if a property page already exists.
This member function implements the OLE 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.
Applies current property page values to the underlying object.
HRESULT Apply(void);
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.
This member function implements the OLE 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.
Constructs a CBasePropertyPage object.
CBasePropertyPage(
TCHAR *pName,
LPUNKNOWN pUnk,
int DialogId,
int TitleId
);
This constructor sets the CBasePropertyPage data members as follows:
Destroys the window created with CBasePropertyPage::Activate.
HRESULT Deactivate(void);
Returns E_UNEXPECTED if the data member m_hwnd does not contain a Window handle for the property page.
This member function implements the OLE IPropertyPage::Deactivate method. It calls the virtual CBasePropertyPage::OnDeactivate member function and then destroys the property page dialog box.
Returns information about the property page.
HRESULT GetPageInfo(
LPPROPPAGEINFO pPageInfo
);
Returns E_OUTOFMEMORY if the function cannot allocate memory for the property page title.
This member function implements the OLE 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.
Invokes Help in response to user request.
HRESULT Help(
LPCWSTR lpszHelpDir
);
Returns E_NOTIMPL by default.
This member function implements the OLE 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.
Indicates whether the property page has changed since activated or since the most recent call to CBasePropertyPage::Apply.
HRESULT IsPageDirty(void);
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.
This member function implements the OLE IPropertyPage::IsPageDirty method. It returns the value of the m_bDirty data member.
Positions and resizes the property page dialog box within the frame.
HRESULT Move(
LPCRECT prect
);
Returns E_UNEXPECTED if the m_hwnd data member does not contain a Window handle for the property page.
This member function implements the OLE 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.
Increments the reference count for an interface.
ULONG NonDelegatingAddRef( );
Returns the object's reference count.
This member function implements the INonDelegatingUnknown::NonDelegatingAddRef method. It increments the owning filter's reference count.
Returns an interface and increments the reference count.
HRESULT NonDelegatingQueryInterface(
REFIID riid,
void ** ppv
);
Returns a pointer to the interface.
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.
Decrements the reference count for an interface.
ULONG NonDelegatingRelease( );
Returns the reference count.
This member function implements the INonDelegatingUnknown::NonDelegatingRelease method. It releases a reference count to the owning filter.
Called when the property page is activated.
virtual HRESULT OnActivate(void);
Returns NOERROR by default. The overriding member function should return a valid HRESULT value.
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 SetDlgItemMessage 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);
}
Called when the user applies changes to the property page.
virtual HRESULT OnApplyChanges(void);
Returns NOERROR by default. The overriding member function should return a valid HRESULT value.
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.
Called when the property page is connected to the filter.
virtual HRESULT OnConnect(
IUnknown *pUnknown
);
Returns NOERROR by default. The overriding member function should return a valid HRESULT value.
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;
}
Called when the property page is dismissed.
virtual HRESULT OnDeactivate(void);
Returns NOERROR by default. The overriding member function should return a valid HRESULT value.
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.
Called when the property page is disconnected from the owning filter.
virtual HRESULT OnDisconnect(void);
Returns NOERROR by default. The overriding member function should return a valid HRESULT value.
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;
}
Called when a message is sent to the property page dialog box.
virtual BOOL OnReceiveMessage(
HWND hwnd,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
);
By default, returns the value returned by the Win32 DefWindowProc function.
The default implementation of this member function calls DefWindowProc with the supplied parameters. Override this member function for special handling of messages.
Provides the property page with an IUnknown pointer for objects associated with this property page.
HRESULT SetObjects(
ULONG cObjects,
LPUNKNOWN *ppUnk
);
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.
This member function implements the OLE 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.
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
);
Returns E_UNEXPECTED if if the m_pPageSite data member has not been initialized with a pointer to the filter's property page.
This member function implements the OLE 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.
Makes the property page dialog box visible or invisible.
HRESULT Show(
UINT nCmdShow
);
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).
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 OLE IPropertyPage::Show method. This is called just before exiting the CBasePropertyPage::Activate member function with the nCmdShow SHOW_NORMAL value.
Provides a pointer to an MSG structure that specifies a keystroke to process.
HRESULT TranslateAccelerator(
LPMSG lpMsg
);
Returns E_NOTIMPL by default.
This member function implements the OLE 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.