Toolbars (XSISDK)

Toolbars are a common way to expose functionality with a nice centralized user interface. Generally toolbars are used to expose a feature as a series of "Action" buttons. To save space multiple commands can be nested under a single menu button (see the Syflex toolbar for an example).

Alternatives to a toolbar are a custom menu, or "control-panel" style custom property.

Table of contents

Toolbar = Shelf = View

Toolbars are now stored in .xsitb files. If you look at this file you will see that a toolbar is really just a shelf with only one tab. So when dealing with toolbars you can also tap into the functionality available in an XSI shelf.

Toolbars (and shelves) are now considered a type of "View". There is an entire API for creating, enumerating and communicating with Views, so this same API can be used to manipulate toolbars.

Example:

var oShelf = Application.Desktop.ActiveLayout.CreateView ("MyToolbar", 
"MyToolbar");
oShelf.Move(120, 33);
oShelf.Resize(333, 130);


XML Definition File

Toolbars are now based on an XML file. The file contains some GUIDs and other scary content, but in fact can easily be modified or even generated.

The entry for a custom command looks like this.

<item type="script" label="Edit Helper Bones" name="vstEditHelperBones" cmdid="{D44614CB-A114-8590-283D-9E6C49CB3EB3}"></item>

You can remove the GUID and XSI will find the correct command based on its name.

<item type="script" label="Edit Helper Bones" name="vstEditHelperBones" ></item>

Don't attempt to change the GUID value or copy the same GUID to other places in the .xsitb file!

As shown above the text label can be set independently of the command name. Although the "type" is script, this works for any Command, including C++ API based commands.

Embedded Scripts

New with v5.0, it will be possible to embed some script code directly into a toolbar button. The XML syntax will look like this:

<item type="scriptbutton" label="4" userwidth="31" userheight="26" 
                    scriptengine="VBScript" tooltip="Four views - Default">
   <scripttext><![CDATA['
       set vw = desktop.activelayout.views("vm")
       vw.setattributevalue "suspenddrawing","true"
       vw.setattributevalue "activecamera:a","top"
       vw.setattributevalue "activecamera:b","camera"
       vw.setattributevalue "activecamera:c","Front"
       vw.setattributevalue "activecamera:d","right"
       vw.setattributevalue "layout","default"
       vw.setattributevalue "suspenddrawing","false"]]>
  </scripttext>
</item>

This is a fast way to attach some straightfoward scripting code to a button.

Bitmaps for buttons

Starting with XSI v5.0 you can specify bitmaps rather than text for your script buttons. To do this you will need to save the image as a .bmp file inside the "bitmaps" directory inside the "Application\toolbars" location.

For example:

\\myserver\myworkgroup\Application\toolbars\mytoolbar.xsitb
\\myserver\myworkgroup\Application\toolbars\bitmaps\mybitmap.bmp

Then you can use the customize button dialog box or modify the XML file directly to specify a bitmap your your command button:

<item type="script" label="ignored" userwidth="80" bitmap="mybitmap" name="MYCOMMANDNAME" cmdid="{D44614CB-A114-8590-283D-9E6C49CB3EB3}"></item>

CreateToolbar Command

You can build a toolbar via the CreateToolbar, CreateToolbarButton and CreateToolbarControl commands. However these build an "old-style" toolbar which is a binary file that cannot be manipulated with the View API. So in most cases it would be better to create a toolbar just by generating the underlying XML file with a script.


Conflicting Toolbars

If you copy a toolbar file you may find that it does not appear anymore in XSI. Or you may find that the original toolbar no longer appears.

This is because both files initially have the same name and clsid GUID.

For example:

<shelf_view name="NewToolbar" clsid="{165713C8-DAB2-4D5E-8B41-178AA7ABBB67}">

XSI uses loads toolbars according to a specific order of priority, so that a duplicate toolbar in the user directory takes priority of workgroup toolbars and factory toolbars.

If you really want two separate toolbars then you should change the clsid. Normally you would also want to change the name as well!

The plug-in manager shows all .xsitb files, including conflicting toolbars. The only way to determine if a toolbar is actually loaded or not is to hover your mouse over it - if it is not loaded (because of a conflict or parsing error) it will have a different tooltip.

Image:ToolbarNotLoaded.JPG


Reading/Writing Toolbar files with Scripting

Because the files are written in XML they can be manipulated via scripting. It isn't even necessary to run the script from within the context of XSI because XML APIs are freely available.

Too learn more about writing toolbar files you can look at the ToolbarWriter class inside ToolbarWizard.js and CreateXMLDoc class inside SDKWizards.js. (Available starting with XSI 5.0)

Python

Python includes an XML parser which can read any XML file including XSI toolbars. This is a simple example that lists the commands it finds.

#Python
from xml.dom import minidom

def ReadToolbarFile( in_file ):
    toolbardoc = None
    try:
        toolbardoc = minidom.parse( in_file )        
    except Exception, detail:
        print "Error parsing file: ", detail

    return toolbardoc

def PrintCommandsInToolbar( in_xmldoc ) :
    print "Toolbar References the Following Commands:"

    items = in_xmldoc.getElementsByTagName( "item" )
    for item in items:
        type = item.getAttribute( "type" )
        #Buttons that execute Commands have type "script"
        #(even if they call a internal or C++ API command)
        if type == "script" :
            print item.getAttribute( "name" )

#Replace this path with a toolbar you wish to read
strToolbar = "c:\\Softimage\\XSI_5.0\\XSISDK\\examples\\workgroup\\Addons\\PPGDemos\\Application\\toolbars\\PPGDemos.xsitb";
oToolbar = ReadToolbarFile( strToolbar )
PrintCommandsInToolbar( oToolbar )


This page was last modified 21:00, 3 Oct 2006.
This page has been accessed 15202 times.

© Copyright 2009 Autodesk Inc. All Rights Reserved. Privacy Policy | Legal Notices and Trademarks | Report Piracy