MODAL should not be a window state

["Dana Jansens" <danakj orodu net>]

Hello,

I'd like to bring to light a misnomer in the current EWMH spec.

The various _NET_WM_STATEs are for states that can be enabled and
disabled on a window, typically by a user:

Sticky, Maximized, Shaded, Above, Below are all things typically found
in the window's menu. Hidden, Fullscreen, Skip Taskbar/Pager, and
Demands Attention are things that are not set directly by the user,
but are for other windows to see like pagers and they also will
possibly change many times over the lifetime of a window.

Modality is the only one in this list which does not change over the
life of a window.

How the major toolkits implement modality:

QT 4.2: http://doc.trolltech.com/4.2/qdialog.html

"The most common way to display a modal dialog is to call its exec() function."

This is done before the window is mapped, and the modality will not
change before the window closes.

"An alternative is to call setModal(true) or setWindowModality(), then show()."

setModal() is called before show(), meaning that again the modality is
set before the window is mapped, not something that changes while the
window is being used.

"modal : bool - This property holds whether show() should pop up the
dialog as modal or modeless."

GTK 2.11.0: http://developer.gnome.org/doc/API/2.0/gtk/GtkDialog.html

"A 'modal' dialog (that is, one which freezes the rest of the
application from user input), can be created by calling
gtk_window_set_modal() on the dialog. Use the GTK_WINDOW() macro to
cast the widget returned from gtk_dialog_new() into a GtkWindow."

GTK allows you to set the modality pretty much at any time from what I
can see, however the expected use case is still to do it before the
window is mapped. "to cast the widget returned from gtk_dialog_new()"
is suggesting you are setting modality on a new window, not on a
window that's being used and has decided to become modal (or modeless)
based on user input.

"When using gtk_dialog_new_with_buttons() you can also pass the
GTK_DIALOG_MODAL flag to make a dialog modal."

This is setting modality on a new window, before it is mapped.

wxWidgets: http://www.wxwidgets.org/manuals/stable/wx_wxdialog.html#wxdialog

"To show a modal dialog you should use the ShowModal method while to
show a dialog modelessly you simply use Show, just as with frames."

Again, modality is selected before the window is presented to the
user, and is for dialog type windows.

Can someone think of a situation where a window would change its
modality while it is being used?

Also, it's clear from these API's that modality is expected to be used
only on DIALOG typed windows. The EMWH already reinforces this notion:
"_NET_WM_STATE_MODAL indicates that this is a modal dialog box." The
MODAL state is clearly not meant to be used on other types of windows.
According to past discussions in this forum, a DIALOG type window
should be made transient for its entire group when the TRANSIENT_FOR
property is not set. The MODAL state now specifies the same thing.

I propose that _NET_WM_STATE_MODAL should be instead changed to be
_NET_WM_WINDOW_TYPE_MODAL_DIALOG. This would not take away from the
intended functionality of modal windows, nor how they are provided in
toolkits and applications, and would provide a more consistant
interface for toolkits and window managers alike to use.

I realize that the _NET_WM_STATE_MODAL has been somewhat widely
deployed, but in terms of applications it's really in two places, Qt
and GTK. It would be okay to check if the window manager supported the
new _NET_WM_WINDOW_TYPE_MODAL_DIALOG, and fall back to
_NET_WM_STATE_MODAL, if people felt that was necessary.

I have attached the proposed changes to the spec's document.

--- wm-spec-1.4.xml	2007-02-07 01:57:04.000000000 -0500
+++ wm-spec-1.4.xml-modality	2007-03-10 16:46:11.000000000 -0500
@@ -980,6 +980,7 @@ _NET_WM_WINDOW_TYPE_MENU, ATOM
 _NET_WM_WINDOW_TYPE_UTILITY, ATOM
 _NET_WM_WINDOW_TYPE_SPLASH, ATOM
 _NET_WM_WINDOW_TYPE_DIALOG, ATOM
+_NET_WM_WINDOW_TYPE_MODAL_DIALOG, ATOM
 _NET_WM_WINDOW_TYPE_DROPDOWN_MENU, ATOM
 _NET_WM_WINDOW_TYPE_POPUP_MENU, ATOM
 _NET_WM_WINDOW_TYPE_TOOLTIP, ATOM
@@ -1021,11 +1022,20 @@ _NET_WM_WINDOW_TYPE_SPLASH indicates tha
 displayed as an application is starting up.
 	</para>
 	<para>
-_NET_WM_WINDOW_TYPE_DIALOG indicates that this is a dialog window.  If
-_NET_WM_WINDOW_TYPE is not set, then managed windows with
+_NET_WM_WINDOW_TYPE_DIALOG indicates that this is a modeless dialog window.
+If _NET_WM_WINDOW_TYPE is not set, then managed windows with
 WM_TRANSIENT_FOR set MUST be taken as this type. Override-redirect
 windows with WM_TRANSIENT_FOR, but without _NET_WM_WINDOW_TYPE must be
-taken as _NET_WM_WINDOW_TYPE_NORMAL.
+taken as _NET_WM_WINDOW_TYPE_NORMAL. If WM_TRANSIENT_FOR is not set, the window
+should be considered as transient for its window group.
+	</para>
+	<para>
+_NET_WM_WINDOW_TYPE_MODAL_DIALOG indicates that this is a modal dialog window.
+The same rules should generally be applied to this window as a
+_NET_WM_WINDOW_TYPE_DIALOG window. However, when this type is set, it
+indicates that the dialog will block input to windows it is transient for, and
+that users will need to close the modal dialog before interacting with any
+windows it is transient for.
 	</para>
       <para>
 _NET_WM_WINDOW_TYPE_DROPDOWN_MENU indicates that the
@@ -1105,7 +1115,6 @@ previous state. 
 Possible atoms are:
 		</para>
 	<programlisting><![CDATA[
-_NET_WM_STATE_MODAL, ATOM
 _NET_WM_STATE_STICKY, ATOM
 _NET_WM_STATE_MAXIMIZED_VERT, ATOM
 _NET_WM_STATE_MAXIMIZED_HORZ, ATOM
@@ -1125,12 +1134,6 @@ them from the list. These extension atom
 _NET. 
       </para>
 	<para>
-_NET_WM_STATE_MODAL indicates that this is a modal dialog box.  
-If the WM_TRANSIENT_FOR hint is set to another toplevel window, the 
-dialog is modal for that window; if WM_TRANSIENT_FOR is not set or set
-to the root window the dialog is modal for its window group.
-	</para>
-	<para>
 _NET_WM_STATE_STICKY indicates that the Window Manager SHOULD keep the
 window's position fixed on the screen, even when the virtual desktop scrolls.
 	</para>
@@ -2178,6 +2181,11 @@ OR OTHER DEALINGS IN THE SOFTWARE.  
  		<title>Changes since 1.3</title>
  		<itemizedlist>
  			<listitem><para>
+Remove _NET_WM_STATE_MODAL in favor of _NET_WM_WINDOW_TYPE_MODAL_DIALOG.
+Modality is not a state which changes over the course of a window's lifetime.
+Further, it is only meant to be applied to dialog windows.
+ 			</para></listitem>
+ 			<listitem><para>
 Added _NET_WM_MOVERESIZE_CANCEL.
 			</para></listitem>
 			<listitem><para>