Class sap.ui.layout.SplitterModule: sap/ui/layout/Splitter

extends Control

A layout that contains several content areas. The content that is added to the splitter should contain LayoutData of the type SplitterLayoutData that defines its size and size contraints.

By adding or changing SplitterLayoutData to the controls that make up the content areas, the size can be changed programatically. Additionally the contents 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 can be focused to enable resizing of the content areas via keyboard. The contents size can be manipulated when the splitter bar is focused and Shift-Left/Down/Right/Up are pressed. When Shift-Home/End are pressed, the contents are set their minimum or maximum size (keep in mind though, that resizing an auto-size content-area next to another auto-size one might lead to the effect that the former does not take its maximum size but only the maximum size before recalculating auto sizes).

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


Since: 1.22.0.
Constructor Summary
new sap.ui.layout.Splitter(sId?, mSettings?)Constructor for a new Splitter.
Event Summary
resize(oControlEvent)Event is fired when contents are resized.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.ui.layout.Splitter.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.layout.Splitter with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.layout.Splitter.getMetadata()Returns a metadata object for class sap.ui.layout.Splitter.
addContentArea(oContentArea)Adds some contentArea to the aggregation contentAreas.
attachResize(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the resize event of this sap.ui.layout.Splitter.
destroyContentAreas()Destroys all the contentAreas in the aggregation contentAreas.
detachResize(fnFunction, oListener)Detaches event handler fnFunction from the resize event of this sap.ui.layout.Splitter.
disableKeyboardSupport()Disables the resizing of the Splitter contents via keyboard.
enableKeyboardSupport()Enables the resizing of the Splitter contents via keyboard.
fireResize(mParameters?)Fires event resize to attached listeners.
getContentAreas()Gets content of aggregation contentAreas.
getHeight()Gets current value of property height.
getOrientation()Gets current value of property orientation.
getWidth()Gets current value of property width.
indexOfContentArea(oContentArea)Checks for the provided sap.ui.core.Control in the aggregation contentAreas.
insertContentArea(oContentArea, iIndex)Inserts a contentArea into the aggregation contentAreas.
removeAllContentAreas()Removes all the controls from the aggregation contentAreas.
removeContentArea(vContentArea)Removes a contentArea from the aggregation contentAreas.
setHeight(sHeight)Sets a new value for property height.
setOrientation(sOrientation)Sets a new value for property orientation.
setWidth(sWidth)Sets a new value for property width.
triggerResize(forceDirectly?)This method triggers a resize on the Splitter - meaning it forces the Splitter to recalculate all sizes.
disableAutoResize(bTemporarily?)Disables the resize handler for this control, this leads to an automatic resize of the contents whenever the control changes its size.
disableLiveResize()Disables recalculation and resize of the splitter contents while dragging the splitter bar.
enableAutoResize(bTemporarily?)Enables the resize handler for this control, this leads to an automatic resize of the contents whenever the control changes its size.
enableLiveResize()Enables recalculation and resize of the splitter contents while dragging the splitter bar.
getCalculatedSizes()Returns the current actual content sizes as pixel value - these values can change with every resize.
Constructor Detail
new sap.ui.layout.Splitter(sId?, mSettings?)

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 for a general description of the syntax of the settings object.

The supported settings are:

  • Properties

    • orientation : sap.ui.core.Orientation (default: Horizontal)
    • width : sap.ui.core.CSSSize (default: 100%)
    • height : sap.ui.core.CSSSize (default: 100%)

  • Aggregations

  • Events

    • resize : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

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
resize(oControlEvent)
Event is fired when contents are resized.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
stringoControlEvent.getParameters.idThe ID of the splitter control. The splitter control can also be accessed by calling getSource() on the event.
int[]oControlEvent.getParameters.oldSizesAn array of values representing the old (pixel-)sizes of the splitter contents
int[]oControlEvent.getParameters.newSizesAn array of values representing the new (pixel-)sizes of the splitter contents
Method Detail
sap.ui.layout.Splitter.extend(sClassName, oClassInfo?, FNMetaImpl?): function

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.

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.ui.layout.Splitter.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.layout.Splitter.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addContentArea(oContentArea): sap.ui.layout.Splitter
Adds some contentArea to the aggregation contentAreas.
Parameters:
sap.ui.core.ControloContentAreathe contentArea to add; if empty, nothing is inserted
Returns:
sap.ui.layout.SplitterReference to this in order to allow method chaining
attachResize(oData?, fnFunction, oListener?): sap.ui.layout.Splitter

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.

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.ui.layout.Splitter itself
Returns:
sap.ui.layout.SplitterReference to this in order to allow method chaining
destroyContentAreas(): sap.ui.layout.Splitter
Destroys all the contentAreas in the aggregation contentAreas.
Returns:
sap.ui.layout.SplitterReference to this in order to allow method chaining
detachResize(fnFunction, oListener): sap.ui.layout.Splitter

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.ui.layout.SplitterReference to this in order to allow method chaining
disableKeyboardSupport()
Disables the resizing of the Splitter contents via keyboard. This changes the Splitter bars to non-focussable elements.
enableKeyboardSupport()
Enables the resizing of the Splitter contents via keyboard. This makes the Splitter bars focussable elements.
fireResize(mParameters?): sap.ui.layout.Splitter
Fires event resize to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
stringmParameters.id?The ID of the splitter control. The splitter control can also be accessed by calling getSource() on the event.
int[]mParameters.oldSizes?An array of values representing the old (pixel-)sizes of the splitter contents
int[]mParameters.newSizes?An array of values representing the new (pixel-)sizes of the splitter contents
Returns:
sap.ui.layout.SplitterReference to this in order to allow method chaining
getContentAreas(): sap.ui.core.Control[]

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.

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

Gets current value of property height.

The height of the control

Default value is 100%.

Returns:
sap.ui.core.CSSSizeValue of property height
getOrientation(): sap.ui.core.Orientation

Gets current value of property orientation.

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

Default value is Horizontal.

Returns:
sap.ui.core.OrientationValue of property orientation
getWidth(): sap.ui.core.CSSSize

Gets current value of property width.

The width of the control

Default value is 100%.

Returns:
sap.ui.core.CSSSizeValue of property width
indexOfContentArea(oContentArea): int
Checks for the provided sap.ui.core.Control in the aggregation contentAreas. and returns its index if found or -1 otherwise.
Parameters:
sap.ui.core.ControloContentAreaThe contentArea whose index is looked for
Returns:
intThe index of the provided control in the aggregation if found, or -1 otherwise
insertContentArea(oContentArea, iIndex): sap.ui.layout.Splitter
Inserts a contentArea into the aggregation contentAreas.
Parameters:
sap.ui.core.ControloContentAreathe contentArea to insert; if empty, nothing is inserted
intiIndexthe 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
Returns:
sap.ui.layout.SplitterReference to this in order to allow method chaining
removeAllContentAreas(): sap.ui.core.Control[]

Removes all the controls from the aggregation contentAreas.

Additionally, it unregisters them from the hosting UIArea.

Returns:
sap.ui.core.Control[]An array of the removed elements (might be empty)
removeContentArea(vContentArea): sap.ui.core.Control
Removes a contentArea from the aggregation contentAreas.
Parameters:
int|string|sap.ui.core.ControlvContentAreaThe contentArea to remove or its index or id
Returns:
sap.ui.core.ControlThe removed contentArea or null
setHeight(sHeight): sap.ui.layout.Splitter

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%.

Parameters:
sap.ui.core.CSSSizesHeightNew value for property height
Returns:
sap.ui.layout.SplitterReference to this in order to allow method chaining
setOrientation(sOrientation): sap.ui.layout.Splitter

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.

Parameters:
sap.ui.core.OrientationsOrientationNew value for property orientation
Returns:
sap.ui.layout.SplitterReference to this in order to allow method chaining
setWidth(sWidth): sap.ui.layout.Splitter

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%.

Parameters:
sap.ui.core.CSSSizesWidthNew value for property width
Returns:
sap.ui.layout.SplitterReference to this in order to allow method chaining
triggerResize(forceDirectly?)
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.
Parameters:
booleanforceDirectly?, Default: falseDo not delay the resize, trigger it right now.
disableAutoResize(bTemporarily?)
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()
Parameters:
booleanbTemporarily?, Default: falseOnly disable autoResize temporarily (used for live resize), so that the previous status can be restored afterwards
Deprecated API:
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
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.
Deprecated API:
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(bTemporarily?)
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()
Parameters:
booleanbTemporarily?, Default: falseOnly enables autoResize if it was previously disabled temporarily (used for live resize)
Deprecated API:
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
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.
Deprecated API:
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
getCalculatedSizes(): Number[]
Returns the current actual content sizes as pixel value - these values can change with every resize.
Returns:
Number[]Array of px values that correspond to the content area sizes
Deprecated API:
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