Abstract Class sap.ui.core.ControlModule: sap/ui/core/Control

extends Element
known direct subclasses: AbsoluteLayout, Accordion, ActionBar, ActionSheet, ApplicationHeader, Avatar, Bar, BlockBase, BlockLayout, BlockLayoutCell, BlockLayoutRow, BorderLayout, BreadCrumbs, Breadcrumbs, BusyDialog, BusyIndicator, Button, Button, Calendar, CalendarLegend, CalendarMonthInterval, CalendarRow, CalendarTimeInterval, Carousel, Carousel, CheckBox, CheckBox, CodeEditor, CollectionInspector, ColorPicker, ComponentContainer, ContentSwitcher, Currency, DOMElement, DataSet, DataSetSimpleView, DateTimeInput, Dialog, Dialog, DraftIndicator, DynamicPage, DynamicPageHeader, DynamicPageTitle, DynamicSideContent, Exact, ExactArea, ExactBrowser, Export, FacetFilter, FacetFilter, FacetFilterList, Feed, FeedChunk, FeedContent, FeedInput, Feeder, FileUploader, FixFlex, FlexBox, FlexibleColumnLayout, Form, FormLayout, FormattedText, FormattedTextView, GenericTile, Grid, HTML, Header, HeaderContainer, HorizontalDivider, HorizontalLayout, Icon, IconTabBar, IconTabHeader, Image, Image, ImageContent, ImageMap, InPlaceEdit, InputBase, InvisibleText, Label, Label, Link, Link, ListBase, ListBox, ListItemBase, LocalBusyIndicator, MatrixLayout, Menu, Menu, MenuBar, MenuButton, Message, MessageBar, MessageList, MessagePage, MessagePopover, MessageStrip, MessageToast, Month, MonthPicker, MonthsRow, NavContainer, NavigationBar, NavigationList, NewsContent, NotificationBar, NumericContent, ObjectAttribute, ObjectHeader, ObjectIdentifier, ObjectMarker, ObjectNumber, ObjectPageHeader, ObjectPageHeaderContent, ObjectPageLayout, ObjectPageLazyLoader, ObjectPageSectionBase, ObjectStatus, Overlay, P13nConditionPanel, P13nPanel, Page, Paginator, PagingButton, Panel, Panel, PlanningCalendar, Popover, ProgressIndicator, ProgressIndicator, PullToRefresh, QuickViewBase, QuickViewPage, RadioButton, RadioButton, RadioButtonGroup, RadioButtonGroup, RatingIndicator, RatingIndicator, ResponsiveContainer, ResponsiveFlowLayout, ResponsivePopover, ResponsiveSplitter, RoadMap, RowAction, RowRepeater, ScrollBar, ScrollContainer, SearchField, SearchField, SegmentedButton, SegmentedButton, Select, SelectDialog, SelectList, SemanticPage, SemanticPage, Shell, Shell, ShellLayout, ShellOverlay, SideNavigation, SimpleForm, SlideTile, Slider, Slider, SplitContainer, SplitContainer, Splitter, Splitter, StepInput, Switch, TabContainer, TabStrip, Table, TableSelectDialog, TaskCircle, TemplateControl, Text, TextField, TextView, ThingViewer, Tile, TileContainer, TileContent, TimesRow, Title, ToolHeaderUtilitySeparator, ToolPage, ToolPopup, Toolbar, Toolbar, ToolbarSeparator, ToolbarSpacer, TooltipBase, Tree, TriStateCheckBox, UploadCollection, UploadCollectionToolbarPlaceholder, VerticalLayout, VerticalProgressIndicator, View, ViewSettingsDialog, Wizard, WizardStep, YearPicker

