Base Class for UI Elements.
Element
is the most basic building block for UI5 UIs. An Element
has state like a ManagedObject
, it has a unique ID by which the framework remembers it. It can have associated DOM, but it can't render itself. Only Controls can render themselves and also take care of rendering Elements
that they aggregate as children. If an Element
has been rendered, its related DOM gets the same ID as the Element
and thereby can be retrieved via API. When the state of an Element
changes, it informs its parent Control
which usually re-renders then.
The UI5 framework already registers generic listeners for common browser events, such as click
or keydown
. When called, the generic listener first determines the corresponding target element using jQuery#control. Then it checks whether the element has an event handler method for the event. An event handler method by convention has the same name as the event, but prefixed with "on": Method onclick
is the handler for the click
event, method onkeydown
the handler for the keydown
event and so on. If there is such a method, it will be called with the original event as the only parameter. If the element has a list of delegates registered, their handler functions will be called the same way, where present. The set of implemented handlers might differ between element and delegates. Not each handler implemented by an element has to be implemented by its delegates, and delegates can implement handlers that the corresponding element doesn't implement.
A list of browser events that are handled that way can be found in module:sap/ui/events/ControlEvents. Additionally, the framework dispatches pseudo events (module:sap/ui/events/PseudoEvents) using the same naming convention. Last but not least, some framework events are also dispatched that way, e.g. BeforeRendering
, AfterRendering
(only for controls) and ThemeChanged
.
If further browser events are needed, controls can register listeners on the DOM using native APIs in their onAfterRendering
handler. If needed, they can do this for their aggregated elements as well. If events might fire often (e.g. mousemove
), it is best practice to register them only while needed, and deregister afterwards. Anyhow, any registered listeners must be cleaned up in the onBeforeRendering
listener and before destruction in the exit
hook.
Constructs and initializes a UI Element with the given sId
and settings.
Each Element
must have an ID. If no sId
or mSettings.id
is given at construction time, a new ID will be created automatically. The IDs of all elements that exist at the same time in the same window must be different. Providing an ID which is already used by another element throws an error.
When an element is created from a declarative source (e.g. XMLView), then an ID defined in that declarative source needs to be unique only within the declarative source. Declarative views will prefix that ID with their own ID (and some separator) before constructing the element. Programmatically created views (JSViews) can do the same with the sap.ui.core.mvc.View#createId API. Similarly, UIComponents can prefix the IDs of elements created in their context with their own ID. Also see UIComponent#getAutoPrefixId.
If the optional mSettings
are given, they must be a JSON-like object (object literal) that defines values for properties, aggregations, associations or events keyed by their name.
Valid Names:
The property (key) names supported in the object literal are exactly the (case sensitive) names documented in the JSDoc for the properties, aggregations, associations and events of the control and its base classes. Note that for 0..n aggregations and associations this usually is the plural name, whereas it is the singular name in case of 0..1 relations.
Each subclass should document the set of supported names in its constructor documentation.
Valid Values:
Special aggregation dependents
is connected to the lifecycle management and databinding, but not rendered automatically and can be used for popups or other dependent controls or elements. This allows the definition of popup controls in declarative views and enables propagation of model and context information to them.
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.Element(sId?, mSettings?)
Param | Type | Default Value | Description |
---|---|---|---|
sId? | string | id for the new control; generated automatically if no non-empty id is given Note: this can be omitted, no matter whether |
|
mSettings? | object | optional map/JSON-object with initial property values, aggregated objects etc. for the new element |
Default Aggregation:
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. |
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. |
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, 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. Alternatively, UI5 currently does not provide a recommended implementation of See the section Using Tooltips
|
Method | Description |
---|---|
$ |
Returns the best suitable DOM node that represents this Element wrapped as jQuery object. I.e. the element returned by sap.ui.core.Element#getDomRef is wrapped and returned. If an ID suffix is given, the ID of this Element is concatenated with the suffix (separated by a single dash) and the DOM node with that compound ID will be wrapped by jQuery. This matches the UI5 naming convention for named inner DOM nodes of a control. |
_attachMediaContainerWidthChange |
Registers the given event handler to change events of the screen width/closest media container width, based on the range set with the given |
_detachMediaContainerWidthChange |
Removes a previously attached event handler from the change events of the screen width/closest media container width. |
_getCurrentMediaContainerRange |
Returns the current media range of the Device or the closest media container |
_getMediaContainerWidth |
Returns the contextual width of an element, if set, or |
sap.ui.core.Element._interceptEvent |
Intercepts an event. This method is meant for private usages. Apps are not supposed to used it. It is created for an experimental purpose. Implementation should be injected by outside. |
addCustomData |
Adds some customData to the aggregation customData. |
addDependent |
Adds some dependent to the aggregation dependents. |
addDragDropConfig |
Adds some dragDropConfig to the aggregation dragDropConfig. |
addEventDelegate |
Adds a delegate that can listen to the browser-, pseudo- and framework events that are handled by this Delegates are simple objects that can have an arbitrary number of event handler methods. See the section "Handling of Events" in the #constructor documentation to learn how events will be dispatched and how event handler methods have to be named to be found. If multiple delegates are registered for the same element, they will be called in the order of their registration. Double registrations are prevented. Before a delegate is added, all registrations of the same delegate (no matter what value for When an element is cloned, all its event delegates will be added to the clone. This behavior is well-suited for applications which want to add delegates that also work with templates in aggregation bindings. For control development, the internal Important: If event delegates were added, the delegate will still be called even if the event was processed and/or cancelled via See Event Handler Methods for a general explanation of event handling in controls. |
applyFocusInfo |
Applies the focus info. To be overwritten by the specific control method. |
bindElement |
Bind the object to the referenced entity in the model, which is used as the binding context to resolve bound properties or aggregations of the object itself and all of its children relatively to the given path. If a relative binding path is used, this will be applied whenever the parent context changes. There's no difference between |
clone |
Create a clone of this Element. Calls sap.ui.base.ManagedObject#clone and additionally clones event delegates. |
sap.ui.core.Element.create |
Creates a new Element from the given data. If
Since 1.44 use the more flexible {@link sap.ui.base.ManagedObject.create}.
|
data |
Retrieves, modifies or removes custom data attached to an Usages: Setting the value for a single key
data("myKey", myData)Attaches myData (which can be any JS data type, e.g. a number, a string, an object, or a function) to this element, under the given key "myKey". If the key already exists,the value will be updated.Setting a value for a single key (rendered to the DOM)
data("myKey", myData, writeToDom)Attaches myData to this element, under the given key "myKey" and (if writeToDom is true) writes key and value to the HTML. If the key already exists,the value will be updated. While oValue can be any JS data type to be attached, it must be a string to be also written to DOM. The key must also be a valid HTML attribute name (it must conform to sap.ui.core.ID and may contain no colon) and may not start with "sap-ui". When written to HTML, the key is prefixed with "data-".Getting the value for a single key
data("myKey")Retrieves whatever data has been attached to this element (using the key "myKey") before. Removing the value for a single key
data("myKey", null)Removes whatever data has been attached to this element (using the key "myKey") before. Removing all custom data for all keys
data(null) Getting all custom data values as a plain object
data()Returns all data, as a map-like object, property names are keys, property values are values. Setting multiple key/value pairs in a single call
data({"myKey1": myData, "myKey2": null})Attaches myData (using the key "myKey1" and removes any data that had been attached for key "myKey2".References:
|
sap.ui.core.Element.defineClass |
Creates metadata for a UI Element by extending the Object Metadata.
Since 1.3.1 Use the static <code>extend</code> method of the desired base class (e.g. {@link sap.ui.core.Element.extend})
|
destroy |
Cleans up the resources associated with this element and all its children. After an element has been destroyed, it can no longer be used in the UI! Applications should call this method if they don't need the element any longer. |
destroyCustomData |
Destroys all the customData in the aggregation customData. |
destroyDependents |
Destroys all the dependents in the aggregation dependents. |
destroyDragDropConfig |
Destroys all the dragDropConfig in the aggregation dragDropConfig. |
destroyLayoutData |
Destroys the layoutData in the aggregation layoutData. |
destroyTooltip |
Destroys the tooltip in the aggregation named |
enhanceAccessibilityState |
Allows the parent of a control to enhance the ARIA information during rendering. This function is called by the RenderManager's accessibilityState and writeAccessibilityState methods for the parent of the currently rendered control - if the parent implements it. |
exit |
Hook method for cleaning up the element instance before destruction. Applications must not call this hook method directly, it is called by the framework when the element is destroyed. Subclasses of Element should override this hook to implement any necessary cleanup. exit: function() { // ... do any further cleanups of your subclass e.g. detach events... this.$().off("click", this.handleClick); if (Element.prototype.exit) { Element.prototype.exit.apply(this, arguments); } } For a more detailed description how to to use the exit hook, see Section exit() Method in the documentation. |
sap.ui.core.Element.extend |
Defines a new subclass of Element with the name
Example: Element.extend('sap.mylib.MyElement', { metadata : { library : 'sap.mylib', properties : { value : 'string', width : 'sap.ui.core.CSSSize' }, dnd : { draggable: true, droppable: false }, aggregations : { items : { type: 'sap.ui.core.Control', multiple : true, dnd : {draggable: false, dropppable: true, layout: "Horizontal" } }, header : {type : "sap.ui.core.Control", multiple : false, dnd : true }, } } });
|
findElements |
Searches and returns an array of child elements and controls which are referenced within an aggregation or aggregations of child elements/controls. This can be either done recursive or not. Take care: this operation might be expensive. |
focus |
Sets the focus to the stored focus DOM reference. |
getCustomData |
Gets content of aggregation customData. Custom Data, a data structure like a map containing arbitrary key value pairs. |
getDependents |
Gets content of aggregation dependents. Dependents are not rendered, but their databinding context and lifecycle are bound to the aggregating Element. |
getDomRef |
Returns the best suitable DOM Element that represents this UI5 Element. By default the DOM Element with the same ID as this Element is returned. Subclasses should override this method if the lookup via id is not sufficient. Note that such a DOM Element does not necessarily exist in all cases. Some elements or controls might not have a DOM representation at all (e.g. a naive FlowLayout) while others might not have one due to their current state (e.g. an initial, not yet rendered control). If an ID suffix is given, the ID of this Element is concatenated with the suffix (separated by a single dash) and the DOM node with that compound ID will be returned. This matches the UI5 naming convention for named inner DOM nodes of a control. |
getDomRefForSetting |
Returns a DOM Element representing the given property or aggregation of this Check the documentation for the The default implementation of this method will return
Subclasses can override this method to handle more complex cases which can't be described by a CSS selector. |
getDragDropConfig |
Gets content of aggregation dragDropConfig. Defines the drag-and-drop configuration. Note: This configuration might be ignored due to control metadata restrictions. |
getElementBinding |
Get the context binding object for a specific model name. Note: to be compatible with future versions of this API, you must not use the following model names:
undefined ) is explicitly allowed and refers to the default model.
|
getFocusDomRef |
Returns the DOM Element that should get the focus. To be overwritten by the specific control method. |
getFocusInfo |
Returns an object representing the serialized focus information. To be overwritten by the specific control method. |
getInterface |
Elements don't have a facade and therefore return themselves as their interface.
|
getLayoutData |
Gets content of aggregation 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. |
getMetadata |
Returns the runtime metadata for this UI element. When using the defineClass method, this function is automatically created and returns a runtime representation of the design time metadata. |
sap.ui.core.Element.getMetadata |
Returns a metadata object for class sap.ui.core.Element. |
getTooltip |
Returns the tooltip for this element if any or an undefined value. The tooltip can either be a simple string or a subclass of sap.ui.core.TooltipBase. Callers that are only interested in tooltips of type string (e.g. to render them as a |
getTooltip_AsString |
Returns the tooltip for this element but only if it is a simple string. Otherwise an undefined value is returned. |
getTooltip_Text |
Returns the main text for the current tooltip or undefined if there is no such text. If the tooltip is an object derived from sap.ui.core.Tooltip, then the text property of that object is returned. Otherwise the object itself is returned (either a string or undefined or null). |
indexOfCustomData |
Checks for the provided |
indexOfDependent |
Checks for the provided |
indexOfDragDropConfig |
Checks for the provided |
init |
Initializes the element instance after creation. Applications must not call this hook method directly, it is called by the framework while the constructor of an element is executed. Subclasses of Element should override this hook to implement any necessary initialization. |
insertCustomData |
Inserts a customData into the aggregation customData. |
insertDependent |
Inserts a dependent into the aggregation dependents. |
insertDragDropConfig |
Inserts a dragDropConfig into the aggregation dragDropConfig. |
prop |
This function either calls set[sPropertyName] or get[sPropertyName] with the specified property name depending if an
Since 1.28.0 The contract of this method is not fully defined and its write capabilities overlap with applySettings
|
removeAllCustomData |
Removes all the controls from the aggregation customData. Additionally, it unregisters them from the hosting UIArea. |
removeAllDependents |
Removes all the controls from the aggregation dependents. Additionally, it unregisters them from the hosting UIArea. |
removeAllDragDropConfig |
Removes all the controls from the aggregation dragDropConfig. Additionally, it unregisters them from the hosting UIArea. |
removeCustomData |
Removes a customData from the aggregation customData. |
removeDependent |
Removes a dependent from the aggregation dependents. |
removeDragDropConfig |
Removes a dragDropConfig from the aggregation dragDropConfig. |
removeEventDelegate |
Removes the given delegate from this element. This method will remove all registrations of the given delegate, not only one. |
rerender |
This triggers immediate rerendering of its parent and thus of itself and its children. As |
setLayoutData |
Sets the sap.ui.core.LayoutData defining the layout constraints for this control when it is used inside a layout. |
setTooltip |
Sets a new tooltip for this object. The tooltip can either be a simple string (which in most cases will be rendered as the If a new tooltip is set, any previously set tooltip is deactivated. |
toString |
Returns a simple string representation of this element. Mainly useful for tracing purposes. |
unbindElement |
Removes the defined binding context of this object, all bindings will now resolve relative to the parent context again. |
Returns the best suitable DOM node that represents this Element wrapped as jQuery object. I.e. the element returned by sap.ui.core.Element#getDomRef is wrapped and returned.
If an ID suffix is given, the ID of this Element is concatenated with the suffix (separated by a single dash) and the DOM node with that compound ID will be wrapped by jQuery. This matches the UI5 naming convention for named inner DOM nodes of a control.
Param | Type | DefaultValue | Description |
---|---|---|---|
sSuffix | string |
ID suffix to get a jQuery object for |
Registers the given event handler to change events of the screen width/closest media container width, based on the range set with the given sName
.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The handler function to call when the event occurs. This function will be called in the context of the |
|
oListener | object |
The object that wants to be notified when the event occurs ( |
|
sName | string |
The name of the desired range set |
Removes a previously attached event handler from the change events of the screen width/closest media container width.
Param | Type | DefaultValue | Description |
---|---|---|---|
fnFunction | function |
The handler function to call when the event occurs. This function will be called in the context of the |
|
oListener | object |
The object that wants to be notified when the event occurs ( |
|
sName | string |
The name of the desired range set |
Returns the current media range of the Device or the closest media container
Param | Type | DefaultValue | Description |
---|---|---|---|
sName | string | Device.media.RANGESETS.SAP_STANDARD |
The name of the range set |
Intercepts an event. This method is meant for private usages. Apps are not supposed to used it. It is created for an experimental purpose. Implementation should be injected by outside.
Param | Type | DefaultValue | Description |
---|---|---|---|
sEventId | string |
the name of the event |
|
oElement | sap.ui.core.Element |
the element itself |
|
mParameters | object |
The parameters which complement the event. Hooks must not modify the parameters. |
Adds some customData to the aggregation customData.
Param | Type | DefaultValue | Description |
---|---|---|---|
oCustomData | sap.ui.core.CustomData |
The customData to add; if empty, nothing is inserted |
Adds some dependent to the aggregation dependents.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDependent | sap.ui.core.Element |
The dependent to add; if empty, nothing is inserted |
Adds some dragDropConfig to the aggregation dragDropConfig.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDragDropConfig | sap.ui.core.dnd.DragDropBase |
The dragDropConfig to add; if empty, nothing is inserted |
Adds a delegate that can listen to the browser-, pseudo- and framework events that are handled by this Element
(as opposed to events which are fired by this Element
).
Delegates are simple objects that can have an arbitrary number of event handler methods. See the section "Handling of Events" in the #constructor documentation to learn how events will be dispatched and how event handler methods have to be named to be found.
If multiple delegates are registered for the same element, they will be called in the order of their registration. Double registrations are prevented. Before a delegate is added, all registrations of the same delegate (no matter what value for oThis
was used for their registration) are removed and only then the delegate is added. Note that this might change the position of the delegate in the list of delegates.
When an element is cloned, all its event delegates will be added to the clone. This behavior is well-suited for applications which want to add delegates that also work with templates in aggregation bindings. For control development, the internal addDelegate
method may be more suitable. Delegates added via that method are not cloned automatically, as typically each control instance takes care of adding its own delegates.
Important: If event delegates were added, the delegate will still be called even if the event was processed and/or cancelled via preventDefault
by the Element or another event delegate. preventDefault
only prevents the event from bubbling. It should be checked e.g. in the event delegate's listener whether an Element is still enabled via getEnabled
. Additionally there might be other things that delegates need to check depending on the event (e.g. not adding a key twice to an output string etc.).
See Event Handler Methods for a general explanation of event handling in controls.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDelegate | object |
The delegate object which consists of the event handler names and the corresponding event handler functions |
|
oThis | object | oDelegate |
If given, this object will be the "this" context in the listener methods; default is the delegate object itself |
Applies the focus info.
To be overwritten by the specific control method.
Param | Type | DefaultValue | Description |
---|---|---|---|
oFocusInfo | object |
Focus info object as returned by #getFocusInfo |
|
preventScroll | boolean | false |
@since 1.60 if it's set to true, the focused element won't be shifted into the viewport if it's not completely visible before the focus is set |
Bind the object to the referenced entity in the model, which is used as the binding context to resolve bound properties or aggregations of the object itself and all of its children relatively to the given path.
If a relative binding path is used, this will be applied whenever the parent context changes.
There's no difference between bindElement
and sap.ui.base.ManagedObject#bindObject.
References:
Param | Type | DefaultValue | Description |
---|---|---|---|
vPath | string object |
the binding path or an object with more detailed binding options |
|
path | string |
the binding path |
|
parameters | object |
map of additional parameters for this binding |
|
model | string |
name of the model |
|
events | object |
map of event listeners for the binding events |
|
mParameters | object |
map of additional parameters for this binding (only taken into account when vPath is a string in that case it corresponds to vPath.parameters). The supported parameters are listed in the corresponding model-specific implementation of |
Create a clone of this Element.
Calls sap.ui.base.ManagedObject#clone and additionally clones event delegates.
Param | Type | DefaultValue | Description |
---|---|---|---|
sIdSuffix | string |
Suffix to be appended to the cloned element ID |
|
aLocalIds | string[] |
Array of local IDs within the cloned hierarchy (internally used) |
Creates a new Element from the given data.
If vData
is an Element already, that element is returned. If vData
is an object (literal), then a new element is created with vData
as settings. The type of the element is either determined by a property named Type
in the vData
or by a type information in the oKeyInfo
object
Param | Type | DefaultValue | Description |
---|---|---|---|
vData | sap.ui.core.Element object |
Data to create the element from |
|
oKeyInfo | object |
An entity information (e.g. aggregation info) |
|
type | string |
Type info for the entity |
Retrieves, modifies or removes custom data attached to an Element
.
Usages:
data("myKey", myData)Attaches
myData
(which can be any JS data type, e.g. a number, a string, an object, or a function) to this element, under the given key "myKey". If the key already exists,the value will be updated.
data("myKey", myData, writeToDom)Attaches
myData
to this element, under the given key "myKey" and (if writeToDom
is true) writes key and value to the HTML. If the key already exists,the value will be updated. While oValue
can be any JS data type to be attached, it must be a string to be also written to DOM. The key must also be a valid HTML attribute name (it must conform to sap.ui.core.ID
and may contain no colon) and may not start with "sap-ui". When written to HTML, the key is prefixed with "data-".
data("myKey")Retrieves whatever data has been attached to this element (using the key "myKey") before.
data("myKey", null)Removes whatever data has been attached to this element (using the key "myKey") before.
data(null)
data()Returns all data, as a map-like object, property names are keys, property values are values.
data({"myKey1": myData, "myKey2": null})Attaches
myData
(using the key "myKey1" and removes any data that had been attached for key "myKey2".Param | Type | DefaultValue | Description |
---|---|---|---|
vKeyOrData | string Object<string,any> null |
Single key to set or remove, or an object with key/value pairs or |
|
vValue | string any |
Value to set or |
|
bWriteToDom | boolean | false |
Whether this custom data entry should be written to the DOM during rendering |
Creates metadata for a UI Element by extending the Object Metadata.
Param | Type | DefaultValue | Description |
---|---|---|---|
sClassName | string |
name of the class to build the metadata for |
|
oStaticInfo | object |
static information used to build the metadata |
|
fnMetaImpl | function | sap.ui.core.ElementMetadata |
constructor to be used for the metadata |
Cleans up the resources associated with this element and all its children.
After an element has been destroyed, it can no longer be used in the UI!
Applications should call this method if they don't need the element any longer.
Param | Type | DefaultValue | Description |
---|---|---|---|
bSuppressInvalidate | boolean | false |
If |
Allows the parent of a control to enhance the ARIA information during rendering.
This function is called by the RenderManager's accessibilityState and writeAccessibilityState methods for the parent of the currently rendered control - if the parent implements it.
Param | Type | DefaultValue | Description |
---|---|---|---|
oElement | sap.ui.core.Element |
The Control/Element for which ARIA properties are collected |
|
mAriaProps | object |
Map of ARIA properties keyed by their name (without prefix "aria-"); the method implementation can enhance this map in any way (add or remove properties, modify values) |
Hook method for cleaning up the element instance before destruction.
Applications must not call this hook method directly, it is called by the framework when the element is destroyed.
Subclasses of Element should override this hook to implement any necessary cleanup.
exit: function() { // ... do any further cleanups of your subclass e.g. detach events... this.$().off("click", this.handleClick); if (Element.prototype.exit) { Element.prototype.exit.apply(this, arguments); } }
For a more detailed description how to to use the exit hook, see Section exit() Method in the documentation.
Defines a new subclass of Element with the name sClassName
and enriches it with the information contained in oClassInfo
.
oClassInfo
can contain the same information that sap.ui.base.ManagedObject.extend already accepts, plus the following dnd
property to configure drag-and-drop behavior in the metadata object literal:
Example:
Element.extend('sap.mylib.MyElement', { metadata : { library : 'sap.mylib', properties : { value : 'string', width : 'sap.ui.core.CSSSize' }, dnd : { draggable: true, droppable: false }, aggregations : { items : { type: 'sap.ui.core.Control', multiple : true, dnd : {draggable: false, dropppable: true, layout: "Horizontal" } }, header : {type : "sap.ui.core.Control", multiple : false, dnd : true }, } } });
dnd
key as a metadata propertydnd: object|boolean
Defines draggable and droppable configuration of the element. The following keys can be provided via dnd
object literal to configure drag-and-drop behavior of the element:
[draggable=false]: boolean
Defines whether the element is draggable or not. The default value is false
.[droppable=false]: boolean
Defines whether the element is droppable (it allows being dropped on by a draggable element) or not. The default value is false
.dnd
property is of type Boolean, then the draggable
and droppable
configuration are set to this Boolean value.dnd
key as an aggregation metadata propertydnd: object|boolean
In addition to draggable and droppable configuration, the layout of the aggregation can be defined as a hint at the drop position indicator.
[layout="Vertical"]:
The arrangement of the items in this aggregation. This setting is recommended for the aggregation with multiplicity 0..n (multiple: true
). Possible values are Vertical
(e.g. rows in a table) and Horizontal
(e.g. columns in a table). It is recommended to use Horizontal
layout if the arrangement is multidimensional.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 |
Searches and returns an array of child elements and controls which are referenced within an aggregation or aggregations of child elements/controls. This can be either done recursive or not.
Take care: this operation might be expensive.
Param | Type | DefaultValue | Description |
---|---|---|---|
bRecursive | boolean |
true, if all nested children should be returned. |
Sets the focus to the stored focus DOM reference.
Param | Type | DefaultValue | Description |
---|---|---|---|
oFocusInfo | object | {} |
Options for setting the focus |
preventScroll | boolean | false |
@since 1.60 if it's set to true, the focused element won't be shifted into the viewport if it's not completely visible before the focus is set |
Gets content of aggregation customData.
Custom Data, a data structure like a map containing arbitrary key value pairs.
Gets content of aggregation dependents.
Dependents are not rendered, but their databinding context and lifecycle are bound to the aggregating Element.
Returns the best suitable DOM Element that represents this UI5 Element. By default the DOM Element with the same ID as this Element is returned. Subclasses should override this method if the lookup via id is not sufficient.
Note that such a DOM Element does not necessarily exist in all cases. Some elements or controls might not have a DOM representation at all (e.g. a naive FlowLayout) while others might not have one due to their current state (e.g. an initial, not yet rendered control).
If an ID suffix is given, the ID of this Element is concatenated with the suffix (separated by a single dash) and the DOM node with that compound ID will be returned. This matches the UI5 naming convention for named inner DOM nodes of a control.
Param | Type | DefaultValue | Description |
---|---|---|---|
sSuffix | string |
ID suffix to get the DOMRef for |
Returns a DOM Element representing the given property or aggregation of this Element
.
Check the documentation for the selector
metadata setting in sap.ui.base.ManagedObject.extend for details about its syntax or its expected result.
The default implementation of this method will return null
in any of the following cases:
Element
Element
or the returned DOM Element has no parentNodethis.getDomRef().parentNode
Subclasses can override this method to handle more complex cases which can't be described by a CSS selector.
Param | Type | DefaultValue | Description |
---|---|---|---|
sSettingsName | string |
Name of the property or aggregation |
Gets content of aggregation dragDropConfig.
Defines the drag-and-drop configuration. Note: This configuration might be ignored due to control metadata restrictions.
Get the context binding object for a specific model name.
Note: to be compatible with future versions of this API, you must not use the following model names:
null
""
"null"
or "undefined"
undefined
) is explicitly allowed and refers to the default model.
Param | Type | DefaultValue | Description |
---|---|---|---|
sModelName | string |
Name of the model or |
Returns the DOM Element that should get the focus.
To be overwritten by the specific control method.
Returns an object representing the serialized focus information.
To be overwritten by the specific control method.
Elements don't have a facade and therefore return themselves as their interface.
References:
Gets content of aggregation 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.
Returns the runtime metadata for this UI element.
When using the defineClass method, this function is automatically created and returns a runtime representation of the design time metadata.
Returns the tooltip for this element if any or an undefined value. The tooltip can either be a simple string or a subclass of sap.ui.core.TooltipBase.
Callers that are only interested in tooltips of type string (e.g. to render them as a title
attribute), should call the convenience method #getTooltip_AsString instead. If they want to get a tooltip text no matter where it comes from (be it a string tooltip or the text from a TooltipBase instance) then they could call #getTooltip_Text instead.
Returns the tooltip for this element but only if it is a simple string. Otherwise an undefined value is returned.
Returns the main text for the current tooltip or undefined if there is no such text. If the tooltip is an object derived from sap.ui.core.Tooltip, then the text property of that object is returned. Otherwise the object itself is returned (either a string or undefined or null).
Checks for the provided sap.ui.core.CustomData
in the aggregation customData. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oCustomData | sap.ui.core.CustomData |
The customData whose index is looked for |
Checks for the provided sap.ui.core.Element
in the aggregation dependents. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDependent | sap.ui.core.Element |
The dependent whose index is looked for |
Checks for the provided sap.ui.core.dnd.DragDropBase
in the aggregation dragDropConfig. and returns its index if found or -1 otherwise.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDragDropConfig | sap.ui.core.dnd.DragDropBase |
The dragDropConfig whose index is looked for |
Initializes the element instance after creation.
Applications must not call this hook method directly, it is called by the framework while the constructor of an element is executed.
Subclasses of Element should override this hook to implement any necessary initialization.
Inserts a customData into the aggregation customData.
Param | Type | DefaultValue | Description |
---|---|---|---|
oCustomData | sap.ui.core.CustomData |
The customData to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
Inserts a dependent into the aggregation dependents.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDependent | sap.ui.core.Element |
The dependent to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
Inserts a dragDropConfig into the aggregation dragDropConfig.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDragDropConfig | sap.ui.core.dnd.DragDropBase |
The dragDropConfig to insert; if empty, nothing is inserted |
|
iIndex | int |
The |
This function either calls set[sPropertyName] or get[sPropertyName] with the specified property name depending if an oValue
is provided or not.
Param | Type | DefaultValue | Description |
---|---|---|---|
sPropertyName | string |
name of the property to set |
|
oValue | any |
value to set the property to |
Removes all the controls from the aggregation customData.
Additionally, it unregisters them from the hosting UIArea.
Removes all the controls from the aggregation dependents.
Additionally, it unregisters them from the hosting UIArea.
Removes all the controls from the aggregation dragDropConfig.
Additionally, it unregisters them from the hosting UIArea.
Removes a customData from the aggregation customData.
Param | Type | DefaultValue | Description |
---|---|---|---|
vCustomData | int string sap.ui.core.CustomData |
The customData to remove or its index or id |
Removes a dependent from the aggregation dependents.
Param | Type | DefaultValue | Description |
---|---|---|---|
vDependent | int string sap.ui.core.Element |
The dependent to remove or its index or id |
Removes a dragDropConfig from the aggregation dragDropConfig.
Param | Type | DefaultValue | Description |
---|---|---|---|
vDragDropConfig | int string sap.ui.core.dnd.DragDropBase |
The dragDropConfig to remove or its index or id |
Removes the given delegate from this element.
This method will remove all registrations of the given delegate, not only one.
Param | Type | DefaultValue | Description |
---|---|---|---|
oDelegate | object |
The delegate object which consists of the event handler names and the corresponding event handler functions |
This triggers immediate rerendering of its parent and thus of itself and its children.
As sap.ui.core.Element
"bubbles up" the rerender, changes to child-Elements
will also result in immediate rerendering of the whole sub tree.
Sets the sap.ui.core.LayoutData defining the layout constraints for this control when it is used inside a layout.
Param | Type | DefaultValue | Description |
---|---|---|---|
oLayoutData | sap.ui.core.LayoutData |
which should be set |
Sets a new tooltip for this object.
The tooltip can either be a simple string (which in most cases will be rendered as the title
attribute of this Element) or an instance of sap.ui.core.TooltipBase.
If a new tooltip is set, any previously set tooltip is deactivated.
Param | Type | DefaultValue | Description |
---|---|---|---|
vTooltip | string sap.ui.core.TooltipBase |
New tooltip |