ToolBox Files

The Toolbox files describe controls to the IDE. They are used to create entries in the Toolbox window and to describe the operation of the control to the IDE. The files reside in:

• Windows: \program files\nsbasic\appstudio\toolbox
• Mac: Applications/AppStudio.app/Contents/Resources/toolbox

You are welcome to create your own ToolBox files - but keep a copy outside of the above directories. The file will be wiped out when you install a new version of AppStudio. If you have come up with a good one, send it to us: we'll test it and perhaps make it part of the AppStudio distribution.

Here is an annotated tour through one of the ToolBox files: Button_jqm.js. We will look at the file for the jqWidgets Button control:

The file is formatted as a JSON structure. They are loaded into the IDE at startup. It's important to keep the syntax correct: the control will not load properly if there are any errors. If you make changes to the file, you need to restart the IDE to see the effect. You can edit the file in a standard text editor, or copy it into an online JSON editor.

{ 

The name of the control. This isn't shown anywhere. It must be unique.

"_type": "Button_jqw", 

The base class of the control. There is also a Widget.js file in the ToolBox: this control starts with what is in that file and builds on it. Widget is a simple definition that is good for building on.

"_base": "Widget", 

Controls are categorized by palette number. For use defined controls, this is usually 4.

"_palette": 4, 

The name of the icon to use for the control. Should be a 16x16 .png file, with transparency for surrounding white space.

"_art": "images/extension.png", 

The shorthelp is displayed under the Properties Window when the control is selected. Can be any text.

"_shorthelp": "Buttons.  jqWidgets", 

Controls in the ToolBox are grouped by Category. This defines which categories the control belongs too. If more than one, use a comma separated list. The categories must be defined in Toolbox.js.

"_category": ["jqWidgets"],

Is the control resizable in the Design Screen?

"_resizable": true,

List of files that the control requires. In this example, jQuery is in the project folder, in nsb, while the other files come from the jqWidgets server. AppStudio will take care of bundling the files into the app.

"_requiredfiles": [
    "nsb/jquery.js",
    "http://jqwidgets.com/public/jqwidgets/styles/jqx.base.css",
    "http://jqwidgets.com/public/jqwidgets/styles/jqx.{theme}.css",
    "http://jqwidgets.com/public/jqwidgets/jqxcore.js",
    "http://jqwidgets.com/public/jqwidgets/jqxbuttons.js",
    "http://jqwidgets.com/public/jqwidgets/styles/images/bg_blueenergy.png",
    "http://jqwidgets.com/public/jqwidgets/styles/images/bg_darkblue.png",
    "http://jqwidgets.com/public/jqwidgets/styles/images/bg_black.png"
    ],

This is the name used to construct the id of the new control. It appears in the Project Explorer.

"_displayname": "Button",

This field isn't used yet.

"_longhelp": "longhelp",

"class": "",

"id": "", 
"_id": { 
    "desc": "Unique button identifier", 
    "type": "str" 
    },
    
"name": "", 
"_name": { 
    "desc": "Key in submitted form", 
    "type": "str" 
    }, 
    
"value": "Button", 
"_value": { 
    "desc": "The caption of the button", 
    "type": "str" 
    }, 
    
"style": "", 
"_style": { 
    "actype": "Style",
    "desc": "Styling rules for element", 
    "type": "css" 
    }, 

"top": 0, 
"_top": { 
    "acignore": true,
    "desc": "Location of top of element", 
    "type": "int" 
    }, 

"left": 0, 
"_left": { 
    "acignore": true,
    "desc": "Location of left side of element", 
    "type": "int" 
    }, 

"height": 32, 
"_height": { 
    "acignore": true,
    "desc": "Vertical size of element", 
    "type": "int" 
    }, 

"width": 100, 
"_width": { 
    "acignore": true,
    "desc": "Horizontal size of element", 
    "type": "int" 
    }, 

"hidden": "", 
"_hidden": { 
    "desc": "Hide control", 
    "type": "enum", 
    "keys": ["True", ""], 
    "values": ["hidden=\"true\";",""]
}, 

"theme": "classic",
"_theme": { 
    "desc": "Color theme for control.", 
    "type": "enum", 
    "keys": ["classic","darkblue","energyblue","shinyblack","summer","black","fresh","highcontrast","ui-darkness","ui-lightness","ui-le-frog","ui-overcast","ui-redmond","ui-smoothness","ui-start","ui-sunny"], 
    "values": ["classic","darkblue","energyblue","shinyblack","summer","black","fresh","highcontrast","ui-darkness","ui-lightness","ui-le-frog","ui-overcast","ui-redmond","ui-smoothness","ui-start","ui-sunny"]
    }, 

"roundedCorners": "jqx-rc-all",
"_roundedCorners": { 
    "desc": "Which corners should be rounded?", 
    "type": "enum", 
    "keys": ["All","Top","Bottom","Left","Right","Top-Right","Top-Left","Bottom-Right",
    "Bottom-Left"], 
    "values": ["jqx-rc-all","jqx-rc-t","jqx-rc-b","jqx-rc-r","jqx-rc-l","jqx-rc-tr","jqx-rc-tl","jqx-rc-br","jqx-rc-bl"]
    }, 

"buttonType": "Button",
"_buttonType": { 
    "desc": "Type of jqWidgets button", 
    "type": "enum", 
    "keys": ["Button","RepeatButton","LinkButton","ToggleButton"], 
    "values": ["Button","RepeatButton","LinkButton","ToggleButton"]
    }, 

"delay": 50,
"_delay": { 
    "acignore": true,
    "desc": "Time between two click events.", 
    "type": "int" 
   }, 

"disabled": "false", 
"_disabled": { 
    "desc": "Control disabled?", 
    "type": "enum", 
    "keys": ["False", "True"], 
    "values": ["false","true"]
    }, 

"_csstemplate": "#{id} {{position:absolute; left:{left}px; top:{top}px; height:{height}px; width:{width}px}}", 

"_htmltemplate": "<input type='button' id='{id}' {hidden}{disabled} style=\"{style}\" name=\"{name}\" value=\"{value}\" data-role='none'>",

"_jstemplate": "$('#{id}').jqx{buttonType}({{theme:'{theme}', width:{width}, height:{height}, roundedCorners:'{roundedCorners}', delay:{delay}, disabled:{disabled} }});",  

"__size": 10, 
"__fontweight": "bold", 
"__fontsize": 12, 
"__textalign": "center" 
}