Grimace for Developers and Researchers

API

This API exposes methods which allow control of the Grimace component from various programming environments. Currently supported environments are JavaScript, ActionScript 3.0 and Flex 3.0.

See also



Methods
 MethodDefined by
  
capture(format:String = "PNG"):void
Captures the currently displayed image and uploads it to a server.
ExternalCommands
  
draw():void
Forces a redraw.
ExternalCommands
  
getEmotion():Object
Gets the currently displayed emotion state.
ExternalCommands
  
getMaxBounds(scaled:Boolean = true):Object
Returns the horizontal and vertical size of the face.
ExternalCommands
  
getPosition():Object
Returns the current position of the face.
ExternalCommands
  
isReady():Boolean
Returns true if Grimace is ready for commands.
ExternalCommands
  
loadFacedata(urls:Array, urlPrefix:String = ""):void
Attempts to load a face description from facedata XML.
ExternalCommands
  
resetEmotion(fadeTime:Number = 0):void
Resets the face to a neutral expression.
ExternalCommands
  
restart():void
Clears active face description and hides the face in preparation for new facedata.
ExternalCommands
  
setCaptureUrl(url:String):void
Defines the URL of the server-side script which handles uploads of captured images.
ExternalCommands
  
setEmotion(emotionSet:Object, fadeTime:Number = 0):void
Defines a new set of emotions to be displayed by grimace.
ExternalCommands
  
setMaxBounds(maxWidth:Number = 0, maxHeight:Number = 0):void
Defines a rectangle to fit the face in.
ExternalCommands
  
setPosition(x:Number, y:Number):void
Moves the face to the position supplied.
ExternalCommands
  
setScale(scale:Number):void
Manually sets a factor to proportionally scale the face.
ExternalCommands
  
setScaleMode(mode:String = "noScale"):void
Sets whether the face should be scaled to fit the container.
ExternalCommands

Event related methods

  
addEventListener(eventType:String, callback:String):Boolean
Registers an event listener.
JSHandler
  
removeEventListener(eventType:String, callback:String):Boolean
Removes a previously registered event listener.
JSHandler
Method detail
capture()method
public function capture(format:String = "PNG"):void

Captures the currently displayed image and uploads it to a server.

When the upload is finished, the script returns the URL of the uploaded image, which is then dispatched as Event.

Parameters
format:String (default = "PNG") — Defines the image format. Valid options are PNG and JPG.

See also

draw()method 
public function draw():void

Forces a redraw.

When a muscle or emotion has changed, the face is re-drawn automatically. An initial manual call of draw is necessary after loading new facedata description.

See also

getEmotion()method 
public function getEmotion():Object

Gets the currently displayed emotion state.

Only active emotions, i.e. emotions with value > 0 are included in the result.

Returns
Object — An object containing currently active emotions and their values.
getMaxBounds()method 
public function getMaxBounds(scaled:Boolean = true):Object

Returns the horizontal and vertical size of the face.

Parameters
scaled:Boolean (default = true) — If a scale factor by setScale() or setMaxBounds() should be taken into account.

Returns
Object — An Object containing "width" and "height" in pixels.
getPosition()method 
public function getPosition():Object

Returns the current position of the face.

The reference point is the upper-left corner of the face's bounding rectangle.

Returns
Object — An Object containing the horizontal position "x" and the vertical position "y" in pixels.
isReady()method 
public function isReady():Boolean

Returns true if Grimace is ready for commands.

This method can be used to determine if other commands can be yet issued, e.g. registering of event listeners.

Returns
Boolean — Always true.
loadFacedata()method 
public function loadFacedata(urls:Array, urlPrefix:String = ""):void

Attempts to load a face description from facedata XML.

Parameters
urls:Array — An array containing absolute or relative paths to the facedata XML files to be loaded.
urlPrefix:String (default = "") — A relative path from the embedding script to the Facedata files

See also

resetEmotion()method 
public function resetEmotion(fadeTime:Number = 0):void

Resets the face to a neutral expression.

Convenience method for supplying setEmotion with an empty object.

Parameters
fadeTime:Number (default = 0) — The time in seconds to morph the face to the neutral state. 0 displays instantly.

See also

restart()method 
public function restart():void

Clears active face description and hides the face in preparation for new facedata.

setCaptureUrl()method 
public function setCaptureUrl(url:String):void

Defines the URL of the server-side script which handles uploads of captured images.

Parameters
url:String — The URL of the upload script, absolute or relative to grimace.swf

See also

setEmotion()method 
public function setEmotion(emotionSet:Object, fadeTime:Number = 0):void

Defines a new set of emotions to be displayed by grimace.

A set of emotions consists of one or more emotions with arbitrary values. If more than one emotion is supplied, Grimace attempts to mix them. While no theoretical limit, mixtures of more than two emotions usually produce unintelligible results.

Parameters
emotionSet:Object — An Object which defines the emotion(s) to be displayed.
 
fadeTime:Number (default = 0) — The time in seconds to morph the face to the new emotion. 0 displays instantly.
setMaxBounds()method 
public function setMaxBounds(maxWidth:Number = 0, maxHeight:Number = 0):void

Defines a rectangle to fit the face in.

The face will be scaled proportionally to fit into the supplied dimensions.

This setting overwrites a manual scale factor set by setScale(). It can work in addition to resizing due to scale mode "showAll". If "showAll" is active, the supplied dimensions will be resized by the same factor as the face.

Parameters
maxWidth:Number (default = 0) — The maximum width of the face in pixels.
 
maxHeight:Number (default = 0) — The maximum height of the face in pixels.
setPosition()method 
public function setPosition(x:Number, y:Number):void

Moves the face to the position supplied.

The reference point is the upper-left corner of the face's bounding rectangle.

Parameters
x:Number — The horizontal distance in pixels from the left edge of the container.
 
y:Number — The vertical distance in pixels from the top edge of the container.
setScale()method 
public function setScale(scale:Number):void

Manually sets a factor to proportionally scale the face.

This setting overwrites a scale factor determined by setMaxBounds(). It can work in addition to resizing due to scale mode "showAll".

Parameters
scale:Number

See also

setScaleMode()method 
public function setScaleMode(mode:String = "noScale"):void

Sets whether the face should be scaled to fit the container.

noScale: The face will not be scaled to fit the container. Trimming might occur unless the face is manually resized by setScale() or setMaxBounds().

showAll: The face will be scaled proportionally to fit the container. Additional resizing through setScale() or setMaxBounds() is not advised. This option only works in a browser environment. The setting is ignored when Grimace is embedded in an ActionScript environment

Parameters
mode:String (default = "noScale") — The desired scale mode. Valid options: "noScale" and "showAll"

See also

addEventListener()method
public function addEventListener(eventType:String, callback:String):Boolean

Registers an event listener.

Parameters
eventType:String — Event type to listen to. See event page for available events.
 
callback:String — Function name to be called when the event is triggered.

Returns
Boolean — Returns true if listener was registered successfully.

See also

removeEventListener()method 
public function removeEventListener(eventType:String, callback:String):Boolean

Removes a previously registered event listener.

Multiple listeners can be registered for one event type. Thus, eventType and callback must be supplied to unregister the corresponding listener.

Parameters
eventType:String — Event type for which to unregister a listener.
 
callback:String — Function name for which listener was registered.

Returns
Boolean — Returns true if listener was removed successfully.

See also