abstract class sap.ui.core.Control

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

Base Class for Controls.

Controls provide the following features:

See section "Developing Controls" in the documentation for an introduction to control development.


Constructor

Creates and initializes a new control with the given sId and settings.

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.core.Control(sId?, mSettings?)
Param Type Default Value Description
sId? string

Optional ID for the new control; generated automatically if no non-empty ID is given Note: this can be omitted, no matter whether mSettings will be given or not!

mSettings? object

Object with initial settings for the new control


Properties

Name Type Default Value Description
blocked boolean false

Whether the control is currently in blocked state.

Visibility: public
busy boolean false

Whether the control is currently in busy state.

Visibility: public
busyIndicatorDelay int 1000

The delay in milliseconds, after which the busy indicator will show up for this control.

Visibility: public
busyIndicatorSize sap.ui.core.BusyIndicatorSize Medium

The size of the BusyIndicator. For controls with a width smaller 3rem a sap.ui.core.BusyIndicatorSize.Small should be used. If the size could vary in width and the width could get smaller than 3rem, the sap.ui.core.BusyIndicatorSize.Auto option could be used. The default is set to sap.ui.core.BusyIndicatorSize.Medium For a full screen BusyIndicator use sap.ui.core.BusyIndicatorSize.Large.

Since: 1.54.

Visibility: public
fieldGroupIds string[]

The IDs of a logical field group that this control belongs to.

All fields in a logical field group should share the same fieldGroupId. Once a logical field group is left, the validateFieldGroup event is fired.

For backward compatibility with older releases, field group IDs are syntactically not limited, but it is suggested to use only valid sap.ui.core.IDs.

See #attachValidateFieldGroup or consult the Field Group documentation.

Since: 1.31.

Visibility: public
visible boolean true

Whether the control should be visible on the screen.

If set to false, a placeholder will be rendered to mark the location of the invisible control in the DOM of the current page. The placeholder will be hidden and have zero dimensions (display: none).

Also see InvisibleRenderer.

Visibility: public

Borrowed Aggregations

Name Cardinality Type Description
customData 0..n sap.ui.core.CustomData

Custom Data, a data structure like a map containing arbitrary key value pairs.

dependents 0..n sap.ui.core.Element

Dependents are not rendered, but their databinding context and lifecycle are bound to the aggregating Element.

Since: 1.19.

dragDropConfig 0..n sap.ui.core.dnd.DragDropBase

Defines the drag-and-drop configuration. Note: This configuration might be ignored due to control metadata restrictions.

Since: 1.56.

layoutData 0..1 sap.ui.core.LayoutData

Defines the layout constraints for this control when it is used inside a Layout. LayoutData classes are typed classes and must match the embedding Layout. See VariantLayoutData for aggregating multiple alternative LayoutData instances to a single Element.

tooltip 0..1 sap.ui.core.TooltipBase

The tooltip that should be shown for this Element.

In the most simple case, a tooltip is a string that will be rendered by the control and displayed by the browser when the mouse pointer hovers over the control's DOM. In this variant, tooltip behaves like a simple control property.

Controls need to explicitly support this kind of tooltip as they have to render it, but most controls do. Exceptions will be documented for the corresponding controls (e.g. sap.ui.core.HTML does not support tooltips).

Alternatively, tooltip can act like a 0..1 aggregation and can be set to a tooltip control (an instance of a subclass of sap.ui.core.TooltipBase). In that case, the framework will take care of rendering the tooltip control in a popup-like manner. Such a tooltip control can display arbitrary content, not only a string.

UI5 currently does not provide a recommended implementation of TooltipBase as the use of content-rich tooltips is discouraged by the Fiori Design Guidelines. Existing subclasses of TooltipBase therefore have been deprecated. However, apps can still subclass from TooltipBase and create their own implementation when needed (potentially taking the deprecated implementations as a starting point).

See the section Using Tooltips in the Fiori Design Guideline.


Events Overview

Event Description
validateFieldGroup

Event is fired if a logical field group defined by fieldGroupIds of a control was left or when the user explicitly pressed the key combination that triggers validation.

By default, the RETURN key without any modifier keys triggers validation, see #triggerValidateFieldGroup.

Listen to this event to validate data of the controls belonging to a field group. See #setFieldGroupIds, or consult the Field Group documentation.

