From 367f908d8ed5a3464b9676223a26ddf4e11bdb5b Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Thu, 7 Jan 1999 16:36:11 +0000 Subject: "Final" changes for first draft of 1.0 documentation. git-svn-id: file:///fltk/svn/fltk/trunk@187 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/functions.html | 1442 +++++++++++++++++++++++++----------------- 1 file changed, 870 insertions(+), 572 deletions(-) (limited to 'documentation/functions.html') diff --git a/documentation/functions.html b/documentation/functions.html index 6dfe9a0cf..8d1ddbf1c 100644 --- a/documentation/functions.html +++ b/documentation/functions.html @@ -3,620 +3,837 @@

B - Function Reference

-When we created the window and box widgets - and widgets inside the window. - Here a single -Fl_Box is created. The arguments to the -constructor are a value for the box() -property (most constructors do not have this), values for x(), y(), w(), h() to define the position -and size of the box, and a value for label() to define the text printed in the -box. +This appendix describes all of the fl_ functions and +Fl:: methods. For a description of the FLTK widgets, see Appendix A. -

All the widgets have several attributes and there is a method for -setting and getting the current value of each of them. -box->labelsize(36) sets the labelsize() to 36. You could get -the value with box->labelsize(). Often you have to set -many properties, so you will be relieved to know that almost all of -these methods are trivial inline functions. +

Functions

-

labelfont() is -set to a symbolic value which is compiled into a constant integer, 3 -in this case. All properties that cannot be described by a single -small number use a 1-byte index into a table. This makes the widget -smaller, allows the actual definition of the property to be deferred -until first use, and you can redefine existing entries to make global -style changes. +

int fl_color_chooser(const char*, double &r, double &g, double &b)
+int fl_color_chooser(const char *, uchar &r, uchar &g, uchar &b)

-

labeltype(FL_SHADOW_LABEL) -also stores a 1-byte symbolic value, in this case indicating a -procedure to draw drop shadows under the letters should be called to -draw the label. +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 constructor for widgets adds them as children of the "current -group" (usually a window). window->end() stops adding -them to this window. For more control over the construction of -objects, you can end() the window immediately, and then add the -objects with window->add(box). You can -also do window->begin() -to switch what window new objects are added to. +

-

window->show() finally -puts the window on the screen. It is not until this point that the X -server is opened. FLTK provides some optional and rather -simple command-line parsing if you call show(argv,argc). If you don't want this, just -call show() with no arguments, and the unused argument code is not -linked into your program, making it smaller! +

fl_color_chooser() pops up a window to let the user pick an +arbitrary RGB color. They can pick the hue and saturation in the "hue +box" on the left (hold down CTRL to just change the saturation), and +the brighness using the vertical slider. Or they can type the 8-bit +numbers into the RGB Fl_Value_Input 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). -

Fl::run() makes FLTK -enter a loop to update the screen and respond to events. By -default when the user closes the last window FLTK exits by calling exit(0). run() does not -actually return, it is declared to return an int so you can end your -main() function with "return Fl::run()" and outwit the stupid compiler -made by a certain very large software company. +

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

The following command compiles this program, assuming the FLTK -library has been put in /usr/local/lib and the header files in -/usr/local/include/FL: +

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 fl_rectf() to fill a region with a +simulated color using dithering. +

int fl_show_colormap(int oldcol)

+fl_show_colormap() pops up a panel of the 256 colors you +can access with fl_color() 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. +
+

void fl_message(const char *, ...)

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

void fl_alert(const char *, ...)

+Same as fl_message() except for the "!" symbol. +
+

int fl_ask(const char *, ...)

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

int fl_choice(const char *q, const char *b0, const char *b1, const char *b2, ...)

+Shows the message with three buttons below it marked with the strings +b0, b1, and b2. Returns 0, 1, or 2 +depending on which button is hit. ESC is a shortcut for button 0 and +the enter key is a shortcut for button 1. Notice the "misordered" +position of the buttons. You can hide buttons by passing NULL +as their labels. +
+

