Class sap.m.DialogModule: sap/m/Dialog

extends Control
implements PopupInterface
known direct subclasses: P13nDialog, TransportDialog

A popup that interrupts the current processing and prompts the user for an action or an input, in a modal mode.

Overview

The Dialog control is used to prompt the user for an action or a confirmation. It interrupts the current app processing as it is the only focused UI element and the main screen is dimmed/blocked. The content of the dialog is fully customizable.

Structure

A dialog consists of a title, optional subtitle, content area and a footer for action buttons. The dialog is usually displayed at the center of the screen. Its size and position can be changed by the user. To enable this, you need to set the properties resizable and draggable accordingly.

There are other specialized types of dialogs:

  • Personalization dialog - used for personalizing sorting, filtering and grouping in tables
  • Select dialog - used to select one or more items from a comprehensive list
  • Table select dialog - used to make a selection from a comprehensive table containing multiple attributes or values
  • Value help dialog - used to help the user find and select single and multiple values
  • View settings dialog - used to sort, filter, or group data within a (master) list or a table
  • Busy dialog - used to block the screen and inform the user about an ongoing operation

Usage

When to use:

  • You want to display a system message.
  • You want to interrupt the user’s action.
  • You want to show a message with a short and a long description.

When not to use:

  • You just want to confirm a successful action.

Responsive Behavior

  • If the stretch property is set to true, the dialog displays on full screen.
  • If the contentWidth and/or contentHeight properties are set, the dialog will try to fill those sizes.
  • If there is no specific sizing, the dialog will try to adjust its size to its content.

Smartphones

If the dialog has one or two actions they will cover the entire footer. If there are more actions, they will overflow.

Tablets

The action buttons in the toolbar are right-aligned. Use cozy mode on tablet devices.

Desktop

The action buttons in the toolbar are right-aligned. Use compact mode on desktop.

