View source for EN/documentation/basic guide/working with dialogs

<section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Working With Dialogs<noinclude>}}</noinclude><section end=title />{{BreadCrumbL10n}}

{{Documentation/BASICGuideTOC
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=EN/documentation/basic_guide/dialogs
|NextPage=EN/documentation/basic_guide/properties
|dial=block
}}

__NOTOC__

{{OOo}} 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 {{OOo}} dialog editor:

[[Image:documentation_basicguide_dlg_01.gif|none|thumb|500px|Create and structure dialogs in the 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.

[[Image:documentation_basicguide_dlg_04.gif|none|thumb|500px|A dialog containing a label and a list box]]

You can open a dialog with the following code:

<source lang="oobas">
Dim Dlg As Object

DialogLibraries.LoadLibrary("Standard")
Dlg = CreateUnoDialog(DialogLibraries.Standard.DlgDef)
Dlg.Execute()
Dlg.dispose()
</source>

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

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 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 [[Documentation/BASIC Guide/Control Elements|Dialog Control Elements in Detail]].

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.

<source lang="oobas">
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
</source>

=== 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 <tt>Execute</tt> method of the dialog returns the value 0, which is the same as when you click Cancel.

=== Closing With an Explicit Program Call ===

You can also close an open dialog window with the <tt>endExecute</tt> method:

<source lang="oobas">
Dlg.endExecute()
</source>
The Execute method of the dialog returns the value 0, which is the same as when you click Cancel.

== 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 the control element by name.

<source lang="oobas">
Dim Ctl As Object

Ctl = Dlg.getControl("MyButton")
Ctl.Label = "New Label"
</source>

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 {{OOo}} Basic identifiers, the names of control elements are case sensitive.}}

== 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 {{OOo}} 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 {{OOo}}. 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.

<source lang="oobas">
Dim cmdNext As Object

cmdNext = Dlg.getControl("cmdNext")
cmdNext.Model.Enabled = False
</source>

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

{{PDL1}}