• Home
• Platform
• Download
• Documentation
• Community
• Wiki
• Blog

From OpenLaszlo

This proposal describes the core APIs required to run OpenLaszlo in a new runtime environment.

Each runtime consists of a kernel, which provides a clean abstraction between OpenLaszlo and runtime-specific details. Each kernel is a collection of classes in two major categories: sprite classes, and environment classes. Sprite classes handle the visual display of OpenLaszlo views, text and input text boxes. Environment classes provide supporting APIs for handling mouse and keyboard events, getting timing information, and loading data or code at runtime.

To be as useful as possible to the community, kernel implementations avoid dependencies on OpenLaszlo. For example, sprite classes use callback methods to communicate internal state changes instead of OpenLaszlo events. Also, sprites use JavaScript prototype-based inheritance instead of the OpenLaszlo class system.

Contents 1 Status 2 Contributors 3 Requirements 4 Sprite Classes 4.1 Sprite 4.1.1 Constructor 4.1.2 Methods 4.1.3 Callback methods 4.2 Text Sprite 4.2.1 Constructor 4.2.2 Methods 4.2.3 Callback methods 4.3 Input text Sprite 4.3.1 Constructor 4.3.2 Methods 4.3.3 Callback methods 5 Environment Classes 5.1 LzKeyboardKernel 5.1.1 Methods 5.1.2 Callback Methods 5.2 LzMouseKernel 5.2.1 Methods 5.2.2 Callback Methods 5.3 LzIdleKernel 5.3.1 Methods 5.3.2 Callback Methods 5.4 HTTP Loader 5.4.1 Constructor 5.4.2 Methods 5.4.3 Callback Methods 5.5 XML Parser 5.6 LzDataNode Copier 5.7 Snippet/code Loading 6 Implementation Notes

Status

This is a draft, and will be expanded and updated as refactoring continues in Legals.

Contributors

Max Carlson wrote this proposal.

Requirements

Describe the APIs required to get applications like LzPix running on new runtimes.

Sprite Classes

Each sprite implementation consists of several JavaScript classes. Sprite classes use prototype-based inheritance when appropriate. Sprites may call callback methods their owner to communicate state changes.

Sprite

Each Sprite represents a visual object in the runtime display hierarchy.

Constructor

new Sprite( Object:owner, Boolean:isroot )

The constructor has two arguments:

• a reference to the owner object
• isroot determines if the sprite is the root display object (canvas) or not

Methods

• init()
  • Called by the owner object when it inits

• addChildSprite(Sprite:sprite)
  • Adds a child sprite to this sprite's display hierarchy

• setResource( String:resource )
  • Displays a compiled-in resource (by name)
  • Calls setSource to load media if resource is an URL
  • Uses the resourceload callback method when the resource finishes loading

• setSource( String:url )
  • Loads and displays media from the specified url
  • Uses the resourceload callback method when the resource finishes loading

• setClickable( Boolean:clickable )
  • If true, sets the sprite to be clickable and receive mouse events through the mouseevent callback method
  • If false, sets the sprite to be unclickable and not receive mouse events

• setX( Number:x )
  • Moves the sprite to the specified x coordinate

• setY( Number:y )
  • Moves the sprite to the specified y coordinate

• setWidth( Number:width )
  • Sets the sprite to the specified width

• setHeight( Number:height )
  • Sets the sprite to the specified height

• setVisible( Boolean:visibility )
  • Sets the visibility of the sprite

• setColor( String/Number:color )
  • Sets the foreground color of the sprite
  • Can be a number (0xff00ff) or a string ('#ff00ff')

• setBGColor( String/Number:color )
  • Sets the background color of the sprite
  • Can be a number (0xff00ff) or a string ('#ff00ff')

• setOpacity( Number:opacity )
  • Sets the opacity of the sprite

• play( Number:framenumber )
  • Plays a multiframe resource starting at the specified framenumber
  • Plays from the current frame if framenumber is null

• stop( Number:framenumber )
  • Stops a multiframe resource at the specified framenumber
  • Stops at the current frame if framenumber is null

