Layer (SignStix JS API)

Layer

Javascript-to-Player interface representing a layer within a sign, as defined in SignStix Creator. It can be used as follows:

 
 <script type="text/javascript>
   // Access a SignStix layer by its name.
   var priceLayer = SignStixGraphics.getLayerNamed('Price');

   // Modify properties of that layer.
   priceLayer.setText('£9.99!');
   priceLayer.setFontSize(80);
   priceLayer.setFontColour('#00FF00'); // Green

   // Tell SignStix to update its graphics accordingly.
   SignStixGraphics.updateDisplay();
 </script>

Note that when dealing with layer coordinates, the origin (0, 0) is at the top left of the sign.

Function Summary

All Functions Instance Functions Abstract Functions
Modifier and Type	Function and Description
`void`	`addCarouselImage(String fileRef, String newLayerName)` Add an image to the end of the carousel layer's image list.
`void`	`carouselShiftDown()` Attempt to decrement this carousel layer's selection index and invoke animations on the carousel's images to reflect that change.
`void`	`carouselShiftUp()` Attempt to increment this carousel layer's selection index and invoke animations on the carousel's images which reflect that change.
`void`	`clearCarousel()` Remove any images from this carousel layer and set its selection index to 0.
`String`	`getBlockColour()` Find the colour of this block layer.
`int`	`getCarouselSelectionIndex()` Find the current selection index of this carousel layer.
`String`	`getFontColour()` Find the font colour of this text layer.
`String`	`getFontFace()` Find the font face name of this text layer.
`int`	`getFontSize()` Find the font size of this text layer.
`String`	`getFontWeight()` Find the weight of this text layer.
`int`	`getHeight()` Find the Height of this layer within the sign.
`int`	`getId()` Find the ID of this layer.
`int`	`getLeft()` Find the basic left coordinate of this layer within the sign.
`String`	`getName()` Find the name of this layer, if any.
`int`	`getNumCarouselImages()` Find the number of images in this carousel layer's image list.
`String`	`getText()` Find the current text in this text layer.
`int`	`getTop()` Find the basic top coordinate of this layer within the sign.
`int`	`getWidth()` Find the Width of this layer within the sign.
`boolean`	`isSelected()` Find out if this image layer is in the selected state.
`void`	`setBlockColour(String htmlColour)` Set the colour of this block layer to be the argument.
`void`	`setCarouselSelectionIndex(int index)` Attempt to set the selection index of this carousel layer, which may cause images to reposition accordingly.
`void`	`setFontColour(String htmlColour)` Set the font colour of this text layer to be the argument.
`void`	`setFontFace(String fontName)` Set the font face of this text layer to be the argument.
`void`	`setFontSize(int size)` Set the font size of this text layer to be the argument.
`void`	`setFontWeight(String weight)` Set the weight of this text layer to be the argument.
`void`	`setHeight(int px)` Set the Height of this layer within the sign.
`void`	`setImageFromFile(String fileRef)` Set the image source of this image layer to be a specific file in the associated folder structure.
`void`	`setImageFromLayerNamed(String layerName)` Set the image source of this image layer to be the same as that of the argument image layer.
`void`	`setImageFromUrl(String imageUrl, boolean forceNewDownload, String jsFunctionName)` Set the image source of this layer to be the image file available at the argument URL.
`void`	`setInteractive(boolean isInteractive)` Set the interactive state of a web view.
`void`	`setLeft(int left)` Set the basic left coordinate of this layer within the sign.
`void`	`setSelected(boolean selected)` Set the selected state of this image layer.
`void`	`setText(String text)` Set the text on this layer.
`void`	`setTextFromLayerNamed(String layerName)` Set the text on this text layer to be the same as that of the argument text layer.
`void`	`setTop(int top)` Set the basic top coordinate of this layer within the sign.
`void`	`setVisible(boolean visibility)` Set the visibility of the layer.
`void`	`setWidth(int px)` Set the Width of this layer within the sign.

- Function Detail
  - getName
```
String getName()
```
    Find the name of this layer, if any.
    
    Returns:
    
    the layer's name, or the empty string if it doesn't have a name.
    
    Since:
    
    Player 2.10.5
  - getId
