FutureBasic Logo

<<    Index    >> FutureBasic 5

dialog( CocoaUI )   function



Syntax:

dim as long event, id, wnd
evnt = dialog(0)
id = dialog(evnt)
wnd = dialog(-1)


Description:

The dialog 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.

dialog syntax and behavior is primarily aimed at CocoaUI builds but most of the syntax applies to Carbon builds too. Usage Example five employing CFTypeRef object is CocoaUI only.

Retrieving events( such as a button click ) and their associated user interface widget( i.e. which button clicked ) with dialog is typically a two-step process:

  1. dialog(0) returns an "event type". The "event type" identifies what kind of event occurred such as a button click.
  2. dialog(evnt) ("evnt" is the output delivered by #1 above ) returns an "Event id" which provides secondary event information. For a button click, secondary information could identify which button was clicked.

As noted above, dialog(0) and dialog(evnt) are called from within a dialog-event handling function designated in the application's code via the on dialog statement. The application's dialog-event handling function should then respond to the event as appropriate.

dialog(-1) retrieves the window number associated with the event. Note: Usage Examples four and five ( below ) provide the window number directly from the passed in parameters without a need for dialog(-1).

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

The name "Dialog function" and its deliverable(s) is not related specifically to dialogs. The name has been retained to minimize user code changes and for historical reasons.

Event Types and their associated constants

Are shown in the CocoaUI documentation:

  1. On the 'Dialog' page
  2. On the pages for specific user interface ( UI ) widgets such as TableView, Cocoa Window, ComboBox etc.


Usage Examples

Shows both the dialog function and a user event-handling function. The examples assume a user event-handling function has been designated with the name "DoDialog" via a "on dialog fn DoDialog".

  1. local fn DoDialog
  2. dim as long evnt, id, wnd
    evnt = dialog(0)
    id = dialog(evnt)
    wnd = dialog(-1)
    ...

    end fn

  3. local fn DoDialog( evnt as long )
  4. dim as long id
    id = dialog(evnt)
    ...

    end fn

  5. local fn DoDialog( evnt as long, id as long )
  6. ...

    end fn

  7. local fn DoDialog( evnt as long, id as long, wnd as long )
  8. select ( evnt )
      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

  9. local fn DoDialog( evnt as long, id as long, wnd as long, obj as CFTypeRef ) // CocoaUI Only
  10. select ( evnt )
      case _viewPerformDragOperation
      // obj contains a file URL
      //...
    end select

    end fn


See Also:

HandleEvents; on dialog fn