Class Fox::FXApp
In: rdoc-sources/FXApp.rb
lib/fox12/chore.rb
lib/fox12/input.rb
lib/fox12/iterators.rb
lib/fox12/signal.rb
lib/fox12/timeout.rb
Parent: FXObject

Application Object

Events

The FXApp object itself doesn’t have a designated message target like other FOX objects, but it can send messages to objects for a few special events.

Timers
When a timeout event is registered with the application using the addTimeout method, a SEL_TIMEOUT message is sent to the message target.
Chores
When a chore event is registered with the application using the addChore method, a SEL_CHORE message is sent to the message target.
Inputs
When an input event is registered with the application using the addInput method, a SEL_IO_READ, SEL_IO_WRITE or SEL_IO_EXCEPT message may be sent to the message target.
Signals
When a signal handler object is registered with the application using the addSignal method, a SEL_SIGNAL message may be sent to the message target.

File input modes for addInput

INPUT_NONE:inactive
INPUT_READ:read input fd
INPUT_WRITE:write input fd
INPUT_EXCEPT:except input fd

All ways of being modal

MODAL_FOR_NONE:Non modal event loop (dispatch normally)
MODAL_FOR_WINDOW:Modal dialog (beep if outside of modal dialog)
MODAL_FOR_POPUP:Modal for popup (always dispatch to popup)

Default cursors provided by the application

These constants symbolically represent the different cursor shapes used in FOX applications, and can be used as the which arguments for getDefaultCursor and setDefaultCursor.

DEF_ARROW_CURSOR:Arrow cursor
DEF_RARROW_CURSOR:Reverse arrow cursor
DEF_TEXT_CURSOR:Text cursor
DEF_HSPLIT_CURSOR:Horizontal split cursor
DEF_VSPLIT_CURSOR:Vertical split cursor
DEF_XSPLIT_CURSOR:Cross split cursor
DEF_SWATCH_CURSOR:Color swatch drag cursor
DEF_MOVE_CURSOR:Move cursor
DEF_DRAGH_CURSOR:Resize horizontal edge
DEF_DRAGV_CURSOR:Resize vertical edge
DEF_DRAGTL_CURSOR:Resize upper-leftcorner
DEF_DRAGBR_CURSOR:Resize bottom-right corner
DEF_DRAGTR_CURSOR:Resize upper-right corner
DEF_DRAGBL_CURSOR:Resize bottom-left corner
DEF_DNDSTOP_CURSOR:Drag and drop stop
DEF_DNDCOPY_CURSOR:Drag and drop copy
DEF_DNDMOVE_CURSOR:Drag and drop move
DEF_DNDLINK_CURSOR:Drag and drop link
DEF_CROSSHAIR_CURSOR:Cross hair cursor
DEF_CORNERNE_CURSOR:North-east cursor
DEF_CORNERNW_CURSOR:North-west cursor
DEF_CORNERSE_CURSOR:South-east cursor
DEF_CORNERSW_CURSOR:South-west cursor
DEF_HELP_CURSOR:Help arrow cursor
DEF_HAND_CURSOR:Hand cursor
DEF_ROTATE_CURSOR:Rotate cursor

Messages identifiers

ID_QUIT:Terminate the application normally
ID_DUMP:Dump the current widget tree

Methods

addChore   addChore   addChoreOrig   addInput   addSignal   addSignal   addSignalOrig   addTimeout   addTimeout   addTimeoutOrig   beep   beginWaitCursor   closeDisplay   copyright   create   destroy   detach   disableThreads   dumpWidgets   enableThreads   endWaitCursor   exit   flush   forceRefresh   getDefaultCursor   getDragTypeName   hasChore?   hasTimeout?   init   initialized?   instance   modal?   new   openDisplay   peekEvent   refresh   registerDragType   remainingTimeout   remainingTimeout   removeChore   removeChore   removeInput   removeSignal   removeTimeout   removeTimeout   repaint   run   runModal   runModalFor   runModalWhileEvents   runModalWhileShown   runOneEvent   runPopup   runUntil   runWhileEvents   setDefaultCursor   stop   stopModal   stopModal   threadsEnabled?  

External Aliases

addInput -> addInputOrig
beginWaitCursor -> beginWaitCursor0

Attributes

