![]() |
<< Index >> |
FutureBasic 5 |
dialog | function | |
|
evnt%|& = dialog(0)
id%|& = dialog(evnt)
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.dialog
functions return long integers instead of shorts.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.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.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).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)
.
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. |
_wndClick
event, and activates the window automatically when your dialog handler returns to the event loop._wndActivate
event, and activates the window automatically when your dialog handler returns to the event loop.window
statement for an inactive window, FutureBasic posts a _wndActivate
event, and activates the window immediately._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)._wndActivate
events, and respond by setting the output window (via the window output
statement, or the SETPORT
or SETGWORLD
Toolbox procedures) as appropriate._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._wndClose
, _wndZoomIn
and _wndZoomOut
events_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)._wndZoomIn
or _wndZoomOut
event, and automatically resizes the window the next time your program calls HandleEvents
.
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) |
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. |
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. |
HandleEvents
is called.
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 |
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. |
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) |
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. |
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. |
HandleEvents
is called.
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 |
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 |
_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&
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
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. |
_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)._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.event%
function and the event&
function to retrieve more details about an event returned by the dialog
function.