From 605791780909d8dd5e4c36663def5c0c9c3bbdb0 Mon Sep 17 00:00:00 2001 From: Alain Romedenne Date: Wed, 28 Apr 2021 15:48:34 +0200 Subject: sf_Dialog(Control) Python support - part 1/2 Change-Id: I204a78557c607708870a51699af140e13ff2c0e4 Reviewed-on: https://gerrit.libreoffice.org/c/help/+/114724 Tested-by: Jenkins Tested-by: Jean-Pierre Ledure Reviewed-by: Jean-Pierre Ledure --- source/text/sbasic/shared/03/sf_dialog.xhp | 142 +++++++++++++++++++---------- 1 file changed, 93 insertions(+), 49 deletions(-) diff --git a/source/text/sbasic/shared/03/sf_dialog.xhp b/source/text/sbasic/shared/03/sf_dialog.xhp index 026c6d28f8..3c1ad74832 100644 --- a/source/text/sbasic/shared/03/sf_dialog.xhp +++ b/source/text/sbasic/shared/03/sf_dialog.xhp @@ -26,18 +26,20 @@ A dialog box can be displayed in modal or in non-modal modes. In modal mode, the box is displayed and the execution of the macro process is suspended until one of the OK or Cancel buttons is pressed. In the meantime, user actions executed on the box can trigger specific actions. - In non-modal mode, the dialog box is "floating" on the user desktop and the execution of the macro process continues normally. Regardless of its status, the dialog closes when the macro that displayed it finishes running. + In non-modal mode, the dialog box is "floating" on the user desktop and the execution of the macro process continues normally. A non-modal dialog closes when it is terminated with the Terminate() method or when the %PRODUCTNAME session ends. The window close button is inactive in non-modal dialogs. A dialog box disappears from memory after its explicit termination. The SFDialogs.Dialog service is closely related to the SFDialogs.DialogControl service. +

Service invocation and usage

- The Dialog service is invoked through the CreateScriptService method. It requires three arguments to specify the dialog box to activate: + The Dialog service is invoked through the CreateScriptService method. It requires three positional arguments to specify the dialog box to activate: Container: "GlobalScope" for preinstalled libraries or a window name as defined by ScriptForge.UI service. Empty string "" default value stands for the current document. Library: The case-sensitive name of a library contained in the container. Default value is "Standard". DialogName: A case-sensitive string designating the dialog. + Below %PRODUCTNAME Basic and Python examples are displaying the dlgConsole dialog that belongs to ScriptForge shared library: Dim oDlg As Object, lButton As Long Dim Container As String, Library As String, DialogName As String - Set oDlg = CreateScriptService("SFDialogs.Dialog", Container, Library, DialogName) + Set oDlg = CreateScriptService("SFDialogs.Dialog", "GlobalScope", "ScriptForge", "dlgConsole") '... controls initialization goes here... lButton = oDlg.Execute() 'Default mode = Modal @@ -45,17 +47,31 @@ '... Process controls and do what is needed here End If oDlg.Terminate() - - Alternatively a Dialog instance can be retrieved via the SFDialogs.DialogEvent service, providing the dialog was initiated with the Dialog service. DialogEvent returns the SFDialogs.Dialog service instance that triggered the event. - - Sub SomeEvent(ByRef poEvent As Object) - Dim oDlg As Object - Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent) - ' oDlg represents now the instance of the Dialog class having triggered the current event - ' ... - End Sub - - Note that in previous examples, the prefix "SFDialogs." may be omitted. + + Or using Python: + + dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', 'ScriptForge', 'dlgConsole') + # ... controls initialization goes here... + rc = dlg.Execute() + # Default mode is Modal + if rc == dlg.OKBUTTON: + # ... Process controls and do what is needed here + dlg.Terminate() + + + Alternatively a Dialog instance can be retrieved via the SFDialogs.DialogEvent service, providing that the dialog was initiated with the Dialog service. DialogEvent returns the SFDialogs.Dialog service instance that triggered the event. + + Sub SomeEvent(ByRef poEvent As Object) + Dim oDlg As Object + Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent) + End Sub + + with Python: + + def some_event(event: uno): + dlg = CreateScriptService("SFDialogs.DialogEvent", event) + + Note that in previous examples, the prefix "SFDialogs." may be omitted when deemed appropriate.

Properties

@@ -234,7 +250,6 @@
-

Event properties

Returns a URI string with the reference to the script triggered by the event. Read its specification in the scripting framework URI specification. @@ -390,18 +405,22 @@ Set the focus on the current Dialog instance. Return True if focusing was successful. This method is called from a dialog or control event, or when a dialog is displayed in non-modal mode.

- - oDlg.Activate() As Boolean - + svc.Activate(): bool

