From c78dcd55ec0b09329c509668507922683f90aab4 Mon Sep 17 00:00:00 2001 From: Michael R Sweet Date: Wed, 28 Nov 2001 20:43:44 +0000 Subject: More doco updates. Enable tooltips by default, and don't enable them when setting the tooltip value, since that will negate any changes a program might make when displaying the file chooser dialog, etc. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@1777 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/Fl.html | 1024 +++++++++++++++++++++++++++++++++++- documentation/Fl_Text_Display.html | 463 ++++++---------- documentation/Fl_Text_Editor.html | 471 ++++++----------- documentation/Fl_Tooltip.html | 87 +++ documentation/Makefile | 6 +- documentation/fltk.book | 1 + documentation/functions.html | 863 +----------------------------- documentation/widgets.html | 334 +++++++----- 8 files changed, 1596 insertions(+), 1653 deletions(-) create mode 100644 documentation/Fl_Tooltip.html (limited to 'documentation') diff --git a/documentation/Fl.html b/documentation/Fl.html index 010fcc73a..8ca85427f 100644 --- a/documentation/Fl.html +++ b/documentation/Fl.html @@ -3,49 +3,1039 @@ -

class Fl_Bitmap

class Fl

Class Hierarchy

-Fl_Image
-   |
-   +----Fl_Bitmap
-           |
-           +----Fl_XBM_Image
+Fl

Include Files

-#include <FL/Fl_Bitmap.H>
+#include &lt;FL/Fl.H&gt;

Description

The Fl_Bitmap class supports caching and drawing of mono-color -(bitmap) images. Images are drawn using the current color.

The Fl class is the FLTK global (static) class containing +state information and global methods for the current application.

Methods

Fl_Bitmap
add_check
add_fd
add_handler
add_idle
add_timeout
arg
args
atclose
background2
background
belowmouse
box_dh
box_dw
box_dx
box_dy
check
compose
compose_reset
damage
default_atclose
display
error
event_alt
event_button1
event_button2
event_button3
event_button
event_buttons
event_clicks
event_ctrl
event
event_inside
event_is_click
event_key
event_length
event_shift
event_state
event_x
event_x_root
event_y
event_y_root
fatal
first_window
flush
focus
foreground
free_color
get_color
get_font
get_font_name
get_font_sizes
get_key
get_mouse
get_system_colors
gl_visual
grab
h
handle
has_check
has_idle
has_timeout
modal
next_window
own_colormap
paste
pushed
readqueue
ready
redraw
release
remove_check
remove_fd
remove_idle
remove_timeout
repeat_timeout
run
selection_owner
selection
set_abort
set_atclose
set_boxtype
set_color
set_font
set_fonts
set_idle
set_labeltype
test_shortcut
version
visible_focus
visual
wait
warning
w
x
y
~Fl_Bitmap

+ +

void add_check(Fl_Timeout_Handler, void* = 0);

+ +

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

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

Sample code: + +

+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();
+}
+

+ +

void add_fd(int fd, int when, void (cb)(int,void),void* =0);
+void add_fd(int fd, void (cb)(int, void), void* = 0);

+ +

Add file descriptor fd to listen to. When the fd +becomes ready for reading Fl::wait() will call the callback +and then return. The callback is +passed the fd and the arbitrary void* argument.

+ +

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

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

Under UNIX any file descriptor can be monitored (files, +devices, pipes, sockets, etc.) Due to limitations in Microsoft Windows, +WIN32 applications can only monitor sockets. + +

void add_handler(int (*h)(int));

+ +

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

FL_SHORTCUT events that are not recognized by any widget. +This lets you provide global shortcut keys.
System events that FLTK does not recognize. See +fl_xevent.
Some other events when the widget FLTK selected returns +zero from its handle() method. Exactly which ones may change +in future versions, however.

+ +

void add_idle(void (cb)(void), void* = 0);

+ +

