Note: Sample plugin code for custom drawn list boxes is available for download in the List box handler reference.

The SETLISTBOXDRAWFUNC is an extremely powerful enhancement of the list box user interface element. Whilst the standard list box functions provide built in flat and shaded list boxes there are cases where complex controls are required. This statement allows the SSE to draw its own list box, meaning that a control can have any appearance required including GIF/JPG/BMP/PNG images on or around the list box (or even used for the entire list box itself).

Note: When using custom drawn list boxes it is useful to specify the X,Y position of the top left of the text in the control, and it's maximum width and height. This allows a border around the text to be defined. To set this border refer to setlistboxtextrect.

Note: True per-pixel alphablending in PNG images is supported. This allows for smooth, blended edges of controls. Note that fastdraw must be disabled for PNG alphablending as true blending can only be achieved by recalculating the panel contents.

The SETLISTBOXDRAWFUNC is called with the name of a specific function as the second parameter. The function is prototyped as follows:

bool function MyListBoxDrawing(int iState, int iWidth, int iHeight)

The name of the function can be anything required, this of course allows for more than one control-drawing functions.

When SETLISTBOXDRAWFUNC is called, it immediately prepares Brass for drawing functions. It then calls the function provided as the second parameter. Inside this function you may use any Brass drawing function, exactly as you would in the Render handler.

The specified drawing function is actually called multiple times. The only change between calls is the value of the iState parameter, which tells the plugin code what state Brass is expecting to be drawn. The following values of iState will be passed to your custom draw handler:

SSEdit define	Integer value	State to be drawn
LISTBOX_BASE	0	The base of the listbox. You should draw your listbox exactly as you want it to appear, excluding any text and the scrollbars.
SCROLLBAR_RANGE	21	The scroll range. The scroll thumb and scroll buttons are drawn on top of this image, therefore this should be drawn as the overall height of the scrollbar.
SCROLLBAR_UP_NORMAL	22	The scroll up button when it is not pressed.
SCROLLBAR_DOWN_NORMAL	23	The scroll down button when it is not pressed
SCROLLBAR_UP_PRESSED	24	The scroll up button when it is pressed
SCROLLBAR_DOWN_PRESSED	25	The scroll down button when it is pressed
SCROLLBAR_THUMB	26	The scroll thumb. This should be the entire thumb, the segments of the thumb to allow scaling are set using the setscrollbarthumbsegs statement.

Note: when the custom drawing function is called with iState == LISTBOX_BASE, the iWidth and iHeight parameters will contain the overall width and height of the listbox. When iState == SCROLLBAR_RANGE, iWidth and iHeight will contain the width and height of the scrollbar only. When iState is set to any of the button state defines (SCROLLBAR_UP_NORMAL, SCROLLBAR_DOWN_NORMAL, SCROLLBAR_UP_PRESSED, SCROLLBAR_DOWN_PRESSED), iWidth and iHeight will be set to the width and height of the buttons. When iState == SCROLLBAR_THUMB, iWidth and iHeight will be set to the width of the scrollbar and the height of the thumb segments combined.

Implementation note: Although SCROLLBAR_THUMB causes iWidth and iHeight will be set to the width of the scrollbar and the height of the thumb segments combined, Brass allows you to draw into a "canvas" that is the same width and height as the scroll range. This is a deviation from the normal process, but it is necessary to avoid a chicken-and-egg situation. setscrollbarthumbsegs may only be called after SETLISTBOXDRAWFUNC has been called. Brass only knows the thumb segment sizes once setscrollbarthumbsegs is called, but it must provide some width and height parameters for the SCROLLBAR_THUMB state in the custom draw handler. Because it's not possible to call setscrollbarthumbsegs before SETLISTBOXDRAWFUNC (the call is simply ignored) a catch-22 situation occurs. To solve this you are allowed to draw your thumb image in a canvas sized the same as the scroll range. You should ensure your drawing begins at X: 0, Y: 0, and that you call setscrollbarthumbsegs after SETLISTBOXDRAWFUNC to configure the correct segment sizes.

There is a comprehensive explanation of the custom draw process in the seteditboxdrawfunc documentation. The process is exactly the same for all controls, the only difference being the value of the iState parameter.

If you do not return boolean TRUE for states you draw, Brass will destroy your drawing and replace it with a standard list box display.

The following scrollbar statements are essential for proper display of custom drawn listboxes:

• setscrollbarpos - Sets the display position of the scrollbar within the list control
• setscrollbarsize - Sets the width and height of the scrollbar
• setscrollbarthumbsegs - Defines the top, middle and bottom "segments" of the thumb, to allow for scaling
• setscrollbarbuttonheight - Sets the height of the up and down scrollbar buttons

These statements enable you to position and size each element of the listbox scrollbar so that it appears correctly within the custom drawn listbox.

Implementation note: Controls may be drawn as complex as you require. Brass calls the control drawing function only when SETLISTBOXDRAWFUNC is called, and caches the controls you draw. Therefore when the display panel must be redrawn, Brass already has the custom control stored in memory and available to draw.

Because of this smart-management system, custom drawn controls are no slower for use than standard, flat controls.

 

Parameters

ID

The control ID of the list box you wish to draw manually

FuncName

The name of the function within the plugin that will be called to draw the control states

 

Return Value

None

Example Code

Sample plugin code for custom drawn list boxes is available for download in the List box handler reference.