Shellfish

Class: Object

core.Object

Base class representing a mid-level object with support for parent-child relations, reference counting, properties, events, and lifecycle management. Unlike plain JavaScript objects, this class has the concept of a destructor method.

new core.Object ()

object.js:830
Properties:
Name Type Description
children Array.<core.Object>

[readonly] The child objects.
lifeCycleStatus string

[readonly] The current lifecycle status: new|initialized|destroyed
objectId number

[readonly] The unique ID of the object for debugging purposes.
objectLocation string

A string describing the object's location for debugging purposes.
objectType string

A string describing the object's type for debugging purposes.
parent core.Object

The parent object, or null if the object has no parent.

Methods

abortWait (name)

object.js:1885

Aborts a named wait operation from core.Object#wait.

Name Type Description
name string

The name of the wait operation.

accumulateCallback (f, name) Deprecated : Use defer instead.

object.js:1758

Accumulates the given callback function associated with a name.

Only the most recent one of the accumulated functions under a name will be executed before the JavaScript engine finished executing its current code.

Name Type Description
f function

The function to invoke.
name string

The accumulation name.

add (child)

object.js:1971

Adds a child object to this object.

Name Type Description
child core.Object

The child object.

addProperty (name, getter, setter)

object.js:1397

Adds a custom external property of any type. The property is notifyable.

Name Type Description
name string

The name of the property.
getter function

A function returning the property's value.
setter function

A function accepting the property's new value.

awaitSharedResource (key, callback)bool

object.js:1717

Waits for a shared resource identified by a key to become available. Once the resource is available, the given callback will be invoked. If this method returns true, the shared resource must be created first (it does not exist and this object is the first one waiting).

This method is useful for dealing with resources that are created asynchronously.

Name Type Description
key string

The resource key.
callback function

The callback function.
See:
Returns:
Type Description
bool
  • Whether the resource needs to be created or not.

cancelNamedCallback (name)

object.js:1148

Cancels the given pending named callback before it gets executed.

Name Type Description
name string

The name.
See:

change (name, newValue)

object.js:1459

Changes the given property by applying a transition if specified. This is the prefered way to change a property's value as it takes potential transitioning into account.

If the value is a Promise object, it will be changed when the Promise resolves.

Name Type Description
name string

The name of the property.
newValue any

The property's new value.
See:

clearQueue (qName)

object.js:1916

Clears the given waiting queue.

Name Type Description
qName string

The name of the queue.
See:

colorName (name)core.Color

object.js:961

Creates a color from a CSS color name.

Name Type Description
name string

The color name.
Returns:
Type Description
core.Color
  • The color.

connect (event, receiver, handler)

object.js:1570

Connects a handler to the given event. The handler gets disconnected automatically when the receiver object is discarded.

Name Type Description
event string

The event name.
receiver core.Object

The receiver object that owns the handler.
handler function

The event handler.
See:

defer (f, name)

object.js:1773

Defers the execution of the given function associated with a name.

Only the most recent one of the defered functions under a name will be executed before the JavaScript engine finished executing its current code.

Name Type Description
f function

The function to invoke.
name string

The function name.

disconnect (event, receiver)

object.js:1587

Disconnects an object from the given event.

Name Type Description
event string

The event name.
receiver core.Object

The object to disconnect.
See:

freeSharedResource (key, deleter)

object.js:1684

Frees a shared resource identified by a key. If this was the last user of the resource, it will be deleted using the supplied deleter function.

The deleter function may be omitted if there is no special action to be taken for deletion.

Name Type Description
key string

The resource key.
deleter function optional

The deleter function.
See:
Example
this.freeSharedResource("mySharedResource", res =>
{
    res.cleanUp();
});

hasConnections (event)bool

object.js:1612

Returns whether the given event has handlers connected.

Name Type Description
event string

The name of the event.
See:
Returns:
Type Description
bool Whether the event has handlers connected.

import (url)Promise

object.js:1928

Imports a JavaScript or WASM module and returns a Promise that resolves to the module.

Name Type Description
url string

The address of the module.
Returns:
Type Description
Promise The Promise object.

init ()

object.js:980

Initializes this object. Call this method after creating the object and its children.

isAncestorOf (obj)bool

object.js:1286

Tests if this object is an ancestor of the given object.

Name Type Description
obj core.Object

The object to test.
Returns:
Type Description
bool Whether the object is an ancestor.

log (domain, level, message)

object.js:1957

Sends a log message to the parent element if there is one. Override this method to handle logging. By default, logging is not handled in any way.

Name Type Description
domain string

The name of the logging domain.
level string

The log level. One of trace|debug|info|warning|error|fatal
message string

The log message.

namedCallback (callback, name)function

object.js:1109

Wraps a callback function to give it a name handle by which it may be canceled before execution.

When setting multiple callbacks of the same name, only the last one will be executed.

Name Type Description
callback function

The callback function.
name string

The name.
See:
Returns:
Type Description
function
  • The wrapped callback function.

namedCallbackPending (name)bool

