COXBackgroundPainter & COXBackgroundPainterOrganizer
Copyright © Dundas Software Ltd. 1997 - 1998, All Rights Reserved

COXBackgroundPainter class is designed to simplify the process of window background painting. It provides the functionality of painting the background of the window with specified image and/or color.
For some reason background painting never been a trivial task. By default, painting happens when WM_ERASEBKGND message is sent to window. If you
don't handle this message in any specific way then Windows use background brush associated with the corresponding window class in order to fill the background of the window. So in order to paint the window using different color you would have to handle WM_ERASEBKGND message or alternatively create new window class for your window with the brush of color you need. 
Painting window's background with different color is neither difficult nor interesting task. But painting background of window with some image (like Windows Desktop) could add some value to your application.
COXBackgroundPainter class provides that kind of functionality. And it takes only one function call in order to setup a window to be painted in new fancy way. 
As a number of other Ultimate Toolbox classes COXBackgroundPainter class is derived from COXHookWnd class. This class allows to handle any messages before the hooked window does. Also internally COXBackgroundPainter uses COXDIB object in order to draw 256> color images. 
In order to set any window background to be painted using COXBackgroundPainter object you have to hook such window using the following function: 
Attach()
In the function you specify the pointer to the window to be hooked, info about the image to be used while painting the background (you can specify COXDIB object, resource or file name), type of image drawing (Tile, Stretch, Center, ...), background color to be used to fill the window background that is not covered by image (refer to the documentation on this function for details), and pointer to the window which top/left point of its paintable rectangle will be used as origin point for painting routines (this is very important if you need to align the background among different child windows of the same parent window). 
It's highly probable that Attach() function will be the only one that you will use in your applications but we defined a set of additional functions that allows you to control all aspects of the class functionality. 
Use Detach() function in order to unhook any attached window. In order to change window background painting properties at run-time without detaching and attaching it use the following set of functions: 
SetWallpaper()
SetPaintType()
SetBkColor() 
SetOriginWnd()

To retrieve background painting properties call: 
GetWallpaperImage()
GetPaintType()
GetBkColor()
GetOriginWnd()

As you can see it's really easy to use this class, but unfortunately every story has two sides. We mentioned above about the standard way Windows paints the background of any window. It is TRUE for any window unless specific window handles the process of its drawing and paint its background in different way (e.g. in WM_PAINT handler). Almost all   standard controls paint their background and almost all of them do this differently. E.g. some of the controls like tree control, list control or toolbar support powerful NM_CUSTOMDRAW notification. Others, like static or edit controls should handle WM_CTLCOLOR message in order to paint the background. And also we shouldn't forget about ownerdraw controls too! 
The question is how to use COXBackgroundPainter class in such cases. There is no easy answer that will work for any control but generally you can use the following approach:
1) Try to hook the control using Attach() function and test if  it paints the background correctly. If everything is alright then you are lucky and you are using the control that was designed consistently with the Windows treat background painting. 
2) Otherwise you have to provide the background painting for such control explicitly at some point depending on the functionality of the control (refer to the documentation on the corresponding control to make a decision where to put background painting code). You still  can use COXBackgroundPainter class in this case but at the appropriate moment you have to explicitly call the following function in order to paint the background:
DrawWallpaper() 
You only have to specify the device context to paint the background in and this function will take care of everything else itself.
In most applicable cases (like painting the background of dialog, MDIClient or View windows) COXBackgroundPainter class will work without any additional 
efforts from your side. But you still have to have one COXBackgroundPainter object for every window that is going to be hooked. This could be a little bit inconvenient, especially if you are going to provide background painting support for a number of windows within the same framework.
In order to simplify things we designed COXBackgroundPainterOrganizer class. COXBackgroundPainterOrganizer provides very similar to COXBackgroundPainter set of functions. E.g. the definition of Attach() function is completely the same. The only difference is that when you call this function for new window new COXBackgroundPainter object will be instantiated and its Attach() function will be called. At any moment you can define whether given window is attached to a COXBackgroundPainter object calling function: 
IsAttached() 
You can retrieve the pointer to the COXBackgroundPainter object that corresponds to the specified window using function: 
GetPainter();
Refer to the COXBackgroundPainterOrganizer class reference documentation for details on the rest of functions.
As long as COXBackgroundPainterOrganizer class provides almost the same functionality as COXBackgroundPainter does and it really simplify things when you hook multiple windows within the same parent window, we suggest that COXBackgroundPainterOrganizer should be used preferably. 
 
One of an interesting aplication of COXBackgroundPainterOrganizer class is the following: you want to display 256> color image in the About Box of your company logo. If you use Picture (actually, CStatic control) object to do that then you don't have palette support and the size of control will depend on the size of image. Instead you can do the following: 
1) Create the window that will be used to display picture
2) Hook this window using COXBackgroundPainterOrganizer object and specify the image that will be displayed
Pretty easy.

Special note:    How to use COXBackgroundPainterOrganizer to display 256> color bitmaps when 256 color video mode is set.

In order to do that we have to release the background image palette when WM_PALETTECHANGED and WM_QUERYNEWPALETTE messages are sent to attached window. It's implemented automatically for you in COXBackgroundPainter class but there is small problem. WM_PALETTECHANGED and WM_QUERYNEWPALETTE messages are sent only to top-level and overlapped windows. So background images will be correctly displayed for dialog or mainframe window, but for non-overlapped child windows you have to provide some way of notifying them that they have to update system palette. We suggest the following solution for your problem. In the class that is guaranteed to get WM_PALETTECHANGED and WM_QUERYNEWPALETTE messages (e.g. it could be your main frame window or dialog window) you include handlers for them. In the handlers you forward these messages to the windows that are hooked using COXBackgroundPainterOrganizer or alternatively you can send these messages to all descendant windows using CWnd::SendMessageToDescendants() function.

All above mentioned techniques are implemented in the BackgroundPainter sample that can be found in .\samples\gui\BackgroundPainter subdirectory
of your Ultimate Toolbox directory.

Source code files: 
"OXBackgroundPainter.cpp" 
The following file implements hooking functionality: 
"OXHookWnd.cpp" 
The following file implements support for DIB files: 
"OXDib.cpp"