Creating General Interface Builder Properties Files

Page restrictions apply
Attachments:2
Added by Barbara Weinstein, last edited by Jesse Costello-Good on Feb 12, 2010 (view change)

In this step you'll create Container and Widget properties files, to integrate the new classes Container and Widget with General Interface Builder. These properties files can then be used by the Properties, Events, and XSL Parameters palettes when editing instances of the new classes.

After custom properties are created and loaded by the General Interface system, they appear in the Properties Editor palette when the component is selected. Then you can set properties for your custom components in General Interface Builder, just as you do with General Interface components.

The properties file adheres to the Common Data Format (CDF). Properties are organized by categories (group) and each category has individual fields (record) that correspond to rows in the Properties Editor palette. For more information on CDF, see Common Data Format (CDF) in the General Interface Developer Guide.

For examples of General Interface Builder files that define properties, events, and XSL parameters, see these directories in the GI_HOME directory:

GI_Builder\plugins\jsx3.ide.palette.events\templates
GI_Builder\plugins\jsx3.ide.palette.properties\templates
GI_Builder\plugins\jsx3.ide.palette.xslparams\templates

Note that you can also create a file, such as master.xml, that contains common properties and then include that file in a properties file. For example: <record group="object" include="master.xml"/>

For examples of how this is done, see General Interface Builder properties files in GI_Builder\plugins\jsx3.ide.palette.properties\templates.

For definitions of attributes in the properties file, see Attribute Definitions for Prototype Properties Files. The properties file, which adheres to CDF format, contains records that correspond to fields in the Properties Editor palette.

To create the properties file for Container:

Choose File > New > XML Document and copy and paste the code shown below this procedure into the empty document.
Save the properties file:
1. Choose File > Save and navigate to the root of the myAddin folder.
2. Click the New Folder icon and create a folder named properties.
Open the properties folder.
Type Container.xml in the file name field and click Save.

<?xml version="1.0" encoding="UTF-8"?>

<data jsxid="jsxroot">
  <record group="1" jsxid="object" jsxtext="Object">
    <record docnoprop="true" eval="0" getter="getClass" jsxid="jsxinstanceof"
        jsxtext="Object Type" jsxtip="The JSX foundation class that this object
        is an instance of." uneditable="1"/>

    <record docgetter="getId" docnoprop="true" eval="0" jsxid="_jsxid" jsxtext="ID"
        jsxtip="The unique, system-assigned ID for this object." uneditable="1"/>

    <record disallow="\[\\u0022\u003C\u003E\u0027\u0026\\]" docgetter="getName"
        docsetter="setName" eval="0"
        jsxexecute="objJSX.setName(vntValue);jsx3.ide.onDomChangeSleep();"
        jsxid="jsxname" jsxmask="jsxtext" jsxtext="Name" jsxtip="Sets the name
        assigned by the developer to identify this object."/>
  </record>

  <record group="1" jsxid="position" jsxtext="Positioning">
    <record docdefault="Relative(&lt;code&gt;jsx3.gui.Block.RELATIVE&lt;/code&gt;\)"
        docgetter="getRelativePosition" docsetter="setRelativePosition" eval="1"         jsxexecute="objJSX.setRelativePosition(vntValue,true);"         jsxid="jsxrelativeposition" jsxmask="jsxselect" jsxtext="Relative XY"
        jsxtip="Sets whether to place this object relatively or absolutely with
        respect to its container.">
      <enum jsxid="jsx3.gui.Block.ABSOLUTE" jsxtext="Absolute"/>
      <enum jsxid="jsx3.gui.Block.RELATIVE" jsxtext="Relative"/>
    </record>

    <record disallow="[^cm^pt^\.^%^0-9^-]"
        docdefault="If absolutely positioned,the default is 0. If relatively         positioned, the default is empty."
        docgetter="getLeft" docsetter="setLeft" eval="0"
        jsxexecute="objJSX.setLeft(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,        true);"
        jsxid="jsxleft" jsxmask="jsxtext"
        jsxtext="Left" jsxtip="Sets the position of this object from left edge
        of container. If this object is absolutely positioned, this value is
        applied as an implied pixel or a percentage. For example,
        &lt;code&gt;10&lt;/code&gt; or &lt;code&gt;15%&lt;/code&gt;."/>

    <record disallow="[^cm^pt^\.^%^0-9^-]"
        docdefault="If absolutely positioned, the default is 0. If relatively         positioned, the default is empty."
        docgetter="getTop" docsetter="setTop" eval="0"
        jsxexecute="objJSX.setTop(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);"
        jsxid="jsxtop" jsxmask="jsxtext" jsxtext="Top"
        jsxtip="Sets the position of this object from top edge of container. If
        this object is absolutely positioned, this value is applied as an implied
        pixel or a percentage. For example, &lt;code&gt;10&lt;/code&gt; or
        &lt;code&gt;15%&lt;/code&gt;."/>

    <record disallow="[^cm^pt^\.^%^0-9^-]" docdefault="Empty"
        docgetter="getWidth" docsetter="setWidth" eval="0"
        jsxexecute="objJSX.setWidth(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);"
        jsxid="jsxwidth" jsxmask="jsxtext" jsxtext="Width"
        jsxtip="Sets the width of the control as implied pixels or a percentage.
        For example, &lt;code&gt;100&lt;/code&gt; or         &lt;code&gt;25%&lt;/code&gt;."/>

    <record disallow="[^cm^pt^\.^%^0-9^-]" docdefault="Empty"
        docgetter="getHeight" docsetter="setHeight" eval="0"
        jsxexecute="objJSX.setHeight(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);"
        jsxid="jsxheight" jsxmask="jsxtext" jsxtext="Height"
        jsxtip="Sets the height of the control in pixels or percentage. For example,
        &lt;code&gt;100&lt;/code&gt; or &lt;code&gt;25%&lt;/code&gt;."/>

    <record disallow="[^0-9^-]" docdefault="&lt;code&gt;1&lt;/code&gt;"
        docgetter="getZIndex" docsetter="setZIndex" eval="1"
        jsxid="jsxzindex" jsxmask="jsxtext" jsxtext="Z-Index"
        jsxtip="If this object is absolutely positioned, sets the CSS z-index.
        The z-index sets the stack order of an element."/>
  </record>

  <record group="1" jsxid="myexamplefield" jsxtext="Category Label for Container">
    <record jsxtip="This is a container.  It can contain other containers as
        well as widgets. Click on the button to activate the custom editor mask."
        docgetter="getBackgroundColor" docsetter="setBackgroundColor" eval="0"
        jsxexecute="objJSX.setBackgroundColor(vntValue,true);"
        jsxid="jsxbgcolor" jsxmask="jsxtext"
       jsxtext="Field Label (BGColor)"/>
  </record>