const char *fl_input(const char *label, const char *deflt = 0, ...)

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

const char *fl_password(const char *label, const char *deflt = 0, ...)

+Same as fl_input() except an Fl_Secret_Input field is used. - -

The first thing your program should do is construct one or more -trees of Fl_Widgets. The base widget of each of these is -an Fl_Window widget. The constructors for widgets -automatically add them as children of the most recent created window -widget (use window->end() to stop this). Constructing the widgets -does not require the display to be open and does not open it, -unless you purposely open it to get information such as the width of a -font. +

-

Fl_Windows are displayed on the screen with -Fl_Window::show(). For the first window you may also use -Fl_Window::show(argc,argv) and FLTK will automatically -parse some startup arguments such as -display. +

void fl_message_font(Fl_Font fontid, uchar size)

-

Then the program repeatedly calls Fl::wait(). Each -time "something happens" Fl::wait() returns, usually after -a block of X events have been read and processed. It is often useful -for a program to check global state after each event, and FLTK makes -this easy by leaving the main loop under your control. +Change the font and font size used for the messages in all the popups. -

Each widget has a single "callback". This is a function that -is called when something happens (such as the user pressing a button). -FLTK avoids all the complexities of signals/slots by having only a -single callback. Instead a when() method on the object selects when -the callback is done (ie. when a slider is moved or when the mouse is -released). +

Fl_Widget *fl_message_icon()

-

The callback is passed a pointer to the widget and a void* user_data -field. This is redundant, as the user_data can be determined from the -widget, but was done for XForms compatability and to make the same -callbacks useful for menu items. Typically you want to turn the -callback into a method on some C++ object. A simple way is to use the -user_data as a pointer to the object. A more common but harder to -understand way is to store the object in the parent widget's -user_data field, since usually all the controls on a window are for the -same object, this lets you use the user_data for an abitrary method -argument. +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. -

To display graphic data, you must subclass either -Fl_Window or Fl_Widget and define the virtual -draw() method. This can use functions defined in -<FL/fl_draw.H>, or can use system-specific calls such as Xlib. If -the data being displayed changes, your main program calls the -redraw() method on your widget, and FLTK will call -draw() while waiting for the next event. Subclassing -Fl_Window or Fl_Widget is so easy that I felt -it unnecessary to provide the "canvas" widget that most toolkits have. +

char *fl_file_chooser(const char * message, const char *pattern, const char *fname)

-

If your program needs to monitor another device (such as stdin) you -can provide a callback routine for when it becomes ready, by using -Fl::add_fd(i). If your program needs something to happen -at regular intervals you can define a timeout callback with Fl::add_timeout(time). +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. -

Building a large hierarchy is made much easier with fluid -(the Fast Light User Interface Designer). This is a program that lets -you interactively design the widget layout and set all the properties -visually. It outputs C++ source code that you compile and link with -your program. All you have to write is the main loop and any -callbacks. +

- - - - +fl_file_chooser() pops up the file chooser, waits for the user +to pick a file or Cancel, and then returns a pointer to that filename +or NULL if Cancel is chosen. -This chapter demonstrates the basics of FLTK programming with examples. +

message is a string used to title the window. -

Compiling a FLTK Program

+

pattern is used to limit the files listed in a directory to +those matching the pattern. This matching is done by filename_match(). Use +NULL to show all files. -

Include Files

+

fname is a default filename to fill in the chooser with. If +this is NULL then the last filename that was choosen is used (unless +that had a different pattern, in which case just the last directory +with no name is used). The first time the file chooser is called this +defaults to a blank string. -

Library Files

+

The returned value points at a static buffer that is only good +until the next time fl_file_chooser() is called. -

A "Hello, World" Program

+

void fl_file_chooser_callback(void (*cb)(const char *))

-

Creating the Window

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

The Main Loop

+

int filename_list(const char *d, dirent ***list)

