2000-06-18 04:38:41 +04:00
|
|
|
<html><body>
|
|
|
|
|
|
|
|
|
|
<h1 align=right><a name=functions>B - Function Reference</A></h1>
|
|
|
|
|
|
2001-11-28 23:43:44 +03:00
|
|
|
This appendix describes all of the <tt>fl_</tt> functions. For a
|
|
|
|
|
description of the FLTK classes, see <A href="widgets.html">Appendix
|
|
|
|
|
A</A>.
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<h2>Functions</h2>
|
|
|
|
|
|
2002-04-09 13:38:15 +04:00
|
|
|
<h3><A name="fl_beep">void fl_beep(int type = FL_BEEP_DEFAULT)</A></h3>
|
|
|
|
|
|
|
|
|
|
<P>Sounds an audible notification; the default <CODE>type</CODE> argument
|
|
|
|
|
sounds a simple "beep" sound. Other values for <CODE>type</CODE> may use
|
|
|
|
|
a system or user-defined sound file:
|
|
|
|
|
|
|
|
|
|
<UL>
|
|
|
|
|
|
|
|
|
|
<LI><TT>FL_BEEP_DEFAULT</TT> - Make a generic "beep" sound.
|
|
|
|
|
|
|
|
|
|
<LI><TT>FL_BEEP_MESSAGE</TT> - Make a sound appropriate for an
|
|
|
|
|
informational message.
|
|
|
|
|
|
|
|
|
|
<LI><TT>FL_BEEP_ERROR</TT> - Make a sound appropriate for an
|
|
|
|
|
error message.
|
|
|
|
|
|
|
|
|
|
<LI><TT>FL_BEEP_QUESTION</TT> - Make a sound appropriate for
|
|
|
|
|
a question.
|
|
|
|
|
|
|
|
|
|
<LI><TT>FL_BEEP_PASSWORD</TT> - Make a sound appropriate for
|
|
|
|
|
a password prompt.
|
|
|
|
|
|
|
|
|
|
<LI><TT>FL_BEEP_NOTIFICATION</TT> - Make a sound appropriate for
|
|
|
|
|
an event notification ("you have mail", etc.)
|
|
|
|
|
|
|
|
|
|
</UL>
|
|
|
|
|
|
2000-06-18 04:38:41 +04:00
|
|
|
<h3><A name="fl_color_chooser_func">int fl_color_chooser(const char
|
|
|
|
|
*title, double &r, double &g, double &b)
|
2001-05-06 20:25:05 +04:00
|
|
|
<br>int fl_color_chooser(const char *title, uchar &r, uchar &g, uchar &b)</A></h3>
|
2000-06-18 04:38:41 +04:00
|
|
|
|
2002-04-09 13:38:15 +04:00
|
|
|
<P>The <CODE>double</CODE> version takes RGB values in the range
|
|
|
|
|
0.0 to 1.0. The <CODE>uchar</CODE> version takes RGB values in
|
|
|
|
|
the range 0 to 255. The <tt>title</tt> argument specifies the
|
|
|
|
|
label (title) for the window.
|
2000-05-17 11:09:26 +04:00
|
|
|
|
2001-05-06 20:25:05 +04:00
|
|
|
<p align=center><img src="fl_color_chooser.jpg" ALT="The fl_color_chooser dialog.">
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<P><tt>fl_color_chooser()</tt> 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 <A href=Fl_Value_Input.html#Fl_Value_Input><tt>
|
|
|
|
|
Fl_Value_Input</tt></A> 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).
|
|
|
|
|
|
|
|
|
|
<P>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.
|
|
|
|
|
|
|
|
|
|
<P>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
|
2001-10-01 00:25:36 +04:00
|
|
|
color the user picks! You can however use <A href="drawing.html#fast"><tt>
|
2000-06-18 04:38:41 +04:00
|
|
|
fl_rectf()</tt></A> to fill a region with a simulated color using
|
|
|
|
|
dithering.
|
|
|
|
|
|
|
|
|
|
<h3><A name=fl_show_colormap>int fl_show_colormap(int oldcol)</A></h3>
|
|
|
|
|
|
|
|
|
|
<tt>fl_show_colormap()</tt> pops up a panel of the 256 colors you can
|
2001-10-01 00:25:36 +04:00
|
|
|
access with <A href="drawing.html#fl_color"><tt>fl_color()</tt></A> and lets the user
|
2000-06-18 04:38:41 +04:00
|
|
|
pick one of them. It returns the new color index, or the old one if
|
|
|
|
|
the user types ESC or clicks outside the window.
|
2001-05-06 20:25:05 +04:00
|
|
|
<P ALIGN=CENTER><IMG src="fl_show_colormap.gif" ALT="The fl_show_colormap dialog">
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<h3><A name=fl_message>void fl_message(const char *, ...)</A></h3>
|
|
|
|
|
|
|
|
|
|
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 <tt>\n</tt> characters into it.
|
|
|
|
|
The enter key is a shortcut for the OK button.
|
2001-05-06 20:25:05 +04:00
|
|
|
<P ALIGN=CENTER><IMG src="fl_message.gif" ALT="The fl_message window.">
|
2000-06-18 04:38:41 +04:00
|
|
|
|
2001-10-01 00:25:36 +04:00
|
|
|
<h3><A name="fl_alert">void fl_alert(const char *, ...)</A></h3>
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
Same as <tt>fl_message()</tt> except for the "!" symbol.
|
2001-05-06 20:25:05 +04:00
|
|
|
<P ALIGN=CENTER><IMG src="fl_alert.gif" ALT="The fl_alert window">
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<h3><A name=fl_ask>int fl_ask(const char *, ...)</A></h3>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2001-05-06 20:25:05 +04:00
|
|
|
<p align=center><img src="fl_ask.gif" ALT="The fl_ask window.">
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<h3><A name=fl_choice2>int fl_choice(const char *q, const char *b0,
|
|
|
|
|
const char *b1, const char *b2, ...)</A></h3>
|
|
|
|
|
|
|
|
|
|
Shows the message with three buttons below it marked with the strings
|
|
|
|
|
<tt> b0</tt>, <tt>b1</tt>, and <tt>b2</tt>. Returns 0, 1, or 2
|
1999-01-27 11:45:11 +03:00
|
|
|
depending on which button is hit. ESC is a shortcut for button 0 and
|
|
|
|
|
the enter key is a shortcut for button 1. Notice the buttons are
|
|
|
|
|
positioned "backwards" You can hide buttons by passing
|
2000-06-18 04:38:41 +04:00
|
|
|
<tt>NULL</tt> as their labels.
|
|
|
|
|
|
2001-05-06 20:25:05 +04:00
|
|
|
<p align=center><img src="fl_choice.gif" ALT="The fl_choice window.">
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<h3><A name=fl_input2>const char *fl_input(const char *label, const char
|
|
|
|
|
*deflt = 0, ...)</A></h3>
|
|
|
|
|
|
|
|
|
|
Pops up a window displaying a string, lets the user edit it, and
|
|
|
|
|
return the new value. The cancel button returns <tt>NULL</tt>. <I>The
|
|
|
|
|
returned pointer is only valid until the next time <tt>fl_input()</tt>
|
|
|
|
|
is called</I>. Due to back-compatability, the arguments to any printf
|
|
|
|
|
commands in the label are after the default value.
|
|
|
|
|
|
2001-05-06 20:25:05 +04:00
|
|
|
<p align=center><img src="fl_input.gif" ALT="The fl_input window.">
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<h3><A name=fl_password>const char *fl_password(const char *label,
|
|
|
|
|
const char *deflt = 0, ...)</A></h3>
|
|
|
|
|
|
|
|
|
|
Same as <tt>fl_input()</tt> except an <A
|
|
|
|
|
href=Fl_Secret_Input.html><tt>Fl_Secret_Input</tt></A> field is used.
|
|
|
|
|
|
2001-05-06 20:25:05 +04:00
|
|
|
<p align=center><img src="fl_password.gif" ALT="The fl_password window.">
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<h3><A name=fl_message_font>void fl_message_font(Fl_Font fontid, uchar
|
|
|
|
|
size)</A></h3>
|
|
|
|
|
|
|
|
|
|
Change the font and font size used for the messages in all the popups.
|
|
|
|
|
|
|
|
|
|
<h3><A name=fl_message_icon>Fl_Widget *fl_message_icon()</A></h3>
|
|
|
|
|
|
|
|
|
|
Returns a pointer to the box at the left edge of all the popups. You
|
|
|
|
|
can alter the font, color, or label (including making it a Pixmap),
|
|
|
|
|
before calling the functions.
|
|
|
|
|
|
|
|
|
|
<h3><A name=fl_file_chooser>char *fl_file_chooser(const char * message,
|
|
|
|
|
const char *pattern, const char *fname)</A></h3>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2001-05-06 20:25:05 +04:00
|
|
|
<p align=center><img src="filechooser.gif" ALT="The fl_file_chooser window.">
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<tt>fl_file_chooser()</tt> pops up the file chooser, waits for the user
|
|
|
|
|
to pick a file or Cancel, and then returns a pointer to that filename
|
|
|
|
|
or <tt>NULL</tt> if Cancel is chosen.
|
|
|
|
|
|
|
|
|
|
<P><tt>message</tt> is a string used to title the window.
|
|
|
|
|
|
|
|
|
|
<P><tt>pattern</tt> is used to limit the files listed in a directory to
|
2002-03-26 00:08:42 +03:00
|
|
|
those matching the pattern. This matching is done by <A href=#fl_filename_match>
|
|
|
|
|
<tt>fl_filename_match()</tt></A>. Use <tt>NULL</tt> to show all files.
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
<P><tt>fname</tt> is a default filename to fill in the chooser with.
|
|
|
|
|
If this is <tt>NULL</tt> 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.
|
|
|
|
|
|
|
|
|
|
<P>The returned value points at a static buffer that is only good until
|
|
|
|
|
the next time <tt>fl_file_chooser()</tt> is called.
|
|
|
|
|
|
|
|
|
|
<h3><A name=fl_file_chooser_callback>void fl_file_chooser_callback(void
|
|
|
|
|
(*cb)(const char *))</A></h3>
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
<h3><A name=fl_filename_list>int fl_filename_list(const char *d, dirent
|
2000-06-18 04:38:41 +04:00
|
|
|
***list)</A></h3>
|
|
|
|
|
|
|
|
|
|
This is a portable and const-correct wrapper for the
|
|
|
|
|
<tt>fl_scandir</tt> function. <tt>d</tt> 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 <tt>*list</tt>. 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
|
|
|
|
|
<tt>errno</tt> has the reason (<tt>errno</tt> does not work under
|
|
|
|
|
WIN32). The files are sorted in "alphanumeric" order, where
|
|
|
|
|
an attempt is made to put unpadded numbers in consecutive order.
|
|
|
|
|
|
|
|
|
|
<P>You can free the returned list of files with the following code:
|
|
|
|
|
|
|
|
|
|
<ul><pre>for (int i = return_value; i > 0;) free((void*)(list[--i]));
|
|
|
|
|
free((void*)list);</pre></ul>
|
|
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
<h3><A name=fl_filename_isdir>int fl_filename_isdir(const char *f)</A></h3>
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
Returns non-zero if the file exists and is a directory.
|
|
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
<h3><A name=fl_filename_name>const char *fl_filename_name(const char *f)</A></h3>
|
2000-06-18 04:38:41 +04:00
|
|
|
|
|
|
|
|
Returns a pointer to the character after the last slash, or to the
|
|
|
|
|
start of the filename if there is none.
|
|
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
<h3><A name=fl_filename_ext>const char *fl_filename_ext(const char *f)</A></h3>
|
2000-06-18 04:38:41 +04:00
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
Returns a pointer to the last period in <tt>fl_filename_name(f)</tt>, or
|
2000-06-18 04:38:41 +04:00
|
|
|
a pointer to the trailing nul if none.
|
|
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
<h3><A name=fl_filename_setext>char *fl_filename_setext(char *f, const char
|
2000-06-18 04:38:41 +04:00
|
|
|
*ext)</A></h3>
|
|
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
Does <tt>strcpy(fl_filename_ext(f), ext ? ext : "")</tt>. Returns a
|
2000-06-18 04:38:41 +04:00
|
|
|
pointer to <tt>f</tt>.
|
|
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
<h3><A name=fl_filename_expand>int fl_filename_expand(char *out, const char
|
2000-06-18 04:38:41 +04:00
|
|
|
*in)</A></h3>
|
|
|
|
|
|
|
|
|
|
Splits <tt>in</tt> at each slash character. Replaces any occurrance
|
|
|
|
|
of <tt>$X</tt> with <tt>getenv("X")</tt> (leaving it as
|
|
|
|
|
<tt>$X</tt> if the environment variable does not exist). Replaces any
|
|
|
|
|
occurances of <tt> ~X</tt> with user <tt>X</tt>'s home directory
|
|
|
|
|
(leaving it as <tt>~X</tt> if the user does not exist). Any resulting
|
|
|
|
|
double slashes cause everything before the second slash to be deleted.
|
|
|
|
|
Copies the result to <tt> out</tt> (<tt>in</tt> and <tt>out</tt> may
|
|
|
|
|
be the same buffer). Returns non-zero if any changes were made. <I>In
|
|
|
|
|
true retro programming style, it is up to you to provide a buffer big
|
|
|
|
|
enough for the result. 1024 characters should be enough.</I>
|
|
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
<h3><A name=fl_filename_absolute>int fl_filename_absolute(char *out, const
|
2000-06-18 04:38:41 +04:00
|
|
|
char *in)</A></h3>
|
|
|
|
|
|
|
|
|
|
If <tt>in</tt> does not start with a slash, this prepends the current
|
|
|
|
|
working directory to <tt>in</tt> and then deletes any occurances of <tt>
|
|
|
|
|
.</tt> and x/.. from the result, which it copies to <tt>out</tt> (<tt>in</tt>
|
|
|
|
|
and <tt>out</tt> may be the same buffer). Returns non-zero if any
|
|
|
|
|
changes were made. <I>In true retro programming style, it is up to you
|
|
|
|
|
to provide a buffer big enough for the result. 1024 characters should
|
1999-01-13 22:28:54 +03:00
|
|
|
be enough.</I>
|
2000-06-18 04:38:41 +04:00
|
|
|
|
2002-03-26 00:08:42 +03:00
|
|
|
<h3><A name=fl_filename_match>int fl_filename_match(const char *f, const char
|
2000-06-18 04:38:41 +04:00
|
|
|
*pattern)</A></h3>
|
|
|
|
|
|
|
|
|
|
Returns true if <tt>f</tt> matches <tt>pattern</tt>. The following
|
|
|
|
|
syntax is used by <tt>pattern</tt>:
|
|
|
|
|
|
1999-01-13 22:28:54 +03:00
|
|
|
<UL>
|
2000-06-18 04:38:41 +04:00
|
|
|
<LI><tt>*</tt> matches any sequence of 0 or more characters. </LI>
|
|
|
|
|
<LI><tt>?</tt> matches any single character. </LI>
|
|
|
|
|
<LI><tt>[set]</tt> 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
|
1999-01-13 22:28:54 +03:00
|
|
|
the first characters. </LI>
|
2000-06-18 04:38:41 +04:00
|
|
|
<LI><tt>[^set] or <B>[!set]</B></tt> matches any character not in the
|
1999-01-13 22:28:54 +03:00
|
|
|
set. </LI>
|
2000-06-18 04:38:41 +04:00
|
|
|
<LI><tt>{X|Y|Z} or <B>{X,Y,Z}</B></tt> matches any one of the
|
1999-01-13 22:28:54 +03:00
|
|
|
subexpressions literally. </LI>
|
2000-06-18 04:38:41 +04:00
|
|
|
<LI><tt>\x</tt> quotes the character x so it has no special meaning. </LI>
|
|
|
|
|
<LI><tt>x</tt> all other characters must be matched exactly. </LI>
|
1999-01-13 22:28:54 +03:00
|
|
|
</UL>
|
2000-06-18 04:38:41 +04:00
|
|
|
|
2001-11-28 23:43:44 +03:00
|
|
|
</body>
|
|
|
|
|
</html>
|