• setClip( Boolean:clip )
  • If true, clips the sprite's children to its width and height
  • If false, does not clip the sprite's children to its width and height

• stretchResource( String:axes )
  • Causes the sprite to stretch its resource along axes, either 'width' 'height' or 'both' so the resource is the same size as the sprite along those axes.
  • If axes is not 'width', 'height' or 'both', the resource is sized to its natural/default size, rather than the sprite's size

• destroy( Boolean:recursive )
  • Causes the sprite to destroy itself
  • if recursive is true, the sprite destroys all its children as well

• getMouse( String:xory )
  • Returns the mouse position for this sprite, for either 'x' or 'y'

• getWidth()
  • Returns the current width of the sprite

• getHeight()
  • Returns the current height of the sprite

• bringToFront()
  • Brings this sprite to the front of its siblings

• sendToBack()
  • Sends this sprite to the back of its siblings

• setStyleObject( Object:style )
  • Sets the style object of the sprite

• getStyleObject()
  • Gets the style object of the sprite

Callback methods

• resourcesize( Number:resourceWidth, Number:resourceHeight, String:resourceName);
  • Returns the width, height and name of a compiled or runtime-loaded resource

• resourceloaded( String:resourceName);
  • Returns the width, height and name of a compiled or runtime-loaded resource

• mouseevent( String:eventName);
  • Returns the name of the mouse event that occurred, either 'onclick', 'onmouseover', 'onmouseout', 'onmousedown' or 'onmouseup

Text Sprite

TextSprite extends Sprite to display styled text

Constructor

new TextSprite( Object:owner )

The constructor has one argument:

• a reference to the owner object

Methods

• setFontSize( Number:size )
  • Sets the size of the font in pixels

• setFontStyle( String:style )
  • Sets the style of the font
  • can be 'plain', 'normal', 'italic', 'bolditalic' or 'bold italic'

• setFontName( String:name )
  • Sets the name of the font
  • Can be a comma-separated list of font names

• setColor( String/Number:color )
  • Sets the color of the text.
  • Can be a number (0xff00ff) or a string ('#ff00ff')

• setText( String:text )
  • Sets the contents to the specified text
  • Uses the widthchange callback method if multiline is false and text is not resizable
  • Uses the heightchange callback method if multiline is true

• setMultiline( Boolean:multiline )
  • If true, sets the text to display across multiple lines
  • If false, sets the text to display on a single line

• setSelectable( Boolean:multiline )
  • If true, sets the text to be selectable
  • If false, sets the text not be selectable

• getTextWidth()
  • Returns the width of the current text in pixels

• getTextHeight()
  • Returns the height of the current text in pixels

• getText()
  • Returns the current text

Callback methods

• heightchange( Number:height )
  • Returns the new height of the text field

• widthchange( Number:width )
  • Returns the new width of the text field

Input text Sprite

InputTextSprite extends TextSprite to display styled input text fields

Constructor

new InputTextSprite( Object:owner )

The constructor has one argument:

• a reference to the owner object

Methods

• setText( String:text )
  • Sets the contents of this text input field to the specified text

• getText()
  • Returns the current contents of this text input field

Callback methods

• inputtextevent( String:eventName, String:keyValue );
  • Returns the name of the input text event that occurred, either 'onblur', 'onfocus', 'onclick', 'onkeyup' 'onkeydown' or 'onselect'
  • 'onkeyup' and 'onkeydown' also return the keyValue, a string corresponding to the key going up or down
  • When focused, the inputtext control sends onkeyup and onkeydown events.
  • When focus snters the inputtext, onfocus is sent.
  • When focus leaves the inputtext, onblur is sent.
  • When the mouse is clicked in the inputtext, onclick is sent.

Environment Classes

Environment classes provide runtime-specific routines to access mouse and keyboard events, timers and idle hooks, and load data or code at runtime. Note: onkeydown and onkeyup events in the LFC will send string representations instead of numeric

LzKeyboardKernel

Handles global keyboard events

Methods

• setCallback( Object:scope, String:funcname )
  • Sets the callback function and scope to receive keyboard events.