- - -FLTK example: ask.C -

ask.C

- -

- -

-#include <stdio.h>
-#include <string.h>
-#include <FL/Fl.H>
-#include <FL/Fl_Window.H>
-#include <FL/Fl_Input.H>
-#include <FL/Fl_Button.H>
-#include <FL/Fl_Return_Button.H>
-
-int get_string(char*buffer, const char *from) {
-  Fl_Window window(320,75);
-  window.set_modal();
-  Fl_Input input(60, 40, 250, 25,"Input:");
-  input.value(buffer);
-  Fl_Button cancel(60, 10,80, 25,"cancel");
-  Fl_Return_Button ok(150, 10,80, 25,"OK");
-  window.end();
-  window.show();
-  for (;;) {
-    Fl::wait();
-    Fl_Widget *o;
-    while (o = Fl::readqueue()) {
-      if (o == &ok) {
-	strcpy(buffer, input.value());
-	return 1;
-      } else if (o == &cancel || o == &window) {
-	return 0;
-      }
-    }
-  }
-}
+This is a portable and const-correct wrapper for the
+fl_scandir function.  d is the name of a directory
+(it does not matter if it has a trailing slash or not).  For each file
+in that directory a "dirent" structure is created.  The only portable
+thing about a dirent is that dirent.d_name is the nul-terminated file
+name.  An array of pointers to these dirents is created and a pointer
+to the array is returned in *list.  The number of entries is
+given as a return value.  If there is an error reading the directory a
+number less than zero is returned, and errno has the reason
+(errno does not work under WIN32).  The files are sorted in
+"alphanumeric" order, where an attempt is made to put unpadded numbers
+in consecutive order.
 
-int main(int argc, char **argv) {
-  char buffer[128];
-  if (get_string(buffer, argv[1])) {
-    puts(buffer);
-    return 0;
-  } else {
-    return 1; // exit with error
-  }
-}
-
- -

Widgets don't need to have callback() set. The default callback puts a -pointer to the widget on a "queue" from which it can later be read -with Fl::readqueue(). This was -done for Forms compatibility but it is useful for modal windows. In this example the -"get_string" function puts up a modal window and loops until one of -the buttons is pushed. - -Fl::wait() does exactly one cycle of -what Fl::run() does repeatedly: it updates the screen and then waits -for and responds to an event (or several events if they are all ready -at the same time). It then returns, allowing the user program to -check any state information it wants to after each group of events. -One thing the user program can check is Fl::readqueue() which returns each -object without a callback that was triggered. It returns null when -the queue is empty. It is possible for more than one object to be on -the queue (or the same object several times) so if your program wants -to read the queue it should always read it until empty and ignore -unrecognized widgets (don't look at them as they may have been -deleted). - -

modal() on a window prevents any -interaction with other program windows below it, and prevents the user -from raising a program window above it (well, it tries, but X is -broken). It won't make any difference in this program because there -is only one window, but this allows the "get_string" function to be -used as subroutine by a larger program and have the expected behavior. - -

This program also demonstrates that FLTK widgets may be constructed -as C++ automatic objects (local variables). You have to be careful -about destruction, however. -Always make sure all automatic children are destructed before the -container (by declaring the children after the container), -since the destructor for a container will attempt to delete all -remaining children, and you don't want to delete automatic objects. - -

[Next example] -
[back to contents] -FLTK example: button.C -

button.C

- -

- -

-#include <stdlib.h>
-#include <stdio.h>
-#include <FL/Fl.H>
-#include <FL/Fl_Window.H>
-#include <FL/Fl_Button.H>
-
-void beepcb(Fl_Widget *, void *) {
-  printf("\007"); fflush(stdout);
-}
+
You can free the returned list of files with the following code:
 
-void exitcb(Fl_Widget *, void *) {
-  exit(0);
-}
+
    +for (int i = return_value; i > 0;) free((void*)(list[--i]));
