fltk::Window Class Reference

Inherits fltk::Group.

Inherited by fltk::DoubleBufferWindow, fltk::GlWindow, fltk::MenuWindow, and fltk::ShapedWindow.

List of all members.

Public Member Functions

void * backbuffer () const
bool border () const
void border (bool set)
void borders (Rectangle *r) const
void child_of (const Window *w)
const Windowchild_of () const
void clear_border ()
void clear_double_buffer ()
void copy_label (const char *c)
virtual void destroy ()
bool double_buffer () const
virtual void draw ()
virtual void draw_overlay ()
void erase_overlay ()
bool exec (const Window *parent=0, bool grab=false)
virtual void flush ()
void free_backbuffer ()
void fullscreen (const Monitor &)
void fullscreen ()
void fullscreen_off (int, int, int, int)
bool get_size_range (int *min_w, int *min_h, int *max_w, int *max_h)
virtual int handle (int)
void hotspot (const Widget &p, bool offscrn=false)
void hotspot (const Widget *, bool offscreen=false)
void hotspot (int x, int y, bool offscreen=false)
void icon (const void *ic)
const void * icon () const
bool iconic () const
void iconize ()
void iconlabel (const char *)
const char * iconlabel () const
void label (const char *label, const char *iconlabel)
void label (const char *)
const char * label () const
virtual void layout ()
void make_exec_return (bool)
void maximize ()
Windownext ()
bool override () const
void redraw_overlay ()
void set_double_buffer ()
void set_modal ()
void set_non_modal ()
void set_override ()
void show (const Window *parent)
void show (int, char **)
void show ()
void show_inside (const Window *parent)
bool shown () const
void size_range (int a, int b, int c=0, int d=0, int e=0, int f=0)
void system_layout ()
 Window (int, int, const char *=0)
 Window (int, int, int, int, const char *=0, bool begin=false)
virtual ~Window ()

Static Public Member Functions

static void default_callback (Window *, void *v)
static const Windowdrawing_window ()
static void first (Window *)
static Windowfirst ()
static void xclass (const char *v)
static const char * xclass ()

Static Public Attributes

static NamedStyledefault_style
static const Windowdrawing_window_

Protected Member Functions

virtual void create ()

Friends

class CreatedWindow


Detailed Description

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 parent(). Internally there are now significant differences between "main" windows and "subwindows" and these really should be different classes, they are the same for historic fltk 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. See fltk::Group for more information on how to add and remove children.

There are several subclasses of fltk::Window that provide double-buffering, overlay, menu, 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 Window::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.


Constructor & Destructor Documentation

Window::Window ( int  X,
int  Y,
int  W,
int  H,
const char *  l = 0,
bool  begin = false 
)

This constructor is for child windows. You should use the constructor with just W and H for normal parent windows. This constructor leaves visible() true, so the child window will appear when the parent window has show() called. WARNING: this is misleading if this is *not* a child window, call clear_visible() for top-level ones.

Window::Window ( int  W,
int  H,
const char *  l = 0 
)

This form of the constructor should be used for a "top-level" window (that is, one that is not inside another window). It correctly sets visible() to false and parent() to NULL. By not specifying the position of the window, the window system will pick a place to show the window (some older X window managers will allow the user to place the window by hand). If you want to force a position you should call position(x,y) or hotspot() before calling show().

Window::~Window (  )  [virtual]

Calls destroy(). The destructor also deletes all the children. This allows a whole tree to be deleted at once, without having to keep a pointer to all the children in the user code. A kludge has been done so the Window and all of it's children can be automatic (local) variables, but you must declare the Window first so that it is destroyed last.

References destroy().


Member Function Documentation

void Window::label ( const char *  name  ) 

Sets the window title, which is drawn in the titlebar by the system.

Reimplemented from fltk::Widget.