object.js:1134

Returns if the given named callback is currently pending.

Name Type Description
name string

The name.
See:
Returns:
Type Description
bool true if the callback is currently pending.

notifyable (name)

object.js:1323

Makes the given property notifyable. This adds a <name>Changed event to the object for watching the property for changes.

Name Type Description
name string

The name of the property.
See:

referenceAdd (which)

object.js:1168

Adds a reference to this object, which means that another object is holding a reference to this object from then on. Objects are not discarded while still being referenced.

The reference is removed automatically when the referencing object gets discarded.

Name Type Description
which core.Object

The referencing object.
See:

referenceRemove (which)

object.js:1219

Removes a reference from this object. When there are no references left, the object will be discarded automatically.

Name Type Description
which core.Object

The referencing object.
See:

registerEvent (name, connectionMonitor)

object.js:1511

Registers the given event. If connectionMonitor is specified, that callback will be invoked whenever a connection to the event is made.

Name Type Description
name string

The name of the event.
connectionMonitor function

The callback to invoke after each new connection.
See:

releaseLater ()

object.js:1056

Releases this object from its parent at a later point when idle.

rgb (r, g, b)core.Color

object.js:954

Creates a color from RGB values.

Name Type Description
r number

The red value between 0.0 and 1.0.
g number

The green value between 0.0 and 1.0.
b number

The blue value between 0.0 and 1.0.
Returns:
Type Description
core.Color
  • The color.

rgba (r, g, b, a)core.Color

object.js:945

Creates a color from RGBA values.

Name Type Description
r number

The red value between 0.0 and 1.0.
g number

The green value between 0.0 and 1.0.
b number

The blue value between 0.0 and 1.0.
a number

The alpha value between 0.0 and 1.0.
Returns:
Type Description
core.Color
  • The color.

safeCallback (callback, condition)function

object.js:1076

Wraps a callback function to be safe, i.e. it will only be invoked if a condition still holds. By default the condition checks if the object is still alive. This helps when working with asynchronous code.

Name Type Description
callback function

The callback function.
condition function

An optional condition function that returns either true or false.
Returns:
Type Description
function
  • The safe-made callback function.

sharedResource (key, factory)any

object.js:1638

Retrieves a shared resource identified by a key. If the resource did not yet exist, it will be created using the supplied factory function.

The factory function may be omitted if you don't want to create the resource at this place. In this case, this method will return null if the resource did not exist.

Name Type Description
key string

The resource key.
factory function optional

The factory function.
See:
Returns:
Type Description
any The shared resource.
Example
const res = this.sharedResource("mySharedResource", () =>
{
    return new BigResource();
});

transitionable (name, interpolate)

object.js:1434

Makes the given property transitionable by adding a property <name>Transition for defining a transition animation.

Name Type Description
name string

The name of the property.
interpolate function

An optional interpolation function.
See:

typeOf (name)string

object.js:1338

Returns the role type of the given property. The type is undefined if the property does not exist.

Name Type Description
name string

The name of the property.
Returns:
Type Description
string The type, one of property|method|event|eventhandler|undefined

vec3 (x, y, z)core.Vec3

object.js:971

Creates a 3-component vector.

Name Type Description
x number

The X component.
y number

The Y component.
z number

The Z component.
Returns:
Type Description
core.Vec3 The vector.

visit (f)

object.js:1307

Visits this object and its decendants recursively with a custom function, while the function returns true. If the function returns false, children are not visited.

Name Type Description
f function

The visitor function. Takes the visited object as parameter and returns a boolean value.

wait (ms, name)Promise

object.js:1793

Returns a Promise that resolves after a given amount of milliseconds.

If the milliseconds are set to 0, the promise resolves immediately after the JavaScript engine finished executing its current code, without using a timer.

If the wait operation is given a name, it is abortable via the core.Object#abortWait method. In this case, the promise resolves to false.

Name Type Description
ms number

The amount of milliseconds to wait.
name string

An optional name for aborting via core.Object#abortWait.
Returns:
Type Description
Promise The Promise object.

waitForActivity (name)Promise

object.js:1854

Returns a Promise that resolves after there has been any event activity.

If the wait operation is given a name, it is abortable via the core.Object#abortWait method. In this case, the promise resolves to false.

Name Type Description
name string

An optional name for aborting via core.Object#abortWait.
Returns:
Type Description
Promise The Promise object.

waitQueued (qName)Promise.<function()>

object.js:1904

Waits in a named queue and returns a Promise that resolves to a next function when it's the caller's turn. After the caller has finished its turn, that next function must be invoked.

Name Type Description
qName string

The name of the queue.
See:
Returns:
Type Description
Promise.<function()> The Promise object.

Events

core.Object.event:destruction

object.js:858

Is triggered immediately before the object will be destroyed. The object is still intact at this place.

core.Object.event:initialization

object.js:851

Is triggered after the object was initialized.

core.Object.event:termination

object.js:866

Is triggered after the object was destroyed. The object is not intact anymore at this place.