AMLibO no6

LibreOffe RefCard Return Values Constants

com.sun.star.ui.dialogs.ExecutableDialogResults.XXX
LibreOfice BASIC CANCEL 0 Canceled OK 1 Validated
The FolderPicker Object (Or OfficeFolderPicker Or SystemFolderPicker)
Dialogs oFldrPicker = CreateUnoService("com.sun.star.ui.dialogs.FolderPicker")
Description Help text to display on the dialog. Does nothing on an
Advanfed OfficeFolderPicker.
v. 1.05 – 12/02/2018 DisplayDirectory Starting directory.
Execute Transfers the execution stream to the dialog and reads the return
Writen using LibreOffe v. 5.3.3 – Platform : All code (see return code constants above).
Title Dialog title.
Directory User’s selection.
Dialogs In BASIC
Opening A Unique File (FilePicker)
Displaying A Simple Message 1. Create a FilePicker. The default type usually fits (FILEOPEN_SIMPLE),
Print "Hello World!"
2. set its properties and methods (see above),
☞ The Cancel choice stops the program.
3. execute,
4. read the return values in theCurrentFilter, DisplayDirectory and Files (vector)
Displaying Information properties (Files(0) only has a value).
MsgBox(MessageText[, Dialog Code[, Title]])
☞ Line breaks in MessageText with Chr(10) or Chr(13). Dim oFilePicker As Object, FileName As String
FileName = ""
Display A Message And Wait For A Response 'FilePicker initialization
Response = MsgBox(MessageText[, DialogCode[, oFilePicker = CreateUnoService("com.sun.star.ui.dialogs.FilePicker")
Title]]) oFilePicker.DisplayDirectory = ConvertToURL("C:\Path\To\SomeDir")
where oFilePicker.appendFilter("Calc Documents", "*.ods")
oFilePicker.CurrentFilter = "Calc Documents"
• Response is an integer value that reflects the user’s choice. oFilePicker.Title = "Select a Calc document"
• DialogCode : the sum of button codes + icon + default button (as below). 'execution and return check (OK?)
If oFilePicker.execute = _
Buttons to display
com.sun.star.ui.dialogs.ExecutableDialogResults.OK Then
0 OK 3 Yes, No, Cancel FileName = oFilePicker.Files(0)
1 OK, Cancel 4 Yes, No End If
2 Stop, Retry, Ignore 5 Retry, Cancel
Opening Several Files (FilePicker)
Icon
1. As above,
0 (none) 48  Caution
2. set its properties and methods (esp. with MultiSelectionMode = True),
16  Critical message 64 i Information (OK only)
3. execute,
32  Question
4. read the Files() vector that holds the user’s choices.
Default button
Saving A File (FilePicker)
0 First 256 Second 512 Last
1. Create a FilePicker,
Return values (user’s selection)
2. set its properties and methods (type FILESAVE_XXX) (see above),
1 OK 3 Stop 5 Ignore 7 No 3. execute,
2 Cancel 4 Retry 6 Yes 4. read the return values in theCurrentFilter, DisplayDirectory and Files (vector)
InputBox() Function properties (Files(0) alone holds a value).
Function InputBox(Message[, Title[, DefaultValue]]) Selecting A Directory (FolderPicker)
returns a string. On cancellation, returns a zero-length string. 1. Create a FolderPicker,
API Dialogs 2. set its properties and methods (see above),
3. execute,
☞ The aspect of FilePicker and FolderPicker types below depend upon
Tools > Options > LibreOffice > General, Use LibreOffice dialogs 4. read the return value in Directory.
API Dialog Types Dim oFP As Object, DirName As String
DirName = ""
File Selection: FilePicker Objects oFP = CreateUnoService("com.sun.star.ui.dialogs.FolderPicker")
com.sun.star.ui.dialogs.FilePicker From above configuration option. oFP.DisplayDirectory = ConvertToURL("C:\Path\To\SomeDir")
com.sun.star.ui.dialogs.OfficeFilePicker Forces LibreOffice style. oFP.Description = "Select a directory"
com.sun.star.ui.dialogs.SystemFilePicker Forces native OS style. oFP.Title = "Select the backup directory"
If oFP.execute = _
Directory Selection: FolderPicker Objects com.sun.star.ui.dialogs.ExecutableDialogResults.OK Then
com.sun.star.ui.dialogs.FolderPicker From above configuration option. DirName = oFP.Directory
com.sun.star.ui.dialogs.OfficeFolderPicker Forces LibreOffice style. End If
com.sun.star.ui.dialogs.SystemFolderPicker Forces native OS style.
The FilePicker Object (or OfficeFilePicker Or SystemFilePicker) Custom Dialogs 101
oFilePicker = CreateUnoService("com.sun.star.ui.dialogs.FilePicker") A BASIC dialog = a dialog module (drawing) + (at least) one code module.
AppendFilter() By pairs: appendFilter("LiteralName", "*.xyz")
Dialog Execution Sequence
Ex : oFilePicker.appendFilter("ODF Documents", _
"*.odt;*.ods")
CurrentFilter Sets the default filter from the ones added using AppendFilter
(literal name) or the user’s filter selection.
DefaultName Default name for the file to save.
DisplayDirectory The starting directory or the user’s directory selection.
Execute Transfers the execution stream to the dialog and reads the return
code (see return constants values below).
Files An array of selected files.
initialize() Dialog type selection (see type constants below).
Dim FPType(0) As Integer
FPType(0) = 'a type constant
oFilePicker.initialize(FPType())
MultiSelectionMode Disables/Enables the multi-selection mode (defaults to False).
Title The dialog window title.
FilePicker Type Constants
com.sun.star.ui.dialogs.TemplateDescription.XXX :
FILEOPEN_SIMPLE 0 Simple open file dialog.
FILESAVE_SIMPLE 1 Simple save file dialog.
FILESAVE_AUTOEXTENSION_PASSWORD 2 Enhanced save dialog: automatic extension
+ password.
FILESAVE_AUTOEXTENSION_PASSWORD_FI 3 Enhanced save dialog: automatic extension
LTEROPTIONS + password + filter options.
FILESAVE_AUTOEXTENSION_SELECTION 4 Enhanced save dialog: automatic extension
+ selection.
FILESAVE_AUTOEXTENSION_TEMPLATE 5 Enhanced save dialog: automatic extension
+ templates.
FILEOPEN_LINK_PREVIEW_IMAGE_TEMPLA 6 Enhanced open dialog: insert as link +
TE preview + template. The figure above illustrates a typical dialog execution sequence:
FILEOPEN_PLAY 7 Enhanced open dialog: play. 1. As a response to an application event, you create the dialog,
FILEOPEN_READONLY_VERSION 8 Enhanced open dialog: read-only + version. 2. (initialize dialog controls from the application context if necessary),
FILEOPEN_LINK_PREVIEW 9 Enhanced open dialog: link + preview. 3. run the dialog that receives the execution flow:
FILESAVE_AUTOEXTENSION 10 Enhanced save dialog: automatic extension 4. display,
FILEOPEN_PREVIEW 11 Enhanced open dialog: preview. 5. (dialog controls events management),
FILEOPEN_LINK_PLAY 12 Enhanced open dialog: insert as link + play. 6. some events imply the dialog close (OK, Cancel) ;
7. (finalize to the application context if necessary),
8. the dialog is destroyed and the flow returns to the calling application.
LibOBasic_6_Dialogs_Flat_A4_EN_v105.odt
☞ Creation, initialization, execution, finalization and destruction: processed in your code.
Sub OnBtnOKClick(ByRef pEvt As Object)
Display, closing: automatic operations that follow the latter. 'Response to a click on a OK button on the non-modal dialog
 Think to the responses to control events (“Associating an event to a macro” and Ref-
Card #4). 'set the appropriate actions
'then end with:
Loading Dialog Libraries gShowMe = False '=> the ShowNonModalDialog while loop ends
☞ Much code or several dialogues? You may want to store them in dedicated libraries. 'thus the dialog closes
End Sub 'OnBtnOKClick
 Dialog libraries are never automatically loaded.
 Loading libraries: beware to the typecase!
Associating An Event To A Macro
Modal Vs Non-modal
A dialog communicates with the application through events ( on the figure). You thus
Modal A modal dialog takes full control upon the keyboard, mouse and screen, have to write macros to respond to events occurrences. Extract from RefCard #4:
waiting for some action from the user. The underlying application is then not
1. Create the macro to call, according to this template:
accessible. Sub MacroName()
☞ By default, dialogues are modal. End Sub
Non-modal A non-modal dialog doesn’t block access to the application.  Hint: name the macro from the object and event type.
Ex : the LibreOffice Search & replace dialogue. Example : Sub OnOKButtonClick()
 Multiple calls to a non-modal dialog may block the application. That Sub may get a parameter. See below “Getting Information”,
Standard Custom Dialogs (modal) 2. select the object that carries the event to intercept,
3. go to its settings (differs according to the object),
This is the most frequent use. 4. select the event to intercept,
Given a dialog module MyDlg and a code module MyDlgCode in a MyDlgLib library. In a 5. point to the macro that should be run when the event fires (point 1).
code module Sub, we instantiate a dialog object (oDlg) from the dialog. ☞ More information about events in RefCard #4.
Creating / Loading In Memory Getting Information About The Triggered Event
DialogLibraries.loadLibrary("MyDlgLib") The event management macro can read the input parameter to get more information
oLib = DialogLibraries.getByName("MyDlgLib") about the event itself:
oModule = oLib.getByName("MyDlg") Sub EventResponse(ByRef Event As Object)
oDlg = CreateUnoDialog(oModule) End Sub
'on now manipulate the oDlg object The Event input object properties and methods depend from the type of event that trig-
gered the macro call.
Calling The Dialog
Most Frequent Cases For Controls
oDlg.execute ☞ The execution flow is transferred to the dialog.
To gain access to the calling… Interrogate
Calling And Testing The Return Value Calling control object Event.Source
If oDlg.execute = com.sun.star.ui.dialogs.ExecutableDialogResults.OK Control model object Event.Source.Model
Then … Dialog object that owns the control Event.Source.Context
☞ The execution flow is transferred to the dialog and the return value is checked (did the
user select OK?). Initialization And Finalization
Terminating / Destroying The Dialog Initialization
oDlg.dispose
( in the figure) A dialog often requires information from the execution context. The initial-
Wrap-up Example (Code Module) ization macro configures the dialogue contents from this data.
This example doesn’t show any event management. Finalization
Sub ShowDialog() ( in the figure) Here, we have the opposite process: setting context data from what was
input in the dialogue.
Dim oLib As Object, oModule As Object, oDlg As Object
Managing Dialog Modules
DialogLibraries.loadLibrary("MyDlgLib")
oLib = DialogLibraries.getByName("MyDlgLib") LibreOffice manages dialog modules independently from code (see RefCard #1). We may
oModule = oLib.getByName("MyDlg") copy such modules from a document to another.
oDlg = CreateUnoDialog(oModule)
'InitializeDlg() 'code to initialize the dialog contents Copying Modules From A Library To Another
If oDlg.execute = com.sun.star.ui.dialogs.ExecutableDialogResults.OK (within the same document or between documents/containers)
Then
'FinalizeDlg() 'code to do something with the user's input 1. In the IDE, open both source and target documents/containers,
End If 2. open the Macro organizer ( button),
oDlg.dispose 3. go to the Dialogs tab, drag/drop from the source to the target.
End Sub
☞ By default, modules are moved. To copy: Ctrl + drag/drop.
Saving A Dialog (Drawing Alone)
Non-modal Custom Dialogs
1. In the IDE, open the dialog module to save,
Given a dialog module MyNMDlg and a code module MyNMDlgCode in MyNMDlgLib library. 2. click the toolbar button Export Dialog,
In a Sub of the code module, we instantiate an object (oDlg) from the dialog. 3. name the file and save it.
Apply the same technique as above, with some subtleties: The document is in XML format with an .xdl extension.
1. The dialog display is ensured using oDlg.SetVisible(True) instead of ☞ Import is the reciprocal process, using the Import Dialog button.
oDlg.execute,
2. we set two global Boolean flags:
• gRunning that prevents multiple executions,
• gShowMe that controls the dialog display,
3. events responses (controls) must set gShowMe to False to close the dialog.
Displaying The Dialog
oDlg.SetVisible(True) ☞ The dialog is displayed.
The execution flow is not transferred to the dialog.
Wrap-up Example (Code Module)
Dim gShowMe As Boolean 'dialog display flag.
Dim gRunning As Boolean 'execution flag to prevent multiple runs.

Sub ShowNonModalDialog()
'manages the dialog creation and display

Dim oLib As Object, oModule As Object, oDlg As Object Credits

Author: Jean-François Nifenecker – [email protected]
'check for multiple runs We are like dwarves perched on the shoulders of giants, and thus we are able to see more and farther than the
If Not gRunning Then latter. And this is not at all because of the acuteness of our sight or the stature of our body, but because we are
gRunning = True carried aloft and elevated by the magnitude of the giants. (Bernard of Chartres [attr.])
gShowMe = True
DialogLibraries.loadLibrary("MyNMDlgLib") History
oLib = DialogLibraries.getByName("MyNMDlgLib") Version Date Comments
oModule = oLib.getByName("MyNMDlg")
oDlg = CreateUnoDialog(oModule) 1.05 02/12/2018 Minor updates.
'InitializeDlg() 'code to initialize the dialog contents
'display the dialog as long as the flag is True
Do While gShowMe
Wait 20 'allow other software execution
oDlg.SetVisible(True) 'keep on screen
Loop
'if we are here, the dialog was closed (see OnBtnOKClick)
'FinalizeDlg() 'code to do something with the user's input
oDlg.dispose
gRunning = False
End If License
End Sub ' ShowNonModalDialog This RefCard is distributed under the
CreativeCommons BY-SA v3 license
Information
https://creativecommons.org/licenses/by-sa/3.0/fr/