void Window::iconlabel ( const char *  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 '/' character.

void Window::label ( const char *  name,
const char *  iname 
)

Sets both the label() and the iconlabel()

References fltk::filename_name(), fltk::Widget::parent(), and fltk::xdisplay.

void Window::border ( bool  set  )  [inline]

if set is true, then a window border will be set, otherwise the window will have neither border nor caption.

Referenced by borders().

void fltk::Window::clear_border (  )  [inline]

Deprecated:
compat. api only, please use Window::border(bool)

void Window::child_of ( const Window 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!

If you want a dialog that blocks interaction with the other windows of your application or with all other applications, you need to look at exec() (or possibly fltk::modal()).

References fltk::Widget::contains(), destroy(), fltk::Widget::parent(), and fltk::Widget::window().

bool Window::double_buffer (  )  const [inline]

Returns true if set_double_buffer() was called, returns false if clear_double_buffer() was called. If neither has been called this returns a machine-dependent state (systems where double buffering is efficient turn it on by default).

Referenced by flush().

void Window::set_double_buffer (  )  [inline]

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.

void Window::clear_double_buffer (  )  [inline]

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.

void Window::free_backbuffer (  ) 

Get rid of extra storage created by drawing when double_buffer() was turned on.

References fltk::stop_drawing(), and fltk::xdisplay.

Referenced by destroy(), and system_layout().

void Window::draw_overlay (  )  [virtual]

A subclass of Window can define this method to draw an "overlay" image that appears atop everything else in the window. This will only be called if you call redraw_overlay() on the shown() window, and it will stop being called if you call erase_overlay().

This is designed for a fast-changing graphic such as a selection rectangle. The implementation is to put the window into double_buffer() mode, and then set things so the on-screen image is being drawn before this method is called. The previous overlay image was erased before calling this by copying the back buffer to the front. Notice that the overlay will blink as you redraw it, you must trade off this annoyance against the slower update of the overlay if you just draw it normally in the draw() method.

Some systems don't allow drawing in the front buffer. In this case the entire back buffer is redrawn and the overlay drawn atop it.

The default version draws a red rectangle, so that mistaken calls to redraw_overlay() are detectable.

Reimplemented in fltk::GlWindow.

References fltk::fillrect(), fltk::Rectangle::h(), fltk::RED, fltk::setcolor(), and fltk::Rectangle::w().

Referenced by flush().

void Window::redraw_overlay (  ) 

Indicate that the image made by draw_overlay() has changed and must be drawn or redrawn. If the image is blank you should call erase_overlay().

This does nothing if the window is not shown(), it is assummed that overlays are only drawn in response to user input.

Reimplemented in fltk::GlWindow.

References fltk::Widget::damage(), fltk::DAMAGE_OVERLAY, fltk::CreatedWindow::overlay, and fltk::Widget::set_damage().

void Window::erase_overlay (  ) 

Indicate that the overlay drawn with draw_overlay() is blank. draw_overlay() will not be called until redraw_overlay() is called again.

References fltk::Widget::damage(), fltk::DAMAGE_OVERLAY, fltk::CreatedWindow::overlay, and fltk::Widget::set_damage().

void Window::hotspot ( int  cx,
int  cy,
bool  offscreen = false 
)

position() the window so that the mouse is pointing at the cx,cy position. If offscreen is true then the window is allowed to extend off the Monitor (some X window managers do not allow this).

References fltk::Rectangle::b(), borders(), fltk::Group::find(), fltk::get_mouse(), fltk::Rectangle::h(), fltk::Widget::position(), fltk::Rectangle::r(), fltk::Rectangle::w(), fltk::Monitor::work, fltk::Rectangle::x(), and fltk::Rectangle::y().

Referenced by hotspot().

void Window::hotspot ( const Widget widget,
bool  offscreen = false 
)

position() the window so that the mouse is pointing at the center of the widget, which may be the window itself. If offscreen is true then the window is allowed to extend off the Monitor (some X window managers do not allow this).

References fltk::Rectangle::h(), hotspot(), fltk::Widget::parent(), fltk::Rectangle::w(), fltk::Rectangle::x(), and fltk::Rectangle::y().

void Window::size_range ( int  minw,
int  minh,
int  maxw = 0,
int  maxh = 0,
int  dw = 0,
int  dh = 0 
) [inline]

Set the allowable range the user can resize this window to. This only works for top-level windows.

  • minw and minh are the smallest the window can be.
  • maxw and maxh are 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.
  • dw and dh are size increments. The window will be constrained to widths of minw+N*dw, where N is 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 size_range().

If this function is not called, FLTK tries to figure out the range from the setting of resizeable():

  • If resizeable() is NULL (this is the default) then the window cannot be resized.
  • If either dimension of resizeable() is less than 100, then that is considered the minimum size. Otherwise the resizeable() has a minimum size of 100.
  • If either dimension of resizeable() is zero, then that is also the maximum size (so the window cannot resize in that direction).

Referenced by show(), and system_layout().

bool Window::shown (  )  const [inline]

void Window::resize(int,int,int,int)

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 x and y indicate that the system should choose the window's position. This will only work before show() is called.

Returns non-zero if show() has been called, but destroy() has not been called. Note that this returns true if hide() was called or if the user has iconized the window.

Referenced by borders(), fltk::CreatedWindow::create(), destroy(), first(), fltk::GlutWindow::make_current(), fltk::GlWindow::mode(), fltk::GlWindow::redraw_overlay(), and show().

void Window::show (  ) 

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 destroy() or ~Window(). hide() will "unmap" the system window.

The first time show() is called on any window is when fltk will call fltk::open_display() and 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.

Reimplemented from fltk::Widget.

References fltk::Widget::any_of(), create(), fltk::Group::current(), first(), fltk::Widget::flag(), fltk::grab(), fltk::Rectangle::h(), fltk::Group::handle(), fltk::Widget::is_group(), fltk::load_theme(), fltk::modal(), fltk::open_display(), fltk::Widget::parent(), fltk::Group::resizable(), fltk::SHOW, shown(), size_range(), fltk::Rectangle::w(), fltk::Widget::window(), fltk::xdisplay, and fltk::CreatedWindow::xid.

Referenced by exec(), iconize(), fltk::GlWindow::mode(), show(), and show_inside().

void Window::show ( int  argc,
char **  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 switch. 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.

References fltk::Monitor::all(), fltk::args(), fltk::filename_name(), fltk::Widget::flags(), fltk::Rectangle::h(), fltk::Rectangle::r(), fltk::Group::resizable(), fltk::Widget::resize(), show(), fltk::Group::sizes(), fltk::Rectangle::w(), fltk::Rectangle::x(), fltk::xdisplay, fltk::xid(), and fltk::Rectangle::y().

void Window::show ( const Window parent  ) 

Same as child_of(parent); show().

References show().

bool Window::exec ( const Window parent = 0,
bool  grab = false 
)

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.

This does child_of(parent) (using first() if parent is null), 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 false if any other method is used to exit the loop.

If parent is null 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.

See fltk::modal() for what grab does. This is useful for popup menus.

References fltk::Widget::clear_flag(), fltk::exit_modal_flag(), first(), fltk::grab(), fltk::Widget::hide(), fltk::modal(), show(), fltk::Widget::state(), fltk::STATE, and fltk::wait().

void Window::make_exec_return ( bool  return_value  ) 

If exec() is currently being called, make it hide this window and return return_value.

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.

References fltk::exit_modal(), fltk::Widget::set_flag(), and fltk::STATE.

void Window::show_inside ( const Window frame  ) 

Make the window with a normal system border and behavior, but place it inside the frame 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.

Notice that 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.

On systems that don't support nested desktops (i.e. X) this does child_of(frame) and show(), which produces an overlapping window that will remain above the frame window. (IMHO this is a great improvement over MDI!).

References show().

void Window::destroy (  )  [virtual]

Hides the window and also deletes all window system information about the window, and thus returns it back to the state it was in before the first show(). It is harmless to call this if the window is already destroyed.

Subclasses can override this, if you do this you must also override the destructor and make it call destroy().

Reimplemented in fltk::GlWindow.

References child_of(), destroy(), fltk::Widget::flag(), free_backbuffer(), fltk::CreatedWindow::frontbuffer, fltk::modal(), fltk::CreatedWindow::next, fltk::CreatedWindow::region, fltk::Widget::set_visible(), shown(), fltk::Widget::throw_focus(), fltk::Widget::visible(), fltk::Rectangle::w(), fltk::Widget::window(), fltk::CreatedWindow::window, fltk::Rectangle::x(), fltk::xdisplay, fltk::xid(), and fltk::CreatedWindow::xid.

Referenced by child_of(), destroy(), and ~Window().

void Window::iconize (  ) 

Iconifies the window. If you call this when shown() is false it will show() it as an icon. If the window is already iconified this does nothing.

Call 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.

References show(), fltk::CreatedWindow::wait_for_expose, fltk::xdisplay, fltk::CreatedWindow::xid, and fltk::xscreen.

bool Window::iconic (  )  const

Returns true if the window is currently displayed as an icon. Returns false if the window is not shown() or hide() has been called.

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.

Returns true if the window is shown but is iconized.

void Window::fullscreen (  ) 

Chooses the Monitor that the center of the window is on to be the one to resize to.

References fltk::Monitor::find(), fltk::Rectangle::h(), fltk::Rectangle::w(), fltk::Rectangle::x(), and fltk::Rectangle::y().

void Window::fullscreen ( const Monitor 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.

Known bugs:

  • Older versions of both Linux and Windows will refuse to hide the taskbar. Proposed solutions for this tend to have detrimental effects, such as making it impossible to switch tasks or to put another window atop this one. It appears that newer versions of both Linux and Windows work correctly, so we will not fix this.

  • Many older X window managers will refuse to position the window correctly and instead place them so the top-left of the border in the screen corner. You may be able to fix this by calling hide() first, then fullscreen(), then show(). We don't do this because it causes newer window systems to blink unnecessarily.

  • Some X window managers will raise the window when you change the size.

References fltk::Rectangle::h(), fltk::Widget::set_flag(), fltk::Rectangle::w(), fltk::Rectangle::x(), and fltk::Rectangle::y().

void Window::fullscreen_off ( int  X,
int  Y,
int  W,
int  H 
)

Turns off any side effects of fullscreen(), then does resize(x,y,w,h).

References fltk::Widget::clear_flag().

void Window::system_layout (  ) 

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.

References free_backbuffer(), fltk::Rectangle::h(), fltk::Widget::is_window(), fltk::Widget::layout_damage(), fltk::LAYOUT_WH, fltk::LAYOUT_XYWH, fltk::Widget::parent(), size_range(), fltk::stop_drawing(), fltk::Rectangle::w(), fltk::Rectangle::x(), fltk::xdisplay, and fltk::Rectangle::y().

void Window::flush (  )  [virtual]

This virtual function is called by flush() to update the window. You can override it for special window subclasses to change how they draw.

For FLTK's normal windows this calls make_current(), then perhaps sets up the clipping if the only damage is expose events, and then draw(), and then does some extra work to get the back buffer copied or swapped into the front buffer.

For your own windows you might just want to put all the drawing code in here.

References fltk::clip_region(), fltk::Widget::damage(), fltk::DAMAGE_ALL, fltk::DAMAGE_EXPOSE, fltk::DAMAGE_OVERLAY, double_buffer(), fltk::draw_into(), draw_overlay(), fltk::gc, fltk::Rectangle::h(), fltk::intersect_with_clip(), fltk::Widget::parent(), fltk::Rectangle::r(), fltk::Widget::set_damage(), fltk::Rectangle::w(), fltk::Rectangle::x(), fltk::xcolormap, fltk::xdisplay, fltk::xvisual, and fltk::Rectangle::y().

Window * Window::first (  )  [static]

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::child_of(). 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.

References fltk::CreatedWindow::next, override(), fltk::Widget::parent(), fltk::Widget::visible(), fltk::CreatedWindow::window, and fltk::Widget::window().

Referenced by fltk::dnd(), exec(), fltk::focus(), fltk::handle(), fltk::modal(), fltk::paste(), fltk::run(), show(), fltk::Widget::throw_focus(), and fltk::Menu::try_popup().

void Window::first ( Window window  )  [static]

If this 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 fltk::Window::exec() or fltk::ask().

References fltk::Group::find(), shown(), and fltk::xid().

Window * Window::next (  ) 

Returns the next visible() top-level window, returns NULL after the last one. You can use this and first() to iterate through all the visible windows.

References fltk::CreatedWindow::next, override(), fltk::Widget::parent(), fltk::Widget::visible(), fltk::CreatedWindow::window, and fltk::Widget::window().

void Window::borders ( fltk::Rectangle r  )  const

Rectangle 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 0,0. 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.

References border(), fltk::Group::children(), fltk::Widget::parent(), fltk::Group::resizable(), fltk::Rectangle::set(), shown(), fltk::xdisplay, and fltk::xid().

Referenced by hotspot().

const Window * Window::drawing_window (  )  [inline, static]

Returns the Window currently being drawn into. To set this use make_current(). It will already be set when draw() is called.

Referenced by fltk::glstart().

void Window::create (  )  [protected, virtual]

This virtual function may be overridden to use something other than FLTK's default code to create the system's window. This must call either CreatedWindow::create() or CreatedWindow::set_xid().

An example for Xlib (include x.h to make this work):

void MyWindow::create() {
  fltk::open_display(); // necessary if this is first window
  // we only calcualte the necessary visual & colormap once:
  static XVisualInfo* visual;
  static Colormap colormap;
  static int background;
  if (!visual) {
    visual = figure_out_visual();
    colormap = XCreateColormap(xdisplay, RootWindow(xdisplay,xscreen),
                    vis->visual, AllocNone);
    XColor xcol; xcol.red = 1; xcol.green = 2; xcol.blue = 3;
    XAllocColor(fltk::display, colormap, &xcol);
    background = xcol.pixel;
  }
  CreatedWindow::create(this, visual, colormap, background);
}

References fltk::xcolormap, and fltk::xvisual.

Referenced by show().


Member Data Documentation

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 fltk::set_background().

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.

Reimplemented from fltk::Widget.

Reimplemented in fltk::MenuWindow, and fltk::Tooltip.


Wed Jun 17 08:58:19 2009. FLTK ©2007 Bill Spitzak and others.
Permission is granted to reproduce this manual or any portion for any purpose, provided this copyright and permission notice are preserved.