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.

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

Top of Page