FutureBasic Logo

<<    Index    >> FutureBasic 5

dialog   function



Syntax:
evnt%|& = dialog(0)
id%|& = dialog(evnt)


Description:
The dialog function returns information about the next event (if any) in FutureBasic's internal dialog queue. An FutureBasic dialog event consists of two parts: an "event type" number, which is returned when you call dialog(0), and "event id" number, which is returned by dialog(evnt) (where evnt is the event type number which was returned by dialog(0)). The "event type" identifies what kind of event occurred, and the "event id" provides some secondary information about it.
In the Appearance runtime, dialog functions return long integers instead of shorts.
Note that the name "dialog function" is a bit of a misnomer. It has nothing to do with dialog boxes or dialog controls. FutureBasic dialog events consist of a wide range of events, mostly related to the user's interaction with the currently active window.
Normally, you will call dialog(0) and dialog(evnt) from within a dialog-event handling function that your program has designated via the on dialog statement. Your dialog-event handling function should then respond to the event as appropriate.
To make sure that events are properly posted to the dialog queue, your program should call HandleEvents periodically. Among other things, HandleEvents checks the system event queue; translates any applicable system events into FutureBasic dialog events and posts them into the dialog queue; and calls your dialog-event handling function (once per dialog event). HandleEvents will also call your dialog-event handling function if your program has posted an event of type _userDialog (see the dialog statement).
The following pages list the various types of events returned by the dialog function. In these tables, "Event Type" refers to the number returned by dialog(0), and "ID" refers to the number returned by dialog(evnt).

Window Events
Event Type
Description
ID
_wndclick (3)
User clicked in the content area of an inactive window. See notes below.
Window ID of the clicked window
_wndClose (4)
User clicked the go away box of an active window. See notes below.
Window ID of the clicked window.
_wndRefresh (5)
A window has been resized, or made visible, or a previously obscured part of the window has been uncovered.
Window ID of the window needing a refresh.
_wndDocWillMove (9)
User clicked in the title bar of a window and is about to drag it.
ID of a _preview event
_wndActivate (18)
A previously inactive window has been made active, or a previously active window has been made inactive (The active window is the frontmost window and is usually highlighted differently from inactive windows.) See notes below.
If ID is positive, the window with that ID number has been made active. If ID is negative, the window whose ID number is abs(ID) has been made inactive.
_wndZoomIn (8) User clicked in the zoom box of an active window which is currently in the zoomed out state. See notes below. Window ID of the clicked window.
_wndZoomOut (9) User clicked in the zoom box of an active window which is currently in the zoomed in state. See notes below. Window ID of the clicked window.
_wndResized (30) This is an updated version of the older preview event and tells your program that a window was resized. (Appearance Manager only) Window ID of the resized window.
_inToolBarButton (13) User clicked in the toolbar attached to a window. (Carbon only) Window ID of the window owning the toolbar.


About _wndClick and _wndActivate events.
When the user clicks on the content region of an inactive window, FutureBasic posts a _wndClick event, and activates the window automatically when your dialog handler returns to the event loop.
When the user clicks on the structure region of an inactive window, FutureBasic posts a _wndActivate event, and activates the window automatically when your dialog handler returns to the event loop.
When you execute a window statement for an inactive window, FutureBasic posts a _wndActivate event, and activates the window immediately.
A _wndActivate event can also be generated in response to other actions: for example, when the active window closes and forces another window to become active; or when your application is brought from the background to the foreground.
_wndActivate events often occur in pairs: one with a positive "ID" value (an inactive window has become active), and one with a negative "ID" value (the previously active window has become inactive).
Note: Whenever FutureBasic activates a window (for any reason), the newly-active window also becomes the output window (i.e., all new drawing and text commands are sent to that window). If you want to make sure that your program's output doesn't inadvertently get re-directed to the newly activated window, then your program should watch for _wndActivate events, and respond by setting the output window (via the window output statement, or the SETPORT or SETGWORLD Toolbox procedures) as appropriate.
Note: Window activation, _wndActivate events and _wndClick events occur somewhat differently if one or more window has its _keepInBack attribute set. See the window statement for more information.