```
int getId()
```
    Find the ID of this layer.
    
    Returns:
    
    the unique ID of this layer.
    
    Since:
    
    Player 2.10.5
  - setWidth
```
void setWidth(int px)
```
    Set the Width of this layer within the sign. Not suitable for video layer.
    
    Parameters:
    
    px - in pixels.
    
    Since:
    
    Player 3.3.6
  - setHeight
```
void setHeight(int px)
```
    Set the Height of this layer within the sign. Not suitable for video layer.
    
    Parameters:
    
    px - Height in pixels
    
    Since:
    
    Player 3.3.6
  - getWidth
```
int getWidth()
```
    Find the Width of this layer within the sign.
    
    Returns:
    
    Width in pixels.
    
    Since:
    
    Player 3.3.6
  - getHeight
```
int getHeight()
```
    Find the Height of this layer within the sign.
    
    Returns:
    
    px Height in pixels
    
    Since:
    
    Player 3.3.6
  - getLeft
```
int getLeft()
```
    Find the basic left coordinate of this layer within the sign.
    
    Returns:
    
    the coordinate of the layer's left-most edge, ignoring any animations.
    
    Since:
    
    Player 2.10.5
  - setLeft
```
void setLeft(int left)
```
    Set the basic left coordinate of this layer within the sign. This has no effect on any animations. Not suitable for video layer.
    
    Parameters:
    
    left - the new coordinate of the layer's left-most edge.
    
    Since:
    
    Player 2.10.5
  - getTop
```
int getTop()
```
    Find the basic top coordinate of this layer within the sign.
    
    Returns:
    
    the coordinate of the layer's top-most edge, ignoring any animations.
    
    Since:
    
    Player 2.10.5
  - setTop
```
void setTop(int top)
```
    Set the basic top coordinate of this layer within the sign. This has no effect on any animations. Not suitable for video layer.
    
    Parameters:
    
    top - the new coordinate of the layer's top-most edge.
    
    Since:
    
    Player 2.10.5
  - setVisible
```
void setVisible(boolean visibility)
```
    Set the visibility of the layer. True if need to make layer visible else false.
    
    Parameters:
    
    visibility - true if visible, otherwise false
    
    Since:
    
    Player 3.3.6
  - setText
```
void setText(String text)
```
    Set the text on this layer. Note that this will not change the bounding box of the text layer, so a long piece of text may wrap or not be visible.
    If the layer is not a text layer, this function will log an error and return.
    Call SignStixGraphics.updateDisplay() for the change to take effect.
    
    Parameters:
    
    text - the new text to adopt. Must not be null.
    
    Since:
    
    Player 2.10.2
  - getText
```
String getText()
```
    Find the current text in this text layer.
    If the layer is not a text layer, this function will log an error and return null.
    
    Returns:
    
    the current layer text, or null if this is not a text layer.
    
    Since:
    
    Player 2.10.2
  - setFontSize
```
void setFontSize(int size)
```
    Set the font size of this text layer to be the argument. If this layer is not a text layer, this function will log an error and return.
    
    Parameters:
    
    size - must be in the range 1 to 10000.
    
    Since:
    
    Player 2.10.2
  - getFontSize
```
int getFontSize()
```
    Find the font size of this text layer. If this layer is not a text layer, the function will log an error and return 0.
    
    Returns:
    
    the current font size, or 0 if this is not a text layer.
    
    Since:
    
    Player 2.10.2
  - setFontColour
```
void setFontColour(String htmlColour)
```
    Set the font colour of this text layer to be the argument. If this layer is not a text layer, this function will log an error and return.
    
    Parameters:
    
    htmlColour - font colour in HTML format e.g. '#FF0000' for red, '#00FF00' for green.
    
    Since:
    
    Player 2.10.2
  - getFontColour
```
String getFontColour()
```
    Find the font colour of this text layer. If this layer is not a text layer, the function will log an error and return null.
    
    Returns:
    
    the font colour in HTML format, or null if this is not a text layer.
    
    Since:
    
    Player 2.10.2
  - setFontFace
```
void setFontFace(String fontName)
```
    Set the font face of this text layer to be the argument. This will only succeed if the argument font is already known to the current sign. If this layer is not a text layer, the function will log an error and return.
    
    Parameters:
    
    fontName - the name of the required font.
    
    Since:
    
    Player 3.0.1
  - getFontFace
