The FLTK "Environement"
Fltk provides enough "environment" functions that the demo programs
can be made to work. Unlike other toolkits, fltk tries to sepearte the
user environment from the actual widgets: these functions are for
convienence only, they are not really part of the core of fltk. If
you don't like the way they look, copy the code and modify to to what
you want. Most likely any real environment built atop fltk, such as
FLEK, will replace all these functions.
FLTK provides an entirely optional command-line switch parser.
You don't have to call it if you don't like them! Everything it can do
can be done with other calls to FLTK.
To use the switch parser, call fltk::args(...) 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 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:
- -display host:n.n The X display to use (ignored under
WIN32).
- -geometry WxH Window is resized to this width & height
- -geometry +X+Y Initial window position
- -geometry WxH+X+Y Window is resized and positioned.
- -name string fltk::Window::xclass(string) will be
done to the window, possibly changing its icon.
- -title string fltk::Window::label(string) will be done
to the window, changing both its title and the icontitle.
- -iconic fltk::Window::iconize() will be done to
the window.
- -bg color XParseColor is used to lookup the passed color
and then fltk::background() is
done. Under WIN32 only color names of the form "#xxxxxx"
are understood.
- -theme name NYI. Names a plugin that fltk will load
automatically and set the fltk::theme()
pointer to any function in the plugin called "fltk_theme". ".theme" is
added to the name to get the filename of the plugin, and if it
does not start with a slash it is tried relative to "~/.fltk".
- -scheme name NYI. This string is stored and theme plugins
can refer to it and use it to alter their behavior. Typically it is
used to name a file the theme reads.
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).
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.
This is the usage string that is displayed if fltk::args() detects an invalid argument on
the command-line. It's value is:
" -d[isplay] host:n.n\n"
" -g[eometry] WxH+X+Y\n"
" -n[ame] windowname\n"
" -i[conic]\n"
" -bg color";

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.
The double version takes and returns RGB values in the range 0.0 to
1.0. The uchar version takes RGB values in the range 0 to 255.
If you use the color chooser on an 8-bit screen, it will allocate
all the available colors, leaving you no space to exactly represent the
color the user picks! You can however use
fltk::rectf() to fill a region with a simulated color using
dithering.
fltk::show_colormap() pops up a panel of the 256 colors you can
access with "indexed" fltk::Color
values and lets the user pick one of them. It returns the new color
index, or the old one if the user types ESC or clicks outside the window.

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.

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

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.

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
button 0. Notice the buttons are positioned "backwards" You
can hide buttons by passing NULL as their labels.

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.

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

Change the font and font size used for the messages in all the popups.
Sets the widget that will be displayed as the icon for all the popups. Any
widget with any label can be created and used as the icon, including widgets
with callbacks! Calling this function with NULL will reset the
icons to the FLTK default.
FLTK provides a "tab completion" file chooser that makes it easy to
choose files from large directories. This file chooser has several
unique features, the major one being that the Tab key completes
filenames like it does in Emacs or tcsh, and the list always shows all
possible completions.

fltk::file_chooser() 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.
message is a string used to title the window.
pattern is 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.
fname is a default filename to fill in the chooser with.
If this is NULL then the last filename that was choosen is
used (unless that had a different pattern, in which case just the last
directory with no name is used). The first time the file chooser is
called this defaults to a blank string.
The returned value points at a static buffer that is only good until
the next time fltk::file_chooser() is called.
Set a function that is called every time the user clicks a file in the
currently popped-up file chooser. This could be used to preview the
contents of the file. It has to be reasonably fast, and cannot create
FLTK windows.
This is a portable and const-correct wrapper for the
fltk::scandir function. d is the name of a directory
(it does not matter if it has a trailing slash or not). For each file
in that directory a "dirent" structure is created. The only
portable thing about a dirent is that dirent.d_name is the
nul-terminated file name. An array of pointers to these dirents is
created and a pointer to the array is returned in *list. The
number of entries is given as a return value. If there is an error
reading the directory a number less than zero is returned, and
errno has the reason (errno does not work under
WIN32). The files are sorted in "alphanumeric" order, where
an attempt is made to put unpadded numbers in consecutive order.
You can free the returned list of files with the following code:
for (int i = return_value; i > 0;) free((void*)(list[--i]));
free((void*)list);
Returns non-zero if the file exists and is a directory.
Returns a pointer to the character after the last slash, or to the
start of the filename if there is none.
Returns a pointer to the last period in filename_name(f), or
a pointer to the trailing nul if none.
Does strcpy(filename_ext(f), ext ? ext : ""). Returns a
pointer to f.
Splits in at each slash character. Replaces any occurrance
of $X with getenv("X") (leaving it as $X if
the environment variable does not exist). Replaces any occurances of
~X with user X's home directory (leaving it as ~X
if the user does not exist). Any resulting double slashes cause
everything before the second slash to be deleted. Copies the result to
out (in and out may be the same buffer).
Returns non-zero if any changes were made. In true retro
programming style, it is up to you to provide a buffer big enough for
the result. 1024 characters should be enough.
If in does not start with a slash, this prepends the current
working directory to in and then deletes any occurances of
. and x/.. from the result, which it copies to out (in
and out may be the same buffer). Returns non-zero if any
changes were made. In true retro programming style, it is up to you
to provide a buffer big enough for the result. 1024 characters should
be enough.
Returns true if f matches pattern. The following
syntax is used by pattern:
- * 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.
- \x quotes the character x so it has no special meaning.
- x all other characters must be matched exactly.