About _wndClose, _wndZoomIn and _wndZoomOut events
When the user clicks on the active window's "close box," FutureBasic generates a _wndClose event, but does not automatically close the window (your program should execute a window close statement in response to the _wndClose event, if you want the window to close).
When the user clicks on the active window's "zoom box," FutureBasic generates a _wndZoomIn or _wndZoomOut event, and automatically resizes the window the next time your program calls HandleEvents.

Button/Scrollbar Event
Event Type
Description
ID
_btnClick (1)
User clicked a button or moved a scrollbar thumb.
Button ID number or scrollbar ID number.
NOTE: If the toolbar button is clicked in an Appearance Manager window, the button ID returned is toolBarBtn (-1)
New in FB 5.7.104: During a dialog _btnClick event, the button's window number can now be retrieved with dialog(-1)


Contextual Menu Events
Event Type
Description
ID
_cntxtMenuClick (24)
The user has clicked in a window with the control key modifier pressed. See the menu statement for additional information.
The window number.


Key Press Events
Note: This event is not reported if there is an active edit field in the current output window or if you are running under the Appearance Compliant runtime. To capture keypress events in the active edit field, use the tekey$ function. To make all edit fields in the current window inactive, use the EDITFIELD0 statement.
Event Type
Description
ID
_evCmdKey (24)
User pressed a command-key combination which does not match any active menu command key equivalent
ASCII value of the key that was pressed.
_evKey (16) User pressed a key (or key combination) which can be mapped to an ASCII character. ASCII value of the key (or key combination) that was pressed.


Cursor (Mouse Pointer) Events
Note: These events might occasionally be missed if the rate at which the cursor moves is too fast compared to the rate at which HandleEvents is called.
Note: These events are reported for the output window and for floating windows.
Event Type
Description
ID
_cursOverBtn (21)
The cursor is over a button. This is the same as the old _cursOver, but is valid only for buttons.
Number of button entered
_cursOverNothing (29) The cursor moved off of a control. Always zero


User Dialog Events
Event Type
Description
ID
_userDialog (23)
The program posted a custom event using the dialog = expr% statement.
The value of expr% that was specified when the event was posted.

