Owner draw box format - %dw[options]
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
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 - Owner Draw Graphics 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.
You can use get_mouse_info@ to obtain mouse data from within a %dw - Owner Draw Graphics