[whatwg] Comments on <dialog>

[Matt Falkenhagen]

On Fri, Sep 27, 2013 at 7:15 AM, Ian Hickson <ian at hixie.ch> wrote:
>
> On Mon, 26 Aug 2013, Ojan Vafai wrote:
> >
> > IMO, showModalDialog is the legacy broken API we're stuck with. Better
> > to name the new thing in a way that's self-consistent and consistent
> > with everything else (i.e. openModal).
>
> I started doing this, since several people have asked about this and it
> seems the consistency between showModalDialog()/close() seems less
> interesting to people than the consistency with "open" everywhere else.
> However, it turns out this would make the show() method clash with the
> "open" IDL attribute on <dialog>, which we want since it matches the name
> of the open="" content attribute which matches <details open>.
>
> Note that window.open() and document.open() don't really do the same as
> this method does, either. window.open() creates a new Window, or navigates
> and existing one; document.open() resets the document. dialog.show() just
> changes the dialog to be visible.
>
> Also, there's an interesting mix in other APIs. (Disclaimer: I don't know
> many of these APIs personally, so I may be misinterpreting their
> documentation wildly. I basically looked for terms like "open" and "close"
> in the docs and tried to see what the right methods were in each case. I
> only included methods for modal dialogs if there was a trivial method;
> many APIs have to be configured to make dialogs modals separately.)
>
>  Android uses show() and dismiss()
>  Closure uses setVisible()
>  Cocoa uses makeKeyAndOrderFront:, orderOut:, close, and performClose:.
>  Delphi uses Show(), ShowModal(), Hide(), and Close().
>  Ext JS uses show(), hide(), and close().
>  jQuery uses "open" and "close".
>  Gtk uses gtk_widget_show(), gtk_dialog_run(), gtk_window_close().

Gtk also has gtk_widget_hide(), see [0]

>  .NET uses Show(), ShowDialog(), Hide(), and Close().
>  Win32 uses ShowWindow() and CloseWindow().
>  X11 uses XMapWindow() and XUnmapWindow()
>
> Most of the APIs I looked at use "close". Most use "show". So I think
> we're in ok company here.

Sorry to add feedback so late. Whenever there's a post/tweet about
Chrome's <dialog>, the most common complaint from devs seems to be this
show/close naming.

I think with any naming choice there will be an inconsistency somewhere
in the whole platform API. For example, show/hide is a little weird since
dialog.hide() is different from dialog.hidden = true. But show/close are
immediately inconsistent with themselves which gives people an adverse
reaction.

I think I'd prefer, in order:
1) open()/openModal()/close() and "opened" attribute
2) show()/showModal()/hide() and "open"
3) show()/showModal()/close() and "open"

1) is nice because it's internally consistent. The downside is that
dialog.opened is inconsistent with details.open.

In the list of existing APIs above, only Win32 has only show/close. Of APIs
that have all of show/hide/close, it looks like close does something like
dispose of the object/free its memory so it can't be shown again (e.g., see
[1][2][3]) So show/hide for <dialog> seems more consistent than
show/close with these APIs.

Some additional data points:
- QT uses show(), hide(), close(), done() (close/done delete the dialog) [4]
- Dojo uses show(), hide() [5]
- Java AWT uses setVisible() (show() and hide() are deprecated, also
there is a dispose()) [6]
- Blackberry uses show(), close() [7]
- Xt uses XtPopup(), XtPopdown() [8]
- wxWindows uses Show(bool), ShowModal(), EndModal(), Close() [9]
- YUI uses show(), hide() [10]
- Bootstrap uses show(), hide() [11]
- GWT uses show(), hide() [12]

It seems existing JS frameworks mostly use show/hide, maybe because they
predate element.hidden.

[0] https://developer.gnome.org/gtk3/stable/GtkWidget.html
[1] http://www.objis.com/formationextjs/lib/extjs-4.0.0/docs/api/Ext.window.MessageBox.html
[2] http://stackoverflow.com/questions/2075405/how-to-close-non-modal-form-in-delphi
[3] http://www.dummies.com/how-to/content/opening-closing-and-hiding-forms-with-visual-basic.html
[4] http://qt-project.org/doc/qt-4.8/qwidget.html#close
[5] http://dojotoolkit.org/api/?qs=1.9/dijit/Dialog
[6] http://docs.oracle.com/javase/6/docs/api/java/awt/Dialog.html
[7] http://www.blackberry.com/developers/docs/5.0.0api/net/rim/device/api/ui/component/Dialog.html
[8] http://www.unix.com/man-page/all/3x/XtPopup/
[9] http://docs.wxwidgets.org/stable/classwx_dialog.html
[10] http://yuilibrary.com/yui/docs/api/classes/Panel.html
[11] http://getbootstrap.com/javascript/#modals
[12] http://www.gwtproject.org/javadoc/latest/com/google/gwt/user/client/ui/DialogBox.html