</data>

When the Container properties file is loaded in the Properties Editor palette in General Interface Builder, it looks like this:

To create the properties file for Widget:

Choose File > New > XML Document and copy and paste the code that follows this procedure into the empty document.
Save the properties file as Widget.xml in the properties folder.

<?xml version="1.0" encoding="UTF-8"?>

<data jsxid="jsxroot">
  <record group="1" jsxid="object" jsxtext="Object">
    <record docnoprop="true" eval="0" getter="getClass"
        jsxid="jsxinstanceof" jsxtext="Object Type"
        jsxtip="The JSX foundation class that this object is an instance of."
        uneditable="1"/>

    <record docgetter="getId"
        docnoprop="true" eval="0"
        jsxid="_jsxid" jsxtext="ID"
        jsxtip="The unique, system-assigned ID for this object." uneditable="1"/>

    <record disallow="\[\\u0022\u003C\u003E\u0027\u0026\\]"
        docgetter="getName" docsetter="setName" eval="0"
        jsxexecute="objJSX.setName(vntValue);jsx3.ide.onDomChangeSleep();"
        jsxid="jsxname" jsxmask="jsxtext" jsxtext="Name"
        jsxtip="Sets the name assigned by the developer to identify this object."/>
  </record>

  <record group="1" jsxid="position" jsxtext="Positioning">
    <record docdefault="Relative(&lt;code&gt;jsx3.gui.Block.RELATIVE&lt;/code&gt;\)"
        docgetter="getRelativePosition" docsetter="setRelativePosition" eval="1"
        jsxexecute="objJSX.setRelativePosition(vntValue,true);"
        jsxid="jsxrelativeposition" jsxmask="jsxselect" jsxtext="Relative XY"
        jsxtip="Sets whether to place this object relatively or absolutely with
        respect to its container.">
      <enum jsxid="jsx3.gui.Block.ABSOLUTE" jsxtext="Absolute"/>
      <enum jsxid="jsx3.gui.Block.RELATIVE" jsxtext="Relative"/>
    </record>

    <record disallow="[^cm^pt^\.^%^0-9^-]"
        docdefault="If absolutely positioned, the default is 0. If relatively
        positioned, the default is empty."
        docgetter="getLeft" docsetter="setLeft" eval="0"
        jsxexecute="objJSX.setLeft(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);"
        jsxid="jsxleft" jsxmask="jsxtext" jsxtext="Left"
        jsxtip="Sets the position of this object from left edge of container.
        If this object is absolutely positioned, this value is applied as an
        implied pixel or a percentage. For example, &lt;code&gt;10&lt;/code&gt;
        or &lt;code&gt;15%&lt;/code&gt;."/>

    <record disallow="[^cm^pt^\.^%^0-9^-]"
        docdefault="If absolutely positioned, the default is 0. If relatively
        positioned, the default is empty."
        docgetter="getTop" docsetter="setTop" eval="0"
        jsxexecute="objJSX.setTop(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);"
        jsxid="jsxtop" jsxmask="jsxtext"
        jsxtext="Top" jsxtip="Sets the position of this object from top edge
        of container. If this object is absolutely positioned, this value is
        applied as an implied pixel or a percentage. For example,
        &lt;code&gt;10&lt;/code&gt; or &lt;code&gt;15%&lt;/code&gt;."/>

    <record disallow="[^cm^pt^\.^%^0-9^-]" docdefault="Empty"
        docgetter="getWidth" docsetter="setWidth" eval="0"
        jsxexecute="objJSX.setWidth(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);"
        jsxid="jsxwidth" jsxmask="jsxtext" jsxtext="Width"
        jsxtip="Sets the width of the control as implied pixels or a percentage.
        For example, &lt;code&gt;100&lt;/code&gt; or
        &lt;code&gt;25%&lt;/code&gt;."/>

    <record disallow="[^cm^pt^\.^%^0-9^-]" docdefault="Empty"
        docgetter="getHeight" docsetter="setHeight" eval="0"
        jsxexecute="objJSX.setHeight(jsx3.util.numIsNaN(vntValue)?vntValue:+vntValue,true);"
        jsxid="jsxheight" jsxmask="jsxtext" jsxtext="Height"
        jsxtip="Sets the height of the control in pixels or percentage.
        For example, &lt;code&gt;100&lt;/code&gt; or
        &lt;code&gt;25%&lt;/code&gt;."/>

    <record disallow="[^0-9^-]" docdefault="&lt;code&gt;1&lt;/code&gt;"
        docgetter="getZIndex" docsetter="setZIndex" eval="1"
        jsxid="jsxzindex" jsxmask="jsxtext" jsxtext="Z-Index"
        jsxtip="If this object is absolutely positioned, sets the CSS z-index.
        The z-index sets the stack order of an element."/>
  </record>

  <record group="1" jsxid="myexamplefield" jsxtext="Category Label for Widget">
    <record jsxtip="This is a widget. It can only be contained by a container."
        docgetter="getText" docsetter="setText" eval="0"
        jsxexecute="objJSX.setText(vntValue);objJSX.repaint();"
        jsxid="jsxtext" jsxmask="jsxtext" jsxtext="Field Label (Text)"/>
  </record>