This event bubbles up the control hierarchy.

validateFieldGroup

Event is fired if a logical field group defined by fieldGroupIds of a control was left or when the user explicitly pressed the key combination that triggers validation.

By default, the RETURN key without any modifier keys triggers validation, see #triggerValidateFieldGroup.

Listen to this event to validate data of the controls belonging to a field group. See #setFieldGroupIds, or consult the Field Group documentation.

This event bubbles up the control hierarchy.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
fieldGroupIds string[]

field group IDs of the logical field groups to validate


Methods Overview

Method Description
addStyleClass

The string given as "sStyleClass" will be added to the "class" attribute of this control's root HTML element.

This method is intended to be used to mark controls as being of a special type for which special styling can be provided using CSS selectors that reference this style class name.

Example:
   myButton.addStyleClass("myRedTextButton"); // add a CSS class to one button instance

...and in CSS:
   .myRedTextButton {
      color: red;
   }

This will add the CSS class "myRedTextButton" to the Button HTML and the CSS code above will then make the text in this particular button red.

Only characters allowed inside HTML attributes are allowed. Quotes are not allowed and this method will ignore any strings containing quotes. Strings containing spaces are interpreted as multiple custom style classes which are split by space and can be removed individually later by calling removeStyleClass. Multiple calls with the same sStyleClass will have no different effect than calling once. If sStyleClass is null, empty string or it contains quotes, the call is ignored.

allowTextSelection

Defines whether the user can select text inside this control. Defaults to true as long as this method has not been called.

Note:This only works in Safari; for Firefox the element's style must be set to:

  -moz-user-select: none;
in order to prevent text selection.

attachBrowserEvent

Allows binding handlers for any native browser event to the root HTML element of this Control. This internally handles DOM element replacements caused by re-rendering.

IMPORTANT:
This should be only used as FALLBACK when the Control events do not cover a specific use-case! Always try using SAPUI5 control events, as e.g. accessibility-related functionality is then provided automatically. E.g. when working with a sap.ui.commons.Button, always use the Button's "press" event, not the native "click" event, because "press" is also guaranteed to be fired when certain keyboard activity is supposed to trigger the Button.

In the event handler, this refers to the Control - not to the root DOM element like in jQuery. While the DOM element can be used and modified, the general caveats for working with SAPUI5 control DOM elements apply. In particular the DOM element may be destroyed and replaced by a new one at any time, so modifications that are required to have permanent effect may not be done. E.g. use #addStyleClass instead if the modification is of visual nature.

Use #detachBrowserEvent to remove the event handler(s) again.

attachValidateFieldGroup

Attaches event handler fnFunction to the validateFieldGroup event of this sap.ui.core.Control.

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.core.Control itself.

Event is fired if a logical field group defined by fieldGroupIds of a control was left or when the user explicitly pressed the key combination that triggers validation.

By default, the RETURN key without any modifier keys triggers validation, see #triggerValidateFieldGroup.

Listen to this event to validate data of the controls belonging to a field group. See #setFieldGroupIds, or consult the Field Group documentation.

checkFieldGroupIds

Returns whether this control belongs to a given combination of field groups.

If the vFieldGroupIds parameter is not specified, the method checks whether this control belongs to any field group, that is, whether any field group ID is defined for it.

If a list of field group IDs is specified, either as an array of strings or as a single string (interpreted as a comma separated list of IDs), then the method will check whether this control belongs to all given field groups. Accordingly, an empty list of IDs (empty array or empty string) will always return true.

Note that a string value for vFieldGroupIds (comma separated list) will not be trimmed. All whitespace characters are significant, but in general not recommended in field group IDs.

References:

clone

Overrides Element.clone to clone additional internal state.

The additionally cloned information contains:

detachBrowserEvent

Removes event handlers which have been previously attached using #attachBrowserEvent.

Note: listeners are only removed, if the same combination of event type, callback function and context object is given as in the call to attachBrowserEvent.

detachValidateFieldGroup

Detaches event handler fnFunction from the validateFieldGroup event of this sap.ui.core.Control.

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

sap.ui.core.Control.extend

Defines a new subclass of Control with the name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo can contain the same information that sap.ui.core.Element.extend already accepts, plus the following renderer property:

Example:

