Class “NativeObject”

Object > NativeObject

Base class for all objects with a native implementation.

Type:	NativeObject extends Object
Constructor:	protected
Singleton:	No
Namespace:	tabris
Direct subclasses:	App, Camera, Device, FileSystem, InactivityTimer, NavigationBar, Permission, Popup, Printer, StatusBar, Tabris, Widget
JSX Support:	No

Methods

off(type, listener, context?)

Removes all occurrences of listener that are bound to type and context from this widget.

In TypeScript you should use the alternative Listeners API, e.g. widget.onResize.off(listener); instead of widget.off('resize', listener}); The former provides more type information.

Parameter	Type	Description
type	string	The type of events to remove listeners for.
listener	Function	The listener function to remove.
context	object	The context of the bound listener to remove. Optional.

Returns: this

off(listeners)

Removes all listeners in the given object from the event type indicated by their key.

In TypeScript you should use the alternative Listeners API, e.g. widget.onResize.off(listener); instead of widget.off({resize: listener}); The former provides more type information.

Parameter	Type	Description
listeners	{[eventType]: Function}	A key-value map where the keys are event types and the values are the listeners to deregister from these events, e.g. {tap: onTap, scroll: onScroll}.

Returns: this

on(type, listener, context?)

Registers a listener function to be notified of events of the given type.

Parameter	Type	Description
type	string	The type of events to listen for.
listener	Function	The listener function to register. This function will be called with an event object.

In TypeScript you should use the alternative Listeners API, e.g. widget.onResize(listener); instead of widget.on({resize: listener}); The former provides more type information. context | object | In the listener function, this will point to this object. If not present, the listener will be called in the context of this object. Optional.

Returns: this

on(listeners)

Registers all listeners in the given object for the event type indicated by their key.

In TypeScript you should use the alternative Listeners API, e.g. widget.onResize(listener); instead of widget.on('resize', listener); The former provides more type information.

Parameter	Type	Description
listeners	{[eventType]: Function}	A key-value map where the keys are event types and the values are the listeners to register for these events, e.g. {tap: onTap, scroll: onScroll}.

Returns: this

once(type, listener, context?)

Same as on, but removes the listener after it has been invoked by an event.

In TypeScript you should use the alternative Listeners API, e.g. widget.onResize.once(listener); instead of widget.once('resize', listener); The former provides more type information.

Parameter	Type	Description
type	string	The type of the event to listen for.
listener	Function	The listener function to register. This function will be called with an event object.
context	object	In the listener function, this will point to this object. If not present, the listener will be called in the context of this object. Optional.

Returns: this

once(listeners)

Same as on, but removes the listener after it has been invoked by an event.

In TypeScript you should use the alternative Listeners API, e.g. widget.onResize.once(listener); instead of widget.once({resize: listener}); The former provides more type information.

Parameter	Type	Description
listeners	{[eventType]: Function}	A key-value map where the keys are event types and the values are the listeners to register for these events, e.g. {tap: onTap, scroll: onScroll}.

Returns: this

set(properties)

Sets all key-value pairs in the properties object as widget properties.

TypeScript note: When called on this from within a subclass constructor (i.e. a custom component/widget) you may have to use the generic version of this method: this.set<MySubclass>(...);

Parameter	Type	Description
properties	Properties<this>

Returns: this

trigger(type)

Notifies all registered listeners for the given type.

In TypeScript you should use the alternative Listeners API, e.g. widget.myEvent.trigger(); instead of widget.trigger('myEvent'); The former provides more type information.

Parameter	Type	Description
type	string	The type of event to trigger

Returns: this

trigger(type, eventData)

Passes the fields of the given object to all listeners registered for this event type.

In TypeScript you should use the alternative Listeners API, e.g. widget.myEvent.trigger(eventData); instead of widget.trigger('myEvent', eventData}); The former provides more type information.

Parameter	Type	Description
type	string	The type of event to trigger
eventData	object	The data to pass to listener functions.

Returns: this

