 |
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. |
[ Previous document | Content Table | Next document ]
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 OpenOffice.org application and want to create a consistent user interface.
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 OpenOffice.org. 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, OpenOffice 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.
The basic concepts that are used in com.sun.star.awt are described in previous chapters:
3.3.6 Professional UNO - UNO Concepts - 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.
3.3.7 Professional UNO - UNO Concepts - Exception Handling explains how to handle errors as Exceptions.
3.1 Professional UNO - Introduction describes factories.
3.2.1 Professional UNO - API Concepts - Data Types describes the basic UNO types, and provides information about how to convert these types to and from various target languages.
12 OpenOffice.org Basic and Dialogs provides information for developers who want to implement Basic macros.
4.11 Writing UNO Components - Accessing Dialogs explains how dialogs created with the dialog engine can be embedded within OpenOffice.org extensions.
In theory, robust exception handling reacts to all unpredictable situations. In practise, 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.
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 practise 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 14.2 Forms - Models and Views.
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.
To create a dialog you can design the dialog within the dialog engine (as explained in 12 OpenOffice.org Basic and Dialogs) and add it to an extension project (as described in 4.11 Writing UNO Components - Accessing Dialogs). A programmatic approach to create a dialog is illustrated in the following process sequence:
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 MultiComponentFactory. The model is assigned to the dialog using setModel(). 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 getControl(). 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 getModel()at the dialog interface com.sun.star.awt.XControl.
public XNameContainer m_xDlgModelNameContainer = null;
public XControlContainer m_xDlgContainer = null;
...
private void createDialog(XMultiComponentFactory _xMCF) {
try {
Object oDialogModel = _xMCF.createInstanceWithContext("com.sun.star.awt.UnoControlDialogModel", m_xContext);
// The XMultiServiceFactory of the dialogmodel is needed to instantiate the controls...
m_xMSFDialogModel = (XMultiServiceFactory) UnoRuntime.queryInterface(XMultiServiceFactory.class, oDialogModel);
// The named container is used to insert the created controls into...
m_xDlgModelNameContainer = (XNameContainer) UnoRuntime.queryInterface(XNameContainer.class, oDialogModel);
// create the dialog...
Object oUnoDialog = _xMCF.createInstanceWithContext("com.sun.star.awt.UnoControlDialog", m_xContext);
m_xDialogControl = (XControl) UnoRuntime.queryInterface(XControl.class, oUnoDialog);
// The scope of the control container is public...
m_xDlgContainer = (XControlContainer) UnoRuntime.queryInterface(XControlContainer.class, oUnoDialog);
m_xTopWindow = (XTopWindow) UnoRuntime.queryInterface(XTopWindow.class, m_xDlgContainer);
// link the dialog and its model...
XControlModel xControlModel = (XControlModel) UnoRuntime.queryInterface(XControlModel.class, oDialogModel);
m_xDialogControl.setModel(xControlModel);
} catch (com.sun.star.uno.Exception exception) {
exception.printStackTrace(System.out);
}}
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 | |||||
|
|
long. Attributes denoting the position and size of controls are also available at the control, but the 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. | ||||
|
long. The Step property is described in detail in the next section. | |||||
|
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”. | |||||
|
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. | |||||
|
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);
}}
A dialog may have several pages that can be traversed step-by-step. This feature is used in the OpenOffice.org 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 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.
After the dialog and its model have been instantiated and configured, the dialog controls can be added as described in 20.5.2 Graphical User Interfaces - Dialog Handling - Dialog Controls.
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 execute() method of the com.sun.star.awt.XDialog interface. It can be closed by calling endExecute(), or by offering a Cancel or OK Button on the dialog 20.5.2 Graphical User Interfaces - Dialog Handling - Dialog Controls - 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 execute() call. The dispose() method at the end of the code frees the resources used by the dialog. It is important to note that dispose()- the method to free the memory - must be positioned directly after the execute() call and not behind endExecute();
public short executeDialog() throws com.sun.star.script.BasicErrorException{
XWindow xWindow = (XWindow) UnoRuntime.queryInterface(XWindow.class, m_xDlgContainer);
// set the dialog invisible until it is executed
xWindow.setVisible(false);
Object oToolkit = m_xMCF.createInstanceWithContext("com.sun.star.awt.Toolkit", m_xContext);
XWindowPeer xWindowParentPeer = ((XToolkit) UnoRuntime.queryInterface(XToolkit.class, oToolkit)).getDesktopWindow();
XToolkit xToolkit = (XToolkit) UnoRuntime.queryInterface(XToolkit.class, oToolkit);
m_xDialogControl.createPeer(xToolkit, xWindowParentPeer);
m_xWindowPeer = m_xDialogControl.getPeer();
XDialog xDialog = (XDialog) UnoRuntime.queryInterface(XDialog.class, m_xDialogControl);
XComponent xDialogComponent = (XComponent) UnoRuntime.queryInterface(XDialog.class, m_xDialogControl);
// the return value contains information about how the dialog has been closed...
short nReturnValue = xDialog.execute();
// free the resources...
xDialogComponent.dispose();
return nReturnValue;
}
The method createPeer()creates an internal or low level peer-object, that makes sure that the window is displayed correctly.
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.
 |