animSpeed  [RW]  Animation speed, in milliseconds [Integer]
appName  [R]  Application name [String]
argc  [R]  Argument count [Integer]
argv  [R]  Argument vector [Array]
backColor  [RW]  Default background color [FXColor]
baseColor  [RW]  Background color of GUI controls [FXColor]
blinkSpeed  [RW]  Blink speed, in milliseconds [Integer]
borderColor  [RW]  Border color [FXColor]
clickSpeed  [RW]  Click speed, in milliseconds [Integer]
cursorWindow  [R]  The window under the cursor, if any [FXWindow]
defaultVisual  [RW]  Default visual [FXVisual]
display  [R]  Display [Integer]
dragDelta  [RW]  Drag delta, in pixels [Integer]
focusWindow  [R]  The shell window at the top of the focus chain, if any [FXWindow]
foreColor  [RW]  Default foreground color [FXColor]
hiliteColor  [RW]  Hilite color of GUI controls [FXColor]
mainWindow  [R]  The main window, if any [FXWindow]
menuPause  [RW]  Menu pause, in milliseconds [Integer]
modalModality  [R]  Mode of current modal loop [Integer]
modalWindow  [R]  The window of the current modal loop [FXWindow]
monoVisual  [R]  Monochrome visual [FXVisual]
normalFont  [RW]  Default font [FXFont]
reg  [R]  Registry for this application [FXRegistry]
root  [R]  Root window [FXRootWindow]
scrollDelay  [RW]  Scroll delay time, in milliseconds [Integer]
scrollSpeed  [RW]  Scroll speed, in milliseconds [Integer]
selbackColor  [RW]  Default background color for selected objects [FXColor]
selforeColor  [RW]  Default foreground color for selected objects [FXColor]
shadowColor  [RW]  Shadow color of GUI controls [FXColor]
sleepTime  [RW]  Amount of time (in milliseconds) to yield to Ruby’s thread scheduler [Integer]
tipbackColor  [RW]  Default background color for tooltips [FXColor]
tipforeColor  [RW]  Default foreground color for tooltips [FXColor]
tooltipPause  [RW]  Tooltip pause, in milliseconds [Integer]
tooltipTime  [RW]  Tooltip time, in milliseconds [Integer]
typingSpeed  [RW]  Typing speed used for the FXIconList, FXList and FXTreeList widgets’ lookup features, in milliseconds. Default value is 1000 milliseconds.
vendorName  [R]  Vendor name [String]
waitCursor  [RW]  Wait cursor [FXCursor]
wheelLines  [RW]  Number of wheel lines [Integer]

Public Class methods

copyright()

Copyright notice for library

instance()

Return application instance

new(appName="Application", vendorName="FoxDefault") {|theApp| ...}

Construct application object; the appName and vendorName strings are used as keys into the registry database for this application’s settings

Public Instance methods

addChore(tgt, sel, ptr=nil)

Add a idle processing message to be sent to target object when the system becomes idle, i.e. there are no events to be processed. The void* ptr is user data which will be passed into the void* ptr of the message handler. If a chore with the same target and message already exists, it will be rescheduled.

addChore(*args, &block)

Add a idle processing message to be sent to a target object when the system becomes idle, i.e. when there are no more events to be processed. There are several forms for addChore; the original form (from FOX) takes two arguments, a target object and a message identifier: 

  anApp.addChore(anObject, aMessageId)

A second form takes a Method instance as its single argument: 

  anApp.addChore(aMethod)

For this form, the method should have the standard argument list for a FOX message handler. That is, the method should take three arguments, for the message sender (an FXObject), the message selector, and the message data (if any).

The last form takes a block: 

  anApp.addChore() { |sender, sel, data|
    ... handle the chore ...
  }

All of these return a reference to an opaque FXChore instance that can be passed to removeChore if it is necessary to remove the chore before it fires.

addChoreOrig(tgt, sel, ptr=nil)

Alias for addChore

addInput(fd, mode, *args, &block)

Add a file descriptor fileDesc to be watched for activity as determined by mode, where mode is a bitwise OR (INPUT_READ, INPUT_WRITE, INPUT_EXCEPT). A message of type SEL_IO_READ, SEL_IO_WRITE, or SEL_IO_EXCEPT will be sent to the target when the specified activity is detected on the file descriptor.

There are several forms for addInput; the original form (from FOX) takes four arguments: 

  anApp.addInput(fileDesc, mode, anObject, aMessageId)

A second form takes three arguments: 

  anApp.addInput(fileDesc, mode, aMethod)

For this form, aMethod should have the standard argument list for a FOX message handler. That is, the method should take three arguments, for the message sender (an FXObject), the message selector, and the message data (if any).

The last form of addInput takes a block: 

  anApp.addInput(fileDesc, mode) { |sender, sel, data|
    ... handle the I/O event ...
  }
