CBaseWindow Class

The CBaseWindow class creates a window and a worker thread. The worker thread pulls messages from the window's input queue and dispatches them as appropriate. The window and its thread are created by the CBaseWindow::PrepareWindow member function and destroyed by the CBaseWindow::DoneWithWindow member function. The window should also be initialized by the CBaseWindow::InitialiseWindow member function and uninitialized by the CBaseWindow::UninitialiseWindow member function. After preparing and initializing a window, size it by using the CBaseWindow::ActivateWindow member function; hide the window using the CBaseWindow::InactivateWindow member function.

Protected Data Members

m_bActivated Flag to indicate window activation status.
m_bBackground Flag to indicate if palettes are to be realized in the background.
m_bDoGetDC Flag to indicate if the window should get a DC.
m_ClassStyles Class styles for the window.
m_hdc Device context (DC) for the window.
m_Height Client window height.
m_hInstance Global module instance handle.
m_hPalette Handle to a palette belonging to this object.
m_hThread Worker thread for the window.
m_hwnd Handle for this object's window.
m_MemoryDC Memory DC used for fast bit-block transfer operations.
m_pClassName Static string holding the class name.
m_RealizePalette Message sent to indicate the window palette has changed.
m_ShowStageMessage Message sent by IVideoWindow::SetWindowForeground that moves the current window to the foreground and optionally gives it focus.
m_ShowStageTop Message sent to set the window to WS_EX_TOPMOST style.
m_SyncWorker CAMEvent data member used to provide interthread synchronization.
m_SyncWorkerCreate CAMMsgEvent data member used to signal the constructor for the window class when to create the window.
m_ThreadSignal Data member used by the thread to signal errors.
m_Width Client window width.
m_WindowLock Data member used to serialize window object access.
m_WindowStyles Data member used to serialize the initial window styles.
m_WindowStylesEx Data member used to serialize the initial extended window styles.

Member Functions

CBaseWindow Constructs a CBaseWindow object.
DoSetWindowForeground Brings the window to the foreground.
DoShowWindow Sets the show state of the specified window.
GetMemoryHDC Retrieves the default off-screen memory device context (DC).
GetWindowHDC Retrieves the default main window DC.
GetWindowHeight Retrieves the current window height.
GetWindowHWND Retrieves the window handle for the window.
GetWindowWidth Retrieves the current window width.
PerformanceAlignWindow Aligns the window to a DWORD boundary for maximum performance.
PaintWindow Invalidates the window client area.

Overridable Member Functions

ActivateWindow Sizes the window according to the requirements of the derived class.
DoneWithWindow Closes, deletes, and frees the window resources.
DoRealisePalette Maps palette entries from this window's palette to the system palette. The window's palette is set with CBaseWindow::SetPalette.
PossiblyEatMessage Forwards keyboard and mouse messages to a specified window.
GetClassWindowStyles Retrieves class and window information.
GetDefaultRect Retrieves the default size for the window.
InactivateWindow Hides the window.
InitialiseWindow Creates the default device contexts.
OnClose Handles the WM_CLOSE message for the base class.
OnPaletteChange Handles WM_PALETTEISCHANGING and WM_PALETTECHANGED messages.
OnSize Handles WM_SIZE messages for the base class.
OnReceiveMessage Indicates a base class implementation of a window procedure.
PrepareWindow Initializes the window along with a worker thread.
SetPalette Changes the palette that the window should realize.
UninitialiseWindow Destroys the device contexts created for the window.

CBaseWindow::ActivateWindow

CBaseWindow Class

Sizes the window according to the requirements of the derived class.

Syntax

virtual HRESULT ActivateWindow(void);

Return Value

Returns an HRESULT value that depends on the implementation of the interface. HRESULT can include one of the following standard constants, or other values not listed.

E_FAIL Failure.
E_NOTIMPL Method is not supported.
NOERROR No error.

Remarks

This member function calls CBaseWindow::GetDefaultRect, which a derived class should override to return the size of the images that will be displayed. ActivateWindow then sizes the window so that the client area matches this size.