Adds a callback function that is called every time by +Fl::wait() and also makes it act as though the timeout is +zero (this makes Fl::wait() 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. + +

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

Fl::wait() and Fl::check() call idle callbacks, +but Fl::ready() does not. + +

The idle callback can call any FLTK functions, including +Fl::wait(), Fl::check(), and Fl::ready(). +FLTK will not recursively call the idle callback. + +

void add_timeout(double t, Fl_Timeout_Handler,void* = 0);

+ +

Add a one-shot timeout callback. The function will be called by +Fl::wait() at t seconds after this function is called. +The optional void* argument is passed to the callback. + +

int arg(int, char**, int&);

+ +

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 args(int, char**, int&, int (*)(int,char**,int&) = 0);

+ +

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 your program. This does not open the display, instead +switches that need the display open are stashed into static variables. +Then you must display your first window by calling +window->show(argc,argv), which will do anything stored in the +static variables. + +

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

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

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

+ +

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

All switches except -bg2 may be abbreviated one letter and case is ignored: + +

-display host:n.n The X display to use (ignored under +WIN32).
-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, possibly changing its icon.
-title string Fl_Window::label(string) will be done to +the window, changing both its title and the icontitle.
-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. Under WIN32 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.
-fg color XParseColor is used to lookup the passed color +and then Fl::foreground() is done.

+ +

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

A usage string is displayed if Fl::args() detects an invalid +argument on the command-line. You can change the message by setting the +Fl::help pointer. + +

void (atclose)(Fl_Window,void*);

+ +

void background2(uchar, uchar, uchar);

+ +

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

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

Fl_Widget* belowmouse();
+void belowmouse(Fl_Widget*);

+ +

Get or set the widget that is below the mouse. This is for +highlighting buttons. It is not used to send FL_PUSH or +FL_MOVE directly, for several obscure reasons, but those events +typically go to this widget. This is also the first widget tried for +FL_SHORTCUT events. + +

If you change the belowmouse widget, the previous one and all +parents (that don't contain the new widget) are sent FL_LEAVE +events. Changing this does not send FL_ENTER to this +or any widget, because sending FL_ENTER is supposed to test +if the widget wants the mouse (by it returning non-zero from +handle()). + +

int box_dh(Fl_Boxtype);

+ +

Returns the height offset for the given boxtype. + +

int box_dw(Fl_Boxtype);

+ +

Returns the width offset for the given boxtype. + +

int box_dx(Fl_Boxtype);

+ +

Returns the X offset for the given boxtype. + +

int box_dy(Fl_Boxtype);

+ +

Returns the Y offset for the given boxtype. + +

int check();

+ +

Same as Fl::wait(0). Calling this during a big calculation +will keep the screen up to date and the interface responsive: + +

+while (!calculation_done()) {
+ calculate();
+ Fl::check();
+ if (user_hit_abort_button()) break;
+}
+

+ +

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

int compose(int &del);

+ +

void compose_reset();

+ +

int damage();
+void damage(int x);

+ +

If true then flush() will do something. + +

void default_atclose(Fl_Window,void);

+ +

void display(const char*);

+ +

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

void (error)(const char, ...);

+ +

FLTK calls this to print a normal error message. You can +override the behavior by setting the function pointer to your +own routine. + +

Fl::error means there is a recoverable error such as +the inability to read an image file. The default implementation +prints the error message to stderr and returns. + +

int event_alt();

+ +

int event_button1();

+ +

int event_button2();

+ +

int event_button3();

+ +

int event_button();

+ +

Returns which mouse button was pressed. This returns garbage if the +most recent event was not a FL_PUSH or FL_RELEASE +event. + +

int event_buttons();

+ +

int event_clicks();

+ +

The first form returns non-zero if the most recent FL_PUSH or +FL_KEYBOARD was a "double click". Returns N-1 for +N clicks. A double click is counted if the same button is pressed +again while event_is_click() is true. + +

The second form directly sets the number returned by +Fl::event_clicks(). This can be used to set it to zero so that +later code does not think an item was double-clicked. + +

int event_ctrl();

+ +

int event();

+ +

int event_inside(int,int,int,int);
+int event_inside(const Fl_Widget*);

+ +

Returns non-zero if the current event_x and event_y +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. + +

int event_is_click();
+void event_is_click(0);

+ +

The first form returns non-zero if the mouse has not moved far enough +and not enough time has passed since the last FL_PUSH or +FL_KEYBOARD event for it to be considered a "drag" rather than a +"click". You can test this on FL_DRAG, FL_RELEASE, +and FL_MOVE events. The second form clears the value returned +by Fl::event_is_click(). Useful to prevent the next +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. + +

int event_key();
+int event_key(int s);

+ +

Fl::event_key() returns which key on the keyboard was last +pushed. It returns zero if the last event was not a key press or release. + +

Fl::event_key(int) returns true if the given key was held +down (or pressed) during the last event. This is constant until +the next event is read from the server. +

Fl::get_key(int) returns true if the given key is held down +now. Under X this requires a round-trip to the server and is +much slower than Fl::event_key(int). + +

Keys are identified by the unshifted values. FLTK defines a +set of symbols that should work on most modern machines for every key +on the keyboard: + +

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.
All keys on the numeric keypad producing a printable ASCII +character use the value of that ASCII character plus FL_KP. +The highest possible value is FL_KP_Last so you can +range-check to see if something is on the keypad.
All numbered function keys use the number on the function key plus +FL_F. The highest possible number is FL_F_Last, so you +can range-check a value.
Buttons on the mouse are considered keys, and use the button +number (where the left button is 1) plus FL_Button.
All other keys on the keypad have a symbol: 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. Be +careful not to confuse these with the very similar, but all-caps, +symbols used by Fl::event_state() +.

+ +

On X Fl::get_key(FL_Button+n) does not work. + +

On WIN32 Fl::get_key(FL_KP_Enter) and +Fl::event_key(FL_KP_Enter) do not work. + +

int event_length();

+ +

Returns the length of the text in Fl::event_text(). 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. + +

int event_shift();

+ +

int event_state();
+int event_state(int i);

+ +

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

FL_SHIFT
FL_CAPS_LOCK
FL_CTRL
FL_ALT
FL_NUM_LOCK
FL_META
FL_SCROLL_LOCK
FL_BUTTON1
FL_BUTTON2
FL_BUTTON3

Fl_Bitmap::Fl_Bitmap(const char array, int W, int H);
-Fl_Bitmap::Fl_Bitmap(const unsigned char array, int W, int H);

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 +after the shift key is pressed or released. + +

int event_x();

+ +

Returns the mouse position of the event relative to the Fl_Window +it was passed to. + +

int event_x_root();

+ +

Returns the mouse position on the screen of the event. To find the +absolute position of an Fl_Window on the screen, use the +difference between event_x_root(),event_y_root() and +event_x(),event_y(). + +

int event_y();

+ +

Returns the mouse position of the event relative to the Fl_Window +it was passed to. + +

int event_y_root();

+ +

void (fatal)(const char, ...);

+ +

FLTK calls this to print a fatal error message. You can +override the behavior by setting the function pointer to your +own routine. + +

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. The default implementation prints the error message to +stderr and exits with status 1. + +

Fl_Window* first_window();
+void first_window(Fl_Window*);

+ +

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

The second form 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. + +

void flush();

+ +

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

Fl_Widget* focus();
+void focus(Fl_Widget*);

+ +

Get or set the widget that will receive FL_KEYBOARD events. + +

If you change Fl::focus(), the previous widget and all +parents (that don't contain the new widget) are sent FL_UNFOCUS +events. Changing the focus does not send FL_FOCUS to +this or any widget, because sending FL_FOCUS is supposed to +test if the widget wants the focus (by it returning non-zero from +handle()). + +

void foreground(uchar, uchar, uchar);

+ +

Changes fl_color(FL_BLACK). Also changes +FL_INACTIVE_COLOR and FL_SELECTION_COLOR to be a ramp +between this and FL_WHITE. + +

void free_color(Fl_Color c, int overlay = 0);

+ +

Frees the specified color from the colormap, if applicable. +If overlay is non-zero then the color is freed from the +overlay colormap. + +

unsigned get_color(Fl_Color c);
+void get_color(Fl_Color c, uchar&r, uchar&g, uchar&b);

+ +

Returns the color index or RGB value for the given FLTK color index. + +

const char* get_font(Fl_Font);

+ +

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

const char* get_font_name(Fl_Font, int* attributes = 0);

+ +

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

The integer pointed to by attributes (if the pointer is not +zero) is set to zero, FL_BOLD or FL_ITALIC or +FL_BOLD | FL_ITALIC. 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. + +

int get_font_sizes(Fl_Font, int*& sizep);

+ +

Return an array of sizes in sizep. 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 fl_font() that will +be matched exactly (fl_font() 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. + +

int get_key(int);

+ +

void get_mouse(int &x,int &y);

+ +

Return where the mouse is on the screen by doing a round-trip query to +the server. You should use Fl::event_x_root() and +Fl::event_y_root() 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. + +

void get_system_colors();

+ +

Read the user preference colors from the system and use them to call + Fl::foreground(), Fl::background(), and +Fl::background2(). This is done by +Fl_Window::show(argc,argv) before applying the -fg and -bg +switches. + +

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

int gl_visual(int, int *alist=0);

+ +

This does the same thing as +Fl::visual(int) but also +requires OpenGL drawing to work. This must be done if +you want to draw in normal windows with OpenGL with gl_start() and +gl_end(). It may be useful to call this so your X +windows use the same visual as an +Fl_Gl_Window, which on +some servers will reduce colormap flashing. + +

See Fl_Gl_Window +for a list of additional values for the argument. + +

Fl_Window* grab();
+void grab(Fl_Window&w) {grab(&w);}

+ +

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 does not have to be +shown() , this lets the handle() 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 +some window must be mapped because the system interface needs a +window id). + +

If grab() 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. + +

To turn off grabbing do Fl::grab(0). + +

Be careful that your program does not enter an infinite loop +while grab() is on. On X this will lock up your screen! + +

int h();

+ +

Returns the height of the screen in pixels. + +

int handle(int, Fl_Window*);

+ +

Sends the event to a window for processing. Returns non-zero if any +widget uses the event. + +

int has_check(Fl_Timeout_Handler, void* = 0);

+ +

Returns true if the check exists and has not been called yet. + +

int has_idle(void (cb)(void), void* = 0);

+ +

Returns true if the specified idle callback is currently installed. + +

int has_timeout(Fl_Timeout_Handler, void* = 0);

+ +

Returns true if the timeout exists and has not been called yet. + +

Fl_Window* modal();

+ +

Returns the top-most modal() window currently shown. +This is the most recently +shown() window with +modal() true, or NULL if there are no modal() +windows shown(). +The modal() window has its handle() method called +for all events, and no other windows will have handle() +called (grab() overrides this). + +

Fl_Window* next_window(const Fl_Window*);

+ +

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

void own_colormap();

+ +

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

This does nothing if the current visual is not colormapped. + +

void paste(Fl_Widget &receiver);

+ +

Set things up so the receiver widget will be called with an +FL_PASTE event some time in the future. The reciever +should be prepared to be called directly by this, or for it to +happen later, or possibly not at all. 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. + +

Fl_Widget* pushed();
+void pushed(Fl_Widget*);

+ +

Get or set the widget that is being pushed. FL_DRAG or +FL_RELEASE (and any more FL_PUSH) events will be sent to +this widget. + +

If you change the pushed widget, the previous one and all parents +(that don't contain the new widget) are sent FL_RELEASE +events. Changing this does not send FL_PUSH to this +or any widget, because sending FL_PUSH is supposed to test +if the widget wants the mouse (by it returning non-zero from +handle()). + +

Fl_Widget* readqueue();

+ +

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

int ready();

+ +

This is similar to Fl::check() except this does not +call Fl::flush() or any callbacks, which is useful if your +program is in a state where such callbacks are illegal. This returns +true if Fl::check() would do anything (it will continue to +return true until you call Fl::check() or Fl::wait()). + +

+while (!calculation_done()) {
+ calculate();
+ if (Fl::ready()) {
+   do_expensive_cleanup();
+   Fl::check();
+   if (user_hit_abort_button()) break;
+ }
+}
+

+ +

void redraw();

+ +

Redraws all widgets. + +

void release();

+ +

void remove_check(Fl_Timeout_Handler, void* = 0);

+ +

Removes a check callback. It is harmless to remove a check +callback that no longer exists. + +

void remove_fd(int, int when);
+void remove_fd(int);

+ +

void remove_idle(void (cb)(void), void* = 0);

+ +

Removes the specified idle callback, if it is installed. + +

void remove_timeout(Fl_Timeout_Handler, void* = 0);

+ +

Removes a timeout callback. It is harmless to remove a timeout +callback that no longer exists. + +

void repeat_timeout(double t, Fl_Timeout_Handler,void* = 0);

+ +

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 t seconds, as the real timeout will be reduced to zero). + +

It is undefined what this does if called from outside a timeout +callback. + +

This code will print "TICK" each second on stdout, with a +fair degree of accuracy: + +

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

+ +

int run();

+ +

As long as any windows are displayed this calls Fl::wait() +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 main() +with return Fl::run();. + +

void selection(Fl_Widget &owner, const char* stuff, int len);

+ +

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 FL_PASTE as this may be the same buffer +returned by event_text()). The selection_owner() +widget is set to the passed owner (possibly sending +FL_SELECTIONCLEAR to the previous owner). + +

Fl_Widget* selection_owner();
+void selection_owner(Fl_Widget*);

+ +

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

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

void set_abort(void (f)(const char,...));

+ +

void set_atclose(void (f)(Fl_Window,void*));

+ +

void set_boxtype(Fl_Boxtype, Fl_Box_Draw_F*,uchar,uchar,uchar,uchar);
+void set_boxtype(Fl_Boxtype, Fl_Boxtype from);

+ +

The first form sets the function to call to draw a specific boxtype. + +

The second form copies the from boxtype. + +

void set_color(Fl_Color, uchar, uchar, uchar);
+void set_color(Fl_Color, unsigned);

+ +

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

void set_font(Fl_Font, const char*);
+void set_font(Fl_Font, Fl_Font);

+ +

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

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

void set_idle(void (*cb)());

+ +

void set_labeltype(Fl_Labeltype,Fl_Label_Draw_F,Fl_Label_Measure_F);
+void 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 test_shortcut(int);

+ +

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

double version();

+ +

Returns the compiled-in value of the FL_VERSION constant. This +is useful for checking the version of a shared library. + +

void visible_focus(int v);
+int visible_focus();

+ +

Gets or sets the visible keyboard focus on buttons and other +non-text widgets. The default mode is to enable keyboard focus +for all widgets. + +

int visual(int);

+ +

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

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

+ +

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

int w();

+ +

Returns the width of the screen in pixels. + +

int wait();
+double wait(double time);

+ +

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

What this really does is call all idle callbacks, all elapsed +timeouts, call Fl::flush() 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 Fl::add_fd() callbacks. It then handles the events and +calls the callbacks and then returns. + +

The return value of the first form is non-zero if there are +any visible windows - this may change in future versions of +FLTK. + +

The second form waits a maximum of time +seconds. It can return much sooner if something happens. + +

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 time is zero). It is negative if an error +occurs (this will happen on Unix if a signal happens). + +

void (warning)(const char, ...);

+ +

FLTK calls this to print a warning message. You can +override the behavior by setting the function pointer to your +own routine. + +

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, for example. + +

int x();

The constructors create a new bitmap from the specified bitmap data.

Returns the origin of the current screen, where 0 indicates +the left side of the screen. -

Fl_Bitmap::~Fl_Bitmap();

int y();

The destructor free all memory and server resources that are used by -the bitmap.

Returns the origin of the current screen, where 0 indicates +the top edge of the screen. diff --git a/documentation/Fl_Text_Display.html b/documentation/Fl_Text_Display.html index a99da8d93..68ddd6db9 100644 --- a/documentation/Fl_Text_Display.html +++ b/documentation/Fl_Text_Display.html @@ -1,336 +1,169 @@ - + + + +

class Fl_Input

Class Hierarchy

-Fl_Input_
+Fl_Group
    |
-   +----Fl_Input
+   +----Fl_Text_Display----Fl_Text_Buffer
            |
-           +----Fl_Float_Input, Fl_Int_Input,
-                Fl_Multiline_Input, Fl_Secret_Input
+           +----Fl_Text_Editor

Include Files

-#include <FL/Fl_Input.H>
+#include <FL/Fl_Text_Display.H>

Description

This is the FLTK text input widget. It displays a single line of text -and lets the user edit it. Normally it is drawn with an inset box and -a white background. The text may contain any characters (even 0), and -will correctly display anything, using ^X notation for unprintable -control characters and \nnn notation for unprintable characters with -the high bit set. It assumes the font can draw any characters in the -ISO-8859-1 character set. - -

- - - - - - - - - - - - - - - - - - - - - - - - -

Mouse button 1	Moves the cursor to - this point. Drag selects characters. Double click selects words. - Triple click selects all text. Shift+click extends the selection. - When you select text it is automatically copied to the clipboard. -
Mouse button 2	Insert the clipboard at -the point clicked. You can also select a region and replace it with the -clipboard by selecting the region with mouse button 2. -
Mouse button 3	Currently acts like button 1.
Backspace	Deletes one character to the left, or -deletes the selected region.
Enter	May cause the callback, see when().
^A or Home	Go to start of line.
^B or Left	Move left
^C	Copy the selection to the clipboard
^D or Delete	Deletes one character to the right -or deletes the selected region.
^E or End	Go to the end of line.
^F or Right	Move right
^K	Delete to the end of line (next \n character) -or deletes a single \n character. These deletions are all concatenated -into the clipboard.
^N or Down	Move down (for Fl_Multiline_Input -only, otherwise it moves to the next input field).
^P or Up	Move up (for Fl_Multiline_Input only, -otherwise it moves to the previous input field).
^U	Delete everything.
^V or ^Y	Paste the clipboard
^X or ^W	Copy the region to the clipboard and -delete it.
^Z or ^_	Undo. This is a single-level undo -mechanism, but all adjacent deletions and insertions are concatenated -into a single "undo". Often this will undo a lot more than you -expected.
Shift+move	Move the cursor but also extend the -selection.
RightCtrl or - Compose	Start -a compose-character -sequence. The next one or two keys typed define the character to -insert (see table that follows.) - - For instance, to type "�" type [compose][a]['] or [compose]['][a]. - - The character "nbsp" (non-breaking space) is typed by using -[compose][space]. - - The single-character sequences may be followed by a space if -necessary to remove ambiguity. For instance, if you really want to -type "�~" rather than "�" you must type [compose][a][space][~]. - - The same key may be used to "quote" control characters into the -text. If you need a `^Q` character you can get one by typing -[compose][Control+Q]. - - X may have a key on the keyboard -defined as `XK_Multi_key`. If so this key may be used as well -as the right-hand control key. You can set this up with the program -`xmodmap`. - - If your keyboard is set to support a foreign language you should -also be able to type "dead key" prefix characters. On X you will -actually be able to see what dead key you typed, and if you then move -the cursor without completing the sequence the accent will remain -inserted. -

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Character Composition Table
Keys	Char	Keys	Char	Keys	Char	Keys	Char	Keys	Char	Keys	Char
`sp`	nbsp	`*`	�	` A	�	`D -`	�	` a	�	`d -`	� -
`!`	�	`+ -`	�	`' A`	�	`~ N`	�	`' a`	�	`~ n`	� -
`%`	�	`2`	�	`A ^`	�	` O	�	`^ a`	�	` o	� -
`#`	�	`3`	�	`~ A`	�	`' O`	�	`~ a`	�	`' o`	� -
`$`	�	`'`	�	`: A`	�	`^ O`	�	`: a`	�	`^ o`	� -
`y =`	�	`u`	�	`* A`	�	`~ O`	�	`* a`	�	`~ o`	� -
`\|`	�	`p`	�	`A E`	�	`: O`	�	`a e`	�	`: o`	� -
`&`	�	`.`	�	`, C`	�	`x`	�	`, c`	�	`- :`	� -
`:`	�	`,`	�	E `	�	`O /`	�	` e	�	`o /`	� -
`c`	�	`1`	�	`' E`	�	` U	�	`' e`	�	` u	� -
`a`	�	`o`	�	`^ E`	�	`' U`	�	`^ e`	�	`' u`	� -
`< <`	�	`> >`	�	`: E`	�	`^ U`	�	`: e`	�	`^ u`	� -
`~`	�	`1 4`	�	` I	�	`: U`	�	` i	�	`: u`	� -
`-`	�	`1 2`	�	`' I`	�	`' Y`	�	`' i`	�	`' y`	� -
`r`	�	`3 4`	�	`^ I`	�	`T H`	�	`^ i`	�	`t h`	� -
`_`	�	`?`	�	`: I`	�	`s s`	�	`: i`	�	`: y`	� -

This is the FLTK text display widget. It allows the user to +view multiple lines of text and supports highlighting and +scrolling. The buffer that is displayed in the widget is managed +by the Fl_Text_Buffer +class. +

Methods

- - - -

Fl_Input
~Fl_Input
cursor_color

index
size

static_value
textcolor

textfont
textsize

value
when

- -

Fl_Input::Fl_Input(int x, int y, int w, -int h, const char *label = 0)

- Creates a new Fl_Input widget using the given position, size, -and label string. The default boxtype is FL_DOWN_BOX. -

virtual Fl_Input::~Fl_Input()

- Destroys the widget and any value associated with it. -

const char Fl_Input::value() const -
int Fl_Input::value(const char) -
int Fl_Input::value(const char*, int)

- The first form returns the current value, which is a pointer to the -internal buffer and is valid only until the next event is handled. -

The second two forms change the text and set the mark and the point -to the end of it. The string is copied to the internal buffer. Passing -NULL is the same as "". This returns non-zero if the new value is -different than the current one. You can use the second version to -directly set the length if you know it already or want to put nul's in -the text.

int Fl_Input::static_value(const -char) -
int Fl_Input::static_value(const char, int)

- Change the text and set the mark and the point to the end of it. The -string is not copied. If the user edits the string it is copied -to the internal buffer then. This can save a great deal of time and -memory if your program is rapidly changing the values of text fields, -but this will only work if the passed string remains unchanged until -either the Fl_Input is destroyed or value() is called -again. -

int Fl_Input::size() const

- Returns the number of characters in value(). This may be -greater than strlen(value()) if there are nul characters in -it. -

char Fl_Input::index(int) const

- Same as value()[n], but may be faster in plausible -implementations. No bounds checking is done. -

Fl_When Fl_Widget::when() const -
void Fl_Widget::when(Fl_When)

- Controls when callbacks are done. The following values are useful, -the default value is FL_WHEN_RELEASE: +

0: The callback is not done, but changed() is - turned on.
FL_WHEN_CHANGED: The callback is done each time the text -is changed by the user.
FL_WHEN_RELEASE: The callback will be done when this -widget loses the focus, including when the window is unmapped. This -is a useful value for text fields in a panel where doing the callback -on every change is wasteful. However the callback will also happen if -the mouse is moved out of the window, which means it should not do -anything visible (like pop up an error message). You might do better -setting this to zero, and scanning all the items for changed() - when the OK button on a panel is pressed.
FL_WHEN_ENTER_KEY: If the user types the Enter key, the -entire text is selected, and the callback is done if the text has -changed. Normally the Enter key will navigate to the next field (or -insert a newline for a Fl_Mulitline_Input), this changes the -behavior.
FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED: The Enter key will -do the callback even if the text has not changed. Useful for command -fields.
Fl_Text_Display
~Fl_Text_Display
buffer
cursor_style
hide_cursor
highlight_data
in_selection
insert
insert_position
move_down
move_left
move_right
move_up
next_word
overstrike
position_style
previous_word
redisplay_range
scrollbar_align
scrollbar_width
scroll
show_cursor
show_insert_position
textcolor
textfont
textsize
word_end
word_start

Fl_Color Fl_Input::textcolor() const -
void Fl_Input::textcolor(Fl_Color)

- Gets or sets the color of the text in the input field. -

Fl_Font Fl_Input::textfont() const -
void Fl_Input::textfont(Fl_Font)

- Gets or sets the font of the text in the input field. -

uchar Fl_Input::textsize() const -
void Fl_Input::textsize(uchar)

- Gets or sets the size of the text in the input field. -

Fl_Color Fl_Input::cursor_color() -const -
void Fl_Input::cursor_color(Fl_Color)

- Get or set the color of the cursor. This is black by default. - - + +

Fl_Text_Display(int X, int Y, int W, int H, const char *l = 0);

+ + +

~Fl_Text_Display();

+ + +

void buffer(Fl_Text_Buffer* buf);
+void buffer(Fl_Text_Buffer& buf);
+Fl_Text_Buffer* buffer();

+ +

void cursor_style(int style);

+ + +

void hide_cursor();

+ + +

void highlight_data(Fl_Text_Buffer styleBuffer, +Style_Table_Entry styleTable, int nStyles, char +unfinishedStyle, Unfinished_Style_Cb unfinishedHighlightCB, void +*cbArg);

+ + +

int in_selection(int x, int y);

+ + +

void insert(const char* text);

+ + +

void insert_position(int newPos);
+int insert_position()

+ + +

int move_down();

+ + +

int move_left();

+ + +

int move_right();

+ + +

int move_up();

+ + +

void next_word(void);

+ + +

void overstrike(const char* text);

+ + +

int position_style(int lineStartPos, int lineLen, int lineIndex, +int dispIndex);

+ + +

void previous_word(void);

+ + +

void redisplay_range(int start, int end);

+ + +

void scrollbar_align(Fl_Align a);
+Fl_Align scrollbar_align();

+ + +

void scrollbar_width(int w);
+int scrollbar_width();

+ + +

void scroll(int topLineNum, int horizOffset);

+ + +

void show_cursor(int b = 1);

+ + +

void show_insert_position();

+ + +

void textcolor(unsigned n);
+Fl_Color textcolor() const;

+ + +

void textfont(uchar s);
+Fl_Font textfont() const;

+ + +

void textsize(uchar s);
+uchar textsize() const;

+ + +

int word_end(int pos);

+ + +

int word_start(int pos);

+ + + + diff --git a/documentation/Fl_Text_Editor.html b/documentation/Fl_Text_Editor.html index a99da8d93..f849edaf4 100644 --- a/documentation/Fl_Text_Editor.html +++ b/documentation/Fl_Text_Editor.html @@ -1,336 +1,173 @@ - + + + -

class Fl_Input

+ +

class Fl_Text_Editor

Class Hierarchy

-Fl_Input_
+Fl_Text_Display
    |
-   +----Fl_Input
-           |
-           +----Fl_Float_Input, Fl_Int_Input,
-                Fl_Multiline_Input, Fl_Secret_Input
+   +----Fl_Text_Editor

Include Files

-#include <FL/Fl_Input.H>
+#include <FL/Fl_Text_Editor.H>

Description

- - - - - - - - - - - - - - - - - - - - - - - - -

Mouse button 1	Moves the cursor to - this point. Drag selects characters. Double click selects words. - Triple click selects all text. Shift+click extends the selection. - When you select text it is automatically copied to the clipboard. -
Mouse button 2	Insert the clipboard at -the point clicked. You can also select a region and replace it with the -clipboard by selecting the region with mouse button 2. -
Mouse button 3	Currently acts like button 1.
Backspace	Deletes one character to the left, or -deletes the selected region.
Enter	May cause the callback, see when().
^A or Home	Go to start of line.
^B or Left	Move left
^C	Copy the selection to the clipboard
^D or Delete	Deletes one character to the right -or deletes the selected region.
^E or End	Go to the end of line.
^F or Right	Move right
^K	Delete to the end of line (next \n character) -or deletes a single \n character. These deletions are all concatenated -into the clipboard.
^N or Down	Move down (for Fl_Multiline_Input -only, otherwise it moves to the next input field).
^P or Up	Move up (for Fl_Multiline_Input only, -otherwise it moves to the previous input field).
^U	Delete everything.
^V or ^Y	Paste the clipboard
^X or ^W	Copy the region to the clipboard and -delete it.
^Z or ^_	Undo. This is a single-level undo -mechanism, but all adjacent deletions and insertions are concatenated -into a single "undo". Often this will undo a lot more than you -expected.
Shift+move	Move the cursor but also extend the -selection.
RightCtrl or - Compose	Start -a compose-character -sequence. The next one or two keys typed define the character to -insert (see table that follows.) - - For instance, to type "�" type [compose][a]['] or [compose]['][a]. - - The character "nbsp" (non-breaking space) is typed by using -[compose][space]. - - The single-character sequences may be followed by a space if -necessary to remove ambiguity. For instance, if you really want to -type "�~" rather than "�" you must type [compose][a][space][~]. - - The same key may be used to "quote" control characters into the -text. If you need a `^Q` character you can get one by typing -[compose][Control+Q]. - - X may have a key on the keyboard -defined as `XK_Multi_key`. If so this key may be used as well -as the right-hand control key. You can set this up with the program -`xmodmap`. - - If your keyboard is set to support a foreign language you should -also be able to type "dead key" prefix characters. On X you will -actually be able to see what dead key you typed, and if you then move -the cursor without completing the sequence the accent will remain -inserted. -

Character Composition Table
Keys	Char	Keys	Char	Keys	Char	Keys	Char	Keys	Char	Keys	Char
`sp`	nbsp	`*`	�	` A	�	`D -`	�	` a	�	`d -`	� -
`!`	�	`+ -`	�	`' A`	�	`~ N`	�	`' a`	�	`~ n`	� -
`%`	�	`2`	�	`A ^`	�	` O	�	`^ a`	�	` o	� -
`#`	�	`3`	�	`~ A`	�	`' O`	�	`~ a`	�	`' o`	� -
`$`	�	`'`	�	`: A`	�	`^ O`	�	`: a`	�	`^ o`	� -
`y =`	�	`u`	�	`* A`	�	`~ O`	�	`* a`	�	`~ o`	� -
`\|`	�	`p`	�	`A E`	�	`: O`	�	`a e`	�	`: o`	� -
`&`	�	`.`	�	`, C`	�	`x`	�	`, c`	�	`- :`	� -
`:`	�	`,`	�	E `	�	`O /`	�	` e	�	`o /`	� -
`c`	�	`1`	�	`' E`	�	` U	�	`' e`	�	` u	� -
`a`	�	`o`	�	`^ E`	�	`' U`	�	`^ e`	�	`' u`	� -
`< <`	�	`> >`	�	`: E`	�	`^ U`	�	`: e`	�	`^ u`	� -
`~`	�	`1 4`	�	` I	�	`: U`	�	` i	�	`: u`	� -
`-`	�	`1 2`	�	`' I`	�	`' Y`	�	`' i`	�	`' y`	� -
`r`	�	`3 4`	�	`^ I`	�	`T H`	�	`^ i`	�	`t h`	� -
`_`	�	`?`	�	`: I`	�	`s s`	�	`: i`	�	`: y`	� -

This is the FLTK text editor widget. It allows the user to +edit multiple lines of text and supports highlighting and +scrolling. The buffer that is displayed in the widget is managed +by the Fl_Text_Buffer +class.

Methods

- - - -

Fl_Input
~Fl_Input
cursor_color

index
size

static_value
textcolor

textfont
textsize

value
when

- -

Fl_Input::Fl_Input(int x, int y, int w, -int h, const char *label = 0)

- Creates a new Fl_Input widget using the given position, size, -and label string. The default boxtype is FL_DOWN_BOX. -

virtual Fl_Input::~Fl_Input()

- Destroys the widget and any value associated with it. -

const char Fl_Input::value() const -
int Fl_Input::value(const char) -
int Fl_Input::value(const char*, int)

- The first form returns the current value, which is a pointer to the -internal buffer and is valid only until the next event is handled. -

int Fl_Input::static_value(const -char) -
int Fl_Input::static_value(const char, int)

int Fl_Input::size() const

- Returns the number of characters in value(). This may be -greater than strlen(value()) if there are nul characters in -it. -

char Fl_Input::index(int) const

- Same as value()[n], but may be faster in plausible -implementations. No bounds checking is done. -

Fl_When Fl_Widget::when() const -
void Fl_Widget::when(Fl_When)

- Controls when callbacks are done. The following values are useful, -the default value is FL_WHEN_RELEASE: +

0: The callback is not done, but changed() is - turned on.
FL_WHEN_CHANGED: The callback is done each time the text -is changed by the user.
FL_WHEN_RELEASE: The callback will be done when this -widget loses the focus, including when the window is unmapped. This -is a useful value for text fields in a panel where doing the callback -on every change is wasteful. However the callback will also happen if -the mouse is moved out of the window, which means it should not do -anything visible (like pop up an error message). You might do better -setting this to zero, and scanning all the items for changed() - when the OK button on a panel is pressed.
FL_WHEN_ENTER_KEY: If the user types the Enter key, the -entire text is selected, and the callback is done if the text has -changed. Normally the Enter key will navigate to the next field (or -insert a newline for a Fl_Mulitline_Input), this changes the -behavior.
FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED: The Enter key will -do the callback even if the text has not changed. Useful for command -fields.
Fl_Text_Editor
~Fl_Text_Editor
add_default_key_bindings
add_key_binding
bound_key_function
default_key_function
insert_mode
kf_backspace
kf_copy
kf_c_s_move
kf_ctrl_move
kf_cut
kf_default
kf_delete
kf_down
kf_end
kf_enter
kf_home
kf_ignore
kf_insert
kf_left
kf_move
kf_page_down
kf_page_up
kf_paste
kf_right
kf_select_all
kf_shift_move
kf_up
remove_all_key_bindings
remove_key_binding

Fl_Color Fl_Input::textcolor() const -
void Fl_Input::textcolor(Fl_Color)

- Gets or sets the color of the text in the input field. -

Fl_Font Fl_Input::textfont() const -
void Fl_Input::textfont(Fl_Font)

- Gets or sets the font of the text in the input field. -

uchar Fl_Input::textsize() const -
void Fl_Input::textsize(uchar)

- Gets or sets the size of the text in the input field. -

Fl_Color Fl_Input::cursor_color() -const -
void Fl_Input::cursor_color(Fl_Color)

- Get or set the color of the cursor. This is black by default. - - + +

Fl_Text_Editor(int X, int Y, int W, int H, const char* l = 0);

+ + +

~Fl_Text_Editor();

+ + +

void add_default_key_bindings(Key_Binding** list);

+ + +

void add_key_binding(int key, int state, Key_Func f, Key_Binding** list);
+void add_key_binding(int key, int state, Key_Func f);

+ + +

Key_Func bound_key_function(int key, int state, Key_Binding* list);
+Key_Func bound_key_function(int key, int state);

+ + +

void default_key_function(Key_Func f);

+ + +

void insert_mode(int b);
+int insert_mode();

+ + +

int kf_backspace(int c, Fl_Text_Editor* e);

+ + +

int kf_copy(int c, Fl_Text_Editor* e);

+ + +

int kf_c_s_move(int c, Fl_Text_Editor* e);

+ + +

int kf_ctrl_move(int c, Fl_Text_Editor* e);

+ + +

int kf_cut(int c, Fl_Text_Editor* e);

+ + +

int kf_default(int c, Fl_Text_Editor* e);

+ + +

int kf_delete(int c, Fl_Text_Editor* e);

+ + +

int kf_down(int c, Fl_Text_Editor* e);

+ + +

int kf_end(int c, Fl_Text_Editor* e);

+ + +

int kf_enter(int c, Fl_Text_Editor* e);

+ + +

int kf_home(int c, Fl_Text_Editor* e);

+ + +

int kf_ignore(int c, Fl_Text_Editor* e);

+ + +

int kf_insert(int c, Fl_Text_Editor* e);

+ + +

int kf_left(int c, Fl_Text_Editor* e);

+ + +

int kf_move(int c, Fl_Text_Editor* e);

+ + +

int kf_page_down(int c, Fl_Text_Editor* e);

+ + +

int kf_page_up(int c, Fl_Text_Editor* e);

+ + +

int kf_paste(int c, Fl_Text_Editor* e);

+ + +

int kf_right(int c, Fl_Text_Editor* e);

+ + +

int kf_select_all(int c, Fl_Text_Editor* e);

+ + +

int kf_shift_move(int c, Fl_Text_Editor* e);

+ + +

int kf_up(int c, Fl_Text_Editor* e);

+ + +

void remove_all_key_bindings(Key_Binding** list);
+void remove_all_key_bindings();

+ + +

void remove_key_binding(int key, int state, Key_Binding** list);
+void remove_key_binding(int key, int state);

+ + + + diff --git a/documentation/Fl_Tooltip.html b/documentation/Fl_Tooltip.html new file mode 100644 index 000000000..00ae89ffe --- /dev/null +++ b/documentation/Fl_Tooltip.html @@ -0,0 +1,87 @@ + + + + + +

class Fl_Tooltip

+ +

Class Hierarchy

+ +

+Fl_Tooltip
+

+ +

Include Files

+ +

+#include &lt;FL/Fl_Tooltip.H&gt;
+

+ +

Description

+ +

The Fl_Tooltip class provides tooltip support for +all FLTK widgets.

+ +

Methods

+ +

color
delay
disable
enabled
enable
enter
exit
font
size

+ +

void color(unsigned c);
+Fl_Color color();

+ +

Gets or sets the background color for tooltips. The label color is +set to white or black depending on the background color. The default +background color is a pale yellow. + +

void delay(float f);
+float delay();

+ +

Gets or sets the tooltip delay. The default delay is 0.5 seconds. + +

void disable();

+ +

Disables tooltips on all widgets. + +

int enabled();

+ +

Returns non-zero if tooltips are enabled. + +

void enable(int b = 1);

+ +

Enables tooltips on all widgets. + +

void enter(Fl_Widget *w);

+ +

This method is called when the mouse pointer enters a +widget. + +

void exit(Fl_Widget *w);

+ +

This method is called when the mouse pointer leaves a +widget. + +

void font(int i);
+int font();

+ +

Gets or sets the typeface for the tooltip text. + +

void size(int s);
+int size();

+ +

Gets or sets the size of the tooltip text. + + + diff --git a/documentation/Makefile b/documentation/Makefile index 1d4b24f08..610a676a2 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -1,5 +1,5 @@ # -# "$Id: Makefile,v 1.9.2.10.2.3 2001/11/27 02:09:45 easysw Exp $" +# "$Id: Makefile,v 1.9.2.10.2.4 2001/11/28 20:43:44 easysw Exp $" # # Documentation makefile for the Fast Light Tool Kit (FLTK). # @@ -48,6 +48,7 @@ HTMLFILES = \ editor.html \ enumerations.html \ events.html \ + Fl.html \ Fl_Adjuster.html \ Fl_Bitmap.html \ Fl_Box.html \ @@ -115,6 +116,7 @@ HTMLFILES = \ Fl_Tiled_Image.html \ Fl_Tile.html \ Fl_Timer.html \ + Fl_Tooltip.html \ fluid.html \ Fl_Valuator.html \ Fl_Value_Input.html \ @@ -199,5 +201,5 @@ fltk.pdf: $(HTMLFILES) $(HTMLDOC) -f fltk.pdf --jpeg --compression=9 --duplex --verbose --toclevels 2 --titleimage FL.gif $(HTMLFILES) # -# End of "$Id: Makefile,v 1.9.2.10.2.3 2001/11/27 02:09:45 easysw Exp $". +# End of "$Id: Makefile,v 1.9.2.10.2.4 2001/11/28 20:43:44 easysw Exp $". # diff --git a/documentation/fltk.book b/documentation/fltk.book index 1d00e2691..e9d67b5fb 100644 --- a/documentation/fltk.book +++ b/documentation/fltk.book @@ -77,6 +77,7 @@ Fl_Text_Editor.html Fl_Tile.html Fl_Tiled_Image.html Fl_Timer.html +Fl_Tooltip.html Fl_Valuator.html Fl_Value_Input.html Fl_Value_Output.html 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 @@

B - Function Reference

-This appendix describes all of the fl_ functions and Fl:: -methods. For a description of the FLTK widgets, see Appendix A. +This appendix describes all of the fl_ functions. For a +description of the FLTK classes, see Appendix +A.

Functions

@@ -235,858 +235,5 @@ subexpressions literally.

x all other characters must be matched exactly.

Fl:: Methods

- -

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)