Base Class for Controls.
Constructor Summary
new sap.ui.core.Control(sId?, mSettings?)Creates and initializes a new control with the given sId and settings.
Event Summary
validateFieldGroup(oControlEvent)Event is fired if a logical field group defined by fieldGroupIds of a control was left or the user explicitly pressed a validation key combination.
Method Summary
sap.ui.core.Control.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.ui.core.Control with name sClassName and enriches it with the information contained in oClassInfo.
sap.ui.core.Control.getMetadata()Returns a metadata object for class sap.ui.core.Control.
addStyleClass(sStyleClass)The string given as "sStyleClass" will be added to the "class" attribute of this control's root HTML element.
allowTextSelection(bAllow)Defines whether the user can select text inside this control.
attachBrowserEvent(sEventType?, fnHandler?, oListener?)Allows binding handlers for any native browser event to the root HTML element of this Control.
attachValidateFieldGroup(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the validateFieldGroup event of this sap.ui.core.Control.
checkFieldGroupIds(vFieldGroupIds?)Returns whether the control has a given field group.
clone(sIdSuffix?, aLocalIds?)Overrides Element.clone to clone additional internal state.
detachBrowserEvent(sEventType?, fnHandler?, oListener?)Removes event handlers which have been previously attached using attachBrowserEvent.
detachValidateFieldGroup(fnFunction, oListener)Detaches event handler fnFunction from the validateFieldGroup event of this sap.ui.core.Control.
fireValidateFieldGroup(mParameters?)Fires event validateFieldGroup to attached listeners.
getAccessibilityInfo()This function (if available on the concrete control) provides the current accessibility state of the control.
getBusy()Gets current value of property busy.
getBusyIndicatorDelay()Gets current value of property busyIndicatorDelay.
getControlsByFieldGroupId(vFieldGroupIds?)Returns a list of all child controls with a field group ID.
getFieldGroupIds()Returns a copy of the field group IDs array.
getIdForLabel()Returns the DOMNode Id to be used for the "labelFor" attribute of the label.
getRenderer()Returns a renderer for this control instance.
getVisible()Gets current value of property visible.
hasStyleClass(sStyleClass)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(oOrigin?)Triggers rerendering of this element and its children.
onAfterRendering()Function is called when the rendering of the control is completed.
onBeforeRendering()Function is called before the rendering of the control is started.
placeAt(oRef, oPosition)Puts this control into the specified container (oRef) at the given position (oPosition).
removeStyleClass(sStyleClass)Removes the given string from the list of custom style classes that have been set previously.
rerender()Tries to replace its DOM reference by re-rendering.
setBusy(bBusy)Set the controls busy state.
setBusyIndicatorDelay(iDelay)Define the delay, after which the busy indicator will show up.
setFieldGroupIds(sFieldGroupIds)Sets a new value for property fieldGroupIds.
setVisible(bVisible)Sets a new value for property visible.
toggleStyleClass(sStyleClass, bAdd)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.
triggerValidateFieldGroup()Triggers the validateFieldGroup event for this control.
isBusy()Check if the control is currently in busy state.
Constructor Detail
new sap.ui.core.Control(sId?, mSettings?)

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

The supported settings are:

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

Parameters:
stringsId?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!
objectmSettings?Object with initial settings for the new control
Event Detail
validateFieldGroup(oControlEvent)
Event is fired if a logical field group defined by fieldGroupIds of a control was left or the user explicitly pressed a validation key combination. Use this event to validate data of the controls belonging to a field group. See sap.ui.core.Control#setFieldGroupIds.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
string[]oControlEvent.getParameters.fieldGroupIdsfield group IDs of the logical field groups to validate
Method Detail
sap.ui.core.Control.extend(sClassName, oClassInfo?, FNMetaImpl?): function

Creates a new subclass of class sap.ui.core.Control 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.Element.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.core.Control.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.core.Control.
Returns:
sap.ui.base.MetadataMetadata object describing this class
addStyleClass(sStyleClass): sap.ui.core.Control

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.

Parameters:
stringsStyleClassthe CSS class name to be added
Returns:
sap.ui.core.ControlReturns this to allow method chaining
allowTextSelection(bAllow): sap.ui.core.Control

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 IE and Safari; for Firefox the element's style must be set to:

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

Parameters:
booleanbAllowwhether to allow text selection or not
Returns:
sap.ui.core.ControlReturns this to allow method chaining
attachBrowserEvent(sEventType?, fnHandler?, oListener?): sap.ui.core.Control

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 sap.ui.core.Control#addStyleClass instead if the modification is of visual nature.

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

Parameters:
stringsEventType?A string containing one or more JavaScript event types, such as "click" or "blur".
functionfnHandler?A function to execute each time the event is triggered.
objectoListener?The object, that wants to be notified, when the event occurs
Returns:
sap.ui.core.ControlReturns this to allow method chaining
attachValidateFieldGroup(oData?, fnFunction, oListener?): sap.ui.core.Control

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 the user explicitly pressed a validation key combination. Use this event to validate data of the controls belonging to a field group. See sap.ui.core.Control#setFieldGroupIds.

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.core.Control itself
Returns:
sap.ui.core.ControlReference to this in order to allow method chaining
checkFieldGroupIds(vFieldGroupIds?): boolean
Returns whether the control has a given field group. If vFieldGroupIds is not given it checks whether at least one field group ID is given for this control. If vFieldGroupIds is an empty array or empty string, true is returned if there is no field group ID set for this control. If vFieldGroupIds is a string array or a string all expected field group IDs are checked and true is returned if all are contained for given for this control. The comma delimiter can be used to separate multiple field group IDs in one string.
Parameters:
string|string[]vFieldGroupIds?ID of the field group or an array of field group IDs to match
Returns:
booleantrue if a field group ID matches
clone(sIdSuffix?, aLocalIds?): sap.ui.core.Element

Overrides Element.clone to clone additional internal state.

The additionally cloned information contains:

Parameters:
stringsIdSuffix?a suffix to be appended to the cloned element id
string[]aLocalIds?an array of local IDs within the cloned hierarchy (internally used)
Returns:
sap.ui.core.Elementreference to the newly created clone
detachBrowserEvent(sEventType?, fnHandler?, oListener?)

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.

Parameters:
stringsEventType?A string containing one or more JavaScript event types, such as "click" or "blur".
functionfnHandler?The function that is to be no longer executed.
objectoListener?The context object that was given in the call to attachBrowserEvent.
detachValidateFieldGroup(fnFunction, oListener): sap.ui.core.Control

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.ui.core.ControlReference to this in order to allow method chaining
fireValidateFieldGroup(mParameters?): sap.ui.core.Control
Fires event validateFieldGroup to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
string[]mParameters.fieldGroupIds?field group IDs of the logical field groups to validate
Returns:
sap.ui.core.ControlReference to this in order to allow method chaining
getAccessibilityInfo(): object

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.

Returns:
objectCurrent accessibility state of the control.
Since:
1.37.0
getBusy(): boolean

Gets current value of property busy.

Whether the control is currently in busy state.

Default value is false.

Returns:
booleanValue of property busy
getBusyIndicatorDelay(): int

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.

Returns:
intValue of property busyIndicatorDelay
getControlsByFieldGroupId(vFieldGroupIds?): sap.ui.core.Control[]
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.
Parameters:
string|string[]vFieldGroupIds?ID of the field group or an array of field group IDs to match
Returns:
sap.ui.core.Control[]The list of controls with a field group ID
getFieldGroupIds(): string[]
Returns a copy of the field group IDs array. Modification of the field group IDs need to call setFieldGroupIds to apply the changes.
Returns:
string[]copy of the field group IDs
getIdForLabel(): string

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

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

Returns:
stringId to be used for the labelFor
getRenderer(): object

Returns a renderer for this control instance.

It is retrieved using the RenderManager as done during rendering.

Returns:
objecta Renderer suitable for this Control instance.
getVisible(): boolean

Gets current value of property visible.

Whether the control should be visible on the screen. If set to false, a placeholder is rendered instead of the real control

Default value is true.

Returns:
booleanValue of property visible
hasStyleClass(sStyleClass): boolean
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().
Parameters:
stringsStyleClassthe style to check for
Returns:
boolean
invalidate(oOrigin?)

Triggers rerendering of this element and its children.

As sap.ui.core.Element "bubbles up" the invalidate, changes to children potentially result in rerendering of the whole sub tree.

The oOrigin parameter was introduced to allow parent controls to limit their rerendering to certain areas that have been invalidated by their children. As there is no strong guideline for control developers 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).

