Toolbar Layout

From K-3D

Overview

You can customize the K-3D Toolbar by modifying the contents of the share/ngui/toolbar_layout.k3d file, which contains an XML representation of the Toolbar:

<k3dml>
  <application>
    <user_interface>
      <toolbars>
        <toolbar name="create" label="Create" description="Primitive Geometry">
          <node name="PolyCube"/>
          <node name="PolyGrid"/>
          <!-- ... -->
        </toolbar>
      </toolbars>
    </user_interface>
  </application>
</k3dml>

Toolbars

Within the layout file is a single <toolbars> tag, which contains zero-to-many <toolbar> tags. Each <toolbar> tag represents a separate tab in the user-configurable portion of the Toolbar. You may add as many <toolbar> tags to the layout as you like:

<toolbars>
  <toolbar name="create" label="Create" description="Primitive Geometry">
    <!-- ... -->
  </toolbar>
  <toolbar name="foo" label="Foo" description="My Foo Stuff">
    <!-- ... -->
  </toolbar>
  <toolbar name="bar" label="Bar" description="My Bar Stuff">
    <!-- ... -->
  </toolbar></toolbars>
</toolbars>

Note: the "name" attribute is used for tutorial recording and playback, and must be unique. The "label" attribute controls the text that will be seen on the notebook tab, and should be short, but human-friendly. The "description" attribute is currently unused, but may be used for tooltips, status bar tips, etc. in the future.

Each <toolbar> tag will contain a collection of <node>, <script>, and <separator> tags that make up the contents of the toolbar tab:

Nodes

The <node> tag places a button on the toolbar that creates a K-3D Node when clicked:

<node name="PolyCube"/>
<node name="PolyGrid"/>
<!-- ... -->

The only attribute you have to specify for the <node> tag is "name", which is the name of the plugin type - this is the same name that shows-up in the Create menu. No other information is necessary, the button icon, tooltip, etc. are all populated based on the plugin type.

Scripts

The <script> tag places a button on the toolbar that runs a script when clicked. Scripts may be located in an external file referenced by relative or absolute paths, or may be embedded in the layout file itself.

Note that in the following examples the "name", "label", and "description" attributes within the <script> tag have the same meanings as within the <toolbar> tag.

Relative Paths

Referencing a script by relative path is required for portability, if the layout file is to be shared with other users or other operating systems:

<script name="foo" label="Foo" description="Sample Relative Script" reference="relative" relative_path="scripts/foo.py">
  <root>$K3D_SHARE_PATH</root>
</script>

In this case the "reference" attribute designates that this script will be referenced via a relative path, specified by the "relative_path" attribute. By default, relative paths are relative to the share/ngui directory. In this example, however, the optional <root>$K3D_SHARE_PATH</root> tag indicates that the path is relative to the K-3D share directory.

Absolute Paths

Referencing a script by absolute path is easier, but less portable:

<script name="bar" label="Bar" description="Sample Absolute Script" reference="absolute" absolute_path="/home/tshead/scripts/bar.py"/>

In this case the "reference" attribute designates that this script will be referenced via an absolute path, specified in the "absolute_path" attribute.

Inline Scripts

Embedding a script within the layout file eliminates portability issues, but clutters the contents of the file:

<script name="baz" label="Baz" description="Sample Inline Script" reference="inline" filename="baz.py" encoding="text/plain">#python
import k3d
k3d.ui.message("Howdy, World!");
</script>

In this case the "reference" attribute designates that this script will be embedded (inlined) into the file. The "filename" attribute is currently unused, but may be used in the future for error reporting. The "encoding" attribute must be set to "text/plain".

Note that the contents of the script begin immediately following the <script> tag ... this is important, as K-3D requires the "magic tag" (#python, in this case) to be located at the immediate start of the script for script language identification. Any whitespace in this position will interfere with that mechanism.

Separators

The <separator> tag provides a visual separation between buttons on the toolbar. Use it to visually group related buttons within a toolbar tab:

<node name="GroupANode1"/>
<node name="GroupANode2"/>
<separator/>
<node name="GroupBNode1"/>
<node name="GroupBNode2"/>