fltk Namespace Reference


class  Adjuster
class  AssociationFunctor
 Class used by the foreach() functions. More...
class  AssociationType
 Base class for the association type. More...
class  Browser
class  Button
class  CheckButton
class  Choice
class  Clock
class  ClockOutput
class  CreatedWindow
class  CycleButton
class  Dial
class  Divider
class  FileBrowser
class  FileChooser
class  FillDial
class  FillSlider
class  FlatBox
class  FloatInput
class  Font
class  FrameBox
class  gifImage
class  GlutWindow
class  GlWindow
class  Group
class  GSave
class  Guard
struct  HelpBlock
struct  HelpLink
struct  HelpTarget
class  HelpView
class  HighlightBox
class  HighlightButton
class  Image
struct  ImageType
class  Input
class  IntInput
class  InvisibleBox
class  Item
class  ItemGroup
class  LightButton
class  LineDial
class  List
class  Menu
class  MenuBar
class  MenuSection
class  MenuWindow
class  Monitor
class  MultiBrowser
class  MultiImage
class  MultiLineOutput
class  Mutex
class  NamedStyle
class  NumericInput
class  Output
class  PackedGroup
class  PopupMenu
class  Preferences
class  ProgressBar
class  RadioButton
class  RadioItem
class  Rectangle
class  RecursiveMutex
class  RepeatButton
class  ReturnButton
class  Scrollbar
class  ScrollGroup
class  ShapedWindow
class  SharedImage
class  SignalMutex
class  Slider
class  StatusBarGroup
class  StringArray
class  StringHierarchy
class  StringList
class  Style
class  StyleSet
class  Symbol
class  TabGroup
class  TabGroupPager
class  TextBuffer
class  TextDisplay
class  TextEditor
class  ThumbWheel
class  TiledImage
class  ToggleButton
class  ToggleItem
class  Tooltip
class  Valuator
class  ValueInput
class  ValueOutput
class  ValueSlider
class  Widget
class  Window
class  WizardGroup
class  WordwrapOutput
class  xbmImage
class  xpmFileImage
class  xpmImage


typedef void( Callback )(Widget *, void *)
typedef void( Callback0 )(Widget *)
typedef void( Callback1 )(Widget *, long)
typedef CallbackCallback_p
typedef void * GLContext
 Actually a GLXContext or HGLDC.
typedef const char *( HelpFunc )(Widget *, const char *)


