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. Elements that begin with "_" do not appear in the Properties Windows. These are usually put at the beginning of the file.

{
"_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",

Now, we start the elements which will appear in Project Properties. "class" is for the names of any styling classifications. It is actually defined in Widgets.js.

"class": "",

The id of a control defaults to _displayname + n, where n is the number of occurrences of the control. Each of the project properties will be defined by a structure like this one. As we see more of these, we will discuss the options. This is the simplest one: the type is "str", which means the field accepts a simple string input. The desc field will appear in the description area under the Properties Window. The id property is followed by a number of other str type properties which are straightforward. The default value of the element, if any, is in the first line of the element definition.

"id": "", 
"_id": { 
    "desc": "Unique button identifier", 
    "type": "str" 
    },

<pre>   
"name": "", 
"_name": { 
    "desc": "Key in submitted form", 
    "type": "str" 
    }, 
    
"value": "Button", 
"_value": { 
    "desc": "The caption of the button", 
    "type": "str" 
    }, 
 

Here we see a couple of additional options. Type 'css' will bring up a textarea to edit the string. Use this for multiline or large string elements. We also see the "actype" option. It stands for autocomplete: this is used by the Code Window to display autocomplete options.

   
"style": "", 
"_style": { 
    "actype": "Style",
    "desc": "Styling rules for element", 
    "type": "css" 
    }, 

This introduces the 'int' type. It's as simple a 'str', but will only accept integers. The acignore option indicates there is no autocomplete for this.

"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" 
    }, 

The 'enum' type is used when there is a list of possible values for the control. "keys" are the choices which are shown in the Properties Window. "Values" are the corresponding values to be used in the actual app. The first line has the initial value, which must be one of the elements in "values". In this case, the initial value is "", the second element in "values".

"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" 
}