+free((void*)list);
+

 
-int main(int argc, char ** argv) {
-  Fl_Window *window = new Fl_Window(320,65);
-  window->begin();
-  Fl_Button *b1 = new Fl_Button(20, 20, 80, 25, "Beep");
-  b1->callback(beepcb,0);
-  Fl_Button *b2 = new Fl_Button(120,20, 80, 25, "no op");
-  Fl_Button *b3 = new Fl_Button(220,20, 80, 25, "Exit");
-  b3->callback(exitcb,0);
-  window->end();
-  window->show(argc,argv);
-  return Fl::run();
-}
-
+

int filename_isdir(const char *f)

-

In this example we make some button widgets and make them do -something through callbacks. +Returns non-zero if the file exists and is a directory. -

All widgets have a single callback() function. It is called in -response to an event on that widget, exactly which event depends on -the type of widget. The function takes two arguments: a pointer to -the widget (you will usually need to cast this to the correct -subclass) and a void* pointer to a piece of arbitrary user_data. +

const char *filename_name(const char *f)

-

You don't have to give all the widgets a callback, as the "no op" b2 -widget demonstrates. What these do is described in the next program. +Returns a pointer to the character after the last slash, or to the +start of the filename if there is none. -

[Next example] -
[back to contents] -FLTK methods +

const char *filename_ext(const char *f)

-

#include <FL/Fl.H>

+Returns a pointer to the last period in filename_name(f), or +a pointer to the trailing nul if none. -

You will have to include at least this header file in your main -code so that you can call the methods described here. +

char *filename_setext(char *f, const char *ext)

-

Initialization

+Does strcpy(filename_ext(f), ext ? ext : ""). Returns a +pointer to f. -

You can construct all your widgets (and menus and boxtypes and -images and other FLTK types) without "initializing". The -constructors do not require a connection to the X display. This makes -it a lot easier, especially if your program has a mode where it does -not use a gui, and guarantees that code you don't use is not linked -in. +

int filename_expand(char *out, const char *in)

-

FLTK is usually "initialized" when you show() the first window. At -this time the X display is opened and everything is set up so the -calls described in the rest of this document work. A few other calls -can open the X display, amoung them are fl_width() to measure the -size of a font. Be careful that the following calls are done before -the display is opened, if not you will get lots of strange X errors. +Splits in at each slash character. Replaces any occurrance of +$X with getenv("X") (leaving it as $X if the +environment variable does not exist). Replaces any occurances of +~X with user X's home directory (leaving it as +~X if the user does not exist). Any resulting double slashes +cause everything before the second slash to be deleted. Copies the +result to out (in and out may be the same +buffer). Returns non-zero if any changes were made. In true retro +programming style, it is up to you to provide a buffer big enough for +the result. 1024 characters should be enough. -

Most of these "initialization" calls are to get around stupid X -things. I have tried to make these as simple to call as possible and -they have no effect on systems which aren't as badly designed as X. -But you should call them to make your program as portable as possible. +

int filename_absolute(char *out, const char *in)

- -

int Fl::visual(int)

 +

static void Fl::add_fd(int fd, void (*cb)(int, void *), void * = 0)
+static void Fl::add_fd(int fd, int when, void (*cb)(int, void *), void * = 0)
+static void Fl::remove_fd(int)

-

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). +Add file descriptor fd to listen to. When the fd +becomes ready for reading the callback is done. The callback is passed +the fd and the arbitrary void * argument. +Fl::wait() will return immediately after calling the callback. -

See here for ways to select the visual -using your own code. +

The second version takes a when bitfield, with the bits +FL_READ, FL_WRITE, and FL_EXCEPT defined, to +indicate when the callback should be done. - -

int Fl::gl_visual(int)

void Fl::own_colormap();

void Fl::background(uchar, uchar, uchar);

    +

    static Fl::add_idle(void (*cb)(void *), void *)

    -Changes fl_color(FL_GRAY) 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. +Adds a callback function that is called by Fl::wait() when there +is nothing to do. This can be used for background +processing. -

