Microsoft DirectX 8.0

CBaseWindow Class

CBaseWindow class hierarchy

Base class for managing windows. Video renderers can use this class to create video windows.

Declaration: Winutil.h

To use this class, create a derived class that inherits from CBaseWindow. In the derived class:

Before using an instance of the derived class, call the PrepareWindow method.

Protected Member Variables
m_hInstanceHandle to the module instance.
m_hwndHandle to the object's window.
m_hdcHandle to the window's device context.
m_WidthWidth of the client area, in pixels.
m_HeightHeight of the client area, in pixels.
m_bActivatedFlag that specifies whether the window has been activated.
m_pClassNameStatic string that contains the name of the window class.
m_ClassStylesClass styles for the window.
m_WindowStylesWindow styles for the window.
m_WindowStylesExExtended window styles for the window.
m_ShowStageMessagePrivate message that brings the window to the foreground.
m_ShowStageTopPrivate message that sets the window style to WS_EX_TOPMOST.
m_RealizePalettePrivate message that realizes the palette.
m_MemoryDCHandle to the memory device context.
m_hPaletteHandle to the window's palette.
m_bNoRealizeFlag that specifies whether the window should realize its palette.
m_bBackgroundFlag that specifies whether the palette should be a background palette.
m_bRealizingFlag that specifies whether a new palette is being realized.
m_WindowLockCritical section, to serialize access to the object.
m_bDoGetDCFlag that specifies whether to retrieve the device context.
m_bDoPostToDestroyFlag that specifies whether the window posts or sends its destruction message.
Protected Methods
OnPaletteChangeHandles palette-change messages. Virtual.
Public Methods
CBaseWindowConstructor method.
DoneWithWindowDestroys the window. Virtual.
PrepareWindowCreates the window. Virtual.
InactivateWindowInactivates the window. Virtual.
ActivateWindowSizes the window according to the requirements of the derived class. Virtual.
OnSizeHandles WM_SIZE messages. Virtual.
OnCloseHandles WM_CLOSE messages. Virtual.
GetDefaultRectRetrieves the default size of the client area. Virtual.
UninitialiseWindowReleases the window's resources. Virtual.
InitialiseWindowInitializes the window. Virtual.
CompleteConnectNotifies the window that the renderer's input pin has been connected.
DoCreateWindowCreates the window.
PerformanceAlignWindowAligns the window to a DWORD boundary, for maximum performance.
DoShowWindowSets the window's show state.
PaintWindowCauses the window to be repainted.
DoSetWindowForegroundBrings the window to the foreground.
SetPaletteInstalls a palette for the window. Virtual.
SetRealizeSpecifies whether the window realizes palettes.
DoRealisePaletteRealizes the window's current palette. Virtual.
PossiblyEatMessageEnables a derived class to forward messages to another window. Virtual.
GetWindowWidthRetrieves the current width of the window.
GetWindowHeightRetrieves the current height of the window.
GetWindowHWNDRetrieves a handle to the window.
GetMemoryHDCRetrieves a handle to the memory device context.
GetWindowHDCRetrieves a handle to the window's device context.
OnReceiveMessageHandles window messages. Virtual.
Pure Virtual Methods
GetClassWindowStylesRetrieves the window's class styles and window styles.

CBaseWindow.m_hInstance

CBaseWindow Class

Handle to the module instance.

Syntax

HINSTANCE m_hInstance;

Remarks

The DLL entry point function sets a global variable with a handle to the module instance. The CBaseWindow class stores this handle in its constructor method.

CBaseWindow.m_hwnd

CBaseWindow Class

Handle to the object's window.

Syntax

HWND m_hwnd;

CBaseWindow.m_hdc

CBaseWindow Class

Handle to the window's device context.

Syntax

HDC m_hdc;

CBaseWindow.m_Width

CBaseWindow Class

Width of the client area, in pixels.

Syntax

LONG m_Width;

CBaseWindow.m_Height

CBaseWindow Class

Height of the client area, in pixels.

Syntax

LONG m_Height;

CBaseWindow.m_bActivated

