mirrors/fltk
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Completed and corrected Fl and related Fl_Window documentation, added cross references, especially to back compatibility functions to the new ones.

Browse Source 
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6372 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
This commit is contained in:
Fabien Costantini 2008-10-04 14:15:16 +00:00
parent 0eb1ac797f
commit bfac12dbfa
5 changed files with 62 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
FL/Fl.H
View File

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

2
FL/Fl_Window.H
View File

@ -343,7 +343,7 @@ public:
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.
Fl_Gl_Window derived classes.
*/
void make_current();

10
src/Fl.cxx
View File

@ -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 <I>directly</I> 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);

9
src/Fl_Window.cxx
View File

@ -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.
<P> 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_;
}

16
src/screen_xywh.cxx
View File

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