Execution Functions


Typedefs

typedef void(* fltk::FileHandler )(int fd, void *)
typedef void(* fltk::TimeoutHandler )(void *)

Enumerations

enum  { READ, WRITE, EXCEPT }

Functions

void fltk::add_check (TimeoutHandler, void *=0)
void add_fd (int fd, FileHandler, void *=0)
void add_fd (int fd, int when, FileHandler, void *=0)
void fltk::add_idle (TimeoutHandler, void *=0)
void fltk::add_timeout (float t, TimeoutHandler, void *v=0)
int fltk::check ()
int fltk::damage ()
void damage (int d)
void fltk::flush ()
bool fltk::has_check (TimeoutHandler, void *=0)
bool fltk::has_idle (TimeoutHandler, void *=0)
bool fltk::has_timeout (TimeoutHandler, void *=0)
int fltk::ready ()
void fltk::redraw ()
void fltk::remove_check (TimeoutHandler, void *=0)
void remove_fd (int, int when=-1)
void fltk::remove_idle (TimeoutHandler, void *=0)
void fltk::remove_timeout (TimeoutHandler, void *=0)
void fltk::repeat_timeout (float t, TimeoutHandler, void *=0)
int fltk::run ()
void set_idle (void(*cb)())
int fltk::wait (float time)
int fltk::wait ()

Variables

int damage_
void(* fltk::error )(const char *,...)
void(* fltk::fatal )(const char *,...)
void(* idle )()
void(* fltk::warning )(const char *,...)

Typedef Documentation

typedef void(* TimeoutHandler)(void *)
 

Type of function passed to add_timeout(), add_check(), and add_idle()

typedef void(* FileHandler)(int fd, void *)
 

Type of function passed to add_fd()

Function Documentation

int wait (   ) 
 

Same as fltk::wait(infinity). Call this repeatedly to "run" your program. You can also check what happened each time after this returns, which is quite useful for managing program state.

int wait (  float  time_to_wait  ) 
 

Waits until "something happens", or the given time interval passes. It can return much sooner than the time if something happens.

What this really does is call all idle callbacks, all elapsed timeouts, call fltk::flush() to get the screen to update, and then wait some time (zero if there are idle callbacks, the shortest of all pending timeouts, or the given time), for any events from the user or any fltk::add_fd() callbacks. It then handles the events and calls the callbacks and then returns.

The return value is zero if nothing happened before the passed time_to_wait expired. It is non-zero if any events or timeouts came in.

int check (   ) 
 

Same as fltk::wait(0). Calling this during a big calculation will keep the screen up to date and the interface responsive: 

while (!calculation_done()) {
  calculate();
  fltk::check();
  if (user_hit_abort_button()) break;
}

int ready (   ) 
 

Test to see if any events or callbacks are pending. This will return true if fltk::check() would do anything other than update the screen. Since this will not draw anything or call any code, it is safe to call this if your program is in an inconsistent state. This is also useful if your calculation is updating widgets but you do not want or need the overhead of the screen updating every time you check for events. 

while (!calculation_done()) {
  calculate();
  if (fltk::ready()) {
    do_expensive_cleanup();
    fltk::check();
    if (user_hit_abort_button()) break;
  }
}

int run (   ) 
 

Calls fltk::wait() as long as any windows are not closed. When all the windows are hidden or destroyed (checked by seeing if Window::first() is null) this will return with zero. A program can also exit by having a callback call exit() or abort().

Most fltk programs will end main() with return fltk::run();.

void flush (   ) 
 

Get the display up to date. This is done by calling layout() on all Window objects with layout_damage() and then calling draw() on all Window objects with damage(). (actually it calls Window::flush() and that calls draw(), but normally you can ignore this). This will also flush the X i/o buffer, update the cursor shape, update Windows window sizes, and other operations to get the display up to date.

wait() calls this before it waits for events.

void redraw (   ) 
 

Redraws all widgets. This is a good idea if you have made global changes to the styles.

int damage (   )  [inline]
 

True if any Widget::redraw() calls have been done since the last fltk::flush(). This indicates that flush() will do something. Currently the meaning of any bits are undefined.

Window flush() routines can set this to indicate that flush() should be called again after waiting for more events. This is useful in some instances such as X windows that are waiting for a mapping event before being drawn.

