## 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

Name | Description
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

Name | Description
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

Name | Description
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 | Returns 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

CBaseControlWindow Class

Constructs a CBaseControlWindow object.

CBaseControlWindow(
CBaseMediaFilter *pFilter,
CCritSec *pInterfaceLock,
TCHAR *pName,
LPUNKNOWN pUnk,
HRESULT *phr
);

##### Parameters

pFilter
  Owning media filter object.
pInterfaceLock
  Critical section to use for locking.
pName
  Object description.
pUnk
  Typical Component Object Model (COM) ownership.
phr
  COM return value.

##### Return Values

No return value.

###

CBaseControlWindow::DoGetWindowStyle

CBaseControlWindow Class

Retrieves the current normal or extended window styles.

HRESULT DoGetWindowStyle(
long *pStyle,
long WindowLong
);

##### Parameters

pStyle
  Contains the appropriate styles.
WindowLong
  Either GWL_STYLE or GWL_EXSTYLE.

##### Return Values

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

CBaseControlWindow Class

Changes the typical or extended window styles.

HRESULT DoSetWindowStyle(
long Style,
long WindowLong
);

##### Parameters

Style
  Contains the appropriate window styles.
WindowLong
  Either GWL_STYLE or GWL_EXSTYLE.

##### Return Values

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

CBaseControlWindow Class

Retrieves the current AutoShow state flag.

HRESULT get_AutoShow(
long *AutoShow
);

##### Parameters

AutoShow
  Automation Boolean flag (0 is off, –1 is on).

##### Return Values

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

CBaseControlWindow Class

Retrieves the realized palette in the background flag.

HRESULT get_BackgroundPalette(
long *pBackgroundPalette
);

##### Parameters

pBackgroundPalette
  Automation Boolean flag (0 is off, –1 is on).

##### Return Values

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

CBaseControlWindow Class

Retrieves the current border color.

HRESULT get_BorderColor(
long *Color
);

##### Parameters

Color
  Current border color.

##### Return Values

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

CBaseControlWindow Class

Returns the current window border color, m_BorderColour.

COLORREF GetBorderColour( );

##### Return Values

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

CBaseControlWindow Class

Retrieves the current window caption.

HRESULT get_Caption(
BSTR *pstrCaption
);

##### Parameters

pstrCaption
  Current window caption.

##### Return Values

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

CBaseControlWindow Class

Retrieves the current full-screen mode.

HRESULT get_FullScreenMode(
long *FullScreenMode
);

##### Parameters

FullScreenMode
  Current full-screen mode.

##### Return Values

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

CBaseControlWindow Class

Retrieves the current window height.

HRESULT get_Height(
long *pHeight
);

##### Parameters

pHeight
  Current window height, in pixels.

##### Return Values

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_Left

CBaseControlWindow Class

Retrieves the current left window coordinate.

HRESULT get_Left(
long *pLeft
);

##### Parameters

pLeft
  Contains the left coordinate, in pixels.

##### Return Values

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

CBaseControlWindow Class

Retrieves the maximum ideal image size.

HRESULT GetMaxIdealImageSize(
long *pWidth,
long *pHeight
);

##### Parameters

pWidth
  Maximum ideal width, in pixels.
pHeight
  Maximum ideal height, in pixels.

##### Return Values

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

CBaseControlWindow Class

Returns the current message drain.

HRESULT get_MessageDrain(
OAHWND *Drain
);

##### Parameters

Drain
  Current window receiving window messages.

##### Return Values

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

CBaseControlWindow Class

Retrieves the minimum ideal image size.

HRESULT GetMinIdealImageSize(
long *pWidth,
long *pHeight
);

##### Parameters

pWidth
  Minimum ideal width, in pixels.
pHeight
  Minimum ideal height, in pixels.

##### Return Values

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

CBaseControlWindow Class

Retrieves the current window owner.

HRESULT get_Owner(
OAHWND *Owner
);