Control.extend("sap.mylib.MyControl", {
  metadata : {
    library : "sap.mylib",
    properties : {
      text : "string",
      width : "sap.ui.core.CSSSize"
    }
  },
  renderer: {
    apiVersion: 2,
    render: function(oRM, oControl) {
      oRM.openStart("div", oControl);
      oRM.style("width", oControl.getWidth());
      oRM.openEnd();
      oRM.text(oControl.getText());
      oRM.close("div");
    }
  }
});

There are multiple ways how a renderer can be specified:

  • As a plain object: The object will be used to create a new renderer by using sap.ui.core.Renderer.extend to extend the renderer of the base class of this control. The new renderer will have the same global name as this control class with the additional suffix 'Renderer'.
    Note: The Renderer.extend method expects a plain object (no prototype chain).
  • As a function: The given function will be used as render function of a new renderer; the renderer will be created in the same way as described for the plain object case.
  • As a ready-made renderer, e.g. imported from the corresponding renderer module. As renderers are simple objects (not instances of a specific class), some heuristic is used to distinguish renderers from the plain object case above: An object is assumed to be a ready-made renderer when it has a render function and either is already exposed under the expected global name or has an extend method.
  • As a fully qualified name: The name will be looked up as a global property. If not defined, a module name will be derived from the global name (dots replaced by slashes), the module will be required and provides the renderer, either as AMD export or via the named global property.
  • Omitting the renderer property or setting it to undefined: The fully qualified name of the renderer will be derived from the fully qualified name of the control by adding the suffix "Renderer". The renderer then is retrieved in the same way as described for the fully qualified name case.
  • null or empty string: The control will have no renderer, a call to oControl.getMetadata().getRenderer() will return undefined.

If the resulting renderer is incomplete (has no render function) or if it cannot be found at all, rendering of the control will be skipped.

Note: The apiVersion: 2 flag is required to enable in-place rendering technology. Before setting this property, please ensure that the constraints documented in section "Contract for Renderer.apiVersion 2" of the RenderManager API documentation are fulfilled.

fireValidateFieldGroup

Fires event validateFieldGroup to attached listeners.

getAccessibilityInfo

This function (if available on the concrete control) provides the current accessibility state of the control.

Applications must not call this hook method directly, it is called by the framework.

Subclasses of Control should implement this hook to provide any necessary accessibility information:

MyControl.prototype.getAccessibilityInfo = function() {
   return {
     role: "textbox",      // String which represents the WAI-ARIA role which is implemented by the control.
     type: "date input",   // String which represents the control type (Must be a translated text). Might correlate with
                           // the role.
     description: "value", // String which describes the most relevant control state (e.g. the inputs value). Must be a
                           // translated text.
                           // Note: The type and the enabled/editable state must not be handled here.
     focusable: true,      // Boolean which describes whether the control can get the focus.
     enabled: true,        // Boolean which describes whether the control is enabled. If not relevant it must not be set or
                           // null can be provided.
     editable: true,       // Boolean which describes whether the control is editable. If not relevant it must not be set or
                           // null can be provided.
     children: []          // Aggregations of the given control (e.g. when the control is a layout). Primitive aggregations will be ignored.
                           // Note: Children should only be provided when it is helpful to understand the accessibility context
                           //       (e.g. a form control must not provide details of its internals (fields, labels, ...) but a
                           //       layout should).
   };
};

Note: The returned object provides the accessibility state of the control at the point in time when this function is called.

getBlocked

Gets current value of property blocked.

Whether the control is currently in blocked state.

Default value is false.

Since 1.69 The blocked property is deprecated. There is no accessibility support for this property. Blocked controls should not be used inside Controls, which rely on keyboard navigation, e.g. List controls.
getBusy

Gets current value of property busy.

Whether the control is currently in busy state.

Default value is false.

getBusyIndicatorDelay

Gets current value of property busyIndicatorDelay.

The delay in milliseconds, after which the busy indicator will show up for this control.

Default value is 1000.

getBusyIndicatorSize

Gets current value of property busyIndicatorSize.

The size of the BusyIndicator. For controls with a width smaller 3rem a sap.ui.core.BusyIndicatorSize.Small should be used. If the size could vary in width and the width could get smaller than 3rem, the sap.ui.core.BusyIndicatorSize.Auto option could be used. The default is set to sap.ui.core.BusyIndicatorSize.Medium For a full screen BusyIndicator use sap.ui.core.BusyIndicatorSize.Large.

