/ 
FLTK-0.532008
River stage zero No dependents
/ FLTK::run

NAME

FLTK::run - Basic activity functions for the Fast Light Toolkit

Description

Functions

add_check

FLTK::add_check( \&coderef, $args );

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:

my $state_changed;   # anything that changes the display turns this on
sub check {
    return if !$state_changed;
    $state_changed = 0;
    do_expensive_calculation();
    $widget->redraw();
}
FLTK::add_check(\&check);
FLTK::run();

Import this function with the :run tag.

add_fd

my $handle = FLTK::add_fd( $fh, $events, \&callback, $args );

Adds a handle to the list watched by FLTK.

$events may be any combination of the following:

  • FLTK::READ: The callback is triggered whenever there is data to be read.

    Listening sockets trigger this when a new incoming connection is attempted.

  • FLTK::WRITE: The callback is triggered whenever the filehandle or socket is ready to accept new data.

  • FLTK::EXCEPT: The callback is triggered whenever the filehandle or socket is encounters an exception.

...these constants are exported through the :fd tag.

The callback is called with the filehandle as the first argument and any data in args as the second argument. It is called in response to user events, but exactly when depends on the widget. For instance a button calls it when the button is released.

NOTE: To make use of callbacks, your perl must be recent enough to support weak references.

Import this function with the :fd tag.

add_idle

FLTK::add_idle( \&coderef, $args );

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.

Import this function with the :run tag.

add_timeout

FLTK::add_timeout( $time, \&callback, $args );

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

Import this function with the :run tag.

check

my $return = FLTK::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();
    last if user_hit_abort_button();
}

Import this function with the :run tag.

damage

my $needs_redraw = FLTK::damage( );

True if any FLTK::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.

FLTK::damage( $d );

Sets damage() to d.

Import this function with the :run tag.

display

FLTK::display( $d );

Startup method to set what X display to use. This uses setenv() to change the DISPLAY environment variable, so it will affect programs that are exec'd by this one.

This does some "uglification" required by X. If there is no colon in the string it appends ":0.0" to it. Thus a plain machine name may be used.

On non-X systems this sets the environment variable anyway, even though it probably will not affect the display used. It appears that putenv is missing on some versions of Windows so I commented it all out there, sigh.

Import this function with the :run tag.

enable_tablet_events

my $okay = FLTK::enable_tablet_events( );

Call this to indicate that you are interested in getting more information from a pen tablet device. It does some necessary overhead to enable tablets on X and Windows. In the future FLTK may do this automatically without you calling this.

If a tablet is detected, FLTK::event_pressure() will return the pen pressure as a float value between 0 and 1. Some tablets also support event_x_tilt() and event_y_tilt().

Import this function with the :run tag.

flush

FLTK::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 FLTK::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.

Import this function with the :run tag.

get_time_secs

my $time = FLTK::get_time_secs( );

Return portable time that increases by 1.0 each second.

On Windows it represents the time since system start, on Unixes, it's the gettimeofday().

Using a double, the numerical precision exceeds 1/1040000 even for the Unix gettimeofday value (which is seconds since 1970). However you should only store the difference between these values in a float.

The precision of the returned value depends on the OS, but the minimum precision is 20ms.

Import this function with the :run tag.

ready

my $actions = FLTK::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();
        last if user_hit_abort_button();
    }
}

Import this function with the :run tag.

redraw

FLTK::redraw( );

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

Import this function with the :run tag.

remove_fd

FLTK::remove_fd( $fh, $when );

Removes a handle from the list watched by FLTK.

The optional $when argument may be any combination of the following:

  • FLTK::READ: The callback is triggered whenever there is data to be read.

    Listening sockets trigger this when a new incoming connection is attempted.

  • FLTK::WRITE: The callback is triggered whenever the filehandle or socket is ready to accept new data.

  • FLTK::EXCEPT: The callback is triggered whenever the filehandle or socket is encounters an exception.

...these constants are exported through the :fd tag.

By default, the filehandle is removed completly which is the same as passing -1.

Import this function with the :fd tag.

remove_idle

FLTK::remove_idle( \&coderef, $args );

Removes the specified idle callback, if it is installed.

Import this function with the :run tag.

repeat_timeout

FLTK::repeat_timeout( $timeout );

Similar to add_timeout(), but 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:

my $ticker;
$ticker = FLTK::add_timeout(
    1,
    sub {
        say('TICK');
        FLTK::repeat_timeout(1, $ticker);
    }
);
FLTK::wait() while 1;

Import this function with the :run tag.

run

my $return = FLTK::run( );

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

Most FLTK programs will end with exit FLTK::run();.

Import this function with the :run or :default tags.

wait

my $events = FLTK::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.

Import this function with the :run tag.

my $events = FLTK::wait( $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.

Import this function with the :run tag.

Author

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

License and Legal

Copyright (C) 2008-2010 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.