void add_timeout (  float  time,
TimeoutHandler  cb,
void *  arg = 0
) 
 

Add a one-shot timeout callback. The function will be called by fltk::wait() at t seconds after this function is called. The optional void* argument is passed to the callback.

void repeat_timeout (  float  time,
TimeoutHandler  cb,
void *  arg = 0
) 
 

Inside a timeout callback you can call this to add another timeout. Rather than the time being measured from "now", it is measured from when the system call elapsed that caused this timeout to be called. This will result in far more accurate spacing of the timeout callbacks, it also has slightly less system call overhead. (It will also use all your machine time if your timeout code and fltk's overhead take more than t seconds, as the real timeout will be reduced to zero).

Outside a timeout callback this acts like add_timeout().

This code will print "TICK" each second on stdout, with a fair degree of accuracy: 

void callback(void*) {
  printf("TICK\n");
  fltk::repeat_timeout(1.0,callback);
}

main() {
  fltk::add_timeout(1.0,callback);
  for (;;) fltk::wait();
}

bool has_timeout (  TimeoutHandler  cb,
void *  arg = 0
) 
 

Returns true if the timeout exists and has not been called yet.

void remove_timeout (  TimeoutHandler  cb,
void *  arg = 0
) 
 

Removes all pending timeout callbacks that match the function and arg. Does nothing if there are no matching ones that have not been called yet.

void add_check (  TimeoutHandler  cb,
void *  arg = 0
) 
 

Fltk will call this callback just before it flushes the display and waits for events. This is different than add_idle() because it is only called once, then fltk calls the system and tells it not to return until an event happens. If several checks have been added fltk calls them all, the most recently added one first.

This can be used by code that wants to monitor the application's state, such as to keep a display up to date. The advantage of using a check callback is that it is called only when no events are pending. If events are coming in quickly, whole blocks of them will be processed before this is called once. This can save significant time and avoid the application falling behind the events: 

bool state_changed; // anything that changes the display turns this on

void check(void*) {
  if (!state_changed) return;
  state_changed = false;
  do_expensive_calculation();
  widget->redraw();
}

main() {
  fltk::add_check(1.0,check);
  return fltk::run();
}

bool has_check (  TimeoutHandler  cb,
void *  arg = 0
) 
 

Return true if add_check() has been done with this cb and arg, and remove_check() has not been done.

void remove_check (  TimeoutHandler  cb,
void *  arg = 0
) 
 

Remove all matching check callback, if any exists. You can call this from inside the check callback if you want.

void add_idle (  TimeoutHandler  cb,
void *  data = 0
) 
 

Adds a callback function that is called every time by fltk::wait() and also makes it act as though the timeout is zero (this makes fltk::wait() return immediately, so if it is in a loop it is called repeatedly, and thus the idle fucntion is called repeatedly). The idle function can be used to get background processing done.

You can have multiple idle callbacks. They are called one after another in a round-robin fashion, checking for events between each.

fltk::wait() and fltk::check() call idle callbacks, but fltk::ready() does not.

The idle callback can call any FLTK functions, including fltk::wait(), fltk::check(), and fltk::ready(). In this case fltk will not recursively call the idle callback.

bool has_idle (  TimeoutHandler  cb,
void *  data = 0
) 
 

Returns true if the specified idle callback is currently installed.

void remove_idle (  TimeoutHandler  cb,
void *  data = 0
) 
 

Removes the specified idle callback, if it is installed.

Variable Documentation

void(* warning)(const char *format,...)
 

fltk will call this when it wants to report a recoverable problem. The display may be messed up but the user can probably keep working. (all X protocol errors call this). The default version on Unix prints a message to stderr, on Windows it pops up a MessageBox.

void(* error)(const char *format,...)
 

fltk will call this when it wants to report a recoverable problem. but in this case the display is so messed up it is unlikely the user can continue. Very little calls this now. The default version on Unix prints a message to stderr, on Windows it pops up a MessageBox, and then both versions call exit(1).

You may be able to use longjmp or an exception to get back to your own code.

void(* fatal)(const char *format,...)
 

fltk will call this when it wants to report a problem that it cannot recover from. You must not make any fltk calls again. The default version is the same function as error().

Sun May 8 21:48:57 2005. FLTK ©2004 Bill Spitzak and others. See Main Page for details.