Documentation/DevGuide/Graphical User Interfaces

The com.sun.star.awt API-module is used to access and design user interface features. The concepts that this module are based on are similar to java.awt. This module provides services and interfaces to create and handle the large set of GUI elements that are demanded by today's modern components. This chapter is directed to extension developers who want to add functionality to their LibreOffice application and want to create a consistent user interface.

Implementation Details
You can use the UNO module Abstract Window Toolkit (UNO-AWT) to create a graphical user interface. The concept of UNO-AWT is based on Java/AWT. Java provides the AWT and Swing user interface design packages within its Java Foundation Classes class library. The implementation of java.awt components is based on the implementation of the peer components of the operating system. This is known as a "heavyweight" implementation. com.sun.star.awt components are lightweight controls because their implementation is based solely on LibreOffice. This gives you platform independence. The functionality of heavyweight controls may only be as high as the lowest common denominator of all involved operating systems, however, LibreOffice UI components are meant to emulate the design of the corresponding components of the operating system. The layer responsible for this is called VCL or Visual Class Library. The layer on top of the VCL is the Toolkit layer. This layer maps all interfaces of com.sun.star.awt to VCL.

Basic Concepts
The basic concepts that are used in com.sun.star.awt are described in previous chapters:


 * Event Model describes how to use event listeners at controls. With Event-Listeners at controls you can determine how a window reacts to mouse or keyboard driven events.
 * Exceptions explains how to handle errors as Exceptions.
 * Introduction describes factories.
 * Data Types describes the basic UNO types, and provides information about how to convert these types to and from various target languages.
 * LibreOffice Basic provides information for developers who want to implement Basic macros.
 * Accessing Dialogs explains how dialogs created with the dialog engine can be embedded within LibreOffice extensions.

Exception Handling
In theory, robust exception handling reacts to all unpredictable situations. In practice, many of these situations can be avoided by preventive runtime behavior or by making sure that the methods defined to raise exceptions are only used in a defined context. In these cases empty exception handling as done in the example code is justifiable.

Dialogs and Controls
The com.sun.star.awt module provides a set of services specifying UNO components that can be used within dialogs. The controls as well as the dialog itself, follow the Model-View-Controller (MVC) paradigm, which separates the component into three logical units, the model, view, and controller. The model represents the data and the low-level behavior of the component and has no specific knowledge of its controllers or its views. In practice this separation is not always strictly followed. The UNO control models can contain information about the visual display of the controls.

The view manages the visual display of the state represented by the model. The controller manages the user interaction with the model. Toolkit controls combine the view and the controller into one logical unit that forms the user interface for the component. For example, the text field model is implemented by the com.sun.star.awt.UnoControlEditModel service that extends the com.sun.star.awt.UnoControlModel service. All aspects of the model are described as a set of properties which are accessible through the com.sun.star.beans.XPropertySet interface. The view is responsible for the display of the text field and its content.

The controller handles the user input provided through the keyboard and mouse. If the user changes the text in a text field, the controller updates the corresponding model property. The controller also updates the view. For example, when the user selects some text in a text field and presses the delete key on the keyboard, the marked text in the text field is deleted.

A more detailed description of the MVC paradigm can be found in The Model-View Paradigm.

The base for all the Toolkit controls is the com.sun.star.awt.UnoControl service that exports the following interfaces:


 * The com.sun.star.awt.XControl interface specifies control basics. For example, it gives access to the model, view and context of a control.
 * The interfaces com.sun.star.awt.XWindow, com.sun.star.awt.XWindow2 , com.sun.star.awt.XWindowPeer specify operations for a window component. They are all based on an equal footing and are a available on arbitrary UNO-objects representing windows.
 * The com.sun.star.awt.XView interface provides methods for attaching an output device and drawing an object.

Dialog Creation
To create a dialog you can design the dialog within the dialog engine (as explained in LibreOffice Basic) and add it to an extension project (as described in Accessing Dialogs). A programmatic approach to create a dialog is illustrated in the following process sequence:

Instantiation of a Dialog
The first step to create a dialog is to instantiate the dialog and its corresponding model. As can be seen in the following code example, the dialog as well as its model are created by the global. The model is assigned to the dialog using. The dialog model is a com.sun.star.container.XNameContainer that keeps all control models and accesses them by their name. Similarly the dialog implements the interface com.sun.star.awt.XControlContainer that accesses the controls via the method. In a later step, each control model must be added to the Name-Container of the dialog model, which is why these object variables are defined with a public scope in the code example. Alternatively you can also retrieve the dialog model using the method  at the dialog interface com.sun.star.awt.XControl.

Setting Dialog Properties
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:

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).

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