CBaseWindow Class

Flag that specifies whether the window has been activated. If TRUE, the window has been activated.

Syntax

BOOL m_bActivated;

CBaseWindow.m_pClassName

CBaseWindow Class

Static string that contains the name of the window class.

Syntax

LPTSTR m_pClassName;

CBaseWindow.m_ClassStyles

CBaseWindow Class

Class styles for the window.

Syntax

DWORD m_ClassStyles;

CBaseWindow.m_WindowStyles

CBaseWindow Class

Window styles for the window.

Syntax

DWORD m_WindowStyles;

CBaseWindow.m_WindowStylesEx

CBaseWindow Class

Extended window styles for the window.

Syntax

DWORD m_WindowStylesEx;

CBaseWindow.m_ShowStageMessage

CBaseWindow Class

Private message that brings the window to the foreground.

Syntax

UINT m_ShowStageMessage;

Remarks

The DoSetWindowForeground method sends this message.

CBaseWindow.m_ShowStageTop

CBaseWindow Class

Private message that sets the window style to WS_EX_TOPMOST.

Syntax

UINT m_ShowStageTop;

Remarks

Video renderers should send this message to the window if they switch to full-screen mode.

CBaseWindow.m_RealizePalette

CBaseWindow Class

Private message that realizes the palette.

Syntax

UINT m_RealizePalette;

Remarks

The SetPalette method sends this message.

CBaseWindow.m_MemoryDC

CBaseWindow Class

Handle to the memory device context.

Syntax

HDC m_MemoryDC;

CBaseWindow.m_hPalette

CBaseWindow Class

Handle to the window's palette.

Syntax

HPALETTE m_hPalette;

CBaseWindow.m_bNoRealize

CBaseWindow Class

Flag that specifies whether the window should realize its palette. If TRUE, the window does not realize its palette. The default value is FALSE.

Syntax

BYTE m_bNoRealize;

CBaseWindow.m_bBackground

CBaseWindow Class

Flag that specifies whether the palette should be a background palette. If TRUE, the palette is selected as a background palette.

Syntax

m_bBackground;

CBaseWindow.m_bRealizing

CBaseWindow Class

Flag that specifies whether a new palette is being realized. In debug builds, the value is TRUE while the palette is changing and FALSE otherwise. This variable is not used in retail builds.

Syntax

BYTE m_bRealizing;

CBaseWindow.m_WindowLock

CBaseWindow Class

Critical section, to serialize access to the object.

Syntax

CCritSec m_WindowLock;

CBaseWindow.m_bDoGetDC

CBaseWindow Class

Flag that specifies whether to retrieve the device context (DC). If TRUE, the object retrieves a handle to the window's DC and creates a compatible memory DC.

Syntax

BOOL m_bDoGetDC;

CBaseWindow.m_bDoPostToDestroy

CBaseWindow Class

Flag that specifies whether the window posts or sends its destruction message. If TRUE, the DoneWithWindow method uses the PostMessage function to send itself a private destruction message. If FALSE, DoneWithWindow uses the SendMessage function to send the message. By default, the value is FALSE.

Syntax

BOOL m_bDoPostToDestroy;

CBaseWindow::ActivateWindow

CBaseWindow Class

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

Syntax

virtual HRESULT ActivateWindow(void);

Return Value

Returns one of the HRESULT values shown in the following table.

S_FALSEWindow was already activated.
S_OKSuccess.

Remarks

This methods calls the CBaseWindow::GetDefaultRect method to determine the window size. The derived class should override GetDefaultRect to return the size of the images that will be displayed.

If the window is already active, calling ActivateWindow moves the window to the top of the Z order, but does not resize the window. The same is true if the window has a parent.

CBaseWindow::CBaseWindow

CBaseWindow Class

Constructor method.

Syntax

CBaseWindow(
    BOOL bDoGetDC = TRUE
    BOOL bPostToDestroy = FALSE
);

Parameters

bDoGetDC
Boolean value that specifies whether to retrieve the device context.
bPostToDestroy
Boolean value that specifies the m_bDoPostToDestroy member variable.