void Fl::foreground(uchar, uchar, uchar);

    +

    Warning: this can absorb all your machine's time! -Changes fl_color(FL_BLACK). Also changes -FL_INACTIVE_COLOR and FL_SELECTION_COLOR to -be a ramp between this and FL_WHITE. +

    You can have multiple idle callbacks. To remove an idle callback +use Fl::remove_idle(). -

void Fl::background2(uchar, uchar, uchar);

    +

    Only Fl::wait() calls the idle callbacks. +Fl::wait(time), Fl::check(), and Fl::ready() +ignore them so that these functions may be called by the idle callbacks +themselves without having to worry about recursion. -Changes fl_color(FL_WHITE) and the same colors as -Fl::foreground(). This color is used as a background by Fl_Input and -other text widgets. +

    The idle callback can call any FLTK functions. However if you call +something that calls Fl::wait() (such as a message pop-up) you +should first remove the idle callback so that it does not recurse. + +

    static void Fl::add_timeout(float t, void (*cb)(void *),void *v=0)

    + +Add a one-shot timeout callback. The timeout will happen as soon as +possible after t seconds after the last time wait() +was called. The optional void * argument is passed to the +callback. + +

    This code will print "TICK" each second on stdout, no matter what +else the user or program does: + +

      +void callback(void *) {
+  printf("TICK\n");
+  Fl::add_timeout(1.0,callback);
+}
+
+main() {
+  Fl::add_timeout(1.0,callback);
+  Fl::run();
+}
+
    + +

    static int Fl::arg(int argc, char **argv, int &i)

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

int Fl::args(int argc, char** argv, int -&i, int (*callback)(int,char**,int&)=0)

    +

    static int Fl::args(int argc, char **argv, int &i, int (*callback)(int, char**,int &)=0)
    +void Fl::args(int argc, char **argv)

    -

    FLTK provides an entirely optional command-line switch -parser. You don't have to call it if you don't like them! -Everything it can do can be done with other calls to FLTK. +FLTK provides an entirely optional command-line switch parser. +You don't have to call it if you don't like them! Everything it can do +can be done with other calls to FLTK. -

    To use the switch parser, call Fl::args(...) near the start of +

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

    callback lets you define your own switches. It is called -with the same argc and argv, and with i the index of each word. +

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

    On return i is set to the index of the first non-switch. +

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

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

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

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

      -display host:n.n The X display to use (ignored -by MSWindows). - -

      -geometry WxH+X+Y The window position and size -will be modified according the the standard X geometry string. - -

      -name string Fl_Window::xclass(string) will be -done to the window, this will change it's icon. +less than argc. -

      -title string Fl_Window::label(string) will be -done to the window, changing both it's title and the icontitle. +

      All switches may be abbreviated to two letters and case is ignored: -

      -iconic Fl_Window::iconize() will be done to -the window. - -

      -bg color XParseColor is used to lookup the -passed color and then Fl::background() is done. On MSWindows -only color names of the form "#xxxxxx" are understood. +

        -

        -bg2 color XParseColor is used to lookup the -passed color and then Fl::background2() is done. +

      • -display host:n.n The X display to use (ignored + under WIN32). -

        -fg color XParseColor is used to lookup the -passed color and then Fl::foreground() is done. +

      • -geometry WxH+X+Y The window position and size + will be modified according the the standard X geometry string. -

      int Fl::arg(int argc, char** argv, int &i)

        +
      • -name string Fl_Window::xclass(string) will be + done to the window, possibly changing its icon. -Consume a single switch from argv, starting at word i. Returns the -number of words eaten (1 or 2, or 0 if it is not recognized) and adds -the same value to i. You can use this function if you prefer to -control the incrementing through the arguments yourself. +
      • -title string Fl_Window::label(string) will be + done to the window, changing both its title and the icontitle. -

      void Fl::args(int argc, char** argv)

        +
      • -iconic Fl_Window::iconize() will be done to + the window. -This method is useful if your program does not have command line -switches of it's own. It parses all the switches, and if any are not -recognized it calls Fl::abort(Fl::help). +
      • -bg color 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. -

      const char* const Fl::help;

        +
      • -bg2 color XParseColor is used to lookup the + passed color and then Fl::background2() is done. -A string descibing the switches understood by Fl::arg(), useful for -printing as an error message. +
      • -fg color XParseColor is used to lookup the + passed color and then Fl::foreground() is done. - -

      int Fl_Window::show(int argc, char** argv)

      -show() a window and set the XA_WM_COMMAND attribute to -the passed argc/argv. If this is the first time this has been called -since Fl::args() or Fl::arg(), the results of those switches are used -to set the xclass(), label(), and other attributes of this window. +The second form of Fl::args() is useful if your program does +not have command line switches of its own. It parses all the switches, +and if any are not recognized it calls Fl::abort(Fl::help). -

      If Fl::args() or Fl::arg() have never been called, this calls -Fl::args(argc,argv) automatically. This is convienent for very small -programs that just want to put up a single window and take no -switches. +

      static void Fl::background(uchar, uchar, uchar)

      -
    +Changes fl_color(FL_GRAY) 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. -

    Running

    +

    static void Fl::background2(uchar, uchar, uchar)

    -After FLTK is "initialized" by calling show() on some window, you get -FLTK to wait for and respond to events by calling the following -methods: +Changes fl_color(FL_WHITE) and the same colors as +Fl::foreground(). This color is used as a background by +Fl_Input and other text widgets. - -

