Author: AlbrechtS
Date: 2011-03-26 17:34:55 -0700 (Sat, 26 Mar 2011)
New Revision: 8538
Log:
Enhanced documentation of Fl::event_inside() to mention the restrictions
WRT subwindows and when using the window itself as the widget argument.
Modified:
branches/branch-1.3/src/Fl.cxx
Modified: branches/branch-1.3/src/Fl.cxx
===================================================================
--- branches/branch-1.3/src/Fl.cxx 2011-03-26 21:56:24 UTC (rev 8537)
+++ branches/branch-1.3/src/Fl.cxx 2011-03-27 00:34:55 UTC (rev 8538)
@@ -149,12 +149,19 @@
}
-/**
- 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.
+/** Returns whether or not the mouse event is inside the given rectangle.
+
+ Returns non-zero if the current Fl::event_x() and Fl::event_y()
+ put it inside the given arbitrary bounding box.
+
+ You should always call this rather than doing your own comparison
+ so you are consistent about edge effects.
+
+ To find out, whether the event is inside a child widget of the
+ current window, you can use Fl::event_inside(const Fl_Widget *).
+
+ \param[in] xx,yy,ww,hh bounding box
+ \return non-zero, if mouse event is inside
*/
int Fl::event_inside(int xx,int yy,int ww,int hh) /*const*/ {
int mx = e_x - xx;
@@ -162,11 +169,32 @@
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.
+/** Returns whether or not the mouse event is inside a given child widget.
+
+ Returns non-zero if the current Fl::event_x() and Fl::event_y()
+ put it inside the given child widget's bounding box.
+
+ This method can only be used to check whether the mouse event is
+ inside a \b child widget of the window that handles the event, and
+ there must not be an intermediate subwindow (i.e. the widget must
+ not be inside a subwindow of the current window). However, it is
+ valid if the widget is inside a nested Fl_Group.
+
+ You must not use it with the window itself as the \p o argument
+ in a window's handle() method.
+
+ \note The mentioned restrictions are necessary, because this method
+ does not transform coordinates of child widgets, and thus the given
+ widget \p o must be within the \e same window that is handling the
+ current event. Otherwise the results are undefined.
+
+ You should always call this rather than doing your own comparison
+ so you are consistent about edge effects.
+
+ \see Fl::event_inside(int, int, int, int)
+
+ \param[in] o child widget to be tested
+ \return non-zero, if mouse event is inside the widget
*/
int Fl::event_inside(const Fl_Widget *o) /*const*/ {
int mx = e_x - o->x();
_______________________________________________
fltk-commit mailing list
[email protected]
http://lists.easysw.com/mailman/listinfo/fltk-commit
