Configuration XML
The IDE plug-in allows you to change the user interface (UI) of XMLSpy. This is done by describing each separate modification using an XML data stream. The XML configuration is passed to XMLSpy using the GetUIModifications method of the IXMLSpyPlugIn interface.
The XML file containing the UI modifications for the IDE PlugIn, must have the following structure:
<ConfigurationData>
<ImageFile>Path to image file</ImageFile>
<Modifications>
<Modification>
...
</Modification>
...
</Modifications>
</ConfigurationData>
You can define icons or toolbar buttons for new menu items that are added to the UI of XMLSpy by the plug-in. The path to the file containing the images is set using the ImageFile element. Each image must be 16x16 pixels using maximum 256 colors. The image references must be arranged from left to right in a single <ImageFile> element. The rightmost image index value is zero.
The Modifications element can have any number of Modification child elements. Each Modification element defines a specific change to the standard UI of XMLSpy. The modifications you can carry out are described in the next section below.
Structure of Modification elements
A Modification element has two child elements:
<Modification>
<Action>Type of action</Action>
<UIElement Type="Type of UI element" />
</Modification>
Valid values for the Action element are:
Add: to add the following UI element to XMLSpy
Hide: to hide the following UI element in XMLSpy
Remove: to remove the UI element from the "Commands" list box, in the customize dialog
Multiple modifications can be combined in an Action element, like this: "Add Hide"
The UIElement element defines any new or existing UI element and may be one of the the following types: toolbars, buttons, menus, or menu items. The type attribute specifies which of these types the UI element belongs to. The structure of UIElement is described in the sections below.
Common UIElement children
The ID and Name elements are defined for all types of UI element. In the case of some types, however, one of these elements is ignored. For example, Name is ignored for a separator.
<ID></ID>
<Name></Name>
If UIElement describes an existing element of the UI, the value of the ID element is predefined by XMLSpy. Normally these ID values are not known to the public. If the XML fragment describes a new part of the UI, then the ID is arbitrary and the value should be less than 1000. The Name element sets the textual value. Existing UI elements can be identified just by name; for example, menus and menu items that have sub menus. For new UI elements, the Name element sets the caption (for example, the title of a toolbar) or the text of a menu item.
Toolbars and Menus
To define a toolbar it is necessary to specify the ID and/or the name of the toolbar. An existing toolbar can be specified using only the name or ID (if the latter is known). To create a new toolbar, both values must be set. The type attribute must have a value of ToolBar.
<UIElement Type="ToolBar">
<ID>1</ID>
<Name>TestPlugIn</Name>
</UIElement>
To specify an XMLSpy menu you need two parameters:
•The ID of the menu bar which contains the menu. If no XML documents are open in the main window, the menu bar ID is 128. If one or more XML documents are open, the menu bar ID is 129.
•The menu name. Menus do not have an associated ID value. The following example defines the "Edit" menu of the menu bar which is active, when at least one XML document is open:
<UIElement Type="Menu">
<ID>129</ID>
<Name>Edit</Name>
</UIElement>
An additional element is used if you want to create a new menu. The Place element defines the position of the new menu in the menu bar:
<UIElement Type="Menu">
<ID>129</ID>
<Name>PlugIn Menu</Name>
<Place>12</Place>
</UIElement>
A value of -1 for the Place element sets the new button or menu item at the end of the menu or toolbar.
Commands
If you add a new command (through a toolbar button or a menu item), the UIElement fragment can contain any of these sub elements:
<MacroName></MacroName>
<Info></Info>
<ImageID></ImageID>
If MacroName is specified, XMLSpy searches for a macro with the same name in the scripting environment and executes it each time this command is processed. The Info element contains a description string that is displayed in the status bar when the mouse pointer is over the associated command (button or menu item). ImageID defines the index of the icon in the image file. Note that all icons are stored in one image file.
To define a toolbar button, create an UIElement with this structure:
<UIElement Type="ToolBarItem">
<!--don't reuse local IDs even the commands do the same-->
<ID>5</ID>
<Name>Open file from repository...</Name>
<!--Set Place To -1 If this is the first button To be inserted-->
<Place>-1</Place>
<ImageID>0</ImageID>
<ToolBarID>1</ToolBarID>
<!--instead of the toolbar ID the toolbar name could be used-->
<ToolBarName>TestPlugIn</ToolBarName>
</UIElement>
Additional elements to declare a toolbar button are Place, ToolBarID and ToolBarName. The ToolBarID and ToolBarName elements are used to identify the toolbar which contains the new or existing button. The textual value of ToolBarName is case-sensitive. The (UIElement) type attribute must be ToolBarItem.
To define a menu item, the elements MenuID, Place and Parent are available in addition to the standard elements used to declare a command. The content of the MenuID element can be either 128 or 129. See the section "Toolbars and Menus" above for more information.
The Parent element is used to identify the menu where the new menu entry should be inserted. As sub menu items have no unique Windows ID, we need some other way to identify the parent of the menu item. We do this by setting the content of the Parent element to be the path to the menu item. The steps in the path are indicated by a colon. The pattern would be ParentMenu:SubMenu. If the menu has no parent (because it is not a submenu), add a colon to the beginning of the name (see example below). The type attribute must be set to MenuItem.
The example below defines a menu item, where the containing menu is not a sub menu:
<UIElement Type="MenuItem">
<!--the following element is a Local command ID-->
<ID>3</ID>
<Name>Open file from repository...</Name>
<Place>-1</Place>
<MenuID>129</MenuID>
<Parent>:PlugIn Menu</Parent>
<ImageID>0</ImageID>
</UIElement>
You can add toolbar separators and menus if the value of the ID element is set to 0.