Wiki

Clone wiki

SAGE2 / SAGE2 Application API - Widgets

Widgets

Three different types of widgets are available for custom applications. Namely:

  • Buttons

  • Sliders and

  • Text Input (Single line)

To add a widget element:

init: function(id, width, height, resrc, date) {
        ...
        this.controls.<addWidget>(paramObject);

        this.controls.finishedAddingControls();
}

Button

To add a button to the widget bar, the application may call addButton function on the controls. AddButton function takes one object with three properties, namely type, sequenceNo, and id. Type specifies the type of the button (appearance and animation of the button). sequenceNo specifies the position of the button around the radial dial of the UI. id is used to associate the button-press event to action code in the app.event handler.

The type property can take any value out of a list of predefined values such as - play-pause, play-stop, rewind, fastforward, prev, next, and so on. A custom defined Type can also be added to the list of Types available to any app by calling addButtonType function on the controls object. This function takes a string value for the name of the type being defined and a type object as it parameters. The example below illustrates the addition of a new type, and the way the id field of a button description is used to link the button to action code in the app.event handler.

var plusButton = {
    "state": 0,
    "from":"m 0 -6 l 0 12 m 6 -6 l -12 0", //svg paths
    "to":"m 6 0 l -12 0 m 6 6 l 0 -12",
    "width":12,
    "height":12,
    "fill":"none",
    "strokeWidth": 1,
    "delay": 600,
    "textual":false,
    "animation":true
};
this.controls.addButtonType("plus", plusButton);

this.controls.addButton({type:"plus", sequenceNo:1, id:"PlusButton"});
this.controls.addButton({type:"rewind", seqeunceNo:7, id:"RewindButton"});
this.controls.finishedAddingControls();

//In the event handler with in the custom app code:
event: function(eventType, position, userId, data, date) {
    if (eventType === "widgetEvent"){
        switch(data.identifier){
            case "PlusButton":
                // Code to be executed when plus button is clicked
                break;
            case "RewindButton":
                // Code to be executed when rewind button is clicked
                break;
            // Other controls follow
        }

    }
}

Slider

To add a slider to the widget bar, the application may call addSlider function on the controls. addSlider function takes an object with the following properties:

  • appObj: The instance of the application that is bound to this slider. Usually 'this' reference is set as the value of appObj.

  • property: A string representing the property of the application that is tied to the slider. (A change in the value of appObj.property will be reflected in the slider and vice versa)

  • begin: starting (minimum) value of the property associated with the slider.

  • end: last (maximum) value of the property associated with the slider.

  • increments: The step value change that occurs in the property when the slider is moved one unit. (alternatively, parts can be specified in place of increments, where parts represents the number of increments from begin to end)

  • id: String to associate slider events to action code in the app.event handler.

  • caption(optional): caption takes a small(length < 6) string and sets a visible label in front of the slider control using this string.

this.controls.addSlider({
                            begin:  ,
                            end:  ,
                            increments:  ,
                            appObj:  ,
                            property: ,
                            id:  "exampleSlider",
                        });

//In the event handler with in the custom app code:
event: function(eventType, position, userId, data, date) {
    if (eventType === "widgetEvent"){
        switch(data.identifier){
            case "exampleSlider":
                switch (data.action){
                    case "sliderLock":
                        // Code to be executed when slider is pressed upon by the user
                        break;
                    case "sliderUpdate":
                        // Code to be executed when slider is dragged by the user
                        break;
                    case "sliderRelease":
                        // Code to be executed when slider is released by the user
                        break;
                }
                break;

            // Other controls follow
        }

    }
}

Text Input

To add a text input to the widget bar, the application may call addTextInput function on the controls. addTextInput function takes an object with id as a mandatory property and two optional properties namely defualtText and caption. id is a String to associate action code in the app.event handler to the "Enter"(or "Return") key event, which marks the end of the input. defualtText can be set to any string value and the widget will be created by placing this string in the text area. caption takes a small(length < 6) string and sets a visible label in front of the text input control using this string.

this.controls.addTextInput({defaultText: "", caption:"Addr", id:"Address"});

//In the event handler with in the custom app code:
event: function(eventType, position, userId, data, date) {
    if (eventType === "widgetEvent"){
        switch(data.identifier){
            case "Address":
                // Code to be executed when Enter key is hit by the user
                break;

            // Other controls follow
        }
    }
}

Updated