addSignal(sig, *args, &block)

Register a signal processing message to be sent to target object when the specified signal is raised.

There are several forms for addSignal; the original form (from FOX) takes (up to) five arguments: 

  anApp.addSignal(aSignal, anObject, aMessageId, sendImmediately=false, flags=0)

Here, aSignal is a string indicating the operating system signal of interest (such as "SIGINT"). The second and third arguments are the target object and message identifier for the message to be sent when this signal is raised. If sendImmediately is true, the message will be sent to the target right away; this should be used with extreme care as the application is interrupted at an unknown point it its execution. The flags are to be set as per POSIX definitions.

A second form of addSignal takes a Method instance as its second argument: 

  anApp.addSignal(aSignal, aMethod, sendImmediately=false, flags=0)

For this form, the method should have the standard argument list for a FOX message handler. That is, the method should take three arguments, for the message sender (an FXObject), the message selector, and the message data (if any).

The last form of addSignal takes a block: 

  anApp.addSignal(aSignal, sendImmediately=false, flags=0) { |sender, sel, data|
    ... handle the signal ...
  }
addSignal(sig, tgt, sel, immediate=false, flags=0)

Add signal processing message to be sent to target object when the signal sig is raised; flags are to be set as per POSIX definitions. When immediate is true, the message will be sent to the target right away; this should be used with extreme care as the application is interrupted at an unknown point in its execution.

addSignalOrig(sig, tgt, sel, immediate=false, flags=0)

Alias for addSignal

addTimeout(ms, tgt, sel, ptr=nil)

Add timeout message to be sent to target object in ms milliseconds; the timer fires only once after the interval expires. The last argument is optional user data which will be passed along as the ptr argument of the message handler. If a timer with the same target and message already exists, it will be rescheduled.

Parameters:

ms:timeout interval, in milliseconds [Integer]
tgt:target object for the timeout [FXObject]
sel:message identifier for the timeout [Integer]
addTimeout(ms, *args, &block)

Register a timeout message to be sent to a target object; the timer fires only once after the interval expires.

There are several forms for addTimeout; the original form (from FOX) takes three arguments: 

  anApp.addTimeout(aDelay, anObject, aMessageId)

Here, aDelay is the time interval (in milliseconds) to wait before firing this timeout. The second and third arguments are the target object and message identifier for the message to be sent when this timeout fires.

A second form of addTimeout takes a Method instance as its single argument: 

  anApp.addTimeout(aDelay, aMethod)

For this form, the method should have the standard argument list for a FOX message handler. That is, the method should take three arguments, for the message sender (an FXObject), the message selector, and the message data (if any).

The last form of addTimeout takes a block: 

  anApp.addTimeout(aDelay) { |sender, sel, data|
    ... handle the chore ...
  }

All of these return a reference to an opaque FXTimer instance that can be passed to removeTimeout if it is necessary to remove the timeout before it fires.

addTimeoutOrig(ms, tgt, sel, ptr=nil)

Alias for addTimeout

beginWaitCursor() {|| ...}

Changes the default application cursor to an hourglass shape, to provide a visual cue to the user that it’s time to wait. To revert the default application cursor to its normal shape, call the endWaitCursor method. For example, 

   getApp().beginWaitCursor()
     ... time-consuming operation ...
   getApp().endWaitCursor()

Invocations of beginWaitCursor may be nested, and if so, the call to endWaitCursor is matched with the most recent call to beginWaitCursor.

If an optional code block is provided, endWaitCursor is automatically called after the block terminates, e.g. 

   getApp().beginWaitCursor() {
             ... time-consuming operation ...
     ... endWaitCursor() is called automatically ...
   }
closeDisplay()

Close connection to the display

create()

Create application’s windows

destroy()

Destroy application’s windows

detach()

Detach application’s windows

disableThreads()

Disable support for multithreaded applications

dumpWidgets()

Dump widget information

enableThreads()

Enable support for multithreaded applications

endWaitCursor()

End the most deeply nested wait-cursor block. See also beginWaitCursor.

exit(code=0)

Exit application. Closes the display and writes the registry.

flush(sync=false)

Flush pending repaints

forceRefresh()

Force GUI refresh

getDefaultCursor(which)

Return a reference to one of the default application cursors (an FXCursor instance), where which is one of the default cursor identifiers listed above, e.g. 

  rotateCursor = app.getDefaultCursor(DEF_ROTATE_CURSOR)

See also setDefaultCursor.