Callback Methods

• The callback function is expected to conform to the signature ( Object:delta, Number:keyCode, String:eventname )
  • delta is an object containing string representations of keycodes that have changed since the last keyboard event
  • keyCode is the numeric representations of the keycode for the keyboard event - note that this must conform with Flash keycodes
  • eventname is the name of the event, e.g. 'onkeydown'

LzMouseKernel

Handles global mouse events

Methods

• setCallback( Object:scope, String:funcname )
  • Sets the callback function and scope to receive mouse events

Callback Methods

• The callback function is expected to conform to the signature ( String:eventname )
  • eventname the name of the mouse event, e.g. 'onmouseup'

LzIdleKernel

Handles idle events

Methods

• addCallback( Object:scope, String:functionname )
  • Adds a callback function to receive idle events, returning an opaque ID.
• removeCallback( Object:scope, String:functionname )
  • Removes a callback function so it no longer receives idle events.

Callback Methods

• The callback function is expected to conform to the signature ( Number:timer )
  • timer contains the number of milliseconds since application startup

HTTP Loader

Handles loading over HTTP/HTTPS.

Constructor

new HTTPLoader( Object:owner , boolean:proxied, Object:dataset)

The constructor has three arguments:

• owner: a reference to the owner object
• proxied: if true proxy requests through server; defaults to canvas.proxied
• dataset: a pointer to an LzDataset object which will receive the data

Methods

• request( String:type, String:url, Array:headers)
  • type can be 'get', 'post', 'put' or 'delete'

• getResponseText()
  • Returns the response as a string

• getResponseXML()
  • DOM-compatible document object of data returned from server process

• getResponseStatus()
  • Returns numeric status code (200, 404, 500, etc...)

• getResponseHeaders()
  • Returns an array of response headers

• abort()
  • Abort the request

• setOption (String:key, String:val)
  • Set option KEY to VAL

• setProxied (boolean:proxied)
  • Sets the request to use server data proxy

• setQueryParams (Object:qparams)
  • Table of key/value pairs to be sent with the query

• setQueryString(String:qstring)
  • URL query arg string to append to URL

• setQueuing( Boolean:queueRequests )
  • If queueRequests is true, subsequent requests will made sequentially
  • If queueRequests is false, subsequent requests will interrupt requests already in process

• getResponseHeader (String:key)
  • Returns the HTTP response header named KEY

• open (String:method, String:url, String:username, String:password)
  • Open an HTTP connection to server using method (one of 'post', 'get', 'put', 'delete')
  • optional Http Auth username and password may be supplied

• makeProxiedURL (Object:options )
  • Returns URL encoded to be passed to the OpenLaszlo data proxy server. Options are: url, reqtype (GET|POST), lzt (defaults to xmldata)

• send (String:content)
  • Sends HTTP request to server, with optional content string (only used when POST method is selected)

• setTimeout (int:timeout)
  • Sets timeout in milliseconds of request. Defaults to LzHTTPLoader.timeout

• setRequestHeader (String:key, String:value)
  • Set request header KEY to VALUE

Callback Methods

Each callback method returns a reference to the loader object, where the response, status codes and headers can all be accessed.

• loadSuccess( Object:LzHTTPLoader, LzDataElement:data )
  • On successful load, the data is returned as an LFC LzDataElement node
• loadTimeout( Object:LzHTTPLoader, LzDataElement:data )
  • Called when the load times out
• loadError( Object:LzHTTPLoader, LzDataElement:data )
  • Called when the load encounters an error (in data load or conversion)

XML Parser

Takes a string and returns a tree of native DOM nodes

LzDataNode Copier

Takes a tree of native DOM nodes and returns a tree of Laszlo DOM nodes

Snippet/code Loading

TBD

Implementation Notes

In the current implementation, Laszlo views delegate to member sprite objects that handle the underlying work of updating the display. Each runtime-specific implementation is kept under a separate directory.

The Legals project currently has sprite implementations for DHTML and SWF7/8 at: http://svn.openlaszlo.org/openlaszlo/branches/legals/WEB-INF/lps/lfc/kernel/