Multi-Page Dialogs
A dialog may have several pages that can be traversed step-by-step. This feature is used in the LibreOffice 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.

Adding Controls to a Dialog
After the dialog and its model have been instantiated and configured, the dialog controls can be added as described in Programming Dialogs and Dialog Controls.

Displaying Dialogs
After you have inserted the controls, you can create a WindowPeer, a low level object that makes sure the window is displayed correctly, and the dialog can be executed. A dialog implements com.sun.star.awt.XWindow. To access the window toolkit implementation, a com.sun.star.awt.XWindowPeer must be created. The dialog control is shown by calling the  method of the com.sun.star.awt.XDialog interface. It can be closed by calling, or by offering a Cancel or OK Button on the dialog Command Button. Dialogs such as this one are described as modal because they do not permit any other program action until they are closed. While the dialog is open, the program remains in the  call. The  method at the end of the code frees the resources used by the dialog. It is important to note that  - the method to free the memory - must be positioned directly after the execute call and not behind

The method  creates an internal or low level peer-object, that makes sure that the window is displayed correctly.

Dialog Handling
When a designed dialog has been executed either after it has been created via a dialog editor or programmatically, there usually is a demand to interact with the dialog, or query its state or the states of its contained controls during runtime. This topic will help you become familiar with how to handle UNO dialogs during runtime, and it will provide you with an overview of all of the supported dialog controls. It does not provide a complete description of all involved facets. It is meant to provide you with the information you need to solve individual problems on your own. Additional information can be found in the respective interface and service descriptions.

Events
LibreOffice dialogs are based on an event-oriented programming model where you can assign event handlers to the control elements. An event handler runs a predefined procedure when a particular action occurs. Event handlers are always added directly to the control (not to the control models). All dialog controls implement the interface com.sun.star.awt.XControl which extends the interface com.sun.star.awt.XWindow. Listeners are added to a control with a specific  method like. Listeners are removed with a specific  method like.

The methods of all listener interfaces have a parameter of a type derived from com.sun.star.lang.EventObject, for example com.sun.star.awt.MouseEvent , com.sun.star.awt.FocusEvent etc. This event object always carries a property  by which it is possible to query the control an event has been triggered at.

The following code example shows how to implement an. You must remember to implement the  method as dictated by com.sun.star.lang.XEventListener. is supposed to be triggered when a  command at the control has been invoked.

Mouse Listeners
Events that correspond to mouse actions are triggered by a com.sun.star.awt.XMouseListener that react to mouse movements over a control. Popular use-cases for a mouse listener are changing the mouse pointer when the mouse moves over the window or querying the click count of the event  when you want to differentiate between a single-click and a double click. For this purpose all methods carry a parameter com.sun.star.awt.MenuEvent, a structure that contains amongst other things, the member. Other members ( and  ) are to query the mouse position during the event invocation and   that refers to the pressed mouse buttons.

A  that implements com.sun.star.awt.XMouseMotionListener can be used when a movement of the mouse pointer must be observed. The following example code shows a part of an implementation of a mouse motion listener that is executed when the mouse is entering a control. For further information about, see Displaying Dialogs.

Keyboard Listener
Keyboard events can be captured by a  that implements com.sun.star.awt.XKeyListener. This allows you to verify each keyboard stroke. This listener is very useful for edit controls. The interface dictates the implementation of the two methods  and.

Focus Listener
A focus listener implementing com.sun.star.awt.XFocusListener is notified when the focus is entering or leaving  a control.

The  is usually used to verify the user input when the control loses the focus.

This example demonstrates how to use the :

Paint Listener
Paint Listeners implementing com.sun.star.awt.XPaintListener are used to repaint areas that have become invalid.

Control element-specific events
Control element-specific events are events that only occur in relation to certain control elements.

The  event is implemented in some control-button models. It is particularly useful because it is sent by either a key-press or a mouse-down action. Thus, it provides a consistent interface for users who navigate by mouse or by keyboard. If the model implements the  capability,   is the event that is repeatedly sent.

Dialog Controls
Dialog controls follow the MVC paradigm Frame-Controller-Model Paradigm in LibreOffice. Many attributes are offered by the control model that you would normally expect to find in the control itself. Properties like  or   are examples of typical view attributes that are available in the model.