Tip: You will most probably want your extension to integrate into OpenOffice.org. The OpenOffice.org style guide under http://ui.openoffice.org/knowledge/DialogSpecificationandGuidelines.odt defines the rules that user interface elements must follow in order to give the application a consistent look and feel. |
|
|
Tip: A specification guide that defines the general behavior of OpenOffice.org assistance is http://specs.openoffice.org/installation/wizards/Wizards_NewConcept.sxw. |
OpenOffice.org 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 add<ListenerName>Listener() method like addMouseListener( [in] XMouseListener xListener ). Listeners are removed with a specific remove<ListenerName>Listener() method like removeMouseListener( [in] XMouseListener xListener ).
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 Source by which it is possible to query the control an event has been triggered at.
The following code example shows how to implement an XActionListener. You must remember to implement the disposing() method as dictated by com.sun.star.lang.XEventListener. disposing() is supposed to be triggered when a dispose() command at the control has been invoked.
public void actionPerformed(ActionEvent rEvent){
try{
// get the control that has fired the event,
XControl xControl = (XControl) UnoRuntime.queryInterface(XControl.class, rEvent.Source);
XControlModel xControlModel = xControl.getModel();
XPropertySet xPSet = (XPropertySet) UnoRuntime.queryInterface(XPropertySet.class, xControlModel);
String sName = (String) xPSet.getPropertyValue("Name");
// just in case the listener has been added to several controls,
// we make sure we refer to the right one
if (sName.equals("CommandButton1")){
//...
}
}catch (com.sun.star.uno.Exception ex){
/* perform individual exception handling here.
* Possible exception types are:
* com.sun.star.lang.WrappedTargetException,
* com.sun.star.beans.UnknownPropertyException,
* com.sun.star.uno.Exception
*/
ex.printStackTrace(System.out);
}}
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 mousePressed([in] com.sun.star.awt.MouseEvent e)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.MouseEvent, a structure that contains amongst other things, the member ClickCount. Other members (PositionX and PositionY) are to query the mouse position during the event invocation and Buttons that refers to the pressed mouse buttons.
A MouseMotionListener 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 WindowPeers, see 20.4.4 Graphical User Interfaces - Dialog Creation - Displaying Dialogs.
public void mouseEntered(MouseEvent _mouseEvent) {
try {
// retrieve the control that the event has been invoked at...
XControl xControl = (XControl) UnoRuntime.queryInterface(XControl.class, _mouseEvent.Source);
Object tk = m_xMCF.createInstanceWithContext("com.sun.star.awt.Toolkit", m_xContext);
XToolkit xToolkit = (XToolkit) UnoRuntime.queryInterface(XToolkit.class, tk);
// create the peer of the control by passing the windowpeer of the parent
// in this case the windowpeer of the control
xControl.createPeer(xToolkit, m_xWindowPeer);
// create a pointer object "in the open countryside" and set the type accordingly...
Object oPointer = this.m_xMCF.createInstanceWithContext("com.sun.star.awt.Pointer", this.m_xContext);
XPointer xPointer = (XPointer) UnoRuntime.queryInterface(XPointer.class, oPointer);
xPointer.setType(com.sun.star.awt.SystemPointer.REFHAND);
// finally set the created pointer at the windowpeer of the control
xControl.getPeer().setPointer(xPointer);
} catch (com.sun.star.uno.Exception ex) {
throw new java.lang.RuntimeException("cannot happen...");
}}
Keyboard events can be captured by a KeyListener 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 keyPressed() and keyReleased().
public void keyReleased(KeyEvent keyEvent) {
int i = keyEvent.KeyChar;
int n = keyEvent.KeyCode;
int m = keyEvent.KeyFunc;
}
A focus listener implementing com.sun.star.awt.XFocusListener is notified when the focus is entering (focusGained()) or leaving (focusLost()) a control.
The FocusListener is usually used to verify the user input when the control loses the focus.
This example demonstrates how to use the focusEvent:
public void focusLost(FocusEvent _focusEvent) {
short nFocusFlags = _focusEvent.FocusFlags;
int nFocusChangeReason = nFocusFlags & FocusChangeReason.TAB;
if (nFocusChangeReason == FocusChangeReason.TAB){
// get the window of the Window that has gained the Focus...
// Note that the xWindow is just a representation of the controlwindow
// but not of the control itself
XWindow xWindow = (XWindow) UnoRuntime.queryInterface(XWindow.class, _focusEvent.NextFocus);
}
}
Paint Listeners implementing com.sun.star.awt.XPaintListener are used to repaint areas that have become invalid.
Control element-specific events are events that only occur in relation to certain control elements.
Dialog controls follow the MVC paradigm 14.2 Forms - Models and Views. Many attributes are offered by the control model that you would normally expect to find in the control itself. Properties like Visible or Printable 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 20.4.2 Graphical User Interfaces - Dialog Creation - 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 com.sun.star.beans.XMultiPropertySet because then multiple properties can be set with a single API call. When you use [IDL: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 getPreferredSize()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 setSize() at the control.
The common set of properties that are used by all controls are:
|
Common Properties of all control models | |
|
Enabled |
The Enabled property can be set to true or false to enable or disable a button during runtime. |
|
HelpText |
Help text is displayed as a tip on the control when the mouse moves over the control. |
|
HelpURL |
The HelpURL is the URL of a help document. When the control has the focus, you can press F1 to open the help document. This feature is not yet available for embedded custom help documents. See issue http://www.openoffice.org/issues/show_bug.cgi?id=20164 for more information. Currently the only supported “Help URL scheme” follows the pattern “HID:<HELPID>”. |
|
Printable |
If Printable set to false, the control is not visible on printer outputs. |
|
Tabstop |
The Tabstop property defines if a control can be reached with the TAB key. |
|
Visible |
The property Visible defines whether a dialog control is shown on its assigned dialog-step or not. The effective Visibility of a control is thus derived from the values of both properties Step and Visible. For example if the Step property of the control model is not equal to the Step property of the dialog model (that denotes the actual visible dialog step) the control will not be visible. In contrast, the method setVisible( [in] boolean Visible ) at the interface com.sun.star.awt.XWindow can be applied to the control and will set the Visibility of the control regardless the value of the Step property.[ISSUE-REFERENCE] |
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, http://www.openoffice.org/issues/show_bug.cgi?id=71482 must be considered.
|
Properties referring to Font Attributes | |
|
The property FontDescriptor applies to the structure com.sun.star.awt.FontDescriptor, where all available characteristics of the font may be set. | |
|
Determines the type and position of an emphasis mark in Asian texts. It can accept any of the values in com.sun.star.awt.FontEmphasis. | |
|
The FontRelief property accepts three values: (com.sun.star.text.FontRelief.) NONE (default), EMBOSSED or ENGRAVED. The embossed relief makes the characters appear as if they are raised above the page. The engraved relief makes the characters appear as if they are pressed into the page. | |
|
float. Specifies the character width. | |
|
short. Specifies the character set which is supported by the font. It can be any of the constants defined in com.sun.star.awt.CharSet. | |
|
string. Specifies the exact name of the font. | |
|
Specifies the family style of a font and can accept values from the constants group com.sun.star.awt.FontFamily. This defines the group of typefaces with similar characteristics. Recognized families are Roman, Swiss, Modern, Script, and Decorative. For example, “Arial”, “Arial Bold”, “Arial Bold Italic”, “Arial Italic”, Small Fonts, and MS Sans Serif are all part of the sans serif Swiss font family. | |
|
short. Specifies the height of the font in the measure of the destination. | |
|
short. Specifies the width of the font in the measure of the destination. | |
|
boolean. Font kerning defines the process of adjusting letter spacing in a proportional font. The value of the property indicates if there is a kerning table available for the font. The kerning table contains the values that control the intercharacter spacing for the glyphs in a font. | |
|
short. Specifies the rotation of the font in degrees where 0 is the baseline. | |
|
short. The font pitch defines whether the width of a character of a font is fixed (as in monospaced fonts) or variable. It may accept one of the values defined in the constants group com.sun.star.awt.FontPitch . | |
|
Specifies how slanted the characters should be. It can be any value of the enumeration com.sun.star.awt.FontSlant, denoting (reverse) italic or (reverse) oblique or none slants. | |
|
Specifies the strikeout style of the text as defined by the constants group com.sun.star.awt.FontStrikeout. | |
|
string. Indicates the individual style of a font. For example “Bold”, “Bold Italic” and “Italic” are defined styles of the font “Arial”. | |
|
short. Specifies the technology of the font representation as defined by the constants group com.sun.star.awt.FontType. These constants either indicate if a font is a raster font. A scalable font (or “vector font” or “outline font”) is one defined as vector graphics, i.e. as a set of lines and curves to define the border of glyphs, as opposed to a bitmap font, which defines each glyph as an array of pixels. A device font is a font that is only presentable on a special device like a printer. OpenOffice may use device independent metrics to display these fonts. | |
|
Specifies the underlining style of the text as defined by the constants group com.sun.star.awt.FontUnderline. | |
|
float. Specifies the thickness of the font lines as a percentage relative to the inherited font weight. | |
|
boolean. Specifies if only words get underlined. True means that only non-space characters get underlined, false means that the spacing also gets underlined. This property is only valid if the property com.sun.star.awt.FontDescriptor.UnderLine is not FontUnderline.NONE. | |
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.
The following properties are used by most controls:
|
Properties | |
|
BackgroundColor |
long. Sets the background color of the control. Its value is an integer type representing an RGB value as described in Color. |
|
TextColor |
long. Refers to the color of the text. When no specific text color is applied, it returns void.. |
|
TextLineColor |
long. Refers to the underlining style color of the text. If Underlining is not applied it is void. See also 20.5.2 Graphical User Interfaces - Dialog Handling - Dialog Controls - Font-specific Properties |
|
BorderColor |
long. Refers to the color of the border (see Border-property). When no specific text color is applied, it returns void. Not every border style may support coloring. For example, a border with 3D effect will usually ignore the BorderColor setting. |
|
Label |
string. The actual text displayed in a control is set by the Label property of the model. A shortcut key can be defined for any control with a label by adding a tilde (~) before the character that will be used as a shortcut. When the user presses the character key simultaneously with the ALT key, the control automatically gets the focus. |
|
MultiLine |
boolean. By default, the label displays the text from the Label property in a single line. If the text exceeds the width of the control, the text is truncated (but not the data of the text). This behavior is changed by setting the MultiLine property to true, so that the text is displayed on more than one line if needed. |
|
Align |
short. Specifies the horizontal alignment of the text in the control. |
|
VerticalAlign |
short. Specifies the vertical alignment of the text in the control. Available options are (com.sun.star.style.VerticalAlignment).TOP, BOTTOM and MIDDLE. |
|
Border |
short. Many controls support this property which accepts three values from the enumeration com.sun.star.awt.VisualEffect that defines if no Border, a flat border or a 3D border is to be applied. |
As OpenOffice.org 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.
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.
|
Control Service Name in com.sun.star.awt |
Interface in com.sun.star.awt |
Method Name |