From 81700be18fb54265c2866c5be4d5bc75d41aa91d Mon Sep 17 00:00:00 2001 From: Rafael Lima Date: Mon, 12 Dec 2022 17:43:24 +0000 Subject: Update documentation of SF_Dialog and SF_Dialog control services This patch does the following changes: 1) Explain how to handle exceptions in dialog and control event handlers (both in Python and Basic) 2) Document the new SetPageManager method 3) Plus a few minor fixes in the text Change-Id: I4f7b3bfae025b45214b90dd036ecdbf4977d47e9 Reviewed-on: https://gerrit.libreoffice.org/c/help/+/144018 Tested-by: Jenkins Reviewed-by: Jean-Pierre Ledure (cherry picked from commit cd924ae6a0bd8fbaad2ee4bcac7d4ccd7c689a59) Reviewed-on: https://gerrit.libreoffice.org/c/help/+/144311 Tested-by: Jean-Pierre Ledure --- source/text/sbasic/shared/03/sf_dialog.xhp | 98 +++++++++++++++++++++-- source/text/sbasic/shared/03/sf_dialogcontrol.xhp | 51 +++++++++--- 2 files changed, 129 insertions(+), 20 deletions(-) (limited to 'source') diff --git a/source/text/sbasic/shared/03/sf_dialog.xhp b/source/text/sbasic/shared/03/sf_dialog.xhp index b4c34f7725..dcf120daef 100644 --- a/source/text/sbasic/shared/03/sf_dialog.xhp +++ b/source/text/sbasic/shared/03/sf_dialog.xhp @@ -38,7 +38,7 @@ 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: + The examples below in Basic and Python display the dlgConsole dialog that belongs to the ScriptForge shared library: Dim oDlg As Object, lButton As Long Dim Container As String, Library As String, DialogName As String @@ -61,20 +61,49 @@ # ... Process controls and do what is needed here dlg.Terminate() + Use the string "GlobalScope" as the container argument when the dialog is stored either in My Macros & Dialogs or in Application Macros & Dialogs. - 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. +

Retrieving the Dialog instance that triggered a dialog event

+ An instance of the Dialog service can be retrieved via the SFDialogs.DialogEvent service, provided that the dialog was initiated with the Dialog service. In the example below, oDlg contains the Dialog instance that triggered the dialog event. - Sub SomeEvent(ByRef poEvent As Object) + Sub aDialogEventHander(ByRef poEvent As Object) Dim oDlg As Object Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent) + ' ... End Sub - with Python: + Or using Python: - def some_event(event: uno): - dlg = CreateScriptService("SFDialogs.DialogEvent", event) + def control_event_handler(event: uno): + dlg = CreateScriptService("SFDialogs.DialogEvent", event) + # ... + + Note that in the previous examples, the prefix "SFDialogs." may be omitted when deemed appropriate. +

Handling exceptions in event handlers

+ When creating an event handler for dialog events it is good practice to handle errors inside the subroutine itself. For instance, suppose the event handler below is called when the mouse button is pressed in the dialog window. + + Sub OnMouseButtonPressed(ByRef oEvent As Object) + On Local Error GoTo Catch + Dim oDialog As Object + oDialog = CreateScriptService("DialogEvent", oEvent) + ' Process the event + Exit Sub + Catch: + MsgBox SF_Exception.Description + SF_Exception.Clear + End Sub + + Call SF_Exception.Clear if you do not want the error to propagate after the dialog execution ended. + In Python use native try/except blocks for exception handling as shown below: + + def on_mouse_button_pressed(event=None): + try: + dlg = CreateScriptService("DialogEvent", event) + # Process the event + except Exception as e: + # The object "bas" is an instance of the Basic service + bas.MsgBox(str(e)) - Note that in previous examples, the prefix "SFDialogs." may be omitted when deemed appropriate.

Properties

@@ -397,7 +426,8 @@ Resize
- Terminate

+ SetPageManager
+ Terminate
@@ -642,6 +672,58 @@ +
+ SetPageManager --------------------------------------------------------------------------------------- + + Dialog service;SetPageManager + +

SetPageManager