int Fl::run()

int Fl::wait()

    +

    static int Fl::box_dh(Fl_Boxtype)

    -Calls the idle function if any, then calls any pending timeout -functions, then calls Fl::flush(). If there are -any windows displayed it then waits some time for events (zero if -there is an idle(), the shortest timeout if there are any timeouts, or -forever) and calls the handle() function on those events, and then -returns non-zero. +Returns the height offset for the given boxtype. -

    Your program can check it's global state and update things after -each call to Fl::wait(), which can be very useful in complex programs. +

    static int Fl::box_dw(Fl_Boxtype)

    -

    If there are no windows (this is checked after the idle and -timeouts are called) then Fl::wait() returns zero without waiting for -any events. Your program can either exit at this point, or call -show() on some window so the UI can continue to operate. +Returns the width offset for the given boxtype. -

float Fl::wait(float time)

    +

    static int Fl::box_dx(Fl_Boxtype)

    -Wait only a certain amount of time for anything to happen. This does -the same as wait() except if the given time (in seconds) passes it -returns. The return value is how much time remains. If the return -value is zero or negative then the entire time period elapsed. +Returns the X offset for the given boxtype. -

    If you do several wait(time) calls in a row, the subsequent ones -are measured from when the first one is called, even if you do -time-consuming calculations after they return. This allows you to -accurately make something happen at regular intervals. This code will -accurately call A() once per second (as long as it takes less than a -second to execute): +

    static int Fl::box_dy(Fl_Boxtype)

    -
      -for (;;) {
-  for (float time = 1.0; time > 0; ) time = Fl::wait(time);
-  A();
-}
-
    +Returns the Y offset for the given boxtype. -

int Fl::check()

    +

    static int Fl::check()

    -This does the same thing as Fl::wait(0), except because it does not +This does the same thing as Fl::wait(0), except because it does not have to return the elapsed time value it can be implemented faster on certain systems. Use this to interrupt a big calculation: -
      +
         while (!calculation_done()) {
   calculate();
   Fl::check();
   if (user_hit_abort_button()) break;
 }
-
      
+
    -

    This returns non-zero if any windows are displayed, and 0 if no +This returns non-zero if any windows are displayed, and 0 if no windows are displayed. -

int Fl::ready();