Remarks

After you create the object, call the PrepareWindow method to create the window. PrepareWindow is a virtual method. It calls InitialiseWindow, also a virtual method. These methods are separated from the constructor so that derived classes can override them, if necessary.

If the value of the bDoGetDC parameter is TRUE, the CBaseWindow object retrieves a handle to the window's device context (DC) and stores it in the m_hdc member variable. The object also creates a compatible memory DC, which it stores in the m_MemoryDC member variable. These actions occur in the InitialiseWindow method.

CBaseWindow::CompleteConnect

CBaseWindow Class

Notifies the window that the renderer's input pin has been connected.

Syntax

HRESULT CompleteConnect(void);

Return Value

Returns S_OK.

Remarks

This method resets the window activation flag (m_bActivated) to FALSE. When a video renderer completes a pin connection, it might call the ActivateWindow method to set the window's size and position. To force ActivateWindow to recalculate these attributes, first call the CompleteConnect method.

CBaseWindow::DoCreateWindow

CBaseWindow Class

Creates the window.

Syntax

HRESULT DoCreateWindow(void);

Return Value

Returns S_OK if successful, or an HRESULT value indicating the cause of the failure.

Remarks

The PrepareWindow method calls this method.

CBaseWindow::DoneWithWindow

CBaseWindow Class

Destroys the window.

Syntax

virtual HRESULT DoneWithWindow(void);

Return Value

Returns S_OK.

Remarks

Call this method from the derived object's destructor method.

If this method is called from the same thread that created the window, the method performs the following actions:

If the thread calling DoneWithWindow is not the thread that created the window, the method sends a private "destroy" message to the window. When the window receives this message, it calls DoneWithWindow on itself. (If m_bDoPostToDestroy is TRUE, the window posts the message.)

CBaseWindow::DoRealisePalette

CBaseWindow Class

Realizes the window's current palette.

Syntax

virtual HRESULT DoRealisePalette(
    BOOL bForceBackground
);

Parameters

bForceBackground
Boolean value that specifies whether the palette is forced to be a background palette. For more information, see SelectPalette in the Platform SDK.

Return Value

Returns one of the HRESULT values shown in the following table.

S_FALSEAn internal call to GdiFlush returned an error.
S_OKSuccess.

Remarks

The CBaseWindow::OnPaletteChange method calls this method. To set a new palette, call the CBaseWindow::SetPalette method.

CBaseWindow::DoSetWindowForeground

CBaseWindow Class

Brings the window to the foreground.

Syntax

void DoSetWindowForeground(
    BOOL bFocus
);

Parameters

bFocus
Boolean value that specifies whether to give the window focus. If the value is TRUE, the window gains focus.

CBaseWindow::DoShowWindow

CBaseWindow Class

Sets the window's show state.

Syntax

HRESULT DoShowWindow(
    LONG ShowCmd
);

Parameters

ShowCmd
Flag that specifies how the window is to be shown. The value can be any constant defined for the nCmdShow parameter of the Microsoft® Windows® ShowWindow function. For more information, see the Platform SDK.

Return Value

Returns S_OK.

CBaseWindow::GetClassWindowStyles

CBaseWindow Class

Retrieves the window's class styles and window styles.

Syntax

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

Parameters

pClassStyles
Pointer to a variable that receives the class styles.
pWindowStyles
Pointer to a variable that receives the window styles.
pWindowStylesEx
Pointer to a variable that receives the extended window styles.

Return Value

Returns a static text string that contains the class name.

Remarks

The CBaseWindow::PrepareWindow method calls this method to retrieve the window's class styles and window styles.

This method is pure virtual; the derived class must implement it. The following example shows a possible implementation:

LPTSTR CMyWindowClass::GetClassWindowStyles(DWORD *pClassStyles,
                                            DWORD *pWindowStyles,
                                            DWORD *pWindowStylesEx)
{
    *pClassStyles = CS_HREDRAW | CS_VREDRAW;
    *pWindowStyles = WS_OVERLAPPEDWINDOW | WS_CLIPCHILDREN;
    *pWindowStylesEx = WS_EX_WINDOWEDGE;
    return TEXT("MyWindowClass");
}