</data>

When the Widget properties file is loaded in the Properties Editor palette in General Interface Builder, it looks like this:

Now that you've created a properties file for each prototype, you'll create a catalog file that describes the location of these files to the General Interface system. You'll do this in Creating and Loading the Catalog File.

Attribute	Description
`disallow`	Restricts user input using a regular expression.
`docdefault`	Documented default value for the property, which appears in the spyglass. If "Empty" there isn't a default value.
`docgetter`	Documented getter for the property, which appears in the spyglass.
`docsetter`	Documented setter for the property, which appears in the spyglass.
`docnoprop`	Set to `true` if some of the documentation shouldn't appear in the spyglass. In this example, only the tip and the getter appear in the spyglass: `docgetter="getId" docnoprop="true"`
`eval`	Determines if the user input should be evaluated as a number using a JavaScript eval before committing. If set to 1, user input is evaluated. If set to 0, user input is not evaluated as a number and is treated as a String. For example, the Positioning Relative XY property has two choices, each of which evaluates to a number, because `eval="1"`. `jsx3.gui.Block.ABSOLUTE evaluates to 0` `jsx3.gui.Block.RELATIVE evaluates to 1`
`group`	Correspond to categories in the Properties Editor palette. In this example, there are three groups---Object, Positioning, and Category Label.
`jsxexecute`	JavaScript code to execute that updates the object after the user changes the value. This code has access to the contextual variables, `objJSX` (the reference to the JSX Object being edited) and `vntValue` (the value just entered by the user).
`jsxid`	Required system attribute that uniquely identifies a CDF record, acts as a key, and must be a unique value.
`jsxmask`	Name of a pre-built set of masks. For example, use `jsxtext` for a text box and `jsxselect` for a drop-down list of items. For `jsxselect` masks, use the `enum` element to specify the items in the list. For example, the Positioning property has these items: <enum jsxid="jsx3.gui.Block.ABSOLUTE" jsxtext="Absolute"/> <enum jsxid="jsx3.gui.Block.RELATIVE" jsxtext="Relative"/>
`jsxtext`	System attribute that defines the visible text (label) for the record in the Properties Editor palette.
jsxtip	Description that displays in the spyglass when you hover over the property. Use HTML markup to format the description.

For more information about CDF, see the General Interface Developer Guide.

Creating Prototypes

Chapter 6 Tutorial on Creating a Custom Add-in

Creating and Loading the Catalog File

Expand all Collapse all

Creating General Interface Builder Properties Files

To create the properties file for Widget:

Contents

Labels