##### Parameters

Owner
  Contains the window owner.

##### Return Values

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

CBaseControlWindow Class

Returns the owning window handle, m_hwndOwner.

HWND GetOwnerWindow( );

##### Return Values

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

CBaseControlWindow Class

Retrieves the position to which the window will be restored when it is not maximized or minimized.

HRESULT GetRestorePosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

##### Parameters

pLeft
  Value for leftmost coordinate.
pTop
  Value for top of the window.
pWidth
  Value for width of the window.
pHeight
  Value for height of window.

##### Return Values

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

CBaseControlWindow Class

Retrieves the top window coordinate.

HRESULT get_Top(
long *pTop
);

##### Parameters

pTop
  Contains the top coordinate, in pixels.

##### Return Values

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

CBaseControlWindow Class

Retrieves the current window visibility.

HRESULT get_Visible(
long *pVisible
);

##### Parameters

pVisible
  Automation Boolean flag (0 is off, –1 is on).

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function returns –1 if the window has the WS_VISIBLE style; 0 otherwise.

###

CBaseControlWindow::get_Width

CBaseControlWindow Class

Retrieves the current window width.

HRESULT get_Width(
long *pWidth
);

##### Parameters

pWidth
  Contains the window width, in pixels.

##### Return Values

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

CBaseControlWindow Class

Retrieves the current coordinates for the window.

HRESULT GetWindowPosition(
long *pLeft,
long *pTop,
long *pWidth,
long *pHeight
);

##### Parameters

pLeft
  Contains the left coordinate, in screen coordinates.
pTop
  Contains the top coordinate, in screen coordinates.
pWidth
  Contains the window width, in screen coordinates.
pHeight
  Contains the window height, in screen coordinates.

##### Return Values

Returns an HRESULT value.

###

CBaseControlWindow::get_WindowState

CBaseControlWindow Class

Retrieves the current window state.

HRESULT get_WindowState(
long *pWindowState
);

##### Parameters

pWindowState
  Contains the window state.

##### Return Values

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

CBaseControlWindow Class

Retrieves the standard window styles.

HRESULT get_WindowStyle(
long *pWindowStyle
);

##### Parameters

pWindowStyle
  Contains the window styles.

##### Return Values

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

CBaseControlWindow Class

Retrieves the extended window styles.

HRESULT get_WindowStyleEx(
long *pWindowStyleEx
);

##### Parameters

pWindowStyleEx
  Contains the extended window styles.

##### Return Values

Returns an HRESULT value.

##### Remarks

This member function retrieves the extended window styles. It calls the CBaseControlWindow::DoGetWindowStyle member function.

###

CBaseControlWindow::HideCursor

CBaseControlWindow Class

Hides or displays the cursor.

HRESULT HideCursor(
long HideCursor
);

##### Parameters

HideCursor
  Set to OATRUE to hide the cursor, or OAFALSE to display the cursor.

##### Return Values

Returns an HRESULT value.

###

CBaseControlWindow::IsCursorHidden

CBaseControlWindow Class

Retrieves the current state of the m_bCursorHidden data member.

HRESULT IsCursorHidden(
long *CursorHidden
);

BOOL IsCursorHidden( );

##### Parameters

CursorHidden
  Value of m_bCursorHidden.

##### Return Values

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

CBaseControlWindow Class

Retrieves information about whether the video window automatically appears when the rendering filter pauses or runs.

BOOL IsAutoShowEnabled( );

##### Return Values

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

CBaseControlWindow Class

Passes along specific messages to the video window.

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 Values

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

CBaseControlWindow Class

Forwards keyboard and mouse messages to a specified window.

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 Values

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

CBaseControlWindow Class

Sets the AutoShow state flag.

HRESULT put_AutoShow(
long AutoShow
);

##### Parameters

AutoShow
  Automation Boolean flag (0 is off, –1 is on).

