From bfac12dbfad45c400fc77fedb0dbeca315b0960f Mon Sep 17 00:00:00 2001 From: Fabien Costantini Date: Sat, 4 Oct 2008 14:15:16 +0000 Subject: [PATCH] Completed and corrected Fl and related Fl_Window documentation, added cross references, especially to back compatibility functions to the new ones. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6372 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Fl.H | 83 ++++++++++++++++++++++++--------------------- FL/Fl_Window.H | 2 +- src/Fl.cxx | 10 +++--- src/Fl_Window.cxx | 9 ++--- src/screen_xywh.cxx | 16 ++++----- 5 files changed, 62 insertions(+), 58 deletions(-) diff --git a/FL/Fl.H b/FL/Fl.H index 7d23b9d13..d9413a8ae 100644 --- a/FL/Fl.H +++ b/FL/Fl.H @@ -388,18 +388,20 @@ public: */ 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 + Returns non zero if we had a double click event. + \retval Non-zero if the most recent FL_PUSH or FL_KEYBOARD was a "double click". + \retval N-1 for N clicks. + A double click is counted if the same button is pressed again while event_is_click() is true. -

The second form directly sets the number returned by - Fl::event_clicks(). This can be used to set it to zero so that - later code does not think an item was double-clicked. - */ + */ static int event_clicks() {return e_clicks;} /** - See int event_clicks() + Manually 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. + \param[in] i correspond to no double-click if 0, i+1 mouse clicks otherwise + \see int event_clicks() */ static void event_clicks(int i) {e_clicks = i;} /** @@ -418,8 +420,10 @@ public: */ 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. + Gets which particular mouse button caused the current event. + This returns garbage if the most recent event was not a FL_PUSH or FL_RELEASE event. + \retval FL_LEFT_MOUSE \retval FL_MIDDLE_MOUSE \retval FL_RIGHT_MOUSE. + \see Fl::event_buttons() */ static int event_button() {return e_keysym-FL_Button;} /** @@ -450,11 +454,20 @@ public: static int event_state() {return e_state;} /** See int event_state() */ static int event_state(int i) {return e_state&i;} + /** Gets which key on the keyboard was last pushed. + \retval 0 if the last event was not a key press or release. + \see int event_key(int) */ + static int event_key() {return e_keysym;} /** - Fl::event_key() returns which key on the keyboard was last - pushed. It returns zero if the last event was not a key press or release. - -

Fl::event_key(int) returns true if the given key was held + 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;} + /** + Returns true if the given \a key was held down (or pressed) during the last event. This is constant until the next event is read from the server. @@ -495,23 +508,13 @@ public:

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 event_key(int key); /** - Returns true if the given key is held down now. + Returns true if the given \a key is held down now. Under X this requires a round-trip to the server and is - much slower than Fl::event_key(int). See event_key(). + much slower than Fl::event_key(int). \see event_key(int) */ - static int get_key(int); // platform dependent + static int get_key(int key); // platform dependent /** Returns the text associated with the current FL_PASTE or FL_DND_RELEASE event. */ static const char* event_text() {return e_text;} /** @@ -536,10 +539,12 @@ public: // event destinations: static int handle(int, Fl_Window*); - /** See Fl_Widget* belowmouse(Fl_Widget*) */ + /** Gets the widget that is below the mouse. + \see belowmouse(Fl_Widget*) */ static Fl_Widget* belowmouse() {return belowmouse_;} static void belowmouse(Fl_Widget*); - /** See Fl_Widget* pushed(Fl_Widget*) */ + /** Sets the widget that is being pushed + \see Fl_Widget* pushed(Fl_Widget*) */ static Fl_Widget* pushed() {return pushed_;} static void pushed(Fl_Widget*); /** Gets the current Fl::focus() widget. \sa Fl::focus(Fl_Widget*) */ @@ -577,7 +582,8 @@ public: static int dnd(); // platform dependent // These are for back-compatibility only: - /** See Fl_Widget* selection_owner(Fl_Widget*) */ + /** back-compatibility only: Gets the widget owning the current selection + \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); @@ -696,13 +702,14 @@ public: static int draw_box_active(); // back compatibility: - /** for back compatibility. sets the (*fatal)() callback. */ /** \addtogroup fl_windows @{ */ + /** For back compatibility, sets the void Fl::fatal handler 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. */ + /** For back compatibility, sets the Fl::atclose handler callback. You + can now simply change the callback for the window instead \see Fl_Window::callback(Fl_Callback*) */ static void set_atclose(void (*f)(Fl_Window*,void*)) {atclose = f;} /** @} */ @@ -715,16 +722,16 @@ public: /** 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 + Returns the mouse buttons state bits; if non-zero, then at least one + button is pressed now. 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. + caused an FL_RELEASE event, you can use Fl::event_button() instead. + \return a bit mask value like { [FL_BUTTON1] | [FL_BUTTON2] | [FL_BUTTON3] } */ static int event_buttons() {return e_state&0x7f000000;} /** - Returns non-zero if button 1 is currently held down. + Returns non-zero if mouse button 1 is currently held down. For more details, see Fl::event_buttons(). */ static int event_button1() {return e_state&FL_BUTTON1;} diff --git a/FL/Fl_Window.H b/FL/Fl_Window.H index 19284d551..b5d5b8f1f 100644 --- a/FL/Fl_Window.H +++ b/FL/Fl_Window.H @@ -343,7 +343,7 @@ public: draws a slow graphic. Danger: incremental update is very hard to debug and maintain!