Parameters:
sap.ui.base.ManagedObjectoOrigin?Child control for which the method was called
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(oRef, oPosition): sap.ui.core.Control

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 an 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.
Parameters:
string|Element|sap.ui.core.ControloRefcontainer into which the control should be put
string|intoPositionDescribes the position where the control should be put into the container
Returns:
sap.ui.core.ControlReturns this to allow method chaining
removeStyleClass(sStyleClass): sap.ui.core.Control
Removes the given string from the list of custom style classes that have been set previously. Regular style classes like "sapUiBtn" cannot be removed.
Parameters:
stringsStyleClassthe style to be removed
Returns:
sap.ui.core.ControlReturns this to allow method chaining
rerender()
Tries to replace its DOM reference by re-rendering.
setBusy(bBusy): sap.ui.core.Control
Set the controls busy state.
Parameters:
booleanbBusyThe new busy state to be set
Returns:
sap.ui.core.Controlthis to allow method chaining
setBusyIndicatorDelay(iDelay): sap.ui.core.Control
Define the delay, after which the busy indicator will show up.
Parameters:
intiDelayThe delay in ms
Returns:
sap.ui.core.Controlthis to allow method chaining
setFieldGroupIds(sFieldGroupIds): sap.ui.core.Control

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

See sap.ui.core.Control#attachValidateFieldGroup.

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

Default value is [].

Parameters:
string[]sFieldGroupIdsNew value for property fieldGroupIds
Returns:
sap.ui.core.ControlReference to this in order to allow method chaining
Since:
1.31
setVisible(bVisible): sap.ui.core.Control

Sets a new value for property visible.

Whether the control should be visible on the screen. If set to false, a placeholder is rendered instead of the real control

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

Default value is true.

Parameters:
booleanbVisibleNew value for property visible
Returns:
sap.ui.core.ControlReference to this in order to allow method chaining
toggleStyleClass(sStyleClass, bAdd): sap.ui.core.Control

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.

Parameters:
stringsStyleClassthe CSS class name to be added or removed
booleanbAddwhether sStyleClass should be added (or removed); when this parameter is not given, sStyleClass will be toggled (removed, if present, and added if not present)
Returns:
sap.ui.core.ControlReturns this to allow method chaining
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 (defined in the UI area member UIArea._oFieldGroupValidationKey).

See attachValidateFieldGroup.

isBusy()
Check if the control is currently in busy state.
Deprecated API:
As of 1.15, use getBusy instead