336996c7ab
and errors reported by HTML Tidy. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.0@1454 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
1093 lines
46 KiB
HTML
1093 lines
46 KiB
HTML
<html><body>
|
|
|
|
<h1 align=right><a name=functions>B - Function Reference</A></h1>
|
|
|
|
This appendix describes all of the <tt>fl_</tt> functions and <tt>Fl::</tt>
|
|
methods. For a description of the FLTK widgets, see <A
|
|
href=widgets.html#widgets> Appendix A</A>.
|
|
|
|
<h2>Functions</h2>
|
|
|
|
<h3><A name="fl_color_chooser_func">int fl_color_chooser(const char
|
|
*title, double &r, double &g, double &b)
|
|
<br>int fl_color_chooser(const char *title, uchar &r, uchar &g, uchar &b)</A></h3>
|
|
|
|
The double version takes RGB values in the range 0.0 to 1.0. The
|
|
uchar version takes RGB values in the range 0 to 255. The <tt>title</tt>
|
|
argument specifies the label (title) for the window.
|
|
|
|
<p align=center><img src="fl_color_chooser.jpg" ALT="The fl_color_chooser dialog.">
|
|
|
|
<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
|
|
color the user picks! You can however use <A href=#fl_rectf><tt>
|
|
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
|
|
access with <A href=#fl_color><tt>fl_color()</tt></A> 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.
|
|
<P ALIGN=CENTER><IMG src="fl_show_colormap.gif" ALT="The fl_show_colormap dialog">
|
|
|
|
<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.
|
|
<P ALIGN=CENTER><IMG src="fl_message.gif" ALT="The fl_message window.">
|
|
|
|
<h3><A name=fl_>void fl_alert(const char *, ...)</A></h3>
|
|
|
|
Same as <tt>fl_message()</tt> except for the "!" symbol.
|
|
<P ALIGN=CENTER><IMG src="fl_alert.gif" ALT="The fl_alert window">
|
|
|
|
<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.
|
|
|
|
<p align=center><img src="fl_ask.gif" ALT="The fl_ask window.">
|
|
|
|
<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
|
|
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
|
|
<tt>NULL</tt> as their labels.
|
|
|
|
<p align=center><img src="fl_choice.gif" ALT="The fl_choice window.">
|
|
|
|
<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.
|
|
|
|
<p align=center><img src="fl_input.gif" ALT="The fl_input window.">
|
|
|
|
<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.
|
|
|
|
<p align=center><img src="fl_password.gif" ALT="The fl_password window.">
|
|
|
|
<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.
|
|
|
|
<p align=center><img src="filechooser.gif" ALT="The fl_file_chooser window.">
|
|
|
|
<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
|
|
those matching the pattern. This matching is done by <A href=#filename_match>
|
|
<tt>filename_match()</tt></A>. Use <tt>NULL</tt> to show all files.
|
|
|
|
<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.
|
|
|
|
<h3><A name=filename_list>int filename_list(const char *d, dirent
|
|
***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>
|
|
|
|
<h3><A name=filename_isdir>int filename_isdir(const char *f)</A></h3>
|
|
|
|
Returns non-zero if the file exists and is a directory.
|
|
|
|
<h3><A name=filename_name>const char *filename_name(const char *f)</A></h3>
|
|
|
|
Returns a pointer to the character after the last slash, or to the
|
|
start of the filename if there is none.
|
|
|
|
<h3><A name=filename_ext>const char *filename_ext(const char *f)</A></h3>
|
|
|
|
Returns a pointer to the last period in <tt>filename_name(f)</tt>, or
|
|
a pointer to the trailing nul if none.
|
|
|
|
<h3><A name=filename_setext>char *filename_setext(char *f, const char
|
|
*ext)</A></h3>
|
|
|
|
Does <tt>strcpy(filename_ext(f), ext ? ext : "")</tt>. Returns a
|
|
pointer to <tt>f</tt>.
|
|
|
|
<h3><A name=filename_expand>int filename_expand(char *out, const char
|
|
*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>
|
|
|
|
<h3><A name=filename_absolute>int filename_absolute(char *out, const
|
|
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
|
|
be enough.</I>
|
|
|
|
<h3><A name=filename_match>int filename_match(const char *f, const char
|
|
*pattern)</A></h3>
|
|
|
|
Returns true if <tt>f</tt> matches <tt>pattern</tt>. The following
|
|
syntax is used by <tt>pattern</tt>:
|
|
|
|
<UL>
|
|
<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
|
|
the first characters. </LI>
|
|
<LI><tt>[^set] or <B>[!set]</B></tt> matches any character not in the
|
|
set. </LI>
|
|
<LI><tt>{X|Y|Z} or <B>{X,Y,Z}</B></tt> matches any one of the
|
|
subexpressions literally. </LI>
|
|
<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>
|
|
</UL>
|
|
|
|
<h2>Fl:: Methods</h2>
|
|
|
|
<h3><A name=add_fd>static void Fl::add_fd(int fd, void (*cb)(int, void
|
|
*), void* = 0)
|
|
<br>static void Fl::add_fd(int fd, int when, void (*cb)(int, void*),
|
|
void* = 0)</A>
|
|
<br><A name=remove_fd>static void Fl::remove_fd(int)</A></h3>
|
|
|
|
Add file descriptor <tt>fd</tt> to listen to. When the <tt>fd</tt>
|
|
becomes ready for reading <tt>Fl::wait()</tt> will call the callback
|
|
and then return. The callback is
|
|
passed the <tt>fd</tt> and the arbitrary <tt>void*</tt> argument.
|
|
|
|
<P>The second version takes a <tt>when</tt> bitfield, with the bits
|
|
<tt>FL_READ</tt>, <tt>FL_WRITE</tt>, and <tt>FL_EXCEPT</tt> defined,
|
|
to indicate when the callback should be done.
|
|
|
|
<P>There can only be one callback of each type for a file descriptor. <tt>
|
|
Fl::remove_fd()</tt> gets rid of <I>all</I> the callbacks for a given
|
|
file descriptor.
|
|
|
|
<P>Under UNIX <I>any</I> file descriptor can be monitored (files,
|
|
devices, pipes, sockets, etc.) Due to limitations in Microsoft Windows,
|
|
WIN32 applications can only monitor sockets.
|
|
|
|
<h3><A name=add_handler>static void Fl::add_handler(int (*f)(int))</A></h3>
|
|
|
|
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. Events that cause
|
|
this to be called are:
|
|
|
|
<UL>
|
|
<LI><tt>FL_SHORTCUT</tt> events that are not recognized by any widget.
|
|
This lets you provide global shortcut keys. </LI>
|
|
<LI>System events that FLTK does not recognize. See <A href=osissues.html#fl_xevent>
|
|
<tt>fl_xevent</tt></A>. </LI>
|
|
<LI><I>Some</I> other events when the widget FLTK selected returns
|
|
zero from its <tt>handle()</tt> method. Exactly which ones may change
|
|
in future versions, however. </LI>
|
|
</UL>
|
|
|
|
<h3><A name=add_idle>static Fl::add_idle(void (*cb)(void*), void*)</A></h3>
|
|
|
|
Adds a callback function that is called every time by
|
|
<tt>Fl::wait()</tt> and also makes it act as though the timeout is
|
|
zero (this makes <tt>Fl::wait()</tt> 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.
|
|
|
|
<P>You can have multiple idle callbacks. To remove an idle callback use <A
|
|
href=#remove_idle><tt>Fl::remove_idle()</tt></A>.
|
|
|
|
<P><tt>Fl::wait()</tt> and <tt>Fl::check()</tt> call idle callbacks,
|
|
but <tt>Fl::ready()</tt> does not.
|
|
|
|
<P>The idle callback can call any FLTK functions, including
|
|
<tt>Fl::wait()</tt>, <tt>Fl::check()</tt>, and <tt>Fl::ready()</tt>.
|
|
Fltk will not recursively call the idle callback.
|
|
|
|
<h3><A name=add_timeout>static void Fl::add_timeout(float t, void (*cb)(void*),void*v=0)</A></h3>
|
|
|
|
Add a one-shot timeout callback. The function will be called by
|
|
<tt>Fl::wait()</tt> at <i>t</i> seconds after this function is called.
|
|
The optional <tt>void*</tt> argument is passed to the callback.
|
|
|
|
<h3><A name=repeat_timeout>static void Fl::repeat_timeout(float t, void (*cb)(void*),void*v=0)</A></h3>
|
|
|
|
Inside a timeout callback you can call this to add another timeout.
|
|
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 <i>t</i> seconds, as the real timeout will be reduced to zero).
|
|
|
|
<p>It is undefined what this does if called from outside a timeout
|
|
callback.
|
|
|
|
<P>This code will print "TICK" each second on stdout, with a
|
|
fair degree of accuracy:
|
|
|
|
<UL><PRE>void callback(void*) {
|
|
printf("TICK\n");
|
|
Fl::repeat_timeout(1.0,callback);
|
|
}
|
|
|
|
main() {
|
|
Fl::add_timeout(1.0,callback);
|
|
return Fl::run();
|
|
}</PRE></UL>
|
|
|
|
<h3><A name=add_timeout>static void Fl::add_check(void (*cb)(void*),void*v=0)</A></h3>
|
|
|
|
Fltk will call this callback just before it flushes the display and
|
|
waits for events. This is different than an idle callback because it
|
|
is only called once, then fltk calls the system and tells it not to
|
|
return until an event happens.
|
|
|
|
<p>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.
|
|
|
|
<p>Sample code:
|
|
|
|
<ul><pre>bool state_changed; // anything that changes the display turns this on
|
|
|
|
void callback(void*) {
|
|
if (!state_changed) return;
|
|
state_changed = false;
|
|
do_expensive_calculation();
|
|
widget->redraw();
|
|
}
|
|
|
|
main() {
|
|
Fl::add_check(1.0,callback);
|
|
return Fl::run();
|
|
}</pre></ul>
|
|
|
|
<h3><A name=arg>static int Fl::arg(int argc, char **argv, int &i)</A></h3>
|
|
|
|
Consume a single switch from <tt>argv</tt>, 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 <tt>i</tt>. You can use this
|
|
function if you prefer to control the incrementing through the
|
|
arguments yourself.
|
|
|
|
<h3><A name=args>static int Fl::args(int argc, char **argv, int &i, int
|
|
(*callback)(int, char**,int &)=0)
|
|
<BR>void Fl::args(int argc, char **argv)</A></h3>
|
|
|
|
FLTK provides an <I>entirely optional</I> 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.
|
|
|
|
<P>To use the switch parser, call <tt>Fl::args(...)</tt> near the start
|
|
of your program. This does <I>not</I> open the display, instead
|
|
switches that need the display open are stashed into static variables.
|
|
Then you <I>must</I> display your first window by calling <A href=Fl_Window.html#Fl_Window.show>
|
|
window->show(argc,argv)</A>, which will do anything stored in the
|
|
static variables.
|
|
|
|
<P><tt>callback</tt> lets you define your own switches. It is called
|
|
with the same <tt>argc</tt> and <tt>argv</tt>, and with <tt>i</tt> the
|
|
index of each word. The callback should return zero if the switch is
|
|
unrecognized, and not change <tt>i</tt>. It should return non-zero if
|
|
the switch is recognized, and add at least 1 to <tt>i</tt> (it can add
|
|
more to consume words after the switch). This function is called
|
|
<i>before</i> any other tests, so <i>you can override any FLTK
|
|
switch</i> (this is why fltk can use very short switches instead of
|
|
the long ones all other toolkits force you to use).
|
|
|
|
<P>On return <tt>i</tt> is set to the index of the first non-switch.
|
|
This is either:
|
|
|
|
<UL>
|
|
<LI>The first word that does not start with '-'. </LI>
|
|
<LI>The word '-' (used by many programs to name stdin as a file) </LI>
|
|
<LI>The first unrecognized switch (return value is 0). </LI>
|
|
<LI><tt>argc</tt></LI>
|
|
</UL>
|
|
The return value is <tt>i</tt> 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 <tt>argc</tt>.
|
|
|
|
<P>All switches except -bg2 may be abbreviated one letter and case is ignored:
|
|
|
|
<UL>
|
|
<LI><tt>-display host:n.n</tt> The X display to use (ignored under
|
|
WIN32). </LI>
|
|
<LI><tt>-geometry WxH+X+Y</tt> The window position and size will be
|
|
modified according the the standard X geometry string. </LI>
|
|
<LI><tt>-name string</tt> Fl_Window::xclass(string) will be done to
|
|
the window, possibly changing its icon. </LI>
|
|
<LI><tt>-title string</tt> Fl_Window::label(string) will be done to
|
|
the window, changing both its title and the icontitle. </LI>
|
|
<LI><tt>-iconic</tt> Fl_Window::iconize() will be done to the window. </LI>
|
|
<LI><tt>-bg color</tt> XParseColor is used to lookup the passed color
|
|
and then Fl::background() is done. Under WIN32 only color names of
|
|
the form "#xxxxxx" are understood. </LI>
|
|
<LI><tt>-bg2 color</tt> XParseColor is used to lookup the passed color
|
|
and then Fl::background2() is done. </LI>
|
|
<LI><tt>-fg color</tt> XParseColor is used to lookup the passed color
|
|
and then Fl::foreground() is done. </LI>
|
|
</UL>
|
|
|
|
The second form of <tt>Fl::args()</tt> 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 <tt>Fl::abort(Fl::help)</tt>.
|
|
|
|
<h3><A name=background>static void Fl::background(uchar, uchar, uchar)</A>
|
|
</h3>
|
|
|
|
Changes <tt>fl_color(FL_GRAY)</tt> to the given color, and changes the
|
|
gray ramp from 32 to 56 to black to white. These are the colors used
|
|
as backgrounds by almost all widgets and used to draw the edges of all
|
|
the boxtypes.
|
|
|
|
<h3><A name=background2>static void Fl::background2(uchar, uchar, uchar)</A>
|
|
</h3>
|
|
|
|
Changes <tt>fl_color(FL_WHITE)</tt> and the same colors as <tt>
|
|
Fl::foreground()</tt>. This color is used as a background by <tt>
|
|
Fl_Input</tt> and other text widgets.
|
|
|
|
<h3><A name=belowmouse>static Fl_Widget *Fl::belowmouse() const
|
|
<br>static void Fl::belowmouse(Fl_Widget *)</A></h3>
|
|
|
|
Get or set the widget that is below the mouse. This is for
|
|
highlighting buttons. It is not used to send <tt>FL_PUSH</tt> or <tt>
|
|
FL_MOVE</tt> directly, for several obscure reasons, but those events
|
|
typically go to this widget. This is also the first widget tried for <tt>
|
|
FL_SHORTCUT</tt> events.
|
|
|
|
<P>If you change the belowmouse widget, the previous one and all
|
|
parents (that don't contain the new widget) are sent <tt>FL_LEAVE</tt>
|
|
events. Changing this does <I>not</I> send <tt>FL_ENTER</tt> to this
|
|
or any widget, because sending <tt>FL_ENTER</tt> is supposed to <I>test</I>
|
|
if the widget wants the mouse (by it returning non-zero from <tt>
|
|
handle()</tt>).
|
|
|
|
<h3><A name=box_dh>static int Fl::box_dh(Fl_Boxtype)</A></h3>
|
|
|
|
Returns the height offset for the given boxtype.
|
|
|
|
<h3><A name=box_dw>static int Fl::box_dw(Fl_Boxtype)</A></h3>
|
|
|
|
Returns the width offset for the given boxtype.
|
|
|
|
<h3><A name=box_dx>static int Fl::box_dx(Fl_Boxtype)</A></h3>
|
|
|
|
Returns the X offset for the given boxtype.
|
|
|
|
<h3><A name=box_dy>static int Fl::box_dy(Fl_Boxtype)</A></h3>
|
|
|
|
Returns the Y offset for the given boxtype.
|
|
|
|
<h3><A name=check>static int Fl::check()</A></h3>
|
|
|
|
Same as <tt>Fl::wait(0)</tt>. Calling this during a big calculation
|
|
will keep the screen up to date and the interface responsive:
|
|
|
|
<ul><pre>while (!calculation_done()) {
|
|
calculate();
|
|
Fl::check();
|
|
if (user_hit_abort_button()) break;
|
|
}</pre></ul>
|
|
|
|
The returns non-zero if any windows are displayed, and 0 if no
|
|
windows are displayed (this is likely to change in future versions of
|
|
fltk).
|
|
|
|
<h3><A name=damage>static int Fl::damage()</A></h3>
|
|
|
|
If true then <A href=#flush><tt>flush()</tt></A> will do something.
|
|
|
|
<h3><A name=display>static void Fl::display(const char *)</A></h3>
|
|
|
|
Sets the X display to use for all windows. Actually this just sets
|
|
the environment variable $DISPLAY to the passed string, so this only
|
|
works before you show() the first window or otherwise open the display,
|
|
and does nothing useful under WIN32.
|
|
|
|
<h3><A name=enable_symbols>static void Fl::enable_symbols()</A></h3>
|
|
|
|
Enables the symbol drawing code.
|
|
|
|
<h3><A name=event_button>static int Fl::event_button()</A></h3>
|
|
|
|
Returns which mouse button was pressed. This returns garbage if the
|
|
most recent event was not a <tt>FL_PUSH</tt> or <tt>FL_RELEASE</tt>
|
|
event.
|
|
|
|
<h3><A name=event_clicks>int Fl::event_clicks()
|
|
<br>void Fl::event_clicks(int)</A></h3>
|
|
|
|
The first form returns non-zero if the most recent <tt>FL_PUSH</tt> or
|
|
<tt>FL_KEYBOARD</tt> was a "double click". Returns N-1 for
|
|
N clicks. A double click is counted if the same button is pressed
|
|
again while <tt>event_is_click()</tt> is true.
|
|
|
|
<P>The second form directly sets the number returned by <tt>
|
|
Fl::event_clicks()</tt>. This can be used to set it to zero so that
|
|
later code does not think an item was double-clicked.
|
|
|
|
<h3><A name=event_inside>int Fl::event_inside(const Fl_Widget *) const
|
|
<br>int Fl::event_inside(int x, int y, int w, int h)</A></h3>
|
|
|
|
Returns non-zero if the current <tt>event_x</tt> and <tt>event_y</tt>
|
|
put it inside the widget or inside an arbitrary bounding box. You
|
|
should always call this rather than doing your own comparison so you
|
|
are consistent about edge effects.
|
|
|
|
<h3><A name=event_is_click>int Fl::event_is_click()
|
|
<br>void Fl::event_is_click(0)</A></h3>
|
|
|
|
The first form returns non-zero if the mouse has not moved far enough
|
|
and not enough time has passed since the last <tt>FL_PUSH</tt> or <tt>
|
|
FL_KEYBOARD</tt> event for it to be considered a "drag" rather than a
|
|
"click". You can test this on <tt>FL_DRAG</tt>, <tt>FL_RELEASE</tt>,
|
|
and <tt>FL_MOVE</tt> events. The second form clears the value returned
|
|
by <tt>Fl::event_is_click()</tt>. Useful to prevent the <I>next</I>
|
|
click from being counted as a double-click or to make a popup menu
|
|
pick an item with a single click. Don't pass non-zero to this.
|
|
|
|
<h3><A name=event_key>int Fl::event_key()
|
|
<br>int Fl::event_key(int)</A>
|
|
<br><A name=get_key>int Fl::get_key(int)</A></h3>
|
|
|
|
<tt>Fl::event_key()</tt> returns which key on the keyboard was last
|
|
pushed. It returns zero if the last event was not a key press or release.
|
|
|
|
<P><tt>Fl::event_key(int)</tt> returns true if the given key was held
|
|
down (or pressed) <I>during</I> the last event. This is constant until
|
|
the next event is read from the server.
|
|
|
|
<P><tt>Fl::get_key(int)</tt> returns true if the given key is held down <I>
|
|
now</I>. Under X this requires a round-trip to the server and is <I>
|
|
much</I> slower than <tt>Fl::event_key(int)</tt>.
|
|
|
|
<P>Keys are identified by the <I>unshifted</I> values. FLTK defines a
|
|
set of symbols that should work on most modern machines for every key
|
|
on the keyboard:
|
|
|
|
<UL>
|
|
<LI>All keys on the main keyboard producing a printable ASCII
|
|
character use the value of that ASCII character (as though shift,
|
|
ctrl, and caps lock were not on). The space bar is 32. </LI>
|
|
<LI>All keys on the numeric keypad producing a printable ASCII
|
|
character use the value of that ASCII character plus <tt>FL_KP</tt>.
|
|
The highest possible value is <tt>FL_KP_Last</tt> so you can
|
|
range-check to see if something is on the keypad. </LI>
|
|
<LI>All numbered function keys use the number on the function key plus <tt>
|
|
FL_F</tt>. The highest possible number is <tt>FL_F_Last</tt>, so you
|
|
can range-check a value. </LI>
|
|
<LI>Buttons on the mouse are considered keys, and use the button
|
|
number (where the left button is 1) plus <tt>FL_Button</tt>. </LI>
|
|
<LI>All other keys on the keypad have a symbol: <tt>FL_Escape,
|
|
FL_BackSpace, FL_Tab, FL_Enter, FL_Print, FL_Scroll_Lock, FL_Pause,
|
|
FL_Insert, FL_Home, FL_Page_Up, FL_Delete, FL_End, FL_Page_Down,
|
|
FL_Left, FL_Up, FL_Right, FL_Down, FL_Shift_L, FL_Shift_R,
|
|
FL_Control_L, FL_Control_R, FL_Caps_Lock, FL_Alt_L, FL_Alt_R,
|
|
FL_Meta_L, FL_Meta_R, FL_Menu, FL_Num_Lock, FL_KP_Enter</tt>. Be
|
|
careful not to confuse these with the very similar, but all-caps,
|
|
symbols used by <A href=events.html#event_state><tt>Fl::event_state()</tt>
|
|
</A>. </LI>
|
|
</UL>
|
|
|
|
On X <tt>Fl::get_key(FL_Button+n)</tt> does not work.
|
|
|
|
<P>On WIN32 <tt>Fl::get_key(FL_KP_Enter)</tt> and <tt>
|
|
Fl::event_key(FL_KP_Enter)</tt> do not work.
|
|
|
|
<h3><A name=event_length>char *Fl::event_length()</A></h3>
|
|
|
|
Returns the length of the text in <tt>Fl::event_text()</tt>. 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.
|
|
|
|
<h3><A name=event_state>ulong Fl::event_state()
|
|
<br>unsigned int Fl::event_state(ulong)</A></h3>
|
|
|
|
This is a bitfield of what shift states were on and what mouse buttons
|
|
were held down during the most recent event. The second version
|
|
returns non-zero if any of the passed bits are turned on. The legal
|
|
bits are:
|
|
|
|
<UL>
|
|
<LI><tt>FL_SHIFT</tt></LI>
|
|
<LI><tt>FL_CAPS_LOCK</tt></LI>
|
|
<LI><tt>FL_CTRL</tt></LI>
|
|
<LI><tt>FL_ALT</tt></LI>
|
|
<LI><tt>FL_NUM_LOCK</tt></LI>
|
|
<LI><tt>FL_META</tt></LI>
|
|
<LI><tt>FL_SCROLL_LOCK</tt></LI>
|
|
<LI><tt>FL_BUTTON1</tt></LI>
|
|
<LI><tt>FL_BUTTON2</tt></LI>
|
|
<LI><tt>FL_BUTTON3</tt></LI>
|
|
</UL>
|
|
|
|
X servers do not agree on shift states, and FL_NUM_LOCK, FL_META, and
|
|
FL_SCROLL_LOCK may not work. The values were selected to match the
|
|
XFree86 server on Linux. In addition there is a bug in the way X works
|
|
so that the shift state is not correctly reported until the first event <I>
|
|
after</I> the shift key is pressed or released.
|
|
|
|
<h3><A name=event_text>char *Fl::event_text()</A></h3>
|
|
|
|
Returns the ASCII text (in the future this may be UTF-8) produced by
|
|
the last <tt>FL_KEYBOARD</tt> or <tt>FL_PASTEM</tt> 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.
|
|
|
|
<P>Under X this is the result of calling <tt>XLookupString()</tt>.
|
|
|
|
<h3><A name=event_x>static int Fl::event_x()
|
|
<br><A name=event_y>static int Fl::event_y()</A></A></h3>
|
|
|
|
Returns the mouse position of the event relative to the <tt>Fl_Window</tt>
|
|
it was passed to.
|
|
|
|
<h3><A name=event_x_root>static int Fl::event_x_root()
|
|
<br><A name=event_y_root>static int Fl::event_y_root()</A></A></h3>
|
|
|
|
Returns the mouse position on the screen of the event. To find the
|
|
absolute position of an <tt>Fl_Window</tt> on the screen, use the
|
|
difference between <tt>event_x_root(),event_y_root()</tt> and <tt>
|
|
event_x(),event_y()</tt>.
|
|
|
|
<h3><A name=first_window>static Fl_Window *Fl::first_window()</A></h3>
|
|
|
|
Returns the first top-level window in the list of shown() windows. If
|
|
a modal() window is shown this is the top-most modal window, otherwise
|
|
it is the most recent window to get an event.
|
|
|
|
<h3><A name=next_window>static Fl_Window *Fl::next_window(Fl_Window *)</A></h3>
|
|
|
|
Returns the next top-level window in the list of shown() windows. You can
|
|
use this call to iterate through all the windows that are shown().
|
|
|
|
<h3>static void Fl::first_window(Fl_Window*)</h3>
|
|
|
|
Sets the window that is returned by first_window. The window is
|
|
removed from wherever it is in the list and inserted at the top. This
|
|
is not done if Fl::modal() is on or if the window is not shown().
|
|
Because the first window is used to set the "parent" of modal windows,
|
|
this is often useful.
|
|
|
|
<h3><A name=flush>static void Fl::flush()</A></h3>
|
|
|
|
Causes all the windows that need it to be redrawn and graphics forced
|
|
out through the pipes. This is what <tt>wait()</tt> does before
|
|
looking for events.
|
|
|
|
<h3><A name=focus>static Fl_Widget *Fl::focus() const
|
|
<br>static void Fl::focus(Fl_Widget *)</A></h3>
|
|
|
|
Get or set the widget that will receive <tt>FL_KEYBOARD</tt> events.
|
|
|
|
<P>If you change <tt>Fl::focus()</tt>, the previous widget and all
|
|
parents (that don't contain the new widget) are sent <tt>FL_UNFOCUS</tt>
|
|
events. Changing the focus does <I>not</I> send <tt>FL_FOCUS</tt> to
|
|
this or any widget, because sending <tt>FL_FOCUS</tt> is supposed to <I>
|
|
test</I> if the widget wants the focus (by it returning non-zero from <tt>
|
|
handle()</tt>).
|
|
|
|
<h3><A name=foreground>static void Fl::foreground(uchar, uchar, uchar)</A></h3>
|
|
|
|
Changes <tt>fl_color(FL_BLACK)</tt>. Also changes <tt>
|
|
FL_INACTIVE_COLOR</tt> and <tt>FL_SELECTION_COLOR</tt> to be a ramp
|
|
between this and <tt>FL_WHITE</tt>.
|
|
|
|
<h3><A name=free_color>static void Fl::free_color(Fl_Color, int overlay = 0)</A></h3>
|
|
|
|
Frees the specified color from the colormap, if applicable. If <tt>
|
|
overlay</tt> is non-zero then the color is freed from the overlay
|
|
colormap.
|
|
|
|
<h3><A name=get_color>static unsigned Fl::get_color(Fl_Color)
|
|
<br>static void Fl::get_color(Fl_Color, uchar &r, uchar &g, uchar &b)</A></h3>
|
|
|
|
Returns the color index or RGB value for the given FLTK color index.
|
|
|
|
<h3><A name=get_font>static const char *Fl::get_font(int face)</A></h3>
|
|
|
|
Get the string for this face. This string is different for each
|
|
face. Under X this value is passed to XListFonts to get all the sizes
|
|
of this face.
|
|
|
|
<h3><A name=get_font_name>static const char *Fl::get_font_name(int
|
|
face, int *attributes = 0)</A></h3>
|
|
|
|
Get a human-readable string describing the family of this face. This
|
|
is useful if you are presenting a choice to the user. There is no
|
|
guarantee that each face has a different name. The return value points
|
|
to a static buffer that is overwritten each call.
|
|
|
|
<P>The integer pointed to by <tt>attributes</tt> (if the pointer is not
|
|
zero) is set to zero, <tt>FL_BOLD</tt> or <tt>FL_ITALIC</tt> or <tt>
|
|
FL_BOLD | FL_ITALIC</tt>. To locate a "family" of fonts, search
|
|
forward and back for a set with non-zero attributes, these faces along
|
|
with the face with a zero attribute before them constitute a family.
|
|
|
|
<h3><A name=get_font_sizes>int get_font_sizes(int face, int *&sizep)</A></h3>
|
|
|
|
Return an array of sizes in <tt>sizep</tt>. The return value is the
|
|
length of this array. The sizes are sorted from smallest to largest
|
|
and indicate what sizes can be given to <tt>fl_font()</tt> that will
|
|
be matched exactly (<tt>fl_font()</tt> will pick the closest size for
|
|
other sizes). A zero in the first location of the array indicates a
|
|
scalable font, where any size works, although the array may list sizes
|
|
that work "better" than others. Warning: the returned array
|
|
points at a static buffer that is overwritten each call. Under X this
|
|
will open the display.
|
|
|
|
<h3><A name=get_mouse>static void Fl::get_mouse(int &x, int &y)</A></h3>
|
|
|
|
Return where the mouse is on the screen by doing a round-trip query to
|
|
the server. You should use <tt>Fl::event_x_root()</tt> and <tt>
|
|
Fl::event_y_root()</tt> 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.
|
|
|
|
<h3><A name=get_system_colors>static void Fl::get_system_colors()</A></h3>
|
|
|
|
Read the user preference colors from the system and use them to call
|
|
<tt> Fl::foreground()</tt>, <tt>Fl::background()</tt>, and <tt>
|
|
Fl::background2()</tt>. This is done by
|
|
<tt>Fl_Window::show(argc,argv)</tt> before applying the -fg and -bg
|
|
switches.
|
|
|
|
<P>On X this reads some common values from the Xdefaults database.
|
|
KDE users can set these values by running the "krdb" program, and
|
|
newer versions of KDE set this automatically if you check the "apply
|
|
style to other X programs" switch in their control panel.
|
|
|
|
<h3><A name=gl_visual>static int Fl::gl_visual(int)</A></h3>
|
|
|
|
This does the same thing as <A
|
|
href=#visual><tt>Fl::visual(int)</tt></A> but also requires OpenGL
|
|
drawing to work. This <I>must</I> be done if you want to draw in
|
|
normal windows with OpenGL with <A href=opengl.html#gl_start>
|
|
<tt>gl_start()</tt></A> and <tt>gl_end()</tt>. It may be useful to
|
|
call this so your X windows use the same visual as an <A
|
|
href=Fl_Gl_Window.html#Fl_Gl_Window> <tt>Fl_Gl_Window</tt></A>, which
|
|
on some servers will reduce colormap flashing.
|
|
|
|
<P>See <A href=Fl_Gl_Window.html#Fl_Gl_Window.mode><tt>Fl_Gl_Window</tt></A>
|
|
for a list of additional values for the argument.
|
|
|
|
<h3><A name=grab>static void Fl::grab(Fl_Window*)
|
|
<br>static Fl_Window* Fl::grab()</A></h3>
|
|
|
|
This is used when pop-up menu systems are active. Send all events to
|
|
the passed window no matter where the pointer or focus is (including
|
|
in other programs). The window <I>does not have to be
|
|
<tt>shown()</tt></I> , this lets the <tt>handle()</tt> method of a
|
|
"dummy" window override all event handling and allows you to
|
|
map and unmap a complex set of windows (under both X and WIN32
|
|
<I>some</I> window must be mapped because the system interface needs a
|
|
window id).
|
|
|
|
<P>If <tt>grab()</tt> is on it will also affect show() of windows by
|
|
doing system-specific operations (on X it turns on
|
|
override-redirect). These are designed to make menus popup reliably
|
|
and faster on the system.
|
|
|
|
<P>To turn off grabbing do <tt>Fl::grab(0)</tt>.
|
|
|
|
<P><I>Be careful that your program does not enter an infinite loop
|
|
while <tt>grab()</tt> is on. On X this will lock up your screen!</I>
|
|
|
|
<h3><A name=h>static int Fl::h()</A></h3>
|
|
|
|
Returns the height of the screen in pixels.
|
|
|
|
<h3><A name=handle>static int Fl::handle(int, Fl_Window *)</A></h3>
|
|
|
|
Sends the event to a window for processing. Returns non-zero if any
|
|
widget uses the event.
|
|
|
|
<h3><A name=help>static const char *Fl::help</A></h3>
|
|
|
|
This is the usage string that is displayed if <tt>Fl::args()</tt>
|
|
detects an invalid argument on the command-line.
|
|
|
|
<h3><A name=modal>static Fl_Window *Fl::modal()</A></h3>
|
|
|
|
Returns the top-most <tt>modal()</tt> window currently shown.
|
|
This is the most recently <tt>
|
|
shown()</tt> window with <A href=Fl_Window.html#Fl_Window.modal><tt>
|
|
modal()</tt></A> true, or <tt>NULL</tt> if there are no <tt>modal()</tt>
|
|
windows <tt>shown()</tt>.
|
|
The <tt>modal()</tt> window has its <tt>handle()</tt> method called
|
|
for all events, and no other windows will have <tt>handle()</tt>
|
|
called (<A href=#grab><tt>grab()</tt></A> overrides this).
|
|
|
|
<h3><A name=own_colormap>static void Fl::own_colormap()</A></h3>
|
|
|
|
Makes FLTK use its own 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.
|
|
|
|
<P>This does nothing if the current visual is not colormapped.
|
|
|
|
<h3><A name=paste>static void Fl::paste(Fl_Widget *receiver)</A></h3>
|
|
|
|
Set things up so the receiver widget will be called with an <A href=#FL_PASTE>
|
|
<tt>FL_PASTE</tt></A> event some time in the future. The reciever
|
|
should be prepared to be called <I>directly</I> by this, or for it to
|
|
happen <I>later</I>, or possibly <I>not at all</I>. 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 in FLTK.
|
|
|
|
<h3><A name=pushed>static Fl_Widget *Fl::pushed() const
|
|
<br>static void Fl::pushed(Fl_Widget *)</A></h3>
|
|
|
|
Get or set the widget that is being pushed. <tt>FL_DRAG</tt> or <tt>
|
|
FL_RELEASE</tt> (and any more <tt>FL_PUSH</tt>) events will be sent to
|
|
this widget.
|
|
|
|
<P>If you change the pushed widget, the previous one and all parents
|
|
(that don't contain the new widget) are sent <tt>FL_RELEASE</tt>
|
|
events. Changing this does <I>not</I> send <tt>FL_PUSH</tt> to this
|
|
or any widget, because sending <tt>FL_PUSH</tt> is supposed to <I>test</I>
|
|
if the widget wants the mouse (by it returning non-zero from <tt>
|
|
handle()</tt>).
|
|
|
|
<h3><A name=readqueue>static Fl_Widget *Fl::readqueue()</A></h3>
|
|
|
|
All <tt>Fl_Widgets</tt> that don't have a callback defined use a
|
|
default callback that puts a pointer to the widget in this queue, and
|
|
this method reads the oldest widget out of this queue.
|
|
|
|
<h3><A name=ready>static int Fl::ready()</A></h3>
|
|
|
|
This is similar to <tt>Fl::check()</tt> except this does <I>not</I>
|
|
call <tt>Fl::flush()</tt> or any callbacks, which is useful if your
|
|
program is in a state where such callbacks are illegal. This returns
|
|
true if <tt>Fl::check()</tt> would do anything (it will continue to
|
|
return true until you call <tt>Fl::check()</tt> or <tt>Fl::wait()</tt>).
|
|
|
|
<ul><pre>while (!calculation_done()) {
|
|
calculate();
|
|
if (Fl::ready()) {
|
|
do_expensive_cleanup();
|
|
Fl::check();
|
|
if (user_hit_abort_button()) break;
|
|
}
|
|
}</pre></ul>
|
|
|
|
<h3><A name=redraw>static void Fl::redraw()</A></h3>
|
|
|
|
Redraws all widgets.
|
|
|
|
<h3><A name=has_idle>static int Fl::has_idle(void (*cb)(void*), void* = 0)</A></h3>
|
|
|
|
Returns true if the specified idle callback is currently installed.
|
|
|
|
<h3><A name=remove_idle>static void Fl::remove_idle(void (*cb)(void*), void* = 0)</A></h3>
|
|
|
|
Removes the specified idle callback, if it is installed.
|
|
|
|
<h3><A name=has_timeout>static int Fl::has_timeout(void (*cb)(void*), void* = 0)</A></h3>
|
|
|
|
Returns true if the timeout exists and has not been called yet.
|
|
|
|
<h3><A name=remove_timeout>static void Fl::remove_timeout(void (*cb)(void*), void* = 0)</A></h3>
|
|
|
|
Removes a timeout callback. It is harmless to remove a timeout
|
|
callback that no longer exists.
|
|
|
|
<h3><A name=has_check>static int Fl::has_check(void (*cb)(void*), void* = 0)</A></h3>
|
|
|
|
Returns true if the check exists and has not been called yet.
|
|
|
|
<h3><A name=remove_check>static void Fl::remove_check(void (*cb)(void*), void* = 0)</A></h3>
|
|
|
|
Removes a check callback. It is harmless to remove a check
|
|
callback that no longer exists.
|
|
|
|
<h3><A name=run>static Fl::run()</A></h3>
|
|
|
|
As long as any windows are displayed this calls <tt>Fl::wait()</tt>
|
|
repeatedly. When all the windows are closed it returns zero
|
|
(supposedly it would return non-zero on any errors, but fltk calls
|
|
exit directly for these). A normal program will end <tt>main()</tt>
|
|
with <tt>return Fl::run();</tt>.
|
|
|
|
<h3><A name=selection>static void Fl::selection(Fl_Widget *owner, const
|
|
char *stuff, int len)
|
|
<br>static const char* Fl::selection()
|
|
<br>static int Fl::selection_length()</A></h3>
|
|
|
|
The first form changes the current selection. The block of text is
|
|
copied to an internal buffer by FLTK (be careful if doing this in
|
|
response to an <tt>FL_PASTE</tt> as this <I>may</I> be the same buffer
|
|
returned by <tt>event_text()</tt>). The <tt>selection_owner()</tt>
|
|
widget is set to the passed owner (possibly sending <tt>
|
|
FL_SELECTIONCLEAR</tt> to the previous owner). The second form looks
|
|
at the buffer containing the current selection. The contents of this
|
|
buffer are undefined if this program does not own the current
|
|
selection.
|
|
|
|
<h3><A name=selection_owner>static Fl_Widget *Fl::selection_owner() const
|
|
<br>static void Fl::selection_owner(Fl_Widget *)</A></h3>
|
|
|
|
The single-argument <tt>selection_owner(x)</tt> call can be used to
|
|
move the selection to another widget or to set the owner to
|
|
<tt>NULL</tt>, without changing the actual text of the
|
|
selection. <tt>FL_SELECTIONCLEAR</tt> is sent to the previous
|
|
selection owner, if any.
|
|
|
|
<P><I>Copying the buffer every time the selection is changed is
|
|
obviously wasteful, especially for large selections. An interface will
|
|
probably be added in a future version to allow the selection to be made
|
|
by a callback function. The current interface will be emulated on top
|
|
of this.</I>
|
|
|
|
<h3><A name=set_boxtype>static void Fl::set_boxtype(Fl_Boxtype,
|
|
Fl_Box_Draw_F *, uchar, uchar, uchar, uchar)
|
|
<br>static void Fl::set_boxtype(Fl_Boxtype, Fl_Boxtype from)</A></h3>
|
|
|
|
The first form sets the function to call to draw a specific boxtype.
|
|
|
|
<P>The second form copies the <tt>from</tt> boxtype.
|
|
|
|
<h3><A name=set_color>static void Fl::set_color(Fl_Color, uchar r,
|
|
uchar g, uchar b)</A></h3>
|
|
|
|
Sets an entry in the <tt>fl_color</tt> index table. You can set it to
|
|
any 8-bit RGB color. The color is not allocated until <tt>fl_color(i)</tt>
|
|
is used.
|
|
|
|
<h3><A name=set_font>static int Fl::set_font(int face, const char *)
|
|
<br>static int Fl::set_font(int face, int from)</A></h3>
|
|
|
|
The first form changes a face. The string pointer is simply stored,
|
|
the string is not copied, so the string must be in static memory.
|
|
|
|
<P>The second form copies one face to another.
|
|
|
|
<h3><A name=set_fonts>int Fl::set_fonts(const char * = 0)</A></h3>
|
|
|
|
FLTK will open the display, and add every font on the server to the
|
|
face table. It will attempt to put "families" of faces together, so
|
|
that the normal one is first, followed by bold, italic, and bold
|
|
italic.
|
|
|
|
<P>The optional argument is a string to describe the set of fonts to
|
|
add. Passing <tt>NULL</tt> will select only fonts that have the
|
|
ISO8859-1 character set (and are thus usable by normal text). Passing
|
|
"-*" will select all fonts with any encoding as long as they have
|
|
normal X font names with dashes in them. Passing "*" will list every
|
|
font that exists (on X this may produce some strange output). Other
|
|
values may be useful but are system dependent. With WIN32 <tt>NULL</tt>
|
|
selects fonts with ISO8859-1 encoding and non-<tt>NULL</tt> selects
|
|
all fonts.
|
|
|
|
<P>The return value is how many faces are in the table after this is
|
|
done.
|
|
|
|
<h3><A name=set_labeltype>static void Fl::set_labeltype(Fl_Labeltype,
|
|
Fl_Label_Draw_F *, Fl_Label_Measure_F *)
|
|
<br>static void Fl:set_labeltype(Fl_Labeltype, Fl_Labeltype from)</A></h3>
|
|
|
|
The first form sets the functions to call to draw and measure a
|
|
specific labeltype.
|
|
|
|
<P>The second form copies the <tt>from</tt> labeltype.
|
|
|
|
<h3><A name=test_shortcut>int Fl::test_shortcut(ulong) const</A></h3>
|
|
|
|
Test the current event, which must be an <tt>FL_KEYBOARD</tt> or <tt>
|
|
FL_SHORTCUT</tt>, against a shortcut value (described in <A href=Fl_Button.html#Fl_Button.shortcut>
|
|
<tt>Fl_Button</tt></A>). Returns non-zero if there is a match. Not to
|
|
be confused with <A href=#Fl_Widge.test_shortcut><tt>
|
|
Fl_Widget::test_shortcut()</tt></A>.
|
|
|
|
<h3><A name=visual>static int Fl::visual(int)</A></h3>
|
|
|
|
Selects a visual so that your graphics are drawn correctly. This is
|
|
only allowed before you call show() on any windows. This does nothing
|
|
if the default visual satisfies the capabilities, or if no visual
|
|
satisfies the capabilities, or on systems that don't have such
|
|
brain-dead notions.
|
|
|
|
<P>Only the following combinations do anything useful:
|
|
|
|
<UL>
|
|
<LI><tt>Fl::visual(FL_RGB)</tt>
|
|
<BR>Full/true color (if there are several depths FLTK chooses the
|
|
largest). Do this if you use <A href=#fl_draw_image><tt>fl_draw_image</tt>
|
|
</A> for much better (non-dithered) output.
|
|
<BR> </LI>
|
|
<LI><tt>Fl::visual(FL_RGB8)</tt>
|
|
<BR>Full color with at least 24 bits of color. <tt>FL_RGB</tt> will
|
|
always pick this if available, but if not it will happily return a
|
|
less-than-24 bit deep visual. This call fails if 24 bits are not
|
|
available.
|
|
<BR> </LI>
|
|
<LI><tt>Fl::visual(FL_DOUBLE|FL_INDEX)</tt>
|
|
<BR>Hardware double buffering. Call this if you are going to use <A href=Fl_Double_Window.html#Fl_Double_Window>
|
|
<tt>Fl_Double_Window</tt></A>.
|
|
<BR> </LI>
|
|
<LI><tt>Fl::visual(FL_DOUBLE|FL_RGB)</tt></LI>
|
|
<LI><tt>Fl::visual(FL_DOUBLE|FL_RGB8)</tt>
|
|
<BR>Hardware double buffering and full color.
|
|
</UL>
|
|
|
|
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).
|
|
|
|
<h3><A name=w>static int Fl::w()</A></h3>
|
|
|
|
Returns the width of the screen in pixels.
|
|
|
|
<h3><A name=wait>static int Fl::wait()</a></h3>
|
|
|
|
Waits until "something happens" and then returns. 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.
|
|
|
|
<P>What this really does is call all idle callbacks, all elapsed
|
|
timeouts, call <tt>Fl::flush()</tt> to get the screen to update, and
|
|
then wait some time (zero if there are idle callbacks, the shortest of
|
|
all pending timeouts, or infinity), for any events from the user or
|
|
any <tt>Fl::add_fd()</tt> callbacks. It then handles the events and
|
|
calls the callbacks and then returns.
|
|
|
|
<P>The return value is non-zero if there are any visible windows (this
|
|
may change in future versions of fltk).
|
|
|
|
<h3>static double Fl::wait(double time)</h3>
|
|
|
|
Same as <tt>Fl::wait()</tt> except it waits a maximum of <i>time</i>
|
|
seconds. <i>It can return much sooner if something happens.</i>
|
|
|
|
<P>The return value is positive if an event or fd happens before the
|
|
time elapsed. It is zero if nothing happens (on Win32 this will only
|
|
return zero if <i>time</i> is zero). It is negative if an error
|
|
occurs (this will happen on Unix if a signal happens).
|
|
|
|
<h3><A name=warning>static void (*Fl::warning)(const char *, ...)</A>
|
|
<br><A name=error>static void (*Fl::error)(const char *, ...)</A>
|
|
<br><A name=fatal>static void (*Fl::fatal)(const char *, ...)</A></h3>
|
|
|
|
FLTK will call these to print messages when unexpected conditions
|
|
occur. By default they <tt>fprintf</tt> to <tt>stderr</tt>, and <tt>
|
|
Fl::error</tt> and <tt>Fl::fatal</tt> call <tt>exit(1)</tt>. You can
|
|
override the behavior by setting the function pointers to your own
|
|
routines.
|
|
|
|
<P><tt>Fl::warning</tt> means that there was a recoverable problem, the
|
|
display may be messed up but the user can probably keep working (all X
|
|
protocol errors call this). <tt>Fl::error</tt> means there is a
|
|
recoverable error, but the display is so messed up it is unlikely the
|
|
user can continue (very little calls this now). <tt>Fl::fatal</tt> must
|
|
not return, as FLTK is in an unusable state, however your version may
|
|
be able to use <tt>longjmp</tt> or an exception to continue, as long as
|
|
it does not call FLTK again.
|
|
|
|
</body></html>
|