Dialog and Control Paradigm
To understand how controls work, it is important that you understand the difference between a model, a view, and a controller. The model-view-control paradigm, sometimes referred to as MVC, is very widely used and accepted in the computer science community.
-
The model describes a control's appearance, data, and behavior. The model does not interact with a user and it is not able to display itself. When an object supports the MVC paradigm, the changes should be made to the object's model and then these changes will automatically be propagated to the views by the controller. Only one model can exist for an object.
-
The view is what the user sees. Although there can be only one model for an object, multiple views may exist to display an object.
-
The controller is what interacts with the user. When the user tells the controller to perform some action, a change is made to the model, and then the view is updated.
| Note | An OpenOffice.org document is distinguished from a non-document desktop component, such as the Basic IDE or the Help window, by the fact that it has a data model. In other words, OOo uses the MVC paradigm for documents. |
The controls that are displayed in dialogs generally contain access methods in the view portion that update and affect the model. I recommend that you use the model rather than the view methods unless you have a compelling reason to do otherwise , because it can lead to some inconsistencies. Apparently this problem is more pronounced with controls embedded in forms than in dialogs, but I have never observed the inconsistencies directly.
Dialog and Control Similarities
In some respects, a dialog is also a control. Dialogs support the MVC paradigm and share many similarities with controls. For example, dialogs support the UnoControl service, which is common to all controls. UNO controls support the XComponent interface, which is also supported by numerous other objects in OpenOffice.org (see Table 1 ).
| Method | Description |
|---|---|
| dispose() | The object's owner calls this method to free all the object's resources. You won't usually call this method. |
| add Event Listener(XEvent Listener) | Add an event listener to the object. |
| removeEventListener(XEventListener) | Remove an event listener from the object's listener list. |
The XControl interface identifies an object as a control. All objects that support the UnoControl service also support the XControl interface. For Basic programmers, the most interesting method is probably getModel() because it returns the control's data model (see Table 2 ).
| Method | Description |
|---|---|
| setContext(XInterface) | Set the control's context. |
| getContext() | Get the control's context. |
| createPeer(XToolkit, XWindowPeer) | Create a child window. If the peer is null, the desktop is the parent. This method is used to create a window to display a dialog that was created in a macro rather than in the IDE (see Listing 23). |
| getPeer() | Return the previously created or set peer XWindowPeer. |
| setModel(XControlModel) | Set the model's control; return True if successful. |
| getModel() | Return the control's XModel. |
| getView() | Return the control's XView. |
| setDesignMode(Boolean) | Turn the design mode on and off. |
| isDesignMode() | Return True if the control is in design mode; otherwise return False. |
| isTransparent() | Return True if the control is transparent; otherwise return False. |
When you set a position and a size by using a single method (see Table 4 ), the PosSize constant group is used to control which portions are actually updated (see Table 3 ).
| Constant | Name | Description |
|---|---|---|
| 1 | X | Flag the X coordinate. |
| 2 | Y | Flag the Y coordinate. |
| 4 | WIDTH | Flag the width. |
| 8 | HEIGHT | Flag the height. |
| 3 | POS | Flag the X and Y coordinates. |
| 12 | SIZE | Flag the width and height. |
| 15 | POSSIZE | Flag everything. |
A window is a rectangular region on an output device defined primarily by its position and size. The constants in Table 3 are used in the setPosSize() method shown in Table 4 to set the position and size. The XWindow interface defines the basic operations for a window component. The methods to get and set the position are demonstrated in Listing 17.
| Method | Description |
|---|---|
| setPosSize (x, y, width, height, PosSize) | Set the window's outer bounds (see Table 3). |
| getPosSize() | Return the window's outer bounds as a rectangle. |
| setVisible(Boolean) | Show or hide the window. |
| setEnable(Boolean) | Enable or disable the window. |
| setFocus() | Focus this window. |
| addWindowListener(listener) | Add the XWindowListener. |
| removeWindowListener(listener) | Remove the XWindowListener from the listener list. |
| addFocusListener(listener) | Add the XFocusListener. |
| removeFocusListener(listener) | Remove the XFocusListener from the listener list. |
| addKeyListener(listener) | Add the XKeyListener. |
| removeKeyListener(listener) | Remove the XKeyListener from the listener list. |
| addMouseListener(listener) | Add the XMouseListener. |
| removeMouseListener(listener) | Remove the XMouseListener from the listener list. |
| addMouseMotionListener(listener) | Add the XMouseMotionListener. |
| removeMouseMotionListener(listener) | Remove the XMouseMotionListener from the listener list. |
| addPaintListener(listener) | Add the XPaintListener. |
| removePaintListener(listener) | Remove the XPaintListener from the listener list. |
The XView interface defines the methods required to display an object (see Table 5 ). These methods are used primarily by advanced users and are included here only for completeness.
| Method | Description |
|---|---|
| setGraphics(XGraphics) | Set the output device. |
| getGraphics() | Return the XGraphics output device. |
| getSize() | Returns the size of the object in device units. |
| draw(x, y) | Draws the object at the specified position. |
| setZoom(x, y) | Set the zoom factor of the control's contents. |
Dialog-Specific Methods
The methods defined in Table 1 through Table 5 are common to all control types. As expected, however, dialogs support methods and properties that are specific to dialogs (see Table 6 ).
| Method | Description |
|---|---|
| setTitle() | Set the dialog's title. |
| getTitle() | Get the dialog's title. |
| execute() | Display the dialog. |
| endExecute() | Hide the dialog and cause the execute() method to return. |
All controls act as a window: They are rectangular in shape, can receive focus, be enabled and disabled, and have listeners (see Table 4). Top-level windows add extra functionality because they are not contained in another window (see Table 7 ).
| Method | Description |
|---|---|
| addTopWindowListener(XTopWindowListener) | Add a listener for this window. |
| removeTopWindowListener(XTopWindowListener) | Remove a listener so that it no longer receives events from this window. |
| toFront() | Move this window in front of all other windows. |
| toBack() | Move this window behind all other windows. |
| setMenuBar(XMenuBar) | Set a menu bar for this window. |
The primary function of a dialog is to contain controls. The methods in Table 8 allow a dialog to add, remove, and get controls contained in a dialog. It is very common to extract a control from a dialog to read or set its value.
| Method | Description |
|---|---|
| setStatusText(String) | Set the text in the container's status bar. |
| getControls() | Return all controls as an array of type XControl. |
| getControl(name) | Return the XControl with the specified name. |
| addControl(name, XControl) | Add the XControl to the container. |
| removeControl(XControl) | Remove the XControl from the container. |
Controls are usually not added to or removed from the dialog. If you create a dialog using a macro, rather than designing the dialog in the IDE, you add control models to the dialog's model, rather than adding controls directly to the dialog. As usual, the work is done in the model and the changes are reflected in the view. The most-used method in Table 8 is getControl(name).
The Dialog Model
You can obtain a control's model by using the method getModel() defined in Table 2. Dialogs support the UnoControlDialogModel service (see Table 9 ) that defines many of the properties that you can set from the Basic IDE (see Figure 3). You can set some properties directly from the dialog object-the setTitle() method in Table 6, for example-but it is better to modify the model directly.
| Property | Description |
|---|---|
| BackgroundColor | Dialog's background color as a Long Integer. |
| Closeable | If True, the dialog is closeable. |
| Enabled | If True, the dialog is enabled. |
| FontDescriptor | Structure that defines and describes the font for the text in the dialog's caption bar. |
| FontEmphasisMark | Constant that defines the type/position of the emphasis mark for text in dialog's caption bar. |
| FontRelief | Constant that specifies if the dialog's caption bar contains embossed or engraved text. |
| HelpText | Dialog's help text as a String. |
| HelpURL | Dialog's help URL as a String. |
| Moveable | If True, the dialog is moveable. |
| Sizeable | If True, the dialog is sizeable. |
| TextColor | Dialog's text color as a Long Integer. |
| TextLineColor | Dialog's text line color as a Long Integer. |
| Title | Text string displayed in the dialog's caption bar. |
Controls that can be inserted into an UNO control dialog support the properties defined by the UnoControlDialogElement service (see Table 10 ).
| Property | Description |
|---|---|
| Height | Control's height. |
| Name | Control's name. |
| PositionX | Control's horizontal position. |
| PositionY | Control's vertical position. |
| Step | Control's step. |
| TabIndex | Control's tab index. |
| Tag | Control's tag. |
| Width | Control's width. |
It is possible to create controls and dialogs by using a macro rather than designing them in the Basic IDE. The dialog's model supports the createlnstance() method defined by the com.sun.star.lang.XMultiServiceFactory interface. When a macro creates a control to be inserted into a dialog, that control should be created by the dialog's model. A control that is created from the global service manager will not have the properties shown in Table 10. Creating controls by using a macro is an advanced topic that is discussed later in this chapter. The macro in Listing 4 shows the objects that a dialog model can create (see Figure 6 ).
Figure 6: Services that the dialog model can create.
 |
Dim x x = oHelloDlg.getModel().getAvailableServiceNames() MsgBox Join(x, CHR$(10))
| |
EAN: 2147483647
Pages: 203