- -Add file descriptor fd to listen to. When the fd -becomes ready for reading Fl::wait() will call the callback -and then return. The callback is -passed the fd and the arbitrary void* argument. - -

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

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

Under UNIX any file descriptor can be monitored (files, -devices, pipes, sockets, etc.) Due to limitations in Microsoft Windows, -WIN32 applications can only monitor sockets. - -

static void Fl::add_handler(int (*f)(int))

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

FL_SHORTCUT events that are not recognized by any widget. -This lets you provide global shortcut keys.
System events that FLTK does not recognize. See -fl_xevent.
Some other events when the widget FLTK selected returns -zero from its handle() method. Exactly which ones may change -in future versions, however.

- -

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

- -Adds a callback function that is called every time by -Fl::wait() and also makes it act as though the timeout is -zero (this makes Fl::wait() 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. - -

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

Fl::wait() and Fl::check() call idle callbacks, -but Fl::ready() does not. - -

The idle callback can call any FLTK functions, including -Fl::wait(), Fl::check(), and Fl::ready(). -Fltk will not recursively call the idle callback. - -

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

- -Add a one-shot timeout callback. The function will be called by -Fl::wait() at t seconds after this function is called. -The optional void* argument is passed to the callback. - -

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

- -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 t seconds, as the real timeout will be reduced to zero). - -