getDragTypeName(dragType)

Return the name of a previously registered drag type, e.g. 

  dragTypeName = app.getDragTypeName(yamlDragType)

See also registerDragType.

hasChore?(tgt, sel)

Return true if given chore has been set, otherwise return false.

Parameters:

tgt:target object for the chore [FXObject]
sel:message identifier for the chore [Integer]
hasTimeout?(tgt, sel)

Return true if given timeout has been set, otherwise return false.

Parameters:

tgt:target object for the timeout [FXObject]
sel:message identifier for the timeout [Integer]
init(argv, connect=true)

Initialize application. Parses and removes common command line arguments, reads the registry. Finally, if connect is true, it opens the display.

initialized?()

Return true if the application has been initialized.

modal?(window)

Returns true if the window is modal

openDisplay(dpyname=nil)

Open connection to display; this is called by init.

peekEvent()

Peek to determine if there’s an event

refresh()

Schedule a refresh

registerDragType(name)

Register a drag type with the given name and return the drag drag type. If this drag type has already been registered, this method will return the previously returned drag type. For example, 

  yamlDragType = app.registerDragType("application/x-yaml")

See also getDragTypeName.

remainingTimeout(timer)

Return the time remaining (in milliseconds) until the given timer fires. If the timer is past due, zero is returned. If there is no such timer, infinity (UINT_MAX) is returned.

Parameters:

timer:a reference to the timer originally returned by the call to addTimeout [FXTimer]
remainingTimeout(tgt, sel)

Return the time remaining (in milliseconds) until the given timer fires. If the timer is past due, zero is returned. If there is no such timer, infinity (UINT_MAX) is returned.

Parameters:

tgt:target object for the timeout [FXObject]
sel:message identifier for the timeout [Integer]
removeChore(chore)

Remove idle processing message identified by chore; returns nil.

removeChore(tgt, sel)

Remove idle processing message identified by tgt and sel; returns nil.

removeInput(fd, mode)

Remove input message and target object for the specified file descriptor and mode, which is a bitwise OR of (INPUT_READ, INPUT_WRITE, INPUT_EXCEPT).

removeSignal(sig)

Remove signal message for signal sig

removeTimeout(timer)

Remove timeout identified by timer; returns nil.

Parameters:

timer:timer record originally returned by addTimeout [FXTimer]
removeTimeout(tgt, sel)

Remove timeout identified by tgt and sel; returns nil.

Parameters:

tgt:target object for the timeout [FXObject]
sel:message identifier for the timeout [Integer]
repaint()

Paint all windows marked for repainting. On return all the applications windows have been painted.

run()

Run the main application event loop until stop is called, and return the exit code passed as argument to stop.

runModal()

Run modal event loop, blocking keyboard and mouse events to all windows until stopModal is called.

runModalFor(window)

Run a modal event loop for the given window, until stop or stopModal is called. Except for the modal window and its children, user input to all windows is blocked; if the modal window is nil all user input is blocked.

runModalWhileEvents(window=nil)

Run event loop while there are events are available in the queue. Returns 1 when all events in the queue have been handled, and 0 when the event loop was terminated due to stop or stopModal. Except for the modal window and its children, user input to all windows is blocked; if the modal window is nil, all user input is blocked.

runModalWhileShown(window)

Run modal while window is shown, or until stop or stopModal is called. Except for the modal window and its children, user input to all windows is blocked; if the modal window is nil all user input is blocked.

runOneEvent(blocking=true)

Perform one event dispatch; return true if event was dispatched.

runPopup(window)

Run popup menu while shown, until stop or stopModal is called. Also returns when entering previous cascading popup menu.

runUntil(condition)

Run an event loop till some flag becomes non-zero, and then return.

runWhileEvents()

Run event loop while events are available, non-modally. Return when no more events, timers, or chores are outstanding.

setDefaultCursor(which, cursor)

Replace one of the default application cursors with cursor; e.g 

  app.setDefaultCursor(DEF_ROTATE_CURSOR, myRotateCursor)

See also getDefaultCursor.

stop(value=0)

Terminate the outermost event loop, and all inner modal loops; All more deeper nested event loops will be terminated with code equal to 0, while the outermost event loop will return code equal to value.

stopModal(window, value=0)

Break out of the matching modal loop, returning code equal to value. All deeper nested event loops are terminated with code equal to 0.

stopModal(value=0)

Break out of the innermost modal loop, returning code equal to value.

threadsEnabled?()

Check to see if multithreaded applications are supported

[Validate]