diff options
Diffstat (limited to 'FL')
| -rw-r--r-- | FL/Fl.H | 449 | ||||
| -rw-r--r-- | FL/Fl_Double_Window.H | 22 | ||||
| -rw-r--r-- | FL/Fl_Gl_Window.H | 109 | ||||
| -rw-r--r-- | FL/Fl_Group.H | 68 | ||||
| -rw-r--r-- | FL/Fl_Overlay_Window.H | 22 | ||||
| -rw-r--r-- | FL/Fl_Single_Window.H | 15 | ||||
| -rw-r--r-- | FL/Fl_Window.H | 257 |
7 files changed, 916 insertions, 26 deletions
@@ -49,6 +49,10 @@ typedef void (Fl_Box_Draw_F)(int,int,int,int, Fl_Color); typedef void (*Fl_Timeout_Handler)(void*); typedef void (*Fl_Awake_Handler)(void*); +/** + The Fl is the FLTK global (static) containing + state information and global methods for the current application. +*/ class FL_EXPORT Fl { Fl() {}; // no constructor! @@ -77,6 +81,9 @@ public: // should be private! static int compose_state; static int visible_focus_; static int dnd_text_ops_; + /** + If true then flush() will do something. + */ static void damage(int d) {damage_ = d;} static void (*idle)(); @@ -102,8 +109,8 @@ public: // argument parsers: static int arg(int, char**, int&); static int args(int, char**, int&, int (*)(int,char**,int&) = 0); - static const char* const help; static void args(int, char**); + static const char* const help; // things called by initialization: static void display(const char*); @@ -117,8 +124,14 @@ public: // schemes: static int scheme(const char*); + /** See void scheme(const char *name) */ static const char* scheme() {return scheme_;} - static int reload_scheme(); + /** + Called by scheme according to scheme name. + Loads or reloads the current scheme selection. + See void scheme(const char *name) + */ + static int reload_scheme(); // platform dependent static int scrollbar_size(); static void scrollbar_size(int W); @@ -136,49 +149,300 @@ public: static void add_check(Fl_Timeout_Handler, void* = 0); static int has_check(Fl_Timeout_Handler, void* = 0); static void remove_check(Fl_Timeout_Handler, void* = 0); - static void add_fd(int fd, int when, void (*cb)(int,void*),void* =0); - static void add_fd(int fd, void (*cb)(int, void*), void* = 0); - static void remove_fd(int, int when); - static void 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.</P> + + <P>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. + + <P>There can only be one callback of each type for a file descriptor. + Fl::remove_fd() gets rid of <I>all</I> the callbacks for a given + file descriptor. + + <P>Under UNIX <I>any</I> file descriptor can be monitored (files, + devices, pipes, sockets, etc.) Due to limitations in Microsoft Windows, + WIN32 applications can only monitor sockets. + */ + static void add_fd(int fd, int when, void (*cb)(int,void*),void* =0); // platform dependent + /** See void add_fd(int fd, int when, void (*cb)(int,void*),void* =0) */ + static void add_fd(int fd, void (*cb)(int, void*), void* = 0); // platform dependent + /** Removes a file descriptor handler. */ + static void remove_fd(int, int when); // platform dependent + /** Removes a file descriptor handler. */ + static void remove_fd(int); // platform dependent + static void add_idle(void (*cb)(void*), void* = 0); static int has_idle(void (*cb)(void*), void* = 0); static void remove_idle(void (*cb)(void*), void* = 0); + /** If true then flush() will do something. */ static int damage() {return damage_;} static void redraw(); static void flush(); + /** \fn 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. + <P>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. + */ static void (*warning)(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. + <P>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. + */ static void (*error)(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. + <P>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. + */ static void (*fatal)(const char*, ...); static Fl_Window* first_window(); static void first_window(Fl_Window*); static Fl_Window* next_window(const Fl_Window*); + /** + 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 Fl_Window* modal() {return modal_;} + /** + This is used when pop-up menu systems are active. Send all events to + the passed window no matter where the pointer or focus is (including + in other programs). The window <I>does not have to be + shown()</I> , 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 + <I>some</I> window must be mapped because the system interface needs a + window id). + + <P>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. + + <P>To turn off grabbing do Fl::grab(0). + + <P><I>Be careful that your program does not enter an infinite loop + while grab() is on. On X this will lock up your screen!</I> + To avoid this potential lockup, all newer operating systems seem to + limit mouse pointer grabbing to the time during which a mouse button + is held down. Some OS's may not support grabbing at all. + */ static Fl_Window* grab() {return grab_;} - static void grab(Fl_Window*); + /** Selects the window to grab. See Fl_Window* Fl::grab() */ + static void grab(Fl_Window*); // platform dependent // event information: + /** + Returns the last event that was processed. This can be used + to determine if a callback is being done in response to a + keypress, mouse click, etc. + */ static int event() {return e_number;} + /** + Returns the mouse position of the event relative to the Fl_Window + it was passed to. + */ static int event_x() {return e_x;} + /** + Returns the mouse position of the event relative to the Fl_Window + it was passed to. + */ static int event_y() {return e_y;} + /** + 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 int event_x_root() {return e_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(). + */ static int event_y_root() {return e_y_root;} + /** + Returns the current horizontal mouse scrolling associated with the + FL_MOUSEWHEEL event. Right is positive. + */ static int event_dx() {return e_dx;} + /** + Returns the current vertical mouse scrolling assoaciated with the + FL_MOUSEWHEEL event. Down is positive. + */ static int event_dy() {return e_dy;} - static void get_mouse(int &,int &); + /** + 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 get_mouse(int &,int &); // platform dependent + /** + 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. + + <P>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. + */ static int event_clicks() {return e_clicks;} + /** + See int event_clicks() + */ static void event_clicks(int i) {e_clicks = i;} + /** + 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 <I>next</I> + click from being counted as a double-click or to make a popup menu + pick an item with a single click. Don't pass non-zero to this. + */ static int event_is_click() {return e_is_click;} - static void event_is_click(int i) {e_is_click = i;} // only 0 works! + /** + Only i=0 works! See int event_is_click(). + */ + static void event_is_click(int i) {e_is_click = i;} + /** + Returns which mouse button caused te current event. This returns garbage if the + most recent event was not a FL_PUSH or FL_RELEASE event. + */ static int event_button() {return e_keysym-FL_Button;} + /** + This is a bitfield of what shift states were on and what mouse buttons + were held down during the most recent event. The second version + returns non-zero if any of the passed bits are turned on. The legal + bits are: + + <UL> + <LI>FL_SHIFT</LI> + <LI>FL_CAPS_LOCK</LI> + <LI>FL_CTRL</LI> + <LI>FL_ALT</LI> + <LI>FL_NUM_LOCK</LI> + <LI>FL_META</LI> + <LI>FL_SCROLL_LOCK</LI> + <LI>FL_BUTTON1</LI> + <LI>FL_BUTTON2</LI> + <LI>FL_BUTTON3</LI> + </UL> + + <P>X servers do not agree on shift states, and FL_NUM_LOCK, FL_META, and + FL_SCROLL_LOCK may not work. The values were selected to match the + XFree86 server on Linux. In addition there is a bug in the way X works + so that the shift state is not correctly reported until the first event <I> + after</I> the shift key is pressed or released. + */ static int event_state() {return e_state;} + /** See int event_state() */ static int event_state(int i) {return e_state&i;} + /** + 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. + + <P>Fl::event_key(int) returns true if the given key was held + down (or pressed) <I>during</I> the last event. This is constant until + the next event is read from the server. + + <P>Fl::get_key(int) returns true if the given key is held down <I> + now</I>. Under X this requires a round-trip to the server and is <I> + much</I> slower than Fl::event_key(int). + + <P>Keys are identified by the <I>unshifted</I> values. FLTK defines a + set of symbols that should work on most modern machines for every key + on the keyboard: + + <UL> + <LI>All keys on the main keyboard producing a printable ASCII + character use the value of that ASCII character (as though shift, + ctrl, and caps lock were not on). The space bar is 32. </LI> + <LI>All keys on the numeric keypad producing a printable ASCII + character use the value of that ASCII character plus FL_KP. + The highest possible value is FL_KP_Last so you can + range-check to see if something is on the keypad. </LI> + <LI>All numbered function keys use the number on the function key plus + FL_F. The highest possible number is FL_F_Last, so you + can range-check a value. </LI> + <LI>Buttons on the mouse are considered keys, and use the button + number (where the left button is 1) plus FL_Button. </LI> + <LI>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() + . </LI> + </UL> + + <P>On X Fl::get_key(FL_Button+n) does not work. + + <P>On WIN32 Fl::get_key(FL_KP_Enter) and + Fl::event_key(FL_KP_Enter) do not work. + */ static int event_key() {return e_keysym;} + /** + If NumLock is deactivated, FLTK translates events from the + numeric keypad into the corresponding arrow key events. + event_key() returns the translated key code, whereas + event_original_key() returns the keycode before + NumLock translation. + */ static int event_original_key(){return e_original_keysym;} + /** See int event_key() */ static int event_key(int); - static int get_key(int); + /** + Returns true if the given key is held down <I>now</I>. + Under X this requires a round-trip to the server and is <I> + much</I> slower than Fl::event_key(int). See event_key(). + */ + static int get_key(int); // platform dependent + /** Returns the text associated with the current FL_PASTE or FL_DND_RELEASE event. */ static const char* event_text() {return e_text;} + /** + 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. + */ static int event_length() {return e_length;} static int compose(int &del); + /** + If the user moves the cursor, be sure to call Fl::compose_reset(). + The next call to Fl::compose() will start out in an initial state. In + particular it will not set "del" to non-zero. This call is very fast + so it is ok to call it many times and in many places. + */ static void compose_reset() {compose_state = 0;} static int event_inside(int,int,int,int); static int event_inside(const Fl_Widget*); @@ -186,33 +450,61 @@ public: // event destinations: static int handle(int, Fl_Window*); + /** See Fl_Widget* belowmouse(Fl_Widget*) */ static Fl_Widget* belowmouse() {return belowmouse_;} static void belowmouse(Fl_Widget*); + /** See Fl_Widget* pushed(Fl_Widget*) */ static Fl_Widget* pushed() {return pushed_;} static void pushed(Fl_Widget*); + /** See Fl_Widget* focus(Fl_Widget*) */ static Fl_Widget* focus() {return focus_;} static void focus(Fl_Widget*); static void add_handler(int (*h)(int)); static void remove_handler(int (*h)(int)); // cut/paste: - static void copy(const char* stuff, int len, int clipboard = 0); - static void paste(Fl_Widget &receiver, int clipboard /*=0*/); - static int dnd(); + /** + Copies the data pointed to by stuff to the selection + (0) or primary (1) clipboard. The selection clipboard is used + for middle-mouse pastes and for drag-and-drop selections. The + primary clipboard is used for traditional copy/cut/paste + operations. + */ + static void copy(const char* stuff, int len, int clipboard = 0); // platform dependent + /** + Pastes the data from the selection (0) or primary (1) clipboard into receiver. + The selection clipboard is used for middle-mouse pastes and for + drag-and-drop selections. The primary clipboard is used for + traditional copy/cut/paste operations. + */ + static void paste(Fl_Widget &receiver, int clipboard /*=0*/); // platform dependent + /** + Initiate a Drag And Drop operation. The clipboard should be + filled with relevant data before calling this method. FLTK will + then initiate the system wide drag and drop handling. Dropped data + will be marked as <i>text</i>. + */ + static int dnd(); // platform dependent // These are for back-compatability only: + /** See Fl_Widget* selection_owner(Fl_Widget*) */ static Fl_Widget* selection_owner() {return selection_owner_;} static void selection_owner(Fl_Widget*); static void selection(Fl_Widget &owner, const char*, int len); static void paste(Fl_Widget &receiver); // screen size: - static int x(); - static int y(); - static int w(); - static int h(); + /** Returns the origin of the current screen, where 0 indicates the left side of the screen. */ + static int x(); // platform dependent + /** Returns the origin of the current screen, where 0 indicates the top edge of the screen. */ + static int y(); // platform dependent + /** Returns the width of the screen in pixels. */ + static int w(); // platform dependent + /** Returns the height of the screen in pixels. */ + static int h(); // platform dependent // multi-head support: static int screen_count(); + /** See void screen_xywh(int &x, int &y, int &w, int &h, int mx, int my) */ static void screen_xywh(int &X, int &Y, int &W, int &H) { screen_xywh(X, Y, W, H, e_x_root, e_y_root); } @@ -221,22 +513,75 @@ public: // color map: static void set_color(Fl_Color, uchar, uchar, uchar); - static 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. + */ + static void set_color(Fl_Color, unsigned); // platorm dependent static unsigned get_color(Fl_Color); static void get_color(Fl_Color, uchar&, uchar&, uchar&); - static void 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 void free_color(Fl_Color, int overlay = 0); // platform dependent // fonts: static const char* get_font(Fl_Font); + /** + Get a human-readable string describing the family of this face. This + is useful if you are presenting a choice to the user. There is no + guarantee that each face has a different name. The return value points + to a static buffer that is overwritten each call. + + <P>The integer pointed to by 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. + */ static const char* get_font_name(Fl_Font, int* attributes = 0); + /** + 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 int get_font_sizes(Fl_Font, int*& sizep); static void set_font(Fl_Font, const char*); static void set_font(Fl_Font, Fl_Font); - static Fl_Font set_fonts(const char* = 0); + /** + FLTK will open the display, and add every fonts on the server to the + face table. It will attempt to put "families" of faces together, so + that the normal one is first, followed by bold, italic, and bold + italic. + + <P>The optional argument is a string to describe the set of fonts to + add. Passing 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. + + <P>The return value is how many faces are in the table after this is + done. + */ + static Fl_Font set_fonts(const char* = 0); // platform dependent // labeltypes: static void set_labeltype(Fl_Labeltype,Fl_Label_Draw_F*,Fl_Label_Measure_F*); - static void set_labeltype(Fl_Labeltype, Fl_Labeltype from); + /** Sets the functions to call to draw and measure a specific labeltype. */ + static void set_labeltype(Fl_Labeltype, Fl_Labeltype from); // is it defined ? // boxtypes: static Fl_Box_Draw_F *get_boxtype(Fl_Boxtype); @@ -249,35 +594,95 @@ public: static int draw_box_active(); // back compatability: + /** for back compatibility. sets the (*fatal)() callback. */ static void set_abort(void (*f)(const char*,...)) {fatal = f;} static void (*atclose)(Fl_Window*,void*); static void default_atclose(Fl_Window*,void*); + /** for back compatibility. sets the (*atclose)() callback. */ static void set_atclose(void (*f)(Fl_Window*,void*)) {atclose = f;} + /** Returns non-zero if the Shift key is pressed. */ static int event_shift() {return e_state&FL_SHIFT;} + /** Returns non-zero if the Control key is pressed. */ static int event_ctrl() {return e_state&FL_CTRL;} + /** Returns non-zero if the Alt key is pressed. */ static int event_alt() {return e_state&FL_ALT;} + /** + Returns the button state bits; if non-zero, then at least one + button is pressed. This function returns the button state at the + time of the event. During an FL_RELEASE event, the state + of the released button will be 0. To find out, which button + caused an FL_RELEASE event, you can use + Fl::event_button() instead. + */ static int event_buttons() {return e_state&0x7f000000;} + /** + Returns non-zero if button 1 is currently held down. + For more details, see Fl::event_buttons(). + */ static int event_button1() {return e_state&FL_BUTTON1;} + /** + Returns non-zero if button 2 is currently held down. + For more details, see Fl::event_buttons(). + */ static int event_button2() {return e_state&FL_BUTTON2;} + /** + Returns non-zero if button 3 is currently held down. + For more details, see Fl::event_buttons(). + */ static int event_button3() {return e_state&FL_BUTTON3;} + /** + Sets an idle callback. + <P>This method is obsolete - use the add_idle() method instead. + */ static void set_idle(void (*cb)()) {idle = cb;} + /** See Fl_Window* grab() */ static void grab(Fl_Window&win) {grab(&win);} + /** Releases the current grabbed window, equals grab(0). See Fl_Window* grab() */ static void release() {grab(0);} // Visible focus methods... + /** + 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. + */ static void visible_focus(int v) { visible_focus_ = v; } + /** + 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. + */ static int visible_focus() { return visible_focus_; } // Drag-n-drop text operation methods... + /** + Gets or sets whether drag and drop text operations are + supported. This specifically affects whether selected text can + be dragged from text fields or dragged within a text field as a + cut/paste shortcut. + */ static void dnd_text_ops(int v) { dnd_text_ops_ = v; } + /** + Gets or sets whether drag and drop text operations are + supported. This specifically affects whether selected text can + be dragged from text fields or dragged within a text field as a + cut/paste shortcut. + */ static int dnd_text_ops() { return dnd_text_ops_; } // Multithreading support: static void lock(); static void unlock(); static void awake(void* message = 0); + /** See void awake(void* message=0). */ static int awake(Fl_Awake_Handler cb, void* message = 0); - static void* thread_message(); + /** + The thread_message() method returns the last message + that was sent from a child by the awake() method. + + <P>See also: multithreading + */ + static void* thread_message(); // platform dependent // Widget deletion: static void delete_widget(Fl_Widget *w); diff --git a/FL/Fl_Double_Window.H b/FL/Fl_Double_Window.H index bbb68a1e6..5aac830f4 100644 --- a/FL/Fl_Double_Window.H +++ b/FL/Fl_Double_Window.H @@ -30,6 +30,21 @@ #include "Fl_Window.H" +/** + The Fl_Double_Window provides a double-buffered window. + If possible this will use the X double buffering extension (Xdbe). If + not, it will draw the window data into an off-screen pixmap, and then + copy it to the on-screen window. + <P>It is highly recommended that you put the following code before the + first show() of <I>any</I> window in your program: </P> + <UL> + <PRE> + Fl::visual(FL_DOUBLE|FL_INDEX) + </PRE> + </UL> + This makes sure you can use Xdbe on servers where double buffering + does not exist for every visual. +*/ class FL_EXPORT Fl_Double_Window : public Fl_Window { protected: void flush(int eraseoverlay); @@ -41,8 +56,15 @@ public: void resize(int,int,int,int); void hide(); ~Fl_Double_Window(); + /** + Creates a new Fl_Double_Window widget using the given + position, size, and label (title) string. + */ Fl_Double_Window(int W, int H, const char *l = 0) : Fl_Window(W,H,l), force_doublebuffering_(0) { type(FL_DOUBLE_WINDOW); } + /** + See Fl_Double_Window::Fl_Double_Window(int w, int h, const char *label = 0) + */ Fl_Double_Window(int X, int Y, int W, int H, const char *l = 0) : Fl_Window(X,Y,W,H,l), force_doublebuffering_(0) { type(FL_DOUBLE_WINDOW); } }; diff --git a/FL/Fl_Gl_Window.H b/FL/Fl_Gl_Window.H index d13b832ca..cbe793baf 100644 --- a/FL/Fl_Gl_Window.H +++ b/FL/Fl_Gl_Window.H @@ -35,6 +35,24 @@ typedef void* GLContext; // actually a GLXContext or HGLDC class Fl_Gl_Choice; // structure to hold result of glXChooseVisual +/** + The Fl_Gl_Window widget sets things up so OpenGL works, and + also keeps an OpenGL "context" for that window, so that changes to the + lighting and projection may be reused between redraws. Fl_Gl_Window + also flushes the OpenGL streams and swaps buffers after draw() + returns. + <P>OpenGL hardware typically provides some overlay bit planes, which + are very useful for drawing UI controls atop your 3D graphics. If the + overlay hardware is not provided, FLTK tries to simulate the overlay, + This works pretty well if your graphics are double buffered, but not + very well for single-buffered. </P> + <P>Please note that the FLTK drawing and clipping functions + will not work inside an Fl_Gl_Window. All drawing + should be done using OpenGL calls exclusively. + Even though Fl_Gl_Window is derived from Fl_Group, + it is not useful to add other FLTK Widgets as children, + unless those Widgets are modified to draw using OpenGL calls. +*/ class FL_EXPORT Fl_Gl_Window : public Fl_Window { int mode_; @@ -61,16 +79,84 @@ public: void hide(); void resize(int,int,int,int); + /** + Is turned off when FLTK creates a new + context for this window or when the window resizes, and is turned on <I> + after</I> draw() is called. You can use this inside your + draw() method to avoid unneccessarily initializing the OpenGL + context. Just do this: + <UL><PRE> + void mywindow::draw() { + if (!valid()) { + glViewport(0,0,w(),h()); + glFrustum(...); + ...other initialization... + } + if (!context_valid()) { + ...load textures, etc. ... + } + ... draw your geometry here ... + } + </PRE></UL> + + You can turn valid() on by calling valid(1). You + should only do this after fixing the transformation inside a draw() + or after make_current(). This is done automatically after + draw() returns. + */ char valid() const {return valid_f_ & 1;} + /** + See char Fl_Gl_Window::valid() const + */ void valid(char v) {if (v) valid_f_ |= 1; else valid_f_ &= 0xfe;} void invalidate(); + /** + Will only be set if the + OpenGL context is created or recreated. It differs from + Fl_Gl_Window::valid() which is also set whenever the context + changes size. + */ char context_valid() const {return valid_f_ & 2;} + /** + See char Fl_Gl_Window::context_valid() const + */ void context_valid(char v) {if (v) valid_f_ |= 2; else valid_f_ &= 0xfd;} static int can_do(int m) {return can_do(m,0);} static int can_do(const int *m) {return can_do(0, m);} + /** + See static int Fl_Gl_Window::can_do(int) + */ int can_do() {return can_do(mode_,alist);} + /** + Set or change the OpenGL capabilites of the window. The value can be + any of the following OR'd together: + <UL> + <LI>FL_RGB - RGB color (not indexed) </LI> + <LI>FL_RGB8 - RGB color with at least 8 bits of each color </LI> + <LI>FL_INDEX - Indexed mode </LI> + <LI>FL_SINGLE - not double buffered </LI> + <LI>FL_DOUBLE - double buffered </LI> + <LI>FL_ACCUM - accumulation buffer </LI> + <LI>FL_ALPHA - alpha channel in color </LI> + <LI>FL_DEPTH - depth buffer </LI> + <LI>FL_STENCIL - stencil buffer </LI> + <LI>FL_MULTISAMPLE - multisample antialiasing </LI> + </UL> + FL_RGB and FL_SINGLE have a value of zero, so they + are "on" unless you give FL_INDEX or FL_DOUBLE. + <P>If the desired combination cannot be done, FLTK will try turning off + FL_MULTISAMPLE. If this also fails the show() will call + Fl::error() and not show the window. </P> + <P>You can change the mode while the window is displayed. This is most + useful for turning double-buffering on and off. Under X this will + cause the old X window to be destroyed and a new one to be created. If + this is a top-level window this will unfortunately also cause the + window to blink, raise to the top, and be de-iconized, and the xid() + will change, possibly breaking other code. It is best to make the GL + window a child of another window if you wish to do this! + */ Fl_Mode mode() const {return (Fl_Mode)mode_;} int mode(int a) {return mode(a,0);} int mode(const int *a) {return mode(0, a);} @@ -81,12 +167,35 @@ public: void swap_buffers(); void ortho(); + /** + Returns true if the hardware overlay is possible. If this is false, + FLTK will try to simulate the overlay, with significant loss of update + speed. Calling this will cause FLTK to open the display. + */ int can_do_overlay(); + /** + This method causes draw_overlay to be called at a later time. + Initially the overlay is clear, if you want the window to display + something in the overlay when it first appears, you must call this + immediately after you show() your window. + */ void redraw_overlay(); void hide_overlay(); + /** + The make_overlay_current() method selects the OpenGL context + for the widget's overlay. It is called automatically prior to the + draw_overlay() method being called and can also be used to + implement feedback and/or selection within the handle() + method. + */ void make_overlay_current(); ~Fl_Gl_Window(); + /** + Creates a new Fl_Gl_Window widget using the given position, + size, and label string. The default boxtype is FL_NO_BOX. The + default mode is FL_RGB|FL_DOUBLE|FL_DEPTH. + */ Fl_Gl_Window(int W, int H, const char *l=0) : Fl_Window(W,H,l) {init();} Fl_Gl_Window(int X, int Y, int W, int H, const char *l=0) : Fl_Window(X,Y,W,H,l) {init();} diff --git a/FL/Fl_Group.H b/FL/Fl_Group.H index c140b3c5c..8e8626dce 100644 --- a/FL/Fl_Group.H +++ b/FL/Fl_Group.H @@ -32,6 +32,14 @@ #include "Fl_Widget.H" #endif +/** + The Fl_Group class is the FLTK container widget. It maintains + an array of child widgets. These children can themselves be any widget + including Fl_Group. The most important subclass of Fl_Group + is Fl_Window, however + groups can also be used to control radio buttons or to enforce resize + behavior. +*/ class FL_EXPORT Fl_Group : public Fl_Widget { Fl_Widget** array_; @@ -50,7 +58,18 @@ class FL_EXPORT Fl_Group : public Fl_Widget { protected: enum { CLIP_CHILDREN = 2048 }; + /** + The first method controls whether the group widget clips the drawing of + child widgets to its bounding box. + + <p>The second method returns the current clipping mode. + + <p>The default is to not clip (0) the drawing of child widgets. + */ void clip_children(int c) { if (c) set_flag(CLIP_CHILDREN); else clear_flag(CLIP_CHILDREN); } + /** + See void Fl_Group::clip_children(int c) + */ int clip_children() { return (flags() & CLIP_CHILDREN) != 0; } void draw(); @@ -68,26 +87,75 @@ public: static Fl_Group *current(); static void current(Fl_Group *g); + /** + Returns how many child widgets the group has. + */ int children() const {return children_;} + /** + Returns array()[n]. <i>No range checking is done!</i> + */ Fl_Widget* child(int n) const {return array()[n];} int find(const Fl_Widget*) const; + /** + See int Fl_Group::find(const Fl_Widget *w) const + */ int find(const Fl_Widget& o) const {return find(&o);} Fl_Widget* const* array() const; void resize(int,int,int,int); + /** + Creates a new Fl_Group widget using the given position, size, + and label string. The default boxtype is FL_NO_BOX. + */ Fl_Group(int,int,int,int, const char * = 0); virtual ~Fl_Group(); void add(Fl_Widget&); + /** + See void Fl_Group::add(Fl_Widget &w) + */ void add(Fl_Widget* o) {add(*o);} void insert(Fl_Widget&, int i); + /** + This does insert(w, find(beforethis)). This will append the + widget if beforethis is not in the group. + */ void insert(Fl_Widget& o, Fl_Widget* before) {insert(o,find(before));} void remove(Fl_Widget&); void remove(Fl_Widget* o) {remove(*o);} void clear(); + /** + See void Fl_Group::resizable(Fl_Widget *box) + */ void resizable(Fl_Widget& o) {resizable_ = &o;} + /** + The resizable widget defines the resizing box for the group. When the + group is resized it calculates a new size and position for all of its + children. Widgets that are horizontally or vertically inside the + dimensions of the box are scaled to the new size. Widgets outside the + box are moved. + <P>In these examples the gray area is the resizable: + <BR></P> + <P align=center>\image html resizebox1.gif + \image html resizebox2.gif</P> + <P>The resizable may be set to the group itself (this is the default + value for an Fl_Group, although NULL is the default + for Fl_Window and Fl_Pack), in which case all the + contents are resized. + If the resizable is NULL then all widgets remain a fixed size + and distance from the top-left corner. </P> + <P>It is possible to achieve any type of resize behavior by using an + invisible Fl_Box as the resizable and/or by using a hierarchy + of child Fl_Group's. + */ void resizable(Fl_Widget* o) {resizable_ = o;} + /** + See void Fl_Group::resizable(Fl_Widget *box) + */ Fl_Widget* resizable() const {return resizable_;} + /** + Adds a widget to the group and makes it the resizable widget. + */ void add_resizable(Fl_Widget& o) {resizable_ = &o; add(o);} void init_sizes(); diff --git a/FL/Fl_Overlay_Window.H b/FL/Fl_Overlay_Window.H index ff8677ce3..8f4c96b78 100644 --- a/FL/Fl_Overlay_Window.H +++ b/FL/Fl_Overlay_Window.H @@ -30,6 +30,17 @@ #include "Fl_Double_Window.H" +/** + This window provides double buffering and also the ability to draw the + "overlay" which is another picture placed on top of the main image. The + overlay is designed to be a rapidly-changing but simple graphic such as + a mouse selection box. Fl_Overlay_Window uses the overlay + planes provided by your graphics hardware if they are available. + <P>If no hardware support is found the overlay is simulated by drawing + directly into the on-screen copy of the double-buffered window, and + "erased" by copying the backbuffer over it again. This means the + overlay will blink if you change the image in the window. +*/ class FL_EXPORT Fl_Overlay_Window : public Fl_Double_Window { friend class _Fl_Overlay; virtual void draw_overlay() = 0; @@ -42,9 +53,18 @@ public: ~Fl_Overlay_Window(); int can_do_overlay(); void redraw_overlay(); + /** + Creates a new Fl_Overlay_Window widget using the given + position, size, and label (title) string. If the + positions (x,y) are not given, then the window manager + will choose them. + */ Fl_Overlay_Window(int W, int H, const char *l=0) : Fl_Double_Window(W,H,l) {overlay_ = 0; force_doublebuffering_=1; image(0); } - Fl_Overlay_Window(int X, int Y, int W, int H, const char *l=0) + /** + See Fl_Overlay_Window::Fl_Overlay_Window(int W, int H, const char *l=0) + */ + Fl_Overlay_Window(int X, int Y, int W, int H, const char *l=0) : Fl_Double_Window(X,Y,W,H,l) {overlay_ = 0; force_doublebuffering_=1; image(0); } void show(int a, char **b) {Fl_Double_Window::show(a,b);} }; diff --git a/FL/Fl_Single_Window.H b/FL/Fl_Single_Window.H index b87c54a6f..c865e8b44 100644 --- a/FL/Fl_Single_Window.H +++ b/FL/Fl_Single_Window.H @@ -30,13 +30,28 @@ #include "Fl_Window.H" +/** + This is the same as Fl_Window. However, it is possible that + some implementations will provide double-buffered windows by default. + This subcan be used to force single-buffering. This may be + useful for modifying existing programs that use incremental update, or + for some types of image data, such as a movie flipbook. +*/ class FL_EXPORT Fl_Single_Window : public Fl_Window { public: void show(); void show(int a, char **b) {Fl_Window::show(a,b);} void flush(); + /** + Creates a new Fl_Single_Window widget using the given + size, and label (title) string. + */ Fl_Single_Window(int W, int H, const char *l=0) : Fl_Window(W,H,l) {} + /** + Creates a new Fl_Single_Window widget using the given + position, size, and label (title) string. + */ Fl_Single_Window(int X, int Y, int W, int H, const char *l=0) : Fl_Window(X,Y,W,H,l) {} int make_current(); diff --git a/FL/Fl_Window.H b/FL/Fl_Window.H index 2d518ac0e..53ecac5f6 100644 --- a/FL/Fl_Window.H +++ b/FL/Fl_Window.H @@ -35,6 +35,21 @@ class Fl_X; +/** + This widget produces an actual window. This can either be a main + window, with a border and title and all the window management controls, + or a "subwindow" inside a window. This is controlled by whether or not + the window has a parent(). + <P>Once you create a window, you usually add children Fl_Widget + 's to it by using window->add(child) for each new widget. See Fl_Group for more information + on how to add and remove children. </P> + <P>There are several subclasses of Fl_Window that provide + double-buffering, overlay, menu, and OpenGL support. </P> + <P>The window's callback is done if the user tries to close a window + using the window manager and + Fl::modal() is zero or equal to the window. Fl_Window + has a default callback that calls Fl_Window::hide(). +*/ class FL_EXPORT Fl_Window : public Fl_Group { friend class Fl_X; @@ -69,60 +84,296 @@ protected: static Fl_Window *current_; virtual void draw(); + /** Forces the window to be drawn, this window is also made current and calls draw(). */ virtual void flush(); public: - Fl_Window(int,int,int,int, const char* = 0); - Fl_Window(int,int, const char* = 0); - virtual ~Fl_Window(); + /** + Creates a window from the given size and title. + If Fl_Group::current() is not NULL, the window is created as a + subwindow of the parent window.</p> + + <p>The first form of the constructor creates a top-level window + and asks the window manager to position the window. The second + form of the constructor either creates a subwindow or a + top-level window at the specified location (x,y) , subject to window + manager configuration. If you do not specify the position of the + window, the window manager will pick a place to show the window + or allow the user to pick a location. Use position(x,y) + or hotspot() before calling show() to request a + position on the screen. See Fl_Window::resize() + for some more details on positioning windows.</p> + + <p>Top-level windows initially have visible() set to 0 + and parent() set to NULL. Subwindows initially + have visible() set to 1 and parent() set to + the parent window pointer.</p> + + <P>Fl_Widget::box() defaults to FL_FLAT_BOX. If you + plan to completely fill the window with children widgets you should + change this to FL_NO_BOX. If you turn the window border off + you may want to change this to FL_UP_BOX. + */ + Fl_Window(int w, int h, const char* title= 0); + /** Creates a window from the given position, size and title. + See Fl_Window::Fl_Window(int w, int h, const char *title = 0) + */ + Fl_Window(int x, int y, int w, int h, const char* title = 0); + /** + The destructor <I>also deletes all the children</I>. This allows a + whole tree to be deleted at once, without having to keep a pointer to + all the children in the user code. A kludge has been done so the + Fl_Window and all of it's children can be automatic (local) + variables, but you must declare the Fl_Window <I>first</I> so + that it is destroyed last. + */ + virtual ~Fl_Window(); virtual int handle(int); + /** + Changes the size and position of the window. If shown() is + true, these changes are communicated to the window server (which may + refuse that size and cause a further resize). If shown() is + false, the size and position are used when show() is called. + See Fl_Group for the effect + of resizing on the child widgets. + <P>You can also call the Fl_Widget methods size(x,y) + and position(w,h), which are inline wrappers for this virtual + function. </P> + <P>A top-level window can not force, but merely suggest a position and + size to the operating system. The window manager may not be willing or + able to display a window at the desired position or with the given + dimensions. It is up to the application developer to verify window + parameters after the resize request. + */ virtual void resize(int,int,int,int); + /** + Gets or sets whether or not the window manager border is around the + window. The default value is true. border(n) can be used to + turn the border on and off, and returns non-zero if the value has been + changed. <I>Under most X window managers this does not work after + show() has been called, although SGI's 4DWM does work.</I> + */ void border(int b); + /** + Fast inline function to turn the border + off. It only works before show() is called. + */ void clear_border() {set_flag(FL_NOBORDER);} + /** + See int Fl_Window::border(int) + */ int border() const {return !(flags() & FL_NOBORDER);} + /** Activate the flags FL_NOBORDER|FL_OVERRIDE */ void set_override() {set_flag(FL_NOBORDER|FL_OVERRIDE);} + /** Returns non zero if FL_OVERRIDE flag is set, 0 otherwise. */ int override() const { return flags()&FL_OVERRIDE; } + /** + A "modal" window, when shown(), will prevent any events from + being delivered to other windows in the same program, and will also + remain on top of the other windows (if the X window manager supports + the "transient for" property). Several modal windows may be shown at + once, in which case only the last one shown gets events. You can See + which window (if any) is modal by calling + Fl::modal(). + */ void set_modal() {set_flag(FL_MODAL);} + /** + Returns true if this window is modal. + */ int modal() const {return flags() & FL_MODAL;} + /** + A "non-modal" window (terminology borrowed from Microsoft Windows) + acts like a modal() one in that it remains on top, but it has + no effect on event delivery. There are <I>three</I> states for a + window: modal, non-modal, and normal. + */ void set_non_modal() {set_flag(FL_NON_MODAL);} + /** + Returns true if this window is modal or non-modal. + */ int non_modal() const {return flags() & (FL_NON_MODAL|FL_MODAL);} + /** + Position the window so that the mouse is pointing at the + given position, or at the center of the given widget, which may be the + window itself. If the optional offscreen parameter is + non-zero, then the window is allowed to extend off the screen (this + does not work with some X window managers). \see position() + */ void hotspot(int x, int y, int offscreen = 0); + /** + See void Fl_Window::hotspot(int x, int y, int offscreen = 0) + */ void hotspot(const Fl_Widget*, int offscreen = 0); + /** + See void Fl_Window::hotspot(int x, int y, int offscreen = 0) + */ void hotspot(const Fl_Widget& p, int offscreen = 0) {hotspot(&p,offscreen);} + /** + Undoes the effect of a previous resize() or show() + so that the next time show() is called the window manager is + free to position the window. + */ void free_position() {clear_flag(FL_FORCE_POSITION);} + /** + Set the allowable range the user can resize this window to. This only + works for top-level windows. + <UL> + <LI>minw and minh are the smallest the window can + be. Either value must be greater than 0.</LI> + <LI>maxw and maxh are the largest the window can be. + If either is <I>equal</I> to the minimum then you cannot resize in + that direction. If either is zero then FLTK picks a maximum size in + that direction such that the window will fill the screen. </LI> + <LI>dw and dh are size increments. The window will + be constrained to widths of minw + N * dw, where N + is any non-negative integer. If these are less or equal to 1 they + are ignored. (this is ignored on WIN32)</LI> + <LI>aspect is a flag that indicates that the window should + preserve it's aspect ratio. This only works if both the maximum and + minimum have the same aspect ratio. (ignored on WIN32 and by many X + window managers)</LI> + </UL> + If this function is not called, FLTK tries to figure out the range + from the setting of resizable(): + <UL> + <LI>If resizable() is NULL (this is the default) + then the window cannot be resized and the resize border and max-size + control will not be displayed for the window. </LI> + <LI>If either dimension of resizable() is less than 100, + then that is considered the minimum size. Otherwise the + resizable() has a minimum size of 100. </LI> + <LI>If either dimension of resizable() is zero, then that is + also the maximum size (so the window cannot resize in that direction). </LI> + </UL> + It is undefined what happens if the current size does not fit in the + constraints passed to size_range(). + */ void size_range(int a, int b, int c=0, int d=0, int e=0, int f=0, int g=0) { minw=a; minh=b; maxw=c; maxh=d; dw=e; dh=f; aspect=g; size_range_();} + /** + See void Fl_Window::label(const char*) + */ const char* label() const {return Fl_Widget::label();} + /** + See void Fl_Window::iconlabel(const char*) + */ const char* iconlabel() const {return iconlabel_;} + /** + Gets or sets the window title bar label. + */ void label(const char*); + /** + Gets or sets the icon label. + */ void iconlabel(const char*); void label(const char* label, const char* iconlabel); void copy_label(const char* a); + /** + See void Fl_Window::xclass(const char*) + */ const char* xclass() const {return xclass_;} + /** + A string used to tell the system what type of window this is. Mostly + this identifies the picture to draw in the icon. <I>Under X, this is + turned into a XA_WM_CLASS pair by truncating at the first + non-alphanumeric character and capitalizing the first character, and + the second one if the first is 'x'. Thus "foo" turns into "foo, Foo", + and "xprog.1" turns into "xprog, XProg".</I> This only works if called <I> + before</I> calling show(). + <P>Under Microsoft Windows this string is used as the name of the + WNDCLASS structure, though it is not clear if this can have any + visible effect. The passed pointer is stored unchanged. The string + is not copied. + */ void xclass(const char* c) {xclass_ = c;} + /** Gets the current icon window target dependent data */ const void* icon() const {return icon_;} + /** Sets the current icon window target dependent data */ void icon(const void * ic) {icon_ = ic;} + /** + Returns non-zero if show() has been called (but not hide() + ). You can tell if a window is iconified with (w->shown() + &!w->visible()). + */ int shown() {return i != 0;} + /** + Put the window on the screen. Usually this has the side effect of + opening the display. The second form is used for top-level + windows and allow standard arguments to be parsed from the + command-line. + <P>If the window is already shown then it is restored and raised to the + top. This is really convenient because your program can call show() + at any time, even if the window is already up. It also means that + show() serves the purpose of raise() in other toolkits. + */ virtual void show(); + /** + Remove the window from the screen. If the window is already hidden or + has not been shown then this does nothing and is harmless. + */ virtual void hide(); + /** + See virtual void Fl_Window::show() + */ void show(int, char**); + /** + Makes the window completely fill the screen, without any window + manager border visible. You must use fullscreen_off() to undo + this. This may not work with all window managers. + */ void fullscreen(); + /** + Turns off any side effects of fullscreen() and does + resize(x,y,w,h). + */ void fullscreen_off(int,int,int,int); + /** + Iconifies the window. If you call this when shown() is false + it will show() it as an icon. If the window is already + iconified this does nothing. + <P>Call show() to restore the window. </P> + <P>When a window is iconified/restored (either by these calls or by the + user) the handle() method is called with FL_HIDE and + FL_SHOW events and visible() is turned on and off. </P> + <P>There is no way to control what is drawn in the icon except with the + string passed to Fl_Window::xclass(). You should not rely on + window managers displaying the icons. + */ void iconize(); int x_root() const ; int y_root() const ; static Fl_Window *current(); + /** + Sets things up so that the drawing functions in <FL/fl_draw.H> will go into this + window. This is useful for incremental update of windows, such as in an + idle callback, which will make your program behave much better if it + draws a slow graphic. <B>Danger: incremental update is very hard to + debug and maintain!</B> + <P>This method only works for the Fl_Window and + Fl_Gl_Window classes. + */ void make_current(); // for back-compatability only: + /** + Changes the cursor for this window. This always calls the system, if + you are changing the cursor a lot you may want to keep track of how + you set it in a static varaible and call this only if the new cursor + is different. + + <P>The type Fl_Cursor is an enumeration defined in <Enumerations.H>. + (Under X you can get any XC_cursor value by passing + Fl_Cursor((XC_foo/2)+1)). The colors only work on X, they are + not implemented on WIN32. + */ void cursor(Fl_Cursor, Fl_Color=FL_BLACK, Fl_Color=FL_WHITE); void default_cursor(Fl_Cursor, Fl_Color=FL_BLACK, Fl_Color=FL_WHITE); static void default_callback(Fl_Window*, void* v); |