12.3. Describing User Interface in XML

The XML file used by a part or a mainwindow provides only the layout of the actions in the user interface. The actions themselves are still implemented in the code, with slots, as usual.

More precisely, the XML file describes the layout of the menus and submenus in the menubar (only one menubar is always present) and the menu items within those menus, as well as the toolbars and the toolbar buttons. The menubar, menus, and toolbars are containers; menu items and toolbar buttons are the actions.

A sample XML file for a mainwindow looks like the one shown in Listing 12.1.

   1 
   2 <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
   3 <kpartgui name="Konqueror" version="1">
   4   <MenuBar>
   5    <Menu name="file"><Text>&amp;File</Text>
   6     <Action name="find"/>
   7     <Separator/>
   8     <Action name="print"/>
   9     <Separator/>
  10     <Action name="close"/>
  11    </Menu>
  12    <Menu name="edit"><Text>&amp;Edit</Text>
  13     <Action name="cut"/>
  14     <Action name="copy"/>
  15     <Action name="paste"/>
  16     <Action name="trash"/>
  17     <Action name="del"/>
  18     <Separator/>
  19     <Merge/>
  20     <Separator/>
  21    </Menu>
  22    <Merge/>
  23   </MenuBar>
  24   <ToolBar fullWidth="true" name="mainToolBar"><Text>Main</Text>
  25    <Action name="cut"/>
  26    <Action name="copy"/>
  27    <Action name="paste"/>
  28    <Action name="print"/>
  29    <Separator/>
  30    <Merge/>
  31    <Separator/>
  32    <Action name="animated_logo"/>
  33   </ToolBar>
  34   <ToolBar name="locationToolBar"><Text>Location</Text>
  35    <Action name="toolbar_url_combo"/>
  36   </ToolBar>
  37 </kpartgui>
  38 				
  39 				
  40 			

The DOCTYPE tag contains the name of the main element, which should be set to kpartgui. The top-level elements are MenuBar and ToolBar, as expected. In the MenuBar, the menus are described. Note that they have a name, used for merging later on, and a text, which is displayed in the user interface, possibly translated. Because this is XML, & has to be encoded as &. Inside a Menu tag, the actions, some separators, and possibly submenus are laid out. The action names are very important because they are used to match the actions created in the code.

The toolbars are then described. Note that the main toolbar has to be called mainToolBar because its settings can be different. KToolBar takes care of adding text under icons for this particular toolbar, if the user wants them. Actions are laid out in the toolbars the usual way. The text for a toolbar is used where the name of the toolbar is to be displayed to the user, possibly translated, such as the toolbar editor.

Another important tag is the Merge tag. This tag tells the framework where the actions of the active part—and the plug-ins—should be merged in a given container. As you can see, this XML file inserts the part's actions before a separator in the Edit menu, whereas it doesn't specify a position for items in the File menu. This means that if the part defines actions for the File menu, they will be appended to the File menu of the mainwindow.

The merging happens when a part simply uses the same menu name or toolbar name as the mainwindow.

If a Merge tag is specified as a child of the MenuBar tag, the merging happens at that position; otherwise, it takes place on the right of the existing menus. The toolbar allows merging of the part's actions as well, based on the same principle.

The Merge tag can also appear in a part's XML. It will be used for merging plug-ins or for more advanced uses; the merging engine can merge any number of "inputs" and it is possible to define specific inputs, such as the one Konqueror defines for its View menu.

Another advanced use of the Merge tag is to set a name attribute for it. For instance, if another XML file wants to embed a part and any other parts or plug-ins at different positions in a given menu, it can use two merge tags:

   1 
   2 <Merge name="MyPart"/>
   3 .
   4 .
   5 .
   6 <Merge />
   7 

Using the name attribute for the Merge tag allows you to control at which position each XML fragment is merged, but it is usually unnecessary.