CBaseControlWindow Class
The CBaseControlWindow class implements the IVideoWindow interface and controls external access to its associated filter. You must synchronize the CBaseControlWindow object with the filter by passing it a pointer to a critical section synchronization object. For more information about critical section synchronization objects, see the Platform SDK. The CBaseControlWindow class provides a number of methods that return property settings without dealing with this critical section. For example, calling CBaseControlWindow::get_AutoShow to retrieve the value of the m_bAutoShow data member locks the critical section. The filter might already have a locked internal critical section, however, which could violate the filter's lock hierarchy. Instead, calling the CBaseControlWindow::IsAutoShowEnabled member function returns the required value without affecting the critical section.
All CBaseControlWindow implemented IVideoWindow methods require that the filter be connected correctly with its upstream filter. For this reason, class objects require a synchronization pin, which you set by calling the CBaseControlWindow::SetControlWindowPin method. Whenever you call an IVideoWindow method, the CBaseControlWindow object checks that the pin is still connected.
Protected Data Members
m_bAutoShow Result when the state changes. m_bCursorHidden Determination of whether the cursor is displayed or hidden. m_BorderColour Color of the current window border. m_hwndDrain Window handle to which messages received are posted. m_hwndOwner Owning window. m_pFilter Pointer to the owning media filter. m_pInterfaceLock Externally defined critical section. m_pPin Control of the media types for connection.
Member Functions
CBaseControlWindow Constructs a CBaseControlWindow object. DoGetWindowStyle Retrieves either the typical or extended window styles. DoSetWindowStyle Sets the typical or extended window styles. GetBorderColour Retrieves the current border color. This is a helper member function. GetOwnerWindow Retrieves the owning window. This is a helper member function. IsAutoShowEnabled Retrieves information about whether the video window automatically appears when the rendering filter pauses or runs. IsCursorHidden Retrieves the current state of the m_bCursorHidden data member without locking the critical section. This is a helper member function. PossiblyEatMessage Distributes messages to the parent window. SetControlWindowPin Notifies the object of the pin to which it applies.
Implemented IVideoWindow Methods
get_AutoShow Retrieves the current AutoShow flag setting. get_BackgroundPalette Retrieves the realized palette in the background flag. get_BorderColor Retrieves the current border color. get_Caption Retrieves the current window caption. get_FullScreenMode Retrieves the current full-screen mode. get_Height Retrieves the current window height. get_Left Retrieves the current left window coordinate. GetMaxIdealImageSize Retrieves the maximum size of the ideal image. get_MessageDrain Retrieves the current message drain. GetMinIdealImageSize Retrieves the minimum size of the ideal image. get_Owner Retrieves the Microsoft® Win32® parent window handle. GetRestorePosition Retrieves the position to which the window will be restored when maximized or minimized. get_Top Retrieves the y-coordinate for the top of the window. get_Visible Retrieves the current visibility setting of the window. get_Width Retrieves the width of the window. GetWindowPosition Retrieves the current window coordinates. get_WindowState Retrieves the current state of the window. get_WindowStyle Retrieves the standard window styles. get_WindowStyleEx Retrieves the extended window styles. HideCursor Hides or displays the cursor. IsCursorHidden Retrieves the current state of the m_bCursorHidden data member. NotifyOwnerMessage Passes on messages that are sent to owning windows. put_AutoShow Sets the AutoShow property. put_BackgroundPalette Sets a flag to realize the palette in the background. put_BorderColor Sets the current border color. put_Caption Sets the current window caption. put_FullScreenMode Sets the full-screen mode. put_Height Sets the current window height. put_Left Sets the left coordinate for the window. put_MessageDrain Sets the message drain window. put_Owner Sets the Microsoft Win32 parent window handle. put_Top Sets the position for the top of the window. put_Visible Hides or shows the window. put_Width Sets the width of the window. put_WindowState Sets the state of the window. put_WindowStyle Sets the standard window styles. put_WindowStyleEx Sets the extended window styles. SetWindowForeground Sets the window in the foreground. SetWindowPosition Sets the window position.
CBaseControlWindow::CBaseControlWindow
Constructs a CBaseControlWindow object.
Syntax
CBaseControlWindow(
CBaseMediaFilter *pFilter,
CCritSec *pInterfaceLock,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
);
Parameters
- pFilter
- Pointer to the owning media filter object.
- pInterfaceLock
- Pointer to the critical section to use for locking.
- pName
- Pointer to the object description.
- pUnk
- Typical Component Object Model (COM) ownership.
- phr
- Pointer to the COM return value.
Return Value
No return value.
CBaseControlWindow::DoGetWindowStyle
Retrieves the current normal or extended window styles.
Syntax
HRESULT DoGetWindowStyle(
long *pStyle,
long WindowLong
);
Parameters
- pStyle
- Pointer to the appropriate styles.
- WindowLong
- Either GWL_STYLE or GWL_EXSTYLE.
Return Value
Returns an HRESULT value.
Remarks
This member function calls the Win32 GetWindowLong function to retrieve the window style. It is called by the CBaseControlWindow::get_WindowStyle and CBaseControlWindow::get_WindowStyleEx member functions.
CBaseControlWindow::DoSetWindowStyle
Changes the typical or extended window styles.
Syntax
HRESULT DoSetWindowStyle(
long Style,
long WindowLong
);
Parameters
- Style
- Appropriate window styles.
- WindowLong
- Either GWL_STYLE or GWL_EXSTYLE.
Return Value
Returns an HRESULT value.
Remarks
This member function calls the Win32 SetWindowLong function to set the window style, and then redisplays the window in the current position. This member function is called by the CBaseControlWindow::put_WindowStyle and CBaseControlWindow::put_WindowStyleEx member functions.
CBaseControlWindow::get_AutoShow
Retrieves the current AutoShow state flag.
Syntax
HRESULT get_AutoShow(
long *AutoShow
);
Parameters
- AutoShow
- Pointer to an Automation Boolean flag (0 is off, –1 is on).
Return Value
Returns an HRESULT value.
Remarks
This member function implements the IVideoWindow::get_AutoShow method. This property simplifies window display access for applications. If this is set to –1 (on), the window, which is typically hidden after connection of the filter, will be displayed automatically when the filter pauses or runs. The window should not be hidden when the filter stops, however. If this parameter is set to 0 (off), the window is made visible only when the application calls CBaseControlWindow::put_Visible or CBaseControlWindow::put_WindowState with the appropriate parameters.
This member function is meant to be called by external objects through the IVideoWindow interface, and therefore locks the critical section to synchronize with the associated filter. Call the CBaseControlWindow::IsAutoShowEnabled member function to retrieve this property if you are not calling from an external object.
CBaseControlWindow::get_BackgroundPalette
Retrieves the realized palette in the background flag.
Syntax
HRESULT get_BackgroundPalette(
long *pBackgroundPalette
);
Parameters
- pBackgroundPalette
- Pointer to an Automation Boolean flag (0 is off, –1 is on).
Return Value
Returns an HRESULT value.
Remarks
This member function implements the IVideoWindow::get_BackgroundPalette method. If a video will be played within another application or document, the application might want to use its own palette. It can ask that the video use the current foreground palette rather than its own by setting this flag to –1. If this is set to 0, the window will install and realize its own preferred palette. Note that asking the window to use a different palette will cause severe performance penalties.
CBaseControlWindow::get_BorderColor
Retrieves the current border color.
Syntax
HRESULT get_BorderColor(
long *Color
);
Parameters
- Color
- Pointer to the current border color.
Return Value
Returns an HRESULT value.
Remarks
An application can set a destination rectangle in which the video should be displayed. This rectangle is relative to the client area for the window. If this is done (the default is to always paint the entire window), there is a border surrounding the video. This property affects the color used by the border. Although the parameter is specified as a LONG type, it is actually a COLORREF value.
This member function is meant to be called by external objects through the IVideoWindow interface, and therefore locks the critical section to synchronize with the associated filter. Call the CBaseControlWindow::GetBorderColour member function to retrieve this property if not calling from an external object.
CBaseControlWindow::GetBorderColour
Retrieves the current window border color, m_BorderColour.
Syntax
COLORREF GetBorderColour(void);
Return Value
Returns the color of the border.
Remarks
An application can set a destination rectangle to display the video. This rectangle should be relative to the client area for the window. If this is done (the default is to always paint the entire window), there is an area that surrounds the video; that is, the border. The border color can be set through the CBaseControlWindow::put_BorderColor member function. This property affects the color of the border. Use this member function instead of CBaseControlWindow::get_BorderColor, unless you are calling this externally through the IVideoWindow::get_BorderColor method.
CBaseControlWindow::get_Caption
Retrieves the current window caption.
Syntax
HRESULT get_Caption(
BSTR *pstrCaption
);
Parameters
- pstrCaption
- Pointer to the current window caption.
Return Value
Returns an HRESULT value.
Remarks
Most top-level windows on a Windows-based desktop have a title (caption) associated with them. This property can be queried and set through the IVideoWindow interface. Any caption set will be visible only if the window has the WS_CAPTION style applied. If it does not, the caption can still be set (and retrieved), although it will not be visible to the user.
CBaseControlWindow::get_FullScreenMode
Retrieves the current full-screen mode.
Syntax
HRESULT get_FullScreenMode(
long *FullScreenMode
);
Parameters
- FullScreenMode
- Pointer to the current full-screen mode.
Return Value
Returns an HRESULT value.
Remarks
This member function returns E_NOTIMPL by default. This informs the IVideoWindow plug-in distributor that this renderer does not implement a full-screen renderer.
CBaseControlWindow::get_Height
Retrieves the current window height.
Syntax
HRESULT get_Height(
long *pHeight
);
Parameters
- pHeight
- Pointer to the current window height, in pixels.
Return Value
Returns an HRESULT value.
Remarks
The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in Microsoft® DirectShow®. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.
Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.
CBaseControlWindow::get_Left
Retrieves the current left window coordinate.
Syntax
HRESULT get_Left(
long *pLeft
);
Parameters
- pLeft
- Pointer to the left coordinate, in pixels.
Return Value
Returns an HRESULT value.
Remarks
The window has a position on the desktop. This position is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.
Setting the left or top coordinates moves the window left and up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height have no effect on the left and top coordinates.
CBaseControlWindow::GetMaxIdealImageSize
Retrieves the maximum ideal image size.
Syntax
HRESULT GetMaxIdealImageSize(
long *pWidth,
long *pHeight
);
Parameters
- pWidth
- Pointer to the maximum ideal width, in pixels.
- pHeight
- Pointer to the maximum ideal height, in pixels.
Return Value
Returns an HRESULT value.
Remarks
Various renderers have performance restrictions on the size of images they can display. Although they should still function properly when requested to display images larger than the specified maximum, renderers can nominate the minimum and maximum ideal sizes through the IVideoWindow interface. This interface can be called only when the filter graph is paused or running, because it is not until then that resources are allocated and the renderer can recognize its restrictions. If no restrictions exist, the renderer fills in the pWidth and pHeight parameters with the native video dimensions and returns S_FALSE. If restrictions do exist, the restricted width and height are entered, and the member function returns S_OK.
The dimensions apply to the size of the destination video and not to the overall window size. So, when calculating the size of the window to set, account for the current window styles (for example, WS_CAPTION and WS_BORDER).
CBaseControlWindow::get_MessageDrain
Retrieves the current message drain.
Syntax
HRESULT get_MessageDrain(
OAHWND *Drain
);
Parameters
- Drain
- Pointer to the current window receiving window messages.
Return Value
Returns an HRESULT value.
Remarks
Messages sent to the video renderer filter can be posted to another window. The window registered to receive these messages (using the CBaseControlWindow::get_MessageDrain member function) is the current message drain.
CBaseControlWindow::GetMinIdealImageSize
Retrieves the minimum ideal image size.
Syntax
HRESULT GetMinIdealImageSize(
long *pWidth,
long *pHeight
);
Parameters
- pWidth
- Pointer to the minimum ideal width, in pixels.
- pHeight
- Pointer to the minimum ideal height, in pixels.
Return Value
Returns an HRESULT value.
Remarks
Various renderers have performance restrictions on the size of images they can display. Although they should still function properly when requested to display images larger than the specified maximum, renderers can nominate the minimum and maximum ideal sizes through the IVideoWindow interface. This interface can be called only when the filter graph is paused or running, because it is not until then that resources are allocated and the renderer can recognize its restrictions. If no restrictions exist, the renderer fills in the pWidth and pHeight parameters with the native video dimensions and returns S_FALSE. If restrictions do exist, the restricted width and height are entered, and the member function returns S_OK.
The dimensions apply to the size of the destination video and not to the overall window size. So, when calculating the size of the window to set, account for the current window styles (for example, WS_CAPTION and WS_BORDER).
CBaseControlWindow::get_Owner
Retrieves the current window owner.
Syntax
HRESULT get_Owner(
OAHWND *Owner
);
Parameters
- Owner
- Pointer to the window owner.
Return Value
Returns an HRESULT value.
Remarks
The video window can play back within a document environment. To do this, the window must be made a child of another window (so that it is clipped and moved appropriately). This property allows the owner of the window to be set and retrieved. When the window is owned by another window, it simply calls the Microsoft Win32 SetParent function. An application calling this function will change the window styles to set the WS_CHILD bit on.
When the window is owned by another window, it will automatically forward certain sets of messages (in particular, mouse and keyboard messages). This allows an application to do simple hot-spot editing and other interactions.
This member function is meant to be called by external objects through the IVideoWindow interface, and therefore locks the critical section to synchronize with the associated filter. Call the CBaseControlWindow::GetOwnerWindow member function to retrieve this property if not calling from an external object.
CBaseControlWindow::GetOwnerWindow
Retrieves the owning window handle, m_hwndOwner.
Syntax
HWND GetOwnerWindow(void);
Return Value
Returns an internal method to return the owner window.
Remarks
Retrieves the owning window without calling the interface method. Use this member function instead of CBaseControlWindow::get_Owner, unless you are calling this externally through the IVideoWindow::get_Owner method.
CBaseControlWindow::GetRestorePosition
Retrieves the position to which the window will be restored when it is not maximized or minimized.
Syntax
HRESULT GetRestorePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);
Parameters
- pLeft
- Pointer to the value for leftmost coordinate.
- pTop
- Pointer to the value for top of the window.
- pWidth
- Pointer to the value for width of the window.
- pHeight
- Pointer to the value for height of window.
Return Value
Returns an HRESULT value.
Remarks
This is the same as the values returned by the CBaseControlWindow::GetWindowPosition function when the window is neither maximized nor minimized.
CBaseControlWindow::get_Top
Retrieves the top window coordinate.
Syntax
HRESULT get_Top(
long *pTop
);
Parameters
- pTop
- Pointer to the top coordinate, in pixels.
Return Value
Returns an HRESULT value.
Remarks
The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.
Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.
CBaseControlWindow::get_Visible
Retrieves the current window visibility.
Syntax
HRESULT get_Visible(
long *pVisible
);
Parameters
- pVisible
- Pointer to an Automation Boolean flag (0 is off, –1 is on).
Return Value
Returns an HRESULT value.
Remarks
This member function returns –1 if the window has the WS_VISIBLE style; 0 otherwise.
CBaseControlWindow::get_Width
Retrieves the current window width.
Syntax
HRESULT get_Width(
long *pWidth
);
Parameters
- pWidth
- Pointer to the window width, in pixels.
Return Value
Returns an HRESULT value.
Remarks
The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.
Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.
CBaseControlWindow::GetWindowPosition
Retrieves the current coordinates for the window.
Syntax
HRESULT GetWindowPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);
Parameters
- pLeft
- Pointer to the left coordinate, in screen coordinates.
- pTop
- Pointer to the top coordinate, in screen coordinates.
- pWidth
- Pointer to the window width, in screen coordinates.
- pHeight
- Pointer to the window height, in screen coordinates.
Return Value
Returns an HRESULT value.
CBaseControlWindow::get_WindowState
Retrieves the current window state.
Syntax
HRESULT get_WindowState(
long *pWindowState
);
Parameters
- pWindowState
- Pointer to the window state.
Return Value
Returns an HRESULT value.
Remarks
This member function returns a subset of the parameters of the Microsoft Win32 ShowWindow function. In particular, it returns SW_SHOW and SW_HIDE, depending on the current visibility of the window. It also returns SW_MINIMIZE and SW_MAXIMIZE, depending on whether the window is an icon or is expanded.
CBaseControlWindow::get_WindowStyle
Retrieves the standard window styles.
Syntax
HRESULT get_WindowStyle(
long *pWindowStyle
);
Parameters
- pWindowStyle
- Pointer to window styles.
Return Value
Returns an HRESULT value.
Remarks
This member function returns the standard window styles, such as WS_CHILD and WS_VISIBLE. It calls the CBaseControlWindow::DoGetWindowStyle member function.
CBaseControlWindow::get_WindowStyleEx
Retrieves the extended window styles.
Syntax
HRESULT get_WindowStyleEx(
long *pWindowStyleEx
);
Parameters
- pWindowStyleEx
- Pointer to extended window styles.
Return Value
Returns an HRESULT value.
Remarks
This member function retrieves the extended window styles. It calls the CBaseControlWindow::DoGetWindowStyle member function.
CBaseControlWindow::HideCursor
Hides or displays the cursor.
Syntax
HRESULT HideCursor(
long HideCursor
);
Parameters
- HideCursor
- Value specifying whether to show the cursor. Set to OATRUE to hide the cursor, or OAFALSE to display the cursor.
Return Value
Returns an HRESULT value.
CBaseControlWindow::IsCursorHidden
Retrieves the current state of the m_bCursorHidden data member.
Syntax
HRESULT IsCursorHidden(
long *CursorHidden
);
BOOL IsCursorHidden(void);
Parameters
- CursorHidden
- Pointer to the value of m_bCursorHidden.
Return Value
When called without a parameter, returns OATRUE if the cursor is hidden, or OAFALSE if the cursor is visible.
When called with a parameter, returns an HRESULT value.
Remarks
Internal objects should call this member function without the CursorHidden parameter to avoid locking the critical section. External objects access this member function with the CursorHidden parameter through the IVideoWindow::IsCursorHidden method.
CBaseControlWindow::IsAutoShowEnabled
Retrieves information about whether the video window automatically appears when the rendering filter pauses or runs.
Syntax
BOOL IsAutoShowEnabled(void);
Return Value
Returns TRUE if the m_bAutoShow member is set to –1 or FALSE if it is set to 0.
Remarks
If the m_bAutoShow member is set to –1 on a video window that is hidden, the window becomes visible when the filter pauses or runs. If this member is set to 0, the window will appear only if you use the CBaseControlWindow::put_Visible or CBaseControlWindow::put_WindowState member function with the appropriate parameters.
This member function retrieves the m_bAutoShow member setting and has the same result as using the IVideoWindow::get_AutoShow method.
CBaseControlWindow::NotifyOwnerMessage
Passes along specific messages to the video window.
Syntax
HRESULT NotifyOwnerMessage(
long hwnd,
long uMsg,
long wParam,
long lParam
);
Parameters
- hwnd
- Handle to the video window.
- uMsg
- Message details.
- wParam
- Standard WPARAM parameter.
- lParam
- Standard LPARAM parameter.
Return Value
Returns NO_ERROR.
Remarks
When the video window is a child of another window, it does not receive certain top-level window messages. These messages can be valuable to a renderer, because they could affect its behavior. NotifyOwnerMessage passes any of the following messages to the video window.
- WM_ACTIVATEAPP
- WM_DEVMODECHANGE
- WM_DISPLAYCHANGE
- WM_PALETTECHANGED
- WM_PALETTEISCHANGING
- WM_QUERYNEWPALETTE
- WM_SYSCOLORCHANGE
You can request that the IVideoWindow plug-in distributor (PID) make a window become a child of another window. When this occurs, the PID will look for certain messages that might be sent to the owning window. The PID will then forward those messages to the owned window. The default processing for the messages is to send them to the owned window procedure synchronously by calling the Win32 SendMessage function.
CBaseControlWindow::PossiblyEatMessage
Forwards keyboard and mouse messages to a specified window.
Syntax
BOOL WINAPI PossiblyEatMessage(
HWND hwndDrain,
UINT uMsg,
WPARAM wParam,
LPARAM lParam
)
Parameters
- hwndDrain
- Handle of the window to which messages will be forwarded.
- uMsg
- Message that was forwarded.
- wParam
- First message parameter.
- lParam
- Second message parameter.
Return Value
Returns TRUE if the message was posted or FALSE if it wasn't.
Remarks
When the window is owned, it will pass certain classes of messages to the owning window (such as keyboard and mouse events). In this case, the Win32 PostMessage function is used to post messages to any window specified by hwndDrain which is set in CBaseControlWindow::put_MessageDrain. If a certain message cannot be posted, this message will return FALSE.
The following is a list of messages that will get passed on untranslated and return TRUE.
WM_CHAR WM_DEADCHAR WM_KEYDOWN WM_KEYUP WM_LBUTTONDBLCLK WM_LBUTTONDOWN WM_LBUTTONUP WM_MBUTTONDBLCLK WM_MBUTTONDOWN WM_MBUTTONUP WM_MOUSEACTIVATE WM_MOUSEMOVE WM_NCHITTEST WM_NCLBUTTONDBLCLK WM_NCLBUTTONDOWN WM_NCLBUTTONUP WM_NCMBUTTONDBLCLK WM_NCMBUTTONDOWN WM_NCMBUTTONUP WM_NCMOUSEMOVE WM_NCRBUTTONDBLCLK WM_NCRBUTTONDOWN WM_NCRBUTTONUP WM_RBUTTONDBLCLK WM_RBUTTONDOWN WM_RBUTTONUP WM_SYSCHAR WM_SYSDEADCHAR WM_SYSKEYDOWN WM_SYSKEYUP
CBaseControlWindow::put_AutoShow
Sets the AutoShow state flag.
Syntax
HRESULT put_AutoShow(
long AutoShow
);
Parameters
- AutoShow
- Automation Boolean flag (0 is off, –1 is on).
Return Value
Returns an HRESULT value.
Remarks
This property simplifies window display access for applications. If this is set to –1 (on), the window, which is typically hidden after the filter is connected, will be displayed automatically when the filter pauses or runs. The window should not be hidden when the filter stops, however. If this is set to 0 (off), the window is made visible only when the application calls CBaseControlWindow::put_Visible or CBaseControlWindow::put_WindowState with the appropriate parameters.
CBaseControlWindow::put_BackgroundPalette
Sets a flag to realize the palette in the background.
Syntax
HRESULT put_BackgroundPalette(
long BackgroundPalette
);
Parameters
- BackgroundPalette
- Automation Boolean flag (0 is off, –1 is on).
Return Value
Returns an HRESULT value.
Remarks
To play a video within another application or document, the application might want to use its own palette. It can ask that the video use the current foreground palette rather than its own as the background palette by setting this flag to –1. If this is set to 0, the window will install and realize its own preferred palette. Asking the window to use a different palette will cause severe performance penalties.
CBaseControlWindow::put_BorderColor
Changes the border color.
Syntax
HRESULT put_BorderColor(
long Color
);
Parameters
- Color
- New border color.
Return Value
Returns an HRESULT value.
Remarks
An application can establish a destination rectangle in which the video should be displayed. This rectangle is relative to the client area for the window. If this is done (the default is to always paint the entire window), there is a border surrounding the video. This property affects the color used by the border. Although the parameter is specified as a LONG type, it is actually a COLORREF value.
CBaseControlWindow::put_Caption
Sets the window title or caption.
Syntax
HRESULT put_Caption(
BSTR strCaption
);
Parameters
- strCaption
- New window caption.
Return Value
Returns an HRESULT value.
Remarks
Most top-level windows on a Windows-based desktop have a title (caption) associated with them. This property can be queried and set through the IVideoWindow interface. Any caption set will be visible only if the window has the WS_CAPTION style applied. If it does not, the caption can still be set (and retrieved), although it will not be visible to the user.
CBaseControlWindow::put_FullScreenMode
Sets the full-screen mode of the renderer.
Syntax
HRESULT put_FullScreenMode(
long FullScreenMode
);
Parameters
- FullScreenMode
- Full-screen mode to apply.
Return Value
Returns an HRESULT value. The current implementation returns E_NOTIMPL.
Remarks
A video renderer that implements a full-screen mode should override this member function and implement whatever modes it supports.
CBaseControlWindow::put_Height
Sets the window height.
Syntax
HRESULT put_Height(
long Height
);
Parameters
- Height
- New window height, in pixels.
Return Value
Returns an HRESULT value.
Remarks
The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.
Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.
CBaseControlWindow::put_Left
Sets the left coordinate for the window.
Syntax
HRESULT put_Left(
long Left
);
Parameters
- Left
- New left coordinate, in pixels.
Return Value
Returns an HRESULT value.
Remarks
The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.
Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.
CBaseControlWindow::put_MessageDrain
Sets the window to receive window messages sent to the video renderer.
Syntax
HRESULT put_MessageDrain(
OAHWND Drain
);
Parameters
- Drain
- Window to post messages to.
Return Value
Returns an HRESULT value.
Remarks
Messages sent to the video renderer filter can be posted to another window. This member function registers the window to receive these messages. Unlike the CBaseControlWindow::put_Owner member function, this member function does not make the video window a child of another window. It is particularly useful for full-screen video renderers, which cannot be child windows.
CBaseControlWindow::put_Owner
Sets the video window's parent window; the parent window then forwards certain messages to the video window.
Syntax
HRESULT put_Owner(
OAHWND Owner
);
Parameters
- Owner
- Handle to the parent window.
Return Value
Returns NOERROR.
Remarks
Internally, this method calls the Microsoft Win32 SetParent function to set the new owner and sets the parent window's style to WS_CHILD. The parent window will then forward certain sets of messages (in particular, mouse and keyboard messages) to the video window.
After you set the video window's owner, you must set the owner to NULL and the owner's window style to WS_OVERLAPPED and WS_CLIPCHILDREN before releasing the filter graph. When you set the owner to NULL, this method turns off the parent window's WS_CHILD bit. If you don't set the owner to NULL, the parent window will continue to pass messages to the video window and errors will likely occur when the application closes.
CBaseControlWindow::put_Top
Sets the top window coordinate.
Syntax
HRESULT put_Top(
long Top
);
Parameters
- Top
- New top coordinate, in pixels.
Return Value
Returns an HRESULT value.
Remarks
The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels, and changing any coordinate will update the window immediately.
Setting the left or top coordinates moves the window left or up, respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.
CBaseControlWindow::put_Visible
Makes the window either visible or hidden.
Syntax
HRESULT put_Visible(
long Visible
);
Parameters
- Visible
- Automation Boolean flag (0 means window is hidden, –1 means window is shown).
Return Value
Returns an HRESULT value.
CBaseControlWindow::put_Width
Sets the window width.
Syntax
HRESULT put_Width(
long Width
);
Parameters
- Width
- New window width, in pixels.
Return Value
Returns an HRESULT value.
Remarks
The window has a position on the desktop. This is expressed in pixels by four coordinates (left, top, right, and bottom). Interfaces that are automated by OLE typically express this position through left, top, width, and height; this is the convention used in DirectShow. All coordinates are expressed in pixels and changing any coordinate will update the window immediately.
Setting the left or top coordinates moves the window left or up respectively; these coordinates have no effect on the width and height of the window. Likewise, setting the width and height does not affect the left and top coordinates.
CBaseControlWindow::put_WindowState
Sets the window state.
Syntax
HRESULT put_WindowState(
long WindowState
);
Parameters
- WindowState
- New window state.
Return Value
Returns an HRESULT value.
Remarks
This member function takes the same parameters as the Microsoft Win32 ShowWindow function (for example, WS_SHOWNORMAL, WS_SHOWMINNOACTIVATE, and WS_SHOWMAXIMIZED).
CBaseControlWindow::put_WindowStyle
Sets the standard Windows-based styles.
Syntax
HRESULT put_WindowStyle(
long WindowStyle
);
Parameters
- WindowStyle
- New window styles.
Return Value
Returns an HRESULT value.
Remarks
Take care when changing the window styles. In most cases, an application should retrieve the current style and then add or remove the inappropriate bits. This procedure allows various internal window styles used by Windows® to remain intact.
CBaseControlWindow::put_WindowStyleEx
Sets the style of the control window.
Syntax
HRESULT put_WindowStyleEx(
long WindowStyleEx
);
Parameters
- WindowStyleEx
- [in] Value that specifies the style of the control window.
Return Value
Returns NOERROR.
Remarks
This method uses EX (extended) window styles. For a complete list of extended window styles, see the Microsoft Win32 CreateWindowEx function. To change the window style, retrieve the current window style, and then add or remove the necessary bit fields.
Do not use the following window styles because they are not validated.
- WS_DISABLED
- WS_HSCROLL
- WS_ICONIC
- WS_MAXIMIZE
- WS_MINIMIZE
- WS_VSCROLL
With some exceptions (noted here), the acceptable flags are the same as those allowed by the Win32 CreateWindow function.
CBaseControlWindow::SetControlWindowPin
Sets the pin with which to synchronize.
Syntax
void SetControlWindowPin(
CBasePin *pPin
);
Parameters
- pPin
- Pointer to the pin with which the interface is synchronized.
Return Value
No return value.
Remarks
This member function sets the m_pPin variable equal to the pPin parameter. As described in the constructor, the interface can be called only when the filter has been connected successfully. The object is passed in through this member function to the pin with which it should synchronize; in most cases, it will determine if the pin is connected whenever it has an interface method called and will return VFW_E_NOT_CONNECTED if it fails.
CBaseControlWindow::SetWindowForeground
Moves the video window to the foreground and optionally gives it focus.
Syntax
HRESULT SetWindowForeground(
long Focus
);
Parameters
- Focus
- Value that specifies whether the video window will get focus. A value of –1 gives the window focus and 0 does not.
Return Value
Returns one of the following values.
NOERROR The method succeeded. E_INVALIDARG Focus doesn't equal –1 or 0. VFW_E_NOT_CONNECTED The current filter isn't connected to a complete filter graph.
CBaseControlWindow::SetWindowPosition
Sets the window position on the desktop.
Syntax
HRESULT SetWindowPosition(
long Left,
long Top,
long Width,
long Height
);
Parameters
- Left
- New left coordinate.
- Top
- New top coordinate.
- Width
- Width of the window.
- Height
- Height of the window.
Return Value
Returns an HRESULT value.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.