Constructor Summary
new sap.m.Dialog(sId?, mSettings?)Constructor for a new Dialog.
Event Summary
afterClose(oControlEvent)This event will be fired after the dialog is closed.
afterOpen(oControlEvent)This event will be fired after the dialog is opened.
beforeClose(oControlEvent)This event will be fired before the dialog is closed.
beforeOpen(oControlEvent)This event will be fired before the dialog is opened.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.Dialog.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.Dialog with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.Dialog.getMetadata()Returns a metadata object for class sap.m.Dialog.
_getAnyHeader()Returns the custom header instance when the customHeader aggregation is set.
addAriaDescribedBy(vAriaDescribedBy)Adds some ariaDescribedBy into the association ariaDescribedBy.
addAriaLabelledBy(vAriaLabelledBy)Adds some ariaLabelledBy into the association ariaLabelledBy.
addButton(oButton)Adds some button to the aggregation buttons.
addContent(oContent)Adds some content to the aggregation content.
attachAfterClose(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the afterClose event of this sap.m.Dialog.
attachAfterOpen(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the afterOpen event of this sap.m.Dialog.
attachBeforeClose(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the beforeClose event of this sap.m.Dialog.
attachBeforeOpen(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the beforeOpen event of this sap.m.Dialog.
close()Close the dialog.
destroyBeginButton()Destroys the beginButton in the aggregation beginButton.
destroyButtons()Destroys all the buttons in the aggregation buttons.
destroyContent()Destroys all the content in the aggregation content.
destroyCustomHeader()Destroys the customHeader in the aggregation customHeader.
destroyEndButton()Destroys the endButton in the aggregation endButton.
destroySubHeader()Destroys the subHeader in the aggregation subHeader.
detachAfterClose(fnFunction, oListener)Detaches event handler fnFunction from the afterClose event of this sap.m.Dialog.
detachAfterOpen(fnFunction, oListener)Detaches event handler fnFunction from the afterOpen event of this sap.m.Dialog.
detachBeforeClose(fnFunction, oListener)Detaches event handler fnFunction from the beforeClose event of this sap.m.Dialog.
detachBeforeOpen(fnFunction, oListener)Detaches event handler fnFunction from the beforeOpen event of this sap.m.Dialog.
fireAfterClose(mParameters?)Fires event afterClose to attached listeners.
fireAfterOpen(mParameters?)Fires event afterOpen to attached listeners.
fireBeforeClose(mParameters?)Fires event beforeClose to attached listeners.
fireBeforeOpen(mParameters?)Fires event beforeOpen to attached listeners.
getAriaDescribedBy()Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
getAriaLabelledBy()Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
getBeginButton()Gets content of aggregation beginButton.
getButtons()Gets content of aggregation buttons.
getContent()Gets content of aggregation content.
getContentHeight()Gets current value of property contentHeight.
getContentWidth()Gets current value of property contentWidth.
getCustomHeader()Gets content of aggregation customHeader.
getDraggable()Gets current value of property draggable.
getEndButton()Gets content of aggregation endButton.
getEscapeHandler()Gets current value of property escapeHandler.
getHorizontalScrolling()Gets current value of property horizontalScrolling.
getIcon()Gets current value of property icon.
getInitialFocus()ID of the element which is the current target of the association initialFocus, or null.
getResizable()Gets current value of property resizable.
getShowHeader()Gets current value of property showHeader.
getState()Gets current value of property state.
getStretch()Gets current value of property stretch.
getSubHeader()Gets content of aggregation subHeader.
getTitle()Gets current value of property title.
getType()Gets current value of property type.
getVerticalScrolling()Gets current value of property verticalScrolling.
indexOfButton(oButton)Checks for the provided sap.m.Button in the aggregation buttons.
indexOfContent(oContent)Checks for the provided sap.ui.core.Control in the aggregation content.
insertButton(oButton, iIndex)Inserts a button into the aggregation buttons.
insertContent(oContent, iIndex)Inserts a content into the aggregation content.
isOpen()The method checks if the Dialog is open.
open()Open the dialog.
removeAllAriaDescribedBy()Removes all the controls in the association named ariaDescribedBy.
removeAllAriaLabelledBy()Removes all the controls in the association named ariaLabelledBy.
removeAllButtons()Removes all the controls from the aggregation buttons.
removeAllContent()Removes all the controls from the aggregation content.
removeAriaDescribedBy(vAriaDescribedBy)Removes an ariaDescribedBy from the association named ariaDescribedBy.
removeAriaLabelledBy(vAriaLabelledBy)Removes an ariaLabelledBy from the association named ariaLabelledBy.
removeButton(vButton)Removes a button from the aggregation buttons.
removeContent(vContent)Removes a content from the aggregation content.
setBeginButton(oBeginButton)Sets the aggregated beginButton.
setContentHeight(sContentHeight)Sets a new value for property contentHeight.
setContentWidth(sContentWidth)Sets a new value for property contentWidth.
setCustomHeader(oCustomHeader)Sets the aggregated customHeader.
setDraggable(bDraggable)Sets a new value for property draggable.
setEndButton(oEndButton)Sets the aggregated endButton.
setEscapeHandler(oEscapeHandler)Sets a new value for property escapeHandler.
setHorizontalScrolling(bHorizontalScrolling)Sets a new value for property horizontalScrolling.
setIcon(sIcon)Sets a new value for property icon.
setInitialFocus(oInitialFocus)Sets the associated initialFocus.
setResizable(bResizable)Sets a new value for property resizable.
setShowHeader(bShowHeader)Sets a new value for property showHeader.
setState(sState)Sets a new value for property state.
setStretch(bStretch)Sets a new value for property stretch.
setSubHeader(oSubHeader)Sets the aggregated subHeader.
setTitle(sTitle)Sets a new value for property title.
setType(sType)Sets a new value for property type.
setVerticalScrolling(bVerticalScrolling)Sets a new value for property verticalScrolling.
getLeftButton()ID of the element which is the current target of the association leftButton, or null.
getRightButton()ID of the element which is the current target of the association rightButton, or null.
getStretchOnPhone()Gets current value of property stretchOnPhone.
setLeftButton(oLeftButton)Sets the associated leftButton.
setRightButton(oRightButton)Sets the associated rightButton.
setStretchOnPhone(bStretchOnPhone)Sets a new value for property stretchOnPhone.
Constructor Detail
new sap.m.Dialog(sId?, mSettings?)

Constructor for a new Dialog.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject for a general description of the syntax of the settings object.

The supported settings are:

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?ID for the new control, generated automatically if no ID is given
objectmSettings?Initial settings for the new control
Event Detail
afterClose(oControlEvent)
This event will be fired after the dialog is closed.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
sap.m.ButtonoControlEvent.getParameters.originThis indicates the trigger of closing the dialog. If dialog is closed by either leftButton or rightButton, the button that closes the dialog is set to this parameter. Otherwise this parameter is set to null.
afterOpen(oControlEvent)
This event will be fired after the dialog is opened.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
beforeClose(oControlEvent)
This event will be fired before the dialog is closed.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
sap.m.ButtonoControlEvent.getParameters.originThis indicates the trigger of closing the dialog. If dialog is closed by either leftButton or rightButton, the button that closes the dialog is set to this parameter. Otherwise this parameter is set to null.
beforeOpen(oControlEvent)
This event will be fired before the dialog is opened.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
Method Detail
sap.m.Dialog.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.m.Dialog with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.Dialog.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.Dialog.
Returns:
sap.ui.base.MetadataMetadata object describing this class
_getAnyHeader()
Returns the custom header instance when the customHeader aggregation is set. Otherwise it returns the internal managed header instance. This method can be called within composite controls which use sap.m.Dialog inside.
addAriaDescribedBy(vAriaDescribedBy): sap.m.Dialog
Adds some ariaDescribedBy into the association ariaDescribedBy.
Parameters:
sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedBythe ariaDescribedBy to add; if empty, nothing is inserted
Returns:
sap.m.DialogReference to this in order to allow method chaining
addAriaLabelledBy(vAriaLabelledBy): sap.m.Dialog
Adds some ariaLabelledBy into the association ariaLabelledBy.
Parameters:
sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledBythe ariaLabelledBy to add; if empty, nothing is inserted
Returns:
sap.m.DialogReference to this in order to allow method chaining
addButton(oButton): sap.m.Dialog
Adds some button to the aggregation buttons.
Parameters:
sap.m.ButtonoButtonthe button to add; if empty, nothing is inserted
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.21.1
addContent(oContent): sap.m.Dialog
Adds some content to the aggregation content.
Parameters:
sap.ui.core.ControloContentthe content to add; if empty, nothing is inserted
Returns:
sap.m.DialogReference to this in order to allow method chaining
attachAfterClose(oData?, fnFunction, oListener?): sap.m.Dialog

Attaches event handler fnFunction to the afterClose event of this sap.m.Dialog.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Dialog itself.

This event will be fired after the dialog is closed.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Dialog itself
Returns:
sap.m.DialogReference to this in order to allow method chaining
attachAfterOpen(oData?, fnFunction, oListener?): sap.m.Dialog

Attaches event handler fnFunction to the afterOpen event of this sap.m.Dialog.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Dialog itself.

This event will be fired after the dialog is opened.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Dialog itself
Returns:
sap.m.DialogReference to this in order to allow method chaining
attachBeforeClose(oData?, fnFunction, oListener?): sap.m.Dialog

Attaches event handler fnFunction to the beforeClose event of this sap.m.Dialog.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Dialog itself.

This event will be fired before the dialog is closed.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Dialog itself
Returns:
sap.m.DialogReference to this in order to allow method chaining
attachBeforeOpen(oData?, fnFunction, oListener?): sap.m.Dialog

Attaches event handler fnFunction to the beforeOpen event of this sap.m.Dialog.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Dialog itself.

This event will be fired before the dialog is opened.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Dialog itself
Returns:
sap.m.DialogReference to this in order to allow method chaining
close()
Close the dialog.
destroyBeginButton(): sap.m.Dialog
Destroys the beginButton in the aggregation beginButton.
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.1
destroyButtons(): sap.m.Dialog
Destroys all the buttons in the aggregation buttons.
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.21.1
destroyContent(): sap.m.Dialog
Destroys all the content in the aggregation content.
Returns:
sap.m.DialogReference to this in order to allow method chaining
destroyCustomHeader(): sap.m.Dialog
Destroys the customHeader in the aggregation customHeader.
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.1
destroyEndButton(): sap.m.Dialog
Destroys the endButton in the aggregation endButton.
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.1
destroySubHeader(): sap.m.Dialog
Destroys the subHeader in the aggregation subHeader.
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.12.2
detachAfterClose(fnFunction, oListener): sap.m.Dialog

Detaches event handler fnFunction from the afterClose event of this sap.m.Dialog.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.DialogReference to this in order to allow method chaining
detachAfterOpen(fnFunction, oListener): sap.m.Dialog

Detaches event handler fnFunction from the afterOpen event of this sap.m.Dialog.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.DialogReference to this in order to allow method chaining
detachBeforeClose(fnFunction, oListener): sap.m.Dialog

Detaches event handler fnFunction from the beforeClose event of this sap.m.Dialog.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.DialogReference to this in order to allow method chaining
detachBeforeOpen(fnFunction, oListener): sap.m.Dialog

Detaches event handler fnFunction from the beforeOpen event of this sap.m.Dialog.

The passed function and listener object must match the ones used for event registration.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.DialogReference to this in order to allow method chaining
fireAfterClose(mParameters?): sap.m.Dialog
Fires event afterClose to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
sap.m.ButtonmParameters.origin?This indicates the trigger of closing the dialog. If dialog is closed by either leftButton or rightButton, the button that closes the dialog is set to this parameter. Otherwise this parameter is set to null.
Returns:
sap.m.DialogReference to this in order to allow method chaining
fireAfterOpen(mParameters?): sap.m.Dialog
Fires event afterOpen to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.DialogReference to this in order to allow method chaining
fireBeforeClose(mParameters?): sap.m.Dialog
Fires event beforeClose to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
sap.m.ButtonmParameters.origin?This indicates the trigger of closing the dialog. If dialog is closed by either leftButton or rightButton, the button that closes the dialog is set to this parameter. Otherwise this parameter is set to null.
Returns:
sap.m.DialogReference to this in order to allow method chaining
fireBeforeOpen(mParameters?): sap.m.Dialog
Fires event beforeOpen to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.DialogReference to this in order to allow method chaining
getAriaDescribedBy(): sap.ui.core.ID[]
Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.
Returns:
sap.ui.core.ID[]
getAriaLabelledBy(): sap.ui.core.ID[]
Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.
Returns:
sap.ui.core.ID[]
getBeginButton(): sap.m.Button

Gets content of aggregation beginButton.

The button which is rendered to the left side (right side in RTL mode) of the endButton in the footer area inside the dialog. From UI5 version 1.21.1, there's a new aggregation "buttons" created with which more than 2 buttons can be added to the footer area of dialog. If the new "buttons" aggregation is set, any change made to this aggregation has no effect anymore. When runs on the phone, this button (and the endButton together when set) is (are) rendered at the center of the footer area. When runs on the other platforms, this button (and the endButton together when set) is (are) rendered at the right side (left side in RTL mode) of the footer area.

Returns:
sap.m.Button
Since:
1.15.1
getButtons(): sap.m.Button[]

Gets content of aggregation buttons.

Buttons can be added to the footer area of dialog through this aggregation. When this aggregation is set, any change to beginButton and endButton has no effect anymore. Buttons which are inside this aggregation are aligned at the right side (left side in RTL mode) of the footer instead of in the middle of the footer.

Returns:
sap.m.Button[]
Since:
1.21.1
getContent(): sap.ui.core.Control[]

Gets content of aggregation content.

The content inside the dialog.
Note: When the content of the Dialog is comprised of controls that use position: absolute, such as SplitContainer, the dialog has to have either stretch: true or contentHeight set.

Returns:
sap.ui.core.Control[]
getContentHeight(): sap.ui.core.CSSSize

Gets current value of property contentHeight.

Preferred height of content in Dialog. If the preferred height is bigger than the available space on screen, it will be overwritten by the maximum available height on screen in order to make sure that dialog isn't cut off.

Returns:
sap.ui.core.CSSSizeValue of property contentHeight
Since:
1.12.1
getContentWidth(): sap.ui.core.CSSSize

Gets current value of property contentWidth.

Preferred width of content in Dialog. This property affects the width of dialog on phone in landscape mode, tablet or desktop, because the dialog has a fixed width on phone in portrait mode. If the preferred width is less than the minimum width of dilaog or more than the available width of the screen, it will be overwritten by the min or max value. The current mininum value of dialog width on tablet is 400px.

Returns:
sap.ui.core.CSSSizeValue of property contentWidth
Since:
1.12.1
getCustomHeader(): sap.m.IBar

Gets content of aggregation customHeader.

CustomHeader is only supported in some themes. When it's set, the icon, title and showHeader are properties ignored. Only the customHeader is shown as the header of the dialog.

Returns:
sap.m.IBar
Since:
1.15.1
getDraggable(): boolean

Gets current value of property draggable.

Indicates whether the dialog is draggable. If this property is set to true, the dialog will be draggable by it's header. This property has a default value false. The Dialog can be draggable only in desktop mode.

Default value is false.

Returns:
booleanValue of property draggable
Since:
1.30
getEndButton(): sap.m.Button

Gets content of aggregation endButton.

The button which is rendered to the right side (left side in RTL mode) of the beginButton in the footer area inside the dialog. From UI5 version 1.21.1, there's a new aggregation "buttons" created with which more than 2 buttons can be added to the footer area of dialog. If the new "buttons" aggregation is set, any change made to this aggregation has no effect anymore. When runs on the phone, this button (and the beginButton together when set) is (are) rendered at the center of the footer area. When runs on the other platforms, this button (and the beginButton together when set) is (are) rendered at the right side (left side in RTL mode) of the footer area.

Returns:
sap.m.Button
Since:
1.15.1
getEscapeHandler(): any

Gets current value of property escapeHandler.

This property expects a function with one parameter of type Promise. In the function you should call either resolve() or reject() on the Promise object.
The function allows you to define custom behaviour which will be executed when the ESCAPE key is pressed. By default when the ESCAPE key is pressed the Dialog is immediately closed.

Returns:
anyValue of property escapeHandler
Since:
1.44
getHorizontalScrolling(): boolean

Gets current value of property horizontalScrolling.

Indicates if user can scroll horizontally inside dialog when the content is bigger than the content area. Dialog detects if there's sap.m.NavContainer, sap.m.Page, sap.m.ScrollContainer or sap.m.SplitContainer as direct child added to dialog. If there is, dialog will turn off scrolling by setting this property to false automatically ignoring the existing value of this property.

Default value is true.

Returns:
booleanValue of property horizontalScrolling
Since:
1.15.1
getIcon(): sap.ui.core.URI

Gets current value of property icon.

Icon displayed in the dialog's header. This icon is invisible on the iOS platform and it's density aware. You can use the density convention (@2, @1.5, etc.) to provide higher resolution image for higher density screen.

Returns:
sap.ui.core.URIValue of property icon
getInitialFocus(): sap.ui.core.ID
ID of the element which is the current target of the association initialFocus, or null.
Returns:
sap.ui.core.ID
Since:
1.15.0
getResizable(): boolean

Gets current value of property resizable.

Indicates whether the dialog is resizable. the dialog is resizable. If this property is set to true, the dialog will have a resize handler in it's bottom right corner. This property has a default value false. The Dialog can be resizable only in desktop mode.

Default value is false.

Returns:
booleanValue of property resizable
Since:
1.30
getShowHeader(): boolean

Gets current value of property showHeader.

Determines whether the header is shown inside the dialog. If this property is set to true, the text and icon property are ignored. This property has a default value true.

Default value is true.

Returns:
booleanValue of property showHeader
Since:
1.15.1

Gets current value of property state.

The state affects the icon and the title color. If other than "None" is set, a predefined icon will be added to the dialog. Setting icon property will overwrite the predefined icon. The default value is "None" which doesn't add any icon to the Dialog control. This property is by now only supported by blue crystal theme.

Default value is None.

Returns:
sap.ui.core.ValueStateValue of property state
Since:
1.11.2
getStretch(): boolean

Gets current value of property stretch.

Determines if the dialog will be stretched to full screen. This property is only applicable to standard dialog and message type dialog ignores this property.

Default value is false.

Returns:
booleanValue of property stretch
Since:
1.13.1
getSubHeader(): sap.m.IBar

Gets content of aggregation subHeader.

When subHeader is assigned to Dialog, it's rendered directly after the main header in Dialog. SubHeader is out of the content area and won't be scrolled when content's size is bigger than the content area's size.

Returns:
sap.m.IBar
Since:
1.12.2
getTitle(): string

Gets current value of property title.

Title text appears in the dialog header.

Returns:
stringValue of property title
getType(): sap.m.DialogType

Gets current value of property type.

The type of the dialog. In some themes, the type "message" will limit the dialog's width within 480px on tablet and desktop.

Default value is Standard.

Returns:
sap.m.DialogTypeValue of property type
getVerticalScrolling(): boolean

Gets current value of property verticalScrolling.

Indicates if user can scroll vertically inside dialog when the content is bigger than the content area. Dialog detects if there's sap.m.NavContainer, sap.m.Page, sap.m.ScrollContainer or sap.m.SplitContainer as direct child added to dialog. If there is, dialog will turn off scrolling by setting this property to false automatically ignoring the existing value of this property.

Default value is true.

Returns:
booleanValue of property verticalScrolling
Since:
1.15.1
indexOfButton(oButton): int
Checks for the provided sap.m.Button in the aggregation buttons. and returns its index if found or -1 otherwise.
Parameters:
sap.m.ButtonoButtonThe button whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
Since:
1.21.1
indexOfContent(oContent): int
Checks for the provided sap.ui.core.Control in the aggregation content. and returns its index if found or -1 otherwise.
Parameters:
sap.ui.core.ControloContentThe content whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
insertButton(oButton, iIndex): sap.m.Dialog
Inserts a button into the aggregation buttons.
Parameters:
sap.m.ButtonoButtonthe button to insert; if empty, nothing is inserted
intiIndexthe 0-based index the button should be inserted at; for a negative value of iIndex, the button is inserted at position 0; for a value greater than the current size of the aggregation, the button is inserted at the last position
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.21.1
insertContent(oContent, iIndex): sap.m.Dialog
Inserts a content into the aggregation content.
Parameters:
sap.ui.core.ControloContentthe content to insert; if empty, nothing is inserted
intiIndexthe 0-based index the content should be inserted at; for a negative value of iIndex, the content is inserted at position 0; for a value greater than the current size of the aggregation, the content is inserted at the last position
Returns:
sap.m.DialogReference to this in order to allow method chaining
isOpen()
The method checks if the Dialog is open. It returns true when the Dialog is currently open (this includes opening and closing animations), otherwise it returns false.
Since:
1.9.1
open()
Open the dialog.
removeAllAriaDescribedBy(): sap.ui.core.ID[]
Removes all the controls in the association named ariaDescribedBy.
Returns:
sap.ui.core.ID[]An array of the removed elements (might be empty)
removeAllAriaLabelledBy(): sap.ui.core.ID[]
Removes all the controls in the association named ariaLabelledBy.
Returns:
sap.ui.core.ID[]An array of the removed elements (might be empty)
removeAllButtons(): sap.m.Button[]

Removes all the controls from the aggregation buttons.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.m.Button[]An array of the removed elements (might be empty)
Since:
1.21.1
removeAllContent(): sap.ui.core.Control[]

Removes all the controls from the aggregation content.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.ui.core.Control[]An array of the removed elements (might be empty)
removeAriaDescribedBy(vAriaDescribedBy): sap.ui.core.ID
Removes an ariaDescribedBy from the association named ariaDescribedBy.
Parameters:
int|sap.ui.core.ID|sap.ui.core.ControlvAriaDescribedByThe ariaDescribedBy to be removed or its index or ID
Returns:
sap.ui.core.IDThe removed ariaDescribedBy or null
removeAriaLabelledBy(vAriaLabelledBy): sap.ui.core.ID
Removes an ariaLabelledBy from the association named ariaLabelledBy.
Parameters:
int|sap.ui.core.ID|sap.ui.core.ControlvAriaLabelledByThe ariaLabelledBy to be removed or its index or ID
Returns:
sap.ui.core.IDThe removed ariaLabelledBy or null
removeButton(vButton): sap.m.Button
Removes a button from the aggregation buttons.
Parameters:
int|string|sap.m.ButtonvButtonThe button to remove or its index or id
Returns:
sap.m.ButtonThe removed button or null
Since:
1.21.1
removeContent(vContent): sap.ui.core.Control
Removes a content from the aggregation content.
Parameters:
int|string|sap.ui.core.ControlvContentThe content to remove or its index or id
Returns:
sap.ui.core.ControlThe removed content or null
setBeginButton(oBeginButton): sap.m.Dialog
Sets the aggregated beginButton.
Parameters:
sap.m.ButtonoBeginButtonThe beginButton to set
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.1
setContentHeight(sContentHeight): sap.m.Dialog

Sets a new value for property contentHeight.

Preferred height of content in Dialog. If the preferred height is bigger than the available space on screen, it will be overwritten by the maximum available height on screen in order to make sure that dialog isn't cut off.

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:
sap.ui.core.CSSSizesContentHeightNew value for property contentHeight
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.12.1
setContentWidth(sContentWidth): sap.m.Dialog

Sets a new value for property contentWidth.

Preferred width of content in Dialog. This property affects the width of dialog on phone in landscape mode, tablet or desktop, because the dialog has a fixed width on phone in portrait mode. If the preferred width is less than the minimum width of dilaog or more than the available width of the screen, it will be overwritten by the min or max value. The current mininum value of dialog width on tablet is 400px.

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:
sap.ui.core.CSSSizesContentWidthNew value for property contentWidth
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.12.1
setCustomHeader(oCustomHeader): sap.m.Dialog
Sets the aggregated customHeader.
Parameters:
sap.m.IBaroCustomHeaderThe customHeader to set
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.1
setDraggable(bDraggable): sap.m.Dialog

Sets a new value for property draggable.

Indicates whether the dialog is draggable. If this property is set to true, the dialog will be draggable by it's header. This property has a default value false. The Dialog can be draggable only in desktop mode.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Parameters:
booleanbDraggableNew value for property draggable
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.30
setEndButton(oEndButton): sap.m.Dialog
Sets the aggregated endButton.
Parameters:
sap.m.ButtonoEndButtonThe endButton to set
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.1
setEscapeHandler(oEscapeHandler): sap.m.Dialog

Sets a new value for property escapeHandler.

This property expects a function with one parameter of type Promise. In the function you should call either resolve() or reject() on the Promise object.
The function allows you to define custom behaviour which will be executed when the ESCAPE key is pressed. By default when the ESCAPE key is pressed the Dialog is immediately closed.

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:
anyoEscapeHandlerNew value for property escapeHandler
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.44
setHorizontalScrolling(bHorizontalScrolling): sap.m.Dialog

Sets a new value for property horizontalScrolling.

Indicates if user can scroll horizontally inside dialog when the content is bigger than the content area. Dialog detects if there's sap.m.NavContainer, sap.m.Page, sap.m.ScrollContainer or sap.m.SplitContainer as direct child added to dialog. If there is, dialog will turn off scrolling by setting this property to false automatically ignoring the existing value of this property.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Parameters:
booleanbHorizontalScrollingNew value for property horizontalScrolling
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.1
setIcon(sIcon): sap.m.Dialog

Sets a new value for property icon.

Icon displayed in the dialog's header. This icon is invisible on the iOS platform and it's density aware. You can use the density convention (@2, @1.5, etc.) to provide higher resolution image for higher density screen.

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:
sap.ui.core.URIsIconNew value for property icon
Returns:
sap.m.DialogReference to this in order to allow method chaining
setInitialFocus(oInitialFocus): sap.m.Dialog
Sets the associated initialFocus.
Parameters:
sap.ui.core.ID|sap.ui.core.ControloInitialFocusID of an element which becomes the new target of this initialFocus association; alternatively, an element instance may be given
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.0
setResizable(bResizable): sap.m.Dialog

Sets a new value for property resizable.

Indicates whether the dialog is resizable. the dialog is resizable. If this property is set to true, the dialog will have a resize handler in it's bottom right corner. This property has a default value false. The Dialog can be resizable only in desktop mode.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Parameters:
booleanbResizableNew value for property resizable
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.30
setShowHeader(bShowHeader): sap.m.Dialog

Sets a new value for property showHeader.

Determines whether the header is shown inside the dialog. If this property is set to true, the text and icon property are ignored. This property has a default value true.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Parameters:
booleanbShowHeaderNew value for property showHeader
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.1
setState(sState): sap.m.Dialog

Sets a new value for property state.

The state affects the icon and the title color. If other than "None" is set, a predefined icon will be added to the dialog. Setting icon property will overwrite the predefined icon. The default value is "None" which doesn't add any icon to the Dialog control. This property is by now only supported by blue crystal theme.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

Parameters:
sap.ui.core.ValueStatesStateNew value for property state
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.11.2
setStretch(bStretch): sap.m.Dialog

Sets a new value for property stretch.

Determines if the dialog will be stretched to full screen. This property is only applicable to standard dialog and message type dialog ignores this property.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Parameters:
booleanbStretchNew value for property stretch
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.13.1
setSubHeader(oSubHeader): sap.m.Dialog
Sets the aggregated subHeader.
Parameters:
sap.m.IBaroSubHeaderThe subHeader to set
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.12.2
setTitle(sTitle): sap.m.Dialog

Sets a new value for property title.

Title text appears in the dialog header.

When called with a value of null or undefined, the default value of the property will be restored.

Parameters:
stringsTitleNew value for property title
Returns:
sap.m.DialogReference to this in order to allow method chaining
setType(sType): sap.m.Dialog

Sets a new value for property type.

The type of the dialog. In some themes, the type "message" will limit the dialog's width within 480px on tablet and desktop.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Standard.

Parameters:
sap.m.DialogTypesTypeNew value for property type
Returns:
sap.m.DialogReference to this in order to allow method chaining
setVerticalScrolling(bVerticalScrolling): sap.m.Dialog

Sets a new value for property verticalScrolling.

Indicates if user can scroll vertically inside dialog when the content is bigger than the content area. Dialog detects if there's sap.m.NavContainer, sap.m.Page, sap.m.ScrollContainer or sap.m.SplitContainer as direct child added to dialog. If there is, dialog will turn off scrolling by setting this property to false automatically ignoring the existing value of this property.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Parameters:
booleanbVerticalScrollingNew value for property verticalScrolling
Returns:
sap.m.DialogReference to this in order to allow method chaining
Since:
1.15.1
getLeftButton(): sap.ui.core.ID
ID of the element which is the current target of the association leftButton, or null.
Returns:
sap.ui.core.ID
Deprecated API:

Since version 1.15.1.

LeftButton has been deprecated since 1.15.1. Please use the beginButton instead which is more RTL friendly.

getRightButton(): sap.ui.core.ID
ID of the element which is the current target of the association rightButton, or null.
Returns:
sap.ui.core.ID
Deprecated API:

Since version 1.15.1.

RightButton has been deprecated since 1.15.1. Please use the endButton instead which is more RTL friendly.

getStretchOnPhone(): boolean

Gets current value of property stretchOnPhone.

Determines whether the dialog will displayed on full screen on a phone.

Default value is false.

Returns:
booleanValue of property stretchOnPhone
Deprecated API:
Since version 1.13.1. Please use the new stretch property instead. This enables a stretched dialog even on tablet and desktop. If you want to achieve the same effect as stretchOnPhone, please set the stretch with jQuery.device.is.phone, then dialog is only stretched when runs on phone.
Since:
1.11.2
setLeftButton(oLeftButton): sap.m.Dialog
Sets the associated leftButton.
Parameters:
sap.ui.core.ID|sap.m.ButtonoLeftButtonID of an element which becomes the new target of this leftButton association; alternatively, an element instance may be given
Returns:
sap.m.DialogReference to this in order to allow method chaining
Deprecated API:

Since version 1.15.1.

LeftButton has been deprecated since 1.15.1. Please use the beginButton instead which is more RTL friendly.

setRightButton(oRightButton): sap.m.Dialog
Sets the associated rightButton.
Parameters:
sap.ui.core.ID|sap.m.ButtonoRightButtonID of an element which becomes the new target of this rightButton association; alternatively, an element instance may be given
Returns:
sap.m.DialogReference to this in order to allow method chaining
Deprecated API:

Since version 1.15.1.

RightButton has been deprecated since 1.15.1. Please use the endButton instead which is more RTL friendly.

setStretchOnPhone(bStretchOnPhone): sap.m.Dialog

Sets a new value for property stretchOnPhone.

Determines whether the dialog will displayed on full screen on a phone.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Parameters:
booleanbStretchOnPhoneNew value for property stretchOnPhone
Returns:
sap.m.DialogReference to this in order to allow method chaining
Deprecated API:
Since version 1.13.1. Please use the new stretch property instead. This enables a stretched dialog even on tablet and desktop. If you want to achieve the same effect as stretchOnPhone, please set the stretch with jQuery.device.is.phone, then dialog is only stretched when runs on phone.
Since:
1.11.2