Default value is 'Medium'.

getControlsByFieldGroupId

Returns a list of all child controls with a field group ID. See checkFieldGroupIds for a description of the vFieldGroupIds parameter. Associated controls are not taken into account.

getFieldGroupIds

Returns a copy of the field group IDs array. Modification of the field group IDs need to call setFieldGroupIds to apply the changes.

getIdForLabel

Returns the DOMNode Id to be used for the "labelFor" attribute of the label.

By default, this is the Id of the control itself.

sap.ui.core.Control.getMetadata

Returns a metadata object for class sap.ui.core.Control.

getRenderer

Returns a renderer for this control instance.

It is retrieved using the RenderManager as done during rendering.

getVisible

Gets current value of property visible.

Whether the control should be visible on the screen.

If set to false, a placeholder will be rendered to mark the location of the invisible control in the DOM of the current page. The placeholder will be hidden and have zero dimensions (display: none).

Also see InvisibleRenderer.

Default value is true.

hasStyleClass

Returns true if the given style class or all multiple style classes which are generated by splitting the given string with space are already set on the control via previous call(s) to addStyleClass().

invalidate

Marks this control and its children for a re-rendering, usually because its state has changed and now differs from the rendered DOM.

Managed settings (properties, aggregations, associations) automatically invalidate the corresponding object. Changing the state via the standard mutators, therefore, does not require an explicit call to invalidate.

By default, all invalidations are buffered and processed together (asynchronously) in a new browser task.

The oOrigin parameter was introduced to allow parent controls to limit their re-rendering to certain areas that have been invalidated by their children. As there is no strong guideline for control developers whether or not to provide the parameter, it is not a reliable source of information. It is, therefore, not recommended in general to use it, only in scenarios where a control and its descendants know each other very well (e.g. complex controls where parent and children have the same code owner).

isBusy

Check if the control is currently in busy state.

