Documentation/DevGuide/GUI/Roadmap Control

OpenOffice.org Developer's Guide

Graphical User Interfaces

< Previous Section

Next Section >

• Exception Handling
• Dialogs and Controls
• Dialog Creation

• Instantiation of a Dialog
• Setting Dialog Properties
• Adding Controls to a Dialog
• Displaying Dialogs

• Dialog Handling

• Events
• Dialog Controls

• Common Properties
• Font-specific Properties
• Other Common Properties
• Property Propagation Between Model and Control
• Common Workflow to add Controls
• The Example Listings
• Label Field
• Command Button
• Image Control
• Check Box
• Radio Button
• Scroll Bar
• List Box
• Combo Box
• Progress Bar
• Horizontal/Vertical Line Control
• Group Box
• Text Field
• Text Field Extensions
• Formatted Field
• Numeric Field
• Currency Field
• Date Field
• Time Field
• Pattern Field
• Roadmap Control
• File Control
• File Picker
• Message Box

• The Toolkit Service
• Creating Menus

• Summarizing Example to Create a UNO Dialog

< Previous Page

Next Page >

The roadmap control that supports the service com.sun.star.awt.UnoControlRoadmap is a container of roadmap items supporting com.sun.star.awt.RoadmapItem. The roadmap control was designed to give an overview about all existing steps in a dialog as done in all Apache OpenOffice wizards. The roadmap items are labels with some additional functionality as described later in the text. They are due to give the user a clue about "what is going on" on a certain dialog step. Roadmap items can be programmatically accessed by their respective index using the interface XIndexContainer at the roadmap model that is described by com.sun.star.awt.UnoControlRoadmapModel.

Roadmap Item

Each roadmap item delivers the following information:

Properties of com.sun.star.awt.RoadmapItem
ID	short. The ID uniquely identifies the roadmap item and can be used to refer to the value of a dialog step.
Label	The label of a roadmap item is displayed similar to the label of a fixed text control. Each label is prefixed with an index and a ". ".
Interactive	boolean. Setting Interactive to true will automatically change the mouse pointer to a refhand and underline the label for the time the mouse pointer resides over the roadmap item. Clicking the mouse pointer will then notify the roadmap container. The property Interactive is readonly because it is adapted from the container of the roadmap item, the roadmap model. When the user clicks on the roadmap item of an interactive roadmap the ID of the triggered roadmap item automatically gets selected - similarly to the selection of a list box item. Automatically the property CurrentItemID of the roadmap model is set to the value of the property ID of the roadmap item element.
Enabled	boolean. Determines whether a roadmap item is enabled or disabled. As roadmap items usually refer to a dialog step they are disabled when the the actions taking place on that step have become unnecessary for example because of user input.

Roadmap Controlmodel

Properties of com.sun.star.awt.UnoControlRoadmapModel
BackgroundColor	long. Specifies the background color (RGB) of the control. The Default value is white.
Interactive	boolean. Determines whether the roadmap items are interactive or not. To have an interactive roadmap may demand some extra implementation work because the developer will then be responsible to check if for each roadmap item the necessary prerequisites are fulfilled to allow the user to enter the respective dialog step.
Complete	boolean. Determines whether the control container is complete or not. It might occur that the exact roadmap of an assistant is not clear from the beginning because it contains one or several branches where the input of the user impacts the content of the roadmap. If it is unclear how the roadmap is moving on after a branch the following step after the branch is visualized with "…". In this case the property Complete is previously set to false. The steps afterwards are unavailable as long as the state of this branch is uncertain.
ImageURL	string. Refers to an image that is displayed in the bottom right corner of the roadmap. The image is meant to contain a metaphor that can easily be associated with the task of the wizard or the subtask of an according step.
Text	string. Specifies the bold and underlined text displayed in the top of the control
CurrentItemID	short. Refers to the ID of the currently selected roadmap item. Initially this property is set to '-1' which is equal to 'undefined.

Roadmap

Specifies a Roadmap control. A roadmap implements the interface com.sun.star.awt.XItemEventBroadcaster, which is helpful to add an ItemListener to the roadmap, when the property Interactive of the roadmap model is set to true. The listener is then always notified about changes of the property CurrentItemID and has an opportunity to adjust the property Step of the dialog.

