The SETHANDLER statement sets the event handler function that is called in response to an event occurring for the specified control. An example of an event would be a button control being clicked.

When a control receives an event, Brass calls the specified handler to notify the SSE something happened. It is the plugin's responsibility to act on the event.

The purpose of this statement is to allow plugins to associate specific controls with specific functions. For example, if clicking a button always displayed an image it would be sensible to associate that button with a handler that displays an image. Each type of control has a specific handler prototype (style of function, such as return value and parameters) that must be used. Refer to the individual control reference for each control to locate the appropriate handler prototype.

Specifying a handler for a control is not mandatory. It is also perfectly acceptable to associate multiple controls with one event handler, which is useful if the controls in question mostly perform the same action with a minor variation (for example: 2 buttons that load and display images, one displays the next image in a sequence, the other displays the previous image). Using a single handler for multiple controls reduces code duplication.

Parameters

ID

The ID of the control to set the handler for

FuncName

The name of the function to use as the event handler

 

Return Value

True if the assignment succeeded (if the control ID was valid and the function was found in the plugin), otherwise False.

Example Code

function Init()
{
    int ExplorerButtonID = createbutton(1, 10, 10, 50, 20);
    sethandler(ExplorerButtonID, "ExplorerButton");
}

function ExplorerButton(int iControlID, int iMessage)
{
    // iMessage contains the event ID, 1 is a button click, SSEdit
    // is preconfigured with the BUTTON_CLICKED definition.
    if(iMessage == BUTTON_CLICKED)
        shellexecute("Explorer.exe", "", "", 1);
}