Since 1.15 use {@link #getBusy} instead
onAfterRendering

Function is called when the rendering of the control is completed.

Applications must not call this hook method directly, it is called by the framework.

Subclasses of Control should override this hook to implement any necessary actions after the rendering.

onBeforeRendering

Function is called before the rendering of the control is started.

Applications must not call this hook method directly, it is called by the framework.

Subclasses of Control should override this hook to implement any necessary actions before the rendering.

placeAt

Puts this control into the specified container (oRef) at the given position (oPosition).

First it is checked whether oRef is a container element / control (has a multiple aggregation with type sap.ui.core.Control and name 'content') or is an Id String of such a container. If this is not the case oRef can either be a Dom Reference or Id String of the UIArea (if it does not yet exist implicitly a new UIArea is created),

The oPosition can be one of the following:

  • "first": The control is added as the first element to the container.
  • "last": The control is added as the last element to the container (default).
  • "only": All existing children of the container are removed (not destroyed!) and the control is added as new child.
  • index: The control is added at the specified index to the container.

removeStyleClass

Removes the given string from the list of custom style classes that have been set previously. Regular style classes like "sapUiBtn" cannot be removed.

rerender

Synchronously updates the DOM of this control to reflect the current object state.

Note that this method can only be called when the control already has a DOM representation (it has been rendered before) and when the control still is assigned to a UIArea.

Since 1.70 using this method is no longer recommended, but still works. Synchronous DOM updates via this method have several drawbacks: they only work when the control has been rendered before (no initial rendering possible), multiple state changes won't be combined automatically into a single re-rendering, they might cause additional layout trashing, standard invalidation might cause another async re-rendering. The recommended alternative is to rely on invalidation and standard re-rendering.
setBlocked

Set the controls block state.

setBusy

Set the controls busy state.

Note: The busy state can't be set on controls (e.g. sap.m.ColumnListItem) which renderings have the following tags as DOM root element: area|base|br|col|embed|hr|img|input|keygen|link|menuitem|meta|param|source|track|wbr|tr

setBusyIndicatorDelay

Define the delay, after which the busy indicator will show up.

setBusyIndicatorSize

Sets a new value for property busyIndicatorSize.

The size of the BusyIndicator. For controls with a width smaller 3rem a sap.ui.core.BusyIndicatorSize.Small should be used. If the size could vary in width and the width could get smaller than 3rem, the sap.ui.core.BusyIndicatorSize.Auto option could be used. The default is set to sap.ui.core.BusyIndicatorSize.Medium For a full screen BusyIndicator use sap.ui.core.BusyIndicatorSize.Large.

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

Default value is 'Medium'.

setFieldGroupIds

Sets a new value for property fieldGroupIds.

The IDs of a logical field group that this control belongs to.

All fields in a logical field group should share the same fieldGroupId. Once a logical field group is left, the validateFieldGroup event is fired.

For backward compatibility with older releases, field group IDs are syntactically not limited, but it is suggested to use only valid sap.ui.core.IDs.

See #attachValidateFieldGroup or consult the Field Group documentation.

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

Default value is [].

setVisible

Sets a new value for property visible.

Whether the control should be visible on the screen.

If set to false, a placeholder will be rendered to mark the location of the invisible control in the DOM of the current page. The placeholder will be hidden and have zero dimensions (display: none).

Also see InvisibleRenderer.

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

Default value is true.

toggleStyleClass

The string given as "sStyleClass" will be be either added to or removed from the "class" attribute of this control's root HTML element, depending on the value of "bAdd": if bAdd is true, sStyleClass will be added. If bAdd is not given, sStyleClass will be removed if it is currently present and will be added if not present. If sStyleClass is null or empty string, the call is ignored.

See addStyleClass and removeStyleClass for further documentation.

triggerValidateFieldGroup

Triggers the validateFieldGroup event for this control.

Called by sap.ui.core.UIArea if a field group should be validated after it lost the focus or when the key combination was pressed that was configured to trigger validation.

By default, the RETURN key without any modifier keys triggers validation. There's no public API to change that key combination.

See #attachValidateFieldGroup.

addStyleClass

The string given as "sStyleClass" will be added to the "class" attribute of this control's root HTML element.

This method is intended to be used to mark controls as being of a special type for which special styling can be provided using CSS selectors that reference this style class name.

Example:
   myButton.addStyleClass("myRedTextButton"); // add a CSS class to one button instance

...and in CSS:
   .myRedTextButton {
      color: red;
   }

This will add the CSS class "myRedTextButton" to the Button HTML and the CSS code above will then make the text in this particular button red.

Only characters allowed inside HTML attributes are allowed. Quotes are not allowed and this method will ignore any strings containing quotes. Strings containing spaces are interpreted as multiple custom style classes which are split by space and can be removed individually later by calling removeStyleClass. Multiple calls with the same sStyleClass will have no different effect than calling once. If sStyleClass is null, empty string or it contains quotes, the call is ignored.

Param Type DefaultValue Description
sStyleClass string

the CSS class name to be added

allowTextSelection

Defines whether the user can select text inside this control. Defaults to true as long as this method has not been called.

Note:This only works in Safari; for Firefox the element's style must be set to:

  -moz-user-select: none;
in order to prevent text selection.

Param Type DefaultValue Description
bAllow boolean

whether to allow text selection or not

attachBrowserEvent

Allows binding handlers for any native browser event to the root HTML element of this Control. This internally handles DOM element replacements caused by re-rendering.

IMPORTANT:
This should be only used as FALLBACK when the Control events do not cover a specific use-case! Always try using SAPUI5 control events, as e.g. accessibility-related functionality is then provided automatically. E.g. when working with a sap.ui.commons.Button, always use the Button's "press" event, not the native "click" event, because "press" is also guaranteed to be fired when certain keyboard activity is supposed to trigger the Button.

In the event handler, this refers to the Control - not to the root DOM element like in jQuery. While the DOM element can be used and modified, the general caveats for working with SAPUI5 control DOM elements apply. In particular the DOM element may be destroyed and replaced by a new one at any time, so modifications that are required to have permanent effect may not be done. E.g. use #addStyleClass instead if the modification is of visual nature.

Use #detachBrowserEvent to remove the event handler(s) again.

Param Type DefaultValue Description
sEventType string

A string containing one or more JavaScript event types, such as "click" or "blur".

fnHandler function

A function to execute each time the event is triggered.

oListener object

The object, that wants to be notified, when the event occurs

attachValidateFieldGroup

Attaches event handler fnFunction to the validateFieldGroup event of this sap.ui.core.Control.

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.core.Control itself.

Event is fired if a logical field group defined by fieldGroupIds of a control was left or when the user explicitly pressed the key combination that triggers validation.

By default, the RETURN key without any modifier keys triggers validation, see #triggerValidateFieldGroup.

Listen to this event to validate data of the controls belonging to a field group. See #setFieldGroupIds, or consult the Field Group documentation.

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.core.Control itself

checkFieldGroupIds

Returns whether this control belongs to a given combination of field groups.

If the vFieldGroupIds parameter is not specified, the method checks whether this control belongs to any field group, that is, whether any field group ID is defined for it.

If a list of field group IDs is specified, either as an array of strings or as a single string (interpreted as a comma separated list of IDs), then the method will check whether this control belongs to all given field groups. Accordingly, an empty list of IDs (empty array or empty string) will always return true.

Note that a string value for vFieldGroupIds (comma separated list) will not be trimmed. All whitespace characters are significant, but in general not recommended in field group IDs.

References:

Param Type DefaultValue Description
vFieldGroupIds string string[]

An array of field group IDs or a single string with a comma separated list of IDs to match

clone

Overrides Element.clone to clone additional internal state.

The additionally cloned information contains:

Param Type DefaultValue Description
sIdSuffix string

a suffix to be appended to the cloned element id

aLocalIds string[]

an array of local IDs within the cloned hierarchy (internally used)

detachBrowserEvent

Removes event handlers which have been previously attached using #attachBrowserEvent.

Note: listeners are only removed, if the same combination of event type, callback function and context object is given as in the call to attachBrowserEvent.

Param Type DefaultValue Description
sEventType string

A string containing one or more JavaScript event types, such as "click" or "blur".

fnHandler function

The function that is to be no longer executed.

oListener object

The context object that was given in the call to attachBrowserEvent.

detachValidateFieldGroup

Detaches event handler fnFunction from the validateFieldGroup event of this sap.ui.core.Control.

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

sap.ui.core.Control.extend

Defines a new subclass of Control with the name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo can contain the same information that sap.ui.core.Element.extend already accepts, plus the following renderer property:

Example:

Control.extend("sap.mylib.MyControl", {
  metadata : {
    library : "sap.mylib",
    properties : {
      text : "string",
      width : "sap.ui.core.CSSSize"
    }
  },
  renderer: {
    apiVersion: 2,
    render: function(oRM, oControl) {
      oRM.openStart("div", oControl);
      oRM.style("width", oControl.getWidth());
      oRM.openEnd();
      oRM.text(oControl.getText());
      oRM.close("div");
    }
  }
});

There are multiple ways how a renderer can be specified:

If the resulting renderer is incomplete (has no render function) or if it cannot be found at all, rendering of the control will be skipped.

Note: The apiVersion: 2 flag is required to enable in-place rendering technology. Before setting this property, please ensure that the constraints documented in section "Contract for Renderer.apiVersion 2" of the RenderManager API documentation are fulfilled.

Param Type DefaultValue Description
sClassName string

Name of the class to be created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object. If not given, it defaults to sap.ui.core.ElementMetadata.

fireValidateFieldGroup

Fires event validateFieldGroup to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fieldGroupIds string[]

field group IDs of the logical field groups to validate

getAccessibilityInfo

This function (if available on the concrete control) provides the current accessibility state of the control.

Applications must not call this hook method directly, it is called by the framework.

Subclasses of Control should implement this hook to provide any necessary accessibility information:

MyControl.prototype.getAccessibilityInfo = function() {
   return {
     role: "textbox",      // String which represents the WAI-ARIA role which is implemented by the control.
     type: "date input",   // String which represents the control type (Must be a translated text). Might correlate with
                           // the role.
     description: "value", // String which describes the most relevant control state (e.g. the inputs value). Must be a
                           // translated text.
                           // Note: The type and the enabled/editable state must not be handled here.
     focusable: true,      // Boolean which describes whether the control can get the focus.
     enabled: true,        // Boolean which describes whether the control is enabled. If not relevant it must not be set or
                           // null can be provided.
     editable: true,       // Boolean which describes whether the control is editable. If not relevant it must not be set or
                           // null can be provided.
     children: []          // Aggregations of the given control (e.g. when the control is a layout). Primitive aggregations will be ignored.
                           // Note: Children should only be provided when it is helpful to understand the accessibility context
                           //       (e.g. a form control must not provide details of its internals (fields, labels, ...) but a
                           //       layout should).
   };
};

Note: The returned object provides the accessibility state of the control at the point in time when this function is called.

getBlocked

Gets current value of property blocked.

Whether the control is currently in blocked state.

Default value is false.

Since 1.69 The blocked property is deprecated. There is no accessibility support for this property. Blocked controls should not be used inside Controls, which rely on keyboard navigation, e.g. List controls.

getBusy

Gets current value of property busy.

Whether the control is currently in busy state.

Default value is false.

getBusyIndicatorDelay

Gets current value of property busyIndicatorDelay.

The delay in milliseconds, after which the busy indicator will show up for this control.

Default value is 1000.

getBusyIndicatorSize

Gets current value of property busyIndicatorSize.

The size of the BusyIndicator. For controls with a width smaller 3rem a sap.ui.core.BusyIndicatorSize.Small should be used. If the size could vary in width and the width could get smaller than 3rem, the sap.ui.core.BusyIndicatorSize.Auto option could be used. The default is set to sap.ui.core.BusyIndicatorSize.Medium For a full screen BusyIndicator use sap.ui.core.BusyIndicatorSize.Large.

Default value is 'Medium'.

getControlsByFieldGroupId

Returns a list of all child controls with a field group ID. See checkFieldGroupIds for a description of the vFieldGroupIds parameter. Associated controls are not taken into account.

Param Type DefaultValue Description
vFieldGroupIds string string[]

ID of the field group or an array of field group IDs to match

getFieldGroupIds

Returns a copy of the field group IDs array. Modification of the field group IDs need to call setFieldGroupIds to apply the changes.

getIdForLabel

Returns the DOMNode Id to be used for the "labelFor" attribute of the label.

By default, this is the Id of the control itself.

sap.ui.core.Control.getMetadata

Returns a metadata object for class sap.ui.core.Control.

getRenderer

Returns a renderer for this control instance.

It is retrieved using the RenderManager as done during rendering.

getVisible

Gets current value of property visible.

Whether the control should be visible on the screen.

If set to false, a placeholder will be rendered to mark the location of the invisible control in the DOM of the current page. The placeholder will be hidden and have zero dimensions (display: none).

Also see InvisibleRenderer.

Default value is true.

hasStyleClass

Returns true if the given style class or all multiple style classes which are generated by splitting the given string with space are already set on the control via previous call(s) to addStyleClass().

Param Type DefaultValue Description
sStyleClass string

the style to check for

invalidate

Marks this control and its children for a re-rendering, usually because its state has changed and now differs from the rendered DOM.

Managed settings (properties, aggregations, associations) automatically invalidate the corresponding object. Changing the state via the standard mutators, therefore, does not require an explicit call to invalidate.

By default, all invalidations are buffered and processed together (asynchronously) in a new browser task.

The oOrigin parameter was introduced to allow parent controls to limit their re-rendering to certain areas that have been invalidated by their children. As there is no strong guideline for control developers whether or not to provide the parameter, it is not a reliable source of information. It is, therefore, not recommended in general to use it, only in scenarios where a control and its descendants know each other very well (e.g. complex controls where parent and children have the same code owner).

Param Type DefaultValue Description
oOrigin sap.ui.base.ManagedObject

Child control for which the method was called

isBusy

Check if the control is currently in busy state.

Since 1.15 use {@link #getBusy} instead

onAfterRendering

Function is called when the rendering of the control is completed.

Applications must not call this hook method directly, it is called by the framework.

Subclasses of Control should override this hook to implement any necessary actions after the rendering.

Param Type DefaultValue Description
oEvent jQuery.Event

onAfterRendering event object

onBeforeRendering

Function is called before the rendering of the control is started.

Applications must not call this hook method directly, it is called by the framework.

Subclasses of Control should override this hook to implement any necessary actions before the rendering.

Param Type DefaultValue Description
oEvent jQuery.Event

onBeforeRendering event object

placeAt

Puts this control into the specified container (oRef) at the given position (oPosition).

First it is checked whether oRef is a container element / control (has a multiple aggregation with type sap.ui.core.Control and name 'content') or is an Id String of such a container. If this is not the case oRef can either be a Dom Reference or Id String of the UIArea (if it does not yet exist implicitly a new UIArea is created),

The oPosition can be one of the following:

Param Type DefaultValue Description
oRef string Element sap.ui.core.Control

container into which the control should be put

vPosition string int "last"

Describes the position where the control should be put into the container

removeStyleClass

Removes the given string from the list of custom style classes that have been set previously. Regular style classes like "sapUiBtn" cannot be removed.

Param Type DefaultValue Description
sStyleClass string

the style to be removed

rerender

Synchronously updates the DOM of this control to reflect the current object state.

Note that this method can only be called when the control already has a DOM representation (it has been rendered before) and when the control still is assigned to a UIArea.

Since 1.70 using this method is no longer recommended, but still works. Synchronous DOM updates via this method have several drawbacks: they only work when the control has been rendered before (no initial rendering possible), multiple state changes won't be combined automatically into a single re-rendering, they might cause additional layout trashing, standard invalidation might cause another async re-rendering. The recommended alternative is to rely on invalidation and standard re-rendering.

setBlocked

Set the controls block state.

Param Type DefaultValue Description
bBlocked boolean

The new blocked state to be set

setBusy

Set the controls busy state.

Note: The busy state can't be set on controls (e.g. sap.m.ColumnListItem) which renderings have the following tags as DOM root element: area|base|br|col|embed|hr|img|input|keygen|link|menuitem|meta|param|source|track|wbr|tr

Param Type DefaultValue Description
bBusy boolean

The new busy state to be set

setBusyIndicatorDelay

Define the delay, after which the busy indicator will show up.

Param Type DefaultValue Description
iDelay int

The delay in ms

setBusyIndicatorSize

Sets a new value for property busyIndicatorSize.

The size of the BusyIndicator. For controls with a width smaller 3rem a sap.ui.core.BusyIndicatorSize.Small should be used. If the size could vary in width and the width could get smaller than 3rem, the sap.ui.core.BusyIndicatorSize.Auto option could be used. The default is set to sap.ui.core.BusyIndicatorSize.Medium For a full screen BusyIndicator use sap.ui.core.BusyIndicatorSize.Large.

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

Default value is 'Medium'.

Param Type DefaultValue Description
sBusyIndicatorSize sap.ui.core.BusyIndicatorSize 'Medium'

New value for property busyIndicatorSize

setFieldGroupIds

Sets a new value for property fieldGroupIds.

The IDs of a logical field group that this control belongs to.

All fields in a logical field group should share the same fieldGroupId. Once a logical field group is left, the validateFieldGroup event is fired.

For backward compatibility with older releases, field group IDs are syntactically not limited, but it is suggested to use only valid sap.ui.core.IDs.

See #attachValidateFieldGroup or consult the Field Group documentation.

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

Default value is [].

Param Type DefaultValue Description
sFieldGroupIds string[] []

New value for property fieldGroupIds

setVisible

Sets a new value for property visible.

Whether the control should be visible on the screen.

If set to false, a placeholder will be rendered to mark the location of the invisible control in the DOM of the current page. The placeholder will be hidden and have zero dimensions (display: none).

Also see InvisibleRenderer.

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

Default value is true.

Param Type DefaultValue Description
bVisible boolean true

New value for property visible

toggleStyleClass

The string given as "sStyleClass" will be be either added to or removed from the "class" attribute of this control's root HTML element, depending on the value of "bAdd": if bAdd is true, sStyleClass will be added. If bAdd is not given, sStyleClass will be removed if it is currently present and will be added if not present. If sStyleClass is null or empty string, the call is ignored.

See addStyleClass and removeStyleClass for further documentation.

Param Type DefaultValue Description
sStyleClass string

the CSS class name to be added or removed

bAdd boolean

whether sStyleClass should be added (or removed); when this parameter is not given, sStyleClass will be toggled (removed, if present, and added if not present)

triggerValidateFieldGroup

Triggers the validateFieldGroup event for this control.

Called by sap.ui.core.UIArea if a field group should be validated after it lost the focus or when the key combination was pressed that was configured to trigger validation.

By default, the RETURN key without any modifier keys triggers validation. There's no public API to change that key combination.

See #attachValidateFieldGroup.

Param Type DefaultValue Description
aFieldGroupIds string[]

IDs of the field groups that should be validated