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
`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
`(package private) HandlerRegistration` `resizeHandlerRegistration`

### 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

All Methods Instance Methods Concrete Methods Deprecated Methods
`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(boolean autoClosed)` 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, getAnimationType, 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, 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, unsinkEvents`

### 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`

### 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`

### Methods inherited from interface java.lang.Iterable

`forEach, spliterator`

### Field Detail

#### resizeHandlerRegistration

    HandlerRegistration resizeHandlerRegistration

### 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(boolean autoClosed)

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`
Parameters:
  `autoClosed` - the value that will be passed to `CloseHandler.onClose(CloseEvent)` when the popup is closed

#### 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.dom.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.dom.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`