FutureBasic Logo

 <<    Index    >> FutureBasic
on dialog   statement


Syntax
on dialog fn userFunction

Description
This statement designates a specific userFunction to handle events. It is called in response to a number of different kinds of user actions and internal events.

After an event occurs, FutureBasic's runtime will dispatch it to the designated routine as soon as possible.

The userFunction must refer to a function which was defined or prototyped at an earlier location in the source code.

HandleEvents must be called once to make sure events are properly posted to the dialog queue. Additional HandleEvents calls after first call are superfluous, unnecessary, unproductive and harmless. Please use only one HandleEvents in application code.

 
User function
The user function provides access to dynamic event information as it occurs in your application. FutureBasic's runtime sends event notifications to the event-handling function (established with the on dialog fn statement). Within the event-handling function the dialog function is used to identify and intercept those events. Events are typically related to the user's interaction with the currently active window and its controls such as buttons, but could also be non-user interface related such as completion notifications.

void local fn DoDialog( ev as long, tag as long, wnd as long, obj as CFTypeRef )

// ...

end fn

Parameters
Parameter
 Description
ev The event type. Event types are shown in the header for the specific user interface widgets such as textfield, window, combobox, etc.
tag Usually the tag number of the UI widget that triggered the event.
wnd The window tag value.
obj A CF/NS object. Which object type it represents varies based on context and each context could be a different object. For example, for the _openPanelDidEnd event, it is a CFURLRef.

 


Examples
These examples assume a user event-handling function has been designated with the name "DoDialog" via a "on dialog fn DoDialog".


  1. local fn DoDialog( ev as long )
    2. // ...
    end fn

  2. local fn DoDialog( ev as long, tag as long )
    3. // ...
    end fn

  3. local fn DoDialog( ev as long, tag as long, wnd as long )
    4. select ( ev )
    case _btnClick
    select ( wnd )
    case 1   // window id 1
    // do something with button click in window 1
    case 2   // window id 2
    // do something with button click in window 2
    end select
    end select
    end fn

  4. local fn DoDialog( ev as long, tag as long, wnd as long, obj as CFTypeRef )
    5. select ( ev )
    case _viewPerformDragOperation
    // obj contains a file URL
    // ...
    end select
    end fn

See also
dialog statement; HandleEvents