```
String getFontFace()
```
    Find the font face name of this text layer. If the receiving layer is not a text layer, this function will log an error and return the empty string.
    
    Returns:
    
    the current font face.
    
    Since:
    
    Player 3.0.1
  - setFontWeight
```
void setFontWeight(String weight)
```
    Set the weight of this text layer to be the argument. If this layer is not a text layer, or the weight is not recognised, the function will log an error and return.
    
    Parameters:
    
    weight - one of {"normal", "bold"}.
    
    Since:
    
    Player 3.0.1
  - getFontWeight
```
String getFontWeight()
```
    Find the weight of this text layer. If this layer is not a text layer, or the weight is not recognised, the function will log an error and return the empty string.
    
    Returns:
    
    one of {"normal", "bold"}.
    
    Since:
    
    Player 3.0.1
  - setImageFromLayerNamed
```
void setImageFromLayerNamed(String layerName)
```
    Set the image source of this image layer to be the same as that of the argument image layer. For example, this can be used to populate a template layer with a given image, in response to a touch.
    If the receiving layer is not an image layer, or the argument does not identify an image layer, this function will log an error and return.
    Call SignStixGraphics.updateDisplay() for the change to take effect.
    
    Parameters:
    
    layerName - the name of an image layer.
    
    Since:
    
    Player 2.10.5
  - setImageFromUrl
```
void setImageFromUrl(String imageUrl,
                     boolean forceNewDownload,
                     String jsFunctionName)
```
    Set the image source of this layer to be the image file available at the argument URL. This will download the image (subject to the rules below) and set it to be the layer's source.
    On completion, a callback function will be invoked to indicate success (or otherwise). On success, call SignStixGraphics.updateDisplay() for the change to take effect.
    Reasons for failure may include:
    - The receiving layer is not an image layer.
    - The imageUrl is not a valid URL.
    - The image could not be downloaded.
    - The storage usage of the device is already over a threshold so further downloads will not be attempted.
    In the case of failure, the details of the problem will be logged, and the success parameter of the callback will be set to false.
    Note that if the sign is restarted (e.g. as a result of a content re-deployment, or a device or application restart), the layer will revert to its original image.
    Parameters:
    
    imageUrl - URL of the image file to download (must be a PNG or JPEG file).
    
    forceNewDownload - when true, this will force a new download even if the file from a previous download for this URL is still available. When false, this will attempt to re-use a previously downloaded file, if there is one available.
    jsFunctionName - the name of a Javascript callback function that will be called on completion. It must take parameters as follows:
    
    String layerName - this layer's name.
    
    int layerId - this layer's ID.
    
    String imageUrl - the URL passed in originally.
    
    boolean success - true if the image was successfully downloaded (if appropriate) and incorporated into the layer.
    Since:
    
    Player 3.0.1
  - setImageFromFile
```
void setImageFromFile(String fileRef)
```
    Set the image source of this image layer to be a specific file in the associated folder structure.
    If the receiving layer is not an image layer, or the parameter does not resolve to a known file, this function will log an error and return false.
    Call SignStixGraphics.updateDisplay() for the change to take effect.
    
    Parameters:
    
    fileRef - file reference (produced by SignStixFiles) identifying an image file within the associated folder structure.
    
    Since:
    
    Player 3.2.1
  - setTextFromLayerNamed
```
void setTextFromLayerNamed(String layerName)
```
    Set the text on this text layer to be the same as that of the argument text layer. For example, this can be used to populate a template layer with some given text content, in response to a touch.
    Note that this will not change the bounding box of the text layer, so a long piece of text may wrap or not be visible.
    If the receiving layer is not a text layer, or the argument does not identify a text layer, this function will log an error and return.
    Call SignStixGraphics.updateDisplay() for the change to take effect.
    
    Parameters:
    
    layerName - name of the layer that provides the text.
    
    Since:
    
    Player 2.10.5
  - setBlockColour