+ Defines which controls in a dialog are responsible for switching pages, making it easier to manage the Page property of a dialog and its controls. + Dialogs may have multiple pages and the currently visible page is defined by the Page dialog property. If the Page property is left unchanged, the default visible page is equal to 0 (zero), meaning that no particular page is defined and all visible controls are displayed regardless of the value set in their own Page property. + When the Page property of a dialog is changed to some other value such as 1, 2, 3 and so forth, then only the controls whose Page property match the current dialog page will be displayed. + By using the SetPageManager method it is possible to define four types of page managers: + + + List box or combo box: in this case, each entry in the list box or combo box corresponds to a page. The first item refers to Page 1, the second items refers to Page 2 and so on. + + + Group of radio buttons: defines a group of radio buttons that will control which page is visible. + + + Sequence of buttons: defines a set of buttons, each of which corresponding to a dialog page. This can be used to emulate a tabbed interface by placing buttons side by side in the dialog. + + + Previous/Next buttons: defines which buttons in the dialog that will be used to navigate to the Previous/Next page in the dialog. + + + It is possible to use more than one page management mechanism at the same time. + This method is supposed to be called just once before calling the Execute method. Subsequent calls are ignored. + If successful this method returns True. + + svc.SetPageManager(pilotcontrols: str = "", tabcontrols: str = "", wizardcontrols: str = "", opt lastpage: int): bool + + pilotcontrols: a comma-separated list of ListBox, ComboBox or RadioButton control names used as page managers. For RadioButton controls, specify the name of the first control in the group to be used. + tabcontrols: a comma-separated list of button names that will be used as page managers. The order in which they are specified in this argument corresponds to the page number they are associated with. + wizardcontrols: a comma-separated list with the names of two buttons that will be used as the Previous/Next buttons. + lastpage: the number of the last available page. It is recommended to specify this value when using the Previous/Next page manager. + + Consider a dialog with three pages. The dialog has a ListBox control named "aPageList" that will be used to control the visible page. Additionally, there are two buttons named "btnPrevious" and "btnNext" that will be used as the Previous/Next buttons in the dialog. + + + oDialog.SetPageManager(PilotControls := "aPageList", _ + WizardControls := "btnPrevious,btnNext", _ + LastPage := 3) + oDialog.Execute() + + + + dlg.SetPageManager(pilotcontrols="aPageList", + wizardcontrols="btnPrevious,btnNext", + lastpage=3) + dlg.Execute() + +
+
Terminate -------------------------------------------------------------------------------------------------------------------------- diff --git a/source/text/sbasic/shared/03/sf_dialogcontrol.xhp b/source/text/sbasic/shared/03/sf_dialogcontrol.xhp index c29d82c65f..642acfeaa8 100644 --- a/source/text/sbasic/shared/03/sf_dialogcontrol.xhp +++ b/source/text/sbasic/shared/03/sf_dialogcontrol.xhp @@ -53,23 +53,50 @@ # ... process the controls actual values dlg.Terminate() - Alternatively a control instance can be retrieved via the SFDialogs.DialogEvent service, providing the dialog was initiated with the Dialog service. DialogEvent returns the SFDialogs.DialogControl class instance that triggered the event. - - Sub SomeEvent(ByRef poEvent As Object) +

Retrieving the DialogControl instance that triggered a control event

+ An instance of the DialogControl service can be retrieved via the SFDialogs.DialogEvent service, provided that the dialog was initiated with the Dialog service. In the example below, oControl contains the DialogControl instance that triggered the control event. + + Sub aControlEventHandler(ByRef poEvent As Object) Dim oControl As Object Set oControl = CreateScriptService("SFDialogs.DialogEvent", poEvent) ' ... End Sub - - - def some_event(event: uno): - ctrl = CreateScriptService('SFDialogs.DialogEvent', event) + + Or using Python: + + def control_event_handler(event: uno): + oControl = CreateScriptService('SFDialogs.DialogEvent', event) # ... - - Note that in previous examples, the prefix "SFDialogs." may be omitted. -

Control types

- The DialogControl service is available for these control types: - + + Note that in the previous examples, the prefix "SFDialogs." may be omitted when deemed appropriate. +

Handling exceptions in event handlers

+ When creating an event handler for control events it is good practice to handle errors inside the subroutine itself. For instance, suppose the event handler below is called when button is clicked. + + Sub OnButtonClicked(ByRef oEvent As Object) + On Local Error GoTo Catch + Dim oControl As Object + oControl = CreateScriptService("DialogEvent", oEvent) + ' Process the event + Exit Sub + Catch: + MsgBox SF_Exception.Description + SF_Exception.Clear + End Sub + + Call SF_Exception.Clear if you do not want the error to propagate after the dialog execution ended. + In Python use native try/except blocks for exception handling as shown below: + + def on_button_clicked(event=None): + try: + oControl = CreateScriptService("DialogEvent", event) + # Process the event + except Exception as e: + # The object "bas" below is an instance of the Basic service + bas.MsgBox(str(e)) + +

Control types

+ The DialogControl service is available for these control types: + Button -- cgit