Add method Fl_Window::clear_modal_states(),

addresses STR #3123



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

CHANGES

@@ -70,6 +70,8 @@ CHANGES IN FLTK 1.3.3					RELEASED: Oct XX 2014
 	- Improved Fl_Widget::when() handling in Fl_Tabs (STR #2939).
 	- Improved support for more recent compilers (clang and gcc) that
 	  issue more warnings, and fixed some 32-/64-bit compilation issues.
+	- Add method Fl_Window::clear_modal_states() to make it possible to
+	  remove the modal or non-modal state from a window (STR #3123).
 	- New portable sleep methods Fl::sleep(), Fl::msleep(), Fl::usleep().
 
 	Bug fixes

FL/Fl_Window.H

@@ -299,6 +299,45 @@ public:
   /**  Returns true if this window is modal or non-modal. */
   unsigned int non_modal() const {return flags() & (NON_MODAL|MODAL);}
 
+  /**
+    Clears the "modal" flags and converts a "modal" or "non-modal"
+    window back into a "normal" window.
+
+    Note that there are <I>three</I> states for a window: modal,
+    non-modal, and normal.
+
+    You can not change the "modality" of a window whilst
+    it is shown, so it is necessary to first hide() the window,
+    change its "modality" as required, then re-show the window
+    for the new state to take effect.
+
+    This method can also be used to change a "modal" window into a
+    "non-modal" one. On several supported platforms, the "modal" state
+    over-rides the "non-modal" state, so the "modal" state must be
+    cleared before the window can be set into the "non-modal"
+    state.
+    In general, the following sequence should work:
+
+    \code
+    win->hide();
+    win->clear_modal_states();
+    //Set win to new state as desired, or leave "normal", e.g...
+    win->set_non_modal();
+    win->show();
+    \endcode
+
+    \note Under some window managers, the sequence of hiding the
+    window and changing its modality will often cause it to be
+    re-displayed at a different position when it is subsequently
+    shown. This is an irritating feature but appears to be
+    unavoidable at present.
+    As a result we would advise to use this method only when
+    absolutely necessary.
+
+    \see void set_modal(), void set_non_modal()
+  */
+  void clear_modal_states() {clear_flag(NON_MODAL | MODAL);}
+
   /**
     Marks the window as a menu window.