Microsoft DirectX 8.0 |
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_hInstance | Handle to the module instance. |
m_hwnd | Handle to the object's window. |
m_hdc | Handle to the window's device context. |
m_Width | Width of the client area, in pixels. |
m_Height | Height of the client area, in pixels. |
m_bActivated | Flag that specifies whether the window has been activated. |
m_pClassName | Static string that contains the name of the window class. |
m_ClassStyles | Class styles for the window. |
m_WindowStyles | Window styles for the window. |
m_WindowStylesEx | Extended window styles for the window. |
m_ShowStageMessage | Private message that brings the window to the foreground. |
m_ShowStageTop | Private message that sets the window style to WS_EX_TOPMOST. |
m_RealizePalette | Private message that realizes the palette. |
m_MemoryDC | Handle to the memory device context. |
m_hPalette | Handle to the window's palette. |
m_bNoRealize | Flag that specifies whether the window should realize its palette. |
m_bBackground | Flag that specifies whether the palette should be a background palette. |
m_bRealizing | Flag that specifies whether a new palette is being realized. |
m_WindowLock | Critical section, to serialize access to the object. |
m_bDoGetDC | Flag that specifies whether to retrieve the device context. |
m_bDoPostToDestroy | Flag that specifies whether the window posts or sends its destruction message. |
Protected Methods | |
OnPaletteChange | Handles palette-change messages. Virtual. |
Public Methods | |
CBaseWindow | Constructor method. |
DoneWithWindow | Destroys the window. Virtual. |
PrepareWindow | Creates the window. Virtual. |
InactivateWindow | Inactivates the window. Virtual. |
ActivateWindow | Sizes the window according to the requirements of the derived class. Virtual. |
OnSize | Handles WM_SIZE messages. Virtual. |
OnClose | Handles WM_CLOSE messages. Virtual. |
GetDefaultRect | Retrieves the default size of the client area. Virtual. |
UninitialiseWindow | Releases the window's resources. Virtual. |
InitialiseWindow | Initializes the window. Virtual. |
CompleteConnect | Notifies the window that the renderer's input pin has been connected. |
DoCreateWindow | Creates the window. |
PerformanceAlignWindow | Aligns the window to a DWORD boundary, for maximum performance. |
DoShowWindow | Sets the window's show state. |
PaintWindow | Causes the window to be repainted. |
DoSetWindowForeground | Brings the window to the foreground. |
SetPalette | Installs a palette for the window. Virtual. |
SetRealize | Specifies whether the window realizes palettes. |
DoRealisePalette | Realizes the window's current palette. Virtual. |
PossiblyEatMessage | Enables a derived class to forward messages to another window. Virtual. |
GetWindowWidth | Retrieves the current width of the window. |
GetWindowHeight | Retrieves the current height of the window. |
GetWindowHWND | Retrieves a handle to the window. |
GetMemoryHDC | Retrieves a handle to the memory device context. |
GetWindowHDC | Retrieves a handle to the window's device context. |
OnReceiveMessage | Handles window messages. Virtual. |
Pure Virtual Methods | |
GetClassWindowStyles | Retrieves the window's class styles and window styles. |
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.
Handle to the object's window.
Syntax
HWND m_hwnd;
Handle to the window's device context.
Syntax
HDC m_hdc;
Width of the client area, in pixels.
Syntax
LONG m_Width;
Height of the client area, in pixels.
Syntax
LONG m_Height;
Flag that specifies whether the window has been activated. If TRUE, the window has been activated.
Syntax
BOOL m_bActivated;
Static string that contains the name of the window class.
Syntax
LPTSTR m_pClassName;
Class styles for the window.
Syntax
DWORD m_ClassStyles;
Window styles for the window.
Syntax
DWORD m_WindowStyles;
Extended window styles for the window.
Syntax
DWORD m_WindowStylesEx;
Private message that brings the window to the foreground.
Syntax
UINT m_ShowStageMessage;
Remarks
The DoSetWindowForeground method sends this message.
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.
Private message that realizes the palette.
Syntax
UINT m_RealizePalette;
Remarks
The SetPalette method sends this message.
Handle to the memory device context.
Syntax
HDC m_MemoryDC;
Handle to the window's palette.
Syntax
HPALETTE m_hPalette;
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;
Flag that specifies whether the palette should be a background palette. If TRUE, the palette is selected as a background palette.
Syntax
m_bBackground;
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;
Critical section, to serialize access to the object.
Syntax
CCritSec m_WindowLock;
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;
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;
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_FALSE Window was already activated. S_OK Success.
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.
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.
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.
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.
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:
- Calls the InactivateWindow method, which deactivates the window.
- Calls the UninitialiseWindow method, which releases resources used by the window.
- Destroys the window.
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.)
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_FALSE An internal call to GdiFlush returned an error. S_OK Success.
Remarks
The CBaseWindow::OnPaletteChange method calls this method. To set a new palette, call the CBaseWindow::SetPalette method.
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.
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.
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.
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.
Retrieves a handle to the memory device context (DC).
Syntax
virtual HDC GetMemoryHDC(void);
Return Value
Returns a handle to the memory DC.
Retrieves a handle to the window's device context (DC).
Syntax
HDC GetWindowHDC(void);
Return Value
Returns a handle to the DC.
Retrieves the current height of the window.
Syntax
LONG GetWindowHeight(void);
Return Value
Returns the height of the window, in pixels.
Retrieves a handle to the window.
Syntax
HWND GetWindowHWND(void);
Return Value
Returns a handle to the window.
Retrieves the current width of the window.
Syntax
LONG GetWindowWidth(void);
Return Value
Returns the width of the window, in pixels.
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_OK Success. S_FALSE Window is already inactive.
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.
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.
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.
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:
- WM_CLOSE
- WM_MOVE
- WM_PALETTECHANGED
- WM_QUERYNEWPALETTE
- WM_SIZE
- WM_SYSCOLORCHANGE
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.
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.
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.
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.
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.
Creates the window.
Syntax
virtual HRESULT PrepareWindow(void);
Return Value
Returns an HRESULT value. Possible values include those shown in the following table.
S_OK Success. E_FAIL Failure.
Remarks
Call this method after creating the object. This method performs some initial bookkeeping and then calls the DoCreateWindow method to create the window.
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_FALSE An internal call to GdiFlush returned an error. S_OK Success.
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.
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.
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.