1 // 2 // "$Id: Fl.H 8724 2011-05-23 18:01:29Z manolo $" 3 // 4 // Main header file for the Fast Light Tool Kit (FLTK). 5 // 6 // Copyright 1998-2010 by Bill Spitzak and others. 7 // 8 // This library is free software; you can redistribute it and/or 9 // modify it under the terms of the GNU Library General Public 10 // License as published by the Free Software Foundation; either 11 // version 2 of the License, or (at your option) any later version. 12 // 13 // This library is distributed in the hope that it will be useful, 14 // but WITHOUT ANY WARRANTY; without even the implied warranty of 15 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 // Library General Public License for more details. 17 // 18 // You should have received a copy of the GNU Library General Public 19 // License along with this library; if not, write to the Free Software 20 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 21 // USA. 22 // 23 // Please report all bugs and problems on the following page: 24 // 25 // http://www.fltk.org/str.php 26 // 27 28 /** \file 29 Fl static class. 30 */ 31 32 #ifndef Fl_H 33 # define Fl_H 34 35 #ifdef FLTK_HAVE_CAIRO 36 # include <FL/Fl_Cairo.H> 37 #endif 38 39 # include "fl_utf8.h" 40 # include "Enumerations.H" 41 # ifndef Fl_Object 42 # define Fl_Object Fl_Widget /**< for back compatibility - use Fl_Widget! */ 43 # endif 44 45 # ifdef check 46 # undef check 47 # endif 48 49 50 class Fl_Widget; 51 class Fl_Window; 52 class Fl_Image; 53 struct Fl_Label; 54 55 56 /** \defgroup callback_functions Callback function typedefs 57 \brief Typedefs defined in <FL/Fl.H> for callback or handler functions passed as function parameters. 58 59 FLTK uses callback functions as parameters for some function calls, e.g. to 60 set up global event handlers (Fl::add_handler()), to add a timeout handler 61 (Fl::add_timeout()), and many more. 62 63 The typedefs defined in this group describe the function parameters used to set 64 up or clear the callback functions and should also be referenced to define the 65 callback function to handle such events in the user's code. 66 67 \see Fl::add_handler(), Fl::add_timeout(), Fl::repeat_timeout(), 68 Fl::remove_timeout() and others 69 @{ */ 70 71 /** Signature of some label drawing functions passed as parameters */ 72 typedef void (Fl_Label_Draw_F)(const Fl_Label *label, int x, int y, int w, int h, Fl_Align align); 73 74 /** Signature of some label measurement functions passed as parameters */ 75 typedef void (Fl_Label_Measure_F)(const Fl_Label *label, int &width, int &height); 76 77 /** Signature of some box drawing functions passed as parameters */ 78 typedef void (Fl_Box_Draw_F)(int x, int y, int w, int h, Fl_Color color); 79 80 /** Signature of some timeout callback functions passed as parameters */ 81 typedef void (*Fl_Timeout_Handler)(void *data); 82 83 /** Signature of some wakeup callback functions passed as parameters */ 84 typedef void (*Fl_Awake_Handler)(void *data); 85 86 /** Signature of add_idle callback functions passed as parameters */ 87 typedef void (*Fl_Idle_Handler)(void *data); 88 89 /** Signature of set_idle callback functions passed as parameters */ 90 typedef void (*Fl_Old_Idle_Handler)(); 91 92 /** Signature of add_fd functions passed as parameters */ 93 typedef void (*Fl_FD_Handler)(int fd, void *data); 94 95 /** Signature of add_handler functions passed as parameters */ 96 typedef int (*Fl_Event_Handler)(int event); 97 98 /** Signature of set_abort functions passed as parameters */ 99 typedef void (*Fl_Abort_Handler)(const char *format,...); 100 101 /** Signature of set_atclose functions passed as parameters */ 102 typedef void (*Fl_Atclose_Handler)(Fl_Window *window, void *data); 103 104 /** Signature of args functions passed as parameters */ 105 typedef int (*Fl_Args_Handler)(int argc, char **argv, int &i); 106 107 /** Signature of event_dispatch functions passed as parameters. 108 \see Fl::event_dispatch(Fl_Event_Dispatch) */ 109 typedef int (*Fl_Event_Dispatch)(int event, Fl_Window *w); 110 111 /** @} */ /* group callback_functions */ 112 113 114 /** 115 The Fl is the FLTK global (static) class containing 116 state information and global methods for the current application. 117 */ 118 class FL_EXPORT Fl { Fl()119 Fl() {}; // no constructor! 120 121 public: // should be private! 122 #ifndef FL_DOXYGEN 123 static int e_number; 124 static int e_x; 125 static int e_y; 126 static int e_x_root; 127 static int e_y_root; 128 static int e_dx; 129 static int e_dy; 130 static int e_state; 131 static int e_clicks; 132 static int e_is_click; 133 static int e_keysym; 134 static char* e_text; 135 static int e_length; 136 static Fl_Event_Dispatch e_dispatch; 137 static Fl_Widget* belowmouse_; 138 static Fl_Widget* pushed_; 139 static Fl_Widget* focus_; 140 static int damage_; 141 static Fl_Widget* selection_owner_; 142 static Fl_Window* modal_; 143 static Fl_Window* grab_; 144 static int compose_state; 145 #endif 146 /** 147 If true then flush() will do something. 148 */ damage(int d)149 static void damage(int d) {damage_ = d;} 150 151 public: 152 /** Enumerator for global FLTK options. 153 These options can be set system wide, per user, or for the running 154 application only. 155 \see Fl::option(Fl_Option, bool) 156 \see Fl::option(Fl_Option) 157 */ 158 typedef enum { 159 /// When switched on, moving the text cursor beyond the start or end of 160 /// a text in a text widget will change focus to the next text widget. 161 /// When switched off, the cursor will stop at the end of the text. 162 /// Pressing Tab or Ctrl-Tab will advance the keyboard focus. 163 OPTION_ARROW_FOCUS = 0, 164 // When switched on, FLTK will use the file chooser dialog that comes 165 // with your operating system whenever possible. When switched off, FLTK 166 // will present its own file chooser. 167 // \todo implement me 168 // OPTION_NATIVE_FILECHOOSER, 169 // When Filechooser Preview is enabled, the FLTK or native file chooser 170 // will show a preview of a selected file (if possible) before the user 171 // decides to choose the file. 172 // \todo implement me 173 //OPTION_FILECHOOSER_PREVIEW, 174 /// If visible focus is switched on, FLTK will draw a dotted rectangle 175 /// inside the widget that will receive the next keystroke. If switched 176 /// off, no such indicator will be drawn and keyboard navigation 177 /// is disabled. 178 OPTION_VISIBLE_FOCUS, 179 /// If text drag-and-drop is enabled, the user can select and drag text 180 /// from any text widget. If disabled, no dragging is possible, however 181 /// dropping text from other applications still works. 182 OPTION_DND_TEXT, 183 /// If tooltips are enabled, hovering the mouse over a widget with a 184 /// tooltip text will open a little tooltip window until the mouse leaves 185 /// the widget. If disabled, no tooltip is shown. 186 OPTION_SHOW_TOOLTIPS, 187 // don't change this, leave it always as the last element 188 /// For internal use only. 189 OPTION_LAST 190 } Fl_Option; 191 192 private: 193 static unsigned char options_[OPTION_LAST]; 194 static unsigned char options_read_; 195 196 public: 197 /* 198 Return a global setting for all FLTK applications, possibly overridden 199 by a setting specifically for this application. 200 */ 201 static bool option(Fl_Option opt); 202 203 /* 204 Override an option while the application is running. 205 */ 206 static void option(Fl_Option opt, bool val); 207 208 /** 209 The currently executing idle callback function: DO NOT USE THIS DIRECTLY! 210 211 This is now used as part of a higher level system allowing multiple 212 idle callback functions to be called. 213 \see add_idle(), remove_idle() 214 */ 215 static void (*idle)(); 216 217 #ifndef FL_DOXYGEN 218 static Fl_Awake_Handler *awake_ring_; 219 static void **awake_data_; 220 static int awake_ring_size_; 221 static int awake_ring_head_; 222 static int awake_ring_tail_; 223 static const char* scheme_; 224 static Fl_Image* scheme_bg_; 225 226 static int e_original_keysym; // late addition 227 static int scrollbar_size_; 228 #endif 229 230 231 static int add_awake_handler_(Fl_Awake_Handler, void*); 232 static int get_awake_handler_(Fl_Awake_Handler&, void*&); 233 234 public: 235 236 // API version number 237 static double version(); 238 239 // argument parsers: 240 static int arg(int argc, char **argv, int& i); 241 static int args(int argc, char **argv, int& i, Fl_Args_Handler cb = 0); 242 static void args(int argc, char **argv); 243 /** 244 Usage string displayed if Fl::args() detects an invalid argument. 245 This may be changed to point to customized text at run-time. 246 */ 247 static const char* const help; 248 249 // things called by initialization: 250 static void display(const char*); 251 static int visual(int); 252 /** 253 This does the same thing as Fl::visual(int) but also requires OpenGL 254 drawing to work. This <I>must</I> be done if you want to draw in 255 normal windows with OpenGL with gl_start() and gl_end(). 256 It may be useful to call this so your X windows use the same visual 257 as an Fl_Gl_Window, which on some servers will reduce colormap flashing. 258 259 See Fl_Gl_Window for a list of additional values for the argument. 260 */ 261 static int gl_visual(int, int *alist=0); // platform dependent 262 static void own_colormap(); 263 static void get_system_colors(); 264 static void foreground(uchar, uchar, uchar); 265 static void background(uchar, uchar, uchar); 266 static void background2(uchar, uchar, uchar); 267 268 // schemes: 269 static int scheme(const char*); 270 /** See void scheme(const char *name) */ scheme()271 static const char* scheme() {return scheme_;} 272 /** 273 Called by scheme according to scheme name. 274 Loads or reloads the current scheme selection. 275 See void scheme(const char *name) 276 */ 277 static int reload_scheme(); // platform dependent 278 static int scrollbar_size(); 279 static void scrollbar_size(int W); 280 281 // execution: 282 static int wait(); 283 static double wait(double time); 284 static int check(); 285 static int ready(); 286 static int run(); 287 static Fl_Widget* readqueue(); 288 /** 289 Adds a one-shot timeout callback. The function will be called by 290 Fl::wait() at <i>t</i> seconds after this function is called. 291 The optional void* argument is passed to the callback. 292 293 You can have multiple timeout callbacks. To remove a timeout 294 callback use Fl::remove_timeout(). 295 296 If you need more accurate, repeated timeouts, use Fl::repeat_timeout() to 297 reschedule the subsequent timeouts. 298 299 The following code will print "TICK" each second on 300 stdout with a fair degree of accuracy: 301 302 \code 303 void callback(void*) { 304 puts("TICK"); 305 Fl::repeat_timeout(1.0, callback); 306 } 307 308 int main() { 309 Fl::add_timeout(1.0, callback); 310 return Fl::run(); 311 } 312 \endcode 313 */ 314 static void add_timeout(double t, Fl_Timeout_Handler,void* = 0); // platform dependent 315 /** 316 Repeats a timeout callback from the expiration of the 317 previous timeout, allowing for more accurate timing. You may only call 318 this method inside a timeout callback. 319 320 The following code will print "TICK" each second on 321 stdout with a fair degree of accuracy: 322 323 \code 324 void callback(void*) { 325 puts("TICK"); 326 Fl::repeat_timeout(1.0, callback); 327 } 328 329 int main() { 330 Fl::add_timeout(1.0, callback); 331 return Fl::run(); 332 } 333 \endcode 334 */ 335 static void repeat_timeout(double t, Fl_Timeout_Handler, void* = 0); // platform dependent 336 static int has_timeout(Fl_Timeout_Handler, void* = 0); 337 static void remove_timeout(Fl_Timeout_Handler, void* = 0); 338 static void add_check(Fl_Timeout_Handler, void* = 0); 339 static int has_check(Fl_Timeout_Handler, void* = 0); 340 static void remove_check(Fl_Timeout_Handler, void* = 0); 341 /** 342 Adds file descriptor fd to listen to. 343 344 When the fd becomes ready for reading Fl::wait() will call the 345 callback and then return. The callback is passed the fd and the 346 arbitrary void* argument. 347 348 The second version takes a when bitfield, with the bits 349 FL_READ, FL_WRITE, and FL_EXCEPT defined, 350 to indicate when the callback should be done. 351 352 There can only be one callback of each type for a file descriptor. 353 Fl::remove_fd() gets rid of <I>all</I> the callbacks for a given 354 file descriptor. 355 356 Under UNIX <I>any</I> file descriptor can be monitored (files, 357 devices, pipes, sockets, etc.). Due to limitations in Microsoft Windows, 358 WIN32 applications can only monitor sockets. 359 */ 360 static void add_fd(int fd, int when, Fl_FD_Handler cb, void* = 0); // platform dependent 361 /** See void add_fd(int fd, int when, Fl_FD_Handler cb, void* = 0) */ 362 static void add_fd(int fd, Fl_FD_Handler cb, void* = 0); // platform dependent 363 /** Removes a file descriptor handler. */ 364 static void remove_fd(int, int when); // platform dependent 365 /** Removes a file descriptor handler. */ 366 static void remove_fd(int); // platform dependent 367 368 static void add_idle(Fl_Idle_Handler cb, void* data = 0); 369 static int has_idle(Fl_Idle_Handler cb, void* data = 0); 370 static void remove_idle(Fl_Idle_Handler cb, void* data = 0); 371 /** If true then flush() will do something. */ damage()372 static int damage() {return damage_;} 373 static void redraw(); 374 static void flush(); 375 /** \addtogroup group_comdlg 376 @{ */ 377 /** 378 FLTK calls Fl::warning() to output a warning message. 379 380 The default version on Windows returns \e without printing a warning 381 message, because Windows programs normally don't have stderr (a console 382 window) enabled. 383 384 The default version on all other platforms prints the warning message to stderr. 385 386 You can override the behavior by setting the function pointer to your 387 own routine. 388 389 Fl::warning() means that there was a recoverable problem, the display may 390 be messed up, but the user can probably keep working - all X protocol 391 errors call this, for example. The default implementation returns after 392 displaying the message. 393 \note \#include <FL/Fl.H> 394 */ 395 static void (*warning)(const char*, ...); 396 /** 397 FLTK calls Fl::error() to output a normal error message. 398 399 The default version on Windows displays the error message in a MessageBox window. 400 401 The default version on all other platforms prints the error message to stderr. 402 403 You can override the behavior by setting the function pointer to your 404 own routine. 405 406 Fl::error() means there is a recoverable error such as the inability to read 407 an image file. The default implementation returns after displaying the message. 408 \note \#include <FL/Fl.H> 409 */ 410 static void (*error)(const char*, ...); 411 /** 412 FLTK calls Fl::fatal() to output a fatal error message. 413 414 The default version on Windows displays the error message in a MessageBox window. 415 416 The default version on all other platforms prints the error message to stderr. 417 418 You can override the behavior by setting the function pointer to your 419 own routine. 420 421 Fl::fatal() must not return, as FLTK is in an unusable state, however your 422 version may be able to use longjmp or an exception to continue, as long as 423 it does not call FLTK again. The default implementation exits with status 1 424 after displaying the message. 425 \note \#include <FL/Fl.H> 426 */ 427 static void (*fatal)(const char*, ...); 428 /** @} */ 429 430 /** \defgroup fl_windows Windows handling functions 431 \brief Windows and standard dialogs handling declared in <FL/Fl.H> 432 @{ */ 433 static Fl_Window* first_window(); 434 static void first_window(Fl_Window*); 435 static Fl_Window* next_window(const Fl_Window*); 436 437 /** 438 Returns the top-most modal() window currently shown. 439 440 This is the most recently shown() window with modal() true, or NULL 441 if there are no modal() windows shown(). 442 The modal() window has its handle() method called 443 for all events, and no other windows will have handle() 444 called (grab() overrides this). 445 */ modal()446 static Fl_Window* modal() {return modal_;} 447 /** Returns the window that currently receives all events. 448 449 \return The window that currently receives all events, 450 or NULL if event grabbing is currently OFF. 451 */ grab()452 static Fl_Window* grab() {return grab_;} 453 /** Selects the window to grab. 454 This is used when pop-up menu systems are active. 455 456 Send all events to the passed window no matter where the pointer or 457 focus is (including in other programs). The window <I>does not have 458 to be shown()</I> , this lets the handle() method of a 459 "dummy" window override all event handling and allows you to 460 map and unmap a complex set of windows (under both X and WIN32 461 <I>some</I> window must be mapped because the system interface needs a 462 window id). 463 464 If grab() is on it will also affect show() of windows by doing 465 system-specific operations (on X it turns on override-redirect). 466 These are designed to make menus popup reliably 467 and faster on the system. 468 469 To turn off grabbing do Fl::grab(0). 470 471 <I>Be careful that your program does not enter an infinite loop 472 while grab() is on. On X this will lock up your screen!</I> 473 To avoid this potential lockup, all newer operating systems seem to 474 limit mouse pointer grabbing to the time during which a mouse button 475 is held down. Some OS's may not support grabbing at all. 476 */ 477 static void grab(Fl_Window*); // platform dependent 478 /** @} */ 479 480 /** \defgroup fl_events Events handling functions 481 Fl class events handling API declared in <FL/Fl.H> 482 @{ 483 */ 484 // event information: 485 /** 486 Returns the last event that was processed. This can be used 487 to determine if a callback is being done in response to a 488 keypress, mouse click, etc. 489 */ event()490 static int event() {return e_number;} 491 /** 492 Returns the mouse position of the event relative to the Fl_Window 493 it was passed to. 494 */ event_x()495 static int event_x() {return e_x;} 496 /** 497 Returns the mouse position of the event relative to the Fl_Window 498 it was passed to. 499 */ event_y()500 static int event_y() {return e_y;} 501 /** 502 Returns the mouse position on the screen of the event. To find the 503 absolute position of an Fl_Window on the screen, use the 504 difference between event_x_root(),event_y_root() and 505 event_x(),event_y(). 506 */ event_x_root()507 static int event_x_root() {return e_x_root;} 508 /** 509 Returns the mouse position on the screen of the event. To find the 510 absolute position of an Fl_Window on the screen, use the 511 difference between event_x_root(),event_y_root() and 512 event_x(),event_y(). 513 */ event_y_root()514 static int event_y_root() {return e_y_root;} 515 /** 516 Returns the current horizontal mouse scrolling associated with the 517 FL_MOUSEWHEEL event. Right is positive. 518 */ event_dx()519 static int event_dx() {return e_dx;} 520 /** 521 Returns the current vertical mouse scrolling associated with the 522 FL_MOUSEWHEEL event. Down is positive. 523 */ event_dy()524 static int event_dy() {return e_dy;} 525 /** 526 Return where the mouse is on the screen by doing a round-trip query to 527 the server. You should use Fl::event_x_root() and 528 Fl::event_y_root() if possible, but this is necessary if you are 529 not sure if a mouse event has been processed recently (such as to 530 position your first window). If the display is not open, this will 531 open it. 532 */ 533 static void get_mouse(int &,int &); // platform dependent 534 /** 535 Returns non zero if we had a double click event. 536 \retval Non-zero if the most recent FL_PUSH or FL_KEYBOARD was a "double click". 537 \retval N-1 for N clicks. 538 A double click is counted if the same button is pressed 539 again while event_is_click() is true. 540 541 */ event_clicks()542 static int event_clicks() {return e_clicks;} 543 /** 544 Manually sets the number returned by Fl::event_clicks(). 545 This can be used to set it to zero so that 546 later code does not think an item was double-clicked. 547 \param[in] i corresponds to no double-click if 0, i+1 mouse clicks otherwise 548 \see int event_clicks() 549 */ event_clicks(int i)550 static void event_clicks(int i) {e_clicks = i;} 551 /** 552 Returns non-zero if the mouse has not moved far enough 553 and not enough time has passed since the last FL_PUSH or 554 FL_KEYBOARD event for it to be considered a "drag" rather than a 555 "click". You can test this on FL_DRAG, FL_RELEASE, 556 and FL_MOVE events. 557 */ event_is_click()558 static int event_is_click() {return e_is_click;} 559 /** 560 Clears the value returned by Fl::event_is_click(). 561 Useful to prevent the <I>next</I> 562 click from being counted as a double-click or to make a popup menu 563 pick an item with a single click. Don't pass non-zero to this. 564 */ event_is_click(int i)565 static void event_is_click(int i) {e_is_click = i;} 566 /** 567 Gets which particular mouse button caused the current event. 568 This returns garbage if the most recent event was not a FL_PUSH or FL_RELEASE event. 569 \retval FL_LEFT_MOUSE \retval FL_MIDDLE_MOUSE \retval FL_RIGHT_MOUSE. 570 \see Fl::event_buttons() 571 */ event_button()572 static int event_button() {return e_keysym-FL_Button;} 573 /** 574 This is a bitfield of what shift states were on and what mouse buttons 575 were held down during the most recent event. The second version 576 returns non-zero if any of the passed bits are turned on. 577 The legal bits are: 578 579 \li FL_SHIFT 580 \li FL_CAPS_LOCK 581 \li FL_CTRL 582 \li FL_ALT 583 \li FL_NUM_LOCK 584 \li FL_META 585 \li FL_SCROLL_LOCK 586 \li FL_BUTTON1 587 \li FL_BUTTON2 588 \li FL_BUTTON3 589 590 X servers do not agree on shift states, and FL_NUM_LOCK, FL_META, and 591 FL_SCROLL_LOCK may not work. The values were selected to match the 592 XFree86 server on Linux. In addition there is a bug in the way X works 593 so that the shift state is not correctly reported until the first event 594 <I>after</I> the shift key is pressed or released. 595 */ event_state()596 static int event_state() {return e_state;} 597 /** See int event_state() */ event_state(int i)598 static int event_state(int i) {return e_state&i;} 599 /** 600 Gets which key on the keyboard was last pushed. 601 602 The returned integer 'key code' is not necessarily a text 603 equivalent for the keystroke. For instance: if someone presses '5' on the 604 numeric keypad with numlock on, Fl::event_key() may return the 'key code' 605 for this key, and NOT the character '5'. To always get the '5', use Fl::event_text() instead. 606 607 \returns an integer 'key code', or 0 if the last event was not a key press or release. 608 \see int event_key(int), event_text(), compose(int&). 609 */ event_key()610 static int event_key() {return e_keysym;} 611 /** 612 Returns the keycode of the last key event, regardless of the NumLock state. 613 614 If NumLock is deactivated, FLTK translates events from the 615 numeric keypad into the corresponding arrow key events. 616 event_key() returns the translated key code, whereas 617 event_original_key() returns the keycode before NumLock translation. 618 */ event_original_key()619 static int event_original_key(){return e_original_keysym;} 620 /** 621 Returns true if the given \p key was held 622 down (or pressed) <I>during</I> the last event. This is constant until 623 the next event is read from the server. 624 625 Fl::get_key(int) returns true if the given key is held down <I>now</I>. 626 Under X this requires a round-trip to the server and is <I>much</I> 627 slower than Fl::event_key(int). 628 629 Keys are identified by the <I>unshifted</I> values. FLTK defines a 630 set of symbols that should work on most modern machines for every key 631 on the keyboard: 632 633 \li All keys on the main keyboard producing a printable ASCII 634 character use the value of that ASCII character (as though shift, 635 ctrl, and caps lock were not on). The space bar is 32. 636 \li All keys on the numeric keypad producing a printable ASCII 637 character use the value of that ASCII character plus FL_KP. 638 The highest possible value is FL_KP_Last so you can 639 range-check to see if something is on the keypad. 640 \li All numbered function keys use the number on the function key plus 641 FL_F. The highest possible number is FL_F_Last, so you 642 can range-check a value. 643 \li Buttons on the mouse are considered keys, and use the button 644 number (where the left button is 1) plus FL_Button. 645 \li All other keys on the keypad have a symbol: FL_Escape, 646 FL_BackSpace, FL_Tab, FL_Enter, FL_Print, FL_Scroll_Lock, FL_Pause, 647 FL_Insert, FL_Home, FL_Page_Up, FL_Delete, FL_End, FL_Page_Down, 648 FL_Left, FL_Up, FL_Right, FL_Down, FL_Shift_L, FL_Shift_R, 649 FL_Control_L, FL_Control_R, FL_Caps_Lock, FL_Alt_L, FL_Alt_R, 650 FL_Meta_L, FL_Meta_R, FL_Menu, FL_Num_Lock, FL_KP_Enter. Be 651 careful not to confuse these with the very similar, but all-caps, 652 symbols used by Fl::event_state(). 653 654 On X Fl::get_key(FL_Button+n) does not work. 655 656 On WIN32 Fl::get_key(FL_KP_Enter) and Fl::event_key(FL_KP_Enter) do not work. 657 */ 658 static int event_key(int key); 659 /** 660 Returns true if the given \p key is held down <I>now</I>. 661 Under X this requires a round-trip to the server and is <I>much</I> 662 slower than Fl::event_key(int). \see event_key(int) 663 */ 664 static int get_key(int key); // platform dependent 665 /** 666 Returns the text associated with the current event, including FL_PASTE or FL_DND_RELEASE events. 667 This can be used in response to FL_KEYUP, FL_KEYDOWN, FL_PASTE, FL_DND_RELEASE. 668 669 When responding to FL_KEYUP/FL_KEYDOWN, use this function instead of Fl::event_key() 670 to get the text equivalent of keystrokes suitable for inserting into strings 671 and text widgets. 672 673 The returned string is guaranteed to be be NULL terminated. 674 However, see Fl::event_length() for the actual length of the string, 675 in case the string itself contains NULLs that are part of the text data. 676 677 \returns A NULL terminated text string equivalent of the last keystroke. 678 */ event_text()679 static const char* event_text() {return e_text;} 680 /** 681 Returns the length of the text in Fl::event_text(). There 682 will always be a nul at this position in the text. However there may 683 be a nul before that if the keystroke translates to a nul character or 684 you paste a nul character. 685 */ event_length()686 static int event_length() {return e_length;} 687 688 static int compose(int &del); 689 static void compose_reset(); 690 static int event_inside(int,int,int,int); 691 static int event_inside(const Fl_Widget*); 692 static int test_shortcut(Fl_Shortcut); 693 694 // event destinations: 695 static int handle(int, Fl_Window*); 696 static int handle_(int, Fl_Window*); 697 /** Gets the widget that is below the mouse. 698 \see belowmouse(Fl_Widget*) */ belowmouse()699 static Fl_Widget* belowmouse() {return belowmouse_;} 700 static void belowmouse(Fl_Widget*); 701 /** Gets the widget that is being pushed. 702 \see void pushed(Fl_Widget*) */ pushed()703 static Fl_Widget* pushed() {return pushed_;} 704 static void pushed(Fl_Widget*); 705 /** Gets the current Fl::focus() widget. \sa Fl::focus(Fl_Widget*) */ focus()706 static Fl_Widget* focus() {return focus_;} 707 static void focus(Fl_Widget*); 708 static void add_handler(Fl_Event_Handler h); 709 static void remove_handler(Fl_Event_Handler h); 710 static void event_dispatch(Fl_Event_Dispatch d); 711 static Fl_Event_Dispatch event_dispatch(); 712 /** @} */ 713 714 /** \defgroup fl_clipboard Selection & Clipboard functions 715 FLTK global copy/cut/paste functions declared in <FL/Fl.H> 716 @{ */ 717 // cut/paste: 718 /** 719 Copies the data pointed to by \p stuff to the selection buffer 720 (\p destination is 0) or 721 the clipboard (\p destination is 1); \p len is the number of relevant 722 bytes in \p stuff. 723 The selection buffer is used for 724 middle-mouse pastes and for drag-and-drop selections. The 725 clipboard is used for traditional copy/cut/paste operations. 726 */ 727 static void copy(const char* stuff, int len, int destination = 0); // platform dependent 728 /** 729 Pastes the data from the selection buffer (\p source is 0) or the clipboard 730 (\p source is 1) into \p receiver. 731 Set things up so the receiver widget will be called with an FL_PASTE event some 732 time in the future with the data from the specified \p source in Fl::event_text() 733 and the number of characters in Fl::event_length(). 734 The receiver 735 should be prepared to be called \e directly by this, or for 736 it to happen \e later, or possibly <i>not at all</i>. This 737 allows the window system to take as long as necessary to retrieve 738 the paste buffer (or even to screw up completely) without complex 739 and error-prone synchronization code in FLTK. 740 741 The selection buffer is used for middle-mouse pastes and for 742 drag-and-drop selections. The clipboard is used for traditional 743 copy/cut/paste operations. 744 */ 745 static void paste(Fl_Widget &receiver, int source /*=0*/); // platform dependent 746 /** 747 Initiate a Drag And Drop operation. The selection buffer should be 748 filled with relevant data before calling this method. FLTK will 749 then initiate the system wide drag and drop handling. Dropped data 750 will be marked as <i>text</i>. 751 752 Create a selection first using: 753 Fl::copy(const char *stuff, int len, 0) 754 */ 755 static int dnd(); // platform dependent 756 757 // These are for back-compatibility only: 758 /** back-compatibility only: Gets the widget owning the current selection 759 \see Fl_Widget* selection_owner(Fl_Widget*) */ selection_owner()760 static Fl_Widget* selection_owner() {return selection_owner_;} 761 static void selection_owner(Fl_Widget*); 762 static void selection(Fl_Widget &owner, const char*, int len); 763 static void paste(Fl_Widget &receiver); 764 /** @} */ 765 /** \defgroup fl_screen Screen functions 766 fl global screen functions declared in <FL/Fl.H> 767 @{ */ 768 // screen size: 769 /** Returns the origin of the current screen work area, where 0 indicates the left side of the screen. */ 770 static int x(); // platform dependent 771 /** Returns the origin of the current screen work area, where 0 indicates the top edge of the screen. */ 772 static int y(); // platform dependent 773 /** Returns the width of the screen work area in pixels. */ 774 static int w(); // platform dependent 775 /** Returns the height of the screen work area in pixels. */ 776 static int h(); // platform dependent 777 778 // multi-head support: 779 static int screen_count(); 780 /** 781 Gets the bounding box of a screen that contains the mouse pointer. 782 \param[out] X,Y,W,H the corresponding screen bounding box 783 \see void screen_xywh(int &x, int &y, int &w, int &h, int mx, int my) 784 */ screen_xywh(int & X,int & Y,int & W,int & H)785 static void screen_xywh(int &X, int &Y, int &W, int &H) { 786 screen_xywh(X, Y, W, H, e_x_root, e_y_root); 787 } 788 static void screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my); 789 static void screen_xywh(int &X, int &Y, int &W, int &H, int n); 790 static void screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my, int mw, int mh); 791 static void screen_dpi(float &h, float &v, int n=0); 792 793 /** @} */ 794 795 /** \defgroup fl_attributes Color & Font functions 796 fl global color, font functions. 797 These functions are declared in <FL/Fl.H> or <FL/fl_draw.H>. 798 @{ */ 799 800 // color map: 801 static void set_color(Fl_Color, uchar, uchar, uchar); 802 /** 803 Sets an entry in the fl_color index table. You can set it to any 804 8-bit RGB color. The color is not allocated until fl_color(i) is used. 805 */ 806 static void set_color(Fl_Color i, unsigned c); // platform dependent 807 static unsigned get_color(Fl_Color i); 808 static void get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue); 809 /** 810 Frees the specified color from the colormap, if applicable. 811 If overlay is non-zero then the color is freed from the 812 overlay colormap. 813 */ 814 static void free_color(Fl_Color i, int overlay = 0); // platform dependent 815 816 // fonts: 817 static const char* get_font(Fl_Font); 818 /** 819 Get a human-readable string describing the family of this face. This 820 is useful if you are presenting a choice to the user. There is no 821 guarantee that each face has a different name. The return value points 822 to a static buffer that is overwritten each call. 823 824 The integer pointed to by \p attributes (if the pointer is not 825 zero) is set to zero, FL_BOLD or FL_ITALIC or 826 FL_BOLD | FL_ITALIC. To locate a "family" of fonts, search 827 forward and back for a set with non-zero attributes, these faces along 828 with the face with a zero attribute before them constitute a family. 829 */ 830 static const char* get_font_name(Fl_Font, int* attributes = 0); 831 /** 832 Return an array of sizes in \p sizep. The return value is the 833 length of this array. The sizes are sorted from smallest to largest 834 and indicate what sizes can be given to fl_font() that will 835 be matched exactly (fl_font() will pick the closest size for 836 other sizes). A zero in the first location of the array indicates a 837 scalable font, where any size works, although the array may list sizes 838 that work "better" than others. Warning: the returned array 839 points at a static buffer that is overwritten each call. Under X this 840 will open the display. 841 */ 842 static int get_font_sizes(Fl_Font, int*& sizep); 843 static void set_font(Fl_Font, const char*); 844 static void set_font(Fl_Font, Fl_Font); 845 /** 846 FLTK will open the display, and add every fonts on the server to the 847 face table. It will attempt to put "families" of faces together, so 848 that the normal one is first, followed by bold, italic, and bold 849 italic. 850 851 The optional argument is a string to describe the set of fonts to 852 add. Passing NULL will select only fonts that have the 853 ISO8859-1 character set (and are thus usable by normal text). Passing 854 "-*" will select all fonts with any encoding as long as they have 855 normal X font names with dashes in them. Passing "*" will list every 856 font that exists (on X this may produce some strange output). Other 857 values may be useful but are system dependent. With WIN32 NULL 858 selects fonts with ISO8859-1 encoding and non-NULL selects 859 all fonts. 860 861 The return value is how many faces are in the table after this is done. 862 */ 863 static Fl_Font set_fonts(const char* = 0); // platform dependent 864 865 /** @} */ 866 /** \defgroup fl_drawings Drawing functions 867 FLTK global graphics and GUI drawing functions. 868 These functions are declared in <FL/fl_draw.H>, 869 and in <FL/x.H> for offscreen buffer-related ones. 870 @{ */ 871 // <Hack to re-order the 'Drawing functions' group> 872 /** @} */ 873 874 // labeltypes: 875 static void set_labeltype(Fl_Labeltype,Fl_Label_Draw_F*,Fl_Label_Measure_F*); 876 /** Sets the functions to call to draw and measure a specific labeltype. */ 877 static void set_labeltype(Fl_Labeltype, Fl_Labeltype from); // is it defined ? 878 879 // boxtypes: 880 static Fl_Box_Draw_F *get_boxtype(Fl_Boxtype); 881 static void set_boxtype(Fl_Boxtype, Fl_Box_Draw_F*,uchar,uchar,uchar,uchar); 882 static void set_boxtype(Fl_Boxtype, Fl_Boxtype from); 883 static int box_dx(Fl_Boxtype); 884 static int box_dy(Fl_Boxtype); 885 static int box_dw(Fl_Boxtype); 886 static int box_dh(Fl_Boxtype); 887 static int draw_box_active(); 888 889 // back compatibility: 890 /** \addtogroup fl_windows 891 @{ */ 892 /** For back compatibility, sets the void Fl::fatal handler callback */ set_abort(Fl_Abort_Handler f)893 static void set_abort(Fl_Abort_Handler f) {fatal = f;} 894 static void (*atclose)(Fl_Window*,void*); 895 static void default_atclose(Fl_Window*,void*); 896 /** For back compatibility, sets the Fl::atclose handler callback. You 897 can now simply change the callback for the window instead. 898 \see Fl_Window::callback(Fl_Callback*) */ set_atclose(Fl_Atclose_Handler f)899 static void set_atclose(Fl_Atclose_Handler f) {atclose = f;} 900 /** @} */ 901 902 /** \addtogroup fl_events 903 @{ */ 904 /** Returns non-zero if the Shift key is pressed. */ event_shift()905 static int event_shift() {return e_state&FL_SHIFT;} 906 /** Returns non-zero if the Control key is pressed. */ event_ctrl()907 static int event_ctrl() {return e_state&FL_CTRL;} 908 /** Returns non-zero if the FL_COMMAND key is pressed, either FL_CTRL or on OSX FL_META. */ event_command()909 static int event_command() {return e_state&FL_COMMAND;} 910 /** Returns non-zero if the Alt key is pressed. */ event_alt()911 static int event_alt() {return e_state&FL_ALT;} 912 /** 913 Returns the mouse buttons state bits; if non-zero, then at least one 914 button is pressed now. This function returns the button state at the 915 time of the event. During an FL_RELEASE event, the state 916 of the released button will be 0. To find out, which button 917 caused an FL_RELEASE event, you can use Fl::event_button() instead. 918 \return a bit mask value like { [FL_BUTTON1] | [FL_BUTTON2] | [FL_BUTTON3] } 919 */ event_buttons()920 static int event_buttons() {return e_state&0x7f000000;} 921 /** 922 Returns non-zero if mouse button 1 is currently held down. 923 For more details, see Fl::event_buttons(). 924 */ event_button1()925 static int event_button1() {return e_state&FL_BUTTON1;} 926 /** 927 Returns non-zero if button 2 is currently held down. 928 For more details, see Fl::event_buttons(). 929 */ event_button2()930 static int event_button2() {return e_state&FL_BUTTON2;} 931 /** 932 Returns non-zero if button 3 is currently held down. 933 For more details, see Fl::event_buttons(). 934 */ event_button3()935 static int event_button3() {return e_state&FL_BUTTON3;} 936 /** @} */ 937 938 /** 939 Sets an idle callback. 940 941 \deprecated This method is obsolete - use the add_idle() method instead. 942 */ set_idle(Fl_Old_Idle_Handler cb)943 static void set_idle(Fl_Old_Idle_Handler cb) {idle = cb;} 944 /** See grab(Fl_Window*) */ grab(Fl_Window & win)945 static void grab(Fl_Window& win) {grab(&win);} 946 /** Releases the current grabbed window, equals grab(0). 947 \deprecated Use Fl::grab(0) instead. 948 \see grab(Fl_Window*) */ release()949 static void release() {grab(0);} 950 951 // Visible focus methods... 952 /** 953 Gets or sets the visible keyboard focus on buttons and other 954 non-text widgets. The default mode is to enable keyboard focus 955 for all widgets. 956 */ visible_focus(int v)957 static void visible_focus(int v) { option(OPTION_VISIBLE_FOCUS, (v!=0)); } 958 /** 959 Gets or sets the visible keyboard focus on buttons and other 960 non-text widgets. The default mode is to enable keyboard focus 961 for all widgets. 962 */ visible_focus()963 static int visible_focus() { return option(OPTION_VISIBLE_FOCUS); } 964 965 // Drag-n-drop text operation methods... 966 /** 967 Gets or sets whether drag and drop text operations are supported. 968 This specifically affects whether selected text can 969 be dragged from text fields or dragged within a text field as a 970 cut/paste shortcut. 971 */ dnd_text_ops(int v)972 static void dnd_text_ops(int v) { option(OPTION_DND_TEXT, (v!=0)); } 973 /** 974 Gets or sets whether drag and drop text operations are 975 supported. This specifically affects whether selected text can 976 be dragged from text fields or dragged within a text field as a 977 cut/paste shortcut. 978 */ dnd_text_ops()979 static int dnd_text_ops() { return option(OPTION_DND_TEXT); } 980 /** \defgroup fl_multithread Multithreading support functions 981 fl multithreading support functions declared in <FL/Fl.H> 982 @{ */ 983 984 // Multithreading support: 985 static int lock(); 986 static void unlock(); 987 static void awake(void* message = 0); 988 /** See void awake(void* message=0). */ 989 static int awake(Fl_Awake_Handler cb, void* message = 0); 990 /** 991 The thread_message() method returns the last message 992 that was sent from a child by the awake() method. 993 994 See also: \ref advanced_multithreading 995 */ 996 static void* thread_message(); // platform dependent 997 /** @} */ 998 999 /** \defgroup fl_del_widget Safe widget deletion support functions 1000 1001 These functions, declared in <FL/Fl.H>, support deletion of widgets inside callbacks. 1002 1003 Fl::delete_widget() should be called when deleting widgets 1004 or complete widget trees (Fl_Group, Fl_Window, ...) inside 1005 callbacks. 1006 1007 The other functions are intended for internal use. The preferred 1008 way to use them is by using the helper class Fl_Widget_Tracker. 1009 1010 The following is to show how it works ... 1011 1012 There are three groups of related methods: 1013 1014 -# scheduled widget deletion 1015 - Fl::delete_widget() schedules widgets for deletion 1016 - Fl::do_widget_deletion() deletes all scheduled widgets 1017 -# widget watch list ("smart pointers") 1018 - Fl::watch_widget_pointer() adds a widget pointer to the watch list 1019 - Fl::release_widget_pointer() removes a widget pointer from the watch list 1020 - Fl::clear_widget_pointer() clears a widget pointer \e in the watch list 1021 -# the class Fl_Widget_Tracker: 1022 - the constructor calls Fl::watch_widget_pointer() 1023 - the destructor calls Fl::release_widget_pointer() 1024 - the access methods can be used to test, if a widget has been deleted 1025 \see Fl_Widget_Tracker. 1026 1027 @{ */ 1028 // Widget deletion: 1029 static void delete_widget(Fl_Widget *w); 1030 static void do_widget_deletion(); 1031 static void watch_widget_pointer(Fl_Widget *&w); 1032 static void release_widget_pointer(Fl_Widget *&w); 1033 static void clear_widget_pointer(Fl_Widget const *w); 1034 /** @} */ 1035 1036 #ifdef FLTK_HAVE_CAIRO 1037 /** \defgroup group_cairo Cairo support functions and classes 1038 @{ 1039 */ 1040 public: 1041 // Cairo support API 1042 static cairo_t * cairo_make_current(Fl_Window* w); 1043 /** when FLTK_HAVE_CAIRO is defined and cairo_autolink_context() is true, 1044 any current window dc is linked to a current context. 1045 This is not the default, because it may not be necessary 1046 to add cairo support to all fltk supported windows. 1047 When you wish to associate a cairo context in this mode, 1048 you need to call explicitly in your draw() overridden method, 1049 FL::cairo_make_current(Fl_Window*). This will create a cairo context 1050 but only for this Window. 1051 Still in custom cairo application it is possible to handle 1052 completely this process automatically by setting \p alink to true. 1053 In this last case, you don't need anymore to call Fl::cairo_make_current(). 1054 You can use Fl::cairo_cc() to get the current cairo context anytime. 1055 \note Only available when configure has the --enable-cairo option 1056 */ cairo_autolink_context(bool alink)1057 static void cairo_autolink_context(bool alink) {cairo_state_.autolink(alink);} 1058 /** 1059 Gets the current autolink mode for cairo support. 1060 \retval false if no cairo context autolink is made for each window. 1061 \retval true if any fltk window is attached a cairo context when it 1062 is current. \see void cairo_autolink_context(bool alink) 1063 \note Only available when configure has the --enable-cairo option 1064 */ cairo_autolink_context()1065 static bool cairo_autolink_context() {return cairo_state_.autolink();} 1066 /** Gets the current cairo context linked with a fltk window. */ cairo_cc()1067 static cairo_t * cairo_cc() { return cairo_state_.cc(); } 1068 /** Sets the current cairo context to \p c. 1069 Set \p own to true if you want fltk to handle this cc deletion. 1070 \note Only available when configure has the --enable-cairo option 1071 */ 1072 static void cairo_cc(cairo_t * c, bool own=false){ cairo_state_.cc(c, own); } 1073 1074 private: 1075 static cairo_t * cairo_make_current(void* gc); 1076 static cairo_t * cairo_make_current(void* gc, int W, int H); 1077 static Fl_Cairo_State cairo_state_; 1078 public: 1079 /** @} */ 1080 1081 #endif // FLTK_HAVE_CAIRO 1082 1083 }; 1084 1085 /** 1086 This class should be used to control safe widget deletion. 1087 1088 You can use an Fl_Widget_Tracker object to watch another widget, if you 1089 need to know, if this widget has been deleted during a callback. 1090 1091 This simplifies the use of the "safe widget deletion" methods 1092 Fl::watch_widget_pointer() and Fl::release_widget_pointer() and 1093 makes their use more reliable, because the destructor autmatically 1094 releases the widget pointer from the widget watch list. 1095 1096 It is intended to be used as an automatic (local/stack) variable, 1097 such that the automatic destructor is called when the object's 1098 scope is left. This ensures that no stale widget pointers are 1099 left in the widget watch list (see example below). 1100 1101 You can also create Fl_Widget_Tracker objects with \c new, but then it 1102 is your responsibility to delete the object (and thus remove the 1103 widget pointer from the watch list) when it is not needed any more. 1104 1105 Example: 1106 1107 \code 1108 int MyClass::handle (int event) { 1109 1110 if (...) { 1111 Fl_Widget_Tracker wp(this); // watch myself 1112 do_callback(); // call the callback 1113 1114 if (wp.deleted()) return 1; // exit, if deleted 1115 1116 // Now we are sure that the widget has not been deleted. 1117 // It is safe to access the widget 1118 1119 clear_changed(); // access the widget 1120 } 1121 } 1122 \endcode 1123 1124 */ 1125 class FL_EXPORT Fl_Widget_Tracker { 1126 1127 Fl_Widget* wp_; 1128 1129 public: 1130 1131 Fl_Widget_Tracker(Fl_Widget *wi); 1132 ~Fl_Widget_Tracker(); 1133 1134 /** 1135 Returns a pointer to the watched widget. 1136 1137 This pointer is \c NULL, if the widget has been deleted. 1138 */ widget()1139 Fl_Widget *widget() {return wp_;} 1140 1141 /** 1142 Returns 1, if the watched widget has been deleted. 1143 1144 This is a convenience method. You can also use something like 1145 1146 <tt> if (wp.widget() == 0) // ...</tt> 1147 1148 where \p wp is an Fl_Widget_Tracker object. 1149 */ deleted()1150 int deleted() {return wp_ == 0;} 1151 1152 /** 1153 Returns 1, if the watched widget exists (has not been deleted). 1154 1155 This is a convenience method. You can also use something like 1156 1157 <tt> if (wp.widget() != 0) // ...</tt> 1158 1159 where \p wp is an Fl_Widget_Tracker object. 1160 */ exists()1161 int exists() {return wp_ != 0;} 1162 1163 }; 1164 1165 /** \defgroup fl_unicode Unicode and UTF-8 functions 1166 fl global Unicode and UTF-8 handling functions declared in <FL/fl_utf8.h> 1167 @{ */ 1168 /** @} */ 1169 1170 #endif // !Fl_H 1171 1172 // 1173 // End of "$Id: Fl.H 8724 2011-05-23 18:01:29Z manolo $". 1174 // 1175