In this section:
The %dw (Owner Draw Graphics) format allows you to access the Windows GDI directly to prepare a bitmap for display. This is a low level method that has been provided primarily for the integration of certain existing packages. It does not use ClearWin+ drawing routines (that is, it does not generate a drawing surface).
The format takes one argument that is a handle to a device context acquired by calling the ClearWin+ function GET_BITMAP_DC@. This handle accesses a bitmap that is drawn to using standard Windows API functions. It is never necessary to re-paint the area because the bitmap remains in existence even if the window is obscured.
The device context will continue to exist (together with its associated bitmap) until released with the ClearWin+ function RELEASE_BITMAP_DC@. At normal program termination the system will automatically release device contexts acquired by GET_BITMAP_DC@, so it is only necessary to use RELEASE_BITMAP_DC@ in complex programs that manipulate many graphics bitmaps.
c--- The next line is not necessary unless ---
c--- many device contexts will be acquired ---
Note that you can continue to change the graphics in the bitmap after the window has been displayed (from call-back functions, or using the %lw (Leave Window Open) format to leave the window in place) provided that WINDOW_UPDATE@(HDC) is used to update the screen, where HDC is the handle of the device context. Other routines that operate in terms of a handle to a device context are listed in Graphics functions(device context).
When it is created, the bitmap will be filled with the default background window colour (i.e. it will be invisible unless displayed inside a shaded box). The colour can be changed with a call to the standard Windows API FillRect function.
It is possible to change the pen associated with a device context acquired by calling the ClearWin+ function GET_BITMAP_DC@, without worrying about deleting used pens. This is performed by calling the ClearWin+ CHANGE_PEN@. The first argument in this function is a device context acquired by calling GET_BITMAP_DC@ followed by three other arguments similar those supplied to the Windows API CreatePen function.
Currently the option list, if present, may contain:
%dw can take the option user_resize, which allows it to be re-sized as the pivot item of a window. In this form, %dw does not take a handle from GET_BITMAP_DC@ as an argument, but two integers specifying the initial width and depth of the desired owner-draw region. A call-back function must be supplied in this case. When the call-back function is called, it can check the CLEARWIN_INFO@ parameter GRAPHICS_RESIZING to determine that it is being called to re-draw the image (the image is deemed to be re-sized once as it is created, so all the drawing code can be placed in the call-back).
The call-back function should use CLEARWIN_INFO@ to obtain GRAPHICS_DC, GRAPHICS_WIDTH, and GRAPHICS_DEPTH. Traditional Windows programmers should note that although your function will be called to re-draw the image each time the size changes, you will not be called each time a WM_PAINT message is processed. For example, if the image is obscured and then exposed again without change, your function will not be called.
With this option the %dw call-back function is called each time the mouse is moved, or a button is pressed or released within the area of the control. Otherwise the call-back function only responds to mouse input when the user clicks on the control.