The following example listings are supposed to give an idea how a roadmap can be used to control the displayed steps of a dialog:

  // Globally available object variables of the roadmapmodel
  XPropertySet m_xRMPSet; 
  XSingleServiceFactory m_xSSFRoadmap;
  XIndexContainer m_xRMIndexCont;
  
  public void addRoadmap(XItemListener _xItemListener) {
  try {
      // create a unique name by means of an own implementation...
      String sRoadmapName = createUniqueName(m_xDlgModelNameContainer, "Roadmap");
      
      XPropertySet xDialogModelPropertySet = (XPropertySet) UnoRuntime.queryInterface(XPropertySet.class, m_xMSFDialogModel); 
      // Similar to the office assistants the roadmap is adjusted to the height of the dialog
      // where a certain space is left at the bottom for the buttons...
      int nDialogHeight = ((Integer) xDialogModelPropertySet.getPropertyValue("Height")).intValue();
      
      // instantiate the roadmapmodel...
      Object oRoadmapModel = m_xMSFDialogModel.createInstance("com.sun.star.awt.UnoControlRoadmapModel");
      
      // define the properties of the roadmapmodel
      XMultiPropertySet xRMMPSet = (XMultiPropertySet) UnoRuntime.queryInterface(XMultiPropertySet.class, oRoadmapModel);
      xRMMPSet.setPropertyValues( new String[] {"Complete", "Height", "Name", "PositionX", "PositionY", "Text", "Width" },
      new Object[] {Boolean.FALSE, new Integer(nDialogHeight - 26), sRoadmapName, new Integer(0), new Integer(0), "Steps", new Integer(85)});
      m_xRMPSet = (XPropertySet) UnoRuntime.queryInterface(XPropertySet.class, oRoadmapModel);
      
      // add the roadmapmodel to the dialog container..
      m_xDlgModelNameContainer.insertByName(sRoadmapName, oRoadmapModel); 
      
      // the roadmapmodel is a SingleServiceFactory to instantiate the roadmapitems...
      m_xSSFRoadmap = (XSingleServiceFactory) UnoRuntime.queryInterface(XSingleServiceFactory.class, oRoadmapModel);
      m_xRMIndexCont = (XIndexContainer) UnoRuntime.queryInterface(XIndexContainer.class, oRoadmapModel); 
      
      // add the itemlistener to the control...
      XControl xRMControl = this.m_xDlgContainer.getControl(sRoadmapName);
      XItemEventBroadcaster xRMBroadcaster = (XItemEventBroadcaster) UnoRuntime.queryInterface(XItemEventBroadcaster.class, xRMControl);
      xRMBroadcaster.addItemListener(new RoadmapItemStateChangeListener()); //_xItemListener); 
  } catch (java.lang.Exception jexception) {
      jexception.printStackTrace(System.out);
  }}
 </source>
The following code snippet inserts a roadmap item into the roadmap control model. 
 <source lang="java">
  /**
   * To fully understand the example one has to be aware that the passed "Index" parameter 
   * refers to the position of the roadmap item in the roadmapmodel container 
   * whereas the variable "_ID" directly references to a certain step of dialog.
   */
  public void insertRoadmapItem(int Index, boolean _bEnabled, String _sLabel, int _ID) {
  try {
      // a roadmap is a SingleServiceFactory that can only create roadmapitems that are the only possible
      // element types of the container
      Object oRoadmapItem = m_xSSFRoadmap.createInstance();
      XPropertySet xRMItemPSet = (XPropertySet) UnoRuntime.queryInterface(XPropertySet.class,       oRoadmapItem);
      xRMItemPSet.setPropertyValue("Label", _sLabel);
      // sometimes steps are supposed to be set disabled depending on the program logic...
      xRMItemPSet.setPropertyValue("Enabled", new Boolean(_bEnabled));
      // in this context the "ID" is meant to refer to a step of the dialog
      xRMItemPSet.setPropertyValue("ID", new Integer(_ID));
      m_xRMIndexCont.insertByIndex(Index, oRoadmapItem);
  } catch (com.sun.star.uno.Exception exception) {
      exception.printStackTrace(System.out);
  }}

The following example demonstrates the way an ItemListener could evaluate the information of the roadmap control to adjust the step of the dialog:

  public void itemStateChanged(com.sun.star.awt.ItemEvent itemEvent) {
  try {
      // get the new ID of the roadmap that is supposed to refer to the new step of the dialogmodel
      int nNewID = itemEvent.ItemId;
      XPropertySet xDialogModelPropertySet = (XPropertySet) UnoRuntime.queryInterface(XPropertySet.class, m_xMSFDialogModel); 
      int nOldStep = ((Integer) xDialogModelPropertySet.getPropertyValue("Step")).intValue();
      // in the following line "ID" and "Step" are mixed together.
      // In fact in this case they denot the same
      if (nNewID != nOldStep){
          xDialogModelPropertySet.setPropertyValue("Step", new Integer(nNewID));
      }
  } catch (com.sun.star.uno.Exception exception) {
      exception.printStackTrace(System.out);
  }}

Content on this page is licensed under the Public Documentation License (PDL).