It is undefined what this does if called from outside a timeout -callback. - -

This code will print "TICK" each second on stdout, with a -fair degree of accuracy: - -

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

- -

static void Fl::add_check(void (cb)(void),void*v=0)

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

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

Sample code: - -

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();
-}

- -

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

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

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 -window->show(argc,argv), which will do anything stored in the -static variables. - -

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

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

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

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

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

-display host:n.n The X display to use (ignored under -WIN32).
-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, possibly changing its icon.
-title string Fl_Window::label(string) will be done to -the window, changing both its title and the icontitle.
-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. Under WIN32 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.
-fg color XParseColor is used to lookup the passed color -and then Fl::foreground() is done.

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

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

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

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

static Fl_Widget Fl::belowmouse() const -
static void Fl::belowmouse(Fl_Widget )

- -Get or set the widget that is below the mouse. This is for -highlighting buttons. It is not used to send FL_PUSH or -FL_MOVE directly, for several obscure reasons, but those events -typically go to this widget. This is also the first widget tried for -FL_SHORTCUT events. - -

If you change the belowmouse widget, the previous one and all -parents (that don't contain the new widget) are sent FL_LEAVE -events. Changing this does not send FL_ENTER to this -or any widget, because sending FL_ENTER is supposed to test -if the widget wants the mouse (by it returning non-zero from -handle()). - -

static int Fl::box_dh(Fl_Boxtype)

- -Returns the height offset for the given boxtype. - -

static int Fl::box_dw(Fl_Boxtype)

- -Returns the width offset for the given boxtype. - -

static int Fl::box_dx(Fl_Boxtype)

- -Returns the X offset for the given boxtype. - -

static int Fl::box_dy(Fl_Boxtype)

- -Returns the Y offset for the given boxtype. - -

static int Fl::check()

- -Same as Fl::wait(0). Calling this during a big calculation -will keep the screen up to date and the interface responsive: - -

while (!calculation_done()) {
- calculate();
- Fl::check();
- if (user_hit_abort_button()) break;
-}

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

static int Fl::damage()

- -If true then flush() will do something. - -

static void Fl::display(const char *)

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

static void Fl::enable_symbols()

- -Enables the symbol drawing code. - -

static int Fl::event_button()

- -Returns which mouse button was pressed. This returns garbage if the -most recent event was not a FL_PUSH or FL_RELEASE -event. - -

int Fl::event_clicks() -
void Fl::event_clicks(int)

- -The first form returns non-zero if the most recent FL_PUSH or -FL_KEYBOARD was a "double click". Returns N-1 for -N clicks. A double click is counted if the same button is pressed -again while event_is_click() is true. - -

The second form directly sets the number returned by -Fl::event_clicks(). This can be used to set it to zero so that -later code does not think an item was double-clicked. - -

int Fl::event_inside(const Fl_Widget *) const -
int Fl::event_inside(int x, int y, int w, int h)

- -Returns non-zero if the current event_x and event_y -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. - -

int Fl::event_is_click() -
void Fl::event_is_click(0)

- -The first form returns non-zero if the mouse has not moved far enough -and not enough time has passed since the last FL_PUSH or -FL_KEYBOARD event for it to be considered a "drag" rather than a -"click". You can test this on FL_DRAG, FL_RELEASE, -and FL_MOVE events. The second form clears the value returned -by Fl::event_is_click(). Useful to prevent the next -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. - -

int Fl::event_key() -
int Fl::event_key(int) -
int Fl::get_key(int)

- -Fl::event_key() returns which key on the keyboard was last -pushed. It returns zero if the last event was not a key press or release. - -

Fl::event_key(int) returns true if the given key was held -down (or pressed) during the last event. This is constant until -the next event is read from the server. - -

Fl::get_key(int) returns true if the given key is held down -now. Under X this requires a round-trip to the server and is -much slower than Fl::event_key(int). - -

Keys are identified by the unshifted values. FLTK defines a -set of symbols that should work on most modern machines for every key -on the keyboard: - -

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.
All keys on the numeric keypad producing a printable ASCII -character use the value of that ASCII character plus FL_KP. -The highest possible value is FL_KP_Last so you can -range-check to see if something is on the keypad.
All numbered function keys use the number on the function key plus -FL_F. The highest possible number is FL_F_Last, so you -can range-check a value.
Buttons on the mouse are considered keys, and use the button -number (where the left button is 1) plus FL_Button.
All other keys on the keypad have a symbol: 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. Be -careful not to confuse these with the very similar, but all-caps, -symbols used by Fl::event_state() -.

- -On X Fl::get_key(FL_Button+n) does not work. - -

On WIN32 Fl::get_key(FL_KP_Enter) and -Fl::event_key(FL_KP_Enter) do not work. - -

char *Fl::event_length()

- -Returns the length of the text in Fl::event_text(). 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. - -

ulong Fl::event_state() -
unsigned int Fl::event_state(ulong)

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

FL_SHIFT
FL_CAPS_LOCK
FL_CTRL
FL_ALT
FL_NUM_LOCK
FL_META
FL_SCROLL_LOCK
FL_BUTTON1
FL_BUTTON2
FL_BUTTON3

- -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 -after the shift key is pressed or released. - -

char *Fl::event_text()

- -Returns the ASCII text (in the future this may be UTF-8) produced by -the last FL_KEYBOARD or FL_PASTE 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. - -

Under X this is the result of calling XLookupString(). - -

static int Fl::event_x() -
static int Fl::event_y()

- -Returns the mouse position of the event relative to the Fl_Window -it was passed to. - -

static int Fl::event_x_root() -
static int Fl::event_y_root()

- -Returns the mouse position on the screen of the event. To find the -absolute position of an Fl_Window on the screen, use the -difference between event_x_root(),event_y_root() and -event_x(),event_y(). - -

static Fl_Window *Fl::first_window()

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

static Fl_Window Fl::next_window(Fl_Window )

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

static void Fl::first_window(Fl_Window*)

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

static void Fl::flush()

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

static Fl_Widget Fl::focus() const -
static void Fl::focus(Fl_Widget )

- -Get or set the widget that will receive FL_KEYBOARD events. - -

If you change Fl::focus(), the previous widget and all -parents (that don't contain the new widget) are sent FL_UNFOCUS -events. Changing the focus does not send FL_FOCUS to -this or any widget, because sending FL_FOCUS is supposed to -test if the widget wants the focus (by it returning non-zero from -handle()). - -

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

- -Changes fl_color(FL_BLACK). Also changes -FL_INACTIVE_COLOR and FL_SELECTION_COLOR to be a ramp -between this and FL_WHITE. - -

static void Fl::free_color(Fl_Color, int overlay = 0)

- -Frees the specified color from the colormap, if applicable. If -overlay is non-zero then the color is freed from the overlay -colormap. - -

static unsigned Fl::get_color(Fl_Color) -
static void Fl::get_color(Fl_Color, uchar &r, uchar &g, uchar &b)

- -Returns the color index or RGB value for the given FLTK color index. - -

static const char *Fl::get_font(int face)

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

static const char Fl::get_font_name(int -face, int attributes = 0)

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

The integer pointed to by attributes (if the pointer is not -zero) is set to zero, FL_BOLD or FL_ITALIC or -FL_BOLD | FL_ITALIC. 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. - -

int get_font_sizes(int face, int *&sizep)

- -Return an array of sizes in sizep. 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 fl_font() that will -be matched exactly (fl_font() 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. - -

static void Fl::get_mouse(int &x, int &y)

- -Return where the mouse is on the screen by doing a round-trip query to -the server. You should use Fl::event_x_root() and -Fl::event_y_root() 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. - -

static void Fl::get_system_colors()

- -Read the user preference colors from the system and use them to call - Fl::foreground(), Fl::background(), and -Fl::background2(). This is done by -Fl_Window::show(argc,argv) before applying the -fg and -bg -switches. - -

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

static int Fl::gl_visual(int)

- -This does the same thing as Fl::visual(int) but also requires OpenGL -drawing to work. This must be done if you want to draw in -normal windows with OpenGL with -gl_start() and gl_end(). It may be useful to -call this so your X windows use the same visual as an Fl_Gl_Window, which -on some servers will reduce colormap flashing. - -

See Fl_Gl_Window -for a list of additional values for the argument. - -

static void Fl::grab(Fl_Window) -
static Fl_Window Fl::grab()

- -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 does not have to be -shown() , this lets the handle() 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 -some window must be mapped because the system interface needs a -window id). - -

If grab() 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. - -

To turn off grabbing do Fl::grab(0). - -

Be careful that your program does not enter an infinite loop -while grab() is on. On X this will lock up your screen! - -

static int Fl::h()

- -Returns the height of the screen in pixels. - -

static int Fl::handle(int, Fl_Window *)

- -Sends the event to a window for processing. Returns non-zero if any -widget uses the event. - -

static const char *Fl::help

- -This is the usage string that is displayed if Fl::args() -detects an invalid argument on the command-line. - -

static Fl_Window *Fl::modal()

- -Returns the top-most modal() window currently shown. -This is the most recently -shown() window with -modal() true, or NULL if there are no modal() -windows shown(). -The modal() window has its handle() method called -for all events, and no other windows will have handle() -called (grab() overrides this). - -

static void Fl::own_colormap()

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

This does nothing if the current visual is not colormapped. - -

static void Fl::paste(Fl_Widget *receiver)

- -Set things up so the receiver widget will be called with an -FL_PASTE event some time in the future. The reciever -should be prepared to be called directly by this, or for it to -happen later, or possibly not at all. 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. - -

static Fl_Widget Fl::pushed() const -
static void Fl::pushed(Fl_Widget )

- -Get or set the widget that is being pushed. FL_DRAG or -FL_RELEASE (and any more FL_PUSH) events will be sent to -this widget. - -

If you change the pushed widget, the previous one and all parents -(that don't contain the new widget) are sent FL_RELEASE -events. Changing this does not send FL_PUSH to this -or any widget, because sending FL_PUSH is supposed to test -if the widget wants the mouse (by it returning non-zero from -handle()). - -

static Fl_Widget *Fl::readqueue()

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

static int Fl::ready()

- -This is similar to Fl::check() except this does not -call Fl::flush() or any callbacks, which is useful if your -program is in a state where such callbacks are illegal. This returns -true if Fl::check() would do anything (it will continue to -return true until you call Fl::check() or Fl::wait()). - -

while (!calculation_done()) {
- calculate();
- if (Fl::ready()) {
-   do_expensive_cleanup();
-   Fl::check();
-   if (user_hit_abort_button()) break;
- }
-}

- -

static void Fl::redraw()

- -Redraws all widgets. - -

static int Fl::has_idle(void (cb)(void), void* = 0)

- -Returns true if the specified idle callback is currently installed. - -

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

- -Removes the specified idle callback, if it is installed. - -

static int Fl::has_timeout(void (cb)(void), void* = 0)

- -Returns true if the timeout exists and has not been called yet. - -

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

- -Removes a timeout callback. It is harmless to remove a timeout -callback that no longer exists. - -

static int Fl::has_check(void (cb)(void), void* = 0)

- -Returns true if the check exists and has not been called yet. - -

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

- -Removes a check callback. It is harmless to remove a check -callback that no longer exists. - -

static Fl::run()

- -As long as any windows are displayed this calls Fl::wait() -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 main() -with return Fl::run();. - -

static void Fl::selection(Fl_Widget owner, const -char stuff, int len) -
static const char* Fl::selection() -
static int Fl::selection_length()

- -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 FL_PASTE as this may be the same buffer -returned by event_text()). The selection_owner() -widget is set to the passed owner (possibly sending -FL_SELECTIONCLEAR 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. - -

static Fl_Widget Fl::selection_owner() const -
static void Fl::selection_owner(Fl_Widget )

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

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

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)

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

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

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

static int Fl::w()

- -Returns the width of the screen in pixels. - -

static int Fl::wait()

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

What this really does is call all idle callbacks, all elapsed -timeouts, call Fl::flush() 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 Fl::add_fd() callbacks. It then handles the events and -calls the callbacks and then returns. - -

The return value is non-zero if there are any visible windows (this -may change in future versions of fltk). - -

static double Fl::wait(double time)

- -Same as Fl::wait() except it waits a maximum of time -seconds. It can return much sooner if something happens. - -

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 time is zero). It is negative if an error -occurs (this will happen on Unix if a signal happens). - -

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. - - + + diff --git a/documentation/widgets.html b/documentation/widgets.html index bf4100968..159913ca5 100644 --- a/documentation/widgets.html +++ b/documentation/widgets.html @@ -1,75 +1,94 @@

A - Widget Reference

-This appendix describes all of the widget classes in FLTK. For a -description of the fl_ functions and Fl:: methods, -see Appendix B. +This appendix describes all of the classes in FLTK. For a +description of the fl_ functions, see +Appendix B.

Alphabetical List of Classes

- +

-Fl_Adjuster
-Fl_Box
-Fl_Browser
-Fl_Browser_
-Fl_Button
-Fl_Chart
-Fl_Check_Button
-Fl_Choice
-Fl_Clock
-Fl_Color_Chooser
-Fl_Counter
-Fl_Dial
-Fl_Double_Window
-Fl_End
-Fl_File_Browser
-Fl_File_Chooser
-Fl_File_Icon
-Fl_Float_Input
-Fl_Free
-Fl_Gl_Window
-Fl_Group
-Fl_Help_Dialog
-Fl_Help_View
-Fl_Hold_Browser
-Fl_Input
-Fl_Input_
-Fl_Int_Input
-Fl_Light_Button
-Fl_Menu_
-Fl_Menu_Bar
-Fl_Menu_Button
-Fl_Menu_Item
-Fl_Menu_Window
-Fl_Multi_Browser
-Fl_Multiline_Input
-Fl_Multiline_Output
-Fl_Output
-Fl_Overlay_Window
-Fl_Pack
-Fl_Positioner
-Fl_Repeat_Button
-Fl_Return_Button
-Fl_Roller
-Fl_Round_Button
-Fl_Scroll
-Fl_Scrollbar
-Fl_Secret_Input
-Fl_Select_Browser
-Fl_Single_Window
-Fl_Slider
-Fl_Tabs
-Fl_Tile
-Fl_Timer
-Fl_Valuator
-Fl_Value_Input
-Fl_Value_Output
-Fl_Value_Slider
-Fl_Widget
-Fl_Window
-Fl_Wizard
+Fl
+Fl_Adjuster
+Fl_Bitmap
+Fl_Box
+Fl_Browser_
+Fl_Browser
+Fl_Button
+Fl_Chart
+Fl_Check_Button
+Fl_Choice
+Fl_Clock
+Fl_Color_Chooser
+Fl_Counter
+Fl_Dial
+Fl_Double_Window
+Fl_End
+Fl_File_Browser
+Fl_File_Chooser
+Fl_File_Icon
+Fl_Float_Input
+Fl_Free
+Fl_GIF_Image
+Fl_Gl_Window
+Fl_Group
+Fl_Help_Dialog
+Fl_Help_View
+Fl_Hold_Browser
+Fl
+Fl_Image
+Fl_Input_
+Fl_Input
+Fl_Int_Input
+Fl_JPEG_Image
+Fl_Light_Button
+Fl_Menu_Bar
+Fl_Menu_Button
+Fl_Menu_
+Fl_Menu_Item
+

+Fl_Menu_Window
+Fl_Multi_Browser
+Fl_Multiline_Input
+Fl_Multiline_Output
+Fl_Output
+Fl_Overlay_Window
+Fl_Pack
+Fl_Pixmap
+Fl_PNG_Image
+Fl_PNM_Image
+Fl_Positioner
+Fl_Repeat_Button
+Fl_Return_Button
+Fl_RGB_Image
+Fl_Roller
+Fl_Round_Button
+Fl_Scrollbar
+Fl_Scroll
+Fl_Secret_Input
+Fl_Select_Browser
+Fl_Shared_Image
+Fl_Single_Window
+Fl_Slider
+Fl_Tabs
+Fl_Text_Buffer
+Fl_Text_Display
+Fl_Text_Editor
+Fl_Tiled_Image
+Fl_Tile
+Fl_Timer
+Fl_Tooltip
+Fl_Valuator
+Fl_Value_Input
+Fl_Value_Output
+Fl_Value_Slider
+Fl_Widget
+Fl_Window
+Fl_Wizard
+Fl_XBM_Image
+Fl_XPM_Image

@@ -77,90 +96,117 @@ see Appendix B.

Class Hierarchy

Fl_End -
Fl_File_Icon -
Fl_Menu_Item -
Fl_Widget -
- Fl_Box -
- Fl_Browser_ +
- Fl +
- Fl_End +
- Fl_File_Icon +
- Fl_Image
  - Fl_Browser -
    - Fl_File_Browser -
    - Fl_Hold_Browser -
    - Fl_Multi_Browser -
    - Fl_Select_Browser -
    +
  - Fl_Bitmap
    +
    - Fl_XBM_Image
      +
    +
  - Fl_Pixmap
    +
    - Fl_GIF_Image
      +
    - Fl_XPM_Image
      +
    +
  - Fl_RGB_Image
    +
    - Fl_JPEG_Image
      +
    - Fl_PNG_Image
      +
    - Fl_PNM_Image
      +
    +
  - Fl_Shared_Image
    +
  - Fl_Tiled_Image
  -
- Fl_Button +
- Fl_Menu_Item +
- Fl_Text_Buffer +
- Fl_Tooltip +
- Fl_Widget
  - Fl_Check_Button -
  - Fl_Light_Button -
  - Fl_Repeat_Button -
  - Fl_Return_Button -
  - Fl_Round_Button +
  - Fl_Box +
  - Fl_Browser_ +
    - Fl_Browser +
      - Fl_File_Browser +
      - Fl_Hold_Browser +
      - Fl_Multi_Browser +
      - Fl_Select_Browser +
      +
    +
  - Fl_Button +
    - Fl_Check_Button +
    - Fl_Light_Button +
    - Fl_Repeat_Button +
    - Fl_Return_Button +
    - Fl_Round_Button +
    +
  - Fl_Chart +
  - Fl_Clock +
  - Fl_Free +
  - Fl_Group +
    - Fl_Color_Chooser +
    - Fl_File_Chooser +
    - Fl_Help_Dialog +
    - Fl_Help_View +
    - Fl_Pack +
    - Fl_Scroll +
    - Fl_Tabs +
    - Fl_Text_Display +
      - Fl_Text_Editor +
      +
    - Fl_Tile +
    - Fl_Window +
      - Fl_Double_Window +
      - Fl_Gl_Window +
      - Fl_Menu_Window +
      - Fl_Overlay_Window +
      - Fl_Single_Window +
      +
    - Fl_Wizard +
    +
  - Fl_Input_ +
    - Fl_Input +
      - Fl_Float_Input +
      - Fl_Int_Input +
      - Fl_Multiline_Input +
      - Fl_Secret_Input +
      +
    - Fl_Output +
      - Fl_Multiline_Output +
      +
    +
  - Fl_Menu_ +
    - Fl_Choice +
    - Fl_Menu_Bar +
    - Fl_Menu_Button +
    +
  - Fl_Positioner +
  - Fl_Timer +
  - Fl_Valuator +
    - Fl_Adjuster +
    - Fl_Counter +
    - Fl_Dial +
    - Fl_Roller +
    - Fl_Slider +
      - Fl_Scrollbar +
      - Fl_Value_Slider +
      +
    - Fl_Value_Input +
    - Fl_Value_Output +
  -
- Fl_Chart -
- Fl_Clock -
- Fl_Free -
- Fl_Group -
  - Fl_Color_Chooser -
  - Fl_File_Chooser -
  - Fl_Help_Dialog -
  - Fl_Help_View -
  - Fl_Pack -
  - Fl_Scroll -
  - Fl_Tabs -
  - Fl_Tile -
  - Fl_Window -
    - Fl_Double_Window -
    - Fl_Gl_Window -
    - Fl_Menu_Window -
    - Fl_Overlay_Window -
    - Fl_Single_Window -
    -
  - Fl_Wizard -
  -
- Fl_Input_ -
  - Fl_Input -
    - Fl_Float_Input -
    - Fl_Int_Input -
    - Fl_Multiline_Input -
    - Fl_Secret_Input -
    -
  - Fl_Output -
    - Fl_Multiline_Output -
    -
  -
- Fl_Menu_ -
  - Fl_Choice -
  - Fl_Menu_Bar -
  - Fl_Menu_Button -
  -
- Fl_Positioner -
- Fl_Timer -
- Fl_Valuator -
  - Fl_Adjuster -
  - Fl_Counter -
  - Fl_Dial -
  - Fl_Roller -
  - Fl_Slider -
    - Fl_Scrollbar -
    - Fl_Value_Slider -
    -
  - Fl_Value_Input -
  - Fl_Value_Output -
  -

-- cgit v1.2.3