diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/Fl.cxx | 318 | ||||
| -rw-r--r-- | src/Fl_Browser_.cxx | 16 | ||||
| -rw-r--r-- | src/Fl_Double_Window.cxx | 5 | ||||
| -rw-r--r-- | src/Fl_Gl_Window.cxx | 75 | ||||
| -rw-r--r-- | src/Fl_Group.cxx | 68 | ||||
| -rw-r--r-- | src/Fl_Overlay_Window.cxx | 16 | ||||
| -rw-r--r-- | src/Fl_Widget.cxx | 6 | ||||
| -rw-r--r-- | src/Fl_Window.cxx | 8 | ||||
| -rw-r--r-- | src/Fl_add_idle.cxx | 19 | ||||
| -rw-r--r-- | src/Fl_arg.cxx | 125 | ||||
| -rw-r--r-- | src/Fl_compose.cxx | 18 | ||||
| -rw-r--r-- | src/Fl_display.cxx | 6 | ||||
| -rw-r--r-- | src/Fl_get_system_colors.cxx | 47 | ||||
| -rw-r--r-- | src/Fl_lock.cxx | 72 | ||||
| -rw-r--r-- | src/Fl_own_colormap.cxx | 7 | ||||
| -rw-r--r-- | src/Fl_visual.cxx | 34 | ||||
| -rw-r--r-- | src/fl_boxtype.cxx | 37 | ||||
| -rw-r--r-- | src/fl_color.cxx | 19 | ||||
| -rw-r--r-- | src/fl_labeltype.cxx | 1 | ||||
| -rw-r--r-- | src/fl_set_font.cxx | 13 | ||||
| -rw-r--r-- | src/fl_shortcut.cxx | 7 | ||||
| -rw-r--r-- | src/gl_start.cxx | 14 | ||||
| -rw-r--r-- | src/screen_xywh.cxx | 18 |
23 files changed, 888 insertions, 61 deletions
diff --git a/src/Fl.cxx b/src/Fl.cxx index dde61972d..5d2f30e54 100644 --- a/src/Fl.cxx +++ b/src/Fl.cxx @@ -25,6 +25,7 @@ // http://www.fltk.org/str.php // + // warning: the Apple Quartz version still uses some Quickdraw calls, // mostly to get around the single active context in QD and // to implement clipping. This should be changed into pure @@ -89,22 +90,34 @@ Fl_Window *Fl::modal_; // topmost modal() window // double +/** + Returns the compiled-in value of the FL_VERSION constant. This + is useful for checking the version of a shared library. +*/ Fl::version() { return FL_VERSION; } -// -// 'Fl:event_inside()' - Return whether or not the mouse event is inside -// the given rectangle. -// - +/** + Returns whether or not the mouse event is inside the given rectangle. + Returns non-zero if the current event_x and event_y + put it inside the widget or inside an arbitrary bounding box. You + should always call this rather than doing your own comparison so you + are consistent about edge effects. +*/ int Fl::event_inside(int xx,int yy,int ww,int hh) /*const*/ { int mx = e_x - xx; int my = e_y - yy; return (mx >= 0 && mx < ww && my >= 0 && my < hh); } +/** Returns whether or not the mouse event is inside the given widget. + Returns non-zero if the current event_x and event_y + put it inside the widget or inside an arbitrary bounding box. You + should always call this rather than doing your own comparison so you + are consistent about edge effects. +*/ int Fl::event_inside(const Fl_Widget *o) /*const*/ { int mx = e_x - o->x(); int my = e_y - o->y(); @@ -173,11 +186,57 @@ static void elapse_timeouts() { // time interval: static double missed_timeout_by; +/** + Add a one-shot timeout callback. The function will be called by + Fl::wait() at <i>t</i> seconds after this function is called. + The optional void* argument is passed to the callback. + + <P>You can have multiple timeout callbacks. To remove an timeout + callback use Fl::remove_timeout(). + + <p>If you need more accurate, repeated timeouts, use Fl::repeat_timeout() to + reschedule the subsequent timeouts.</p> + + <p>The following code will print "TICK" each second on + stdout with a fair degree of accuracy:</p> + + <PRE> + void callback(void*) { + puts("TICK"); + Fl::repeat_timeout(1.0, callback); + } + + int main() { + Fl::add_timeout(1.0, callback); + return Fl::run(); + } + </PRE> +*/ void Fl::add_timeout(double time, Fl_Timeout_Handler cb, void *argp) { elapse_timeouts(); repeat_timeout(time, cb, argp); } +/** + This method repeats a timeout callback from the expiration of the + previous timeout, allowing for more accurate timing. You may only call + this method inside a timeout callback. + + <p>The following code will print "TICK" each second on + stdout with a fair degree of accuracy:</p> + + <PRE> + void callback(void*) { + puts("TICK"); + Fl::repeat_timeout(1.0, callback); + } + + int main() { + Fl::add_timeout(1.0, callback); + return Fl::run(); + } + </PRE> +*/ void Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *argp) { time += missed_timeout_by; if (time < -.05) time = 0; Timeout* t = free_timeout; @@ -197,12 +256,19 @@ void Fl::repeat_timeout(double time, Fl_Timeout_Handler cb, void *argp) { *p = t; } +/** + Returns true if the timeout exists and has not been called yet. +*/ int Fl::has_timeout(Fl_Timeout_Handler cb, void *argp) { for (Timeout* t = first_timeout; t; t = t->next) if (t->cb == cb && t->arg == argp) return 1; return 0; } +/** + Removes a timeout callback. It is harmless to remove a timeout + callback that no longer exists. +*/ void Fl::remove_timeout(Fl_Timeout_Handler cb, void *argp) { // This version removes all matching timeouts, not just the first one. // This may change in the future. @@ -235,6 +301,37 @@ struct Check { }; static Check *first_check, *next_check, *free_check; +/** + FLTK will call this callback just before it flushes the display and + waits for events. This is different than an idle callback because it + is only called once, then FLTK calls the system and tells it not to + return until an event happens. + + <p>This can be used by code that wants to monitor the + application's state, such as to keep a display up to date. The + advantage of using a check callback is that it is called only when no + events are pending. If events are coming in quickly, whole blocks of + them will be processed before this is called once. This can save + significant time and avoid the application falling behind the events. + + <p>Sample code: + + <UL><PRE> + bool state_changed; // anything that changes the display turns this on + + void callback(void*) { + if (!state_changed) return; + state_changed = false; + do_expensive_calculation(); + widget->redraw(); + } + + main() { + Fl::add_check(callback); + return Fl::run(); + } + </PRE></UL> +*/ void Fl::add_check(Fl_Timeout_Handler cb, void *argp) { Check* t = free_check; if (t) free_check = t->next; @@ -246,6 +343,10 @@ void Fl::add_check(Fl_Timeout_Handler cb, void *argp) { first_check = t; } +/** + Removes a check callback. It is harmless to remove a check + callback that no longer exists. +*/ void Fl::remove_check(Fl_Timeout_Handler cb, void *argp) { for (Check** p = &first_check; *p;) { Check* t = *p; @@ -261,9 +362,8 @@ void Fl::remove_check(Fl_Timeout_Handler cb, void *argp) { } /** - * Return 1, if a check with the same handler and data pointer - * is pending, 0 otherwise. - */ + Returns 1 if the check exists and has not been called yet, 0 otherwise. +*/ int Fl::has_check(Fl_Timeout_Handler cb, void *argp) { for (Check** p = &first_check; *p;) { Check* t = *p; @@ -302,6 +402,9 @@ void (*Fl::idle)(); // see Fl_add_idle.cxx for the add/remove functions extern int fl_ready(); // in Fl_<platform>.cxx extern int fl_wait(double time); // in Fl_<platform>.cxx +/** + See int wait() +*/ double Fl::wait(double time_to_wait) { // delete all widgets that were listed during callbacks do_widget_deletion(); @@ -376,6 +479,13 @@ double Fl::wait(double time_to_wait) { #define FOREVER 1e20 +/** + As long as any windows are displayed this calls Fl::wait() + repeatedly. When all the windows are closed it returns zero + (supposedly it would return non-zero on any errors, but FLTK calls + exit directly for these). A normal program will end main() + with return Fl::run();. +*/ int Fl::run() { while (Fl_X::first) wait(FOREVER); return 0; @@ -398,17 +508,76 @@ static Fl_Win32_At_Exit win32_at_exit; +/** + Waits until "something happens" and then returns. Call this + repeatedly to "run" your program. You can also check what happened + each time after this returns, which is quite useful for managing + program state. + + <P>What this really does is call all idle callbacks, all elapsed + timeouts, call Fl::flush() to get the screen to update, and + then wait some time (zero if there are idle callbacks, the shortest of + all pending timeouts, or infinity), for any events from the user or + any Fl::add_fd() callbacks. It then handles the events and + calls the callbacks and then returns. + + <P>The return value of the first form is non-zero if there are + any visible windows - this may change in future versions of + FLTK. + + <P>The second form waits a maximum of <i>time</i> + seconds. <i>It can return much sooner if something happens.</i> + + <P>The return value is positive if an event or fd happens before the + time elapsed. It is zero if nothing happens (on Win32 this will only + return zero if <i>time</i> is zero). It is negative if an error + occurs (this will happen on UNIX if a signal happens). +*/ int Fl::wait() { if (!Fl_X::first) return 0; wait(FOREVER); return Fl_X::first != 0; // return true if there is a window } +/** + Same as Fl::wait(0). Calling this during a big calculation + will keep the screen up to date and the interface responsive: + + <UL><PRE> + while (!calculation_done()) { + calculate(); + Fl::check(); + if (user_hit_abort_button()) break; + } + </PRE></UL> + + <P>The returns non-zero if any windows are displayed, and 0 if no + windows are displayed (this is likely to change in future versions of + FLTK). +*/ int Fl::check() { wait(0.0); return Fl_X::first != 0; // return true if there is a window } +/** + This is similar to Fl::check() except this does <I>not</I> + call Fl::flush() or any callbacks, which is useful if your + program is in a state where such callbacks are illegal. This returns + true if Fl::check() would do anything (it will continue to + return true until you call Fl::check() or Fl::wait()). + + <UL><PRE> + while (!calculation_done()) { + calculate(); + if (Fl::ready()) { + do_expensive_cleanup(); + Fl::check(); + if (user_hit_abort_button()) break; + } + } + </PRE></UL> +*/ int Fl::ready() { #if ! defined( WIN32 ) && ! defined(__APPLE__) if (first_timeout) { @@ -448,25 +617,52 @@ Fl_Window* fl_find(Window xid) { return 0; } +/** + Returns the first top-level window in the list of shown() windows. If + a modal() window is shown this is the top-most modal window, otherwise + it is the most recent window to get an event. + + <P>The second form sets the window that is returned by + first_window. The window is removed from wherever it is in the + list and inserted at the top. This is not done if Fl::modal() + is on or if the window is not shown(). Because the first window + is used to set the "parent" of modal windows, this is often + useful. +*/ Fl_Window* Fl::first_window() { Fl_X* i = Fl_X::first; return i ? i->w : 0; } +/** + Returns the next top-level window in the list of shown() windows. You can + use this call to iterate through all the windows that are shown(). +*/ Fl_Window* Fl::next_window(const Fl_Window* window) { Fl_X* i = Fl_X::i(window)->next; return i ? i->w : 0; } +/** + See Fl_Window* first_window() +*/ void Fl::first_window(Fl_Window* window) { if (!window || !window->shown()) return; fl_find(fl_xid(window)); } +/** + Redraws all widgets. +*/ void Fl::redraw() { for (Fl_X* i = Fl_X::first; i; i = i->next) i->w->redraw(); } +/** + Causes all the windows that need it to be redrawn and graphics forced + out through the pipes. This is what wait() does before + looking for events. +*/ void Fl::flush() { if (damage()) { damage_ = 0; @@ -505,6 +701,23 @@ struct handler_link { static handler_link *handlers = 0; +/** + Install a function to parse unrecognized events. If FLTK cannot + figure out what to do with an event, it calls each of these functions + (most recent first) until one of them returns non-zero. If none of + them returns non zero then the event is ignored. Events that cause + this to be called are: + + <UL> + <LI>FL_SHORTCUT events that are not recognized by any widget. + This lets you provide global shortcut keys. </LI> + <LI>System events that FLTK does not recognize. See + fl_xevent. </LI> + <LI><I>Some</I> other events when the widget FLTK selected returns + zero from its handle() method. Exactly which ones may change + in future versions, however. </LI> + </UL> +*/ void Fl::add_handler(int (*ha)(int)) { handler_link *l = new handler_link; l->handle = ha; @@ -512,6 +725,9 @@ void Fl::add_handler(int (*ha)(int)) { handlers = l; } +/** + Removes a previously added event handler. +*/ void Fl::remove_handler(int (*ha)(int)) { handler_link *l, *p; @@ -540,6 +756,16 @@ static int send_handlers(int e) { Fl_Widget* fl_oldfocus; // kludge for Fl_Group... +/** + Get or set the widget that will receive FL_KEYBOARD events. + + <P>If you change Fl::focus(), the previous widget and all + parents (that don't contain the new widget) are sent FL_UNFOCUS + events. Changing the focus does <I>not</I> send FL_FOCUS to + this or any widget, because sending FL_FOCUS is supposed to <I> + test</I> if the widget wants the focus (by it returning non-zero from + handle()). +*/ void Fl::focus(Fl_Widget *o) { if (o && !o->visible_focus()) return; if (grab()) return; // don't do anything while grab is on @@ -568,6 +794,20 @@ void Fl::focus(Fl_Widget *o) { static char dnd_flag = 0; // make 'belowmouse' send DND_LEAVE instead of LEAVE +/** + Get or set the widget that is below the mouse. This is for + highlighting buttons. It is not used to send FL_PUSH or + FL_MOVE directly, for several obscure reasons, but those events + typically go to this widget. This is also the first widget tried for + FL_SHORTCUT events. + + <P>If you change the belowmouse widget, the previous one and all + parents (that don't contain the new widget) are sent FL_LEAVE + events. Changing this does <I>not</I> send FL_ENTER to this + or any widget, because sending FL_ENTER is supposed to <I>test</I> + if the widget wants the mouse (by it returning non-zero from + handle()). +*/ void Fl::belowmouse(Fl_Widget *o) { if (grab()) return; // don't do anything while grab is on Fl_Widget *p = belowmouse_; @@ -582,7 +822,19 @@ void Fl::belowmouse(Fl_Widget *o) { } } -void Fl::pushed(Fl_Widget *o) { +/** + Get or set the widget that is being pushed. FL_DRAG or + FL_RELEASE (and any more FL_PUSH) events will be sent to + this widget. + + <P>If you change the pushed widget, the previous one and all parents + (that don't contain the new widget) are sent FL_RELEASE + events. Changing this does <I>not</I> send FL_PUSH to this + or any widget, because sending FL_PUSH is supposed to <I>test</I> + if the widget wants the mouse (by it returning non-zero from + handle()). +*/ + void Fl::pushed(Fl_Widget *o) { pushed_ = o; } @@ -703,6 +955,10 @@ static int send(int event, Fl_Widget* to, Fl_Window* window) { } int Fl::handle(int e, Fl_Window* window) +/** + Sends the event to a window for processing. Returns non-zero if any + widget uses the event. +*/ { e_number = e; if (fl_local_grab) return fl_local_grab(e); @@ -1073,13 +1329,42 @@ int Fl_Window::handle(int ev) //////////////////////////////////////////////////////////////// // Back compatability cut & paste functions for fltk 1.1 only: +/** + The single-argument selection_owner(x) call can be used to + move the selection to another widget or to set the owner to + NULL, without changing the actual text of the + selection. FL_SELECTIONCLEAR is sent to the previous + selection owner, if any. + + <P><I>Copying the buffer every time the selection is changed is + obviously wasteful, especially for large selections. An interface will + probably be added in a future version to allow the selection to be made + by a callback function. The current interface will be emulated on top + of this.</I> +*/ void Fl::selection_owner(Fl_Widget *owner) {selection_owner_ = owner;} +/** + Changes the current selection. The block of text is + copied to an internal buffer by FLTK (be careful if doing this in + response to an FL_PASTE as this <I>may</I> be the same buffer + returned by event_text()). The selection_owner() + widget is set to the passed owner. +*/ void Fl::selection(Fl_Widget &owner, const char* text, int len) { selection_owner_ = &owner; Fl::copy(text, len, 0); } +/** + Set things up so the receiver widget will be called with an FL_PASTE event some + time in the future for the specified clipboard. The reciever + should be prepared to be called <I>directly</I> by this, or for + it to happen <I>later</I>, or possibly <I>not at all</I>. This + allows the window system to take as long as necessary to retrieve + the paste buffer (or even to screw up completely) without complex + and error-prone synchronization code in FLTK. +*/ void Fl::paste(Fl_Widget &receiver) { Fl::paste(receiver, 0); } @@ -1200,7 +1485,6 @@ void Fl_Widget::damage(uchar fl, int X, int Y, int W, int H) { } Fl::damage(FL_DAMAGE_CHILD); } - void Fl_Window::flush() { make_current(); //if (damage() == FL_DAMAGE_EXPOSE && can_boxcheat(box())) fl_boxcheat = this; @@ -1222,8 +1506,18 @@ void Fl_Window::flush() { static int num_dwidgets = 0, alloc_dwidgets = 0; static Fl_Widget **dwidgets = 0; -void -Fl::delete_widget(Fl_Widget *wi) { +/** + Schedules a widget for deletion at the next call to the event loop. + Use this method to delete a widget inside a callback function. + To avoid early deletion of widgets, this function + should be called toward the end of a callback and only after any call + to the event loop (Fl:wait(), Fl::flush(), + fl_ask(), etc).</p> + + <p>When deleting groups or windows, you must only delete the group or + window widget and not the individual child widgets. +*/ +void Fl::delete_widget(Fl_Widget *wi) { if (!wi) return; if (num_dwidgets >= alloc_dwidgets) { diff --git a/src/Fl_Browser_.cxx b/src/Fl_Browser_.cxx index 8a4bc2714..9a6b8f801 100644 --- a/src/Fl_Browser_.cxx +++ b/src/Fl_Browser_.cxx @@ -71,12 +71,24 @@ static void hscrollbar_callback(Fl_Widget* s, void*) { // binary compatibility in 1.1.x - M. Sweet int Fl_Browser_::scrollbar_width_ = 16; -// Get the standard scrollbar size +/** + Gets the default scrollbar size that is used by the + Fl_Browser_, + Fl_Help_View, + Fl_Scroll, and + Fl_Text_Display widgets. +*/ int Fl::scrollbar_size() { return Fl_Browser_::scrollbar_width(); } -// Set the standard scrollbar size +/** + Sets the default scrollbar size that is used by the + Fl_Browser_, + Fl_Help_View, + Fl_Scroll, and + Fl_Text_Display widgets. +*/ void Fl::scrollbar_size(int W) { Fl_Browser_::scrollbar_width(W); } diff --git a/src/Fl_Double_Window.cxx b/src/Fl_Double_Window.cxx index 02a9fea07..4ef7c719c 100644 --- a/src/Fl_Double_Window.cxx +++ b/src/Fl_Double_Window.cxx @@ -443,6 +443,11 @@ void Fl_Double_Window::hide() { Fl_Window::hide(); } +/** + 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. +*/ Fl_Double_Window::~Fl_Double_Window() { hide(); } diff --git a/src/Fl_Gl_Window.cxx b/src/Fl_Gl_Window.cxx index 61c045e12..8d1a587be 100644 --- a/src/Fl_Gl_Window.cxx +++ b/src/Fl_Gl_Window.cxx @@ -25,6 +25,21 @@ // http://www.fltk.org/str.php // +/** \fn virtual void Fl_Gl_Window::draw(void) + Fl_Gl_Window::draw() is a pure virtual method. You must + subclass Fl_Gl_Window and provide an implementation for + draw(). You may also provide an implementation of draw_overlay() + if you want to draw into the overlay planes. You can avoid + reinitializing the viewport and lights and other things by checking + valid() at the start of draw() and only doing the + initialization if it is false. + <P>The draw() method can <I>only</I> use OpenGL calls. Do not + attempt to call X, any of the functions in <FL/fl_draw.H>, or glX + directly. Do not call gl_start() or gl_finish(). </P> + <P>If double-buffering is enabled in the window, the back and front + buffers are swapped after this function is completed. +*/ + #include "flstring.h" #if HAVE_GL @@ -60,6 +75,23 @@ static char SWAP_TYPE = 0 ; // 0 = determine it from environment variable //////////////////////////////////////////////////////////////// +/** + Returns non-zero if the hardware supports the given or current OpenGL + mode. + + <h4>void* Fl_Gl_Window::context() const; + <br>void Fl_Gl_Window::context(void*, int destroy_flag = false);</h4> + + Return or set a pointer to the GLContext that this window is + using. This is a system-dependent structure, but it is portable to copy + the context from one window to another. You can also set it to NULL, + which will force FLTK to recreate the context the next time make_current() is called, this is + useful for getting around bugs in OpenGL implementations. + + <p>If <i>destroy_flag</i> is true the context will be destroyed by + fltk when the window is destroyed, or when the mode() is changed, or the next time + context(x) is called. +*/ int Fl_Gl_Window::can_do(int a, const int *b) { return Fl_Gl_Choice::find(a,b) != 0; } @@ -91,6 +123,10 @@ void Fl_Gl_Window::show() { #endif /* __APPLE__ */ } +/** + The invalidate() method turns off valid() and is + equivalent to calling value(0). +*/ void Fl_Gl_Window::invalidate() { valid(0); context_valid(0); @@ -102,6 +138,9 @@ void Fl_Gl_Window::invalidate() { #endif } +/** + See const int Fl_Gl_Window::mode() const +*/ int Fl_Gl_Window::mode(int m, const int *a) { if (m == mode_ && a == alist) return 0; #ifndef __APPLE__ @@ -139,6 +178,12 @@ int Fl_Gl_Window::mode(int m, const int *a) { #define NON_LOCAL_CONTEXT 0x80000000 +/** + The make_current() method selects the OpenGL context for the + widget. It is called automatically prior to the draw() method + being called and can also be used to implement feedback and/or + selection within the handle() method. +*/ void Fl_Gl_Window::make_current() { // puts("Fl_Gl_Window::make_current()"); // printf("make_current: context_=%p\n", context_); @@ -185,6 +230,11 @@ void Fl_Gl_Window::make_current() { current_ = this; } +/** + Set the projection so 0,0 is in the lower left of the window and each + pixel is 1 unit wide/tall. If you are drawing 2D images, your + draw() method may want to call this if valid() is false. +*/ void Fl_Gl_Window::ortho() { // Alpha NT seems to have a broken OpenGL that does not like negative coords: #ifdef _M_ALPHA @@ -200,6 +250,10 @@ void Fl_Gl_Window::ortho() { #endif } +/** + The swap_buffers() method swaps the back and front buffers. + It is called automatically after the draw() method is called. +*/ void Fl_Gl_Window::swap_buffers() { #ifdef WIN32 # if HAVE_GL_OVERLAY @@ -397,6 +451,9 @@ void Fl_Gl_Window::context(void* v, int destroy_flag) { else mode_ |= NON_LOCAL_CONTEXT; } +/** + Hides the window and destroys the OpenGL context. +*/ void Fl_Gl_Window::hide() { context(0); #if HAVE_GL_OVERLAY && defined(WIN32) @@ -408,6 +465,10 @@ void Fl_Gl_Window::hide() { Fl_Window::hide(); } +/** + The destructor removes the widget and destroys the OpenGL context + associated with it. +*/ Fl_Gl_Window::~Fl_Gl_Window() { hide(); // delete overlay; this is done by ~Fl_Group @@ -432,6 +493,20 @@ void Fl_Gl_Window::init() { #endif // 0 } +/** + You must implement this virtual function if you want to draw into the + overlay. The overlay is cleared before this is called. You should + draw anything that is not clear using OpenGL. You must use + gl_color(i) to choose colors (it allocates them from the colormap + using system-specific calls), and remember that you are in an indexed + OpenGL mode and drawing anything other than flat-shaded will probably + not work. + <P>Both this function and Fl_Gl_Window::draw() should check + Fl_Gl_Window::valid() and set the same transformation. If you + don't your code may not work on other systems. Depending on the OS, + and on whether overlays are real or simulated, the OpenGL context may + be the same or different between the overlay and main window. +*/ void Fl_Gl_Window::draw_overlay() {} #endif diff --git a/src/Fl_Group.cxx b/src/Fl_Group.cxx index 49e2ccb1b..4879e5c2f 100644 --- a/src/Fl_Group.cxx +++ b/src/Fl_Group.cxx @@ -41,10 +41,18 @@ Fl_Group* Fl_Group::current_; // Hack: A single child is stored in the pointer to the array, while // multiple children are stored in an allocated array: +/** + Returns a pointer to the array of children. <I>This pointer is only + valid until the next time a child is added or removed.</I> +*/ Fl_Widget*const* Fl_Group::array() const { return children_ <= 1 ? (Fl_Widget**)(&array_) : array_; } +/** + Searches the child array for the widget and returns the index. Returns children() if the widget is + NULL or not found. +*/ int Fl_Group::find(const Fl_Widget* o) const { Fl_Widget*const* a = array(); int i; for (i=0; i < children_; i++) if (*a++ == o) break; @@ -53,9 +61,28 @@ int Fl_Group::find(const Fl_Widget* o) const { // Metrowerks CodeWarrior and others can't export the static // class member: current_, so these methods can't be inlined... +/** + Sets the current group so you can build the widget + tree by just constructing the widgets. begin() is + automatically called by the constructor for Fl_Group (and thus for + Fl_Window as well). begin() <i>is exactly the same as</i> current(this). + <P><I>Don't forget to end() the group or window!</I> +*/ void Fl_Group::begin() {current_ = this;} +/** + <i>Exactly the same as</i> current(this->parent()). Any new widgets + added to the widget tree will be added to the parent of the group. +*/ void Fl_Group::end() {current_ = (Fl_Group*)parent();} +/** + Returns the currently active group. The Fl_Widget + constructor automatically does current()->add(widget) if this is not null. + To prevent new widgets from being added to a group, call Fl_Group::current(0). +*/ Fl_Group *Fl_Group::current() {return current_;} +/** + See static Fl_Group *Fl_Group::current() +*/ void Fl_Group::current(Fl_Group *g) {current_ = g;} extern Fl_Widget* fl_oldfocus; // set by Fl::focus @@ -341,6 +368,13 @@ Fl_Group::Fl_Group(int X,int Y,int W,int H,const char *l) begin(); } +/** + The clear() method deletes all child widgets from + memory recursively.</p> + + <p>This method differs from the remove() method in that it + affects all child widgets and deletes them from memory. +*/ void Fl_Group::clear() { Fl_Widget*const* old_array = array(); int old_children = children(); @@ -359,10 +393,24 @@ void Fl_Group::clear() { if (old_children > 1) free((void*)old_array); } +/** + 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_Group and all of it's children can be automatic (local) + variables, but you must declare the Fl_Group <I>first</I>, so + that it is destroyed last. +*/ Fl_Group::~Fl_Group() { clear(); } +/** + The widget is removed from it's current group (if any) and then + inserted into this group. It is put at index n (or at the end + if n >= children(). This can also be used to rearrange + the widgets inside a group. +*/ void Fl_Group::insert(Fl_Widget &o, int index) { if (o.parent()) { Fl_Group* g = (Fl_Group*)(o.parent()); @@ -392,8 +440,21 @@ void Fl_Group::insert(Fl_Widget &o, int index) { init_sizes(); } +/** + The widget is removed from it's current group (if any) and then added + to the end of this group. +*/ void Fl_Group::add(Fl_Widget &o) {insert(o, children_);} +/** + Removes a widget from the group but does not delete it. This + method does nothing if the widget is not a child of the + group. + + <p>This method differs from the clear() method in that it + only affects a single widget and does not delete it from + memory. +*/ void Fl_Group::remove(Fl_Widget &o) { if (!children_) return; int i = find(o); @@ -424,6 +485,13 @@ void Fl_Group::remove(Fl_Widget &o) { // algorithim. If you change this be sure to fix Fl_Tile which // also uses this array! +/** + The Fl_Group widget keeps track of the original widget sizes and + positions when resizing occurs so that if you resize a window back to its + original size the widgets will be in the correct places. If you rearrange + the widgets in your group, call this method to register the new arrangement + with the Fl_Group that contains them. +*/ void Fl_Group::init_sizes() { delete[] sizes_; sizes_ = 0; } diff --git a/src/Fl_Overlay_Window.cxx b/src/Fl_Overlay_Window.cxx index 06ed0b244..539503180 100644 --- a/src/Fl_Overlay_Window.cxx +++ b/src/Fl_Overlay_Window.cxx @@ -25,6 +25,13 @@ // http://www.fltk.org/str.php // +/** \fn virtual void Fl_Overlay_Window::draw_overlay() = 0 + You must subclass Fl_Overlay_Window and provide this method. + It is just like a draw() method, except it draws the overlay. + The overlay will have already been "cleared" when this is called. You + can use any of the routines described in <FL/fl_draw.H>. +*/ + // A window using double-buffering and able to draw an overlay // on top of that. Uses the hardware to draw the overlay if // possible, otherwise it just draws in the front buffer. @@ -65,6 +72,9 @@ void Fl_Overlay_Window::resize(int X, int Y, int W, int H) { if (overlay_ && overlay_!=this) overlay_->resize(0,0,w(),h()); } +/** + Destroys the window and all child widgets. +*/ Fl_Overlay_Window::~Fl_Overlay_Window() { hide(); // delete overlay; this is done by ~Fl_Group @@ -74,6 +84,12 @@ Fl_Overlay_Window::~Fl_Overlay_Window() { int Fl_Overlay_Window::can_do_overlay() {return 0;} +/** + Call this to indicate that the overlay data has changed and needs to + be redrawn. The overlay will be clear until the first time this is + called, so if you want an initial display you must call this after + calling show(). +*/ void Fl_Overlay_Window::redraw_overlay() { overlay_ = this; clear_damage((uchar)(damage()|FL_DAMAGE_OVERLAY)); diff --git a/src/Fl_Widget.cxx b/src/Fl_Widget.cxx index 4ae8d8306..f96051a0e 100644 --- a/src/Fl_Widget.cxx +++ b/src/Fl_Widget.cxx @@ -62,7 +62,11 @@ void Fl_Widget::default_callback(Fl_Widget *o, void * /*v*/) { if (obj_tail >= QUEUE_SIZE) obj_tail = 0; } } - +/** + All Fl_Widgets that don't have a callback defined use a + default callback that puts a pointer to the widget in this queue, and + this method reads the oldest widget out of this queue. +*/ Fl_Widget *Fl::readqueue() { if (obj_tail==obj_head) return 0; Fl_Widget *o = obj_queue[obj_tail++]; diff --git a/src/Fl_Window.cxx b/src/Fl_Window.cxx index 04d94aa5c..c4a7ca8ce 100644 --- a/src/Fl_Window.cxx +++ b/src/Fl_Window.cxx @@ -85,13 +85,13 @@ Fl_Window *Fl_Widget::window() const { if (o->type() >= FL_WINDOW) return (Fl_Window*)o; return 0; } - +/** Gets the x position of the window on the screen */ int Fl_Window::x_root() const { Fl_Window *p = window(); if (p) return p->x_root() + x(); return x(); } - +/** Gets the y position of the window on the screen */ int Fl_Window::y_root() const { Fl_Window *p = window(); if (p) return p->y_root() + y(); @@ -159,6 +159,7 @@ void Fl_Window::iconlabel(const char *iname) { // the Fl::atclose pointer is provided for back compatability. You // can now just change the callback for the window instead. +/** Default callback for window widgets. It hides the window and then calls the default widget callback. */ void Fl::default_atclose(Fl_Window* window, void* v) { window->hide(); Fl_Widget::default_callback(window, v); // put on Fl::read_queue() @@ -170,6 +171,9 @@ void Fl_Window::default_callback(Fl_Window* win, void* v) { Fl::atclose(win, v); } +/** + Returns the last window that was made current. +*/ Fl_Window *Fl_Window::current() { return current_; } diff --git a/src/Fl_add_idle.cxx b/src/Fl_add_idle.cxx index 1afc4e987..6d5e4b038 100644 --- a/src/Fl_add_idle.cxx +++ b/src/Fl_add_idle.cxx @@ -49,6 +49,23 @@ static void call_idle() { p->cb(p->data); // this may call add_idle() or remove_idle()! } +/** + Adds a callback function that is called every time by + Fl::wait() and also makes it act as though the timeout is + zero (this makes Fl::wait() return immediately, so if it is + in a loop it is called repeatedly, and thus the idle fucntion is + called repeatedly). The idle function can be used to get background + processing done. + + <P>You can have multiple idle callbacks. To remove an idle callback use Fl::remove_idle(). + + <P>Fl::wait() and Fl::check() call idle callbacks, + but Fl::ready() does not. + + <P>The idle callback can call any FLTK functions, including + Fl::wait(), Fl::check(), and Fl::ready(). + FLTK will not recursively call the idle callback. +*/ void Fl::add_idle(void (*cb)(void*), void* data) { idle_cb* p = freelist; if (p) freelist = p->next; @@ -66,6 +83,7 @@ void Fl::add_idle(void (*cb)(void*), void* data) { } } +/** Returns true if the specified idle callback is currently installed. */ int Fl::has_idle(void (*cb)(void*), void* data) { idle_cb* p = first; if (!p) return 0; @@ -75,6 +93,7 @@ int Fl::has_idle(void (*cb)(void*), void* data) { } } +/** Removes the specified idle callback, if it is installed. */ void Fl::remove_idle(void (*cb)(void*), void* data) { idle_cb* p = first; if (!p) return; diff --git a/src/Fl_arg.cxx b/src/Fl_arg.cxx index 49002816d..ae0d446bf 100644 --- a/src/Fl_arg.cxx +++ b/src/Fl_arg.cxx @@ -67,7 +67,13 @@ extern const char *fl_fg; extern const char *fl_bg; extern const char *fl_bg2; -// consume a switch from argv. Returns number of words eaten, 0 on error: +/** + Consume a single switch from argv, starting at word i. + Returns the number of words eaten (1 or 2, or 0 if it is not + recognized) and adds the same value to i. You can use this + function if you prefer to control the incrementing through the + arguments yourself. +*/ int Fl::arg(int argc, char **argv, int &i) { arg_called = 1; const char *s = argv[i]; @@ -167,11 +173,116 @@ int Fl::arg(int argc, char **argv, int &i) { return 2; } -// consume all switches from argv. Returns number of words eaten. -// Returns zero on error. 'i' will either point at first word that -// does not start with '-', at the error word, or after a '--', or at -// argc. If your program does not take any word arguments you can -// report an error if i < argc. + +/** + Consume all switches from argv. Returns number of words eaten + Returns zero on error. 'i' will either point at first word that + does not start with '-', at the error word, or after a '--', or at + argc. If your program does not take any word arguments you can + report an error if i < argc. + + <P>FLTK provides an <I>entirely optional</I> command-line switch parser. + You don't have to call it if you don't like them! Everything it can do + can be done with other calls to FLTK. + + <P>To use the switch parser, call Fl::args(...) near the start + of your program. This does <I>not</I> open the display, instead + switches that need the display open are stashed into static variables. + Then you <I>must</I> display your first window by calling + window->show(argc,argv), which will do anything stored in the + static variables. + + <P>callback lets you define your own switches. It is called + with the same argc and argv, and with i the + index of each word. The callback should return zero if the switch is + unrecognized, and not change i. It should return non-zero if + the switch is recognized, and add at least 1 to i (it can add + more to consume words after the switch). This function is called + <i>before</i> any other tests, so <i>you can override any FLTK + switch</i> (this is why FLTK can use very short switches instead of + the long ones all other toolkits force you to use). + + <P>On return i is set to the index of the first non-switch. + This is either: + + <UL> + <LI>The first word that does not start with '-'. </LI> + <LI>The word '-' (used by many programs to name stdin as a file) </LI> + <LI>The first unrecognized switch (return value is 0). </LI> + <LI>argc</LI> + </UL> + + <P>The return value is i unless an unrecognized switch is found, + in which case it is zero. If your program takes no arguments other + than switches you should produce an error if the return value is less + than argc. + + <P>All switches except -bg2 may be abbreviated one letter and case is ignored: + + <UL> + + <LI>-bg color or -background color + + <P>Sets the background color using Fl::background().</LI> + + <LI>-bg2 color or -background2 color + + <P>Sets the secondary background color using Fl::background2().</LI> + + <LI>-display host:n.n + + <P>Sets the X display to use; this option is silently + ignored under WIN32 and MacOS.</LI> + + <LI>-dnd and -nodnd + + <P>Enables or disables drag and drop text operations + using Fl::dnd_text_ops().</LI> + + <LI>-fg color or -foreground color + + <P>Sets the foreground color using Fl::foreground().</LI> + + <LI>-geometry WxH+X+Y + + <P>Sets the initial window position and size according + the the standard X geometry string.</LI> + + <LI>-iconic + + <P>Iconifies the window using Fl_Window::iconize().</LI> + + <LI>-kbd and -nokbd + + <P>Enables or disables visible keyboard focus for + non-text widgets using Fl::visible_focus().</LI> + + <LI>-name string + + <P>Sets the window class using Fl_Window::xclass().</LI> + + <LI>-scheme string + + <P>Sets the widget scheme using Fl::scheme().</LI> + + <LI>-title string + + <P>Sets the window title using Fl_Window::label().</LI> + + <LI>-tooltips and -notooltips + + <P>Enables or disables tooltips using Fl_Tooltip::enable().</LI> + + </UL> + + <P>The second form of Fl::args() is useful if your program does + not have command line switches of its own. It parses all the switches, + and if any are not recognized it calls Fl::abort(Fl::help). + + <P>A usage string is displayed if Fl::args() detects an invalid + argument on the command-line. You can change the message by setting the + Fl::help pointer. +*/ int Fl::args(int argc, char** argv, int& i, int (*cb)(int,char**,int&)) { arg_called = 1; @@ -283,7 +394,7 @@ static const char * const helpmsg = " -to[oltips]"; const char * const Fl::help = helpmsg+13; - +/** See Fl::args(int argc, char **argv, int& i, int (*cb)(int,char**,int&)) */ void Fl::args(int argc, char **argv) { int i; if (Fl::args(argc,argv,i) < argc) Fl::error(helpmsg); } diff --git a/src/Fl_compose.cxx b/src/Fl_compose.cxx index 10cdb0602..a442ee108 100644 --- a/src/Fl_compose.cxx +++ b/src/Fl_compose.cxx @@ -87,6 +87,24 @@ static char dead_keys[] = { int Fl::compose_state = 0; +/** Any text editing widget should call this for each FL_KEYBOARD event. + Use of this function is very simple. + + <p>If <i>true</i> is returned, then it has modified the + Fl::event_text() and Fl::event_length() to a set of <i>bytes</i> to + insert (it may be of zero length!). In will also set the "del" + parameter to the number of <i>bytes</i> to the left of the cursor to + delete, this is used to delete the results of the previous call to + Fl::compose(). + + <p>If <i>false</i> is returned, the keys should be treated as function + keys, and del is set to zero. You could insert the text anyways, if + you don't know what else to do. + + <p>Though the current implementation returns immediately, future + versions may take quite awhile, as they may pop up a window or do + other user-interface things to allow characters to be selected. +*/ int Fl::compose(int& del) { del = 0; diff --git a/src/Fl_display.cxx b/src/Fl_display.cxx index 8afc2583e..7ce6d4293 100644 --- a/src/Fl_display.cxx +++ b/src/Fl_display.cxx @@ -32,6 +32,12 @@ #include <stdlib.h> #include "flstring.h" +/** + Sets the X display to use for all windows. Actually this just sets + the environment variable $DISPLAY to the passed string, so this only + works before you show() the first window or otherwise open the display, + and does nothing useful under WIN32. +*/ void Fl::display(const char *d) { #if defined(__APPLE__) || defined(WIN32) (void)d; diff --git a/src/Fl_get_system_colors.cxx b/src/Fl_get_system_colors.cxx index 3f2fadf0e..f929cef89 100644 --- a/src/Fl_get_system_colors.cxx +++ b/src/Fl_get_system_colors.cxx @@ -51,7 +51,12 @@ static char fl_bg_set = 0; static char fl_bg2_set = 0; static char fl_fg_set = 0; - +/** + Changes fl_color(FL_BACKGROUND_COLOR) to the given color, + and changes the gray ramp from 32 to 56 to black to white. These are + the colors used as backgrounds by almost all widgets and used to draw + the edges of all the boxtypes. +*/ void Fl::background(uchar r, uchar g, uchar b) { fl_bg_set = 1; @@ -70,13 +75,19 @@ void Fl::background(uchar r, uchar g, uchar b) { uchar(pow(gray,powb)*255+.5)); } } - +/** Changes fl_color(FL_FOREGROUND_COLOR). */ void Fl::foreground(uchar r, uchar g, uchar b) { fl_fg_set = 1; Fl::set_color(FL_FOREGROUND_COLOR,r,g,b); } +/** + Changes the alternative background color. This color is used as a + background by Fl_Input and other text widgets. + <P>This call may change fl_color(FL_FOREGROUND_COLOR) if it + does not provide sufficient contrast to FL_BACKGROUND2_COLOR. +*/ void Fl::background2(uchar r, uchar g, uchar b) { fl_bg2_set = 1; @@ -132,7 +143,18 @@ int fl_parse_color(const char* p, uchar& r, uchar& g, uchar& b) { } else return 0; } #endif // WIN32 || __APPLE__ - +/** \fn Fl::get_system_colors() + Read the user preference colors from the system and use them to call + Fl::foreground(), Fl::background(), and + Fl::background2(). This is done by + Fl_Window::show(argc,argv) before applying the -fg and -bg + switches. + + <P>On X this reads some common values from the Xdefaults database. + KDE users can set these values by running the "krdb" program, and + newer versions of KDE set this automatically if you check the "apply + style to other X programs" switch in their control panel. +*/ #if defined(WIN32) static void getsyscolor(int what, const char* arg, void (*func)(uchar,uchar,uchar)) @@ -246,6 +268,25 @@ Fl_Image *Fl::scheme_bg_ = (Fl_Image *)0; static Fl_Pixmap tile(tile_xpm); +/** + Gets or sets the current widget scheme. NULL will use + the scheme defined in the FLTK_SCHEME environment + variable or the scheme resource under X11. Otherwise, + any of the following schemes can be used:</P> + + <ul> + + <li>"none" - This is the default look-n-feel which resembles old + Windows (95/98/Me/NT/2000) and old GTK/KDE</li> + + <li>"plastic" - This scheme is inspired by the Aqua user interface + on Mac OS X</li> + + <li>"gtk+" - This scheme is inspired by the Red Hat Bluecurve + theme</li> + + </ul> +*/ int Fl::scheme(const char *s) { if (!s) { if ((s = getenv("FLTK_SCHEME")) == NULL) { diff --git a/src/Fl_lock.cxx b/src/Fl_lock.cxx index a7be4c308..82763aeb1 100644 --- a/src/Fl_lock.cxx +++ b/src/Fl_lock.cxx @@ -78,6 +78,7 @@ static void lock_ring(); static void unlock_ring(); +/** Adds an awake handler for use in awake(). */ int Fl::add_awake_handler_(Fl_Awake_Handler func, void *data) { int ret = 0; @@ -100,7 +101,7 @@ int Fl::add_awake_handler_(Fl_Awake_Handler func, void *data) unlock_ring(); return ret; } - +/** Gets the last stored awake handler for use in awake(). */ int Fl::get_awake_handler_(Fl_Awake_Handler &func, void *&data) { int ret = 0; @@ -119,9 +120,11 @@ int Fl::get_awake_handler_(Fl_Awake_Handler &func, void *&data) } // -// 'Fl::awake()' - Let the main thread know an update is pending -// and have it cal a specific function -// +/** + Let the main thread know an update is pending + and have it call a specific function + See void awake(void* message=0). +*/ int Fl::awake(Fl_Awake_Handler func, void *data) { int ret = add_awake_handler_(func, data); Fl::awake(); @@ -130,6 +133,52 @@ int Fl::awake(Fl_Awake_Handler func, void *data) { //////////////////////////////////////////////////////////////// // Windows threading... +/** \fn void Fl::lock() + The lock() method blocks the current thread until it + can safely access FLTK widgets and data. Child threads should + call this method prior to updating any widgets or accessing + data. The main thread must call lock() to initialize + the threading support in FLTK. + + <P>Child threads must call unlock() when they are done + accessing FLTK. + + <P>When the wait() method is waiting + for input or timeouts, child threads are given access to FLTK. + Similarly, when the main thread needs to do processing, it will + wait until all child threads have called unlock() before processing + additional data. + + <P>See also: multithreading +*/ +/** \fn void Fl::unlock() + The unlock() method releases the lock that was set + using the lock() method. Child + threads should call this method as soon as they are finished + accessing FLTK. + + <P>See also: multithreading +*/ +/** \fn void Fl::awake(void* msg) + The awake() method sends a message pointer to the main thread, + causing any pending Fl::wait() call to + terminate so that the main thread can retrieve the message and any pending + redraws can be processed. + + <P>Multiple calls to Fl::awake() will queue multiple pointers + for the main thread to process, up to a system-defined (typically several + thousand) depth. The default message handler saves the last message which + can be accessed using the + Fl::thread_message() function. + + <P>The second form of awake() registers a function that will be + called by the main thread during the next message handling cycle. + awake() will return 0 if the callback function was registered, + and -1 if registration failed. Over a thousand awake callbacks can be + registered simultaneously. + + <P>See also: multithreading. +*/ #ifdef WIN32 # include <windows.h> # include <process.h> @@ -174,10 +223,6 @@ static void lock_function() { EnterCriticalSection(&cs); } -// -// 'Fl::lock()' - Lock access to FLTK data structures... -// - void Fl::lock() { if (!main_thread) InitializeCriticalSection(&cs); @@ -190,21 +235,10 @@ void Fl::lock() { } } -// -// 'Fl::unlock()' - Unlock access to FLTK data structures... -// - void Fl::unlock() { unlock_function(); } - -// -// 'Fl::awake()' - Let the main thread know an update is pending. -// -// When called from a thread, it causes FLTK to awake from Fl::wait()... -// - void Fl::awake(void* msg) { PostThreadMessage( main_thread, fl_wake_msg, (WPARAM)msg, 0); } diff --git a/src/Fl_own_colormap.cxx b/src/Fl_own_colormap.cxx index 9045e5da1..d1191a811 100644 --- a/src/Fl_own_colormap.cxx +++ b/src/Fl_own_colormap.cxx @@ -37,6 +37,13 @@ #include <FL/Fl.H> #include <FL/x.H> +/** \fn Fl::own_colormap() + Makes FLTK use its own colormap. This may make FLTK display better + and will reduce conflicts with other programs that want lots of colors. + However the colors may flash as you move the cursor between windows. + + <P>This does nothing if the current visual is not colormapped. +*/ #ifdef WIN32 // There is probably something relevant to do on MSWindows 8-bit displays // but I don't know what it is diff --git a/src/Fl_visual.cxx b/src/Fl_visual.cxx index a0487c046..c19fa5b03 100644 --- a/src/Fl_visual.cxx +++ b/src/Fl_visual.cxx @@ -31,6 +31,40 @@ #include <FL/Fl.H> #include <FL/x.H> +/** \fn Fl::visual(int flags) + Selects a visual so that your graphics are drawn correctly. This is + only allowed before you call show() on any windows. This does nothing + if the default visual satisfies the capabilities, or if no visual + satisfies the capabilities, or on systems that don't have such + brain-dead notions. + + <P>Only the following combinations do anything useful: + + <UL> + <LI>Fl::visual(FL_RGB) + <BR>Full/true color (if there are several depths FLTK chooses the + largest). Do this if you use fl_draw_image + for much better (non-dithered) output. + <BR> </LI> + <LI>Fl::visual(FL_RGB8) + <BR>Full color with at least 24 bits of color. FL_RGB will + always pick this if available, but if not it will happily return a + less-than-24 bit deep visual. This call fails if 24 bits are not + available. + <BR> </LI> + <LI>Fl::visual(FL_DOUBLE|FL_INDEX) + <BR>Hardware double buffering. Call this if you are going to use + Fl_Double_Window. + <BR> </LI> + <LI>Fl::visual(FL_DOUBLE|FL_RGB)</LI> + <LI>Fl::visual(FL_DOUBLE|FL_RGB8) + <BR>Hardware double buffering and full color. + </UL> + + <P>This returns true if the system has the capabilities by default or + FLTK suceeded in turing them on. Your program will still work even if + this returns false (it just won't look as good). +*/ #ifdef WIN32 int Fl::visual(int flags) { fl_GetDC(0); diff --git a/src/fl_boxtype.cxx b/src/fl_boxtype.cxx index e8099efab..ec7490e30 100644 --- a/src/fl_boxtype.cxx +++ b/src/fl_boxtype.cxx @@ -259,9 +259,36 @@ static struct { {fl_down_box, 3,3,6,6,0}, // FL_FREE_BOX+7 }; +/** Returns the X offset for the given boxtype. See box_dy(). */ int Fl::box_dx(Fl_Boxtype t) {return fl_box_table[t].dx;} +/** + Returns the Y offset for the given boxtype. + + <P>These functions return the offset values necessary for a given + boxtype, useful for computing the area inside a box's borders, to + prevent overdrawing the borders. + + <P>For instance, in the case of a boxtype like FL_DOWN_BOX + where the border width might be 2 pixels all around, the above + functions would return 2, 2, 4, and 4 for box_dx, + box_dy, box_dw, and box_dh + respectively. + + <P>An example to compute the area inside a widget's box(): + <pre> + int X = yourwidget->x() + Fl::box_dx(yourwidget->box()); + int Y = yourwidget->y() + Fl::box_dy(yourwidget->box()); + int W = yourwidget->w() - Fl::box_dw(yourwidget->box()); + int H = yourwidget->h() - Fl::box_dh(yourwidget->box()); + </pre> + <P>These functions are mainly useful in the draw() code + for deriving custom widgets, where one wants to avoid drawing + over the widget's own border box(). +*/ int Fl::box_dy(Fl_Boxtype t) {return fl_box_table[t].dy;} +/** Returns the width offset for the given boxtype. See box_dy(). */ int Fl::box_dw(Fl_Boxtype t) {return fl_box_table[t].dw;} +/** Returns the height offset for the given boxtype. See box_dy(). */ int Fl::box_dh(Fl_Boxtype t) {return fl_box_table[t].dh;} void fl_internal_boxtype(Fl_Boxtype t, Fl_Box_Draw_F* f) { @@ -270,11 +297,11 @@ void fl_internal_boxtype(Fl_Boxtype t, Fl_Box_Draw_F* f) { fl_box_table[t].set = 1; } } - +/** Gets the current box drawing function for the specified box type. */ Fl_Box_Draw_F *Fl::get_boxtype(Fl_Boxtype t) { return fl_box_table[t].f; } - +/** Sets the function to call to draw a specific boxtype. */ void Fl::set_boxtype(Fl_Boxtype t, Fl_Box_Draw_F* f, uchar a, uchar b, uchar c, uchar d) { fl_box_table[t].f = f; @@ -284,9 +311,9 @@ void Fl::set_boxtype(Fl_Boxtype t, Fl_Box_Draw_F* f, fl_box_table[t].dw = c; fl_box_table[t].dh = d; } - -void Fl::set_boxtype(Fl_Boxtype t, Fl_Boxtype f) { - fl_box_table[t] = fl_box_table[f]; +/** Copies the from boxtype. */ +void Fl::set_boxtype(Fl_Boxtype to, Fl_Boxtype from) { + fl_box_table[to] = fl_box_table[from]; } void fl_draw_box(Fl_Boxtype t, int x, int y, int w, int h, Fl_Color c) { diff --git a/src/fl_color.cxx b/src/fl_color.cxx index cad299f4d..4b692ac50 100644 --- a/src/fl_color.cxx +++ b/src/fl_color.cxx @@ -317,17 +317,30 @@ void Fl::set_color(Fl_Color i, unsigned c) { } #endif // end of X-specific code - +/** + Returns the RGB value(s) for the given FLTK color index. The + first form returns the RGB values packed in a 32-bit unsigned + integer with the red value in the upper 8 bits, the green value + in the next 8 bits, and the blue value in bits 8-15. The lower + 8 bits will always be 0. + + <P>The second form returns the red, green, and blue values + separately in referenced variables. +*/ unsigned Fl::get_color(Fl_Color i) { if (i & 0xffffff00) return (i); else return fl_cmap[i]; } - +/** + Sets an entry in the fl_color index table. You can set it to + any 8-bit RGB color. The color is not allocated until fl_color(i) + is used. +*/ void Fl::set_color(Fl_Color i, uchar red, uchar green, uchar blue) { Fl::set_color((Fl_Color)(i & 255), ((unsigned)red<<24)+((unsigned)green<<16)+((unsigned)blue<<8)); } - +/** See unsigned get_color(Fl_Color c) */ void Fl::get_color(Fl_Color i, uchar &red, uchar &green, uchar &blue) { unsigned c; diff --git a/src/fl_labeltype.cxx b/src/fl_labeltype.cxx index c73f40a9f..88e22a20b 100644 --- a/src/fl_labeltype.cxx +++ b/src/fl_labeltype.cxx @@ -74,6 +74,7 @@ static Fl_Label_Draw_F* table[MAX_LABELTYPE] = { static Fl_Label_Measure_F* measure[MAX_LABELTYPE]; +/** Sets the functions to call to draw and measure a specific labeltype. */ void Fl::set_labeltype(Fl_Labeltype t,Fl_Label_Draw_F* f,Fl_Label_Measure_F*m) { table[t] = f; measure[t] = m; diff --git a/src/fl_set_font.cxx b/src/fl_set_font.cxx index 180d3bb87..4421ee86b 100644 --- a/src/fl_set_font.cxx +++ b/src/fl_set_font.cxx @@ -36,7 +36,10 @@ #include <stdlib.h> static int table_size; - +/** + Changes a face. The string pointer is simply stored, + the string is not copied, so the string must be in static memory. +*/ void Fl::set_font(Fl_Font fnum, const char* name) { while (fnum >= table_size) { int i = table_size; @@ -78,11 +81,15 @@ void Fl::set_font(Fl_Font fnum, const char* name) { s->first = 0; fl_font(-1, 0); } - +/** Copies one face to another. */ void Fl::set_font(Fl_Font fnum, Fl_Font from) { Fl::set_font(fnum, get_font(from)); } - +/** + Get the string for this face. This string is different for each + face. Under X this value is passed to XListFonts to get all the sizes + of this face. +*/ const char* Fl::get_font(Fl_Font fnum) {return fl_fonts[fnum].name;} // diff --git a/src/fl_shortcut.cxx b/src/fl_shortcut.cxx index 98c13ad59..38bf3857b 100644 --- a/src/fl_shortcut.cxx +++ b/src/fl_shortcut.cxx @@ -51,6 +51,13 @@ #include <FL/x.H> #endif +/** + Test the current event, which must be an FL_KEYBOARD or + FL_SHORTCUT, against a shortcut value (described in + Fl_Button). Returns non-zero if there is a match. Not to + be confused with + Fl_Widget::test_shortcut(). +*/ int Fl::test_shortcut(int shortcut) { if (!shortcut) return 0; diff --git a/src/gl_start.cxx b/src/gl_start.cxx index a47aeaca7..868a0d894 100644 --- a/src/gl_start.cxx +++ b/src/gl_start.cxx @@ -109,7 +109,19 @@ void gl_finish() { glXWaitGL(); #endif } - +/** + This does the same thing as + Fl::visual(int) but also + requires OpenGL drawing to work. This <I>must</I> be done if + you want to draw in normal windows with OpenGL with gl_start() and + gl_end(). It may be useful to call this so your X + windows use the same visual as an + Fl_Gl_Window, which on + some servers will reduce colormap flashing. + + <P>See Fl_Gl_Window + for a list of additional values for the argument. +*/ int Fl::gl_visual(int mode, int *alist) { Fl_Gl_Choice *c = Fl_Gl_Choice::find(mode,alist); if (!c) return 0; diff --git a/src/screen_xywh.cxx b/src/screen_xywh.cxx index a6c98d304..7a36e19e7 100644 --- a/src/screen_xywh.cxx +++ b/src/screen_xywh.cxx @@ -141,14 +141,23 @@ static void screen_init() { #endif // WIN32 -// Return the number of screens... +/** + Gets the number of available screens. +*/ int Fl::screen_count() { if (!num_screens) screen_init(); return num_screens; } -// Return the screen bounding rect for the given mouse position... +/** + Gets the bounding box of a screen. The first form gets the + bounding box for the screen the mouse pointer is in. The second + form gets the bounding box for the screen that contains the + specified coordinates. The last form gets the bounding box for + the numbered screen, where n is a number from 0 to the + number of screens less 1. +*/ void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my) { if (!num_screens) screen_init(); @@ -212,7 +221,10 @@ void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my) { H = Fl::h(); } -// Return the screen bounding rect for the given screen... +/** + Returns the screen bounding rect for the given screen. + See void screen_xywh(int &x, int &y, int &w, int &h, int mx, int my) +*/ void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int n) { if (!num_screens) screen_init(); |