enum  {
  LAYOUT_X = 0x01, LAYOUT_Y = 0x02, LAYOUT_XY = 0x03, LAYOUT_W = 0x04,
  LAYOUT_H = 0x08, LAYOUT_WH = 0x0C, LAYOUT_XYWH = 0x0F, LAYOUT_CHILD = 0x10,
enum  {
enum  {


bool color_chooser (const char *name, float &r, float &g, float &b)
bool color_chooser (const char *name, float &r, float &g, float &b, float &a)
bool color_chooser (const char *name, uchar &r, uchar &g, uchar &b, uchar &a)
bool color_chooser (const char *name, Color &c)
bool color_chooser (const char *name, uchar &r, uchar &g, uchar &b)
Fontfont (int)
ImageTypeguess_image (const char *name, const uchar *datas=0)
void register_images ()
Color show_colormap (Color oldcol)
double version ()
void file_chooser_ok_label (const char *l)
void use_system_file_chooser (bool=true)
const char * dir_chooser (const char *message, const char *fname, int relative=0)
void file_chooser_callback (void(*cb)(const char *))
const char * file_chooser (const char *message, const char *pattern, const char *filename, bool save=false, int relative=1)
void glstart ()
void glfinish ()
void glsetcolor (Color)
void glstrokerect (int x, int y, int w, int h)
void glfillrect (int x, int y, int w, int h)
void glsetfont (Font *f, float size)
float glgetascent ()
float glgetdescent ()
float glgetwidth (const char *)
float glgetwidth (const char *, int n)
void gldrawtext (const char *)
void gldrawtext (const char *, int n)
void gldrawtext (const char *, float x, float y, float z=0)
void gldrawtext (const char *, int n, float x, float y, float z=0)
void gldrawimage (const uchar *, int x, int y, int w, int h, int d=3, int ld=0)


void(* warning )(const char *,...) = ::warning
void(* error )(const char *,...) = ::error
void(* fatal )(const char *,...) = ::error


NamedStyleicon_style = &i_style
NamedStylemessage_style = &m_style
const char * message_window_label = NULL
float message_window_timeout = 0
bool message_window_scrollable = 0
const char * no = "&No"
const char * yes = "&Yes"
const char * ok = "&OK"
const char * cancel = "&Cancel"
void message (const char *,...)
void alert (const char *,...)
int ask (const char *,...)
int choice (const char *q, const char *b0, const char *b1, const char *b2,...)
int choice_alert (const char *q, const char *b0, const char *b1, const char *b2,...)
const char * input (const char *label, const char *deflt=0,...)
const char * password (const char *label, const char *deflt=0,...)
void beep (int type=BEEP_DEFAULT)
void beep_on_dialog (bool)
bool beep_on_dialog ()


enum  {
  NO_COLOR = 0, FREE_COLOR = 16, NUM_FREE_COLOR = 16, GRAY00 = 32,
  GRAY05 = 33, GRAY10 = 34, GRAY15 = 35, GRAY20 = 36,
  GRAY25 = 37, GRAY30 = 38, GRAY33 = 39, GRAY35 = 40,
  GRAY40 = 41, GRAY45 = 42, GRAY50 = 43, GRAY55 = 44,
  GRAY60 = 45, GRAY65 = 46, GRAY66 = 47, GRAY70 = 48,
  GRAY75 = 49, GRAY80 = 50, GRAY85 = 51, GRAY90 = 53,
  GRAY95 = 54, GRAY99 = 55, BLACK = 0x38, RED = 0x58,
  GREEN = 0x3f, YELLOW = 0x5f, BLUE = 0xd8, MAGENTA = 0xf8,
  CYAN = 0xdf, WHITE = 0xff , WINDOWS_BLUE = 0x88
typedef unsigned Color
Color color (unsigned char r, unsigned char g, unsigned char b)
Color color (unsigned char g)
Color color (const char *)
Color parsecolor (const char *, unsigned length)
Color lerp (Color c0, Color c1, float f)
Color inactive (Color fg)
Color inactive (Color fg, Color bg)
Color contrast (Color fg, Color bg)
void split_color (Color c, unsigned char &r, unsigned char &g, unsigned char &b)
void set_color_index (Color index, Color)
Color get_color_index (Color index)
void set_background (Color)
Color nearest_index (Color)


Color current_color_
Color current_bgcolor_
const Styledrawstyle_ = Widget::default_style
Flags drawflags_
int line_style_
float line_width_
const char * line_dashes_
const char * encoding_ = "iso10646-1"
float current_size_
const int * column_widths_ = 0
typedef const uchar *(* DrawImageCallback )(void *data, int x, int y, int w, uchar *buffer)
void push_matrix ()
void pop_matrix ()
void scale (float x, float y)
void scale (float x)
void translate (float x, float y)
void translate (int x, int y)
void rotate (float d)
void concat (float, float, float, float, float, float)
void load_identity ()
void transform (float &x, float &y)
void transform_distance (float &x, float &y)
void transform (int &x, int &y)
void transform (const Rectangle &from, Rectangle &to)
void transform (int &x, int &y, int &w, int &h)
void push_clip (const Rectangle &)
void push_clip (int X, int Y, int W, int H)
 Same as push_clip(Rectangle(x,y,w,h)) but faster:
void clipout (const Rectangle &)
void pop_clip ()
void push_no_clip ()
bool not_clipped (const Rectangle &)
int intersect_with_clip (Rectangle &)
void setcolor (Color)
void setcolor_alpha (Color, float alpha)
Color getcolor ()
void setbgcolor (Color c)
Color getbgcolor ()
void drawstyle (const Style *s, Flags)
const Styledrawstyle ()
void setdrawflags (Flags f)
Flags drawflags ()
Flags drawflags (Flags f)
void line_style (int, float width=0, const char *dashes=0)
int line_style ()
float line_width ()
const char * line_dashes ()
void newpath ()
void addvertex (float x, float y)
void addvertex (int x, int y)
void addvertices (int n, const float v[][2])
void addvertices (int n, const int v[][2])
void addvertices_transformed (int n, const float v[][2])
void addcurve (float, float, float, float, float, float, float, float)
void addarc (float x, float y, float w, float h, float a1, float a2)
void addpie (const Rectangle &r, float a, float a2)
void addchord (const Rectangle &r, float a, float a2)
void closepath ()
void strokepath ()
void fillpath ()
void fillstrokepath (Color)
void fillrect (int, int, int, int)
void fillrect (const Rectangle &r)
void strokerect (int, int, int, int)
void strokerect (const Rectangle &r)
void drawline (int x0, int y0, int x1, int y1)
void drawline (float x0, float y0, float x1, float y1)
void drawpoint (int x, int y)
void drawpoint (float x, float y)
void setfont (Font *, float size)
void setfont (const char *, float size)
void setfont (const char *, int attributes, float size)
const char * get_encoding ()
void set_encoding (const char *)
Fontgetfont ()
float getsize ()
float getwidth (const char *)
float getwidth (const char *, int length)
float getascent ()
float getdescent ()
void drawtext_transformed (const char *, int n, float x, float y)
void drawtext (const char *, float x, float y)
void drawtext (const char *, int length, float x, float y)
void measure (const char *, int &w, int &h, Flags=0)
void measure (float(*getwidth)(const char *, int), const char *, float &w, float &h, Flags=0)
void drawtext (const char *, const Rectangle &, Flags)
void drawtext (void(*textfunction)(const char *, int, float, float), float(*getwidth)(const char *, int), const char *str, const Rectangle &r, Flags flags)
const int * column_widths ()
void column_widths (const int *i)
void drawimage (const uchar *, PixelType, const Rectangle &)
void drawimage (const uchar *, PixelType, const Rectangle &, int linedelta)
void drawimage (DrawImageCallback, void *, PixelType, const Rectangle &)
uchar * readimage (uchar *p, PixelType, const Rectangle &)
uchar * readimage (uchar *p, PixelType, const Rectangle &, int linedelta)
void scrollrect (const Rectangle &, int dx, int dy, void(*draw_area)(void *, const Rectangle &), void *)


enum  {
  NO_EVENT = 0, PUSH = 1, RELEASE = 2, ENTER = 3,
  LEAVE = 4, DRAG = 5, FOCUS = 6, UNFOCUS = 7,
  KEY = 8, KEYUP = 9, FOCUS_CHANGE = 10, MOVE = 11,
  SHOW = 16, PASTE = 17, TIMEOUT = 18, MOUSEWHEEL = 19,
  DND_ENTER = 20, DND_DRAG = 21, DND_LEAVE = 22, DND_RELEASE = 23,
  TOOLTIP = 24
enum  {
  LeftButton = 1, MiddleButton = 2, RightButton = 3, WheelUp = 4,
  WheelDown = 5, WheelLeft = 6, WheelRight = 7, SpaceKey = 32,
  BackSpaceKey = 0xff08, TabKey = 0xff09, ClearKey = 0xff0b, ReturnKey = 0xff0d,
  PauseKey = 0xff13, ScrollLockKey = 0xff14, EscapeKey = 0xff1b, HomeKey = 0xff50,
  LeftKey = 0xff51, UpKey = 0xff52, RightKey = 0xff53, DownKey = 0xff54,
  PageUpKey = 0xff55, PageDownKey = 0xff56, EndKey = 0xff57, PrintKey = 0xff61,
  InsertKey = 0xff63, MenuKey = 0xff67, HelpKey = 0xff68, NumLockKey = 0xff7f,
  Keypad = 0xff80, KeypadEnter = Keypad+'\r', MultiplyKey = Keypad+'*', AddKey = Keypad+'+',
  SubtractKey = Keypad+'-', DecimalKey = Keypad+'.', DivideKey = Keypad+'/', Keypad0 = Keypad+'0',
  Keypad1 = Keypad+'1', Keypad2 = Keypad+'2', Keypad3 = Keypad+'3', Keypad4 = Keypad+'4',
  Keypad5 = Keypad+'5', Keypad6 = Keypad+'6', Keypad7 = Keypad+'7', Keypad8 = Keypad+'8',
  Keypad9 = Keypad+'9', KeypadLast = 0xffbd, F0Key = 0xffbd, F1Key = F0Key+1,
  F2Key = F0Key+2, F3Key = F0Key+3, F4Key = F0Key+4, F5Key = F0Key+5,
  F6Key = F0Key+6, F7Key = F0Key+7, F8Key = F0Key+8, F9Key = F0Key+9,
  F10Key = F0Key+10, F11Key = F0Key+11, F12Key = F0Key+12, LastFunctionKey = F0Key+35,
  LeftShiftKey = 0xffe1, RightShiftKey = 0xffe2, LeftCtrlKey = 0xffe3, RightCtrlKey = 0xffe4,
  CapsLockKey = 0xffe5, LeftMetaKey = 0xffe7, RightMetaKey = 0xffe8, LeftAltKey = 0xffe9,
  RightAltKey = 0xffea, DeleteKey = 0xffff
enum  {
  SHIFT = 0x00010000, CAPSLOCK = 0x00020000, CTRL = 0x00040000, ALT = 0x00080000,
  NUMLOCK = 0x00100000, META = 0x00400000, SCROLLLOCK = 0x00800000, BUTTON1 = 0x01000000,
  BUTTON2 = 0x02000000, BUTTON3 = 0x04000000, BUTTON4 = 0x08000000, BUTTON5 = 0x10000000,
  BUTTON6 = 0x20000000, BUTTON7 = 0x40000000, ANY_BUTTON = 0xff000000, ACCELERATOR = ALT,
enum  {
unsigned BUTTON (int n)
int event ()
int event_x ()
int event_y ()
int event_dx ()
int event_dy ()
int event_x_root ()
int event_y_root ()
int event_clicks ()
void event_clicks (int i)
bool event_is_click ()
void event_is_click (bool)
unsigned event_state ()
bool event_state (unsigned i)
unsigned event_key ()
unsigned event_button ()
bool event_key_state (unsigned)
const char * event_text ()
unsigned event_length ()
unsigned event_key_repeated ()
float event_pressure ()
float event_x_tilt ()
float event_y_tilt ()
int event_device ()
bool event_inside (const Rectangle &)
bool compose (int &del)
void compose_reset ()
bool try_shortcut ()
const char * key_name (unsigned key)
unsigned key (const char *name)
unsigned foreachShortcut (const Widget *, ShortcutFunctor &)
unsigned foreachShortcut (ShortcutFunctor &f)
bool get_key_state (unsigned)
void get_mouse (int &, int &)
bool warp_mouse (int, int)
bool handle (int, Window *)
void add_event_handler (int(*h)(int, Window *))
Widgetbelowmouse ()
void belowmouse (Widget *)
void belowmouse (Widget &w)
Widgetpushed ()
void pushed (Widget *)
void pushed (Widget &w)
Widgetfocus ()
void focus (Widget *)
void focus (Widget &w)
void copy (const char *stuff, int len, bool clipboard=false)
void paste (Widget &receiver, bool clipboard=false)
bool dnd ()
void modal (Widget *, bool grab=false)
Widgetmodal ()
bool grab ()
void exit_modal ()
bool exit_modal_flag ()
const char * event_name (int event)
 return the corresponding str of an event, should not consume memory if api is not used


Some functions to manipulate filenames, to make portable programs.
typedef int( FileSortF )(const dirent *const *, const dirent *const *)
int fltk_stat (const char *name, struct stat *buffer)
int filename_absolute (char *to, int tolen, const char *from, const char *cwd=0)
int filename_relative (char *to, int tolen, const char *from, const char *cwd=0)
const char * filename_name (const char *)
char * filename_name (char *a)
const char * filename_ext (const char *)
char * filename_ext (char *a)
bool filename_match (const char *, const char *pattern)
bool filename_exist (const char *)
bool filename_isdir (const char *)
bool filename_isfile (const char *)
FL_FILESIZE_T filename_size (const char *)
long int filename_mtime (const char *)
int alphasort (const dirent *const *, const dirent *const *)
int casealphasort (const dirent *const *, const dirent *const *)
int casenumericsort (const dirent *const *, const dirent *const *)
int numericsort (const dirent *const *, const dirent *const *)
int modificationsort (const dirent *const *, const dirent *const *)
int filename_list (const char *d, dirent ***list, FileSortF *sort)
int filename_list (const char *d, dirent ***list)


enum  { ,
  ALIGN_TOP = 0x00000001, ALIGN_BOTTOM = 0x00000002, ALIGN_LEFT = 0x00000004, ALIGN_RIGHT = 0x00000008,
  ALIGN_CENTER = 0x00000010, ALIGN_INSIDE = 0x00000020, ALIGN_CLIP = 0x00000040, ALIGN_WRAP = 0x00000080,
  STATE = 0x00000400, SELECTED = 0x00000800, INVISIBLE = 0x00001000, HIGHLIGHT = 0x00002000,
  CHANGED = 0x00004000, COPIED_LABEL = 0x00008000, RAW_LABEL = 0x00010000, LAYOUT_VERTICAL = 0x00020000,
  TAB_TO_FOCUS = 0x00040000, CLICK_TO_FOCUS = 0x00080000, INACTIVE_R = 0x00100000, FOCUSED = 0x00200000,
  PUSHED = 0x00400000, RESIZE_NONE = 0, RESIZE_FIT = 0x01000000, RESIZE_FILL = 0x00800000,
typedef unsigned Flags
typedef Flags Align


WindowPtr quartz_window
CGContextRef quartz_gc
Handle system_menu
class SystemMenuBarsystem_menu_bar = 0
void open_display ()
void close_display ()
void open_callback (void(*cb)(const char *name))
void clip_region (RgnHandle)
RgnHandle clip_region ()
void draw_into (CGContextRef xid, int w, int h)
void stop_drawing (CGImageRef xid)
HFONT xfont ()
void clear_quartz_clipping ()
void begin_quartz_image (CGRect &, const Rectangle &)
void end_quartz_image ()


enum  PixelType {
  MASK = 0, MONO = 1, RGBx = 2, RGB = 3,
  RGBA = 4, RGB32 = 5, ARGB32 = 6, RGBM = 7,
  MRGB32 = 8
int depth (PixelType t)


const char *const help = helpmsg+13
int damage_
void(* idle )()
typedef void(* TimeoutHandler )(void *)
typedef void(* FileHandler )(int fd, void *)
void display (const char *)
int arg (int, char **, int &)
int args (int, char **, int &, int(*)(int, char **, int &)=0)
void args (int, char **)
bool enable_tablet_events ()
int wait ()
int wait (float time)
int check ()
int ready ()
int run ()
void flush ()
void redraw ()
void damage (int d)
int damage ()
double get_time_secs ()
void add_timeout (float t, TimeoutHandler, void *v=0)
void repeat_timeout (float t, TimeoutHandler, void *=0)
bool has_timeout (TimeoutHandler, void *=0)
void remove_timeout (TimeoutHandler, void *=0)
void add_check (TimeoutHandler, void *=0)
bool has_check (TimeoutHandler, void *=0)
void remove_check (TimeoutHandler, void *=0)
void add_idle (TimeoutHandler, void *=0)
bool has_idle (TimeoutHandler, void *=0)
void remove_idle (TimeoutHandler, void *=0)
void set_idle (void(*cb)())
void add_fd (int fd, int when, FileHandler, void *=0)
void add_fd (int fd, FileHandler, void *=0)
void remove_fd (int, int when=-1)
FILE * fltk_fopen (const char *name, const char *flags)
void lock ()
void unlock ()
void awake (void *message=0)
void * thread_message ()
bool in_main_thread ()


home ben fltk clean fltk Box h
typedef Symbol 
Box *const UP_BOX = &upBox
Box *const DOWN_BOX = &downBox
Box *const DEFAULT_FOCUS_BOX = &defaultFocusBox
Box *const THIN_UP_BOX = &thinUpBox
Box *const THIN_DOWN_BOX = &thinDownBox
Box *const ENGRAVED_BOX = &engravedBox
Box *const EMBOSSED_BOX = &embossedBox
Box *const BORDER_BOX = &borderBox
Box *const FLAT_BOX = &flatBox
Box *const HIGHLIGHT_UP_BOX = &highlightUpBox
Box *const HIGHLIGHT_DOWN_BOX = &highlightDownBox
Box *const ROUND_UP_BOX = &roundUpBox
Box *const ROUND_DOWN_BOX = &roundDownBox
Box *const DIAMOND_UP_BOX = &diamondUpBox
Box *const DIAMOND_DOWN_BOX = &diamondDownBox
Box *const NO_BOX = &noBox
Box *const SHADOW_BOX = &shadowBox
Box *const ROUNDED_BOX = &roundedBox
Box *const RSHADOW_BOX = &rshadowBox
Box *const RFLAT_BOX = &rflatBox
Box *const OVAL_BOX = &ovalBox
Box *const OSHADOW_BOX = &ovalShadowBox
Box *const OFLAT_BOX = &ovalFlatBox
Box *const BORDER_FRAME = &borderFrame
Box *const PLASTIC_UP_BOX = &plasticUpBox
Box *const PLASTIC_DOWN_BOX = &plasticDownBox
Font *const HELVETICA = &(fonts[0].f)
Font *const HELVETICA_BOLD = &(fonts[1].f)
Font *const HELVETICA_ITALIC = &(fonts[2].f)
Font *const HELVETICA_BOLD_ITALIC = &(fonts[3].f)
Font *const COURIER = &(fonts[4].f)
Font *const COURIER_BOLD = &(fonts[5].f)
Font *const COURIER_ITALIC = &(fonts[6].f)
Font *const COURIER_BOLD_ITALIC = &(fonts[7].f)
Font *const TIMES = &(fonts[8].f)
Font *const TIMES_BOLD = &(fonts[9].f)
Font *const TIMES_ITALIC = &(fonts[10].f)
Font *const TIMES_BOLD_ITALIC = &(fonts[11].f)
Font *const SYMBOL_FONT = &(fonts[12].f)
Font *const SCREEN_FONT = &(fonts[13].f)
Font *const SCREEN_BOLD_FONT = &(fonts[14].f)
Font *const ZAPF_DINGBATS = &(fonts[15].f)
LabelType *const NO_LABEL = &noLabel
LabelType *const NORMAL_LABEL = &normalLabel
LabelType *const SYMBOL_LABEL = &normalLabel
LabelType *const SHADOW_LABEL = &shadowLabel
LabelType *const ENGRAVED_LABEL = &engravedLabel
LabelType *const EMBOSSED_LABEL = &embossedLabel
Theme theme_ = fltk_theme
typedef bool(* Theme )()
Theme theme ()
void theme (Theme f)
void load_theme ()
void reload_theme ()
bool reset_theme ()


typedef pthread_t Thread
int create_thread (Thread &t, void *(*f)(void *), void *p)


bool visual (int)
bool glVisual (int)
void own_colormap ()


HPALETTE xpalette
MSG msg
HDC dc
COLORREF current_xpixel
HDC getDC ()
TEXTMETRICW * textmetric ()
COLORREF xpixel (Color i)
HPEN setpen ()
HBRUSH setbrush ()
void clip_region (HRGN)
void draw_into (HBITMAP, int w, int h)
void stop_drawing (HBITMAP)
void stop_drawing (HWND)


XWindow message_window
int xscreen
XVisualInfo * xvisual
Colormap xcolormap
XEvent xevent
ulong event_time
XWindow dnd_source_window
Atom * dnd_source_types
Atom dnd_type
Atom dnd_source_action
Atom dnd_action
XftDraw * xftc
GC gc
XWindow xwindow
void open_display (Display *)
bool handle ()
void clip_region (Region)
void draw_into (XWindow, int w, int h)
void stop_drawing (XWindow)
XftFont * xftfont ()
XWindow xid (const Window *w)
Windowfind (XWindow xid)

Detailed Description

Typedef Documentation

typedef Flags fltk::Align

For back compatability with fltk1.1

typedef void( fltk::Callback)(Widget *, void *)

Callback is a function pointer to a fltk callback mechanism. It points to any function void foo(Widget*, void*)

typedef void( fltk::Callback0)(Widget *)

Function pointer to a callback with only one argument, the widget

typedef void( fltk::Callback1)(Widget *, long)

Function pointer to a callback with a long argument instead of a void argument

A pointer to a Callback. Needed for BORLAND

fltk::Color is a typedef for a 32-bit integer containing r,g,b bytes and an "index" in the lowest byte (the first byte on a little-endian machine such as an x86). For instance 0xFF008000 is 255 red, zero green, and 128 blue. If rgb are not zero then the low byte is ignored, or may be treated as "alpha" by some code.

If the rgb is zero, the N is the color "index". This index is used to look up an fltk::Color in an internal table of 255 colors shown here. All the indexed colors may be changed by using set_color_index(). However fltk uses the ones between 32 and 255 and assummes they are not changed from their default values.


(this is not the X colormap used by fltk)

A Color of zero (fltk::NO_COLOR) will draw black but is ambiguous. It is returned as an error value or to indicate portions of a Style that should be inherited, and it is also used as the default label color for everything so that changing color zero can be used by the -fg switch. You should use fltk::BLACK (56) to get black.

Type of function passed to drawimage(). It must return a pointer to a horizontal row of w pixels, starting with the pixel at x and y (relative to the top-left corner of the image, not to the coordinate space drawimage() is called in). These pixels must be in the format described by type passed to drawimage() and must be the delta apart passed to drawimage().

userdata is the same as the argument passed to drawimage(). This can be used to point at a structure of information about the image.

Due to cropping, less than the whole image may be requested. So the callback may get an x greater than zero, the first y passed to it may be greater than zero, and x+w may be less than the width of the image. The passed buffer contains room for at least the number of pixels specified by the width passed to drawimage(). You can use this as temporary storage to construct a row of the image, and return a pointer offset by x into it.

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

Type of function passed to add_fd()

typedef unsigned fltk::Flags

Type returned by fltk::Widget::flags() and passed to fltk::Box and many other drawing functions.

typedef const char*( fltk::HelpFunc)(Widget *, const char *)

HelpFunc type - link callback function for files...

A Theme is a function called by fltk just before it shows the first window, and also whenever it receives a signal from the operating system that the user's preferences have changed.

The Theme's job is to set all the NamedStyle structures to the correct values for the appearance selected by the user and operating system.

The return value is ignored but you should return true for future compatability.

This pointer is declared as a "C" function to make it easier to load the correct function by name from a plugin, if you would like to write a scheme where the appearance is controlled by plugins. Fltk provides a convienence function to portably load plugins called fltk::load_plugin() that you may want to use if you are writing such a system.

typedef pthread_t fltk::Thread

Hides whatever the system uses to identify a thread. Used so the "toy" interface is portable.

typedef void(* fltk::TimeoutHandler)(void *)

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

Enumeration Type Documentation

anonymous enum

Numbers passed to Widget::handle() and returned by event().


Has the value zero. All fltk widgets return false if this is passed to their handle() method.

Fltk will produce this for unrecognized X events, if it can figure out what window to send them to. You can then subclass Window and add a handler for these events. Unfortunately this is not done on Windows due to the enormous number of garbage messages a program gets, you should instead use Windows pre-filtering functions to look for unknown messages.


A mouse button has gone down with the mouse pointing at this widget. You can find out what button by calling fltk::event_button(). You find out the mouse position by calling fltk::event_x() and fltk::event_y(). These positions are relative to the corner of the widget whose handle() method is being called.

A widget indicates that it "wants" the mouse click by returning non-zero from its handle() method. It will then become the fltk::pushed() widget (this is done by the enclosing group widget) and will get fltk::DRAG and the matching fltk::RELEASE events.


A mouse button has been released. You can find out what button by calling fltk::event_button().

To receive fltk::RELEASE events you must return non-zero when passed a fltk::PUSH event.


The mouse has been moved to point at this widget. This can be used for highlighting feedback. If a widget wants to highlight or otherwise track the mouse, it indicates this by returning non-zero from its handle() method. It then becomes the fltk::belowmouse() widget and will receive fltk::MOVE and fltk::LEAVE events.


The mouse has moved out of the widget. To get this event you must return 1 in response to a fltk::ENTER event.


The mouse has moved with a button held down. The current button state is in fltk::event_state(). The mouse position, relative to this widget, is in fltk::event_x() and fltk::event_y().

To receive fltk::DRAG events you must return non-zero when passed a fltk::PUSH event.


This indicates an attempt to give a widget the keyboard focus.

If a widget wants the focus, it should change itself to display the fact that it has the focus, and return non-zero from its handle() method. It then becomes the fltk::focus() widget and gets fltk::KEY, fltk::KEYUP and fltk::UNFOCUS events.

The focus will change either because the window manager changed which window gets the focus, or because the user tried to navigate using tab, arrows, or other keys. You can check fltk::event_key() to figure out why it moved, for navigation it will be the key pressed and for switching windows it will be zero.


Sent to the previous fltk::focus() widget when another widget gets the focus.


A key press event. Fltk sends these directly to the fltk::focus() widget. If it returns zero then fltk will change the event into fltk::SHORTCUT and try the widgets under the mouse.

The key pressed can be found in fltk::event_key(). The text that the key should insert can be found with fltk::event_text() and its length is in fltk::event_length().

If you are actually doing text editing, you should use fltk::compose() to process the individual keystrokes into I18N characters.


Sent to the fltk::focus() widget. The key that was released can be found in fltk::event_key() (fltk::event_text() is not set).


Sent to all parents of the new fltk::focus() widget when the focus changes. This can be used to record which child has focus so it can be restored later, or to scroll a view to show the focus.


The mouse has moved without any mouse buttons held down. This event is sent to the fltk::belowmouse() widget.


If the fltk::focus() widget is zero or it returns zero for an fltk::KEY event then FLTK tries sending this event to every widget it can, until one of them returns non-zero. fltk::SHORTCUT is first sent to the belowmouse() widget, then its parents and siblings, and eventually to every widget in the window, trying to find an object that returns non-zero. FLTK tries really hard to not to ignore any keystrokes!

You can also make "global" shortcuts by using fltk::add_handler(). A global shortcut will work no matter what windows are displayed or which one has the focus.


The method Widget::deactivate() has been called on this widget or one of its parents. The function Widget::active_r() will now return false.


The method Widget::activate() has been called on this widget or one of its parents. The function Widget::active_r() will now return true.


This widget is no longer visible, due to Widget::hide() being called on it or one of its parents, or due to a parent window being minimized. The function Widget::visible_r() will now return false.

If you implement a widget class it is important to call your base class with this same event. Fltk relies on this to communicate the visibility of widgets that are windows to the system.


This widget is visible, due to Widget::show() being called on it or one of its parents, or due to a parent window being restored from minimized state. The function Widget::visible_r() will now return true.

If you implement a widget class it is important to call your base class with this same event. Fltk relies on this to communicate the visibility of widgets that are windows to the system.


You should get this event some time after you call fltk::paste() or you return true for fltk::DND_RELEASE. The contents of fltk::event_text() is the text to insert and the number of characters is in fltk::event_length().


This event is generated if you called Widget::add_timeout().


The wheel was moved on the mouse. fltk::event_dy() contains how many clicks the wheel moved, positive for up and negative for down. There is also a fltk::event_dx() for any kind of horizontal scrolling device but nothing produces that yet.


The user is dragging something over your widget. Return 1 if you are interested in getting fltk::DND_DRAG and fltk::DND_RELEASE events.

It is impossible to examine the text of the drag until you release it. There are system-specific variables that can be examined to determine the type of drag being done, but unless you are making a file-management application that wants to delete or rename the source files, you should not need this information.


The user moved the mouse some more while dragging something. You might use this to move around a cursor indicating where the insertion will go.


The user moved out of the widget without releasing the dragged object.


The user let go of the mouse and dropped something on your widget. Return 1 if you are interested in getting this data. In this case you will get an fltk::PASTE event with the text of object. This is usually a URL string, such as a filename with "file:" on the start. All fltk widgets just insert the data as text into text editors.


NYI. Sent when the mouse hovers over the widget long enough for it to pop up a tooltip. The base class handle() actually pops up the tooltip.

anonymous enum

Values returned by event_key(), passed to event_key_state() and get_key_state(), and used for the low 16 bits of add_shortcut().

The actual values returned are based on X11 keysym values, though fltk always returns "unshifted" values much like Windows does. A given key always returns the same value no matter what shift keys are held down. Use event_text() to see the results of any shift keys.

The lowercase letters 'a' through 'z' and the ascii symbols '`', '-', '=', '[', ']', '\', ',', '.', '/', ';', '\'' and space are used to identify the keys in the main keyboard.

On X systems unrecognized keys are returned unchanged as their X keysym value. If they have no keysym it uses the scan code or'd with 0x8000, this is what all those blue buttons on a Microsoft keyboard will do. I don't know how to get those buttons on Windows.


PUSH/RELEASE sets event_key to this


PUSH/RELEASE sets event_key to this


PUSH/RELEASE sets event_key to this


MOUSEWHEEL sets event_key to this


MOUSEWHEEL sets event_key to this


MOUSEWHEEL sets event_key to this


MOUSEWHEEL sets event_key to this


Same as ' ' or 32






On some systems with NumLock off '5' produces this


Main Enter key, Windows and X documentation calls this "Return"


Pause + Break button


Scroll Lock button








Up arrow


Right arrow


Down arrow


Page Up


Page Down




Print Scrn key + SysRq key




Key in lower-right with picture of popup menu


Help key on Macintosh keyboards


NumLock key


Add ASCII to get keypad keys


































Keypad+'=', largest legal keypad key


Add a number to get function key


























F0Key+35, largest legal function key


Left-hand Shift


Right-hand Shift


Left-hand Ctrl


Right-hand Ctrl


Caps Lock


The left "Windows" or "Apple" key


The right "Windows" or "Apple" key


Left-hand Alt (option on Mac)


Right-hand Alt (option on Mac)



anonymous enum

Flags returned by event_state(), and used as the high 16 bits of Widget::add_shortcut() values (the low 16 bits are all zero, so these may be or'd with key values).

The inline function BUTTON(n) will turn n (1-8) into the flag for a mouse button.


Either shift key held down


Caps lock is toggled on


Either ctrl key held down


Either alt key held down


Num Lock turned on


"Windows" or the "Apple" keys held down


Scroll Lock turned on


Left mouse button held down


Middle mouse button held down


Right mouse button held down


Mouse wheel scroll up


Mouse wheel scroll down


Mouse wheel scroll left


Mouse wheel scroll right


Any mouse button (up to 8)


ALT on Windows/Linux, CTRL on OS/X, use for menu accelerators.


CTRL on Windows/Linux, META on OS/X, use for menu shortcuts.


ALT|META on Windows/Linux, just ALT on OS/X, use as a drag modifier.

anonymous enum

Device identifier returned by event_device(). This enumeration is useful to get the device type that caused a PUSH, RELEASE, DRAG or MOVE event


Event triggered by the system mouse


Event triggered by a pen on a tablet, givin pressure and tilt information


Event triggered by an eraser on a tablet, givin pressure and tilt information


Event triggered by a puck style device on a tablet


Event triggered by an airbrush on a tablet, giving pressure and tilt information


Event triggered by touch a touch screen device

anonymous enum

Label is centered above widget.


Label is centered below widget.


Label is to left of widget.


Label is to right of widget.


(0) The label is centered inside widget


Label is inside widget, image centered.


The label is clipped to the widget.


The label is word-wrapped.


Used to split align() from flags()


Used to split align() from flags()


Label is left-justified above widget.


Label is left-justified below widget.


Label is right-justified above widget.


Label is right-justified below widget.


Label is centered in space left of widget.


Label is centered in space left of widget.


Label is inside widget at top.


Label is inside widget at bottom.


Label is inside widget at left.


Label is inside widget at top left.


Label is inside widget at bottom left.


Label is inside widget at right.


Label is inside widget at top right.


Label is inside widget bottom right.


Label is inside widget bottom right.


Label is inside widget bottom right.




does not get events, draw text colors


state(), value() for buttons


chosen in browser/menu, draw selected colors


!visible(), draw_frame()


draw highlighted


value changed since last callback


copy_label() was called


don't interpret & or @ in label


fltk::Pack puts this widget vertical






draw it grayed-out


draw with keyboard focus


draw pushed-in


default behavior


proportionnaly resize img in widget


resize img to fill the widget


opened browser hierarchy parent

anonymous enum

Values of the bits stored in Widget::layout_damage().

When a widget resized or moved (or when it is initially created), flags are set in Widget::layout_damage() to indicate the layout is damaged. This will cause the virtual function Widget::layout() to be called just before fltk attempts to draw the windows on the screen. This is useful because often calculating the new layout is quite expensive, this expense is now deferred until the user will actually see the new size.

Some Group widgets such as fltk::PackedGroup will also use the virtual Widget::layout() function to find out how big a widget should be. A Widget is allowed to change it's own dimensions in layout() (except it is not allowed to change it if called a second time with no changes other than it's x/y position). This allows widgets to resize to fit their contents.

The layout bits are turned on by calling Widget::relayout().


Widget::x() changed by resize()


Widget::y() changed by resize()




Widget::w() changed by resize()


Widget::h() changed by resize()






Widget::layout() needs to be called on a child of this group widget.


The moving/resizing is being caused by the user and not internal code.


Widget::relayout() was called.

anonymous enum

Widget::when() values


Never triggers the callback


Triggers the callback when the data has changed


Triggers the callback when the data has changed and the mouse button has been released


Triggers the callback when the mouse button has been released, regardless of the data's state


Triggers the callback when the user hits the Enter key and the data has changed


Triggers the callback when the user hits the Enter key, regardless of the data's state


Triggers the callback either when the data has changed or the user hits the Enter key


Modifier bit to disable changed() test

anonymous enum

Symbolic names for some of the indexed colors.

The 24-entry "gray ramp" is modified by fltk::set_background() so that the color fltk::GRAY75 is the background color, and the others are a nice range from black to a lighter version of the gray. These are used to draw box edges. The gray levels are chosen to be evenly spaced, listed here is the actual 8-bit and decimal gray level assigned by default. Also listed here is the letter used for fltk::FrameBox and the old fltk1.1 names used for these levels.

The remiander of the colormap is a 5x8x5 color cube. This cube is used to dither images on 8-bit screens X colormaps to reduce the number of colors used.


Black, empty place holder in Style.


Starting from index 16 is the FREE_COLOR area.


Number of free color slots starting from index FREE_COLOR.


hex=00, dec=.00, framebox=A, fltk1 = GRAY0, GRAY_RAMP


hex=0d, dec=.05, framebox=B


hex=1a, dec=.10, framebox=C


hex=27, dec=.15, framebox=D


hex=34, dec=.20, framebox=E


hex=41, dec=.25, framebox=F


hex=4f, dec=.31, framebox=G


hex=5c, dec=.36, framebox=H, fltk1 = DARK3


hex=69, dec=.41, framebox=I


hex=76, dec=.46, framebox=J (18% gray card)


hex=83, dec=.51, framebox=K


hex=90, dec=.56, framebox=L


hex=9e, dec=.62, framebox=M


hex=ab, dec=.67, framebox=N, fltk1 = DARK2


hex=b8, dec=.72, framebox=O


hex=c5, dec=.77, framebox=P, fltk1 = DARK1, INACTIVE_COLOR


hex=d2, dec=.82, framebox=Q


hex=e0, dec=.88, framebox=R, fltk1 = GRAY, SELECTION_COLOR


hex=e5, dec=.90, framebox=S


hex=ea, dec=.92, framebox=T, fltk1 = LIGHT1


hex=f4, dec=.96, framebox=V, fltk1 = LIGHT2


hex=f9, dec=.98, framebox=W


hex=ff, dec=1.0, framebox=X, fltk1 = LIGHT3


Corner of color cube.


Corner of color cube.


Corner of color cube.


Corner of color cube.


Corner of color cube.


Corner of color cube.


Corner of color cube.


Corner of color cube.


default selection_color

anonymous enum

Values of the bits stored in Widget::damage().

When redrawing your widgets you should look at the damage bits to see what parts of your widget need redrawing. The Widget::handle() method can then set individual damage bits to limit the amount of drawing that needs to be done, and the Widget::draw() method can test these bits to decide what to draw:

MyClass::handle(int event) {
  if (change_to_part1) damage(1);
  if (change_to_part2) damage(2);
  if (change_to_part3) damage(4);

MyClass::draw() {
  if (damage() & fltk::DAMAGE_ALL) {
    ... draw frame/box and other static stuff ...
  if (damage() & (fltk::DAMAGE_ALL | 1)) draw_part1();
  if (damage() & (fltk::DAMAGE_ALL | 2)) draw_part2();
  if (damage() & (fltk::DAMAGE_ALL | 4)) draw_part3();

Except for DAMAGE_ALL, each widget is allowed to assign any meaning to any of the bits it wants. The enumerations are just to provide suggested meanings.


A widget may use this to indicate that the displayed value has changed.


A widget may use this to indicate that the user has pushed or released a button.


A widget may use this to indicate that the displayed data has scrolled moved horizontally and/or vertically.


Same value as fltk::DAMAGE_SCROLL.


A widget may use this to indicate that the mouse has entered/exited part of the widget.


A child of this group widget needs to be redrawn (non-group widgets can use this bit for their own purposes).


An outside label of this widget needs to be redrawn. This is handled (and this bit is cleared) by the parent group.

Because anti-aliasing cannot be redrawn atop itself, this is not used anymore. Instead if an outside label needs to change the entire parent widget is redrawn.


Damage caused by damage() or by expose events from the operating system. If this and fltk::DAMAGE_ALL is on the widget should draw every pixel inside it's region.


Same as fltk::DAMAGE_EXPOSE but if fltk::DAMAGE_ALL is off a widget can use this for it's own purposes.


This bit is set by redraw() and indicates that all of the widget (but not "holes" where the background shows through) needs to be redraw.

Enumeration describing how colors are stored in an array of bytes that is a pixel. This is used as an argument for fltk::drawimage(), fltk::readimage(), and fltk::Image.

Notice that the order of the bytes in memory of ARGB32 or RGB32 is a,r,g,b on a little-endian machine and b,g,r,a on a big-endian machine. Due to the use of these types by Windows, this is often the fastest form of data, if you have a choice. To convert an fltk::Color to RGB32, shift it right by 8 (for ARGB32 shift the alpha left 24 and or it in).

More types may be added in the future. The set is as minimal as possible while still covering the types I have actually encountered.


1 byte of inverted mask, filled with current color


1 byte of gray scale


bytes in r,g,b,a,r,g,b,a... order, a byte is ignored


bytes in r,g,b,r,g,b... order


bytes in r,g,b,a,r,g,b,a... order


32-bit words containiing 0xaarrggbb (aa is ignored)


32-bit words containing 0xaarrggbb


unpremultiplied bytes in r,g,b,a order


unpremultiplied 0xaarrggbb

Function Documentation

void fltk::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;

main() {
  return fltk::run();
void fltk::add_event_handler ( int(*)(int, Window *)  h)

Install a function to parse unrecognized events. If FLTK cannot figure out what to do with an event, it calls each of these functions (most recent first) until one of them returns non-zero. If none of them returns non zero then the event is ignored.

Currently this is called for these reasons:

  • If there is a keystroke that no widgets are interested in, this is called with fltk::SHORTCUT. You can use this to implement global hotkeys.
  • Unrecognized X events cause this to be called with NO_EVENT. The Window parameter is set if fltk can figure out the target window and it is an fltk one. You can then use system specific code to access the event data and figure out what to do. This is not done on Windows due to the enormous number of garbage messages a program gets, you should instead use Windows pre-filtering functions to look at these.
  • Events it gets with a window id it does not recognize cause this to be called, with the Window parameter set to null. This can only happen on X, on Windows any unknown windows should have their own message handling function that does not call fltk.
  • This may be called with other event types when the widget fltk wants to send it to returns zero. However the exact rules when this happens may change in future versions.
void fltk::add_fd ( int  n,
int  events,
FileHandler  cb,
void *  v = 0 

Add file descriptor fd to listen to. When the fd becomes ready for reading fltk::wait() will call the callback function and then return. The callback is passed the fd and the arbitrary void* argument.

The second argument is a bitfield to indicate when the callback should be done. You can or these together to make the callback be called for multiple conditions:

  • fltk::READ - Call the callback when there is data to be read.
  • fltk::WRITE - Call the callback when data can be written without blocking.
  • fltk::EXCEPT - Call the callback if an exception occurs on the file.

Under UNIX any file descriptor can be monitored (files, devices, pipes, sockets, etc.) Due to limitations in Microsoft Windows, WIN32 applications can only monitor sockets (? and is the when value ignored?)

void fltk::add_fd ( int  fd,
FileHandler  cb,
void *  v = 0 

Same as add_fd(fd, READ, cb, v);

void fltk::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.

void fltk::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 fltk::addarc ( float  l,
float  t,
float  w,
float  h,
float  start,
float  end 

Add a series of points to the current path on the arc of an ellipse. The ellipse in inscribed in the l,t,w,h rectangle, and the start and end angles are measured in degrees counter-clockwise from 3 o'clock, 45 points at the upper-right corner of the rectangle. If end is less than start then it draws the arc in a clockwise direction.

void fltk::addchord ( const Rectangle r,
float  start,
float  end 

Add an isolated circular arc to the path. It is inscribed in the rectangle so if it is stroked with the default line width it exactly fills the rectangle (this is slightly smaller than addarc() will draw). If the angles are 0 and 360 a closed circle is added.

This tries to take advantage of the primitive calls provided by Xlib and GDI32. Limitations are that you can only draw one, a rotated current transform does not work.

void fltk::addcurve ( float  x0,
float  y0,
float  x1,
float  y1,
float  x2,
float  y2,
float  x3,
float  y3 

Add a series of points on a Bezier spline to the path. The curve ends (and two of the points) are at x,y and x3,y3. The "handles" are at x1,y1 and x2,y2.

void fltk::addpie ( const Rectangle r,
float  start,
float  end 

Add a pie-shaped closed piece to the path, inscribed in the rectangle so if it is stroked with the default line width it exactly fills the rectangle (this is slightly smaller than addarc() will draw). If you want a full circle use addchord().

This tries to take advantage of the primitive calls provided by Xlib and GDI32. Limitations are that you can only draw one per path, that rotated coordinates don't work, and doing anything other than fillpath() will produce unpredictable results.

See also:
void fltk::addvertex ( float  X,
float  Y 

Add a single vertex to the current path. (if the path is empty or a closepath() was done, this is equivalent to a "moveto" in PostScript, otherwise it is equivalent to a "lineto").

void fltk::addvertex ( int  X,
int  Y 

This integer version is provided because it is much faster than the floating-point version. However C++ will not "resolve" which one you want to call if you try passing doubles as arguments. To get it to compile, make sure you cast the arguments to float (add 'f' after floating-point constants). Use the 'f' versions (ie sinf(), cosf(), etc) of the math functions from <fltk/math.h> to produce floats and get maximum calculation speed.

void fltk::addvertices ( int  n,
const int  array[][2] 

Add a whole set of integer vertices to the current path.

void fltk::addvertices ( int  n,
const float  array[][2] 

Add a whole set of vertices to the current path. This is much faster than calling fltk::addvertex once for each point.

void fltk::addvertices_transformed ( int  n,
const float  array[][2] 

Adds a whole set of vertcies that have been produced from values returned by fltk::transform(). This is how curve() and arc() are implemented.

void fltk::alert ( const char *  fmt,

Same as fltk::message() except for the "!" symbol.

int fltk::arg ( int  argc,
char **  argv,
int &  i 

Consume a single switch from argv, starting at word i. Returns the number of words eaten (1 or 2, or 0 if it is not recognized) and adds the same value to i. You can use this function if you prefer to control the incrementing through the arguments yourself. The arguments recognized are listed under args().

The args() argument parser is entirely optional. It was written to make demo programs easy to write, although some minor work was done to make it usable by more complex programs. But there is no requirement that you call it or even acknoledge it's existence, if you prefer to use your own code to parse switches.

void fltk::args ( int  argc,
char **  argv 

The second form of fltk::args() is useful if your program does not have command line switches of its own. It parses all the switches, and if any are not recognized it calls fltk::fatal(fltk::help).

int fltk::args ( int  argc,
char **  argv,
int &  i,
int(*)(int, char **, int &)  cb = 0 

Consume all switches from argv.

To use the switch parser, call fltk::args(argc,argv) near the start of your program. This does not open the display, instead switches that need the display open are stashed into static variables. Then you must display your first window by calling window->show(argc,argv), which will do anything stored in the static variables.

callback lets you define your own switches. It is called with the same argc and argv, and with i the index of each word. The callback should return zero if the switch is unrecognized, and not change i. It should return non-zero if the switch is recognized, and add at least 1 to i (it can add more to consume words after the switch). This function is called before any other tests, so you can override any FLTK switch (this is why fltk can use very short switches instead of the long ones all other toolkits force you to use).

On return i is set to the index of the first non-switch. This is either:

  • The first word that does not start with '-'.
  • The word "-" (used by many programs to name stdin as a file)
  • The first word after "--" (GNU standard end-of-switches switch)
  • The first unrecognized switch (return value is 0).
  • argc

The return value is i unless an unrecognized switch is found, in which case it is zero. If your program takes no arguments other than switches you should produce an error if the return value is less than argc.

All switches may be abbreviated one letter and case is ignored:

  • -iconic Window::iconize() will be done to the window.
  • -geometry WxH Window is resized to this width & height
  • -geometry +X+Y Initial window position
  • -geometry WxH+X+Y Window is resized and positioned.
  • -display host or -display host:n.n The X display to use (ignored under WIN32).
  • -name string will set the Window::label()
  • -bg color Call set_background() with the named color. Use "#rrggbb" to set it in hex.
  • -background color is the same as -bg color
int fltk::ask ( const char *  fmt,

Displays a printf-style message in a pop-up box with an "Yes" and "No" button and waits for the user to hit a button. The return value is 1 if the user hits Yes, 0 if they pick No. The enter key is a shortcut for Yes and ESC is a shortcut for No.

If message_window_timeout is used, then -1 will be returned if the timeout expires.

void fltk::awake ( void *  message = 0)

A child thread can call this to cause the main thread's call to wait() to return (with the lock locked) even if there are no events ready. The main purpose of this is to get the main thread to redraw the screen, but it will also cause fltk::wait() to return so the program's code can do something.

You should call this immediately before fltk::unlock() for best performance.

The message argument can be retrieved by the other thread using fltk::thread_message().

void fltk::beep ( int  type = BEEP_DEFAULT)

Generates a simple beep message

void fltk::beep_on_dialog ( bool  b)

You can enable beep on default message dialog (like ask, choice, input, ...) by using this function with true (default is false)

bool fltk::beep_on_dialog ( )

You get the state enable beep on default message dialog (like ask, choice, input, ...) by using this function with true (default is false)

Widget * fltk::belowmouse ( ) [inline]

Get the widget that is below the mouse. This is the last widget to respond to an fltk::ENTER event as long as the mouse is still pointing at it. This is for highlighting buttons and bringing up tooltips. It is not used to send fltk::PUSH or fltk::MOVE directly, for several obscure reasons, but those events typically go to this widget.

void fltk::belowmouse ( Widget o)

Change the fltk::belowmouse() widget, the previous one and all parents (that don't contain the new widget) are sent fltk::LEAVE events. Changing this does not send fltk::ENTER to this or any widget, because sending fltk::ENTER is supposed to test if the widget wants the mouse (by it returning non-zero from handle()).

int 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()) {
  if (user_hit_abort_button()) break;
int fltk::choice ( const char *  fmt,
const char *  b0,
const char *  b1,
const char *  b2,

Shows the message with three buttons below it marked with the strings b0, b1, and b2. Returns 0, 1, or 2 depending on which button is hit. If one of the strings begins with the special character '*' then the associated button will be the default which is selected when the enter key is pressed. ESC is a shortcut for b2.

If message_window_timeout is used, then -1 will be returned if the timeout expires.

int fltk::choice_alert ( const char *  fmt,
const char *  b0,
const char *  b1,
const char *  b2,

Same as choice() except a "!" icon is used instead of a "?"

void fltk::clip_region ( Region  r)

Replace the top of the clip stack.

Region fltk::clip_region ( )

Return the current region as a system-specific structure. You must include <fltk/x.h> to use this. Returns null if there is no clipping.

void fltk::clipout ( const Rectangle r1)

Remove rectangle from the current clip region, thus making it a more complex shape. This does not push the stack, it just replaces the top of it.

Some graphics backends (OpenGL and Cairo, at least) do not support non-rectangular clip regions. This call does nothing on those.

Remove the rectangle from the current clip region, thus making it a more complex shape. This does not push the stack, it just replaces the top of it.

Some graphics backends (OpenGL and Cairo, at least) do not support non-rectangular clip regions. This call does nothing on those.

void fltk::close_display ( )

This closes the X connection. You do not need to call this to exit, and in fact it is faster to not do so! It may be useful to call this if you want your program to continue without the X connection. You cannot open the display again, and probably cannot call any FLTK functions.

void fltk::closepath ( )

Similar to drawing another vertex back at the starting point, but fltk knows the path is closed. The next addvertex() will start a new disconnected part of the shape.

It is harmless to call fltk::closepath() several times in a row, or to call it before the first point. Sections with less than 3 points in them will not draw anything when filled.

fltk::Color fltk::color ( const char *  name)

Turn a string into a color. If name is null this returns NO_COLOR. Otherwise it returns fltk::parsecolor(name, strlen(name)).

bool fltk::color_chooser ( const char *  name,
float &  r,
float &  g,
float &  b 

fltk::color_chooser() pops up a window to let the user pick an arbitrary RGB color. They can pick the hue and saturation in the "hue box" on the left (hold down CTRL to just change the saturation), and the brighness using the vertical slider. Or they can type the 8-bit numbers into the RGB fltk::ValueInput fields, or drag the mouse across them to adjust them. The pull-down menu lets the user set the input fields to show RGB, HSV, or 8-bit RGB (0 to 255).

This returns non-zero if the user picks ok, and updates the RGB values. If the user picks cancel or closes the window this returns zero and leaves RGB unchanged.

This version takes and returns numbers in the 0-1 range.

There is also a class fltk::ColorChooser which you can use to imbed a color chooser into another control panel.

bool fltk::color_chooser ( const char *  name,
float &  r,
float &  g,
float &  b,
float &  a 

Same but user can also select an alpha value. Currently the color chips do not remember or set the alpha!

bool fltk::color_chooser ( const char *  name,
uchar &  r,
uchar &  g,
uchar &  b 

Same but it takes and returns 8-bit numbers for the rgb arguments.

bool fltk::color_chooser ( const char *  name,
uchar &  r,
uchar &  g,
uchar &  b,
uchar &  a 

Same but with 8-bit alpha chosen by the user.

bool fltk::color_chooser ( const char *  name,
Color c 

Same but it takes and returns an fltk::Color number. No alpha.

bool fltk::compose ( int &  del)

Use of this function is very simple. Any text editing widget should call this for each fltk::KEY event.

If true is returned, then it has modified the fltk::event_text() and fltk::event_length() to a set of bytes to insert (it may be of zero length!). It will also set the del parameter to the number of bytes to the left of the cursor to delete, this is used to delete the results of the previous call to fltk::compose(). Compose may consume the key, which is indicated by returning true, but both the length and del are set to zero.

Compose returns false if it thinks the key is a function key that the widget should handle itself, and not an attempt by the user to insert text.

Though the current implementation returns immediately, future versions may take quite awhile, as they may pop up a window or do other user-interface things to allow international characters to be selected.

void fltk::compose_reset ( ) [inline]

If the user moves the cursor, be sure to call fltk::compose_reset(). The next call to fltk::compose() will start out in an initial state. In particular it will not set "del" to non-zero. This call is very fast so it is ok to call it many times and in many places.

void fltk::concat ( float  a,
float  b,
float  c,
float  d,
float  x,
float  y 

Multiply the current transformation by

a b 0
c d 0
x y 1
Color fltk::contrast ( Color  fg,
Color  bg 

Returns fg if fltk decides it can be seen well when drawn against bg. Otherwise it returns either fltk::BLACK or fltk::WHITE.

void fltk::copy ( const char *  stuff,
int  len,
bool  clipboard = false 

Change the current selection. The block of text is copied to an internal buffer by FLTK (be careful if doing this in response to an fltk::PASTE as this may be the same buffer returned by event_text()).

The block of text may be retrieved (from this program or whatever program last set it) with fltk::paste().

There are actually two buffers. If clipboard is true then the text goes into the user-visible selection that is moved around with cut/copy/paste commands (on X this is the CLIPBOARD selection). If clipboard is false then the text goes into a less-visible buffer used for temporarily selecting text with the mouse and for drag & drop (on X this is the XA_PRIMARY selection).

int fltk::create_thread ( Thread &  t,
void *(*)(void *)  f,
void *  p 
) [inline]

Fork a new thread and make it run f(p). Returns negative number on error, otherwise t is set to the new thread.

int fltk::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.

int fltk::depth ( PixelType  t) [inline]

Turn a PixelType into the number of bytes needed to hold a pixel.

void fltk::display ( const char *  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.

bool fltk::dnd ( )

Drag and drop the data set by the most recent fltk::copy() (with the clipboard argument false). Returns true if the data was dropped on something that accepted it.

By default only blocks of text are dragged. You can use system-specific variables to change the type of data.

void fltk::draw_into ( XWindow  window,
int  w,
int  h 

Fltk can draw into any X window or pixmap that uses the fltk::xvisual. This will reset the transformation and clip region and leave the font, color, etc at unpredictable values. The w and h arguments must be the size of the window and are used by fltk::not_clipped().

Before you destroy the window or pixmap you must call fltk::stop_drawing() so that it can destroy any temporary structures that were created by this.

Flags fltk::drawflags ( ) [inline]

Return the last flags passed to setdrawflags().

Flags fltk::drawflags ( Flags  f) [inline]

Same as (drawflags() & f), returns true if any of the flags in f are set.

void fltk::drawimage ( const uchar *  pointer,
fltk::PixelType  type,
const Rectangle r 

Same except line_delta is set to r.w() times depth(type), indicating the rows are packed together one after another with no gap.

void fltk::drawimage ( const uchar *  pointer,
fltk::PixelType  type,
const Rectangle r,
int  line_delta 

Draw a image (a rectangle of pixels) stored in your program's memory. The current transformation (scale, rotate) is applied.

  • pointer points at the first byte of the top-left pixel.
  • type describes how to interpret the bytes of each pixel.
  • rectangle: the image is put in the top-left corner and the width and height declare how many pixels the image has.
  • line_delta is how much to add to pointer to go 1 pixel down. By setting line_delta to larger than depth(type)*r.w() you can crop a picture out of a larger buffer. You can also set it negative for images that are stored with bottom-to-top in memory, notice that in this case pointer still points at the top-left pixel, which is at the end of your buffer minus one line_delta.

The X version of FLTK will abort() if the default visual is one it cannot use for images. To avoid this call fltk::visual(fltk::RGB) at the start of your program.

void fltk::drawimage ( DrawImageCallback  cb,
void *  userdata,
fltk::PixelType  type,
const Rectangle r 

Call the passed function to provide each scan line of the image. This lets you generate the image as it is being drawn, or do arbitrary decompression of stored data (provided it can be decompressed to individual scan lines easily).

callback is called with the void* data argument (this can be used to point at a structure of information about the image), the x, y, and number of pixels desired from the image, measured from the upper-left corner of the image. It is also given a buffer of at least w pixels that can be used as temporary storage, for instance to decompress a line read from a file. You can then return a pointer to this buffer, or to somewhere inside it.

The callback must return n pixels of the format described by type.

The xywh rectangle describes the area to draw. The callback is called with y values between 0 and h-1. Due to cropping not all pixels may be asked for. You can assumme y will be asked for in increasing order.

void fltk::drawline ( int  x,
int  y,
int  x1,
int  y1 

Draw a straight line between the two points.

If line_width() is zero, this tries to draw as though a 1x1 square pen is moved between the first centers of pixels to the lower-right of the start and end points. Thus if y==y1 this will fill a rectangle with the corners x,y and x1+1,y+1. This may be 1 wider than you expect, but is necessary for compatability with previous fltk versions (and is due to the original X11 behavior).

If line_width() is not zero then the results depend on the back end. It also may not produce consistent results if the ctm is not an integer translation or if the line is not horizontal or vertical.

void fltk::drawline ( float  x,
float  y,
float  x1,
float  y1 

Draw a straight line between the two points.

void fltk::drawpoint ( int  x,
int  y 

Draw a dot at the given point. If line_width() is zero this is a single pixel to the lower-right of x,y. If line_width() is non-zero this is a dot drawn with the current pen and line caps.

void fltk::drawpoint ( float  X,
float  Y 

Draw a dot at the given point. If line_width() is zero this is the single pixel containing X,Y, or the one to the lower-right if X and Y transform to integers. If line_width() is non-zero this is a dot drawn with the current pen and line caps (currently draws nothing in some api's unless the line_style has CAP_ROUND).

void fltk::drawstyle ( const Style style,
Flags  flags 

Draw using this style. Set drawstyle() to this, drawflags() to flags, calls setcolor() and setbgcolor() with appropriate colors for this style and the given flags, and calls setfont(). This is called by the draw() methods on most fltk widgets. The calling Widget picks what flags to pass to the Symbols so that when they call this they get the correct colors for each part of the widget.

Flags that are understood:

  • HIGHLIGHT: if highlight_color() is non-zero, set bg to highlight_color() and fg to highlight_textcolor().
  • OUTPUT: Normally color(), textcolor(), textfont(), and textsize() are used. If this flag is set buttoncolor(), labelcolor(), labelfont(), and labelsize() are used. Widgets will set this true for any internal buttons, but false for the main area.
  • INACTIVE_R: Change the fg to a gray color.

It then further modifies fg so that it contrasts with the bg.

const Style * fltk::drawstyle ( ) [inline]

Return the last style sent to drawstyle(s,f). Some drawing functions (such as glyphs) look in this for box types. If this has not been called it is Widget::default_style.

void fltk::drawtext ( const char *  text,
float  x,
float  y 

Draw a nul-terminated string.

void fltk::drawtext ( const char *  text,
int  n,
float  x,
float  y 

Draw the first n bytes (not characters if utf8 is used) starting at the given position.

void fltk::drawtext ( const char *  str,
const Rectangle r1,
Flags  flags 

This is the fancy string-drawing function that is used to draw all labels in fltk. The string is formatted and aligned inside the passed rectangle. This also:

  • Breaks the text into lines at \n characters. Word-wraps (if flags has fltk::ALIGN_WRAP set) so the words fit in the columns.
  • Looks up "@xyz;" sequeces to see if they are a Symbol, if so it prints that symbol instead. This is skipped if the flags has fltk::RAW_LABEL set.
  • Parses "&x" combinations to produce Microsoft style underscores, unless RAW_LABEL flag is set.
  • Splits it at every \t tab character and uses column_widths() to set each section into a column.
void fltk::drawtext ( void(*)(const char *, int, float, float)  textfunction,
float(*)(const char *, int)  getwidth,
const char *  str,
const Rectangle r,
Flags  flags 

Provides access to some of the @-string formatting for another graphics API. Most symbols will not work, but you will be able to access the line break and justifications, and commands that change the font, size, and color. I use this to format labels for that are drawn in OpenGL.

textfunction is called to draw all text. It's arguments are a pointer to a UTF-8 string, the length in bytes of that string, and two float numbers for the x and y to draw the text at.

textfunction may use getfont(), getsize(), and getcolor() to find out the settings and recreate them on the output device.

void fltk::drawtext_transformed ( const char *  text,
int  n,
float  x,
float  y 

Draw text starting at a point returned by fltk::transform(). This is needed for complex text layout when the current transform may not match the transform being used by the font.

bool 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().

int fltk::event ( ) [inline]

Returns the most recent event handled, such as fltk::PUSH or fltk::KEY. This is useful so callbacks can find out why they were called.

unsigned fltk::event_button ( ) [inline]

Returns which mouse button was pressed or released by a PUSH or RELEASE event. Returns garbage for other events, so be careful (this actually is the same as event_key(), the buttons have been assigned the key values 1,2,3, etc.

int fltk::event_clicks ( ) [inline]

Returns the number of extra times the mouse was clicked. For a normal fltk::PUSH this is zero, if the user "double-clicks" this is 1, and it is N-1 for each subsequent click.

void fltk::event_clicks ( int  i) [inline]

Setting this value can be used to make callbacks think things were (or were not) double-clicked, and thus act differently.

int fltk::event_dx ( ) [inline]

For fltk::MOUSEWHEEL events this is how many clicks the user moved in the x and y directions (currently dx is always zero).

int fltk::event_dy ( ) [inline]

Reserved for future use if horizontal mouse wheels (or some kind of joystick on the mouse) becomes popular.

bool fltk::event_inside ( const Rectangle r)

Returns true if the current fltk::event_x() and fltk::event_y() put it inside the Rectangle. You should always call this rather than doing your own comparison so you are consistent about edge effects.

bool fltk::event_is_click ( ) [inline]

This is true for a short time after the mouse key is pressed. You test this on the RELEASE events to decide if the user "clicked" or "held" the mouse. It is very useful to do different actions depending on this.

This turns off after a timeout (implemented on X only, currently), when the mouse is moved more than 5 pixels, and when the user presses other mouse or keyboard buttons while the mouse is down.

On X this is used to decide if a click is a double-click, it is if this is still on during the next mouse press. On Windows and OS/X the system's indication is used for double-click.

void fltk::event_is_click ( bool  ) [inline]

You can set this to zero with fltk::event_is_click(0), this can be used to prevent the next mouse click from being considered a double click. Only false works, attempts to set this true are ignored.

unsigned fltk::event_key ( ) [inline]

Returns which key on the keyboard was last pushed. Most non-keyboard events set this to values that do not correspond to any keys, so you can test this in callbacks without having to test first if the event really was a keystroke. The values returned are described under fltk::SpaceKey.

unsigned fltk::event_key_repeated ( ) [inline]

True if the most recent KEY event was caused by a repeating held-down key on the keyboard. The value increments for each repeat.

Note: older versions of fltk reused event_clicks() for this. This made it impossible to design a GUI where the user holds down keyboard keys while clicking the mouse, as well as being pretty hard to understand. So we had to change it for fltk 2.

bool fltk::event_key_state ( unsigned  key)

Returns true if the given key was held down (or pressed) during the last event. This is constant until the next event is read from the server. The possible values for the key are listed under fltk::SpaceKey.

On Win32 event_key_state(KeypadEnter) does not work.

unsigned fltk::event_length ( ) [inline]

Returns the length of the text in fltk::event_text(). There will always be a nul at this position in the text. However there may be a nul before that if the keystroke translates to a nul character or you paste a nul character.

unsigned fltk::event_state ( ) [inline]

This is a bitfield of what shift states were on and what mouse buttons were held down during the most recent event. The flags to pass are described under fltk::SHIFT.

Because Emacs screws up if any key returns the predefined META flag, lots of X servers have really botched up the key assignments trying to make Emacs work. Fltk tries to work around this but you may find that Alt or Meta don't work, since I have seen at least 3 mutually incompatible arrangements. Non-XFree86 machines may also have selected different values so that NUMLOCK, META, and SCROLLLOCK are mixed up. In addition X reports the state before the last key was pressed so the state looks backwards for any shift keys, currently fltk only fixes this bug for the mouse buttons.

bool fltk::event_state ( unsigned  mask) [inline]

Same as event_state()&mask, returns true if any of the passed bits were turned on during the last event. So doing event_state(SHIFT) will return true if the shift keys are held down. This is provided to make the calling code easier to read. The flags to pass are described under fltk::SHIFT.

const char * fltk::event_text ( ) [inline]

Returns the ASCII text (in the future this may be UTF-8) produced by the last fltk::KEY or fltk::PASTE or possibly other event. A zero-length string is returned for any keyboard function keys that do not produce text. This pointer points at a static buffer and is only valid until the next event is processed.

Under X this is the result of calling XLookupString().

int fltk::event_x ( ) [inline]

Returns the distance the mouse is to the right of the left edge of the widget. Widget::send() modifies this as needed before calling the Widget::handle() method.

int fltk::event_x_root ( ) [inline]

Return the absolute horizontal position of the mouse. Usually this is relative to the left edge of the screen, but multiple Monitor setup may change that.

To find the absolute position of the current widget, subtract event_x_root()-event_x().

int fltk::event_y ( ) [inline]

Returns the distance the mouse is below the top edge of the widget. Widget::send() modifies this as needed before calling the Widget::handle() method.

int fltk::event_y_root ( ) [inline]

Return the absolute vertical position of the mouse. Zero is at the top.

void fltk::exit_modal ( ) [inline]

Turns on exit_modal_flag(). This may be used by user callbacks to cancel modal state. See also fltk::Window::make_exec_return().

bool fltk::exit_modal_flag ( ) [inline]

True if exit_modal() has been called. The flag is also set by the destruction or hiding of the modal widget, and on Windows by other applications taking the focus when grab is on.

const char * fltk::file_chooser ( const char *  message,
const char *  pattern,
const char *  fname,
bool  save = false,
int  relative = 1 

pops up the file chooser, waits for the user to pick a file or Cancel, and then returns a pointer to that filename or NULL if Cancel is chosen. If use_system_file_chooser() is set to true, a system FileChooser is opened. If the user picks multiple files, these will be separated by a new line.

messageis a string used to title the window.
patternis used to limit the files listed in a directory to those matching the pattern. This matching is done by filename_match(). Use NULL to show all files. If use_system_file_chooser() is set to true, this will automatically include the "All Files" option.
fnameis a default folder/filename to fill in the chooser with. If this ends with a '/' then this is a default folder and no file is preselected.

If fname is NULL then the last filename that was choosen is used, unless the pattern changes, in which case only the last directory is used. The first time the file chooser is called this defaults to a blank string.

savedetermines whether or not the chooser is created in "save" or "open" mode. This only effects WIN32 and will probably be replaced by the option to OR FileChooser flags together.
relativeis used to determine whether this function returns a relative or an absolute pathname.
The returned value points at a static buffer that is only good until the next time the file_chooser() is called.
Add a "flags" variable that allows the user to override flags.
void fltk::file_chooser_callback ( void(*)(const char *)  cb)

This function is called every time the user navigates to a new file or directory in the file chooser. It can be used to preview the result in the main window.

int fltk::filename_absolute ( char *  output,
int  length,
const char *  input,
const char *  pwd = 0 

Return the filename from expanded to a full "absolute" path name by prepending the current directory:

  • output is a pointer to a buffer that the result is written to.
  • length is the size of output. No more than length-1 bytes are written, plus a trailing nul.
  • input is the initial filename. Must be different than output!
  • cwd is the directory that filename is relative to. If this is NULL then the result of getcwd() is used.

The return value is the number of bytes this wants to write to output. If this value is greater or equal to length, then you know the output has been truncated, and you can call this again with a buffer of n+1 bytes.

Leading "./" sequences in input are removed, and "../" sequences are removed as well as the matching trailing part of the prefixed directory. Technically this is incorrect if symbolic links are used but this matches the behavior of most programs.

If the pwd argument is null, this also expands names starting with '~' to the user or another user's HOME directory. To expand a filename starting with ~ in the current directory you must start it with "./~".

If input is a zero-length string then the pwd is returned with a slash added to the end.

bool fltk::filename_exist ( const char *  name)

Returns true if the file exists .

const char * fltk::filename_ext ( const char *  buf)

Returns a pointer to the last period in filename_name(f), or a pointer to the trailing nul if none. Notice that this points at the period, not after it!

bool fltk::filename_isdir ( const char *  name)

Returns true if the file exists and is a directory.

bool fltk::filename_isfile ( const char *  name)

Returns true if the file exists and is a regular file.

bool fltk::filename_match ( const char *  s,
const char *  p 

Returns true if filename s matches pattern p. The following glob syntax is used by pattern:

  • "\x" quotes the character x so it must be matched exactly
  • "*" matches any sequence of 0 or more characters.
  • "?" matches any single character.
  • "[set]" matches any character in the set. Set can contain any single characters, or a-z to represent a range. To match ] or - they must be the first characters. To match ^ or ! they must not be the first characters.
  • "[^set]" or "[!set]" matches any character not in the set.
  • "{X|Y|Z}" or "{X,Y,Z}" matches any one of the subexpressions literally.
  • lowercase letters match both upper and lowercase
  • all other characters must match exactly
long int fltk::filename_mtime ( const char *  name)

Returns the modification time of the file as a Unix timestamp (number of seconds since the start of 1970 in GMT). Returns 0 if the file does not exist.

const char * fltk::filename_name ( const char *  name)

Returns a pointer to after the last slash in name. If the name ends with a slash then this returns a pointer to the NUL. If there is no slash this returns a pointer to the start of name.

int fltk::filename_relative ( char *  to,
int  tolen,
const char *  from,
const char *  cwd = 0 

Does the opposite of filename_absolute(). Produces the shortest possible name in output that is relative to the current directory. If the filename does not start with any text that matches the current directory then it is returned unchanged.

Return value is the number of characters it wants to write to output.

FL_FILESIZE_T fltk::filename_size ( const char *  name)

Returns the size of the file in bytes. Returns zero if it does not exist.

void fltk::fillpath ( )

Does fltk::closepath() and then fill with the current color, and then clear the path.

For portability, you should only draw polygons that appear the same whether "even/odd" or "non-zero" winding rules are used to fill them. This mostly means that holes should be drawn in the opposite direction of the outside.

Warning: result is somewhat different on X and Win32! Use fillstrokepath() to make matching shapes. In my opinion X is correct, we may change the Win32 version to match in the future, perhaps by making the current pen invisible?

void fltk::fillrect ( int  x,
int  y,
int  w,
int  h 

Fill the rectangle with the current color.

void fltk::fillstrokepath ( Color  color)

Does fltk::fill(), then sets the current color to linecolor and does fltk::stroke with the same closed path, and then clears the path.

This seems to produce very similar results on X and Win32. Also it takes advantage of a single GDI32 call that does this and should be faster.

Window* fltk::find ( XWindow  xid)

Converts a xid to its equivalent Window

xidThe XWindow ID of the window
The Window matching this xid, or NULL if it doesn't exist
FILE * fltk::fltk_fopen ( const char *  name,
const char *  flags 

Portably calls the fopen() function for different systems. Note that ALL calls to this function MUST make sure the filename is UTF8 encoded.

nameUTF8 encoded directory name
flagsFlags to pass to fopen (commonly 'r', 'w', etc...)
See also:
Returns the same FILE* that fopen() returns
int fltk::fltk_stat ( const char *  name,
struct stat *  buffer 

Portably calls the system's stat() function, to deal with native Unicode filenames. Has the same return values and use as the system's stat. The string passed to fltk_stat must be UTF8 (note that ASCII is a subset of UTF8)

void fltk::flush ( )

write all preferences to disk

  • this function works only with the base preference group
  • this function is rarely used as deleting the base preferences flushes automatically

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.

Widget * fltk::focus ( ) [inline]

Returns the widgets that will receive fltk::KEY events. This is NULL if the application does not have focus now, or if no widgets accepted focus.

void fltk::focus ( Widget o)

Change fltk::focus() to the given widget, the previous widget and all parents (that don't contain the new widget) are sent fltk::UNFOCUS events, the new widget is sent an fltk::FOCUS event, and all parents of it get fltk::FOCUS_CHANGE events.

fltk::focus() is set whether or not the applicaton has the focus or if the widgets accept the focus. You may want to use fltk::Widget::take_focus() instead, it will test first.

fltk::Font * fltk::font ( int  i) [related]

For back-compatabilty with FLTK1, this turns an integer into one of the built-in fonts. 0 = HELVETICA.

unsigned fltk::foreachShortcut ( const Widget widget,
ShortcutFunctor &  f 

Call the handle() method from the passed ShortcutFunctor object for every Widget::shortcut() assignment known. If any return true then this immediately returns that shortcut value, else this returns zero after calling it for the last one. This is most useful for making a display of shortcuts for the user, or implementing a shortcut editor.

class ListShortcuts : public ShortcutFunctor {
  bool handle(const Widget* widget, unsigned key) {
    printf("Widget=%s shortcut=%s\n",
           widget->label() ? widget->label() : "NULL",
    return false;
f() {
  ListShortcuts listShortcuts;

If widget is not null, only do assignments for that widget, this is much faster than searching the entire list. This is useful for drawing the shortcuts on a widget (though most fltk widgets only draw the first one).

Color fltk::get_color_index ( Color  color)

Return the rgb form of color. If it is an indexed color that entry is returned. If it is an rgb color it is returned unchanged.

const char * fltk::get_encoding ( ) [inline]

Returns the string sent to the most recent set_encoding().

bool fltk::get_key_state ( unsigned  key)

Returns true if the given key is held down now. This is different than event_key_state() as that returns how the key was during the last event. This can also be slower as it requires a round-trip query to the window server. The values to pass are described under fltk::SpaceKey.

On Win32 fltk::get_key_state(fltk::KeypadEnter) does not work.

void fltk::get_mouse ( int &  x,
int &  y 

Return where the mouse is on the screen by doing a round-trip query to the server. You should use fltk::event_x_root() and fltk::event_y_root() if possible, but this is necessary if you are not sure if a mouse event has been processed recently (such as to position your first window). If the display is not open, this will open it.

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

float fltk::getascent ( )

Return the distance from the baseline to the top of letters in the current font.

Color fltk::getbgcolor ( ) [inline]

Returns the last Color passed to setbgcolor(). To actually draw in the bg color, do this:

  Color saved = getcolor();
Color fltk::getcolor ( ) [inline]

Returns the last Color passed to setcolor().

HDC fltk::getDC ( )

Return an arbitrary HDC which you can use for Win32 functions that need one as an argument. The returned value is short-lived and may be destroyed the next time anything is drawn into a window!

float fltk::getdescent ( )

Return the distance from the baseline to the bottom of letters in the current font.

Font * fltk::getfont ( ) [inline]

Return the Font sent to the last setfont().

float fltk::getsize ( ) [inline]

Return the size sent to the last setfont(). You should use this as a minimum line spacing (using ascent()+descent() will produce oddly spaced lines for many fonts).

float fltk::getwidth ( const char *  text)

Return the width of a nul-terminated UTF-8 string drawn in the font set by the most recent setfont().

float fltk::getwidth ( const char *  text,
int  n 

Return the width of the first n bytes of this UTF-8 string drawn in the font set by the most recent setfont().

void fltk::gldrawimage ( const uchar *  b,
int  x,
int  y,
int  w,
int  h,
int  d = 3,
int  ld = 0 

Uses glDrawPixels to draw an image using the same arguments as drawimage(). If you are in the normal OpenGL coordinate system with 0,0 in the lower-left, the first pixel is memory is the lower-left corner.

void fltk::gldrawtext ( const char *  str,
float  x,
float  y,
float  z = 0 

Draw text at the given point in 3D space transformed to the screen.

void fltk::gldrawtext ( const char *  str)

Draw text at the current glRasterPos in the current font selected with fltk::glsetfont(). You can use glRasterPos2f() or similar calls to set the position before calling this.

The string is in UTF-8, although only characters in ISO-8859-1 are drawn correctly, others draw as question marks.

void fltk::gldrawtext ( const char *  text,
int  n 

Draw the first n bytes of text at the current glRasterPos.

void fltk::gldrawtext ( const char *  str,
int  n,
float  x,
float  y,
float  z = 0 

Draw the first n bytes of text at the given point in 3D space transformed to the screen.

void fltk::glfillrect ( int  x,
int  y,
int  w,
int  h 
) [inline]

Inline wrapper for glRecti(x,y,x+w,y+h).

void fltk::glfinish ( )

Turn off the effects of a previous glstart(). You must call this before using normal fltk drawing methods.

void fltk::glsetcolor ( Color  i)

Set the current OpenGL color to a FLTK color, or as close as possible.

void fltk::glsetfont ( fltk::Font font,
float  size 

Make the current OpenGL font (as used by gldrawtext()) be as similar as possible to an FLTK Font. Currently the font is aliased except on X.

void fltk::glstart ( )

Set up an OpenGL context to draw into the current window being drawn by fltk. This will allow you to use OpenGL to update a normal window. The current transformation is reproduced, and the current clipping is simulated with glScissor() calls (which can only do a rectangle).

You must use glfinish() to exit this mode before any normal fltk drawing calls are done.

You should call glvisual() at program startup if you intend to use this. This may be used to change how windows are created so this call works.

I would like this to work reliably, but it is not real good now on any platforms. In particular it does not cooperate with the double-buffering schemes. It does appear to work on X when you turn off double buffering, it also works if OpenGL is entirely software, such as MESA.

Do not call glstart()/glfinish() when drawing into a GlWindow!

void fltk::glstrokerect ( int  x,
int  y,
int  w,
int  h 

Draw a 1-thick line just inside the given rectangle.

bool fltk::glVisual ( int  mode)

Same as fltk::visual(int) except choose a visual that is also capable of drawing OpenGL. On modern X servers this is true by default, but on older ones OpenGL will crash if the visual is not selected with this.

mode is the same bitflags accepted by GlWindow::mode(). This causes all windows (and thus glstart()) to have these capabilities.

bool fltk::grab ( ) [inline]

returns the current value of grab (this is always false if modal() is null).

ImageType * fltk::guess_image ( const char *  name,
const uchar *  datas = 0 

Try to guess the filetype Beware that calling this force you to link in all image types !

bool fltk::handle ( )

Make FLTK act as though it just got the event stored in xevent. You can use this to feed artifical X events to it, or to use your own code to get events from X.

Besides feeding events your code should call fltk::flush() periodically so that FLTK redraws its windows.

This function will call any widget callbacks from the widget code. It will not return until they complete, for instance if it pops up a modal window with fltk::ask() it will not return until the user clicks yes or no.

bool fltk::handle ( int  event,
Window window 

This is the function called from the system-specific code for all events that can be passed to Widget::handle().

You can call it directly to fake events happening to your widgets. Currently data other than the event number can only be faked by writing to the undocumented fltk::e_* variables, for instance to make event_x() return 5, you should do fltk::e_x = 5. This may change in future versions.

This will redirect events to the modal(), pushed(), belowmouse(), or focus() widget depending on those settings and the event type. It will turn MOVE into DRAG if any buttons are down. If the resulting widget returns 0 (or the window or widget is null) then the functions pointed to by add_event_handler() are called.

bool fltk::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.

bool fltk::has_idle ( TimeoutHandler  cb,
void *  data = 0 

Returns true if the specified idle callback is currently installed.

bool fltk::has_timeout ( TimeoutHandler  cb,
void *  arg = 0 

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

bool fltk::in_main_thread ( )

Returns true if the current thread is the main thread, i.e. the one that called wait() first. Many fltk calls such as wait() will not

work correctly if this is not true. This function must be surrounded by lock() and unlock() just like all other fltk functions, the return value is wrong if you don't hold the fltk lock!

Warning: in_main_thread() is wrong if the main thread calls fltk::unlock() and another thread calls fltk::lock() (the assumption is that the main thread only calls wait()). Current fix is to do the following unsupported code:

  fltk::in_main_thread_ = false;
  fltk::in_main_thread_ = true;
Color fltk::inactive ( Color  fg)

Same as lerp(fg, getbgcolor(), .5). This is for back-compatability only?

Color fltk::inactive ( Color  fg,
Color  bg 

Same as lerp(fg, bg, .5), it grays out the color.

const char * fltk::input ( const char *  fmt,
const char *  defstr = 0,

Pops up a window displaying a string, lets the user edit it, and return the new value. The cancel button returns NULL. The returned pointer is only valid until the next time fltk::input() is called. Due to back-compatability, the arguments to any printf commands in the label are after the default value.

If message_window_timeout is used, then 0 will be returned if the timeout expires.

int fltk::intersect_with_clip ( Rectangle r)

Intersect a transform()'d rectangle with the current clip region and change it to the smaller rectangle that surrounds (and probably equals) this intersection area.

This can be used by device-specific drawing code to limit complex pixel operations (like drawing images) to the smallest rectangle needed to update the visible area.

Return values:

  • 0 if it does not intersect, and W and H are set to zero.
  • 1 if if the result is equal to the rectangle (i.e. it is entirely inside or equal to the clip region)
  • 2 if it is partially clipped.
unsigned fltk::key ( const char *  name)

Turn a string into a fltk::event_key() value or'd with fltk::event_shift() flags. The returned value can be used by by fltk::Widget::add_shortcut(). Any error, or a null or zero-length string, returns 0.

Currently this understands prefixes of "Alt+", "Shift+", and "Ctrl+" to turn on fltk::ALT, fltk::SHIFT, and fltk::CTRL. Case is ignored and the '+' can be a '-' instead and the prefixes can be in any order. You can also use '#' instead of "Alt+", '+' instead of "Shift+", and '^' instead of Ctrl+.

After the shift prefixes there can either be a single ASCII letter, "Fn" where n is a number to indicate a function key, or "0xnnnn" to get an arbitrary fltk::event_key() enumeration value.

The inverse function to turn a number into a string is fltk::key_name(). Currently this function does not parse some strings fltk::key_name() can return, such as the names of arrow keys!

const char * fltk::key_name ( unsigned  hotkey)

Unparse a fltk::Widget::shortcut(), an fltk::event_key(), or an fltk::event_key() or'd with fltk::event_state(). Returns a pointer to a human-readable string like "Alt+N". If hotkey is zero an empty string is returned. The return value points at a static buffer that is overwritten with each call.

The opposite function is fltk::key().

Color fltk::lerp ( Color  color0,
Color  color1,
float  weight 

Return (1-weight)*color0 + weight*color1. weight is clamped to the 0-1 range before use.

const char * fltk::line_dashes ( ) [inline]

Return the last value for dashes sent to line_style(int,width,dashes). Note that the actual pointer is returned, which may not point at legal data if a local array was passed, so this is only useful for checking if it is NULL or not.

int fltk::line_style ( ) [inline]

Return the last value sent to line_style(int,width,dashes), indicating the cap and join types and the built-in dash patterns.

void fltk::line_style ( int  style,
float  width = 0,
const char *  dashes = 0 

Set how to draw lines (the "pen"). If you change this it is your responsibility to set it back to the default with fltk::line_style(0).

style is a bitmask in which you 'or' the following values. If you don't specify a dash type you will get a solid line. If you don't specify a cap or join type you will get a system-defined default of whatever value is fastest.

  • fltk::SOLID -------
  • fltk::DASH - - - -
  • fltk::DOT ·········
  • fltk::DASHDOT - · - ·
  • fltk::DASHDOTDOT - ·· - ··
  • fltk::CAP_FLAT
  • fltk::CAP_ROUND
  • fltk::CAP_SQUARE (extends past end point 1/2 line width)
  • fltk::JOIN_MITER (pointed)
  • fltk::JOIN_ROUND
  • fltk::JOIN_BEVEL (flat)

width is the number of pixels thick to draw the lines. Zero results in the system-defined default, which on both X and Windows is somewhat different and nicer than 1.

dashes is a pointer to an array of dash lengths, measured in pixels, if set then the dash pattern in style is ignored. The first location is how long to draw a solid portion, the next is how long to draw the gap, then the solid, etc. It is terminated with a zero-length entry. A null pointer or a zero-length array results in a solid line. Odd array sizes are not supported and result in undefined behavior. The dashes array is ignored on Windows 95/98.

float fltk::line_width ( ) [inline]

Return the last value for width sent to line_style(int,width,dashes).

void fltk::load_identity ( )

Replace the current transform with the identity transform, which puts 0,0 in the top-left corner of the window and each unit is 1 pixel in size.

void fltk::load_theme ( )

Call the theme() function if it has not already been called. Normally FLTK calls this just before the first Window::show() is done. You need to call this earlier to execute code such as measuring labels that may depend on the theme.

void fltk::lock ( )

A multi-threaded fltk program must surround all calls to any fltk functions with lock() and unlock() pairs. This is a "recursive lock", a thread can call lock() n times, and it must call unlock() n times before it really is unlocked.

If another thread calls lock() while it is locked, it will block (not return from lock()) until the first thread unlocks.

The main thread must call lock() once before any call to fltk to initialize the thread system.

The X11 version of fltk uses XInitThreads(), XLockDisplay(), and XUnlockDisplay(). This should allow an fltk program to cooperate with other packages updating the display using Xlib calls.

void fltk::measure ( float(*)(const char *, int)  getwidth,
const char *  str,
float &  w,
float &  h,
Flags  flags = 0 

This lets you pass your own measurement function to measure the widths of printed text. Also returns floating point sizes.

void fltk::measure ( const char *  str,
int &  w,
int &  h,
Flags  flags = 0 

Measure the size of box necessary for drawtext() to draw the given string inside of it. The flags are used to set the alignment, though this should not make a difference except for fltk::ALIGN_WRAP. To correctly measure wrap w must be preset to the width you want to wrap at if fltk::ALIGN_WRAP is on in the flags! w and h are changed to the size of the resulting box.

void fltk::message ( const char *  fmt,

Displays a printf-style message in a pop-up box with an "OK" button, waits for the user to hit the button. The message will wrap to fit the window, or may be many lines by putting '\n' characters into it. The enter key is a shortcut for the OK button.

void fltk::modal ( Widget widget,
bool  grab = false 

Restricts events to a certain widget.

First thing: much of the time fltk::Window::exec() will do what you want, so try using that.

This function sets the passed widget as the "modal widget". All user events are directed to it or a child of it, preventing the user from messing with other widgets. The modal widget does not have to be visible or even a child of an fltk::Window for this to work (but if it not visible, fltk::event_x() and fltk::event_y() are meaningless, use fltk::event_x_root() and fltk::event_y_root()).

The calling code is responsible for saving the current value of modal() and grab() and restoring them by calling this after it is done. The code calling this should then loop calling fltk::wait() until fltk::exit_modal_flag() is set or you otherwise decide to get out of the modal state. It is the calling code's responsibility to monitor this flag and restore the modal widget to it's previous value when it turns on.

grab indicates that the modal widget should get events from anywhere on the screen. This is done by messing with the window system. If fltk::exit_modal() is called in response to an fltk::PUSH event (rather than waiting for the drag or release event) fltk will "repost" the event so that it is handled after modal state is exited. This may also be done for keystrokes in the future. On both X and WIN32 grab will not work unless you have some visible window because the system interface needs a visible window id. On X be careful that your program does not enter an infinite loop while grab() is on, it will lock up your screen!

Widget * fltk::modal ( ) [inline]

Returns the current modal widget, or null if there isn't one. It is useful to test these in timeouts and file descriptor callbacks in order to block actions that should not happen while the modal window is up. You also need these in order to save and restore the modal state.

int fltk::modificationsort ( const dirent *const *  a,
const dirent *const *  b 

Sorts two files based on their modification date.

Color fltk::nearest_index ( Color  i)

Find an indexed color in the range 56-127 that is closest to this color. If this is an indexed color it is returned unchanged.

void fltk::newpath ( )

Clear the current "path". This is normally done by fltk::fillpath() or any other drawing command.

bool fltk::not_clipped ( const Rectangle r1)

Returns true if any or all of rectangle is inside the clip region.

Returns true if any or all of the Rectangle is inside the clip region.

void fltk::open_display ( Display *  d)

You can make fltk "open" a display that has already been opened, perhaps by another GUI library. Calling this will set xdisplay to the passed display and also read information FLTK needs from it. Don't call this if the display is already open!

void fltk::open_display ( )

Opens the display. Does nothing if it is already open. You should call this if you wish to do X calls and there is a chance that your code will be called before the first show() of a window. This is called automatically Window::show().

This may call fltk::abort() if there is an error opening the display.

void fltk::own_colormap ( )

Makes FLTK use its own X colormap. This may make FLTK display better and will reduce conflicts with other programs that want lots of colors. However the colors may flash as you move the cursor between windows. This function is pretty much legacy nowadays as all modern systems are full color, on such systems this does nothing.

You must call this before you show() any windows. If you call visual(int) you must call this after that.

fltk::Color fltk::parsecolor ( const char *  name,
unsigned  length 

Turn the first n bytes of name into an fltk color. This allows you to parse a color out of the middle of a string.

Recognized values are:

  • "" turns into NO_COLOR
  • "0"-"99" decimal fltk color number, only works for indexed color range
  • "0xnnn" hex value of any fltk color number
  • "rgb" or "#rgb" three hex digits for rgb
  • "rrggbb" or "#rrggbb" 2 hex digits for each of rgb
  • "rrggbbaa" or "#rrggbbaa" fltk color number in hex
  • "rrrgggbbb" or "#rrrgggbbb" 3 hex digits for each of rgb
  • "rrrrggggbbbb" or "#rrrrggggbbbb" 4 hex digits for each of rgb
  • 17 "web safe colors" as defined by CSS 2.1
  • If FLTK is compiled to use X11, then XParseColor() is tried
  • all other strings return NO_COLOR.
const char * fltk::password ( const char *  fmt,
const char *  defstr = 0,

Same as fltk::input() except an fltk::SecretInput field is used.

void fltk::paste ( Widget receiver,
bool  clipboard = false 

This is what a widget does when a "paste" command (like Ctrl+V or the middle mouse click) is done to it. Cause an fltk::PASTE event to be sent to the receiver with the contents of the current selection in the fltk::event_text(). The selection can be set by fltk::copy().

There are actually two buffers. If clipboard is true then the text is from the user-visible selection that is moved around with cut/copy/paste commands (on X this is the CLIPBOARD selection). If clipboard is false then the text is from a less-visible buffer used for temporarily selecting text with the mouse and for drag & drop (on X this is the XA_PRIMARY selection).

The reciever should be prepared to be called directly by this, or for it to happen later, or possibly not at all. This allows the window system to take as long as necessary to retrieve the paste buffer (or even to screw up completely) without complex and error-prone synchronization code most toolkits require.

void fltk::pop_clip ( )

Restore the previous clip region. You must call fltk::pop_clip() exactly once for every time you call fltk::push_clip(). If you return to FLTK with the clip stack not empty unpredictable results occur.

void fltk::pop_matrix ( )

Put the transformation back to the way it was before the last push_matrix(). Calling this without a matching push_matrix will crash!

void fltk::push_clip ( const Rectangle r)

Pushes the intersection of the current region and r onto the clip stack.

void fltk::push_clip ( int  x,
int  y,
int  w,
int  h 

Same as push_clip(Rectangle(x,y,w,h)) but faster:

Same as push_clip(Rectangle(x,y,r,h)) except faster as it avoids the construction of an intermediate rectangle object.

Pushes the intersection of the current region and this rectangle onto the clip stack.

void fltk::push_matrix ( )

Save the current transformation on a stack, so you can restore it with pop_matrix().

FLTK provides an arbitrary 2-D affine transformation (rotation, scale, skew, reflections, and translation). This is very similar to PostScript, PDF, SVG, and Cairo.

Due to limited graphics capabilities of some systems, not all drawing functions will be correctly transformed, except by the integer portion of the translation. Don't rely on this as we may be fixing this without notice.

void fltk::push_no_clip ( )

Pushes an empty clip region on the stack so nothing will be clipped. This lets you draw outside the current clip region. This should only be used to temporarily ignore the clip region to draw into an offscreen area.

Widget * fltk::pushed ( ) [inline]

Get the widget that is being pushed. fltk::DRAG or fltk::RELEASE (and any more fltk::PUSH) events will be sent to this widget. This is null if no mouse button is being held down, or if no widget responded to the fltk::PUSH event.

void fltk::pushed ( Widget o)

Change the fltk::pushed() widget. This sends no events.

uchar * fltk::readimage ( uchar *  p,
PixelType  type,
const Rectangle &  rectangle,
int  linedelta 

Reads a 2-D image off the current drawing destination. The resulting data can be passed to fltk::drawimage() or the 8-bit pixels examined or stored by your program.

The return value is either p or NULL if there is some problem (such as an inability to read from the current output surface, or if the rectangle is empty).

p points to the location to store the first byte of the upper-left pixel of the image. The caller must allocate this buffer.

type can be fltk::RGB or fltk::RGBA (possibly other types will be supported in the future).

rectangle indicates the position on the surface in the current transformation to read from and the width and height of the resulting image. What happens when the current transformation is rotated or scaled is undefined. If the rectangle extends outside the current drawing surface, or into areas obscured by overlapping windows, the result in those areas is undefined.

linedelta is how much to add to a pointer to advance from one pixel to the one below it. Any bytes skipped over are left with undefined values in them. Negative values can be used to store the image upside-down, however p should point to 1 line before the end of the buffer, as it still points to the top-left pixel.

uchar * fltk::readimage ( uchar *  p,
PixelType  type,
const Rectangle &  r 

Same except linedelta is set to r.w()*depth(type).

int 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()) {
  if (fltk::ready()) {
    if (user_hit_abort_button()) break;
void fltk::redraw ( void  )

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

void fltk::register_images ( )

Makes it so SharedImage can identify image files of the types compiled into fltk. These are XPM, PNG, and Jpeg images.

void fltk::reload_theme ( )

Does nothing if load_theme() has not been called yet. If load_theme() has been called, this calls the theme() function again and then call redraw(). If the theme function is written correctly, this should change the display to the new theme. You should call this if you change the theme() or if external information changes such that the result of your theme() function changes.

FLTK will call this automatically when it gets a message from the system indicating the user's preferences have changed.

void fltk::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 fltk::remove_fd ( int  n,
int  events = -1 

Remove all the callbacks (ie for all different when values) for the given file descriptor. It is harmless to call this if there are no callbacks for the file descriptor. If when is given then those bits are removed from each callback for the file descriptor, and the callback removed only if all of the bits turn off.

void fltk::remove_idle ( TimeoutHandler  cb,
void *  data = 0 

Removes the specified idle callback, if it is installed.

void fltk::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 fltk::repeat_timeout ( float  time,
TimeoutHandler  cb,
void *  arg = 0 

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:

void callback(void*) {

main() {
  for (;;) fltk::wait();
bool fltk::reset_theme ( )

Change the theme to the compiled-in default by calling the revert function of all NamedStyle structures. A theme() function may want to call this to clear the previous settings.

void fltk::rotate ( float  d)

Rotate the current transformation counter-clockwise by d degrees (not radians!!). This is done by multiplying the matrix by:

cos -sin 0
sin  cos 0
0     0  1
int 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 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 fltk::scale ( float  x,
float  y 

Scale the current transformation by multiplying it by

x 0 0
0 y 0
0 0 1
void fltk::scale ( float  x)

Scale the current transformation by multiplying it by

x 0 0
0 x 0
0 0 1
void fltk::scrollrect ( const Rectangle &  r,
int  dx,
int  dy,
void(*)(void *, const Rectangle &)  draw_area,
void *  data 

Move the contents of a rectangle by dx and dy. The area that was previously outside the rectangle or obscured by other windows is then redrawn by calling draw_area for each rectangle. This is a drawing function and can only be called inside the draw() method of a widget.

If dx and dy are zero this returns without doing anything.

If dx or dy are larger than the rectangle then this just calls draw_area for the entire rectangle. This is also done on systems (Quartz) that do not support copying screen regions.

void fltk::set_background ( Color  c)

fltk::GRAY75 is replaced with the passed color, and all the other fltk::GRAY* colors are replaced with a color ramp (or sometimes a straight line) so that using them for highlighted edges of raised buttons looks correct.

void fltk::set_color_index ( Color  i,
Color  color 

Set one of the indexed colors to the given rgb color. i must be in the range 0-255, and c must be a non-indexed rgb color.

void fltk::set_encoding ( const char *  f)

Obsolete function to encourage FLTK to choose a 256-glyph font with the given encoding. You must call setfont() after changing this for it to have any effect.

Notice that this is obsolete! Only the non-Xft X version actually uses it and that may be eliminated as well. In addition FLTK uses UTF-8 internally, and assummes that any font it prints with is using Unicode encoding (or ISO-8859-1 if there are only 256 characters).

The default is "iso10646-1"

void fltk::setbgcolor ( Color  c) [inline]

Set the "background" color. This is not used by the drawing functions, but many box and image types will refer to it by calling getbgcolor().

HBRUSH fltk::setbrush ( )

Set the current "brush" in the DC to match the most recent setcolor() and line_style() calls. This is stupid-expensive on Windows so we defer it until the brush is needed.

void fltk::setcolor ( Color  color)

Set the color for all subsequent drawing operations.

See also:
void fltk::setcolor_alpha ( Color  color,
float  alpha 

Sets the current rgb and alpha to draw in, on rendering systems that allow it. If alpha is not supported this is the same as setcolor(). The color you pass should not premultiplied by the alpha value, that would be a different, nyi, call.

void fltk::setdrawflags ( Flags  f) [inline]

Store a set of bit flags that may influence the drawing of some fltk::Symbol subclasses, such as boxes. Generally you must also use setcolor() and setbgcolor() to set the color you expect as not all symbols draw differently depending on the flags.

The flags are usually copied from the flags() on a Widget.

Some commonly-used flags:

  • INACTIVE_R : Draw inactive, fill images with solid fg color
  • VALUE: Draw turned on or checked
  • SELECTED: Draw as though selected in a browser or menu.
  • HIGHLIGHT: Draw as though highlighted by the mouse pointing at it
  • PUSHED: Draw as though pushed by the user
  • FOCUSED: Draw as though it has keyboard focus
  • INVISIBLE: Some boxes don't draw their interior if this is set
See also:
void fltk::setfont ( fltk::Font font,
float  psize 

Set the current font and font scaling so the size is size pixels. The size is unaffected by the current transformation matrix (you may be able to use fltk::transform() to get the size to get a properly scaled font).

The size is given in pixels. Many pieces of software express sizes in "points" (for mysterious reasons, since everything else is measured in pixels!). To convert these point sizes to pixel sizes use the following code:

const fltk::Monitor& monitor = fltk::Monitor::all();
float pixels_per_point = monitor.dpi_y()/72.0;
float font_pixel_size = font_point_size*pixels_per_point;

See the fltk::Font class for a description of what can be passed as a font. For most uses one of the built-in constant fonts like fltk::HELVETICA can be used.

HPEN fltk::setpen ( )

Set the current "pen" in the DC to match the most recent setcolor() and line_style() calls. This is stupid-expensive on Windows so we defer it until the pen is needed.

Color fltk::show_colormap ( Color  oldcol)

Older style of color chooser that only chooses the "indexed" fltk colors. This pops up a panel of the 256 colors you can access with "indexed" fltk::Color values and lets the user pick one of them.

If the user clicks on one of them, the new index is returned.

If they type Esc or click outside the window, the old index is returned.

void fltk::split_color ( Color  i,
unsigned char &  r,
unsigned char &  g,
unsigned char &  b 

Set r,g,b to the 8-bit components of this color. If it is an indexed color they are looked up in the table, otherwise they are simply copied out of the color number.

void fltk::stop_drawing ( HWND  window)

Destroy any dc or other objects used to draw into this window.

void fltk::stop_drawing ( XWindow  window)

Destroy any "graphics context" structures that point at this window or Pixmap. They will be recreated if you call draw_into() again.

Unfortunately some graphics libraries will crash if you don't do this. Even if the graphics context is not used, destroying it after destroying it's target will cause a crash. Sigh.

void fltk::strokepath ( )

Draw a line between all the points in the path (see fltk::line_style() for ways to set the thicknesss and dot pattern of the line), then clear the path.

void fltk::strokerect ( int  x,
int  y,
int  w,
int  h 

Draw a line inside this bounding box (currently correct only for 0-thickness lines).

fltk::theme ( ) [inline]

Returns the current Theme function. By default this points at fltk_theme().

fltk::theme ( Theme  f) [inline]

Change what function fltk should call to set the appearance. If you change this after any windows may have been shown, you should call reload_theme().

void * fltk::thread_message ( )

Returns an argument sent to the most recent awake(), or returns null if none. Warning: this is almost useless for communication as the current implementation only has a one-entry queue and only returns the most recent awake() result.

void fltk::transform ( float &  x,
float &  y 

Replace x and y transformed into device coordinates. Device-specific code can use this to draw things using the fltk transformation matrix. If the backend is Cairo or another API that does transformations, this may return xy unchagned.

void fltk::transform ( const Rectangle from,
Rectangle to 

Transform the rectangle from into device coordinates and put it into to. This only works correctly for 90 degree rotations, for other transforms this will produce an axis-aligned rectangle with the same area (this is useful for inscribing circles, and is about the best that can be done for device functions that don't handle rotation.

void fltk::transform ( int &  X,
int &  Y,
int &  W,
int &  H 

Same as transform(Rectangle(X,Y,W,H),to) but replaces XYWH with the transformed rectangle. This may be faster as it avoids the rectangle construction.

void fltk::transform ( int &  x,
int &  y 

Replace x and y with the transformed coordinates, rounded to the nearest integer.

void fltk::transform_distance ( float &  x,
float &  y 

Replace x and y with the tranformed coordinates, ignoring translation. This transforms a vector which is measuring a distance between two positions, rather than a position.

void fltk::translate ( int  x,
int  y 

This integer version is provided because it is much faster than the floating-point version. However C++ will not "resolve" which one you want to call if you try passing doubles as arguments. To get it to compile, make sure you cast the arguments to float (add 'f' after floating-point constants). Use the 'f' versions (ie sinf(), cosf(), etc) of the math functions from <fltk/math.h> to produce floats and get maximum calculation speed.

void fltk::translate ( float  x,
float  y 

Translate the current transformation by multiplying it by

1 0 0
0 1 0
x y 1
bool fltk::try_shortcut ( )

Try sending the current KEY event as a SHORTCUT event.

Normally the focus() gets all keystrokes, and shortcuts are only tested if that widget indicates it is uninterested by returning zero from Widget::handle(). However in some cases the focus wants to use the keystroke only if it is not a shortcut. The most common example is Emacs-style editing keystrokes in text editing widgets, which conflict with Microsoft-compatable menu key bindings, but we want the editing keys to work if there is no conflict.

This will send a SHORTCUT event just like the focus returned zero, to every widget in the focus window, and to the add_handler() calls, if any. It will return true if any widgets were found that were interested in it. A handle() method can call this in a KEY event. If it returns true, return 1 immediatly, as the shortcut will have executed and may very well have destroyed your widget. If this returns false, then do what you want the key to do.

void fltk::unlock ( )

Releases the lock that was set using the fltk::lock() method. Child threads should call this method as soon as they are finished accessing FLTK. If some other thread is waiting for fltk::lock() to return, it will get control.

void fltk::use_system_file_chooser ( bool  useit = true)

On Windows this makes file_chooser() call the Win32 file chooser API instead of using the one constructed in fltk. Ignored on other systems.

double fltk::version ( )

Returns the value of FL_VERSION that FLTK was compiled with. This can be compared to the FL_VERSION macro to see if the shared library of fltk your program linked with is up to date.

bool fltk::visual ( int  flags)

X-specific crap to allow you to force the "visual" used by fltk to one you like, rather than the "default visual" which in many cases has less capabilities than your machine really has! For instance fltk::visual(fltk::RGB_COLOR) will get you a full color display instead of an 8-bit colormap, if possible.

You must call this before you show() any windows. The integer argument is an 'or' of the following:

  • fltk::INDEXED_COLOR indicates that a colormapped visual is ok. This call will normally fail if a TrueColor visual cannot be found.
  • fltk::RGB_COLOR this value is zero and may be passed to indicate that fltk::INDEXED_COLOR is not wanted.
  • fltk::RGB24_COLOR indicates that the visual must have at least 8 bits of red, green, and blue (Windows calls this "millions of colors").
  • fltk::DOUBLE_BUFFER indicates that hardware accelerated double buffering is wanted.
  • Other bits used by glVisual() and GlWindow::mode() are ignored by this.

This returns true if the system has the capabilities by default or FLTK suceeded in turing them on. Your program will still work even if this returns false (it just won't look as good).

On non-X systems this just returns true or false indicating if the system supports the passed values.

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

int fltk::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.

bool fltk::warp_mouse ( int  x,
int  y 

Change where the mouse is on the screen. Returns true if successful, false on failure (exactly what success and failure means depends on the os).

XFontStruct * fltk::xfont ( )

Returns the operating-system dependent structure defining the current font. You must include <fltk/x.h> to use this.

XWindow xid ( const Window *  window) [inline]

Returns the XID for a window, or zero if show() has not been called on it.

ulong fltk::xpixel ( Color  i)

Returns the X pixel number used to draw the given FLTK color. If a colormapped visual is being used, this may allocate it, or find the nearest match.

Variable Documentation

Box *const fltk::BORDER_BOX = &borderBox

1-pixel thick gray line around rectangle.

Box *const fltk::BORDER_FRAME = &borderFrame

Obsolete. Draws colored edge and draws nothing inside rectangle.

const char * fltk::cancel = "&Cancel"

You can change this string to convert fltk to a foreign language.

The color picked by the most recent setcolor(Color).

HDC fltk::dc

The device context that is currently being drawn into.

Box *const fltk::DEFAULT_FOCUS_BOX = &defaultFocusBox

Draws a standard box based on the current theme

Box *const fltk::DIAMOND_DOWN_BOX = &diamondDownBox

Diamond shape used to draw Motif-style checkboxes.

Box *const fltk::DIAMOND_UP_BOX = &diamondUpBox

Raised diamond shape used to draw Motif-style checkboxes.

The dnd_* variables allow your fltk program to use the Xdnd protocol to manipulate files and interact with file managers. You can ignore these if you just want to drag & drop blocks of text. I have little information on how to use these, I just tried to clean up the Xlib interface and present the variables nicely.

The program can set this variable before returning non-zero for a DND_DRAG event to indicate what it will do to the object. Fltk presets this to XdndActionCopy so that is what is returned if you don't set it.

The action the source program wants to perform. Due to oddities in the Xdnd design this variable is not set on the fltk::DND_ENTER event, instead it is set on each DND_DRAG event, and it may change each time.

To print the string value of the Atom use this code:

char* x = XGetAtomName(xdisplay, dnd_source_action);

You can set this before calling fltk::dnd() to communicate a different action. See dnd_source_types, which you must also set.

Zero-terminated list of atoms describing the formats of the source data. This is set on the DND_ENTER event. The following code will print them all as text, a typical value is "text/plain;charset=UTF-8" (gag).

for (int i = 0; dnd_source_types[i]; i++) {
  char* x = XGetAtomName(xdisplay, dnd_source_types[i]);

You can set this and dnd_source_action before calling dnd() to change information about the source. You must set both of these, if you don't fltk will default to "text/plain" as the type and XdndActionCopy as the action. To set this change it to point at your own array. Only the first 3 types are sent. Also, FLTK has no support for reporting back what type the target requested, so all your types must use the same block of data.

The X id of the window being dragged from.

The program can set this when returning non-zero for a DND_RELEASE event to indicate the translation wanted. FLTK presets this to "text/plain" so that is returned if you don't set it (supposedly it should be limited to one of the values in dnd_source_types, but "text/plain" appears to always work).

Box *const fltk::DOWN_BOX = &downBox

Inset box in fltk's standard theme

Box *const fltk::EMBOSSED_BOX = &embossedBox

2-pixel thick raised line around edge.

Box *const fltk::ENGRAVED_BOX = &engravedBox

2-pixel thick engraved line around edge.

void(* fltk::error)(const char *format,...) = ::error

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.

The last timestamp from an X event that reported it (not all do). Many X calls (like cut and paste) need this value.

void(* fltk::fatal)(const char *format,...) = ::error

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

Box *const fltk::FLAT_BOX = &flatBox

Draws a flat rectangle of getbgcolor().

The single X GC used for all drawing. This is initialized by the first call to Window::make_current(). This may be removed if we use Cairo or XRender only.

Most Xlib drawing calls look like this:

XDrawSomething(xdisplay, xwindow, gc, ...);
const char *const fltk::help = helpmsg+13

This is a portion of the string printed by fltk::args() detects an invalid argument on the command-line. You can add this to your own error or help message to show the fltk switches. It's value is (no newline at start or the end):

 -d[isplay] host:n.n
 -g[eometry] WxH+X+Y
 -n[ame] windowname
 -bg color
Box *const fltk::HIGHLIGHT_DOWN_BOX = &highlightDownBox

Draws nothing normally, and as THIN_DOWN_BOX when the mouse pointer points at it or the value of the widget is turned on.

Box *const fltk::HIGHLIGHT_UP_BOX = &highlightUpBox

Draws nothing normally, and as THIN_UP_BOX when the mouse pointer points at it or the value of the widget is turned on.

This Style is used for the 50x50 icon area on the left of all the popup windows. You can change the colors or font used here.

This Style is used for the label area for all the popup windows. You can change the textfont() or textsize() to make them print differently.

This dummy 1x1 window is created by fltk::open_display() and is never destroyed. You can use it to communicate with the window manager or other programs.

const char * fltk::message_window_label = NULL

Set this to change the title of message(), alert(), ask(), choice(), etc. windows.

When this is set to true, then (all) message windows will use scrollbars if the given message is too long.

Set this to a positive value to cause the message(), alert(), ask(), choice(), etc. windows to close automatically after this timeout. If the timeout expires, -1 will be returned by the functions that return int. The timeout value is in seconds.

MSG fltk::msg

The most recent message read by GetMessage() (which is called by fltk::wait(). This may not be the most recent message sent to an FLTK window (because our fun-loving friends at MicroSoft decided that calling the handle procedures directly would be a good idea sometimes...)

const char * fltk::no = "&No"

You can change this string to convert fltk to a foreign language.

Box *const fltk::NO_BOX = &noBox

Draws nothing. Can be used as a box to make the background of a widget invisible. Also some widgets check specifically for this and change their behavior or drawing methods.

Box *const fltk::OFLAT_BOX = &ovalFlatBox

Ellipse with no border.

const char * fltk::ok = "&OK"

You can change this string to convert fltk to a foreign language.

Box *const fltk::OSHADOW_BOX = &ovalShadowBox

Ellipse with a black border and gray shadow.

Box *const fltk::OVAL_BOX = &ovalBox

Ellipse with a black border.

Box *const fltk::PLASTIC_DOWN_BOX = &plasticDownBox

Pushed in version of PLASTIC_UP_BOX

Box *const fltk::PLASTIC_UP_BOX = &plasticUpBox

Box designed to vaguely resemble a certain fruit-themed operating system.

Box *const fltk::RFLAT_BOX = &rflatBox

Round-cornered rectangle with no border.

Box *const fltk::ROUND_DOWN_BOX = &roundDownBox

Inset oval or circle.

Box *const fltk::ROUND_UP_BOX = &roundUpBox

Raised oval or circle.

Box *const fltk::ROUNDED_BOX = &roundedBox

Round-cornered rectangle with a black border.

Box *const fltk::RSHADOW_BOX = &rshadowBox

Round-cornered rectangle with a black border and gray shadow.

Box *const fltk::THIN_DOWN_BOX = &thinDownBox

1-pixel-thick inset box.

Box *const fltk::THIN_UP_BOX = &thinUpBox

1-pixel-thick raised box.

Box *const fltk::UP_BOX = &upBox

A up button in fltk's standard theme.

void(* fltk::warning)(const char *format,...) = ::warning

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.

Colormap fltk::xcolormap

The colormap being used by FLTK. This is needed as an argument for many Xlib calls. You can also set this immediately after open_display() is called to your own colormap. The function own_colormap() can be used to make FLTK create a private one. FLTK uses the same colormap for all windows and there is no way to change that, sorry.

Display * fltk::xdisplay = NULL

The open X display. This is needed as an argument to most Xlib calls. Don't attempt to change it! This is NULL before fltk::open_display() is called.

XEvent fltk::xevent

The most recent X event.

HPALETTE fltk::xpalette

If non-zero this is the palette alloced by fltk on an 8-bit screen. Hopefully you can ignore this, I'm not even sure it works anymore.

Which screen number to use. This is set by fltk::open_display() to the default screen. You can change it by setting this to a different value immediately afterwards.

XVisualInfo * fltk::xvisual

The X visual that FLTK will use for all windows. These are set by fltk::open_display() to the default visual. You can change them before calling Window::show() the first time. Typical code for changing the default visual is:

fltk::args(argc, argv); // do this first so $DISPLAY is set
fltk::xvisual = find_a_good_visual(fltk::xdisplay, fltk::xscreen);
if (!fltk::xvisual) fltk::abort(&quot;No good visual&quot;);
fltk::xcolormap = make_a_colormap(fltk::xdisplay, fltk::xvisual->visual, fltk::xvisual->depth);
// it is now ok to show() windows:
window->show(argc, argv);

A portable interface to get a TrueColor visual (which is probably the only reason to do this) is to call fltk::visual(int).

XWindow fltk::xwindow

Set by Window::make_current() and/or draw_into() to the window being drawn into. This may be different than the xid() of the window, as it may be the back buffer which has a different id.

const char * fltk::yes = "&Yes"

You can change this string to convert fltk to a foreign language.