All control models within a UNO dialog support the service com.sun.star.awt.UnoControlModel, that includes com.sun.star.awt.UnoControlDialogElement , as described in Setting Dialog Properties. It 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 [IDL: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 make sure you pass the properties in alphabetical order. All relevant properties may be set directly in the control model. Some controls offer similar functionality, but by default you should always work in the control model.

The coding examples in the following sections concentrate on control models as the default.

Controls are required to:


 * Attach listeners.
 * Get Window or device dependent information.
 * Use the "convenience" functionality offered by list boxes.
 * Adjust the size according to the content. The interface com.sun.star.awt.XLayoutConstrains offers methods like  that can be helpful when the size of the control is to be adjusted to its content. You must remember that the Unit of the returned size is according to the specification in com.sun.star.awt.Size in 1/100th mm. This size may be applied with   at the control.

Common Properties
The common set of properties that are used by all controls are:

Font-specific Properties
The following properties are available on all controls with descriptive texts such as text fields, command buttons, radio buttons and check boxes. They are in all respective service specifications of these controls (it is the model's service description). When you are working with font properties, https://www.openoffice.org/issues/show_bug.cgi?id=71482 must be considered.

Font properties may either be set as single properties or as a whole by means of the font descriptor which is useful when you want to assign the same properties to multiple objects.

Other Common Properties
The following properties are used by most controls:

As LibreOffice emulates the look and feel of the operating system, changing some of these properties may not have any effect. There is no strict rule to be followed when property changes are ignored or not.

Property Propagation Between Model and Control
One particularity in the relationship of UNO controls and their models must be considered. Following the principles of the MVC paradigm all changes applied to the control model are directly propagated to the control and (its peer object). However, conversely not all changes applied to the control will notify the model. The general rule is that whenever an attribute of a control is modifiable by the user, a change of this attribute is also propagated to the model. The following table sums up all methods which invocation at UNO controls is propagated to the respective control model. The controls and interfaces are described in detail in the following sections.

Common Workflow to add Controls
For any existing dialog controls there is a common workflow to follow to insert a control into a dialog:


 * 1) Instantiate the control model at the MultiServiceFactory of the dialog.
 * 2) Set the Properties at the control model (for performance reasons, use the interface com.sun.star.beans.XMultiPropertySet ).
 * 3) Insert the control model at the control model container of the dialog model. In our coding examples we refer to this container by the public object variable   created in the code example of Instantiation of a Dialog
 * 4) Query the control from the dialog control container by referencing the name (that you have previously assigned to the control model). Note: According to the MVC paradigm there is no way to retrieve the control from the model.

The Example Listings
As is generally known, an example is worth a thousand words. This is especially true for UNO. Sourcecode written in UNO is very often self-explanatory and for this reason the following sections provide a large set of example listings. Some of them are ready-to-use, whereas the focus of other examples is on demonstrating concepts.

All coding examples that demonstrate how to insert controls into a dialog make use of the following method:

As already explained, the dialog keeps the controls in a  that implements com.sun.star.container.XNameAccess. It is absolutely necessary for the controls to have a unique name before they are added to the dialog to prevent a com.sun.star.container.ElementExistException. This method appends a suffix to the scheduled name of the control to make sure that the name is unique.

Label Field
A label field control supports the service com.sun.star.awt.UnoControlFixedText and the model com.sun.star.awt.UnoControlFixedTextModel .It displays descriptive texts that are not meant to be edited by the user, such as labels for list boxes and text fields. By default, the label field control is drawn without a border. The format of the text can be set by the properties as described in Font-specific Properties. Label controls can be used to assign shortcut keys for controls without labels that succeed the label field control. To assign a shortcut key to a control without a label such as a text field, the label field is used. The tilde (~) prefixes the corresponding character in the  of the label field. A fixed text control cannot receive the focus, so the focus automatically moves to the next control in the tab order. It is important that the label field and the text field have consecutive tab indices.

The following example demonstrates how to create a  control. You can create all types of dialog controls in the same way as is shown in this example. This example assumes that a dialog has already been created as described in Instantiation of a Dialog. This example also shows how to add a mouse listener.

Command Button
The command button com.sun.star.awt.UnoControlButton allows the user to perform an action by clicking on it. Usually a command button displays a label that is set by the  property of the control model that supports the service com.sun.star.awt.UnoControlButtonModel.

A command button supports the display of images as explained in Image Control.

In the example, an action listener is attached to the command button. An action listener implements the interface com.sun.star.awt.XActionListener and its method  is invoked when the user clicks on the button. (see also Events).

The following code snippet shows an example of how to use the action listener.

Graphics
When an image source is used several times it may be better to keep the image in its own object variable. The following code snippet shows how you can create such a variable:

This object variable may be assigned to the property Graphic that is also supported by image controls Image Control, check boxes Check Box, radio buttons Radio Button and command buttons. Note: Issue https://www.openoffice.org/issues/show_bug.cgi?id=76718 has not yet been resolved. The graphic may only be assigned to the control after the peer of the dialog has been created (see Displaying Dialogs).

