Difference between revisions of "Documentation/BASIC Guide/Working With Dialogs"
m |
|||
(14 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
− | |||
{{Documentation/BASICGuideTOC/v2 | {{Documentation/BASICGuideTOC/v2 | ||
|ShowPrevNext=block | |ShowPrevNext=block | ||
Line 7: | Line 6: | ||
|dial=block | |dial=block | ||
}} | }} | ||
− | {{ | + | {{DISPLAYTITLE:Working With Dialogs}} |
+ | __NOTOC__ | ||
+ | {{AOo}} Basic dialogs consist of a dialog window that can contain text fields, list boxes, radio buttons, and other control elements. | ||
== Creating Dialogs == | == Creating Dialogs == | ||
− | You can create and structure dialogs using the {{ | + | You can create and structure dialogs using the {{AOo}} dialog editor: |
[[Image:documentation_basicguide_dlg_01.gif|none|thumb|500px|Create and structure dialogs in the dialog editor]] | [[Image:documentation_basicguide_dlg_01.gif|none|thumb|500px|Create and structure dialogs in the dialog editor]] | ||
Line 23: | Line 24: | ||
You can open a dialog with the following code: | You can open a dialog with the following code: | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Dim Dlg As Object | Dim Dlg As Object | ||
Line 30: | Line 31: | ||
Dlg.Execute() | Dlg.Execute() | ||
Dlg.dispose() | Dlg.dispose() | ||
− | </ | + | </syntaxhighlight> |
<tt>CreateUnoDialog</tt> creates an object called <tt>Dlg</tt> that references the associated dialog. Before you can create the dialog, you must ensure that the library it uses (in this example, the <tt>Standard</tt> library) is loaded. The <tt>LoadLibrary</tt> method performs this task. | <tt>CreateUnoDialog</tt> creates an object called <tt>Dlg</tt> that references the associated dialog. Before you can create the dialog, you must ensure that the library it uses (in this example, the <tt>Standard</tt> library) is loaded. The <tt>LoadLibrary</tt> method performs this task. | ||
Line 36: | Line 37: | ||
Once the <tt>Dlg</tt> dialog object has been initialized, you can use the <tt>Execute</tt> 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 <tt>Execute</tt> call. | Once the <tt>Dlg</tt> dialog object has been initialized, you can use the <tt>Execute</tt> 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 <tt>Execute</tt> call. | ||
− | The <tt>dispose</tt> method at the end of the code | + | The <tt>dispose</tt> method at the end of the code releases the resources used by the dialog once the program ends. |
== Closing Dialogs == | == Closing Dialogs == | ||
Line 42: | Line 43: | ||
=== Closing With OK or Cancel === | === Closing With OK or Cancel === | ||
− | If a dialog contains an '''OK''' or a '''Cancel''' button, the dialog is automatically closed when you click one of these buttons. More information about working with these buttons | + | If a dialog contains an '''OK''' or a '''Cancel''' button, the dialog is automatically closed when you click one of these buttons. More information about working with these buttons is discussed in [[Documentation/BASIC Guide/Control Elements|Dialog Control Elements in Detail]]. |
− | If you close a dialog by clicking the '''OK''' button, the <tt>Execute | + | If you close a dialog by clicking the '''OK''' button, the <tt>Execute</tt> method returns a return value of 1, otherwise a value of 0 is returned. |
− | < | + | <syntaxhighlight lang="oobas"> |
Dim Dlg As Object | Dim Dlg As Object | ||
Line 57: | Line 58: | ||
MsgBox "Cancel pressed" | MsgBox "Cancel pressed" | ||
End Select | End Select | ||
− | </ | + | </syntaxhighlight> |
=== Closing With the Close Button in the Title Bar === | === Closing With the Close Button in the Title Bar === | ||
Line 65: | Line 66: | ||
=== Closing With an Explicit Program Call === | === Closing With an Explicit Program Call === | ||
− | + | From a routine called by an event of a control, e.g. push of a normal button, you can also close an open dialog window with the <tt>endExecute</tt> method: | |
− | < | + | <syntaxhighlight lang="oobas"> |
Dlg.endExecute() | Dlg.endExecute() | ||
− | </ | + | </syntaxhighlight> |
+ | The dialog object must be accessible from the event routine. A simple way is to declare it as a <tt>Private</tt> or <tt>Public</tt> variable common to the main dialog routine and the event routine. | ||
+ | |||
+ | The <tt>execute</tt> method of the dialog returns the value 0, which is the same as when you click Cancel. | ||
+ | |||
+ | |||
+ | The <tt>endDialog</tt> method of the dialog is an improvement of <tt>endExecute</tt>. Its argument specifies the value that will be returned by <tt>execute</tt> method. | ||
+ | |||
+ | <syntaxhighlight lang="oobas"> | ||
+ | Dlg.endDialog(2) ' Dlg.execute will return 2 | ||
+ | </syntaxhighlight> | ||
== Access to Individual Control Elements == | == Access to Individual Control Elements == | ||
− | A dialog can contain any number of control elements. You can access these elements through the <tt>getControl</tt> method that returns | + | A dialog can contain any number of control elements. You can access these elements through the <tt>getControl</tt> method that returns the control element by name. |
− | < | + | <syntaxhighlight lang="oobas"> |
Dim Ctl As Object | Dim Ctl As Object | ||
Ctl = Dlg.getControl("MyButton") | Ctl = Dlg.getControl("MyButton") | ||
Ctl.Label = "New Label" | Ctl.Label = "New Label" | ||
− | </ | + | </syntaxhighlight> |
− | This code determines the object for the <tt>MyButton</tt> control element and then initializes the <tt>Ctl</tt> object variable with a reference to the element. Finally the code sets the <tt>Label</tt> property of the control element to the <tt>New Label</tt> value. | + | This code determines the object for the <tt>MyButton</tt> control element and then initializes the <tt>Ctl</tt> object variable with a reference to the element. Finally, the code sets the <tt>Label</tt> property of the control element to the <tt>New Label</tt> value. |
− | {{ | + | {{Note|Unlike {{AOo}} Basic identifiers, the names of control elements are case-sensitive.}} |
== Working With the Model of Dialogs and Control Elements == | == Working With the Model of Dialogs and Control Elements == | ||
− | The division between visible program elements ('''View''') and the data or documents behind them ('''Model''') occurs at many places in {{ | + | The division between visible program elements ('''View''') and the data or documents behind them ('''Model''') occurs at many places in {{AOo}} API. In addition to the methods and properties of control elements, both dialog and control element objects have a subordinate <tt>Model</tt> 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 {{ | + | In dialogs, the distinction between data and depiction is not always as clear as in other API areas of {{AOo}}. Elements of the API are available through both the View and the Model. |
The <tt>Model</tt> property provides program-controlled access to the model of dialog and control element objects. | The <tt>Model</tt> property provides program-controlled access to the model of dialog and control element objects. | ||
− | < | + | <syntaxhighlight lang="oobas"> |
Dim cmdNext As Object | Dim cmdNext As Object | ||
cmdNext = Dlg.getControl("cmdNext") | cmdNext = Dlg.getControl("cmdNext") | ||
cmdNext.Model.Enabled = False | cmdNext.Model.Enabled = False | ||
− | </ | + | </syntaxhighlight> |
− | This example deactivates the <tt> | + | This example deactivates the <tt>cmdNext</tt> button in the <tt>Dlg</tt> dialog with the aid of the model object from <tt>cmdNext</tt>. |
+ | {{InterWiki Languages BasicGuide|articletitle=Documentation/BASIC Guide/Working With Dialogs}} | ||
{{PDL1}} | {{PDL1}} |
Latest revision as of 14:09, 30 January 2021
< {{#switch:Previous Page | Previous Section = Previous Section | Next Section = Next Section | Previous Page = Previous Page | Next Page = Next Page | }} | {{#switch:Next Page | Previous Section = Previous Section | Next Section = Next Section | Previous Page = Previous Page | Next Page = Next Page | }} > |
Apache OpenOffice Basic dialogs consist of a dialog window that can contain text fields, list boxes, radio buttons, and other control elements.
Creating Dialogs
You can create and structure dialogs using the Apache OpenOffice dialog editor:
You can drag the control elements from the design pallet (right) into the dialog area, and 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. 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 releases the resources used by the dialog once the program ends.
Closing Dialogs
Closing With OK or Cancel
If a dialog contains an OK or a Cancel button, the dialog is automatically closed when you click one of these buttons. More information about working with these buttons is discussed in Dialog Control Elements in Detail.
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 Bar
You can close a dialog by clicking the close button on the title bar of the dialog window. The Execute method of the dialog returns the value 0, which is the same as when you click Cancel.
Closing With an Explicit Program Call
From a routine called by an event of a control, e.g. push of a normal button, you can also close an open dialog window with the endExecute method:
Dlg.endExecute()
The dialog object must be accessible from the event routine. A simple way is to declare it as a Private or Public variable common to the main dialog routine and the event routine.
The execute method of the dialog returns the value 0, which is the same as when you click Cancel.
The endDialog method of the dialog is an improvement of endExecute. Its argument specifies the value that will be returned by execute method.
Dlg.endDialog(2) ' Dlg.execute will return 2
Access to Individual Control Elements
A dialog can contain any number of control elements. You can access these elements through the getControl method that returns the control element by name.
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.
Working With the Model of Dialogs and Control Elements
The division between visible program elements (View) and the data or documents behind them (Model) occurs at many places in Apache OpenOffice 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 Apache OpenOffice. 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 cmdNext button in the Dlg dialog with the aid of the model object from cmdNext.
Content on this page is licensed under the Public Documentation License (PDL). |