CBaseWindow::CBaseWindow

CBaseWindow Class

Constructs a CBaseWindow object.

Syntax

CBaseWindow(
    BOOL bDoGetDC = TRUE
);

Parameters

bDoGetDC
Boolean value. TRUE means the window should get a device context.

Return Value

No return value.

Remarks

The window and its worker thread are created by CBaseWindow::PrepareWindow and destroyed by CBaseWindow::DoneWithWindow.

CBaseWindow::DoneWithWindow

CBaseWindow Class

Destroys the window and its worker thread.

Syntax

virtual HRESULT DoneWithWindow(void);

Return Value

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed by CBaseWindow::DoneWithWindow. The window should also be initialized using CBaseWindow::InitialiseWindow and uninitialized using CBaseWindow::UninitialiseWindow. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.

CBaseWindow::DoRealisePalette

CBaseWindow Class

Maps palette entries from this window's palette to the system palette. The window's palette is set with CBaseWindow::SetPalette.

Syntax

virtual HRESULT DoRealisePalette(
    BOOL bForceBackground
);

Parameters

bForceBackground
Value that specifies whether the palette is forced to the background.

Return Value

Returns S_OK if successful or S_FALSE if the GdiFlush function could not flush the calling thread's current batch.

Remarks

The window class is given a palette handle to use with the CBaseWindow::SetPalette member function. After a palette has been installed, it can be realized by calling this member function. The class will also call this member function when it gets WM_QUERYNEWPALETTE and WM_PALETTECHANGED messages from the Microsoft® Windows® operating system.
Call this function with TRUE in response to WM_SETPALETTE and FALSE in response to WM_QUERYNEWPALETTE.

CBaseWindow::DoSetWindowForeground

CBaseWindow Class

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

Syntax

void DoSetWindowForeground(
    BOOL bFocus
);

Parameters

bFocus
Value that specifies whether the video window will have focus. A value of TRUE gives it focus and FALSE does not.

Return Value

No return value.

Remarks

Microsoft® DirectShow® provides this method to make it easy for applications to move video windows to the foreground; usually, it is programmatically complex for a thread associated with one window to affect a window associated with a different thread. This method passes the WM_SHOWWINDOW message to the video window's renderer, so the application's window procedure must handle this message and bring the appropriate window to the foreground and give it focus, if specified.

CBaseWindow::DoShowWindow

CBaseWindow Class

Sets the show state of the specified window.

Syntax

HRESULT DoShowWindow(
    LONG ShowCmd
);

Parameters

ShowCmd
Value specifying how the window is to be shown, such as SW_SHOW, SW_HIDE, and so on. For more details on these values and their meaning, see the ShowWindow function in the Platform SDK documentation.

Return Value

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

This member function simply calls the Microsoft Win32® ShowWindow function.

CBaseWindow::GetClassWindowStyles

CBaseWindow Class

Retrieves class and window information.

Syntax

virtual LPTSTR GetClassWindowStyles(
    DWORD *pClassStyles,
    DWORD *pWindowStyles,
    DWORD *pWindowStylesEx
    ) PURE;

Parameters

pClassStyles
Pointer to class styles.
pWindowStyles
Pointer to window styles.
pWindowStylesEx
Pointer to extended window styles.

Return Value

Returns a class name that is a static text string.

Remarks

A derived class must override this pure virtual member function to provide the default class and window styles for the window. The information the derived class returns is used in CBaseWindow::PrepareWindow when the window is first created. The class and window styles take the same parameters as their counterparts in the Microsoft Win32 CreateWindowEx function. The string that is returned should be allocated as a static string and should still be valid after the member function returns.

CBaseWindow::GetDefaultRect

CBaseWindow Class

Retrieves the default size for the window client area.

Syntax

virtual RECT GetDefaultRect(void);

Return Value

Returns the default rectangle.

Remarks

When the window is activated, it calls this member function to determine how large it should make the window's client area. A video renderer will typically return the size of the native video image.

