FLTK::Window - Where you put stuff
This widget produces an actual window.
This can either be a main window,
with a border and title and all the window management controls,
or a "subwindow" inside a window.
This is controlled by whether or not the window has a
Internally there are now significant differences between "main" windows and "subwindows" and these really should be different classes,
they are the same for historic reasons.
Once you create a window,
you usually add children Widgets to it by using
add(child) or by using
begin() and then constructing the children.
FLTK::Group for more information on how to add and remove children.
There are several subclasses of
FLTK::Window that provide double-buffering,
and OpenGL support.
The window's callback is done if the user tries to close a window using the window manager and
FLTK::modal() is zero or equal to the window.
Window has a default callback that calls
hide() and calls
exit(0) if this is the last top-level window.
You can set the
shortcut() and then that key will call the callback.
If you don't change it then that key will close the window.
use FLTK; my $win = FLTK::Window->new(100, 100, 500, 800); $win->show(); FLTK::run();
$window->border( $set );
set is a true value, then a window border will be set, otherwise the window will have neither border nor caption.
my $set = $window->border( );
$window->borders( $rect );
$rect is set to the the size of the borders that will be added around this window. This is done by querying the window system. Because it is more convienent for most code the result is actually the rectangle that would be around the border if this window was zero in size and placed at
x,y are typically negative and
w,h are typically positive. To get the actual rectangle around your window, add these values to the window's size.
$window->child_of( $parent );
Tell the system that this window will not have an icon, it will dissappear and reappear when
parent is iconized or shown, and it is forced to always be above
parent. On X this is called a "Transient window", and Windows calls this a "overlapping child".
parent is different than the
parent(), which must be zero.
Changing this value causes
DESTROY() to be called, due to stupid limitations in X and Windows.
Win32 and some X window managers have an annoying bug where calling
show() on this will also raise the parent window to right below this, making many useful user interface designs impossible!
Turn off double buffering, so that drawing directly goes to the visible image on the screen. Not all systems can do this, they will remain double buffered even if this is off.
my $style = $window->default_style( );
By default a window has box() set to
FLAT_BOX, and the color() set to
GRAY75, which is a special color cell that is altered by
If you plan to turn the
border() off you may want to change the box() to
UP_BOX. You can also produce something that looks like an arbitrary shape (though really it is showing the original screen contents in the "outside" area, so the window had better be temporary and the user cannot move it) by setting the box() to NO_BOX and making draw() only draw the opaque part.
$window->default_style( $style );
Set the style.
my $db_set = $window->double_buffer( );
Returns a true value if
set_double_buffer() was called, returns a false value if
clear_double_buffer() was called. If neither has been called, this returns a machine-dependant state (systems where double buffering is efficient turn it on by default).
my $window = $window->drawing_window( );
my $return = $window->exec( $parent, $grab );
The window is popped up and this function does not return until
make_exec_return() is called, or the window is destroyed or
hide() is called, or
FLTK::exit_modal() is called. During this time events to other windows in this application are either thrown away or redirected to this window.
child_of(parent) (using first() if parent is undefined), so this window is a floating panel that is kept above the parent. It then uses
FLTK::modal(this,grab) to make all events go to this window.
The return value is the argument to
make_exec_return(), or a false value if any other method is used to exit the loop.
parent is undefined, the window that last received an event is used as the parent. This is convenient for popups that appear in response to a mouse or key click.
FLTK::modal() for what grab does. This is useful for popup menus.
my $win = FLTK::first( );
Returns the id of some
visible() window. If there is more than one, the last one to receive an event is returned. This is useful as a default value for
FLTK::Window::exec() uses it for this if no other parent is specified. This is also used by
FLTK::run() to see if any windows still exist.
FLTK::first( $window );
window is visible, this removes it from wherever it is in the list and inserts it at the top, as though it received an event. This can be used to change the parent of dialog boxes run by
Get rid of extra storage created by drawing when
double_buffer() was turned on.
$window->fullscreen( $monitor );
Make the window completely fill the monitor, without any window manager border or taskbar or anything else visible. Use
fullscreen_off() to undo this.
show(). We don't do this because it causes newer window systems to blink unnecessarily.
fullscreen_off()will result in unpredictable effects, and should be avoided.
Chooses the Monitor that the center of the window is on to be the one to resize to.
$window->fullscreen_off( $x, $y, $w, $h );
Turns off any side effects of
fullscreen(), then does
$window->hotspot( $widget, $offscreen );
position() the window so that the mouse is pointing at the center of the widget, which may be the window itself. If
offscreen is a true value, the window is allowed to extend off the Monitor (some X window managers do not allow this).
$window->hotspot( $CX, $CY, $offscreen );
$window->icon( $path );
This loads an icon (.ico) in the window.
my $is_it = $window->iconic( );
On X this will return true in the time between when
show() is called and when the window manager finally puts the window on the screen and causes an expose event.
show() to restore the window.
Currently there are only X and Win32 system-specific ways to control what is drawn in the icon. You should not rely on window managers displaying the icons.
$window->iconlabel( $iname );
Sets the text displayed below the icon (or in the taskbar). If you don't set this it defaults to the
label() but if that appears to be a filename, it defaults to the last portion after the last
$window->label( $name, $iname );
$window->label( $name );
Sets the window title, which is drawn in the titlebar by the system.
my $title = $window->label( );
Returns the window title.
$window->make_exec_return( $return_value );
exec() is currently being called, make it hide this window and return
Does nothing if
exec() is not being called.
Results are undefined if the innermost
exec() is being called on a window other than this one. Current behavior is to cause that exec to return false.
my $win = $window->new( $x, $y, $w, $h, $label );
Creates a new
my $win = $window->new( $w, $h, $label );
Same but window is placed by OS.
my $win = $window->next( );
This does nothing if the window is not
shown(), it is assummed that overlays are only drawn in response to user input.
$window->resize( $x, $y, $w, $h );
Change the size and position of the window. If
shown() is true, these changes are communicated to the window server (which may refuse that size and cause a further resize). If
shown() is false, the size and position are used when
show() is called. See FLTK::Group for the effect of resizing on the child widgets.
The special value
FLTK::USEDEFAULT may be used for
Y indicate that the system should choose the window's position. This will only work before
show() is called.
If the window is double-buffered, all drawing is done first to some offscreen image, and then copied to the screen as a single block. This eliminates blinking as the window is updated, and often the application looks faster, even if it actually is slower.
$window->show( $parent );
$window->show( $argc, @argv );
This must be called after
FLTK::args($argc,@argv) to show the "main" window, this indicates which window should be affected by any
-geometry switches. In addition if
FLTK::args() has not been called yet this does so, this is a useful shortcut for the main window in a small program.
Cause the window to become visible. It is harmless to call this multiple times.
For subwindows (with a
parent()) this just causes the window to appear. Currently no guarantee about stacking order is made.
For a outer window (one with no
parent()) this causes the window to appear on the screen, be de-iconized, and be raised to the top. Depending on
child_of() settings of this window and of windows pointing to it, and on system and window manager settings, this may cause other windows to also be deiconized and raised, or if this window is a
child_of() then this window may remain iconized.
Window::show() is not a virtual override of
Widget::show(). You can call either one. The only difference is that if an outer window has had
show() called already,
Window::show() will raise and deiconize it, while
Widget::show() will only un-hide() it, making it appear in the same stacking order as before but not changing the iconization state (on some X window managers it will deiconize anyway).
The first time this is called is when the actual "system" window (ie the X window) is created. Before that an fltk window is simply an internal data structure and is not visible outside your program. To return to the non-system-window state call
hide() will "unmap" the system window.
The first time
show() is called on any window is when fltk will call
FLTK::load_theme(), unless you have already called them. This allows these expensive operations to be deferred as long as possible, and allows fltk programs to be written that will run without an X server as long as they don't actually show a window.
$window->show_inside( $parent );
Make the window with a normal system border and behavior, but place it inside the
parent as though that was the desktop. This is what Windows calls "MDI". Typically the other window (which must already be shown) is a child window so that space can remain around it for a menu/tool bar.
parent() of the window must be zero and it will remain zero after this is called. Fltk uses a zero parent to indicate that the system is managing the window.
my $was_it = $window->shown( );
$window->size_range( $minW, $minH, $maxW, $maxH, $dw, $dh );
Set the allowable range the user can resize this window to. This only works for top-level windows.
$minHare the smallest the window can be.
$maxHare the largest the window can be. If either is equal to the minimum then you cannot resize in that direction. If either is zero then FLTK picks a maximum size in that direction such that the window will fill the screen.
$dhare size increments. The window will be constrained to widths of
$minW + N * $dw, where
Nis any non-negative integer. If these are less or equal to 1 they are ignored. (this is ignored on WIN32)
It is undefined what happens if the current size does not fit in the constraints passed to
If this function is not called, FLTK tries to figure out the range from the setting of
resizeable()is undefined (this is the default), then the window cannot be resized.
resizeable()is less than
100, then that is considered the minimum size. Otherwise the
resizeable()has a minimum size of
resizeable()is zero, then that is also the maximum size (so the window cannot resize in that direction).
Resizes the actual system window to match the current size of the fltk widget. You should call this in your
layout() method if xywh have changed. The
layout_damage() flags must be on or it won't work.
Sanko Robinson <firstname.lastname@example.org> - http://sankorobinson.com/
Copyright (C) 2008-2010 by Sanko Robinson <email@example.com>
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.