Setting Dialog Properties

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 >

When the dialog has been instantiated as described in the coding example, the dialog is ready to be configured.

The dialog model supports the service com.sun.star.awt.UnoControlDialogModel that includes the service com.sun.star.awt.UnoControlModel, and this includes com.sun.star.awt.UnoControlDialogElement. This service specifies the following properties:

Properties of com.sun.star.awt.UnoControlDialogElement
Height	long. Attributes denoting the position and size of controls are also available at the control, but these properties should be set at the model because they use the Map AppFont unit. Map AppFont units are device and resolution independent. One Map AppFont unit is equal to one eighth of the average character (Systemfont) height and one quarter of the average character width. The dialog editor also uses Map AppFont units, and sets their values automatically.
PositionX
PositionY
Width
Step	long. The Step property is described in detail in the next section.
Name	string. The Name property is required, because all dialogs and controls are referenced by their name. In the dialog editor this name is initially created from the object name and a number that makes the name unique, for example, "TextField1".
TabIndex	short. The TabIndex property determines the tabulator index of the control within the tabulator order of all controls of the dialog. The tabulator order denotes the order in which the controls are focused in the dialog when you press the Tab key. In a dialog that contains more than one control, the focus moves to the next control in the tabulator order when you press the Tab key. The default tab order is derived from the insertion order of the controls in the dialog. The index of the first element has the value 0. The TabIndex must not be directly sequential to the predecessor control. If the program logic requires you to insert an uncertain number of controls between two controls during runtime, a number of tab indices can be kept free in between the two controls.
Tag	string. The Tag property can be used to store and evaluate additional information at a control. This information may then be used in the program source code.

A dialog model exports the interfaces com.sun.star.beans.XPropertySet and com.sun.star.beans.XMultiPropertySet. When you set multiple properties at the same time you should use com.sun.star.beans.XMultiPropertySet because then multiple properties can be set with a single API call. When you use com.sun.star.beans.XMultiPropertySet you must remember to pass the properties in alphabetical order (see the examples in the following chapters).

Note: Toolkit control models are generally configured by attributes that are defined in the service descriptions, whereas controls usually implement interfaces. This same principle applies to dialogs.

The following code snippet demonstrates the assignment of the most important dialog properties:

  // Define the dialog at the model - keep in mind to pass the property names in alphabetical order!
  String[] sPropertyNames = new String[] {"Height", "Moveable", "Name","PositionX","PositionY", "Step", "TabIndex","Title","Width"};
 
  Object[] oObjectValues = new Object[] { new Integer(380), Boolean.TRUE, "MyTestDialog", new Integer(102),new Integer(41), new Integer(0), new Short((short) 0), "OpenOffice", new Integer(250)};
  setPropertyValues( sPropertyNames, oObjectValues);
 
  ...
 
  public void setPropertyValues(String[] PropertyNames, Object[] PropertyValues){
  try{
      XMultiPropertySet xMultiPropertySet = (XMultiPropertySet) UnoRuntime.queryInterface(XMultiPropertySet.class, m_xDlgModelNameContainer);
      xMultiPropertySet.setPropertyValues(PropertyNames, PropertyValues);
  } catch (com.sun.star.uno.Exception ex) {
      ex.printStackTrace(System.out);
  }}

Multi-Page Dialogs

A dialog may have several pages that can be traversed step-by-step. This feature is used in the Apache OpenOffice wizards. The dialog-model property Step defines which page of the dialog is active. At runtime, the next page of a dialog is displayed by increasing the Step value by 1. The Step property of a control defines the page of the dialog that the control is visible on. For example, if a control has a Step value of 1, it is only visible on page 1 of the dialog. If the Step value of the dialog is increased from 1 to 2, then all controls with a Step value of 1 are removed and all controls with a Step value of 2 become visible. A special role has the Step value 0. If the control's Step is assigned to a value of 0, the control is displayed on all dialog pages. If the dialog's Step property is assigned to 0, all controls regardless of their Step value are displayed. The property Visible, specified in the service com.sun.star.awt.UnoControlModel determines if a control should appear on a certain step or not. However, the effective visibility of a control also depends on the value of the Step property. A control is visible only when the Visible property is set to true and when the value of the control Step property is equal to the dialog Step property.

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