CBaseWindow::GetMemoryHDC

CBaseWindow Class

Retrieves the default memory device context (DC).

Syntax

virtual HDC GetMemoryHDC(void);

Return Value

Returns the default memory DC.

Remarks

The base window class creates a window with a worker thread when it is prepared (in CBaseWindow::PrepareWindow). It also creates two DCs that can be used for drawing. The first is a normal window handle to a device context (HDC); the second is an off-screen HDC that can be used as a source HDC in bit-block transfer functions.

CBaseWindow::GetWindowHDC

CBaseWindow Class

Retrieves the default window device context (DC).

Syntax

HDC GetWindowHDC(void);

Return Value

Returns the default window DC.

Remarks

The base window class creates a window with a worker thread when it is prepared (in CBaseWindow::PrepareWindow). It also creates two DCs that can be used for drawing. The first is a normal window handle to a device context (HDC); the second is an off-screen HDC that can be used as a source HDC in bit-block transfer functions.

CBaseWindow::GetWindowHeight

CBaseWindow Class

Retrieves the current window height.

Syntax

LONG GetWindowHeight(void);

Return Value

Returns the window height in pixels.

Remarks

This member function is updated when the base class receives WM_SIZE messages.

CBaseWindow::GetWindowHWND

CBaseWindow Class

Retrieves the window handle associated with this object.

Syntax

HWND GetWindowHWND(void);

Return Value

Returns a window handle.

Remarks

If called before issuing a CBaseWindow::PrepareWindow call, this member function returns NULL.

CBaseWindow::GetWindowWidth

CBaseWindow Class

Retrieves the current window width.

Syntax

LONG GetWindowWidth(void);

Return Value

Returns the window width in pixels.

Remarks

This member function is updated when the base class receives WM_SIZE messages.

CBaseWindow::InactivateWindow

CBaseWindow Class

Effectively hides the window (if it was visible).

Syntax

virtual HRESULT InactivateWindow(void);

Return Value

Returns NOERROR if successful; S_FALSE if the window is not currently active.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed in CBaseWindow::DoneWithWindow. The window should be initialized through CBaseWindow::InitialiseWindow and uninitialized through CBaseWindow::UninitialiseWindow. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.

CBaseWindow::InitialiseWindow

CBaseWindow Class

Creates default device contexts for the window.

Syntax

virtual InitialiseWindow(
    HWND hwnd
);

Parameters

hwnd
Window handle.

Return Value

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed in CBaseWindow::DoneWithWindow. The window should be initialized through CBaseWindow::InitialiseWindow and uninitialized through CBaseWindow::UninitialiseWindow. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.
The base class creates two device contexts that can be used for drawing. The first is a standard handle to a device context (HDC) for the window; the second is an off-screen HDC. The off-screen HDC often is useful for selecting bitmaps before calling the Microsoft Win32 BitBlt or StretchBlt function to copy the bitmap to the main window. This member function also sets the default stretch mode to be COLORONCOLOR. The member function is virtual so that derived classes can change this default if desired.

CBaseWindow::OnClose

CBaseWindow Class

Handles the WM_CLOSE message.

Syntax

virtual BOOL OnClose(void);

Return Value

No return value.

Remarks

The default behavior for this member function is to simply hide the window. A derived class should not destroy the window when it receives a WM_CLOSE message but should send an EC_USERABORT notification to the filter graph manager. This will have the playback stopped, and in some cases will also have the filters disconnected and released. It is only when the filter that owns the window is finally released (that is, destroyed) that the derived class should actually destroy the window (using CBaseWindow::DoneWithWindow).

CBaseWindow::OnPaletteChange

CBaseWindow Class

Handles WM_PALETTEISCHANGING and WM_PALETTECHANGED messages.

Syntax

virtual LRESULT OnPaletteChange(
    HWND hwnd,
    UINT Message
);

Parameters

hwnd
Handle of the window causing the message.
Message
Message details passed on from the window procedure.

Return Value

Returns one of the following values.