Dim oDlg As Object Set oDlg = CreateScriptService(,, "myDialog") - ' Dialog stored in current document's standard library - oDlg.Execute(Modal := False) + oDlg.Execute() ' ... oDlg.Activate() + Python and %PRODUCTNAME Basic examples both assume that the dialog is stored in current document's Standard library. + + dlg = CreateScriptService(,,'myDialog') + dlg.Execute() + # ... + dlg.Activate() +
Controls -------------------------------------------------------------------------------------------------------------------------- @@ -412,16 +431,15 @@ Return either: - the list of the controls contained in the dialog + the list of the controls contained in the dialog - a dialog control class instance based on its name + a DialogControl class instance based on its name

- - oDlg.Controls([ControlName As String]) As Variant - + svc.Controls(): str[0..*] + svc.Controls(controlname: str): svc

ControlName : A valid control name as a case-sensitive string. If absent, the list of control names is returned as a zero-based array.

@@ -431,6 +449,11 @@ myList = myDialog.Controls() Set myControl = myDialog.Controls("myTextBox") + + dlg = CreateScriptService('SFDialogs.Dialog','', 'Standard', 'Dialog1') + ctrls = dlg.Controls() + ctrl = dlg.Controls('myTextBox') +
EndExecute -------------------------------------------------------------------------------------------------------------------------- @@ -439,21 +462,28 @@

EndExecute

Ends the display of a modal dialog and gives back the argument as return value for the current Execute() running action. - EndExecute() is usually contained in the processing of a macro triggered by a dialog or control event. + EndExecute() is usually contained in the processing of a macro triggered by a dialog or control event.

- - oDlg.EndExecute(ReturnValue As Long) - + svc.EndExecute(returnvalue: int)

- ReturnValue : The value passed to the running Execute() method. + returnvalue: The value passed to the running Execute() method.

+ Using %PRODUCTNAME Basic: - Sub OnEvent(poEvent As Variant) + Sub OnEvent(poEvent As com.sun.star.lang.EventObject) Dim oDlg As Object Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent) oDlg.EndExecute(ReturnValue := 25) End Sub + Using Python: + + from com.sun.star.lang import EventObject + def on_event(event: EventObject): + dlg = CreateScriptService("SFDialogs.DialogEvent", event) + dlg.EndExecute(25) + + Above com.sun.star.lang.EventObject mentions are optional. Such annotations help identify %PRODUCTNAME Application Programming Interface (API).
Execute -------------------------------------------------------------------------------------------------------------------------- @@ -463,32 +493,37 @@ Display the dialog box and, when modal, wait for its termination by the user. The returned value is either: - 0 : Cancel button pressed + 0 : Cancel button pressed - 1 : OK button pressed + 1 : OK button pressed - Otherwise the dialog stopped with an EndExecute() statement issued by a dialog or control event + Otherwise the dialog stopped with an EndExecute() statement issued by a dialog or control event For non-modal dialog boxes the method always returns 0 and the execution of the macro continues.

- - oDlg.Execute([Modal As Boolean]) As Long - + svc.Execute(modal: bool = True): int

- Modal : False when non-modal dialog. Default = True. + modal: False when non-modal dialog. Default = True.

+ In this Basic example myDialog dialog is stored in current document's Standard library. Dim oDlg As Object, lReturn As Long - Set oDlg = CreateScriptService(("SFDialogs.Dialog", , , "myDialog") - ' Dialog stored in current document's standard library - lReturn = oDlg.Execute() + Set oDlg = CreateScriptService("SFDialogs.Dialog", , , "myDialog") + lReturn = oDlg.Execute(Modal := False) Select Case lReturn - ' ... + ' ... End Select + This Python code displays DlgConvert modal dialog from Euro shared Basic library. + + dlg = CreateScriptService("SFDialogs.Dialog", 'GlobalScope', 'Euro', "DlgConvert") + rc = dlg.Execute() + if rc == dlg.CANCELBUTTON: + # ... +
Terminate -------------------------------------------------------------------------------------------------------------------------- @@ -498,20 +533,29 @@

Terminate

Terminate the Dialog service for the current instance. Return True if the termination was successful.

- - oDlg.Terminate() As Boolean - + svc.Terminate(): bool

+ Below Basic and Python examples open DlgConsole and dlgTrace non-modal dialogs. They are respectively stored in ScriptForge and Access2Base shared libraries. Dialog close buttons are disabled and explicit termination is performed at the end of a running process. + In this example a button in DlgConsole is substituting inhibited window closing: - oDlg.Terminate() + oDlg = CreateScriptService("SFDialogs.Dialog","GlobalScope","ScriptForge","DlgConsole") + oDlg.Execute(modal:=False) + Wait 5000 + oDlg.Terminate() + With Python: + + from time import sleep + dlg = CreateScriptService('SFDialogs.Dialog',"GlobalScope",'Access2Base',"dlgTrace") + dlg.Execute(modal=False) + sleep 5 + dlg.Terminate() +
- -
- + \ No newline at end of file -- cgit