Disk Insert Events (Not Supported)
Event Type
Description
ID
_evDiskInsert (17)
A floppy disk, tape, or other removable storage medium was inserted into a drive. (Note: some removable-media devices use their own reporting mechanism and won't generate a disk-insert event.
The drive ID number. (Does not function in Appearance Runtime)


Edit Field Events (Not Supported)
Note: these events apply only to editable (non-static) edit fields, and only in the current output window.
Event Type
Description
ID
_efClick (2)
User clicked in an inactive edit field, and FutureBasic activated the field.
Edit field ID of the clicked field.
_efReturn (6) User pressed return while a "noCR" type edit field was active. Edit field ID of the active field.
_efTab (7) User pressed the tab key while an edit field was active Edit field ID of the active field.
_efShiftTab (10) User pressed shift-tab while an edit field was active Edit field ID of the active field.
_efClear (11) User pressed the clear key while an edit field was active. Edit field ID of the active field.
_efLeftArrow (12) User pressed the left arrow key when the insertion point in the active edit field was already to the left of the first text character. Edit field ID of the active field.
_efRightArrow (13) User pressed the right arrow key when the insertion point in the active edit field was already to the right of the last text character. Edit field ID of the active field.
_efUpArrow (14) User pressed the up arrow key when the insertion point in the active edit field was already in the top line of text. Edit field ID of the active field.
_efDownArrow (15) User pressed the down arrow key when the insertion point in the active edit field was already in the bottom line of text. Edit field ID of the active field.
_efSelected (26) A user click or tab key press has changed the focus. (Appearance Manager only) Edit field ID of the activated field.


Picture Field Events (Not Supported)
Note: This event is only reported for picture fields whose type parameter equals _framed, _framedNoCR, _noFramed, or _noFramedNoCR.
Event Type
Description
ID
_efClick (2)
User clicked in a picture field.
Picture field ID of the clicked field.
_pfClick (25) User clicked in a picture field. (Appearance Manager only) Picture field ID of the clicked field.


Cursor (Mouse Pointer) Events (Not Supported)
Note: These events might occasionally be missed if the rate at which the cursor moves is too fast compared to the rate at which HandleEvents is called.
Note: These events are reported for the output window and for floating windows.
Event Type
Description
ID
_cursOverEF (27) The cursor is over an edit field in the active document window or in any floating window. Number of edit field entered
_cursOverPF (28) The cursor is over a picture field in the active document window or in any floating window. Number of picture field entered


Multi-process Events (Not Supported)
Event Type
Description
ID
_mfEvent (19)
An event associated with process-switching has occurred. In System 6, these events were associated with the MultiFinder program; hence the letters "MF".
ASCII value of the key (or key combination) that was pressed.ID is set to one of the following constants:
_mfResume (1) _mfSuspend (2) _mfClipboard (3) _msMouse (4)
See the notes below for more information.
_FBQuitEvent (31) Your application has received a message to quit. This may be from an Apple Core event or by the user selecting Quit from the application menu. zero


ID values for "_MFEvent" events
_mfResume : Your program has been brought to the front, and the clipboard contents were not altered while your program was in the background.
_mfSuspend : Your program is being moved to the background or hidden.
_mfClipboard : Your program has been brought to the front, and the clipboard contents were altered while your program was in the background. It should be noted that this event cannot be reported under Carbon. Apple suggests the use of the Toolbox function GetCurrentScrap for the purpose.
_mfMouse : User moved the mouse cursor to an area outside of a special "mouse region" specified by your program. Before this event can be reported, your program must create a region (in global coordinates), and then execute the following statements:
poke long event-8, tickFrequency%
poke long event-4, regionHandle&

where regionHandle& is a handle to the global mouse region, and tickFrequency% indicates the desired delay in ticks between successive postings of system events (usually you should set this to 1). The _mfMouse event is posted repeatedly for as long as the cursor remains outside of the region. You can later specify a different mouse region by poke'ing a different region's handle into event-4, or you can disable the event as follows:
poke long event-4, _nil
For as long as a region remains the "active" mouse region, you must not dispose of that region's handle.

Preview Events (Partially Supported)
Event Type
Description
ID
_preview (22)
Usually indicates that some other related event is about to be posted.
"ID" is set to one of the following constants:
_premenuclick (1) _prewndgrow (2) _wndmoved (3) _wndsized (4) _efchanged (5) _preefclick (6) _prewndzoomin (7) _prewndzoomout (8) _wnddocwillmove (9)
See notes below for more information.


ID values for "_preview" events
_preMenuClick : User clicked on a menu in the menubar. This event is reported before the menu actually opens.
_preWndGrow : User clicked on the active window's size box. This event is reported as soon as the mouse is pressed down.
_wndMoved : User clicked on the active window's title bar (or its frame, in Mac OS 8.x - Mac OS 9.x). This event is reported after the mouse button is released.
_wndSized : User resized the window. This event is reported after the size change. See _wndResized for a new dialog event invoked by the Appearance Manager runtime.
_efChanged : User selected the "Clear", "Cut" or "Paste" option from the Edit menu. This applies only when the Edit menu was created by the edit menu statement. The event is reported before the text actually changes.
_preEfClick : User clicked in a non-static edit field in the active window. This event is reported whether the clicked field is the active field or not. The event is returned after the mouse button is released, but before the _efClick event (if any) is reported.
_preWndZoomIn : User clicked in the active window's Zoom box (while the window was in the "zoomed-out" state). This event is reported after the mouse button is released, but before the window actually changes size (and before the _wndZoomIn event is reported).
_preWndZoomOut : User clicked in the active window's Zoom box (while the window was the "zoomed-in" state). This event is reported after the mouse button is released, but before the window actually changes size (and before the _wndZoomOut event is reported).

Supported Preview Events in FB5 are:
_preMenuClick : User clicked on a menu in the menubar. This event is reported before the menu actually opens.
_preWndGrow : User clicked on the active window's size box. This event is reported as soon as the mouse is pressed down.
_wndMoved : User clicked on the active window's title bar (or its frame, in Mac OS 8.x - Mac OS 9.x). This event is reported after the mouse button is released.
_wndDocWillMove : User started a window drag as reported by the kEventWindowDragStarted Carbon event.

Note:
You can use the event% function and the event& function to retrieve more details about an event returned by the dialog function.

See Also:
HandleEvents; on dialog fn