void Fl::add_timeout(float t,void (*cb)(void*),void* v=0); -
void Fl::remove_timeout(void (*cb)(void*), void* = 0);

    +

    static void Fl::redraw()

    -Add or remove a one-shot timeout callback. The timeout will happen as -soon as possible after t seconds after the last time wait() was -called. The optional void* argument is passed to the callback. It is -harmless to remove a timeout callback that no longer exists. +Redraws all widgets. -

    This code will print "TICK" each second on stdout, no matter what -else the user or program does: +

    static void Fl::release()

    -
      -void callback(void *) {
-  printf("TICK\n");
-  Fl::add_timeout(1.0,callback);
-}
-main() {...
-  Fl::add_timeout(1.0,callback);
-  Fl::run();
-}
-
    +Turn off the grab() behavior. - -

void Fl::set_idle(void (*cb)());

    +

    static void Fl::remove_idle(void (*cb)(void *), void *= 0)

    -If the idle callback is set it will be called by Fl::wait() and -Fl::wait() will return immediately. This can be used for background -processing. This will absorb all your machine's time! There is -only one idle callback, changing it will replace the old one. To turn -off the idle processing use Fl::set_idle(0). +Removes the specified idle callback. -

    Only Fl::wait(void) calls the idle callback. Fl::wait(time), -Fl::check(), and Fl::ready() ignore it. This is so that these -functions may be called by the idle callback itself without having to -worry about recursion. +

    static void Fl::remove_timeout(void (*cb)(void *), void *= 0)

    -

    The idle callback can call any FLTK functions. However if you call -something that calls Fl::wait() (such as a message pop-up) you should -first set the idle callback to zero so it does not recurse. +Removes a timeout callback. It is harmless to remove a timeout callback +that no longer exists. - -

void Fl::flush()

    +

    static Fl::run()

    -Causes all the windows that need it to be redrawn and graphics forced -out through the pipes. This is what wait() does before looking for -events. +Runs FLTK until there are no windows displayed, and then returns a zero. +Fl::run() is exactly equivalent to: -

int Fl::damage()

Fl_Widget *Fl::readqueue();

-

Listening to other file descriptors (Unix only)

+

static Fl_Widget *Fl::selection_owner() const
+static void Fl::selection_owner(Fl_Widget *)

-