Image Control
If you want to display an image without the command button functionality, the image control com.sun.star.awt.UnoControlImageControl and its model com.sun.star.awt.UnoControlImageControlModel is the control of choice. The location of the graphic for the command button is set by the  property. Usually, the size of the image does not match the size of the control, therefore the image control automatically scales the image to the size of the control by setting the  property to true.

One problem with URLs in LibreOffice is that the developer, in certain contexts, may only know the system dependent path to his or her image file. A system path is not accepted by. The following example shows how you can convert this path to a URL that can then be passed to the property.

Extension developers will be confronted with the problem that the graphic to be displayed by the image is located within the extension file. OpenOffice.org version 2.3 provided a simple method to query the path of the extension, see Location of Installed Extensions.

For previous versions of LibreOffice a manual workaround can be used, see description hereunder.

The path to the images of the extension should be set in a configuration file of the component For example:

The variable  will be automatically assigned the value of the URL of the component file when this entry is queried during runtime:

For further information about the development of extensions and configuration file handling, please see Integrating Components into LibreOffice).

Check Box
The check box control model com.sun.star.awt.UnoControlCheckBoxModel is used in groups to display multiple choices. When a check box is selected it displays a check mark. Check boxes work independently of each other. A user can select any number or combination of check boxes. The  property of the model service com.sun.star.awt.UnoControlCheckBoxModel defines three values, where 0 is not checked, 1 is checked, and 2 is undetermined. You can enable the tri-state mode of a check box by setting the  property to True. A tri-state check box used to give the user the option of setting or unsetting an option.

In this example, a com.sun.star.awt.XItemListener is attached to the checkbox control. This listener is notified on each change of the State property in the control model. Listeners on check boxes are often used to enable or disable controls whose functionality is dependent on the state of a checkbox:

A checkbox may also display images similar to a button as described in Command Button.

Radio Button
A radio button control model com.sun.star.awt.UnoControlRadioButtonModel is a simple switch with two states selected by the user. Usually these controls are used in groups to display several options that the user may select. While they are very similar to check boxes, selecting one radio button deselects all the radio buttons in the same group. To assemble several radio buttons to a control group it is important to know that there may not be any control  between the tab indices of the radio buttons although it is not necessary for the tab indices to be directly consecutive. Two groups of radio buttons can be separated by any control with a tab index that is between the tab indices of the two groups. Usually a group box, or horizontal and vertical lines are used because those controls visually group the radio buttons together. In principal, any control can be used to separate groups of radio buttons. There is no functional relationship between a radio button and a group box Group Box. The state of an radio button is accessed by the State property in the service com.sun.star.awt.UnoControlRadioButtonModel, where 0 is not checked and 1 is checked.

A radio button may also display images similar to a button as described in Command Button.

The following example demonstrates the way a group of two radio buttons may be created. Note the assignment of the tab indices to each radio button.

Scroll Bar
A com.sun.star.awt.UnoControlScrollBar can be used to display arbitrary content. This can be content that is too large in size to fit into a dialog or any other measurable content. It offers assistance to the user for the navigation through a container, like a group of controls. The user positions the thumb in the scroll bar to determine which part of the content is to be displayed in the viewing area of the dialog. The component that uses the scroll bar then typically adjusts the display so that the end of the scroll bar represents the end of the contents that can be displayed, or 100%. The start of the scroll bar is the beginning of the content that can be displayed, or 0%. The position of the thumb within those bounds then translates to the corresponding percentage representing the position within the total content.

Typically a com.sun.star.awt.XAdjustmentListener is added to the control by means of the method  of the interface com.sun.star.awt.XScrollBar. The method  is called each time the position of the thumb in the scroll bar changes. The model com.sun.star.awt.UnoControlScrollBarModel offers the following properties:

You can also set these attributes com.sun.star.awt.XScrollBar interface.

This example demonstrates how you can set up a scroll bar:

The, that has been added to the example scroll bar must implement the method  :

List Box
The list box control com.sun.star.awt.UnoControlListBox displays a list of items that the user can select one or more of. If the number of items exceeds what can be displayed in the list box, scroll bars automatically appear on the control. The model of a list box supports the service com.sun.star.awt.UnoControlListBoxModel :

The list box allows you to register a com.sun.star.awt.XItemListener as well as a com.sun.star.awt.XActionListener. Double-clicking a list box item will invoke the method  of the action listener. If items are selected with a single click or even programmatically, the method  is called when an item listener is registered at the list box control.

The list box control that supports the interface com.sun.star.awt.XListBox offers more convenient functions than the list box model. For example, it offers the method  to select or deselect a single item in the list box. As can be seen in the following example, to achieve the same result with the model, a sequence of all selected list box item indices must be assigned.

