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

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

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

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 SETEDITBOXDRAWFUNC is called with the name of a specific function as the second parameter. The function is prototyped as follows:

bool function MyEditboxDrawing(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 SETEDITBOXDRAWFUNC 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 twice. The only change between calls is the value of the iState parameter. The first call to the drawing function sets the value of iState to 0. This indicates you should draw the edit box in its normal, unfocused state.

When your drawing function returns, Brass cleans up and prepares for drawing again. It then calls your drawing function a second time with the value of iState set to 1. This indicates you should draw the button in its focused state. The focused state is when a user has clicked on the edit box and is able to type text into it.

You may use the definitions of EDITBOX_NORMAL ( = 0) and EDITBOX_FOCUSED ( = 1) to test which state you are being asked to draw.

The iWidth and iHeight parameters contain the width and height of the control. These values are exactly the same as the dimensions you specified for the createeditbox statement, they are simply passed as parameters here for convenience, to save you storing the values as global variables.

When you have drawn a state you must return boolean TRUE. Brass checks the return value of your custom draw handler to decide what actions need to be taken. This is to ensure future compatibility. Brass knows what state it asked the plugin to draw, and checks the return value of the handler. If the return value is boolean TRUE, Brass notes that the plugin has successfully drawn the requested state and caches the output. If the return value is boolean FALSE, Brass assumes that the plugin did not draw the requested state. In this case Brass will make a best-guess attempt to draw the control on the plugin's behalf.

This ensures future compatibility for the following reason. Assume that Brass version 1.0 allows for two-state buttons: normal, and clicked. A plugin written for Brass 1.0 will handle the BUTTON_NORMAL and BUTTON_CLICKED states in its custom draw handler, and return boolean TRUE for both. When Brass version 2.0 is released, it allows for three-state buttons: normal, mouse-over, and clicked. A plugin written for Brass 2.0 will now handle BUTTON_NORMAL, BUTTON_CLICKED and BUTTON_MOUSEOVER correctly. However a plugin written for Brass 1.0 that's run in Brass 2.0 will only handle BUTTON_NORMAL and BUTTON_CLICKED. This means when Brass calls the custom draw handler for the version 1.0 plugin, only 2 states will be drawn and the mouseover state will be left blank. This will obviously be visually incorrect.

However, because the version 1.0 plugin returns boolean TRUE for BUTTON_NORMAL and BUTTON_CLICKED, and boolean FALSE for everything else, when Brass called the custom draw handler with BUTTON_MOUSEOVER and boolean FALSE was returned Brass was able to tell that the plugin doesn't support the mouseover state. It can then make a best-guess drawing attempt for the mouseover state (or flag that a mouseover state should not be used).

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

An overview of the process is as follows:

seteditboxdrawfunc is called: seteditboxdrawfunc(ControlID, "DrawFunc");
Brass prepares drawing states
Brass calls the DrawButton function	The iState parameter of the DrawFunc function is set to 0
The DrawFunc function begins
The function checks the value of iState	If iState is 0, the normal edit box must be drawn
The normal edit box is drawn here	Any Brass drawing function may be used
The function returns True	This signifies the requested state has been drawn
The DrawFunc function ends
Brass prepares new drawing states
Brass calls the DrawFunc function	The iState parameter of the DrawFunc function is set to 1
The DrawFunc function begins
The function checks the value of iState	If iState is 1, the focused edit box must be drawn
The focused edit box is drawn here	Any Brass drawing function may be used
The function returns True	This signifies the requested state has been drawn
The DrawFunc function ends

 

Although this may seem complex, all of the implementation is managed by Brass.

Implementation note: Controls may be drawn as complex as you require. Brass calls the control drawing function only when SETEDITBOXDRAWFUNC 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.

It is possible to use the custom draw control system in conjunction with the standard styles. This can be useful if you need to display an icon on a gradient-shaded control. To do this, first call seteditboxstyle with the appropriate parameters to draw the required gradient. Then call SETEDITBOXDRAWFUNC and specify your callback drawing function. When your drawing function is called, the control will already have the gradient drawn to it. This allows you to simply make any further drawing actions over the top.

Parameters

ID

The control ID of the edit 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 edit boxes is available for download in the Edit box handler reference.