The object uses the class style for the lpszClassName member of a WNDCLASS structure, which it passes to the RegisterClass function. The object uses the window styles for the dwExStyle and dwStyle parameters of the CreateWindowEx function. For more information, see the Platform SDK.

CBaseWindow::GetDefaultRect

CBaseWindow Class

Retrieves the default size of the client area.

Syntax

virtual RECT GetDefaultRect(void);

Return Value

Returns the default rectangle.

Remarks

When the window is activated, the object calls this method to determine how large it should make the window's client area. In the base class, this method returns a rectangle whose height and width are the defined constants DEFHEIGHT and DEFWIDTH. A derived class should override this method. For a video renderer, the derived class will typically return the size of the native video image.

CBaseWindow::GetMemoryHDC

CBaseWindow Class

Retrieves a handle to the memory device context (DC).

Syntax

virtual HDC GetMemoryHDC(void);

Return Value

Returns a handle to the memory DC.

CBaseWindow::GetWindowHDC

CBaseWindow Class

Retrieves a handle to the window's device context (DC).

Syntax

HDC GetWindowHDC(void);

Return Value

Returns a handle to the DC.

CBaseWindow::GetWindowHeight

CBaseWindow Class

Retrieves the current height of the window.

Syntax

LONG GetWindowHeight(void);

Return Value

Returns the height of the window, in pixels.

CBaseWindow::GetWindowHWND

CBaseWindow Class

Retrieves a handle to the window.

Syntax

HWND GetWindowHWND(void);

Return Value

Returns a handle to the window.

CBaseWindow::GetWindowWidth

CBaseWindow Class

Retrieves the current width of the window.

Syntax

LONG GetWindowWidth(void);

Return Value

Returns the width of the window, in pixels.

CBaseWindow::InactivateWindow

CBaseWindow Class

Inactivates the window. In the base class, this method hides the window.

Syntax

virtual HRESULT InactivateWindow(void);

Return Value

Returns one of the HRESULT values shown in the following table.

S_OKSuccess.
S_FALSEWindow is already inactive.

CBaseWindow::InitialiseWindow

CBaseWindow Class

Initializes the window.

Syntax

virtual InitialiseWindow(
    HWND hwnd
);

Parameters

hwnd
Handle to the window.

Return Value

Returns S_OK.

Remarks

By default, this method retrieves a handle to the window's device context (DC) and creates a compatible memory DC. If the value of the m_bDoGetDC flag is FALSE, however, this method does not retrieve the device contexts. The memory DC is useful for selecting bitmaps before blitting them to the window.

The DoCreateWindow method calls this method.

CBaseWindow::OnClose

CBaseWindow Class

Handles WM_CLOSE messages.

Syntax

virtual BOOL OnClose(void);

Return Value

Returns TRUE.

Remarks

In the base class, this method simply hides the window. Typically, a derived class will override this method so that it sends an EC_USERABORT event as well. Do not override the method to destroy the window. Instead, call the CBaseWindow::DoneWithWindow method when the owning filter is destroyed.

CBaseWindow::OnPaletteChange

CBaseWindow Class

Handles palette-change messages.

Syntax

virtual LRESULT OnPaletteChange(
    HWND hwnd,
    UINT Message
);

Parameters

hwnd
Handle to the window.
Message
Message identifier.

Return Value

Returns 0 if the message was processed, or 1 if the message was not processed.

Remarks

This method handles WM_PALETTECHANGED and WM_QUERYNEWPALETTE messages. It calls the DoRealisePalette method to realize the new palette.

CBaseWindow::OnReceiveMessage

CBaseWindow Class

Handles window messages.

Syntax

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

Parameters

hwnd
Handle to the window.
uMsg
Message identifier.
wParam
First message parameter.
lParam
Second message parameter.

Return Value

Returns 0 if the message was processed, or 1 if the message was not processed.

Remarks

The base class handles the following messages:

A derived class can override this method to handle other messages. The derived class should call the base class method to handle any messages that the derived class ignores.