trigger(type, eventObject)

Initializes the given eventObject and passes it to all listeners registered for this event type. If eventObject was already initialized its fields are copied to a new event object.

In TypeScript you should use the alternative Listeners API, e.g. widget.myEvent.trigger(eventObject); instead of widget.trigger('myEvent', eventObject}); The former provides more type information.

Parameter	Type	Description
type	string	The type of event to trigger
eventObject	EventObject	An instance of EventObject (or a subclass) to pass to listener functions.

Returns: this

triggerAsync(type)

Like trigger, but returns a promise. The promise will resolve when all asynchronous listeners (if any) have resolved. If none of the listeners are asynchronous (return a promise) this method works just like trigger(). Useful for unit testing.

Parameter	Type	Description
type	string	The type of event to trigger

Returns: Promise</code>

triggerAsync(type, object)

Notifies all registered listeners for the given type with the given data. Unlike trigger each asynchronous listener will be awaited, meaning that if a listener returns a promise that will pause event processing until it resolves. Returns a promise that resolves once all listeners have been notified. If any listener returns a rejecting promise the even processing is aborted and the returned promise rejects with the error value. If none of the listeners return a promise this method works just like trigger().

In TypeScript you should use widget.myEvent.triggerAsync(); instead

Parameter	Type	Description
type	string	The type of event to trigger
object	object	The data to pass to listener functions.

Returns: Promise</code>

triggerAsync(type, eventObject)

Notifies all registered listeners for the given type with the given EventObject. Unlike trigger each asynchronous listener will be awaited, meaning that if a listener returns a promise that will pause event processing until it resolves. Returns a promise that resolves once all listeners have been notified. If any listener returns a rejecting promise the even processing is aborted and the returned promise rejects with the error value. If none of the listeners return a promise this method works just like trigger().

In TypeScript you should use widget.myEvent.triggerAsync(); instead

Parameter	Type	Description
type	string	The type of event to trigger
eventObject	EventObject	An instance of EventObject (or a subclass) to pass to listener functions.

Returns: Promise</code>

Protected Methods

These methods are accessible only in classes extending NativeObject.

_checkDisposed()

A helper function that throws if the instance has already been marked as disposed.

Returns: undefined

_dispose(skipNative?)

Called by the framework to dispose a NativeObject instance. (The dispose is only used by application code.) The method should never be called directly, but it may be overwritten to prevent dispose for objects that are not disposable.

Parameter	Type	Description
skipNative	boolean	Optional.

Returns: undefined

_getStoredProperty(propertyName)

Returns a value stored via _storeProperty, or undefined.

Parameter	Type	Description
propertyName	string

Returns: unknown

_getXMLAttributes()

Used by console.dirxml() to produce part of the XML representation of this object. May be overwritten to modify the output. The return value should be an array of tuples consisting of the attribute name and string representation. The new implementation may make a super call to obtain the default list of attributes printed for this object.

Returns: Array<[string, any]>

_getXMLContent()

Used by console.dirxml() to produce part of the XML representation of this object. May be overwritten to modify the output. The return value should be an array of strings each representing on of the children of this instance.

Returns: string[]

_getXMLElementName()

Used by console.dirxml() to produce part of the XML representation of this object. May be overwritten to modify the output. The default implementation returns the name of the constructor of this object.

Returns: string

_getXMLFooter(hasChild)

Used by console.dirxml() to produce part of the XML representation of this object. May be overwritten to modify the output. The default implementation the closing tag if hasChild is true, otherwise returns an empty string. The hasChild parameter is true if _getXMLContent returns a non-empty array. It is usually not necessary to call or override this method.

Parameter	Type	Description
hasChild	boolean

Returns: string

_getXMLHeader(hasChild)

Used by console.dirxml() to produce part of the XML representation of this object. May be overwritten to modify the output. The default implementation crates the opening tag including the element name given by _getXMLElementName and attributes given by _getXMLAttributes. The hasChild parameter is true if _getXMLContent returns a non-empty array in which case the tag is not self-closing. It is preferable to override these individual method instead of this one.