Combo Box
A combo box control presents a list of items to the user. It also contains a text field allowing the user to input text that is not in the list. A combo box is used when there is a list of suggested choices, whereas a list box is used when the user's input is limited only to the list. The features and properties of a combo box and a list box are similar. As can be seen in com.sun.star.awt.UnoControlComboBox the combo box includes the functionality of a com.sun.star.awt.UnoControlEdit, which also allows you to add an com.sun.star.awt.XTextListener to the combo box. The text displayed in the field of the combo box can be controlled by the Text property of the combo box model that supports the service com.sun.star.awt.UnoControlComboBoxModel. Just like in the list box, the actual list of items is accessible through the  property. A useful feature of the model is the automatic word completion that can be activated by setting the property  to.

You can control the items in a combo box via the interface com.sun.star.awt.XComboBox at the control, which offers a more convenient access to the control's functionality.

Progress Bar
The progress bar control com.sun.star.awt.UnoControlProgressBar displays a growing or shrinking bar to give the user feedback during a persisting task. The minimum and the maximum progress value of the control is set by the  and the   properties of the control model that supports the service com.sun.star.awt.UnoControlProgressBarModel. The progress value is controlled by the  property. The fill color can be changed by setting the property. The control implements the interface com.sun.star.awt.XProgressBar which allows you to control the progress bar. The progress bar interface com.sun.star.awt.XReschedule helps to update and repaint the progress bar while a concurrent task is running, but this interface interrupts the main thread of the office. Issue https://www.openoffice.org/issues/show_bug.cgi?id=i71425 is assigned to find an appropriate solution for this problem.

Horizontal/Vertical Line Control
The line control service com.sun.star.awt.UnoControlFixedLine describes the behavior of simple lines in a dialog. In most cases, the line control is used to visually subdivide a dialog. The line control may provide horizontal or vertical orientation which is determined by the Orientation property of the model as specified in com.sun.star.awt.UnoControlFixedLineModel. The label of a line control is set by the  property. The label is only displayed if the control has a horizontal orientation.

This example inserts a line with a horizontal orientation (Orientation == 0) in a dialog:

Group Box
The group box control com.sun.star.awt.UnoControlGroupBox creates a frame to visually group other controls together, such as option buttons and check boxes. Controls can be added to the group box at any time. The group box control does not provide any container functionality for other controls, it is merely a visual control, and is always transparent. The group box contains a label embedded within the border and is set by the Label property. LibreOffice uses fixed lines Horizontal/Vertical Line Control to visually subdivide a dialog into logical control groups.

Text Field
The text field, described by the service com.sun.star.awt.UnoControlEdit and its respective model - specified in com.sun.star.awt.UnoControlEditModel - is used to receive input from the user during runtime. As can be seen in the following table, most of the control settings can also be applied to the model. When a text field receives the focus by pressing the TAB key, the displayed text is selected and highlighted by default. The default cursor position within the text field is to the right of the existing text. If the user starts typing while a block of text is selected, the selected text is replaced. In some cases, the user may change the default selection behavior and set the selection manually. This is done using the com.sun.star.awt.XTextComponent interface.

This example demonstrates how you can use a :

The text listener must implement the method :

The control that supports the interface com.sun.star.awt.XTextComponent offers additional methods to query and set selections and insert part texts in the control.

Text Field Extensions
A user can enter any kind of data into a text field. These values are always stored as a string in the  property. This can cause some problems when you are evaluating the user input. These controls offer specific solutions to this issue:


 * Formatted field.
 * Date field.
 * Time field.
 * Currency field.
 * Numeric field.
 * Pattern field.

Formatted Field
The formatted field control com.sun.star.awt.UnoControlFormattedField specifies a format that is used for formatting the entered and displayed data.

As any kind of number format at the model of the formatted field may be set, this control can be universally used instead of the date field, time field, numeric field or currency field controls that are designed for special purposes as described in the following sections.

The following example demonstrates the creation of a formatted field. One critical point is to assign the  to the property. In the example, this is created directly at the global. It is also possible to assign an existing, like a spreadsheet document or a text document.

The attached spin listener in this code example must implement com.sun.star.awt.XSpinListener which, among other things, includes up

Numeric Field
For developers who want to use a simple numeric field control and find the number formatter too difficult to handle, they can use the numeric field control com.sun.star.awt.UnoControlNumericField. The control model, specified in com.sun.star.awt.UnoControlNumericFieldModel is simple to set up as the following table illustrates:

The code example sets up a numeric field with a defined number format and defines the numerical range within which the Value may be modified.

