Solve STR#2948: Add new method Fl_Widget::top_window() to return the widget's top-level window.

Docs for existing Fl_Widget::window() revised to clarify the difference between these two methods.

Docs for window() also moved from .H -> .cxx as per CMP (docs should be where code implementation is).



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@9871 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 21 insertions, 0 deletions

diff --git a/src/Fl_Window.cxx b/src/Fl_Window.cxx
index ffda05a1a..f76615925 100644
--- a/src/Fl_Window.cxx
+++ b/src/Fl_Window.cxx
@@ -80,11 +80,32 @@ Fl_Window::Fl_Window(int W, int H, const char *l)
   clear_visible();
 }
 
+/** Returns a pointer to the nearest parent window up the widget hierarchy.
+    This will return sub-windows if there are any, or the parent window if there's no sub-windows.
+    If this widget IS the top-level window, NULL is returned.
+    \retval  NULL if no window is associated with this widget.
+    \note for an Fl_Window widget, this returns its <I>parent</I> window 
+          (if any), not <I>this</I> window.
+    \see top_window()
+*/
 Fl_Window *Fl_Widget::window() const {
   for (Fl_Widget *o = parent(); o; o = o->parent())
     if (o->type() >= FL_WINDOW) return (Fl_Window*)o;
   return 0;
 }
+
+/** Returns a pointer to the top-level window for the widget.
+    In other words, the 'window manager window' that contains this widget.
+    This method differs from window() in that it won't return sub-windows (if there are any).
+    \returns the top-level window, or NULL if no top-level window is associated with this widget.
+    \see window()
+*/
+Fl_Window *Fl_Widget::top_window() const {
+  const Fl_Widget *w = this;
+  while (w->parent()) { w = w->parent(); }		// walk up the widget hierarchy to top-level item
+  return const_cast<Fl_Widget*>(w)->as_window();	// return if window, or NULL if not
+}
+
 /** Gets the x position of the window on the screen */
 int Fl_Window::x_root() const {
   Fl_Window *p = window();