Class “Constraint”

Object > Constraint

Represents a constraint on the layout of a widget that the parent uses to determine the position of one of its edges. See also ConstraintValue

Type: Constraint extends Object
Constructor: public
Singleton: No
Namespace: tabris
Direct subclasses: None
JSX Support: No

Constructor

new Constraint(reference, offset)

Parameter Type Description
reference Percent | SiblingReference Sets the reference property.
offset Offset Sets the offset property.

Methods

equals(value)

Tests if the given value is a Constraint instance that is deeply equal to this one.

Parameter Type Description
value Constraint  

Returns: boolean

toArray()

A tuple consisting of the values of the reference and offset properties, i.e. [reference, offset].

Returns: ConstraintArray

toString()

A string representation of the constraint as a space separated string in the pattern of 'reference offset'.

Returns: string

Static Methods

from(constraintValue)

Creates a new instance of Constraint using any valid constraint expression. For any other value, including null and 'auto', the method throws.

Parameter Type Description
constraintValue ConstraintValue The value to create an Constraint instance from.

Returns: Constraint

Properties

offset

An additional distance between the reference point and the edge of the widget itself.

Type: Offset
Settable: Yes

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

reference

A reference point from which the offset is added. Either a SiblingReference - indicating the opposing edge of that widget - or a Percent instance, indicating a fraction of the width/height (padding excluded) of the parent widget.

If the sibling reference is a string it will be a valid selector string and not contain any pseudo selectors ('next()'/'prev()').

Type: Percent | SiblingReference
Settable: Yes

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

Static Properties

next

A SiblingReference indicating the next widget in the list of children attached to the same parent. Used by the reference property. Also available as LayoutData.next.

Type: unique symbol
Settable: No

prev

A SiblingReference indicating the previous widget in the list of children attached to the same parent. Used by the reference property. Also available as LayoutData.prev.

Type: unique symbol
Settable: No

ConstraintValue

  • JavaScript Type: tabris.Constraint, tabris.Widget, tabris.Percent, Symbol, Array, Object, string, number or true.
  • TypeScript Type: tabris.ConstraintValue

A ConstraintValue represents a constraint on the layout of a widget that the parent uses to determine the position of one of its edges. This type allows various expressions that can all be used in place of a Constraint instance for convenience. All API that accept these expressions will convert them to a Constraint object. (With the exception of CanvasContext.)

Every expression of ConstraintValue consists of a SiblingReference and/or an offset value.

In addition to Constraint instances ConstraintValue includes:

Offset-only constraints

Simply the Offset number by itself, a positive float including zero. A value of true is also accepted and treated like zero.

Examples:

widget.left = 12.5;
widget.right = 8;
widget.top = 0;
widget.bottom = true;

Reference-only constraints

Either a PercentValue or a SiblingReferenceValue.

Examples:

widget.left = '12%';
widget.right = 'prev()';
widget.top = new Percent(50);
widget.bottom = '#foo';

ConstraintLikeObject

A plain object implementing the following interface:

  • JavaScript Type: Object
  • TypeScript Type: tabris.ConstraintLikeObject
interface ConstraintLikeObject {
  reference?: SiblingReferenceValue | PercentValue;
  offset?: Offset;
}

An object implementing the same properties as Constraint.

An instances of Constraint is a valid ConstraintLikeObject, but ConstraintLikeObject is less strict: The reference property can be a PercentValue or a SiblingReferenceValue, or can be omitted if offset is given. Either of the two entries may be omitted, but not both.

Examples:

widget.left = {reference: sibling, offset: 12};
widget.right = {reference: '23%', offset: 12};
widget.top = {reference: Constraint.prev};
widget.bottom = {offset: 12};

ConstraintArrayValue

  • JavaScript Type: Array
  • TypeScript Type: tabris.ConstraintArrayValue

An array tuple in the format of [reference, offset], where reference is either a PercentValue or a SiblingReferenceValue, and offset is an Offset, i.e. a number.

Examples:

widget.left = [sibling, 0];
widget.right = ['#foo', 0];
widget.top = [{percent: 23}, 12];
widget.bottom = [Constraint.prev, 12];

ConstraintString

  • JavaScript Type: string
  • TypeScript Type: tabris.ConstraintString

This is often the most compact way to express a constraint, but it may not be the preferred way in TypeScript projects if type safety is a priority. The string consists of a space separated list of two values in the pattern of 'reference offset'. The reference part may be of any string as accepted by SiblingReferenceValue or PercentValue. The offset has to be a positive (including zero) float, just like Offset.

Examples:

widget.left = '.bar 0';
widget.right = '#foo 0'
widget.top = '23% 12';
widget.bottom = 'prev() 12';

SiblingReference

  • JavaScript Type: tabris.Widget, Symbol, string
  • TypeScript Type: tabris.SiblingReference

A SiblingReference indicates a single sibling of a given Widget. Differs from the type SiblingReferenceValue in that it does not include 'next() and 'prev()' as selectors strings. It uses symbols instead. There are three variants of SiblingReference:

Sibling instance

  • JavaScript Type: Widget
  • TypeScript Type: tabris.Widget

Any widget instance that has the same parent.

SiblingSelectorString

  • JavaScript Type: string
  • TypeScript Type: tabris.SiblingSelectorString

A simple selector string of the format '#Type', '#id', '.class'. No child selectors. The first matching sibling is selected.

SiblingReferenceSymbol

  • JavaScript Type: Symbol
  • TypeScript Type: tabris.SiblingReferenceSymbol

The constants Constraint.prev and Constraint.next (also available as LayoutData.prev and LayoutData.next) may be used to point to the sibling directly before/after the reference widget in the parents children list.

SiblingReferenceValue

  • JavaScript Type: tabris.Widget, Symbol, string
  • TypeScript Type: tabris.SiblingReferenceValue

Same as SiblingReference, but less strict in that it also allows the strings 'next() and 'prev()' in place of the prev and next symbols.

Offset

  • JavaScript Type: number
  • TypeScript Type: tabris.Offset, an alias for number

A positive or negative float, or 0, representing device independent pixels (DIP).