-void Fl::add_fd(int fd, void (*cb)(int, void*), void* = 0);
-void Fl::add_fd(int fd, int when, void (*cb)(int, void*), void* = 0);
-void Fl::remove_fd(int);

    +The single-argument selection_owner(x) call can be used to +move the selection to another widget or to set the owner to +NULL, without changing the actual text of the selection. +FL_SELECTIONCLEAR is sent to the previous selection owner, if +any. -Add file descriptor fd to listen to. When the fd becomes ready -for reading the callback is done. The callback is passed the fd and -the arbitrary void* argument. Fl::wait() will return immediately -after calling the callback. +

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

    The second version takes a when bitfield, with the bits -FL_READ, FL_WRITE, and FL_EXCEPT defined, to indicate when the -callback should be done. This probably only works on Unix. +

    static void Fl::set_boxtype(Fl_Boxtype, Fl_Box_Draw_F *, uchar, uchar, uchar, uchar)
    +static void Fl::set_boxtype(Fl_Boxtype, Fl_Boxtype from)

    -

    There can only be one callback of each type for a file descriptor. -Fl::remove_fd() gets rid of all the callbacks for a given file -descriptor. +The first form sets the function to call to draw a specific boxtype. + +

    The second form copies the from boxtype. + +

    static void Fl::set_color(Fl_Color, uchar r, uchar g, uchar b)

    + +Sets an entry in the fl_color index table. You can set +it to any 8-bit RGB color. The color is not allocated until +fl_color(i) is used. + +

    static int Fl::set_font(int face, const char *)
    +static int Fl::set_font(int face, int from)

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

    The second form copies one face to another. + +

    int Fl::set_fonts(const char * = 0)

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

    The optional argument is a string to describe the set of fonts to +add. Passing NULL 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 NULL selects fonts +with ISO8859-1 encoding and non-NULL selects all fonts. + +

    The return value is how many faces are in the table after this is done. + +

    static void Fl::set_labeltype(Fl_Labeltype, Fl_Label_Draw_F *, Fl_Label_Measure_F *)
    +static void Fl:set_labeltype(Fl_Labeltype, Fl_Labeltype from)

    + +The first form sets the functions to call to draw and measure a +specific labeltype. + +

    The second form copies the from labeltype. + +

    int Fl::test_shortcut(ulong) const

    + +Test the current event, which must be an FL_KEYBOARD or +FL_SHORTCUT, against a shortcut value (described in Fl_Button). Returns non-zero +if there is a match. Not to be confused with +Fl_Widget::test_shortcut(). + +

    static int Fl::visual(int)

    + +Selects a visual so that your graphics are drawn correctly. 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. + +

    Only the following combinations do anything useful: + +

      + +
    • Fl::visual(FL_RGB) + +
      Full/true color (if there are several depths FLTK chooses + the largest). Do this if you use + fl_draw_image for much better (non-dithered) + output. +
        + +
    • Fl::visual(FL_RGB8) + +
      Full color with at least 24 bits of color. FL_RGB 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. +
        + +
    • Fl::visual(FL_DOUBLE|FL_INDEX) + +
      Hardware double buffering. Call this if you are going to use + Fl_Double_Window. +
        + +
    • Fl::visual(FL_DOUBLE|FL_RGB) +
    • Fl::visual(FL_DOUBLE|FL_RGB8) + +
      Hardware double buffering and full color. +
       
    -

    Exiting

    - -When all windows are closed Fl::wait() and Fl::run() return zero. If -your main() routine then returns the program exits. You can also call -exit(0) at any time in your program. You do not need to do any -cleanup code for FLTK. In particular you do not have to destroy -any widgets you have created. FLTK also does not sneak any atexit -functions in on you either. You will need to do -#include <stdlib.h> to call exit(). - -

    To stop a window from closing, or conversely to make the closing of -a particular window exit the program you must change the callback() -function. Here is a typical use: - -

      -static void main_window_cb(Fl_Widget*, void*) {
-  if (document_changed()) {
-    if (!fl_ask("Exit without saving changes?")) return;
-    // window will not go away as hide() has not been called...
-  }
-  exit(0);
-}
+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).
 
-...somewhere in main():
-  main_window->callback(window_cb);
-
    +

    static int Fl::w()

    - -

void (*Fl::warning)(const char*,...); -
void (*Fl::error)(const char*,...); -
void (*Fl::fatal)(const char*,...);

(back to contents) -FLTK example: hello.C -

hello.C

+The second form of Fl::wait() waits only a certain amount of +time for anything to happen. This does the same as wait() +except if the given time (in seconds) passes it returns. The return +value is how much time remains. If the return value is zero or +negative then the entire time period elapsed. +

If you do several wait(time) calls in a row, the subsequent ones +are measured from when the first one is called, even if you do +time-consuming calculations after they return. This allows you to +accurately make something happen at regular intervals. This code will +accurately call A() once per second (as long as it takes less than a +second to execute): -

[Next example] -
[back to contents] +

    +for (;;) {
+  for (float time = 1.0; time > 0; ) time = Fl::wait(time);
+  A();
+}
+
+ +

static void (*Fl::warning)(const char *, ...)
+static void (*Fl::error)(const char *, ...)
+static void (*Fl::fatal)(const char *, ...)

+ +FLTK will call these to print messages when unexpected conditions +occur. By default they fprintf to stderr, and +Fl::error and Fl::fatal call exit(1). You +can override the behavior by setting the function pointers to your own +routines. + +

Fl::warning 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). Fl::error 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). Fl::fatal +must not return, as FLTK is in an unusable state, however your version +may be able to use longjmp or an exception to continue, as +long as it does not call FLTK again. -- cgit v1.2.3