0 Message was not handled.
1 Message was processed.

Remarks

When the base class receives a WM_PALETTEISCHANGING message, it realizes its palette again. It must also do this when told, through WM_PALETTECHANGED, that the system palette has changed. In the latter case, however, the base class must be careful not to realize its palette if it was the window that caused the WM_PALETTECHANGED message (which is why the window that caused the message to be sent is passed into the member function).
This is a protected member function.

CBaseWindow::OnReceiveMessage

CBaseWindow Class

Indicates a base class implementation of a window procedure.

Syntax

virtual LRESULT OnReceiveMessage(
    HWND hwnd,
    INT uMsg,
    WPARAM wParam,
    LPARAM lParam
);

Parameters

hwnd
Handle to the window.
uMsg
Message identifier.
wParam
Message's wParam parameter.
lParam
Message's lParam parameter.

Return Value

Returns an LRESULT value, based on the uMsg parameter. If uMsg is not one of the specified values, OnReceiveMessage passes the message to the Win32 DefWindowProc function and forwards the resulting return value to the caller.

Message Action

m_RealizePalette Returns 0.
m_ShowStageMessage Returns 1.
m_ShowStageTop Returns 1.
WM_CLOSE Returns 0.
WM_PALETTECHANGED Returns 0.
WM_QUERYNEWPALETTE Returns result of CBaseWindow::OnPaletteChange
WM_SIZE Returns 0.
WM_SYSCOLORCHANGE Returns 1.

Message	Action
m_RealizePalette	Returns 0.
m_ShowStageMessage	Returns 1.
m_ShowStageTop	Returns 1.
WM_CLOSE	Returns 0.
WM_PALETTECHANGED	Returns 0.
WM_QUERYNEWPALETTE	Returns result of CBaseWindow::OnPaletteChange
WM_SIZE	Returns 0.
WM_SYSCOLORCHANGE	Returns 1.

CBaseWindow::OnSize

CBaseWindow Class

Handles the WM_SIZE message.

Syntax

virtual BOOL OnSize(
    LONG Width,
    LONG Height
);

Parameters

Width
Window width.
Height
Window height.

Return Value

No return value.

Remarks

This member function stores the window width and height so that they can be returned from the CBaseWindow::GetWindowHeight and CBaseWindow::GetWindowWidth member functions.

CBaseWindow::PaintWindow

CBaseWindow Class

Invalidates the window client area.

Syntax

void PaintWindow(
    BOOL bErase
);

Parameters

bErase
Value specifying whether the background should be erased.

Return Value

No return value.

CBaseWindow::PerformanceAlignWindow

CBaseWindow Class

Aligns the window to a DWORD boundary for maximum performance.

Syntax

HRESULT PerformanceAlignWindow(void);

Return Value

Returns an HRESULT value.

Remarks

This member function can be called, if the video is not owned by another window, to align the left edge and the top of the window for best display performance.

CBaseWindow::PossiblyEatMessage

CBaseWindow Class

Forwards keyboard and mouse messages to a specified window.

Syntax

virtual BOOL PossiblyEatMessage(
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam
);

Parameters

uMsg
Message that was forwarded.
wParam
First message parameter.
lParam
Second message parameter.

Return Value

Returns FALSE.

CBaseWindow::PrepareWindow

CBaseWindow Class

Creates a window and a worker thread.

Syntax

virtual HRESULT PrepareWindow(void);

Return Value

Returns NOERROR if successful; E_FAIL if unsuccessful.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed in CBaseWindow::DoneWithWindow. The window should also be initialized and uninitialized through CBaseWindow::InitialiseWindow and CBaseWindow::UninitialiseWindow, respectively. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.

CBaseWindow::SetPalette

CBaseWindow Class

Sets a palette for the window to use.

Syntax

virtual HRESULT SetPalette(
    HPALETTE hPalette
);

Parameters

hPalette
Handle to the new palette.

Return Value

Returns an HRESULT value.

Remarks

