Customize UI components with Starling Builder

Sometimes the built-in Starling Builder components and configs do not satisfy what you need, it's easy to customize it.

Customize component properties with config change

If you want to add a property into the property UI, or add some new UI components that's already linked into the editor, you don't need to recompile the app. All you need is to change a config file.

Open Workspace menu and click on edit template, the editor_template.json will open for you. It's located in YOUR_WORKSPACE/setting folder.

When you are done editing it, you need to restart Starling Builder to see the changes

When a new version is upgraded, the editor_template.json may be overridden by a new one. So it's a good idea to make a backup with the config file to preserve your changes.

Here's an example of adding the blendMode property to Image

{
    "cls":"starling.display.Image",
    "params":[
        {"name":"width", "component":"slider", "min":1, "max":2000, "step":1},
        {"name":"height", "component":"slider", "min":1, "max":2000, "step":1},
        {"name":"scaleX", "step":0.01, "default_value":1},
        {"name":"scaleY", "step":0.01, "default_value":1},
        {"name":"color", "component":"colorPicker", "default_value":16777215},
        {"name":"blendMode", "component":"pickerList", "options":["auto", "screen", "normal"], "default_value":"auto"}
    ],
    "constructorParams":
    [
        {"cls":"starling.textures.Texture"}
    ],
    "tag":"asset"
}

Create custom UI components with runtime library

If the UI components you want to use are not supported by Starling Builder, you can compile them into a swf file and drop them into YOUR_WORKSPACE/libs folder

Here's how it works

  • Feel free to add as many custom UI components as possible and compile them into the swf.
  • Drop the EmbeddedComponents.swf into YOUR_WORKSPACE/libs folder
  • Make sure to click on Workspace menu → delete template override, and reload the editor to make it work

When you add a new custom UI component, you need to complete 3 steps.

  1. Write the custom UI component class
  2. Write the config in custom_component_template.json
  3. Link the class to EmbeddedComponents.linkers

For more information you can take a look at the implementation of PixelMaskDisplayObject as an example.

You can also checkout List of official Custom UI Components

Editor Template Reference

Top level

namedescription
supported_componentsOfficial components and its properties supported by the editor
custom_componentsCustom components and its properties supported by the editor
default_componentcommon properties of any UI components
backgroundProperties for background
versionversion number of the template
revisionrevision number of the template, when there's any changes in the template, this number will increase, and the editor_template in the workspace will be overridenn

Inside supported_components or custom_components

namedescription
clsfull qualified name of the UI component class
paramseditable properties of the component, in addition to default_component.params
createButtonwhether create button will show up below the picker list
containerwhether the component can be a container of other components
tagwhat tab the component belongs to on the left, can be either asset, text, container or feathers
createComponentClassa full qualified class name of a class which will show up before creating the UI component

Inside params

namedescription
namename of property
componentcomponent of the inspector, for the time being the following components are supported: textInput, textArea, slider, check, pickerList, colorPicker, popup
clswhether the component is a class or a simple type
disablewhether the textInput is disabled
default_valuedefault value of the parameter in code. If the current value is equal to default value, then it won’t be saved to the layout file
editPropertyClassfull qualified class name when the edit button is triggered, only usable when component set to “popup”

Testing UI Component

Sometimes it’s not very convenient to build the swf, place it to the workspace and test it with the editor. In this case, use the test app inside tests folder to test it. You can simply replace the placer holder image with your own ui component and test it by launching the app.

  builder/custom-component.txt · Last modified: 2016/10/15 00:30 by johannh
 
Powered by DokuWiki