diff options
Diffstat (limited to 'documentation/functions.html')
| -rw-r--r-- | documentation/functions.html | 863 |
1 files changed, 5 insertions, 858 deletions
diff --git a/documentation/functions.html b/documentation/functions.html index d6ff340e0..a227ff5c7 100644 --- a/documentation/functions.html +++ b/documentation/functions.html @@ -2,9 +2,9 @@ <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>. +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>. <h2>Functions</h2> @@ -235,858 +235,5 @@ subexpressions literally. </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="#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_PASTE</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="enumerations.html#events"> -<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="subclassing.html#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="drawing.html#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> +</body> +</html> |