Contidos dentroLocalizar Mais DocumentaçãoDestaques de Recursos de Suporte |  Fazer download desta apostila em PDF (1223 KB)
Chapter 11 DialogsYou can add custom dialog windows and forms to StarOffice documents. These in turn can be linked to StarOffice Basic macros to considerably extend the usage range of StarOffice Basic. Dialogs can, for example, display database information or guide users through a step-by-step process of creating a new document in the form of an AutoPilot. Working With DialogsStarOffice Basic dialogs consist of a dialog window that can contain text fields, list boxes, radio buttons, and other control elements. Creating DialogsYou can create and structure dialogs using the StarOffice dialog editor that you can use in the same way as a StarOffice Draw:  Essentially, you drag the control elements that you want from the design pallet (right) into the dialog area where you can define their position and size. The example shows a dialog that contains a label and a list box.  You can open a dialog with the following code: Dim Dlg As Object
DialogLibraries.LoadLibrary("Standard")
Dlg = CreateUnoDialog(DialogLibraries.Standard.DlgDef)
Dlg.Execute()
Dlg.dispose()
CreateUnoDialog creates an object called Dlg that references the associated dialog. Before you can create the dialog, you must ensure that the library it uses (in this example, the Standard library) is loaded. If not, the LoadLibrary method performs this task. Once the Dlg dialog object has been initialized, you can use the Execute method to display the dialog. Dialogs such as this one are described as modal because they do not permit any other program action until they are closed. While this dialog is open, the program remains in the Execute call. The dispose method at the end of the code approves the resources used by the dialog once the program ends. Closing DialogsClosing With OK or CancelIf a dialog contains an OK or a Cancel button, the dialog is automatically closed when you press one of these buttons. More information about working with these buttons are discussed in this Dialog Control Elements in Detail section of this chapter. If you close a dialog by clicking the OK button, the Execute-method returns a return value of 1, otherwise a value of 0 is returned. Dim Dlg As Object
DialogLibraries.LoadLibrary("Standard")
Dlg = CreateUnoDialog(DialogLibraries.Standard.MyDialog)
Select Case Dlg.Execute()
Case 1
MsgBox "Ok pressed"
Case 0
MsgBox "Cancel pressed"
End Select
Closing With the Close Button in the Title BarIf you want, you can close a dialog by clicking the close button on the title bar of the dialog window. In this instance, the Execute method of the dialog returns the value 0, the same as when you press the Cancel button. Closing With an Explicit Program CallYou can also close an open dialog window with the endExecute method: Dlg.endExecute() Access to Individual Control ElementsA dialog can contain any number of control elements. You can access these elements through the getControl method that returns the name of the control element. Dim Ctl As Object
Ctl = Dlg.getControl("MyButton")
Ctl.Label = "New Label"
This code determines the object for the MyButton control element and then initializes the Ctl object variable with a reference to the element. Finally the code sets the Label property of the control element to the New Label value. Note – StarOffice Basic distinguishes between uppercase and lowercase characters for the names of control elements. Working With the Model of Dialogs and Control ElementsThe division between visible program elements (View) and the data or documents behind them (Model) occurs at many places in StarOffice API. In addition to the methods and properties of control elements, both dialog and control element objects have a subordinate Model object. This object allows you to directly access the content of a dialog or control element. In dialogs, the distinction between data and depiction is not always as clear as in other API areas of StarOffice. Elements of the API are available through both the View and the Model. The Model property provides program-controlled access to the model of dialog and control element objects. Dim cmdNext As Object
cmdNext = Dlg.getControl("cmdNext")
cmdNext.Model.Enabled = False
This example deactivates the cmdNtext button in the Dlg dialog with the aid of the model object from cmdNtext. PropertiesName and TitleEvery control element has its own name that can be queried using the following model property:
You can specify the title that appears in the title bar of a dialog with the following model property:
Position and SizeYou can query the size and position of a control element using the following properties of the model object:
To ensure platform independence for the appearance of dialogs, StarOffice uses the Map AppFont (ma) internal unit to specify the position and size within dialogs. An ma unit is defined as being one eighth of the average height of a character from the system font defined in the operating system and one quarter of its width. By using ma units, StarOffice ensures that a dialog looks the same on different systems under different system settings. If you want to change the size or position of control elements for runtime, determine the total size of the dialog and adjust the values for the control elements to the corresponding part ratios. Note – The Map AppFont (ma) replaces the Twips unit to achieve better platform independence. Focus and Tabulator SequenceYou can navigate through the control elements in any dialog by pressing the Tab key. The following properties are available in this context in the control elements model:
Finally, the control element provides a getFocus method that ensures that the underlying control element receives the focus:
Multi-Page DialogsA dialog in StarOffice can have more than one tab page. The Step property of a dialog defines the current tab page of the dialog whereas the Step property for a control element specifies the tab page where the control element is to be displayed. The Step-value of 0 is a special case. If you set this value to zero in a dialog, all of the control elements are visible regardless of their Step value. Similarly, if you set this value to zero for a control element, the element is displayed on all of the tab pages in a dialog.  In the preceding example, you can also assign the Step value of 0 to the dividing line as well as the Cancel, Prev, Next, and Done buttons to display these elements on all pages. You can also assign the elements to an individual tab page (for example page 1). The following program code shows how the Step value in event handlers of the Next and Prev buttons can be increased or reduced and changes the status of the buttons. Sub cmdNext_Initiated
Dim cmdNext As Object
Dim cmdPrev As Object
cmdPrev = Dlg.getControl("cmdPrev")
cmdNext = Dlg.getControl("cmdNext")
cmdPrev.Model.Enabled = Not cmdPrev.Model.Enabled
cmdNext.Model.Enabled = False
Dlg.Model.Step = Dlg.Model.Step + 1
End Sub
Sub cmdPrev_Initiated
Dim cmdNext As Object
Dim cmdPrev As Object
cmdPrev = Dlg.getControl("cmdPrev")
cmdNext = Dlg.getControl("cmdNext")
cmdPrev.Model.Enabled = False
cmdNext.Model.Enabled = True
Dlg.Model.Step = Dlg.Model.Step - 1
End Sub
A global Dlg variable that references an open dialog must be included to make this example possible. The dialog then changes its appearance as follows: Page 1:  Page 2: 
EventsStarOffice dialogs and forms 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, even when the action is another event. You can also edit documents or open databases with event handling as well as access other control elements. StarOffice control elements recognize different types of events that can be triggered in different situations. These event types can be divided into four groups:
When you work with events, ensure that you create the associated dialog in the StarOffice development environment and that it contains the required control elements or documents (if you the events apply to a form). The preceding figure shows the StarOffice Basic development environment with a dialog window that contains two list boxes. You can move the data from one list to the other using the buttons between the two list boxes. If you want to display the layout on screen, then you should create the associated StarOffice Basic procedures so that they can be called up by the event handlers. Even though you can use these procedures in any module, it is best to limit their use to two modules. To make your code easier to read, you should assign meaningful names to these procedures. Jumping directly to a general program procedure from a macro can result in unclear code. Instead, to simplify code maintenance and troubleshooting, you should create another procedure to serve as an entry point for event handling - even if it only executes a single call to the target procedure. The code in the following example moves an entry from the left to the right list box of a dialog. Sub cmdSelect_Initiated
Dim objList As Object
lstEntries = Dlg.getControl("lstEntries")
lstSelection = Dlg.getControl("lstSelection")
If lstEntries.SelectedItem > 0 Then
lstSelection.AddItem(lstEntries.SelectedItem, 0)
lstEntries.removeItems(lstEntries.SelectItemPos, 1)
Else
Beep
End If
End Sub
If this procedure was created in StarOffice Basic, you can assign it to an event required using the property window of the dialog editor.  The assignment dialog lists all of the StarOffice Basic procedures. To assign a procedure to an event, select the procedure, and then click Assign. ParametersThe occurrence of a particular event is not always enough for an appropriate response. Additional information may be required. For example, to process a mouse click, you may need the screen position where the mouse button was pressed. In StarOffice Basic, you can use object parameters to provide more information about an event to a procedure, for example: Sub ProcessEvent(Event As Object) End Sub The accuracy with which the Event object is structured and its properties depend on the type of event that the procedure call triggers. The following sections describe event types in detail. Regardless of the type of event, all objects provide access to the relevant control element and its model. The control element can be reached using Event.Source and its model using Event.Source.Model You can use these properties to trigger an event within an event handler. Mouse EventsStarOffice Basic recognizes the following mouse events:
The structure of the associated event objects is defined in the com.sun.star.awt.MouseEvent structure which provides the following information:
The constants defined in com.sun.star.awt.MouseButton for the mouse buttons are:
The following example outputs the mouse position as well as the mouse button that was pressed: Sub MouseUp(Event As Object)
Dim Msg As String
Msg = "Keys: "
If Event.Buttons AND com.sun.star.awt.MouseButton.LEFT Then
Msg = Msg & "LEFT "
End If
If Event.Buttons AND com.sun.star.awt.MouseButton.RIGHT Then
Msg = Msg & "RIGHT "
End If
If Event.Buttons AND com.sun.star.awt.MouseButton.MIDDLE Then
Msg = Msg & "MIDDLE "
End If
Msg = Msg & Chr(13) & "Position: "
Msg = Msg & Event.X & "/" & Event.Y
MsgBox Msg
End Sub
Note – The VBA Click and Doubleclick events are not available in StarOffice Basic. Instead use the StarOffice Basic MouseUp event for the click event and imitate the Doubleclick event by changing the application logic. Keyboard EventsThe following keyboard events are available in StarOffice Basic:
Both events relate to logical key actions and not to physical actions. If the user presses several keys to output a single character (for example, to add an accent to a character), then StarOffice Basic only creates one event. A single key action on a modification key, such as the Shift key or the Alt key does not create an independent event. Information about a pressed key is provided by the event object that StarOffice Basic supplies to the procedure for event handling. It contains the following properties:
The following example uses the KeyCode property to establish if the Enter key, the Tab key, or one of the other control keys has been pressed. If one of these keys has been pressed, the name of the key is returns, otherwise the character that was typed is returned: Sub KeyPressed(Event As Object)
Dim Msg As String
Select Case Event.KeyCode
Case com.sun.star.awt.Key.RETURN
Msg = "Return pressed"
Case com.sun.star.awt.Key.TAB
Msg = "Tab pressed"
Case com.sun.star.awt.Key.DELETE
Msg = "Delete pressed"
Case com.sun.star.awt.Key.ESCAPE
Msg = "Escape pressed"
Case com.sun.star.awt.Key.DOWN
Msg = "Down pressed"
Case com.sun.star.awt.Key.UP
Msg = "Up pressed"
Case com.sun.star.awt.Key.LEFT
Msg = "Left pressed"
Case com.sun.star.awt.Key.RIGHT
Msg = "Right pressed"
Case Else
Msg = "Character " & Event.KeyChar & " entered"
End Select
MsgBox Msg
End Sub
Information about other keyboard constants can be found in the API Reference under the com.sun.star.awt.Key group of constants. Focus EventsFocus events indicate if a control element receives or loses focus. You can use these events to, for example, determine if a user has finished processing a control element so that you can update other elements of a dialog. The following focus events are available:
The Event objects for the focus events are structured as follows:
Control Element-Specific EventsIn addition to the preceding events, which are supported by all control elements, there are also some control element-specific events that are only defined for certain control elements. The most important of these events are:
When you work with events, note that some events, such as the When initiating event, can be initiated each time you click the mouse on some control elements (for example, on radio buttons). No action is performed to check if the status of the control element has actually changed. To avoid such “blind events”, save the old control element value in a global variable, and then check to see if the value has changed when an event is executing. The properties for the Item Status Changed event are:
Dialog Control Elements in DetailStarOffice Basic recognizes a range of control elements which can be divided into the following groups: Entry fields:
Buttons:
Selection lists:
Other control elements:
The most important of these control elements are presented below. ButtonsA button performs an action when you click it. The simplest scenario is for the button to trigger a When Initiating event when it is clicked by a user. You can also link another action to the button to open a dialog using the PushButtonType property. When you click a button that has this property set to the value of 0, the dialog remains unaffected. If you click a button that has this property set to the value of 1, the dialog is closed, and the Execute method of the dialog returns the value 1 (dialog sequence has been ended correctly). If the PushButtonType has the value of 2, the dialog is closed and the Execute method of the dialog returns the value 0 (dialog closed). The following are all of the properties that are available through the button model:
Option ButtonsThese buttons are generally used in groups and allow you to select from one of several options. When you select an option, all of the other options in the group are deactivated. This ensures that at any one time, only one option button is set. An option button control element provides two properties:
You can also use the following properties from the model of the option buttons:
To combine several option buttons in a group, you must position them one after another in the activation sequence without any gaps (Model.TabIndex property, described as Order in the dialog editor). If the activation sequence is interrupted by another control element, then StarOffice automatically starts with a new control element group that can be activated regardless of the first group of control elements. Note – Unlike VBA, you cannot insert option buttons in a group of control elements in StarOffice Basic. The grouping of control elements in StarOffice Basic is only used to ensure a visual division by drawing a frame around the control elements. CheckboxesCheckboxes are used to record a Yes or No value and depending on the mode, they can adopt two or three states. In addition to the Yes and No states, a check box can have an in-between state if the corresponding Yes or No status has more than one meaning or is unclear. Checkboxes provide the following properties:
The model object of a checkbox provides the following properties:
Text FieldsText fields allow users to type numbers and text. The com.sun.star.awt.UnoControlEdit. service forms the basis for text fields. A text field can contain one or more lines and can be edited or blocked for user entries. Text fields can also be used as special currency and numerical fields as well as screen fields for special tasks. As these control elements are based on the UnoControlEdit Uno service, their program-controlled handling is similar. Text fields provide the following properties:
Furthermore, the following properties are provided through the associated model object:
List BoxesList boxes (com.sun.star.awt.UnoControlListBox service) support the following properties:
List boxes provide the following methods:
The model object of the list boxes provides the following properties:
Note – The VBA option for issuing list entries with a numerical additional value (ItemData) does not exist in StarOffice Basic. If you want to administer a numerical value (for example a database ID) in addition to the natural language text, you must create an auxiliary data field that administers in parallel to the list box. |
|