Parameter	Type	Description
hasChild	boolean

Returns: string

_isListening(eventType)

Returns true if there is currently one or more listeners registers for the given event type.

Parameter	Type	Description
eventType	string

Returns: boolean

_listen(eventName, listening)

Called by the framework when the first listener of a given event type is registered on the instance (listening is true), and when the last listener of a given event type is removed (listening is false). Typically overwritten to make calls to _nativeListen when the given event type is issues by native code. The new implementation must make a super call if it does not handle the given event type itself.

Parameter	Type	Description
eventName	string
listening	boolean

Returns: undefined

_nativeCall(methodName, parameters)

Sends a ‘call’ operation to the native client and returns the result.

Parameter	Type	Description
methodName	string
parameters	object

Returns: unknown

_nativeCreate(param?)

Sends a ‘create’ operation to the native client. Called once by the constructor and should not be called again. May be overwritten to check the constructor parameter or perform any kind of initialization code prior to creating the native object. The new implementation must make a super call.

Parameter	Type	Description
param	{[property]: any}	The first argument (if any) given in the constructor call. Will be forwarded to the set method after the native object was created. Optional.

Returns: undefined

_nativeGet(propertyName)

Sends a ‘get’ operation to the native client and returns the result.

Parameter	Type	Description
propertyName	string

Returns: unknown

_nativeListen(eventType)

Sends a ‘listen’ operation to the native client.

Parameter	Type	Description
eventType	string

Returns: undefined

_nativeSet(propertyName, value)

Sends a ‘set’ operation to the native client.

Parameter	Type	Description
propertyName	string
value	any

Returns: undefined

_onoff(eventType, listening, listener)

A helper function that register the given listener if listening is true and de-registers it if listening is false.

Parameter	Type	Description
eventType	string
listening	boolean
listener	Function

Returns: undefined

_release()

Called during the dispose process, after the ‘dispose’ event has fired, but before the native code has be executed. Native operations (_nativeSet, _nativeGet, _nativeCall, _nativeListen) on this object are still possible at this point. May be overwritten to perform any kind of clean-up code. The new implementation must perform a super call at some point, typically at the last command.

Returns: undefined

_reorderProperties(propertyNames)

Used by the set method to determined in which order the given property values are applied. May be overwritten, but the new implementation must pass the propertyNames through a super call at one point.

Parameter	Type	Description
propertyNames	string[]	List of properties to be set to a new value

Returns: string[]

_storeProperty(propertyName, encodedValue)

Stores the given value internally and triggers a matching change event.

Parameter	Type	Description
propertyName	string
encodedValue	any

Returns: undefined

_trigger(eventType, eventData?)

Called by the native client to trigger a JavaScript event on this instance. May be overwritten to pre-process the eventData object. The return value indicates whether defaultPrevented on the event object was set to true. The new implementation must forward the parameters to a super call and return that calls return value.

Parameter	Type	Description
eventType	string
eventData	object	Optional.

Returns: boolean

_wasSet(propertyName)

Returns true if _storeProperty was ever called with the given property propertyName

Parameter	Type	Description
propertyName	string

Returns: boolean

Properties

cid

An application-wide unique identifier automatically assigned to all native objects on creation. It follows the pattern ‘$', where the number is incremented for each new NativeObject instance.

Type:	string
Settable:	No
Change Event:	Not supported

This property can only be set via constructor. Once set, it cannot change anymore.

jsxAttributes

When using JSX with TypeScript (.tsx files), the type of this property determines which JSX attributes are valid for this object.

Type:	JSXAttributes</code>
Settable:	No
Change Event:	Not supported

This property can only be set via constructor. Once set, it cannot change anymore.

Protected Properties

These properties are accessible only in classes extending NativeObject.

_isDisposed

Type:	true | undefined
Settable:	Yes
Change Event:	Not supported

_nativeType

Type:	string
Settable:	No
Change Event:	Not supported