CBaseWindow::OnSize

CBaseWindow Class

Handles WM_SIZE messages.

Syntax

virtual BOOL OnSize(
    LONG Width,
    LONG Height
);

Parameters

Width
Width of the client area, in pixels.
Height
Height of the client area, in pixels.

Return Value

Returns TRUE.

Remarks

This method stores the new width and height. To retrieve these values, call the CBaseWindow::GetWindowHeight and CBaseWindow::GetWindowWidth methods.

CBaseWindow::PaintWindow

CBaseWindow Class

Causes the window to be repainted.

Syntax

void PaintWindow(
    BOOL bErase
);

Parameters

bErase
Boolean value that specifies whether the background is erased. If the value is TRUE, the background is erased.

Remarks

This method generates a WM_PAINT message by invalidating the window's entire client area.

CBaseWindow::PerformanceAlignWindow

CBaseWindow Class

Aligns the window to a DWORD boundary, for maximum performance.

Syntax

HRESULT PerformanceAlignWindow(void);

Return Value

Returns S_OK.

Remarks

This method aligns the left and top edges of the window to DWORD boundaries, which can improve performance. If the window has a parent, the method returns S_OK but does perform the alignment.

CBaseWindow::PossiblyEatMessage

CBaseWindow Class

Enables a derived class to forward messages to another window.

Syntax

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

Parameters

uMsg
Message identifier.
wParam
First message parameter.
lParam
Second message parameter.

Return Value

Returns TRUE if the message was forwarded, or FALSE otherwise. The base class returns FALSE.

Remarks

Before the CBaseWindow::OnReceiveMessage method handles a message, it calls PossiblyEatMessage. If PossiblyEatMessage returns TRUE, OnReceiveMessage ignores the message. A derived class can override PossiblyEatMessage so that it forwards some messages to an owner window. For example, the CBaseControlWindow class, which derives from CBaseWindow, forwards keyboard and mouse messages.

CBaseWindow::PrepareWindow

CBaseWindow Class

Creates the window.

Syntax

virtual HRESULT PrepareWindow(void);

Return Value

Returns an HRESULT value. Possible values include those shown in the following table.

S_OKSuccess.
E_FAILFailure.

Remarks

Call this method after creating the object. This method performs some initial bookkeeping and then calls the DoCreateWindow method to create the window.

CBaseWindow::SetPalette

CBaseWindow Class

Installs a palette for the window.

Syntax

virtual HRESULT SetPalette(
    HPALETTE hPalette
);

HRESULT SetPalette(void);

Parameters

hPalette
Handle to the new palette. Cannot be NULL.

Return Value

Returns one of the HRESULT values shown in the following table.

S_FALSEAn internal call to GdiFlush returned an error.
S_OKSuccess.

Remarks

The hPalette parameter specifies a new palette. If the method is called with no parameters, the palette given by the m_hPalette member variable is selected. The caller must ensure the validity of m_hPalette.

If the value of the m_bNoRealize member variable is FALSE (the default), this method selects the palette and realizes it. Otherwise, it selects the palette but does not realize it. The object does not delete any previous palette that it was using. The caller is responsible for deleting palettes.

Any thread can safely call this method, not just the thread that owns the window. The window sends a private message to itself, which triggers a call to the OnPaletteChange method.

CBaseWindow::SetRealize

CBaseWindow Class

Specifies whether the window realizes palettes.

Syntax

void SetRealize(
    BOOL bRealize
);

Parameters

bRealize
Boolean value that specifies whether to realize palettes. If TRUE, the SetPalette method realizes palettes.

Remarks

By default, the SetPalette method realizes the specified palette. Call this method to change the default behavior, so that palettes are selected but not realized. This method sets the m_bNoRealize member variable.

CBaseWindow::UninitialiseWindow

CBaseWindow Class

Releases the window's resources.

Syntax

virtual UninitialiseWindow(void);

Return Value

Returns S_OK.

Remarks

This method frees resources that were acquired by the InitialiseWindow method. The DoneWithWindow method calls this method.