Section: 5.3.0 Xml based UI construction

5.3.0 Xml based UI construction

The ucar.unidata.ui.XmlUi class creates a user interface from a "skin" xml.

Note: You can test the following example skins by:
Right click on the link. Save file to your home directory and run:
java ucar.unidata.ui.XmlUi <skinfile.xml>

Note: The IDV offers a xml utility that formats an xml file in place:
java ucar.unidata.xml.XmlUtil <skinfile.xml>

The xml can take a variety of forms:

  <somecomponenttag>
     <some other component tag/>
 </somecomponenttag>

e.g.:

<?xml version="1.0" encoding="ISO-8859-1"?>
<panel>
  <button label="The Button"/>
</panel>

example1.xml

Or more complex with the skin outer tag, an inner ui and optional components and styles sections:

  <skin>
    <ui>
        Some ui xml
    </ui>
    <components>
        components
    </components>
    <styles>
        style definitions
    </styles>
 </skin>

The skin xml, either under the ui tag or under the components tag, contains a set of nested container and component tags. The panel tags have a layout attribute:

<?xml version="1.0" encoding="ISO-8859-1"?>
<panel
   cols="1"
   layout="gridbag">
  <panel
     bgcolor="red"
     layout="flow">
    <button label="Button 1"/>
    <button label="Button 2"/>
    <button label="Button 3"/>
    <panel
       bgcolor="green"
       cols="1"
       layout="gridbag">
      <label text="Label 1"/>
      <label text="Label 2"/>
      <label text="Label 3"/>
    </panel>
  </panel>
  <textinput value="text field 1"/>
  <textinput
     rows="2"
     value="text field 2"/>
  <textinput value="text field 3"/>
</panel>

example2.xml

Components

Each top-level tag under the components tag has an id attribute. One can then refer to this component in the ui tag with a:

<component idref="the component id">

This allows one to separate overall layout (defined in the ui) from that of actual components. e.g.:

<?xml version="1.0" encoding="ISO-8859-1"?>
<skin>
  <ui>
    <panel layout="border">
      <component idref="top" place="North"/>
      <component idref="middle" place="Center"/>
      <component idref="bottom" place="South"/>
      <component idref="left" place="West"/>
      <component idref="right" place="East"/>
    </panel>
  </ui>
  <components>
      <label
         id="top"
         text="Top Label"/>
      <label
         id="middle"
         text="Middle Label"/>
      <label
         id="bottom"
         text="Bottom Label"/>
      <label
         id="left"
         text="Left Label"/>
      <label
         id="right"
         text="Right Label"/>
  </components>
</skin>

component.xml

Note: any attributes defined in the component tag in the ui section will overwrite the attributes in the actual tag in the components section.

Supported Tags

component
panel
tabbedpane
label
menubar
button  
checkbox
textinput
menu
image

All tags can have these attributes:

bgcolor, fgcolor - background and foreground color. The value can be a color name, e.g.: red, blue, orange, white, etc. or a single numeric value or a comma separated list of rgb values: e.g.: "250,50,10"

fontsize - specify font size used.

fontface - specify font face used.

Tag: component

The component tag can either have an idref, which points to a component defined in the components section:

<component idref="some id in the components section"
           (and any attributes)/>

Or it can have an id which should be held within the idToComponent Hashtable which the XmlUi is created with. This allows the use of any application specific Component-s

<component id="some id in idToComponent Hasthable"
           (and any attributes)/>

Tag: panel

<panel layout="border|card|grid|gridbag|inset"
       hspace="int, hor. spacing "
       vspace="int, vert. spacing "
       rows="int"
       cols="int" 	      	      
       x="int"
       y="int"
       colwidths="int,int,...,int"
       rowheights="int,int,...,int">

The panel tags can have any number of children tags. The layout of the children is defined with a "layout" attribute which can be one of: border, grid, gridbag, inset.

layout="border" - java.awt.BorderLayout. The children components of this tag should have a "place" attribute which is one of the java.awt.BorderLayout places: North, South, East, West, Center. e.g.:

<panel layout="border" >
   <label id="top" place="North" />
   <label id="bottom" place="South"/>
   <label id="left" place="West"/>
   ...
</panel>

layout="grid" This is the java.awt.GridLayout. You can specify a number of rows and/or columns. For example, the following gives 2 rows and 3 columns. The spacing used is defined with: hspace=".." vspace="..." attributes.

<?xml version="1.0" encoding="ISO-8859-1"?>
<panel
   cols="3"
   layout="grid"
   rows="2"
   hspace="10"
   vspace="20">
  <label text="label1"/>
  <panel bgcolor="red"/>
  <panel bgcolor="green"/>
  <panel bgcolor="blue"/>
  <label text="a much wider label"/>
  <panel bgcolor="black"/>
</panel>

grid.xml This would give single row with multiple columns:

<panel layout="grid" rows="1">

layout="gridbag" This uses the java.awt.GridBagLayout in a column oriented way. The spacing used is defined with: hspace=".." vspace="..." attributes. You can specify the number of columns in the grid. You can also specify the column and row weights (As a comma separated string of numeric values) that determine stretchiness. e.g.:

