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
validateFieldGroup
Events borrowed from class sap.ui.base.ManagedObject
formatError, modelContextChange, parseError, validationError, validationSuccess
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(mArguments?)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.
Methods borrowed from class sap.ui.core.Control
addStyleClass, allowTextSelection, attachBrowserEvent, attachValidateFieldGroup, checkFieldGroupIds, clone, detachBrowserEvent, detachValidateFieldGroup, fireValidateFieldGroup, getAccessibilityInfo, getBusy, getBusyIndicatorDelay, getControlsByFieldGroupId, getFieldGroupIds, getIdForLabel, getRenderer, getVisible, hasStyleClass, invalidate, isBusy, onBeforeRendering, placeAt, removeStyleClass, rerender, setBusy, setBusyIndicatorDelay, setFieldGroupIds, setVisible, toggleStyleClass, triggerValidateFieldGroup
Methods borrowed from class sap.ui.core.Element
$, addCustomData, addDependent, addEventDelegate, applyFocusInfo, bindElement, data, destroy, destroyCustomData, destroyDependents, destroyLayoutData, destroyTooltip, enhanceAccessibilityState, exit, findElements, fireEvent, focus, getCustomData, getDependents, getDomRef, getElementBinding, getFocusDomRef, getFocusInfo, getInterface, getLayoutData, getMetadata, getTooltip, getTooltip_AsString, getTooltip_Text, indexOfCustomData, indexOfDependent, init, insertCustomData, insertDependent, prop, removeAllCustomData, removeAllDependents, removeCustomData, removeDependent, removeEventDelegate, setLayoutData, setTooltip, toString, unbindElement
Methods borrowed from class sap.ui.base.ManagedObject
addAggregation, addAssociation, applySettings, attachFormatError, attachModelContextChange, attachParseError, attachValidationError, attachValidationSuccess, bindAggregation, bindContext, bindObject, bindProperty, destroyAggregation, detachFormatError, detachModelContextChange, detachParseError, detachValidationError, detachValidationSuccess, findAggregatedObjects, fireFormatError, fireModelContextChange, fireParseError, fireValidationError, fireValidationSuccess, getAggregation, getAssociation, getBinding, getBindingContext, getBindingInfo, getBindingPath, getEventingParent, getId, getModel, getObjectBinding, getOriginInfo, getParent, getProperty, hasModel, indexOfAggregation, insertAggregation, isBound, isInvalidateSuppressed, isTreeBinding, propagateMessages, removeAggregation, removeAllAggregation, removeAllAssociation, removeAssociation, setAggregation, setAssociation, setBindingContext, setModel, setProperty, unbindAggregation, unbindContext, unbindObject, unbindProperty, validateAggregation, validateProperty
Methods borrowed from class sap.ui.base.EventProvider
attachEvent, attachEventOnce, detachEvent, hasListeners
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:
{string}sId? id for the new control, generated automatically if no id is given
{object}mSettings? initial settings for the new control
Event Detail
resize(oControlEvent)
Event is fired when contents are resized.
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{string}oControlEvent.getParameters.id The ID of the splitter control. The splitter control can also be accessed by calling getSource() on the event.
{int[]}oControlEvent.getParameters.oldSizes An array of values representing the old (pixel-)sizes of the splitter contents
{int[]}oControlEvent.getParameters.newSizes An 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:
{string}sClassName Name of the class being created
{object}oClassInfo? Object literal with information about the class
{function}FNMetaImpl? Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
{function} Created 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.Metadata} Metadata object describing this class
addContentArea(oContentArea): sap.ui.layout.Splitter
Adds some contentArea to the aggregation contentAreas.
Parameters:
{sap.ui.core.Control}oContentArea the contentArea to add; if empty, nothing is inserted
Returns:
{sap.ui.layout.Splitter} Reference 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:
{object}oData? An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}fnFunction The function to be called when the event occurs
{object}oListener? Context object to call the event handler with. Defaults to this sap.ui.layout.Splitter itself
Returns:
{sap.ui.layout.Splitter} Reference 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.Splitter} Reference 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:
{function}fnFunction The function to be called, when the event occurs
{object}oListener Context object on which the given function had to be called
Returns:
{sap.ui.layout.Splitter} Reference 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(mArguments?): sap.ui.layout.Splitter
Fires event resize to attached listeners.

Expects the following event parameters:

  • id of type stringThe ID of the splitter control. The splitter control can also be accessed by calling getSource() on the event.
  • oldSizes of type int[]An array of values representing the old (pixel-)sizes of the splitter contents
  • newSizes of type int[]An array of values representing the new (pixel-)sizes of the splitter contents
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.ui.layout.Splitter} Reference 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.CSSSize} Value 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.Orientation} Value 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.CSSSize} Value 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.Control}oContentArea The contentArea whose index is looked for
Returns:
{int} The 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.Control}oContentArea the contentArea to insert; if empty, nothing is inserted
{int}iIndex 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
Returns:
{sap.ui.layout.Splitter} Reference 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.Control}vContentArea The contentAreato remove or its index or id
Returns:
{sap.ui.core.Control} The 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.CSSSize}sHeight New value for property height
Returns:
{sap.ui.layout.Splitter} Reference 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.Orientation}sOrientation New value for property orientation
Returns:
{sap.ui.layout.Splitter} Reference 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.CSSSize}sWidth New value for property width
Returns:
{sap.ui.layout.Splitter} Reference 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:
{boolean}forceDirectly? Do 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:
{boolean}bTemporarily? Only disable autoResize temporarily (used for live resize), so that the previous status can be restored afterwards
Deprecated:
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:
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:
{boolean}bTemporarily? Only enables autoResize if it was previously disabled temporarily (used for live resize)
Deprecated:
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:
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.
Deprecated:
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
Returns:
{Number[]} Array of px values that correspond to the content area sizes