This member function allows a filter to install a palette in the window object. The palette handle passed in should be non-NULL. The palette is realized when it is installed. The window object does not delete any previous palette that it was using; the client using the window object should ensure it deletes the palette it creates at the appropriate time.

CBaseWindow::UninitialiseWindow

CBaseWindow Class

Flushes GDI and deletes the default device contexts.

Syntax

virtual UninitialiseWindow(void);

Return Value

Returns an HRESULT value. Current implementation returns NOERROR.

Remarks

The base window class creates a window and a worker thread. The worker thread is responsible for pulling messages from the window's input queue and dispatching them as appropriate. The window and its thread are created by CBaseWindow::PrepareWindow and destroyed in CBaseWindow::DoneWithWindow. The window should also be initialized and uninitialized through CBaseWindow::InitialiseWindow and CBaseWindow::UninitialiseWindow, respectively. Having prepared a window and initialized it, the window can be sized using CBaseWindow::ActivateWindow and subsequently hidden using CBaseWindow::InactivateWindow.

m_bActivated	Flag to indicate window activation status.
m_bBackground	Flag to indicate if palettes are to be realized in the background.
m_bDoGetDC	Flag to indicate if the window should get a DC.
m_ClassStyles	Class styles for the window.
m_hdc	Device context (DC) for the window.
m_Height	Client window height.
m_hInstance	Global module instance handle.
m_hPalette	Handle to a palette belonging to this object.
m_hThread	Worker thread for the window.
m_hwnd	Handle for this object's window.
m_MemoryDC	Memory DC used for fast bit-block transfer operations.
m_pClassName	Static string holding the class name.
m_RealizePalette	Message sent to indicate the window palette has changed.
m_ShowStageMessage	Message sent by IVideoWindow::SetWindowForeground that moves the current window to the foreground and optionally gives it focus.
m_ShowStageTop	Message sent to set the window to WS_EX_TOPMOST style.
m_SyncWorker	CAMEvent data member used to provide interthread synchronization.
m_SyncWorkerCreate	CAMMsgEvent data member used to signal the constructor for the window class when to create the window.
m_ThreadSignal	Data member used by the thread to signal errors.
m_Width	Client window width.
m_WindowLock	Data member used to serialize window object access.
m_WindowStyles	Data member used to serialize the initial window styles.
m_WindowStylesEx	Data member used to serialize the initial extended window styles.

CBaseWindow	Constructs a CBaseWindow object.
DoSetWindowForeground	Brings the window to the foreground.
DoShowWindow	Sets the show state of the specified window.
GetMemoryHDC	Retrieves the default off-screen memory device context (DC).
GetWindowHDC	Retrieves the default main window DC.
GetWindowHeight	Retrieves the current window height.
GetWindowHWND	Retrieves the window handle for the window.
GetWindowWidth	Retrieves the current window width.
PerformanceAlignWindow	Aligns the window to a DWORD boundary for maximum performance.
PaintWindow	Invalidates the window client area.

ActivateWindow	Sizes the window according to the requirements of the derived class.
DoneWithWindow	Closes, deletes, and frees the window resources.
DoRealisePalette	Maps palette entries from this window's palette to the system palette. The window's palette is set with CBaseWindow::SetPalette.
PossiblyEatMessage	Forwards keyboard and mouse messages to a specified window.
GetClassWindowStyles	Retrieves class and window information.
GetDefaultRect	Retrieves the default size for the window.
InactivateWindow	Hides the window.
InitialiseWindow	Creates the default device contexts.
OnClose	Handles the WM_CLOSE message for the base class.
OnPaletteChange	Handles WM_PALETTEISCHANGING and WM_PALETTECHANGED messages.
OnSize	Handles WM_SIZE messages for the base class.
OnReceiveMessage	Indicates a base class implementation of a window procedure.
PrepareWindow	Initializes the window along with a worker thread.
SetPalette	Changes the palette that the window should realize.
UninitialiseWindow	Destroys the device contexts created for the window.

E_FAIL	Failure.
E_NOTIMPL	Method is not supported.
NOERROR	No error.