<?xml version="1.0" encoding="ISO-8859-1"?>
<panel
   bgcolor="white"
   layout="inset"
   space="20">
  <panel
     cols="3"
     colwidths="0,1,0"
     layout="gridbag"
     rowheights="1,0">
    <label text="Row 1 height is stretchy"/>
    <panel bgcolor="red"/>
    <panel bgcolor="green"/>
    <panel bgcolor="blue"/>
    <label text="Middle column width is stretchy"/>
    <panel bgcolor="black"/>
  </panel>
</panel>

gridbag.xml

layout="graphpaper" This uses a graph paper layout that allows for exact component placement.

<?xml version="1.0" encoding="ISO-8859-1"?>
<panel layout="graphpaper" rows="4" cols="5">
  <label
     text="x:0 y:0 cols:3 rows:1"
     cols="3"
     x="0"
     y="0" 
     bgcolor="green"
     align="left"/>
  <label
     text="x:0 y:2 cols:2 rows:1"
     x="0"
     y="1"
     cols="2"
     bgcolor="red"
     align="left"/>
  <label
     text="x:2 y:1 cols:1 rows:1"
     x="2"
     y="1"
     bgcolor="cyan"
     align="left"/>
  <label
     text="x:3 y:0 cols:1 rows:3"
     x="3"
     y="0"
     cols="1"
     rows="3"
     bgcolor="gray"
     align="center"/>
</panel>

graphpaper.xml

layout="inset" - This is a simple way to wrap a single child component. The spacing used is defined with: hspace=".." vspace="..." attributes.

Tag: styles

Use the styles section to define classes of components:

<?xml version="1.0" encoding="ISO-8859-1"?>
<skin>
  <ui>
    <panel
       layout="inset"
       space="10">
      <panel layout="border">
        <panel
           layout="flow"
           place="North">
          <button
             class="button1"
             label="Button 1"/>
          <button
             class="button1"
             label="Button 2"/>
          <button
             class="button1"
             label="Button 3"/>
        </panel>
        <label
           class="labelstyle"
           id="messagelabel"
           place="Center"
           text="label"/>

<!-- You can also have a parent container with "i:..." attributes.
Children inherit those values  -->
        <panel
           i:fgcolor="blue"
           layout="flow"
           place="South">
          <button label="Button 1"/>
          <button label="Button 2"/>
          <button label="Button 3"/>
        </panel>
      </panel>
    </panel>
  </ui>
  <styles>
    <style
       border="button"
       class="button1"
       fgcolor="red"
       mouse_enter="ui.setBorder(this,etched);"
       mouse_exit="ui.setBorder(this,button);"
       space="2"/>
    <style
       class="labelstyle"
       fgcolor="green"
       fontsize="24"
       space="2"/>
  </styles>
</skin>

styles.xml

Tag: tabbedpane

<?xml version="1.0" encoding="ISO-8859-1"?>
<tabbedpane>
  <label
     fontsize="36"
     text="Tab 1 contents"
     title="Tab 1"/>
  <label
     fontsize="36"
     text="Tab 2 contents"
     title="Tab 2"/>
  <label
     fontsize="36"
     text="Tab 3 contents"
     title="Tab 3"/>
</tabbedpane>

tabbedpane.xml

Tag: menubar

<?xml version="1.0" encoding="ISO-8859-1"?>
<menubar label="Commands">
  <menu label="Example Menu">
    <menuitem label="Some menu item"/>
    <menuitem label="Some other menu item"/>
    <separator/>
    <menuitem label="And the last menu item"/>
    <separator/>
    <menu label="Sub menu">
      <menuitem label="Item"/>
    </menu>
  </menu>
  <menu label="Another menu">
    <menuitem
       action="foo"
       label="Another menu"/>
  </menu>
</menubar>

menubar.xml

Tag: label

<?xml version="1.0" encoding="ISO-8859-1"?>
<panel
   bgcolor="green"
   layout="border">
  <label
     fgcolor="red"
     fontsize="24"
     fontstyle="italic"
     text="Hello there"/>
</panel>

label.xml

Tag: button

<button  action="some action"  label="label to use"/>

Creates a java.awt.Button. The action (like all actions) can be a semicolon (";") separted list of actions.

Tag: checkbox

<checkbox  action="some action"  label="label to use"/>

Just like the button tag. However, we convert the itemStateChanged event into an action event and pass it on to the actionListener.

Tag: textinput

<textinput rows="optional number of rows"
           cols="optional number of columns"
	   value="initial text value" 
           action="some action"/>

Provides either a TextField or a TextArea depending on the number of rows (the default == 1, which gives a TextField). For TextField-s we add an actionListener if the action attribute is defined.

Tag: menupopup

<menu label="Some menu label" image="some image url">
     <menuitem label="some menu item"  action="some action" />
     <menuitem label="some other menu item"  action="some other action" />     
     <separator/>
     <menu label="some sub menu">
         <menuitem label="..."  action="..." />
         <menuitem label="..."  action="..." />
     </menu>
</menu>

If image attribute is defined creates an image button, else creates a text button. When the button is clicked a menu of menuitems, separators and sub-menus is popped up.

Tag: image

<image url="some url"
       width="Optional width of image"
       height="Optional height of image"       
       action="If defined the image acts like a button"
       border="Optional true|false">

This provides a simple image label or an image button (if action is defined). If it is a button and if border==true then the image is drawn with a border (that changes when clicked).

Unidata IDV Workshop for version 6.3 > Java Developer Topics > IDV User Interfaces