class sap.ui.layout.Splitter

Control sample: sap.ui.layout.Splitter
Visiblity: public
UX Guidelines:
Implements:
Available since: N/A
Module: sap/ui/layout/Splitter
Application Component: CA-UI5-CTR

Overview

A layout that contains several content areas. The content that is added to the splitter should contain layoutData of type SplitterLayoutData which defines its size and size constraints. If such layoutData is not defined, it will be generated automatically.

By adding or changing the layoutData to the controls that make up the content areas, the size can be changed programmatically. Additionally the content areas can be made non-resizable individually and a minimal size (in px) can be set.

The orientation of the splitter can be set to horizontal (default) or vertical. All content areas of the splitter will be arranged in that way. In order to split vertically and horizontally at the same time, splitters need to be nested.

The splitter bars are focusable to enable resizing of the content areas via keyboard. The size of the content areas can be manipulated when the splitter bar is focused and Shift-Left/Down/Right/Up are pressed. When Shift-Home/End are pressed, the content areas are resized to their minimum or maximum size (Note, that resizing one auto-size content area next to another auto-size content area, might lead to the effect that the former does not take its maximum size but only the maximum size before recalculating the auto-sizes).

The splitter bars used for resizing the content areas by the user can be set to different widths (or heights in vertical mode) and the splitter will automatically resize the other content areas accordingly. In case the splitter bar is resized after the splitter has been rendered, a manual resize has to be triggered by invoking triggerResize() on the splitter.

Responsive Behavior

On touch-enabled devices the bars of the splitter can be moved by touching the grip.


Constructor

Constructor for a new Splitter.

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

new sap.ui.layout.Splitter(sId?, mSettings?)
Param Type Default Value Description
sId? string

id for the new control, generated automatically if no id is given

mSettings? object

initial settings for the new control


Properties

Name Type Default Value Description
height sap.ui.core.CSSSize 100%

The height of the control

Visibility: public
orientation sap.ui.core.Orientation Horizontal

Whether to split the contents horizontally (default) or vertically.

Visibility: public
width sap.ui.core.CSSSize 100%

The width of the control

Visibility: public

Aggregations

Default Aggregation: contentAreas

Name Cardinality Type Description
contentAreas (default) 0..n sap.ui.core.Control

The content areas to be split. The control will show n-1 splitter bars between n controls in this aggregation.


Events Overview

Event Description
resize

Event is fired when contents are resized.

resize

Event is fired when contents are resized.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
id string

The ID of the splitter control. The splitter control can also be accessed by calling getSource() on the event.

oldSizes int[]

An array of values representing the old (pixel-)sizes of the splitter contents

newSizes int[]

An array of values representing the new (pixel-)sizes of the splitter contents


Methods Overview

Method Description
addContentArea

Adds some contentArea to the aggregation contentAreas.

attachResize

Attaches event handler fnFunction to the resize event of this sap.ui.layout.Splitter.

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.ui.layout.Splitter itself.

Event is fired when contents are resized.

destroyContentAreas

Destroys all the contentAreas in the aggregation contentAreas.

detachResize

Detaches event handler fnFunction from the resize event of this sap.ui.layout.Splitter.

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

disableAutoResize

Disables the resize handler for this control, this leads to an automatic resize of the contents whenever the control changes its size. The resize handler is enabled in every control instance by default. For performance reasons this behavior can be disabled by calling disableAutoResize()

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface
disableKeyboardSupport

Disables the resizing of the Splitter contents via keyboard. This changes the Splitter bars to non-focusable elements.

disableLiveResize

Disables recalculation and resize of the splitter contents while dragging the splitter bar. This means that the contents are resized only once after moving the splitter bar.

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface
enableAutoResize

Enables the resize handler for this control, this leads to an automatic resize of the contents whenever the control changes its size. The resize handler is enabled in every control instance by default. For performance reasons this behavior can be disabled by calling disableAutoResize()

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface
enableKeyboardSupport

Enables the resizing of the Splitter contents via keyboard. This makes the Splitter bars focusable elements.

enableLiveResize

Enables recalculation and resize of the splitter contents while dragging the splitter bar. This means that the contents are resized several times per second when moving the splitter bar.

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface
sap.ui.layout.Splitter.extend

Creates a new subclass of class sap.ui.layout.Splitter 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.

fireResize

Fires event resize to attached listeners.

getCalculatedSizes

Returns the current actual content sizes as pixel value - these values can change with every resize.

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface
getContentAreas

Gets content of aggregation contentAreas.

The content areas to be split. The control will show n-1 splitter bars between n controls in this aggregation.

getHeight

Gets current value of property height.

The height of the control

Default value is '100%'.

sap.ui.layout.Splitter.getMetadata

Returns a metadata object for class sap.ui.layout.Splitter.

getOrientation

Gets current value of property orientation.

Whether to split the contents horizontally (default) or vertically.

Default value is Horizontal.

getWidth

Gets current value of property width.

The width of the control

Default value is '100%'.

indexOfContentArea

Checks for the provided sap.ui.core.Control in the aggregation contentAreas. and returns its index if found or -1 otherwise.

insertContentArea

Inserts a contentArea into the aggregation contentAreas.

removeAllContentAreas

Removes all the controls from the aggregation contentAreas.

Additionally, it unregisters them from the hosting UIArea.

removeContentArea

Removes a contentArea from the aggregation contentAreas.

resetContentAreasSizes