Currency Field
The currency field control com.sun.star.awt.UnoControlCurrencyField can be considered a specialization of the com.sun.star.awt.UnoControlNumericField. It is used for entering and displaying currency values. In addition to the currency value, reflected by the property, a currency symbol, set by the   property, is displayed. If the  property is set to , the currency symbol is displayed in front of the currency value.

Date Field
The date field control com.sun.star.awt.UnoControlDateField extends the text field control and is used for displaying and entering dates. The model is described in com.sun.star.awt.UnoControlDateFieldModel :

Although the date field control provides a spin button, there is no  property. In this control, the interval steps of the spin button are set automatically and depend on the position of the cursor within the date display. This means that if, for example, the cursor is within the month section of the date display, only the months are controlled by the spin button.

Time Field
The time field control com.sun.star.awt.UnoControlTimeField and its model com.sun.star.awt.UnoControlTimeFieldModel displays and enters time values.


 * com.sun.star.awt.UnoControlTimeFieldModel:TimeMax
 * rowspan="2"| . Similar to to the, the minimum and maximum time value that can be entered is given by the   and   properties. If the value of   exceeds one of these two limits the value is automatically reset to the according maximum or minimum value.
 * com.sun.star.awt.UnoControlTimeFieldModel:TimeMin
 * }
 * com.sun.star.awt.UnoControlTimeFieldModel:TimeMin
 * }

Although the time field provides a spin button, there is no  property. In this control the interval steps are set automatically and depend on the position of the cursor within the time display. For example, if the cursor is within the minute section of the time display only the minutes are controlled by the spin button.

Pattern Field
The pattern field control com.sun.star.awt.UnoControlPatternField defines a character code that restricts the user input. This character code that determines what the user may enter is defined by the  property. The length of the edit is equivalent to the number of the possible input positions. If a character is entered that does not correspond to the edit mask, the input is rejected. For example, in the edit mask " " the character " " has the meaning of a text constant and the character " " means that only the digits 0 to 9 can be entered. A complete list of valid characters can be found in the table below. The  property contains the initial values that are displayed in the pattern field. The length of the literal mask should always correspond to the length of the edit mask. An example of a literal mask which fits to the edit mask would be " ". In this case, the user enters only 4 digits when entering a date. If  is set to , the text will be checked during user input. If  is not set to   the text is not checked until the focus is leaving the control.

Roadmap Control
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 LibreOffice 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 com.sun.star.container.XIndexContainer at the roadmap model that is described by com.sun.star.awt.UnoControlRoadmapModel.

Roadmap Item
Each roadmap item delivers the following information:

Roadmap
Specifies a Roadmap control. A roadmap implements the interface com.sun.star.awt.XItemEventBroadcaster, which is helpful to add an  to the roadmap, when the property   of the roadmap model is set to. The listener is then always notified about changes of the property  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:

The following code snippet inserts a roadmap item into the roadmap control model.

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

File Control
The file control supports the service com.sun.star.awt.UnoControlFileControl and covers a lot of the functionality of an  control and a command button that is built in the control. This is put into practice by a control supporting the service com.sun.star.awt.UnoControlEdit. Similar to a Text Field the content may be retrieved by a  property. The value of  denotes the path of the control. Clicking this button brings up a file dialog in which the user may select a file that is taken over by by the file control like a text field. The following example sets up a file control. It is initialized with the configured  of the office installation that is converted to a system path before passed to the   property of the control Path Settings.

The file control also allows the configuration of the file dialog. File dialogs implementing the service com.sun.star.ui.dialogs.FilePicker do not belong to the module com.sun.star.awt, but, as they are frequently used by extension developers, this topic shall also be covered in this chapter.

Currently the control does not yet offer the described complete functionality which is addressed by https://www.openoffice.org/issues/show_bug.cgi?id=71041.

File Picker
A file picker supports the service com.sun.star.ui.dialogs.FilePicker and may depict a file-open or a file-save dialog in all conceivable facets. LibreOffice supports a great variety of filters. These may be applied to the file picker by means of the filter manager. Filters also affect the list of files displayed by the dialog and enable the file picker to append the file extension automatically. The names of the filters and their titles may be queried programmatically from the LibreOffice registry or - much easier like in the coding example below - be retrieved from Framework/Article/Filter. The following listing illustrates how to customize and raise a file-save dialog and query the result afterwards. The result is a file URL pointing to the location where a file is to be stored.

The directory that the file dialog initially displays is set by the  method. Of course, it must be set as a file URL. If no directory is passed, the customized Work-directory of the office application is shown.

Next to the file picker service it is also possible to raise a folder picker implementing the service com.sun.star.ui.dialogs.FolderPicker. Unlike the file picker the folder picker only displays folders.

