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

extends Element
known direct subclasses: AbsoluteLayout, Accordion, ActionBar, ActionSheet, ApplicationHeader, Bar, BlockBase, BlockLayout, BlockLayoutCell, BlockLayoutRow, BorderLayout, BreadCrumbs, Breadcrumbs, BusyDialog, BusyIndicator, Button, Button, Calendar, CalendarLegend, CalendarMonthInterval, CalendarRow, CalendarTimeInterval, Carousel, Carousel, CheckBox, CheckBox, CollectionInspector, ColorPicker, ComponentContainer, ContentSwitcher, Currency, DOMElement, DataSet, DataSetSimpleView, DateTimeInput, Dialog, Dialog, DraftIndicator, DynamicSideContent, Exact, ExactArea, ExactBrowser, Export, FacetFilter, FacetFilter, FacetFilterList, Feed, FeedChunk, FeedContent, FeedInput, Feeder, FileUploader, FixFlex, FlexBox, Form, FormLayout, FormattedText, FormattedTextView, GenericTile, Grid, HTML, Header, 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, ResponsiveContainerRange, ResponsiveFlowLayout, ResponsivePopover, ResponsiveSplitter, RoadMap, RowRepeater, ScrollBar, ScrollContainer, SearchField, SearchField, SegmentedButton, SegmentedButton, Select, SelectDialog, SelectList, SemanticPage, Shell, Shell, ShellLayout, ShellOverlay, SideNavigation, SimpleForm, SlideTile, Slider, Slider, SplitContainer, SplitContainer, Splitter, Splitter, SuggestionItem, Switch, TabContainer, TabStrip, Table, TableSelectDialog, TaskCircle, TemplateControl, Text, TextField, TextView, ThingViewer, Tile, TileContainer, TileContent, TimesRow, Title, Token, Tokenizer, 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(mArguments?)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.

The set of allowed entries in the mSettings object depends on the concrete subclass and is described there. See sap.ui.core.Element for a general description of this argument.

The settings supported by Control are:

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:
{string}sId? 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!
{object}mSettings? optional map/JSON-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.
Parameters:
{sap.ui.base.Event}oControlEvent
{sap.ui.base.EventProvider}oControlEvent.getSource
{object}oControlEvent.getParameters
{string[]}oControlEvent.getParameters.fieldGroupIds field 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:
{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.core.Control.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.ui.core.Control.
Returns:
{sap.ui.base.Metadata} Metadata 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:
{string}sStyleClass the CSS class name to be added
Returns:
{sap.ui.core.Control} Returns 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:
{boolean}bAllow whether to allow text selection or not
Returns:
{sap.ui.core.Control} Returns 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 Control.addStyleClass() instead if the modification is of visual nature.

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

Parameters:
{string}sEventType? A string containing one or more JavaScript event types, such as "click" or "blur".
{function}fnHandler? A function to execute each time the event is triggered.
{object}oListener? The object, that wants to be notified, when the event occurs
Returns:
{sap.ui.core.Control} Returns 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.

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.core.Control itself
Returns:
{sap.ui.core.Control} Reference 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 seperate 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:
{boolean} true 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:
{string}sIdSuffix? 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.Element} reference 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:
{string}sEventType? A string containing one or more JavaScript event types, such as "click" or "blur".
{function}fnHandler? The function that is to be no longer executed.
{object}oListener? 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:
{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.core.Control} Reference to this in order to allow method chaining
fireValidateFieldGroup(mArguments?): sap.ui.core.Control
Fires event validateFieldGroup to attached listeners.

Expects the following event parameters:

  • fieldGroupIds of type string[]field group IDs of the logical field groups to validate
Parameters:
{Map}mArguments? The arguments to pass along with the event
Returns:
{sap.ui.core.Control} Reference 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: []          // Array of accessibility info objects of children of the given control (e.g. when the control is a layout).
                           // 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.

Since:
1.37.0
Returns:
{object} Current accessibility state of the control.
getBusy(): boolean
Gets current value of property busy.

Whether the control is currently in busy state.

Default value is false.

Returns:
{boolean} Value 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:
{int} Value 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:
{string} Id 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:
{object} a 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:
{boolean} Value 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:
{string}sStyleClass the 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.

Parameters:
{object}oOrigin
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.Control}oRef container into which the control should be put
{string|int}oPosition Describes the position where the control should be put into the container
Returns:
{sap.ui.core.Control} Returns 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:
{string}sStyleClass the style to be removed
Returns:
{sap.ui.core.Control} Returns 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:
{boolean}bBusy The new busy state to be set
Returns:
{sap.ui.core.Control}this to allow method chaining
setBusyIndicatorDelay(iDelay): sap.ui.core.Control
Define the delay, after which the busy indicator will show up
Parameters:
{int}iDelay The delay in ms
Returns:
{sap.ui.core.Control}this 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.

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

Default value is [].

Parameters:
{string[]}sFieldGroupIds New value for property fieldGroupIds
Since:
1.31
Returns:
{sap.ui.core.Control} Reference to this in order to allow method chaining
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:
{boolean}bVisible New value for property visible
Returns:
{sap.ui.core.Control} Reference 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:
{string}sStyleClass the CSS class name to be added or removed
{boolean}bAdd 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)
Returns:
{sap.ui.core.Control} Returns 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 is loses the focus or a validation key combibation was pressed. The validation key is defined in the UI area UIArea._oFieldGroupValidationKey
See:
{sap.ui.core.Control.attachValidateFieldGroup}
isBusy()
Check if the control is currently in busy state
Deprecated:
Use getBusy instead