Resets the size (width or height) of each of the content areas.

setHeight

Sets a new value for property height.

The height of the control

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

Default value is '100%'.

setOrientation

Sets a new value for property orientation.

Whether to split the contents horizontally (default) or vertically.

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

Default value is Horizontal.

setWidth

Sets a new value for property width.

The width of the control

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

Default value is '100%'.

triggerResize

This method triggers a resize on the Splitter - meaning it forces the Splitter to recalculate all sizes. This method should only be used in rare cases, for example when the CSS that defines the sizes of the splitter bars changes without triggering a rerendering of the splitter.

addContentArea

Adds some contentArea to the aggregation contentAreas.

Param Type DefaultValue Description
oContentArea sap.ui.core.Control

The contentArea to add; if empty, nothing is inserted

attachResize

Attaches event handler fnFunction to the resize event of this sap.ui.layout.Splitter.

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.ui.layout.Splitter itself.

Event is fired when contents are resized.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.layout.Splitter itself

destroyContentAreas

Destroys all the contentAreas in the aggregation contentAreas.

detachResize

Detaches event handler fnFunction from the resize event of this sap.ui.layout.Splitter.

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

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

disableAutoResize

Disables the resize handler for this control, this leads to an automatic resize of the contents whenever the control changes its size. The resize handler is enabled in every control instance by default. For performance reasons this behavior can be disabled by calling disableAutoResize()

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface
Param Type DefaultValue Description
bTemporarily boolean false

Only disable autoResize temporarily (used for live resize), so that the previous status can be restored afterwards

disableKeyboardSupport

Disables the resizing of the Splitter contents via keyboard. This changes the Splitter bars to non-focusable elements.

disableLiveResize

Disables recalculation and resize of the splitter contents while dragging the splitter bar. This means that the contents are resized only once after moving the splitter bar.

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface

enableAutoResize

Enables the resize handler for this control, this leads to an automatic resize of the contents whenever the control changes its size. The resize handler is enabled in every control instance by default. For performance reasons this behavior can be disabled by calling disableAutoResize()

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface
Param Type DefaultValue Description
bTemporarily boolean false

Only enables autoResize if it was previously disabled temporarily (used for live resize)

enableKeyboardSupport

Enables the resizing of the Splitter contents via keyboard. This makes the Splitter bars focusable elements.

enableLiveResize

Enables recalculation and resize of the splitter contents while dragging the splitter bar. This means that the contents are resized several times per second when moving the splitter bar.

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface

sap.ui.layout.Splitter.extend

Creates a new subclass of class sap.ui.layout.Splitter 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.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireResize

Fires event resize to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

id string

The ID of the splitter control. The splitter control can also be accessed by calling getSource() on the event.

oldSizes int[]

An array of values representing the old (pixel-)sizes of the splitter contents

newSizes int[]

An array of values representing the new (pixel-)sizes of the splitter contents

getCalculatedSizes

Returns the current actual content sizes as pixel value - these values can change with every resize.

Since 1.21 This method is declared as protected in order to assess the need for this feature. It is declared as deprecated because the API might change in case the need for this is high enough to make it part of the official Splitter interface

getContentAreas

Gets content of aggregation contentAreas.

The content areas to be split. The control will show n-1 splitter bars between n controls in this aggregation.

getHeight

Gets current value of property height.

The height of the control

Default value is '100%'.

sap.ui.layout.Splitter.getMetadata

Returns a metadata object for class sap.ui.layout.Splitter.

getOrientation

Gets current value of property orientation.

Whether to split the contents horizontally (default) or vertically.

Default value is Horizontal.

getWidth

Gets current value of property width.

The width of the control

Default value is '100%'.

indexOfContentArea

Checks for the provided sap.ui.core.Control in the aggregation contentAreas. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oContentArea sap.ui.core.Control

The contentArea whose index is looked for

insertContentArea

Inserts a contentArea into the aggregation contentAreas.

Param Type DefaultValue Description
oContentArea sap.ui.core.Control

The contentArea to insert; if empty, nothing is inserted

iIndex int

The 0-based index the contentArea should be inserted at; for a negative value of iIndex, the contentArea is inserted at position 0; for a value greater than the current size of the aggregation, the contentArea is inserted at the last position

removeAllContentAreas

Removes all the controls from the aggregation contentAreas.

Additionally, it unregisters them from the hosting UIArea.

removeContentArea

Removes a contentArea from the aggregation contentAreas.

Param Type DefaultValue Description
vContentArea int string sap.ui.core.Control

The contentArea to remove or its index or id

resetContentAreasSizes

Resets the size (width or height) of each of the content areas.

setHeight

Sets a new value for property height.

The height of the control

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

Default value is '100%'.

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize '100%'

New value for property height

setOrientation

Sets a new value for property orientation.

Whether to split the contents horizontally (default) or vertically.

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

Default value is Horizontal.

Param Type DefaultValue Description
sOrientation sap.ui.core.Orientation Horizontal

New value for property orientation

setWidth

Sets a new value for property width.

The width of the control

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

Default value is '100%'.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize '100%'

New value for property width

triggerResize

This method triggers a resize on the Splitter - meaning it forces the Splitter to recalculate all sizes. This method should only be used in rare cases, for example when the CSS that defines the sizes of the splitter bars changes without triggering a rerendering of the splitter.

Param Type DefaultValue Description
forceDirectly boolean false

Do not delay the resize, trigger it right now.