Message Box
Message boxes contain a defined message and title that may be combined with predefined icons and buttons. Again the central instance to create a Message box is the service com.sun.star.awt.Toolkit. It serves as a factory that exports the interface com.sun.star.awt.XMessageBoxFactory. Its method  allows the creation of message boxes in various defined facets.


 * The first parameter of  denotes the peer of the parent window. In analogy to all LibreOffice windows the peer of the window parent must be conveyed.
 * The second parameter  may be empty (but not null).
 * The third parameter  describes the special usecase of the message box. The interface description lists a bunch of defined strings like " " or " ". The message box type is than differentiated by its contained icon.
 * Depending on the use case, different combinations of buttons in the message box are possible and reflected by a value of the constants group com.sun.star.awt.MessageBoxButtons . This is the fourth parameter.
 * The last two parameters reflect the title and the message  of the message box.

This example creates and executes a message box.

The Toolkit Service
The Service com.sun.star.awt.Toolkit is the central instance to create Windows. For this purpose the interface com.sun.star.awt.XToolkit is of major interest. The two methods  and   were used when LibreOffice offered an intregrated DesktopWindow, and are now deprecated. An instance of the com.sun.star.awt.Toolkit is created at the global. One way to get this peer from the frame of the document window can be seen in the following example.

Before investigating this example, it is reasonable to briefly describe the character of a frame. A frame exports the interface com.sun.star.frame.XFrame and serves as a container for arbitrary content - mostly document models. To visualize this content it uses a window ( com.sun.star.awt.XWindow ). It is the central coordination instance that brings together menus, documents, LayoutManager (see com.sun.star.frame.XLayoutManager ) and progress bars. For more information see Using the Component Framework. Another important responsibility is the delivery of commands - for example commands fired from toolbar buttons - to the components. See Dispatch Framework and Using the Dispatch Framework for more information on this. A frame may be embedded in a hierarchy of other frames. The following example demonstrates the creation of a very basic window that is attached to a desktop frame.

As can be seen, the window is described by a com.sun.star.awt.WindowDescriptor that manifests all the facets of the window and also the window attributes as defined in com.sun.star.awt.WindowAttribute. It is possible, but not necessary, to define a parent window. The member Type of the windowdescriptor distinguishes between various values of the enumeration com.sun.star.awt.WindowClass.

The following example shows how a document is loaded into a window that has been previously inserted into a dialog. The example method expects the peer of the parent dialog to be passed over.

As can be seen, the procedure to create the window and its frame is quite straightforward. The example clarifies the role of the frame as the central instance to bring together the window, layout manager and the document (model). You must set the  to make sure that the graphical operations on the parent window do not interfere with child windows.

Of course, there are use cases where no parent windowpeer is directly available, so this must be retrieved from a frame beforehand.

From the following example you can learn how to get the windowpeer from a frame

The  is the window that displays just the view of a document. The  is the complete window including its title bar and border.

There are several ways to retrieve a frame. The easiest way to retrieve a frame is to query the frame that has the focus:

This should only be used for debugging purposes. The method  is based on the implementation of the window handler of the operating system and you cannot be sure that the returned frame is always the desired one on all supported platforms, or that a valid frame is returned at all. Usually each LibreOffice extension provides a frame as explained in Integrating Components into LibreOffice.

Dockable Windows
The interface com.sun.star.awt.XDockableWindow is currently unpublished and only used internally to control layout manager based tool bars. Although the interface is exported by Windows too, its method is not fully supported. It is planed to support dockable windows in a future version of LibreOffice.

Creating Menus
If the developer wants to add menus to the LibreOffice menu bar these should be added according the detailed description of the OpenOffice.org Wiki article Implementing an extended recent file popup menu controller.

Add-ons can use the menu bar integration of the add-on feature. More information can be found in Add-Ons.

Programmatic insertion of menus to a menu bar is possible for all windows that support the interface com.sun.star.awt.XTopWindow.

Unlike in Java, in LibreOffice the term "PopupMenu" is used for all menus that can be either be used as location independent context menus or "ordinary" menus that are added to a menu bar.

The following example shows that:


 * Menus are created at the global service manager.
 * Following the definition of the constants group com.sun.star.awt.MenuItemStyle menu items may either work like radio buttons, check boxes or ordinary menu items. The constant  changes the behavior of the menu in such a way that the menu item gets checked on its selection.
 * The first parameter  of the method   denotes an identifier of a menu item. This must be a unique identifier if you want to recognize a selected menu item unambiguously. The last parameter   denotes the position of the menu item in the menu. The unique identifier is ignored for non-selectable menu items. For all other menu items the identifier must always be unique.
 * "Radio-menuitems" are identified as a group by their positions within the menu, meaning that consecutive "radio - menuitems" automatically belong to the same radio button - group.
 * There is no  representation for the menu items. After their creation, menu items are accessed by their   within the menu.
 * To assign a shortcut key to a menu item, the tilde "~" prefixes the corresponding character of the menu text.