```
void setBlockColour(String htmlColour)
```
    Set the colour of this block layer to be the argument. If this layer is not a block layer, this function will log an error and return.
    
    Parameters:
    
    htmlColour - block colour in HTML format e.g. '#FF0000' for red, '#00FF00' for green.
    
    Since:
    
    Player 3.2.1
  - getBlockColour
```
String getBlockColour()
```
    Find the colour of this block layer. If this layer is not a block layer, the function will log an error and return null.
    
    Returns:
    
    the block colour in HTML format, or null if this is not a block layer.
    
    Since:
    
    Player 3.2.1
  - isSelected
```
boolean isSelected()
```
    Find out if this image layer is in the selected state. If the receiving layer is not an image layer, this function will return false.
    
    Returns:
    
    true if the layer is an image layer and is selected.
    
    Since:
    
    Player 2.10.5
  - setInteractive
```
void setInteractive(boolean isInteractive)
```
    Set the interactive state of a web view. If the receiving layer is not an web view, nothing will happen.
    
    Parameters:
    
    isInteractive - true to set the layer interactive, false to non-interactive.
    
    Since:
    
    Player 3.3.6
  - setSelected
```
void setSelected(boolean selected)
```
    Set the selected state of this image layer. If the receiving layer is not an image layer, nothing will happen.
    
    Parameters:
    
    selected - true to select the layer, false to de-select.
    
    Since:
    
    Player 2.10.5
  - clearCarousel
```
void clearCarousel()
```
    Remove any images from this carousel layer and set its selection index to 0.
    If the receiving layer is not a carousel layer, this function will log an error and return.
    
    Since:
    
    Player 3.2.1
  - addCarouselImage
```
void addCarouselImage(String fileRef,
                      String newLayerName)
```
    Add an image to the end of the carousel layer's image list.
    If the receiving layer is not a carousel layer, this function will log an error and return.
    
    Parameters:
    
    fileRef - reference to an image file looked-up via SignStixFiles.
    
    newLayerName - the layer name to use when a layer is created for this image.
    
    Since:
    
    Player 3.2.1
  - getNumCarouselImages
```
int getNumCarouselImages()
```
    Find the number of images in this carousel layer's image list.
    If the receiving layer is not a carousel layer, this function will log an error and return 0.
    
    Returns:
    
    the number of images available to the carousel.
    
    Since:
    
    Player 3.2.1
  - getCarouselSelectionIndex
```
int getCarouselSelectionIndex()
```
    Find the current selection index of this carousel layer.
    If the receiving layer is not a carousel layer, this function will log an error and return -1.
    
    Returns:
    
    the selection index (from 0).
    
    Since:
    
    Player 3.2.1
  - setCarouselSelectionIndex
```
void setCarouselSelectionIndex(int index)
```
    Attempt to set the selection index of this carousel layer, which may cause images to reposition accordingly. An error will be logged if the index is outside the allowed range.
    If the receiving layer is not a carousel layer, this function will log an error and return -1.
    
    Parameters:
    
    index - the index in the image list to become selected (from 0 to the number of images).
    
    Since:
    
    Player 3.2.1
  - carouselShiftUp
```
void carouselShiftUp()
```
    Attempt to increment this carousel layer's selection index and invoke animations on the carousel's images which reflect that change.
    If the receiving layer is not a carousel layer, this function will log an error and return false.
    
    Since:
    
    Player 3.2.1
  - carouselShiftDown
```
void carouselShiftDown()
```
    Attempt to decrement this carousel layer's selection index and invoke animations on the carousel's images to reflect that change.
    If the receiving layer is not a carousel layer, this function will log an error and return false.
    
    Since:
    
    Player 3.2.1

Interface Layer

Function Summary

Function Detail

getName

getId

setWidth

setHeight

getWidth

getHeight

getLeft

setLeft

getTop

setTop

setVisible

setText

getText

setFontSize

getFontSize

setFontColour

getFontColour

setFontFace

getFontFace

setFontWeight

getFontWeight

setImageFromLayerNamed

setImageFromUrl

setImageFromFile

setTextFromLayerNamed

setBlockColour

getBlockColour

isSelected

setInteractive

setSelected

clearCarousel

addCarouselImage

getNumCarouselImages

getCarouselSelectionIndex

setCarouselSelectionIndex

carouselShiftUp

carouselShiftDown