##### Return Values

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

CBaseControlWindow Class

Sets a flag to realize the palette in the background.

HRESULT put_BackgroundPalette(
long BackgroundPalette
);

##### Parameters

BackgroundPalette
  Automation Boolean flag (0 is off, –1 is on).

##### Return Values

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

CBaseControlWindow Class

Changes the border color.

HRESULT put_BorderColor(
long Color
);

##### Parameters

Color
  Contains the new border color.

##### Return Values

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

CBaseControlWindow Class

Sets the window title or caption.

HRESULT put_Caption(
BSTR strCaption
);

##### Parameters

strCaption
  Contains the new window caption.

##### Return Values

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

CBaseControlWindow Class

Sets the full-screen mode of the renderer.

HRESULT put_FullScreenMode(
long FullScreenMode
);

##### Parameters

FullScreenMode
  Full-screen mode to apply.

##### Return Values

Returns an HRESULT value.

##### Remarks

The current implementation returns E_NOTIMPL. A video renderer that implements a full-screen mode should override this member function and implement whatever modes it supports.

###

CBaseControlWindow::put_Height

CBaseControlWindow Class

Sets the window height.

HRESULT put_Height(
long Height
);

##### Parameters

Height
  New window height, in pixels.

##### Return Values

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

CBaseControlWindow Class

Sets the left coordinate for the window.

HRESULT put_Left(
long Left
);

##### Parameters

Left
  New left coordinate, in pixels.

##### Return Values

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

CBaseControlWindow Class

Sets the window to receive window messages sent to the video renderer.

HRESULT put_MessageDrain(
OAHWND Drain
);

##### Parameters

Drain
  Window to post messages to.

##### Return Values

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

CBaseControlWindow Class

Sets the video window's parent window; the parent window then forwards certain messages to the video window.

HRESULT put_Owner(
OAHWND Owner
);

##### Parameters

Owner
  Handle to the parent window.

##### Return Values

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

CBaseControlWindow Class

Sets the top window coordinate.

HRESULT put_Top(
long Top
);

##### Parameters

Top
  New top coordinate, in pixels.

##### Return Values

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

CBaseControlWindow Class

Makes the window either visible or hidden.

HRESULT put_Visible(
long Visible
);

##### Parameters

Visible
  Automation Boolean flag (0 means window is hidden, –1 means window is shown).

##### Return Values

Returns an HRESULT value.

###

CBaseControlWindow::put_Width

CBaseControlWindow Class

Sets the window width.

HRESULT put_Width(
long Width
);

##### Parameters

Width
  New window width, in pixels.

##### Return Values

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

CBaseControlWindow Class

Sets the window state.

HRESULT put_WindowState(
long WindowState
);

##### Parameters

WindowState
  New window state.

##### Return Values

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

CBaseControlWindow Class

Sets the standard Windows-based styles.

HRESULT put_WindowStyle(
long WindowStyle
);

##### Parameters

WindowStyle
  New window styles.

##### Return Values

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

CBaseControlWindow Class

Sets the style of the control window.

HRESULT put_WindowStyleEx(
long WindowStyleEx
);

##### Parameters

WindowStyleEx
  [in] Value that specifies the style of the control window.

##### Return Values

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.

Note: 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

CBaseControlWindow Class

Sets the pin with which to synchronize.

void SetControlWindowPin(
CBasePin *pPin
);

##### Parameters

pPin
  Pin with which the interface is synchronized.

##### Return Values

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

CBaseControlWindow Class

Moves the video window to the foreground and optionally gives it focus.

HRESULT SetWindowForeground(
long Focus
);

##### Parameters

Focus
  Long value that specifies whether the video window will get focus. A value of –1 gives the window focus and 0 does not.

##### Return Values

Returns one of the following values.

Value | Meaning
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

CBaseControlWindow Class

Sets the window position on the desktop.

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 Values

Returns an HRESULT value.

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