This method only works for the Fl_Window and - Fl_Gl_Window classes. + Fl_Gl_Window derived classes. */ void make_current(); diff --git a/src/Fl.cxx b/src/Fl.cxx index 5006ea143..050abe510 100644 --- a/src/Fl.cxx +++ b/src/Fl.cxx @@ -754,7 +754,7 @@ 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 + Sets 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 @@ -782,7 +782,7 @@ void Fl::belowmouse(Fl_Widget *o) { } /** - Get or set the widget that is being pushed. FL_DRAG or + Sets the widget that is being pushed. FL_DRAG or FL_RELEASE (and any more FL_PUSH) events will be sent to this widget. @@ -1291,8 +1291,7 @@ int Fl_Window::handle(int ev) //////////////////////////////////////////////////////////////// // Back compatibility cut & paste functions for fltk 1.1 only: -/** - The single-argument selection_owner(x) call can be used to +/** Back-compatibility only: The single-argument 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 @@ -1318,7 +1317,7 @@ void Fl::selection(Fl_Widget &owner, const char* text, int len) { Fl::copy(text, len, 0); } -/** +/** Backward compatibility only: 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 directly by this, or for @@ -1326,6 +1325,7 @@ void Fl::selection(Fl_Widget &owner, const char* text, int len) { 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. + \see Fl::paste(Fl_Widget &receiver, int clipboard) */ void Fl::paste(Fl_Widget &receiver) { Fl::paste(receiver, 0); diff --git a/src/Fl_Window.cxx b/src/Fl_Window.cxx index 32459d367..70b9c7f47 100644 --- a/src/Fl_Window.cxx +++ b/src/Fl_Window.cxx @@ -168,17 +168,14 @@ void Fl::default_atclose(Fl_Window* window, void* v) { window->hide(); Fl_Widget::default_callback(window, v); // put on Fl::read_queue() } - +/** Back compatibility: default window callback handler \see Fl::set_atclose() */ void (*Fl::atclose)(Fl_Window*, void*) = default_atclose; -/** - Sets the default callback v for win to call on close event. -

For back compatibility only. -*/ +/** Back compatibility: Sets the default callback v for win to call on close event */ void Fl_Window::default_callback(Fl_Window* win, void* v) { Fl::atclose(win, v); } -/** Returns the last window that was made current. */ +/** Returns the last window that was made current. \see Fl_Window::make_current() */ Fl_Window *Fl_Window::current() { return current_; } diff --git a/src/screen_xywh.cxx b/src/screen_xywh.cxx index bd31be0fd..529e74c4b 100644 --- a/src/screen_xywh.cxx +++ b/src/screen_xywh.cxx @@ -151,12 +151,10 @@ int Fl::screen_count() { } /** - 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. + Gets the bounding box of a screen + where the mouse pointer is in. + \param[out] X,Y,W,H the corresponding screen bounding box + \param[in] mx, my the mouse absolute screen position */ void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my) { if (!num_screens) screen_init(); @@ -222,8 +220,10 @@ void Fl::screen_xywh(int &X, int &Y, int &W, int &H, int mx, int my) { } /** - 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) + Gets the screen bounding rect for the given screen. + \param[out] X,Y,W,H the corresponding screen bounding box + \param[in] n the screen number (0 to Fl::screen_count() - 1) + \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();