com.google.gwt.user.client.ui

## Class DialogBox

- java.lang.Object
- - com.google.gwt.user.client.ui.UIObject
  - - com.google.gwt.user.client.ui.Widget
    - - com.google.gwt.user.client.ui.Panel
      - - com.google.gwt.user.client.ui.SimplePanel
        - - com.google.gwt.user.client.ui.PopupPanel
          - - com.google.gwt.user.client.ui.DecoratedPopupPanel
            - - com.google.gwt.user.client.ui.DialogBox

- All Implemented Interfaces:
    HasAttachHandlers, HasCloseHandlers<PopupPanel>, HasHandlers, HasSafeHtml, EventListener, EventPreview, AcceptsOneWidget, HasAnimation, HasHTML, HasOneWidget, HasText, HasVisibility, HasWidgets, HasWidgets.ForIsWidget, IsWidget, MouseListener, SourcesPopupEvents, java.lang.Iterable<Widget>

      public class DialogBox
      extends DecoratedPopupPanel
      implements HasHTML, HasSafeHtml, MouseListener

  A form of popup that has a caption area at the top and can be dragged by the user. Unlike a PopupPanel, calls to `PopupPanel.setWidth(String)` and `PopupPanel.setHeight(String)` will set the width and height of the dialog box itself, even if a widget has not been added as yet.

  ### CSS Style Rules

  - .gwt-DialogBox { the outside of the dialog }
  - .gwt-DialogBox .Caption { the caption }
  - .gwt-DialogBox .dialogContent { the wrapper around the content }
  - .gwt-DialogBox .dialogTopLeft { the top left cell }
  - .gwt-DialogBox .dialogTopLeftInner { the inner element of the cell }
  - .gwt-DialogBox .dialogTopCenter { the top center cell, where the caption is located }
  - .gwt-DialogBox .dialogTopCenterInner { the inner element of the cell }
  - .gwt-DialogBox .dialogTopRight { the top right cell }
  - .gwt-DialogBox .dialogTopRightInner { the inner element of the cell }
  - .gwt-DialogBox .dialogMiddleLeft { the middle left cell }
  - .gwt-DialogBox .dialogMiddleLeftInner { the inner element of the cell }
  - .gwt-DialogBox .dialogMiddleCenter { the middle center cell, where the content is located }
  - .gwt-DialogBox .dialogMiddleCenterInner { the inner element of the cell }
  - .gwt-DialogBox .dialogMiddleRight { the middle right cell }
  - .gwt-DialogBox .dialogMiddleRightInner { the inner element of the cell }
  - .gwt-DialogBox .dialogBottomLeft { the bottom left cell }
  - .gwt-DialogBox .dialogBottomLeftInner { the inner element of the cell }
  - .gwt-DialogBox .dialogBottomCenter { the bottom center cell }
  - .gwt-DialogBox .dialogBottomCenterInner { the inner element of the cell }
  - .gwt-DialogBox .dialogBottomRight { the bottom right cell }
  - .gwt-DialogBox .dialogBottomRightInner { the inner element of the cell }

  ### Example

  >     public class DialogBoxExample implements EntryPoint, ClickHandler {

  >       private static class MyDialog extends DialogBox {

  >         public MyDialog() {
  >           // Set the dialog box's caption.
  >           setText("My First Dialog");

  >           // Enable animation.
  >           setAnimationEnabled(true);

  >           // Enable glass background.
  >           setGlassEnabled(true);

  >           // DialogBox is a SimplePanel, so you have to set its widget property to
  >           // whatever you want its contents to be.
  >           Button ok = new Button("OK");
  >           ok.addClickHandler(new ClickHandler() {
  >             public void onClick(ClickEvent event) {
  >               MyDialog.this.hide();
  >             }
  >           });
  >           setWidget(ok);
  >         }
  >       }

  >       public void onModuleLoad() {
  >         Button b = new Button("Click me");
  >         b.addClickHandler(this);

  >         RootPanel.get().add(b);
  >       }

  >       public void onClick(ClickEvent event) {
  >         // Instantiate the dialog box and show it.
  >         new MyDialog().show();
  >       }
  >     }

  ### Use in UiBinder Templates

  DialogBox elements in `UiBinder` templates can have one widget child and one <g:caption> child. (Note the lower case "c", meant to signal that the caption is not a runtime object, and so cannot have a `ui:field` attribute.) The body of the caption can be html.

  For example:

       <g:DialogBox autoHide="true" modal="true">
         <g:caption><b>Caption text</b></g:caption>
         <g:HTMLPanel>
           Body text
           <g:Button ui:field='cancelButton'>Cancel</g:Button>
           <g:Button ui:field='okButton'>Okay</g:Button>
         </g:HTMLPanel>
       </g:DialogBox>

  You may also create your own header caption. The caption must implement `DialogBox.Caption`.

  For example:

       <g:DialogBox autoHide="true" modal="true">
         <-- foo is your prefix and Bar is a class that implements DialogBox.Caption-->
         <g:customCaption><foo:Bar/></g:customCaption>
         <g:HTMLPanel>
           Body text
           <g:Button ui:field='cancelButton'>Cancel</g:Button>
           <g:Button ui:field='okButton'>Okay</g:Button>
         </g:HTMLPanel>
       </g:DialogBox>

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static interface` | `DialogBox.Caption` Set of characteristic interfaces supported by the `DialogBox` caption.
    `static class` | `DialogBox.CaptionImpl` Default implementation of Caption.

    - ### Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.PopupPanel

      `PopupPanel.AnimationType, PopupPanel.PositionCallback, PopupPanel.ResizeAnimation`

    - ### Nested classes/interfaces inherited from class com.google.gwt.user.client.ui.UIObject

      `UIObject.DebugIdImpl, UIObject.DebugIdImplEnabled`

    - ### Nested classes/interfaces inherited from interface com.google.gwt.user.client.ui.HasWidgets

      `HasWidgets.ForIsWidget`

  - ### Field Summary

    - ### Fields inherited from class com.google.gwt.user.client.ui.SimplePanel

      `widget`

    - ### Fields inherited from class com.google.gwt.user.client.ui.Widget

      `eventsToSink`

    - ### Fields inherited from class com.google.gwt.user.client.ui.UIObject

      `DEBUG_ID_PREFIX, MISSING_ELEMENT_ERROR, SETELEMENT_TWICE_ERROR`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `DialogBox()` Creates an empty dialog box.
    `DialogBox(boolean autoHide)` Creates an empty dialog box specifying its "auto-hide" property.
    `DialogBox(boolean autoHide, boolean modal)` Creates an empty dialog box specifying its "auto-hide" and "modal" properties.
    `DialogBox(boolean autoHide, boolean modal, DialogBox.Caption captionWidget)` Creates an empty dialog box specifying its "auto-hide", "modal" properties and an implementation a custom `DialogBox.Caption`.
    `DialogBox(DialogBox.Caption captionWidget)` Creates an empty dialog box specifying its `DialogBox.Caption`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `beginDragging(MouseDownEvent event)` Called on mouse down in the caption area, begins the dragging loop by turning on event capture.
    `protected void` | `continueDragging(MouseMoveEvent event)` Called on mouse move in the caption area, continues dragging if it was started by `beginDragging(com.google.gwt.event.dom.client.MouseDownEvent)`.
    `protected void` | `doAttachChildren()` If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call `Widget.onAttach()` for each of its child widgets.
    `protected void` | `doDetachChildren()` If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call `Widget.onDetach()` for each of its child widgets.
    `protected void` | `endDragging(MouseUpEvent event)` Called on mouse up in the caption area, ends dragging by ending event capture.
    `DialogBox.Caption` | `getCaption()` Provides access to the dialog's caption.
    `java.lang.String` | `getHTML()` Gets this object's contents as HTML.
    `java.lang.String` | `getText()` Gets this object's text.
    `void` | `hide()` Hides the popup and detaches it from the page.
    `void` | `onBrowserEvent(Event event)` Fired whenever a browser event is received.
    `protected void` | `onEnsureDebugId(java.lang.String baseID)` Affected Elements: -caption = text at the top of the `DialogBox`. -content = the container around the content.
    `void` | `onMouseDown(Widget sender, int x, int y)` Deprecated. Use `beginDragging(com.google.gwt.event.dom.client.MouseDownEvent)` and `getCaption()` instead
    `void` | `onMouseEnter(Widget sender)` Deprecated. Use `HasMouseOverHandlers.addMouseOverHandler(com.google.gwt.event.dom.client.MouseOverHandler)` instead
    `void` | `onMouseLeave(Widget sender)` Deprecated. Use `HasMouseOutHandlers.addMouseOutHandler(com.google.gwt.event.dom.client.MouseOutHandler)` instead
    `void` | `onMouseMove(Widget sender, int x, int y)` Deprecated. Use `continueDragging(com.google.gwt.event.dom.client.MouseMoveEvent)` and `getCaption()` instead
    `void` | `onMouseUp(Widget sender, int x, int y)` Deprecated. Use `endDragging(com.google.gwt.event.dom.client.MouseUpEvent)` and `getCaption()` instead
    `protected void` | `onPreviewNativeEvent(Event.NativePreviewEvent event)`
    `void` | `setHTML(SafeHtml html)` Sets the html string inside the caption by calling its `setHTML(SafeHtml)` method.
    `void` | `setHTML(java.lang.String html)` Sets the html string inside the caption by calling its `setHTML(SafeHtml)` method.
    `void` | `setText(java.lang.String text)` Sets the text inside the caption by calling its `setText(String)` method.
    `void` | `show()` Shows the popup and attach it to the page.

    - ### Methods inherited from class com.google.gwt.user.client.ui.DecoratedPopupPanel

      `clear, getCellElement, getWidget, iterator, remove, setWidget`

    - ### Methods inherited from class com.google.gwt.user.client.ui.PopupPanel

      `addAutoHidePartner, addCloseHandler, addPopupListener, center, getContainerElement, getGlassElement, getGlassStyleName, getOffsetHeight, getOffsetWidth, getPopupLeft, getPopupTop, getStyleElement, getTitle, hide, isAnimationEnabled, isAutoHideEnabled, isAutoHideOnHistoryEventsEnabled, isGlassEnabled, isModal, isPreviewingAllNativeEvents, isShowing, isVisible, maybeUpdateSize, onEventPreview, onKeyDownPreview, onKeyPressPreview, onKeyUpPreview, onUnload, removeAutoHidePartner, removePopupListener, setAnimation, setAnimationEnabled, setAnimationType, setAutoHideEnabled, setAutoHideOnHistoryEventsEnabled, setGlassEnabled, setGlassStyleName, setHeight, setModal, setPopupPosition, setPopupPositionAndShow, setPreviewingAllNativeEvents, setTitle, setVisible, setWidth, showRelativeTo`

    - ### Methods inherited from class com.google.gwt.user.client.ui.SimplePanel

      `add, setWidget`

    - ### Methods inherited from class com.google.gwt.user.client.ui.Panel

      `add, adopt, adopt, disown, orphan, remove`

    - ### Methods inherited from class com.google.gwt.user.client.ui.Widget

      `addAttachHandler, addBitlessDomHandler, addDomHandler, addHandler, asWidget, asWidgetOrNull, createHandlerManager, delegateEvent, ensureHandlers, fireEvent, getHandlerCount, getHandlerManager, getLayoutData, getParent, isAttached, isOrWasAttached, onAttach, onDetach, onLoad, removeFromParent, replaceElement, setLayoutData, setParent, sinkEvents`

    - ### Methods inherited from class com.google.gwt.user.client.ui.UIObject

      `addStyleDependentName, addStyleName, ensureDebugId, ensureDebugId, ensureDebugId, getAbsoluteLeft, getAbsoluteTop, getElement, getStyleName, getStyleName, getStylePrimaryName, getStylePrimaryName, isVisible, removeStyleDependentName, removeStyleName, resolvePotentialElement, setElement, setElement, setPixelSize, setSize, setStyleDependentName, setStyleName, setStyleName, setStyleName, setStyleName, setStylePrimaryName, setStylePrimaryName, setVisible, sinkBitlessEvent, toString, unsinkEvents`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface com.google.gwt.event.shared.HasHandlers

      `fireEvent`

- - ### Constructor Detail

    - #### DialogBox

          public DialogBox()

      Creates an empty dialog box. It should not be shown until its child widget has been added using `SimplePanel.add(Widget)`.

    - #### DialogBox

          public DialogBox(boolean autoHide)

      Creates an empty dialog box specifying its "auto-hide" property. It should not be shown until its child widget has been added using `SimplePanel.add(Widget)`.
      Parameters:
        `autoHide` - `true` if the dialog should be automatically hidden when the user clicks outside of it

    - #### DialogBox

          public DialogBox(DialogBox.Caption captionWidget)

      Creates an empty dialog box specifying its `DialogBox.Caption`. It should not be shown until its child widget has been added using `SimplePanel.add(Widget)`.
      Parameters:
        `captionWidget` - the widget that is the DialogBox's header.

    - #### DialogBox

          public DialogBox(boolean autoHide,
                   boolean modal)

      Creates an empty dialog box specifying its "auto-hide" and "modal" properties. It should not be shown until its child widget has been added using `SimplePanel.add(Widget)`.
      Parameters:
        `autoHide` - `true` if the dialog should be automatically hidden when the user clicks outside of it
        `modal` - `true` if keyboard and mouse events for widgets not contained by the dialog should be ignored

    - #### DialogBox

          public DialogBox(boolean autoHide,
                   boolean modal,
                   DialogBox.Caption captionWidget)

      Creates an empty dialog box specifying its "auto-hide", "modal" properties and an implementation a custom `DialogBox.Caption`. It should not be shown until its child widget has been added using `SimplePanel.add(Widget)`.
      Parameters:
        `autoHide` - `true` if the dialog should be automatically hidden when the user clicks outside of it
        `modal` - `true` if keyboard and mouse events for widgets not contained by the dialog should be ignored
        `captionWidget` - the widget that is the DialogBox's header.

  - ### Method Detail

    - #### getCaption

          public DialogBox.Caption getCaption()

      Provides access to the dialog's caption.
      Returns:
        the logical caption for this dialog box

    - #### getHTML

          public java.lang.String getHTML()

      Description copied from interface: `HasHTML`
      Gets this object's contents as HTML.
      Specified by:
        `getHTML` in interface `HasHTML`
      Returns:
        the object's HTML

    - #### getText

          public java.lang.String getText()

      Description copied from interface: `HasText`
      Gets this object's text.
      Specified by:
        `getText` in interface `HasText`
      Returns:
        the object's text

    - #### hide

          public void hide()

      Description copied from class: `PopupPanel`
      Hides the popup and detaches it from the page. This has no effect if it is not currently showing.
      Overrides:
        `hide` in class `PopupPanel`

    - #### onBrowserEvent

          public void onBrowserEvent(Event event)

      Description copied from interface: `EventListener`
      Fired whenever a browser event is received.
      Specified by:
        `onBrowserEvent` in interface `EventListener`
      Overrides:
        `onBrowserEvent` in class `Widget`
      Parameters:
        `event` - the event received

    - #### onMouseDown

          @Deprecated
          public void onMouseDown(Widget sender,
                                    int x,
                                    int y)

      Deprecated. Use `beginDragging(com.google.gwt.event.dom.client.MouseDownEvent)` and `getCaption()` instead
      Description copied from interface: `MouseListener`
      Fired when the user depresses the mouse button over a widget.
      Specified by:
        `onMouseDown` in interface `MouseListener`
      Parameters:
        `sender` - the widget sending the event
        `x` - the x coordinate of the mouse
        `y` - the y coordinate of the mouse

    - #### onMouseEnter

          @Deprecated
          public void onMouseEnter(Widget sender)

      Deprecated. Use `HasMouseOverHandlers.addMouseOverHandler(com.google.gwt.event.dom.client.MouseOverHandler)` instead
      Description copied from interface: `MouseListener`
      Fired when the mouse enters a widget's area.
      Specified by:
        `onMouseEnter` in interface `MouseListener`
      Parameters:
        `sender` - the widget sending the event

    - #### onMouseLeave

          @Deprecated
          public void onMouseLeave(Widget sender)

      Deprecated. Use `HasMouseOutHandlers.addMouseOutHandler(com.google.gwt.event.dom.client.MouseOutHandler)` instead
      Description copied from interface: `MouseListener`
      Fired when the mouse leaves a widget's area.
      Specified by:
        `onMouseLeave` in interface `MouseListener`
      Parameters:
        `sender` - the widget sending the event

    - #### onMouseMove

          @Deprecated
          public void onMouseMove(Widget sender,
                                    int x,
                                    int y)

      Deprecated. Use `continueDragging(com.google.gwt.event.dom.client.MouseMoveEvent)` and `getCaption()` instead
      Description copied from interface: `MouseListener`
      Fired when the user moves the mouse over a widget.
      Specified by:
        `onMouseMove` in interface `MouseListener`
      Parameters:
        `sender` - the widget sending the event
        `x` - the x coordinate of the mouse
        `y` - the y coordinate of the mouse

    - #### onMouseUp

          @Deprecated
          public void onMouseUp(Widget sender,
                                  int x,
                                  int y)

      Deprecated. Use `endDragging(com.google.gwt.event.dom.client.MouseUpEvent)` and `getCaption()` instead
      Description copied from interface: `MouseListener`
      Fired when the user releases the mouse button over a widget.
      Specified by:
        `onMouseUp` in interface `MouseListener`
      Parameters:
        `sender` - the widget sending the event
        `x` - the x coordinate of the mouse
        `y` - the y coordinate of the mouse

    - #### setHTML

          public void setHTML(SafeHtml html)

      Sets the html string inside the caption by calling its `setHTML(SafeHtml)` method. Use `DecoratedPopupPanel.setWidget(Widget)` to set the contents inside the `DialogBox`.
      Specified by:
        `setHTML` in interface `HasSafeHtml`
      Parameters:
        `html` - the object's new HTML

    - #### setHTML

          public void setHTML(java.lang.String html)

      Sets the html string inside the caption by calling its `setHTML(SafeHtml)` method. Only known safe HTML should be inserted in here. Use `DecoratedPopupPanel.setWidget(Widget)` to set the contents inside the `DialogBox`.
      Specified by:
        `setHTML` in interface `HasHTML`
      Parameters:
        `html` - the object's new HTML

    - #### setText

          public void setText(java.lang.String text)

      Sets the text inside the caption by calling its `setText(String)` method. Use `DecoratedPopupPanel.setWidget(Widget)` to set the contents inside the `DialogBox`.
      Specified by:
        `setText` in interface `HasText`
      Parameters:
        `text` - the object's new text

    - #### show

          public void show()

      Description copied from class: `PopupPanel`
      Shows the popup and attach it to the page. It must have a child widget before this method is called.
      Overrides:
        `show` in class `PopupPanel`

    - #### beginDragging

          protected void beginDragging(MouseDownEvent event)

      Called on mouse down in the caption area, begins the dragging loop by turning on event capture.
      Parameters:
        `event` - the mouse down event that triggered dragging
      See Also:
        `DOM.setCapture(com.google.gwt.user.client.Element)`, `continueDragging(com.google.gwt.event.dom.client.MouseMoveEvent)`

    - #### continueDragging

          protected void continueDragging(MouseMoveEvent event)

      Called on mouse move in the caption area, continues dragging if it was started by `beginDragging(com.google.gwt.event.dom.client.MouseDownEvent)`.
      Parameters:
        `event` - the mouse move event that continues dragging
      See Also:
        `beginDragging(com.google.gwt.event.dom.client.MouseDownEvent)`, `endDragging(com.google.gwt.event.dom.client.MouseUpEvent)`

    - #### doAttachChildren

          protected void doAttachChildren()

      Description copied from class: `Widget`
      If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call `Widget.onAttach()` for each of its child widgets.
      Overrides:
        `doAttachChildren` in class `DecoratedPopupPanel`
      See Also:
        `Widget.onAttach()`

    - #### doDetachChildren

          protected void doDetachChildren()

      Description copied from class: `Widget`
      If a widget contains one or more child widgets that are not in the logical widget hierarchy (the child is physically connected only on the DOM level), it must override this method and call `Widget.onDetach()` for each of its child widgets.
      Overrides:
        `doDetachChildren` in class `DecoratedPopupPanel`
      See Also:
        `Widget.onDetach()`

    - #### endDragging

          protected void endDragging(MouseUpEvent event)

      Called on mouse up in the caption area, ends dragging by ending event capture.
      Parameters:
        `event` - the mouse up event that ended dragging
      See Also:
        `DOM.releaseCapture(com.google.gwt.user.client.Element)`, `beginDragging(com.google.gwt.event.dom.client.MouseDownEvent)`, `endDragging(com.google.gwt.event.dom.client.MouseUpEvent)`

    - #### onEnsureDebugId

          protected void onEnsureDebugId(java.lang.String baseID)

      Affected Elements:
      - -caption = text at the top of the `DialogBox`.
      - -content = the container around the content.
      Overrides:
        `onEnsureDebugId` in class `UIObject`
      Parameters:
        `baseID` - the base ID used by the main element
      See Also:
        `UIObject.onEnsureDebugId(String)`

    - #### onPreviewNativeEvent

          protected void onPreviewNativeEvent(Event.NativePreviewEvent event)

      Overrides:
        `onPreviewNativeEvent` in class `PopupPanel`