Issue https://qa.openoffice.org/issues/show_bug.cgi?id=76363 addressed the deprecated notation of the service " "

The added  of the menu has to implement several methods such as


 * - invoked when the menu item is activated
 * - invoked when the menu item is highlighted, for example when the mouse moves over it
 * / - depending on the context, menu items may be activated (enabled) or deactivated (disabled)

All these methods carry a com.sun.star.awt.MenuEvent parameter. The menu item at which the method has been triggered can be identified by the  of this struct.

As we see, we encounter the  again that helps us to identify the triggered menu item.

At last the create menu has to be added to a menu bar: As can be seen from the idl description of com.sun.star.awt.XMenuBar, it is a direct descendant of com.sun.star.awt.XMenu. The menus below the menu bar items are added by means of the method.

Accessibility
Certainly for many LibreOffice extension developers, accessibility is an important issue. Luckily all UNO-AWT-elements automatically bring support for various accessibility aspects like keyboard navigation, scheming, assistive technology (AT), and much more, so that the developer does not even have to worry accessibility. A good introduction to this topic is the Wiki article at Accessibility. Some problems may arise and shall be dealt with in this chapter.

In the following scenario, a command button is inserted into a dialog. The label ">" of the button indicates that the activation of the button shifts some data from the left side to the right. As this label cannot be interpreted by the screenreader, an "AccessibleName" must be set at the control. Unfortunately this is not yet possible due to the issue https://www.openoffice.org/issues/show_bug.cgi?id=70296. At this stage, only a temporary solution can be offered that uses the deprecated interface com.sun.star.awt.XVclWindowPeer

LibreOffice offers a high contrast mode, in which objects are displayed without fill colors or text colors. This mode will automatically be used when high contrast is chosen in the system settings. Extension developers with the demand to create accessible applications must consider this and provide High-Contrast images for their dialog controls. Also for this usecase, only a temporary solution based on the deprecated interface com.sun.star.awt.XVclWindowPeer can be offered:

The method  expects a com.sun.star.awt.XVclWindowPeer reference from any existing dialog control or of the dialog itself.

Issue https://www.openoffice.org/issues/show_bug.cgi?id=74568 addresses this problem and will certainly lead to a more elegant solution.

Rendering
The module com.sun.star.awt offers a set of interfaces to render graphics. These interfaces are not deprecated as they are used internally. Developers are advised not to use these interfaces because the future belongs to a new API called the SimpleCanvas API ( https://www.openoffice.org/gsl/canvas/api/rendering/XSimpleCanvas.html ). For this reason these interfaces shall only be briefly explained.

com.sun.star.awt.XDevice The pixel model is extremely device dependent because it is applicable to printers as well as to screens with all kind of resolutions. This interface provides information about a graphical output device. For example the method  returns an object implementing com.sun.star.awt.XFont that describes a font on the respective device. The methods  and   create bitmap objects with the device depth (these objects are primarily used for internal use of graphic operations). The method  returns an object providing a set of output operations by implementing the interface com.sun.star.awt.XGraphics. It offers methods to draw geometric figures like,  , etc. and permits the assignment of clip regions that implement com.sun.star.awt.XRegion. By defining a clipping region the output is reduced to a certain area of a window in order to prevent other parts like the border or the menubar from being overdrawn by output operations. com.sun.star.awt.XRegion manages multiple rectangles which make up a region. Its main task is to perform adding, excluding, intersecting and moving operations on regions. A raster graphics image is defined by grid of pixels, that individually define a color. They are distinguished from vector graphics in that vector graphics represent an image through the use of geometric objects such as curves and polygons. The method  of com.sun.star.awt.XGraphics applies values specified in the enumeration com.sun.star.awt.RasterOperation on the pixels of a graphic.

Summarizing Example to Create a UNO Dialog
Last but not least, a final example shall give an overall demonstration about how a dialog is created. The aim of the dialog is to inspect an arbitrary UNO-object and display its supported services, exported interfaces, methods and properties. It uses the code fragments that were introduced in the previous chapters. These code fragments are encapsulated in the class, that is not listed here. The creation of the dialog is implemented within the main method. Before this takes place an UNO object – an empty writer document - is created. This code piece can of course be exchanged and only serves as an example UNO object. The class  is a deduction of   and incorporates all the functionality used to create and display this specific dialog. Keep in mind that all variables prefixed with “ ” are member variables defined in the constructor.