pxScene - Scene Graph API

A 2d scene graph API supporting the following:

Scene instance

Properties

root
returns the root Object for the scene
w
returns the width in pixel-sized units of the scene
h
returns the height in pixel-sized units of the scene
animation
animation for animation-related constants
stretch
stretch for x/y stretch-related constants (for image)
alignVertical
alignVertical for vertical alignment-related constants (for textBox)
alignHorizontal
alignHorizontal for horizontal alignment-related constants (for textBox)
truncation
truncation for truncation-related constants (for textBox)

Methods

create(json)
create a subtree of scene graph Objects
Use json t: to construct specific object types:
  • text
  • textBox
  • wayland
  • image
  • image9 (for 9-slice images)
  • imageA (for animated PNGs and GIFs)
  • rect
  • object
  • scene
    • create(json)
    create resources that can be shared
    Use json t: to construct specific resource types:
  • imageResource
  • imageAResource
  • fontResource
    • on(string, function)
    registers a function callback for the specified event:
    • onMouseDown - parameter object has properties: x, y, flags
    • onMouseUp - parameter object hasproperties: x, y, flags
    • onMouseMove - parameter object has properties: x, y
    • onMouseEnter - parameter object has properties: target, stopPropagation()
    • onMouseLeave - parameter object has properties: target, stopPropagation()
    • onFocus - parameter object has properties: target, stopPropagation()
    • onBlur - parameter object has properties: target, loseFocusChain, stopPropagation() -
        loseFocusChain: true or false to indicate whether the object receiving this onBlur event is within the heirarchy of the object losing focus. Example usage: loseFocusChain example
    • onKeyDown - parameter object has properties: target, keyCode, flags, stopPropagation()
    • onKeyUp - parameter object has properties: target, keyCode, flags, stopPropagation()
    • onChar - parameter object has properties: target, charCode, stopPropagation()
    • onResize - parameter object has properties w, h
    • onClose - parameter object no properties -
        onClose indicates the object scene is destructed and garbage collected
    delListener(string, function)
    unregister a callback function for the specified event
    getFocus()
    will return the object that has keyboard focus


    Object instance

    Properties

    parent
    returns this object's parent Object
    x
    x-coordinate used as input into the object's transform function in pixel units
    y
    y-coordinate used as input into the object's transform function in pixel units
    w
    pixel unit width of the object
    h
    pixel unit height of the object
    cx
    x offset used as the center of rotation and scale
    cy
    y offset used as the center of rotation and scale
    sx
    scale factor in the x dimension
    sy
    scale factor in the y dimension
    a
    opacity of the object [0-1]
    r
    angle of rotation in degrees
    id
    user-assigned associated string identifier for the object. defaults to "".
    interactive
    determines whether the object is mouse interactive. defaults to true.
    painting
    when set to false the object and it's children will be snapshotted. when set to true the object and it's children will immediately reflect any changes
    clip
    determines whether the drawing done by the object and it's children will be clipped by the objects w and h properties. defaults to false.
    mask
    determines whether this object will be used to define an alpha layer mask for the siblings of this object. defaults to false.
    draw
    determines whether this object will be drawn
    focus
    when set to true, this object will be given keyboard focus. the object that had previous focus will be blurred.
    numChildren
    returns the number of immediate child objects that this object parents
    children
    returns a collection of child objects for this object

    Methods

    getChild(i)
    returns the i-th child for this object
    remove
    removes this object from the scene
    removeAll
    removes all children and their descendents from the scene.
    moveToFront
    Moves this child to the top of the z-order within its siblings
    moveToBack
    Moves this child to the bottom of the z-order within its siblings
    moveForward
    Moves this child one forward in the z-order within its siblings
    moveBackward
    Moves this child one backward in the z-order within its siblings
    animateTo(json, duration, tween, type, count)
    tween the object's properties to the targets specified over the specified duration using the tween function.
  • Tween indicates the interpolator to be used for the animation. See animation constants for valid values. Defaults to TWEEN_LINEAR.
  • Type (option) determines whether the animation loops or oscillates. See animation constants for valid values. Defaults to OPTION_LOOP.
  • Count is the number of times the animation should repeat. Defaults to 1. Use COUNT_FOREVER to create an animation that won't end until canceled.
    • Returns a promise that will fulfill when the animation is complete.
    animate(json, duration, tween, type, count)
    tween the object's properties to the targets specified over the specified duration using the tween function.
  • Tween indicates the interpolator to be used for the animation. See interpolator animation constants for valid values. Defaults to TWEEN_LINEAR.
  • Type (option) determines whether the animation loops or oscillates. See option animation constants for valid values. Defaults to OPTION_LOOP.
  • Count is the number of times the animation should repeat. Defaults to 1. Use COUNT_FOREVER to create an animation that won't end until canceled.
    • Returns an Animate object that can be used to cancel or check on status of the animation.
    on(string, function)
    registers a function callback for the specified event:
  • onMouseDown - parameter object has properties: x, y, flags
  • onMouseUp - parameter object hasproperties: x, y, flags
  • onMouseMove - parameter object has properties: x, y
  • onMouseEnter
  • onMouseLeave
  • onFocus
  • onBlur
  • onKeyDown - parameter object has properties: target, keyCode, flags
  • onKeyUp - parameter object has properties: target, keyCode, flags
  • onChar - parameter object has properties: target, charCode
  • onSize - parameter object has properties w, h
    • delListener(string, function)
    unregisters a function callback for the specified event
    getObjectById(id)
    returns object with associated id. search scope is this object and its children.


    scene instance inherits from Object

    Properties

    url
    the url to JavaScript file that defines this scene


    Rectangle instance inherits from Object

    Properties

    fillColor
    specifies the color to fill the interior of the rectangle. eg. 0xff0000ff, opaque red, Format: 0xrrggbbaa

    NOTE: Web style "#rgb", "#rrggbb" and color names are also supported as a convenience shortcut. See Basics for more information.
    lineColor
    specifies the color to stroke the edge of the rectangle. eg. 0xff0000ff, opaque red, Format: 0xrrggbbaa

    NOTE: Web style "#rgb", "#rrggbb" and color names are also supported as a convenience shortcut.See Basics for more information.
    lineWidth
    species the width of the line to stroke around the ege of the rectangle. defaults to 0.


    Image instance inherits from Object

    Properties

    url
    specifies the url of the image to load. supports .png and .jpg
    stretchX
    specifies the stretch option to use for the x-coordinate. See stretch constants.
    stretchY
    specifies the stretch option to use for the y-coordinate. See stretch constants.
    ready
    returns a promise for when the object is ready
    resource
    specifies the imageResource to be used by this image

    Note that setting url will create an imageResource and set the resource property for this image.

    Note that w or h equal to -1 will cause the image to be rendered using the imageResource's associated property.


    Image9 instance inherits from Object

    Properties

    url
    specifies the url of the image to load. Supports .png and .jpg
    insetLeft
    specifies the first slicing offset on the x-axis
    insetTop
    specifies the first slicing offset on the y-axis
    insetRight
    specifies the second slicing offset on the x-axis
    insetBottom
    specifies the second slicing offset on the y-axis
    ready
    returns a promise for when the object is ready
    resource
    specifies the imageResource to be used by this image9

    Note that setting url will create an imageResource and set the resource property for this image9.


    ImageA instance inherits from Object

    Properties

    url
    specifies the url of the image to load. Supports animated PNGs (as of release 0.28) and GIFs (as of release 1.7). Check for (scene.capabilities.graphics.gif >= 1) in a Spark application to confirm GIF support is available.
    ready
    returns a promise for when the object is ready
    resource
    specifies the imageAResource to be used by this imageA

    Note that setting url will create an imageAResource and set the resource property for this imageA.


    Text instance inherits from Object

    Text height and width are determined at runtime based on the text value, font, pixelSize, etc.

    Properties

    text
    specifies the text to render
    textColor
    specifies the color to render the text. eg. 0xff0000ff,opaque red,0xrrggbbaa. defaults to opaque black [0x000000ff].

    NOTE: Web style "#rgb", "#rrggbb" and color names are also supported as a convenience shortcut. See Basics for more information.
    pixelSize
    specifies the pixelSize of the rendered text
    fontUrl
    specifies the url of the face to use.
    ready
    returns a promise for when the object is ready
    font
    specifies the fontResource to be used by this text

    Note that setting url will create a fontResource and set the font property for this text.


    TextBox instance inherits from Text

    Unlike Text, the height and width of TextBox does NOT change based on the text value; instead, the height and width values in constructor and assignments are respected, and the text is rendered within those dimensions, according to the property values, below.

    Behaviors for alignment, wordWrap and clip:
    • If truncation is none and wrap is true, then the text will continue to flow beyond the height of the bounding rectangle, possibly cut off if clip is applied.
    • If truncation is none, and wrap is false, then the line(s) (that /n case has to be taken into consideration) should be centered in the view, even if the text goes beyond its x/width boundaries. If clip is true, text is cut off on either end. Such as:

        alignHorizontal CENTER
          The qu|ick brown fox jumped over the la|zy dog
                      |ick brown fox jumped over the la|

        Or

        alignHorizontal RIGHT
          The quick br|own fox jumped over the lazy dog|
                              |own fox jumped over the lazy dog|

    Properties

    wordWrap
    when width > 0, and wordWrap is true, wraps text at width of text box. defaults to false.
    xStartPos
    x position relative to the text box object, in pixels, for the first line of text only, similar to an indent. defaults to 0.
    NOTE: xStartPos and xStopPos are only applied when horizontalAlign=LEFT.
    xStopPos
    x position where text must stop flowing on the last line of text only. If ellipses are applied, the ellipses must also stop at this location. defaults to 0.
    NOTE: xStartPos and xStopPos are only applied when horizontalAlign=LEFT.
    NOTE: xStopPos can only be applied when truncation is true.
    ellipsis
    indicates if ellipsis shall be shown when truncation occurs. Ignored if truncation=NONE. defaults to false.
    truncation
    see truncation constants. defaults to NONE.
    alignHorizontal
    see horizontal alignment constants. defaults to LEFT.
    alignVertical
    see vertical alignment constants. defaults to TOP.
    leading
    number of pixels of height to apply between lines of text when multiple lines of text exist. May be negative. defaults to 0.

    Methods

    measureText
    returns an object with the following properties (measurements are relative to (x,y) of the TextBox object's parent):
  • bounds - object - {x1:0, y1:0, x2:0, y2:0} - The two points representing the bounding rectangle of the complete text
  • charFirst - {x:0, y:0} - The x position represents the left most rendered pixel of the first character on the first line of text. The y position represents the baseline.
  • charLast - {x:0, y:0} - The x position represents the right most rendered pixel of the last character on the last line of text. The y position represents the baseline.


    • Wayland instance inherits from Object

    Creates an element which contains a Wayland display. Any Wayland clients that connect to this display will appear in this element.

    Properties

    displayName
    Specifies the name of the Wayland display. If no value is assigned a unique name will be generated
    cmd
    Specifies a command to launch a Wayland client app to connect to the display. Consists of the client name optionally followed by arguments
    server
    Specifies the name of an rtRemote server
    clientPID
    Gives the process pid of the connected Wayland client
    fillColor
    specifies the color to fill the interior of the element. eg. 0xff0000ff, opaque red, 0xrrggbbaa. This will provide background for the connected Wayland client
    hasApi
    indicates if the element exports an API.
    api
    If hasApi is true, then this is the element's exported API
    remoteReady
    returns a promise for when the remote object is ready

    Methods

    suspend(bool)
    Causes the element to cease drawing
    resume(bool)
    Causes the element to resume drawing
    destroy(bool)
    Destroys the element


    SceneContainer instance inherits from Object

    Properties

    url
    specifies the url of the JavaScript to use for the child scene


    Resource instance

    Note: Once Resource is created, the url and proxy are readonly.

    Properties

    url
    url to the resource to be loaded
    proxy
    http proxy url to be used while downloading
    ready
    returns a promise when the resource is loaded (Read only)
    loadStatus
    array of status values (Read only)


    imageResource instance inherits from Resource

    Properties

    w
    pixel unit width of the image
    h
    pixel unit height of the image

    SVG support in imageResource

    See SVG imageResource page.

    imageAResource instance inherits from Resource

    Properties

    w
    pixel unit width of the image
    h
    pixel unit height of the image


    fontResource instance inherits from Resource

    Methods

    getFontMetrics(pixelSize)
    Returns information about the font based on pixelSize. See section 3.a in http://www.freetype.org/freetype2/docs/tutorial/step2.html. The returned object has the following properties:
  • height - float - the distance between baselines
  • ascent - float - the distance from the baseline to the font ascender (note that this is a hint, not a solid rule)
  • descent - float - the distance from the baseline to the font descender (note that this is a hint, not a solid rule)
  • naturalLeading - float - the distance that must be placed between two lines of text (See linegap in section 2 in http://www.freetype.org/freetype2/docs/glyphs/glyphs-3.html#section-1)
  • baseline - float - the baseline position for a line of text
    • measureText(pixelSize, textToMeasure)
    Returns an object from which height and width of the measured text can be obtained. Note that this measurement does not consider truncation, word wrapping or alignment that could be used in a TextBox containing this text.
  • h - float - the height of the text
  • w - float - the width of the text


    • Animate

    The Animate object is returned from the animate() method. It can be used to check on the status of an animation, as well as to cancel the animation.

    Properties

    done
    Promise that indicates completion of the animation
    type
    the type (option) of the animation, e.g. whether the animation loops or oscillates. See option animation constants for valid values. (Read only)
    interp
    Indicates the interpolator used for this animation. See interpolator animation constants for valid values. (Read only)
    status
    status of the animation. See status animation constants for valid values. Note that this is the constant name returned as a string rather than as its numeric value. (Read only)
    provduration
    duration value used when the animate function was called (Read only)
    provcount
    count value used when the animate function was called. Could be positive numeric value or a constant. See animation constants for valid constant values. (Read only)/dd>
    cancelled
    reflects whether or not the animation has been canceled. (Read only)
    props
    object whose properties are the properties that are being animated, and those property values are the target values for the animation
    details
    object whose properties are the properties that are being animated, and those property values are an AnimationDetail object reflecting the current state of the animation for that property.

    Methods

    cancel()
    Cancels the animation.


    AnimationDetail

    Properties

    from
    the start value for the current state of this animation. (Read only)
    to
    the end value for the current state of this animation. (Read only)
    duration
    the duration value for the current state of this animation. (Read only)
    count
    current count number for this animation. (Read only)
    status
    current status for this animation. See status animation constants for valid values. Note that this is the constant name returned as a string rather than as its numeric value. (Read only)


    animation Constants

    http://www.pxscene.org/examples/px-reference/gallery/dynamics.js demonstrates the different animation interpolators available.

    Properties

    Interpolators

    returns a collection of valid TWEEN_ and EASE_ interpolator constants
    TWEEN_LINEAR
    constant for specifying a linear tween. constant value is 0.
    TWEEN_EXP1
    constant for specifying a exp1 tween. constant value is 1.
    TWEEN_EXP2
    constant for specifying a exp2 tween. constant value is 2.
    TWEEN_EXP3
    constant for specifying a exp3 tween. constant value is 3.
    TWEEN_STOP
    constant for specifying a stop (easein) tween. constant value is 4.
    EASE_IN_QUAD
    constant for specifying a "inquad" tween. constant value is 5.
    EASE_IN_CUBIC
    constant for specifying a "incubic" tween. constant value is 6.
    EASE_IN_BACK
    constant for specifying a "inback" tween. constant value is 7.
    EASE_IN_ELASTIC
    constant for specifying a "easeinelastic" tween. constant value is 8.
    EASE_OUT_ELASTIC
    constant for specifying a "easeoutelastic" tween. constant value is 9.
    EASE_OUT_BOUNCE
    constant for specifying a "easeoutbounce" tween. constant value is 10.

    Options

    OPTION_OSCILLATE
    constant for use as the type in the animateTo method. the animation with oscillate back and forth. constant value is 1.
    OPTION_LOOP
    constant for use as the type in the animateTo method. the animation will loop continuously. constant value is 2.
    OPTION_FASTFORWARD
    constant for use as an option in the animateTo method. This value can be OR'd with the OPTION type to indicate that any animations in progress should fastforward to their ending values. constant value is 8.
    OPTION_REWIND
    constant for use as the type in the animateTo method. This value can be OR'd with the OPTION type to indicate that any animations in progress should rewind to their beginning values. constant value is 16.

    Count

    COUNT_FOREVER
    constant to use as count to indicate the animation should never end. When using this value, the promise for the animation will resolve immediately. constant value is -1.

    Status

    IDLE
    constant to indicate that the animation has not yet started. constant value is 0.
    INPROGRESS
    constant to indicate that the animation is in progress. constant value is 1.
    CANCELLED
    constant to indicate that the animation has been cancelled. constant value is 2.
    ENDED
    constant to indicate that the animation has ended. constant value is 3.


    stretch Constants

    Properties

    NONE
    constant for use in image stretch options. constant value is 0.
    STRETCH
    constant for use in image stretch options. constant value is 1.
    REPEAT
    constant for use in image stretch options. constant value is 2.


    Vertical Alignment Constants

    Properties

    TOP
    begin text at the upper-most y-coordinate of the textBox. constant value is 0.
    CENTER
    center text vertically within the textBox. constant value is 1.
    BOTTOM
    justify text to the bottom of the textBox. constant value is 2.


    Horizontal Alignment Constants

    Properties

    LEFT
    left-justify text in the textBox. constant value is 0.
    CENTER
    center text horizontally in the textBox. constant value is 1.
    RIGHT
    right-justify text in the textBox. constant value is 2.


    Truncation Constants

    Properties

    NONE
    text is not truncated. constant value is 0.
    TRUNCATE
    text is truncated at the bottom of the textBox. The last word may be partially truncated. constant value is 1.
    TRUNCATE_AT_WORD
    text is truncated at the bottom of the textBox. Truncation occurs at the word boundary. constant value is 2.


    Version: Bleeding Edge.