Съдържание

# Услуга SFDialogs.Dialog

Услугата Dialog подпомага управлението на диалози, изградени с редактора на диалози на Basic или създадени в движение. Всеки екземпляр на текущия клас представя един отделен диалогов прозорец, показан на потребителя.

Диалоговите прозорци могат да се показват в модален или немодален режим.

В модален режим прозорецът се показва и изпълнението на макропроцеса се преустановява, докато бъде натиснат някой от бутоните OK или „Отказ“. Междувременно потребителските действия, изпълнени върху прозореца, може да активират определени действия.

В немодален режим диалоговият прозорец „плава“ върху работния плот на потребителя и изпълнението на макропроцеса продължава нормално. Немодалният диалог се затваря, когато бъде прекратен с метода Terminate(), или когато сесията на LibreOffice приключи. Бутонът за затваряне на прозореца е неактивен в немодалните диалози.

Диалоговите прозорци изчезват от паметта, след като бъдат изрично прекратени.

Услугата SFDialogs.Dialog е тясно свързана с услугата SFDialogs.DialogControl.

## Извикване и използване на услугата

Преди да използвате услугата Dialog, библиотеката ScriptForge трябва да бъде заредена или импортирана:

• Макросите на Basic изискват зареждане на библиотеката ScriptForge чрез следния оператор:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Скриптовете на Python изискват импортиране от модула scriptforge:
from scriptforge import CreateScriptService

Услугата Dialog се извиква чрез метода CreateScriptService. Тя изисква три допълнителни позиционни аргумента, указващи кой диалогов прозорец да се активира:

Container: "GlobalScope" за предварително инсталирани библиотеки или име на прозорец, както е дефинирано от услугата ScriptForge.UI. Подразбираната стойност е празен низ "", който означава текущия документ.

Library: чувствително към регистъра име на библиотека от контейнера. Подразбираната стойност е "Standard".

DialogName: чувствителен към регистъра низ, указващ диалога.

Примерните откъси на Basic и Python по-долу показват диалога dlgConsole, който принадлежи на споделената библиотека ScriptForge:

          Dim oDlg As Object, lButton As Long
          Dim Container As String, Library As String, DialogName As String
          Set oDlg = CreateScriptService("SFDialogs.Dialog", "GlobalScope", "ScriptForge", "dlgConsole")
          '... тук се инициализират контролите...
          lButton = oDlg.Execute()
          'Подразбиран режим = Modal
          If lButton = oDlg.OKBUTTON Then
          '... Тук обработваме контролите и извършваме необходимите действия
          End If
          oDlg.Terminate()

Или чрез Python:

        dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', 'ScriptForge', 'dlgConsole')
        '... тук се инициализират контролите...
        rc = dlg.Execute()
        # Подразбираният режим е Modal
        if rc == dlg.OKBUTTON:
            # ... Тук обработваме контролите и извършваме необходимите действия
        dlg.Terminate()

Използвайте низа "GlobalScope" за аргумента container, когато диалогът се съхранява в Моите макроси и диалози или Макроси и диалози на приложението.

Услугата за диалог предоставя методи за динамично създаване на нови контроли в съществуващ диалог, дефиниран предварително с редактора на диалози. Диалогът се инициализира с контролите от редактора, а към тях могат да се добавят нови по време на изпълнение преди или след оператора Execute() на диалога.

Услугата Dialog може да бъде извиквана – чрез метода CreateScriptService – и при създаване на диалози в движение. Тогава се изискват два допълнителни позиционни аргумента след името на ad-hoc услугата "NewDialog":

DialogName: чувствителен към регистъра низ, указващ диалога.

Place: позиция на прозореца на диалога, която може да бъде едно от двете неща:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

        Sub newDialog()
            Dim oDlg As Object
           oDlg = CreateScriptService("NewDialog", "myDialog1", Array(100,200, 40, 110))
           ' ...
        End Sub

Или чрез Python:

        def newDialog():
           dlg = CreateScriptService('NewDialog', 'myDialog1', (100,200, 40, 110))
           # ... Тук обработваме контролите и извършваме необходимите действия

Всички свойства и методи, приложими върху предварително дефинирани диалози, са достъпни и за такива нови диалози. Това включва редицата методи CreateXXX() за създаване на нови диалогови контроли.

## Извличане на екземпляра на Dialog, който е задействал диалогово събитие

Екземпляр на услугата Dialog може да бъде извлечен чрез услугата SFDialogs.DialogEvent, стига диалогът да е започнат рез услугата Dialog. В долния пример oDlg съдържа екземпляра на Dialog, който е активирал диалоговото събитие.

        Sub aDialogEventHander(ByRef poEvent As Object)
            Dim oDlg As Object
            Set oDlg = CreateScriptService("SFDialogs.DialogEvent", poEvent)
            ' ...
        End Sub

Или чрез Python:

        def control_event_handler(event: uno):
            dlg = CreateScriptService("SFDialogs.DialogEvent", event)
            # ...

Обърнете внимание, че в предишните примери префиксът "SFDialogs." може да бъде пропуснат, когато това се смята за подходящо.

### Обработка на изключения в обработчиците на събития

Когато създавате обработчик на събития за събития от диалог, добра практика е грешките да се обработват в самата подпрограма. Например, да предположим, че следващият обработчик на събития се извиква, когато в диалоговия прозорец бъде натиснат бутонът на мишката.

        Sub OnMouseButtonPressed(ByRef oEvent As Object)
        On Local Error GoTo Catch
            Dim oDialog As Object
            oDialog = CreateScriptService("DialogEvent", oEvent)
            ' Обработваме събитието
            Exit Sub
        Catch:
            MsgBox SF_Exception.Description
            SF_Exception.Clear
        End Sub

Извикайте SF_Exception.Clear, ако не искате грешката да се разпространява, след като приключи изпълнението на диалога.

В Python за обработка на изключенията използвайте нормални блокове try/except, както е показано по-долу:

        def on_mouse_button_pressed(event=None):
            try:
                dlg = CreateScriptService("DialogEvent", event)
                # Обработваме събитието
            except Exception as e:
                # Обектът "bas" е екземпляр на услугата на Basic.
                bas.MsgBox(str(e))

## Свойства

Име | Само за четене | Тип | Описание
--- | --- | --- | ---
OKBUTTON | Да | Integer | Стойност = 1. Натиснат е бутон OK.
CANCELBUTTON | Да | Integer | Стойност = 0. Натиснат е бутон „Отказ“.
Caption | Не | String | Указва заглавието на диалога.
Height | Не | Long | Указва височината на диалоговия прозорец.
Modal | Да | Boolean | Указва дали диалогът в момента се изпълнява в модален режим.
Name | Да | String | Името на диалога.
Page | Не | Integer | Диалогът може да има няколко страници, които потребителят да обхожда стъпка по стъпка. Свойството Page на обекта от тип Dialog определя коя страница на диалога е активна.
Visible | Не | Boolean | Указва дали диалоговият прозорец се вижда на работния плот. По подразбиране той е невидим, преди да се изпълни методът Execute(), а след това е видим.
XDialogModel | Да | UNO object | UNO обектът, представящ модела на диалога. За подробна информация вижте XControlModel и UnoControlDialogModel в документацията на интерфейса за приложно програмиране (API).
XDialogView | Да | UNO object | UNO обектът, представящ изгледа на диалога. За подробна информация вижте XControl и UnoControlDialog в документацията на интерфейса за приложно програмиране (API).
Width | Не | Long | Указва ширината на диалоговия прозорец.

## Свойства за събития

On… event properties are URI strings that reference a script triggered for an event. Read its specification in the scripting framework URI specification.

Име | Описание в развойната среда на Basic
--- | ---
OnFocusGained | При получаване на фокуса
OnFocusLost | При загубване на фокуса
OnKeyPressed | Натиснат клавиш
OnKeyReleased | Отпуснат клавиш
OnMouseDragged | Преместена мишка с натиснат клавиш
OnMouseEntered | Мишката е вътре
OnMouseExited | Мишката е отвън
OnMouseMoved | Преместена мишка
OnMousePressed | Натиснат бутон на мишката
OnMouseReleased | Отпуснат бутон на мишката

Tip: All On… properties can be set programmatically.
How to display data in a tree control example in LibreOffice Wiki demonstrates such.

Присвояването на събития чрез развойната среда на Basic и присвояването на събития чрез макроси взаимно се изключват.

Списък с методи на услугата Dialog
Activate Center Controls CloneControl CreateButton CreateCheckBox CreateComboBox CreateCurrencyField CreateDateField CreateFileControl CreateFixedLine CreateFixedText | CreateFormattedField CreateGroupBox CreateHyperlink CreateImageControl CreateListBox CreateNumericField CreatePatternField CreateProgressBar CreateRadioButton CreateScrollBar CreateTableControl CreateTabPageContainer | CreateTextField CreateTimeField CreateTreeControl EndExecute Execute GetTextsFromL10N ImportControl OrderTabs Resize SetPageManager Terminate

TabPageContainer controls are not available in Dialog Editor.

Оразмеряването на диалози се извършва в единици Map AppFont. Моделите на диалози и на контроли също използват единици Map AppFont. Съответните изгледи използват пиксели.

## Activate

Фокусира текущия екземпляр на услугата Dialog. Връща True, ако фокусирането е успешно.

Този метод се извиква от събитие на диалог или контрола или когато диалог се показва в немодален режим.

### Синтаксис:

svc.Activate(): bool

### Пример:

          Dim oDlg As Object
          Set oDlg = CreateScriptService(,, "myDialog")
          oDlg.Execute()
          ' ...
          oDlg.Activate()

В примерите на Python и LibreOffice Basic приемаме, че диалогът се съхранява в библиотеката Standard на текущия документ.

         dlg = CreateScriptService(,,'myDialog')
         dlg.Execute()
         # ...
         dlg.Activate()

## Center

Центрира текущия екземпляр на диалог спрямо родителски прозорец. Без аргументи методът центрира диалога спрямо текущия прозорец.

Връща True при успех.

### Синтаксис:

svc.Center(opt Parent: obj): bool

### Параметри:

Parent: незадължителен обект, който може да бъде един от следните:

- обект диалог на ScriptForge

- обект документ (Calc, Base, ...) на ScriptForge.

### Пример:

##### В Basic

         Sub TriggerEvent(oEvent As Object)
             Dim oDialog1 As Object, oDialog2 As Object, lExec As Long
             Set oDialog1 = CreateScriptService("DialogEvent", oEvent) ' Диалогът, причинил събитието
             Set oDialog2 = CreateScriptService("Dialog", ...) ' Отваряме втори диалог
             oDialog2.Center(oDialog1)
             lExec = oDialog2.Execute()
             Select Case lExec
                 ...
         End Sub

##### В Python

         def triggerEvent(event: uno):
           dlg1 = CreateScriptService('DialogEvent.Dialog', event)  # Диалогът, причинил събитието
           dlg2 = CreateScriptService('Dialog', ...)  # Отваряме втори диалог
           dlg2.Center(dlg1)
           rc = dlg2.Execute()
           if rc is False:
             # ...

## CloneControl

Дублира съществуваща контрола от произволен тип в действителния диалог. Дублираната контрола остава непроменена и може да бъде преместена.

### Синтаксис:

svc.CloneControl(SourceName: str, ControlName: str, Left: num, Top: num): svc

### Параметри:

SourceName: името на контролата, на която да се създаде копие.

ControlName: валидно име на контрола като чувствителен към регистъра низ. То още не трябва да съществува.

Left, Top: координатите на новата контрола, изразени в единици Map AppFont.

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

          Set myButton2 = oDlg.CloneControl("Button1", "Button2", 30, 30)

##### В Python

         dlg = dlg.CloneControl('Button1', 'Button2', 30, 30)

## Controls

Връща едно от следните:

- списъка на контролите, съдържани в диалога

- екземпляр на класа DialogControl на базата на името.

### Синтаксис:

svc.Controls(): str[0..*]

svc.Controls(controlname: str): svc

### Параметри:

ControlName: валидно име на контрола като чувствителен към регистъра низ. Ако отсъства, се връща списъкът от имената на контролите като започващ от 0 масив.

### Пример:

          Dim myDialog As Object, myList As Variant, myControl As Object
          Set myDialog = CreateScriptService("SFDialogs.Dialog", , "Standard", "Dialog1")
          myList = myDialog.Controls()
          Set myControl = myDialog.Controls("myTextBox")

         dlg = CreateScriptService('SFDialogs.Dialog','', 'Standard', 'Dialog1')
         ctrls = dlg.Controls()
         ctrl = dlg.Controls('myTextBox')

## CreateButton

Създава нова контрола от тип Button в текущия диалог.

### Синтаксис:

svc.CreateButton(ControlName: str, Place: any, Toggle: bool = False, Push: str = ""): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Toggle: когато е True, се създава бутон за превключване. Подразбира се False.

Push: "OK", "CANCEL" или "" (по подразбиране)

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myButton = oDlg.CreateButton("Button1", Array(20, 20, 60, 15))

##### В Python

         myButton = dlg.CreateButton('Button1', (20, 20, 60, 15))

## CreateCheckBox

Създава нова контрола от тип CheckBox в текущия диалог.

### Синтаксис:

svc.CreateCheckBox(ControlName: str, Place: any, Multiline: bool = False): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

MultiLine: когато е True (подразбира се False), надписът може да се показва на повече от един ред.

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myCheckBox = oDlg.CreateCheckBox("CheckBox1", Array(20, 20, 60, 15), MultiLine := True)

##### В Python

         myCheckBox = dlg.CreateCheckBox('CheckBox1', (20, 20, 60, 15), MultiLine = True)

## CreateComboBox

Създава нова контрола от тип ComboBox в текущия диалог.

### Синтаксис:

svc.CreateComboBox(ControlName: str, Place: any, Border: str = "3D", DropDown: bool = True, LineCount: num = 5): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (по подразбиране), "FLAT" или "NONE"

DropDown: когато е True (подразбира се), се показва бутон за падащ списък.

LineCount: Specifies the maximum line count displayed in the drop down (default = 5)

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myComboBox = oDlg.CreateComboBox("ComboBox1", Array(20, 20, 60, 15), Dropdown := True)

##### В Python

         myComboBox = dlg.CreateComboBox('ComboBox1', (20, 20, 60, 15), Dropdown = True)

## CreateCurrencyField

Creates a new control of type CurrencyField in the current dialog.

### Синтаксис:

svc.CreateCurrencyField(ControlName: str, Place: any, Border ="3D", SpinButton: bool = False, MinValue: num = -1000000, MaxValue: num = +1000000, Increment: num = 1, Accuracy: num = 2): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

SpinButton: when True (default = False), a spin button is present

MinValue: the smallest value that can be entered in the control. Default = -1000000

MaxValue: the largest value that can be entered in the control. Default = +1000000

Increment: the step when the spin button is pressed. Default = 1

Accuracy: specifies the decimal accuracy. Default = 2 decimal digits

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myCurrencyField = oDlg.CreateCurrencyField("CurrencyField1", Array(20, 20, 60, 15), SpinButton := True)

##### В Python

         myCurrencyField = dlg.CreateCurrencyField('CurrencyField1', (20, 20, 60, 15), SpinButton = True)

## CreateDateField

Creates a new control of type DateField in the current dialog.

### Синтаксис:

svc.CreateDateField(ControlName: str, Place: any, Border: str = "3D", DropDown: bool = False, opt MinDate: datetime, opt MaxDate: datetime): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

DropDown: when True (default = False), a dropdown button is shown

MinDate: the smallest date that can be entered in the control. Default = 1900-01-01

MaxDate: the largest date that can be entered in the control. Default = 2200-12-31

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myDateField = oDlg.CreateDateField("DateField1", Array(20, 20, 60, 15), Dropdown := True)

##### В Python

         myDateField = dlg.CreateDateField('DateField1', (20, 20, 60, 15), Dropdown = True)

## CreateFileControl

Creates a new control of type FileControl in the current dialog.

### Синтаксис:

svc.CreateFileControl(ControlName: str, Place: any, Border: str = "3D"): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myFileControl = oDlg.CreateFileControl("FileControl1", Array(20, 20, 60, 15))

##### В Python

         myFileControl = dlg.CreateFileControl('FileControl1', (20, 20, 60, 15))

## CreateFixedLine

Creates a new control of type FixedLine in the current dialog.

### Синтаксис:

svc.CreateFixedLine(ControlName: str, Place: any, Orientation: str): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Orientation: for horizontal orientation use "H" or "Horizontal"; for vertical orientation use "V" or "Vertical".

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myFixedLine = oDlg.CreateFixedLine("FixedLine1", Array(20, 20, 60, 15), Orientation := "vertical")

##### В Python

         myFixedLine = dlg.CreateFixedLine('FixedLine1', (20, 20, 60, 15), Orientation = 'vertical')

## CreateFixedText

Creates a new control of type FixedText in the current dialog.

### Синтаксис:

svc.CreateFixedText(ControlName: str, Place: any, Border: str = "3D", MultiLine: bool = False, Align: str = "LEFT", VerticalAlign: str = "TOP"): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "NONE" (default), "FLAT" or "3D"

Multiline: When True (default = False), the caption may be displayed on more than one line

Align: horizontal alignment, "LEFT" (default), "CENTER" or "RIGHT"

VerticalAlign: vertical alignment, "TOP" (default), "MIDDLE" or "BOTTOM"

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myFixedText = oDlg.CreateFixedText("FixedText1", Array(20, 20, 60, 15), MultiLine := True)

##### В Python

         myFixedText = dlg.CreateFixedText('FixedText1', (20, 20, 60, 15), MultiLine = True)

## CreateFormattedField

Creates a new control of type FormattedField in the current dialog.

### Синтаксис:

svc.CreateFormattedField(ControlName: str, Place: any, Border: str = "3D", SpinButton: bool = False, MinValue: num = -1000000, MaxValue: num = +1000000): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

SpinButton: when True (default = False), a spin button is present

MinValue: the smallest value that can be entered in the control. Default = -1000000

MaxValue: the largest value that can be entered in the control. Default = +1000000

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myFormattedField = oDlg.CreateFormattedField("FormattedField1", Array(20, 20, 60, 15), SpinButton := True)

##### В Python

         myFormattedField = dlg.CreateFormattedField('FormattedField1', (20, 20, 60, 15), SpinButton = True)

## CreateGroupBox

Creates a new control of type GroupBox in the current dialog.

### Синтаксис:

svc.CreateGroupBox(ControlName: str, Place: any): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myGroupBox = oDlg.CreateGroupBox("GroupBox1", Array(20, 20, 60, 15))

##### В Python

         myGroupBox = dlg.CreateGroupBox('GroupBox1', (20, 20, 60, 15))

## CreateHyperlink

Creates a new control of type Hyperlink in the current dialog.

### Синтаксис:

svc.CreateHyperlink(ControlName: str, Place: any, Border: str = "NONE", MultiLine: bool = False, Align: str = "LEFT", VerticalAlign: str = "TOP"): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "NONE" (default), "FLAT" or "3D"

MultiLine: When True (default = False), the caption may be displayed on more than one line

Align: horizontal alignment, "LEFT" (default), "CENTER" or "RIGHT"

VerticalAlign: vertical alignment, "TOP" (default), "MIDDLE" or "BOTTOM"

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myHyperlink = oDlg.CreateHyperlink("Hyperlink1", Array(20, 20, 60, 15), MultiLine := True)

##### В Python

         myHyperlink = dlg.CreateHyperlink('Hyperlink1', (20, 20, 60, 15), MultiLine = True)

## CreateImageControl

Creates a new control of type ImageControl in the current dialog.

### Синтаксис:

svc.CreateImageControl(ControlName: str, Place: any, Border: str = "3D", Scale: str = "FITTOSIZE"): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

Scale: One of next values: "FITTOSIZE" (default), "KEEPRATIO" or "NO"

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myImageControl = oDlg.CreateImageControl("ImageControl1", Array(20, 20, 60, 15))

##### В Python

           myImageControl = dlg.CreateImageControl('ImageControl1", (20, 20, 60, 15))

## CreateListBox

Creates a new control of type ListBox in the current dialog.

### Синтаксис:

svc.CreateListBox(ControlName: str, Place: any, Border: str = "3D", DropDown: bool = True, LineCount: num = 5, MultiSelect: bool = False): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

DropDown: When True (default), a drop down button is displayed

LineCount: Specifies the maximum line count displayed in the drop down (default = 5)

MultiSelect: When True, more than 1 entry may be selected. Default = False

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myListBox = oDlg.CreateListBox("ListBox1", Array(20, 20, 60, 15), Dropdown := True, MultiSelect := True)

##### В Python

         myListBox = dlg.CreateListBox('ListBox1', (20, 20, 60, 15), Dropdown = True, MultiSelect = True)

## CreateNumericField

Creates a new control of type NumericField in the current dialog.

### Синтаксис:

svc.CreateNumericField(ControlName: str, Place: any, Border: str = "3D", SpinButton: bool = False, MinValue: num = -1000000, MaxValue: num = 1000000, Increment: num = 1, Accuracy: num = 2): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

SpinButton: when True (default = False), a spin button is present

MinValue: the smallest value that can be entered in the control. Default = -1000000

MaxValue: the largest value that can be entered in the control. Default = +1000000

Increment: the step when the spin button is pressed. Default = 1

Accuracy: specifies the decimal accuracy. Default = 2 decimal digits

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myNumericField = oDlg.CreateNumericField("NumericField1", Array(20, 20, 60, 15), SpinButton := True)

##### В Python

         myNumericField = dlg.CreateNumericField('NumericField1', (20, 20, 60, 15), SpinButton = True)

## CreatePatternField

Creates a new control of type PatternField in the current dialog.

### Синтаксис:

svc.CreatePatternField(ControlName: str, Place: any, Border: str = "3D", EditMask: str, opt LiteralMax: str): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

EditMask: a character code that determines what the user may enter
Refer to Pattern_Field in the wiki for more information.

LiteralMask: contains the initial values that are displayed in the pattern field

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myPatternField = oDlg.CreatePatternField("PatternField1", Array(20, 20, 60, 15), EditMask := "NNLNNLLLLL", LiteralMask := "__.__.2002")

##### В Python

         myPatternField = dlg.CreatePatternField('PatternField1', (20, 20, 60, 15), EditMask = 'NNLNNLLLLL', LiteralMask = '__.__.2002')

## CreateProgressBar

Creates a new control of type ProgressBar in the current dialog.

### Синтаксис:

svc.CreateProgressBar(ControlName: str, opt Place: any, Border: str = "3D", MinValue: num = 0, MaxValue: num = 100): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

MinValue: the smallest value that can be entered in the control. Default = 0

MaxValue: the largest value that can be entered in the control. Default = 100

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myProgressBar = oDlg.CreateProgressBar("ProgressBar1", Array(20, 20, 60, 15), MaxValue := 1000)

##### В Python

         myProgressBar = dlg.CreateProgressBar('ProgressBar1', (20, 20, 60, 15), MaxValue = 1000)

## CreateRadioButton

Creates a new control of type RadioButton in the current dialog.

### Синтаксис:

svc.CreateRadioButton(ControlName: str, Place: any, MultiLine: bool = False): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

MultiLine: When True (default = False), the caption may be displayed on more than one line

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myRadioButton = oDlg.CreateRadioButton("RadioButton1", Array(20, 20, 60, 15), MultiLine := True)

##### В Python

         myRadioButton = dlg.CreateRadioButton('RadioButton1', (20, 20, 60, 15), MultiLine = True)

## CreateScrollBar

Creates a new control of type ScrollBar in the current dialog.

### Синтаксис:

svc.CreateScrollBar(ControlName: str, Place, Orientation: str, Border: str = "3D", MinValue: num = 0, MaxValue: num = 100): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Orientation: for horizontal orientation use "H" or "Horizontal"; for vertical orientation use "V" or "Vertical".

Border: "3D" (default), "FLAT" or "NONE"

MinValue: the smallest value that can be entered in the control. Default = 0

MaxValue: the largest value that can be entered in the control. Default = 100

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myScrollBar = oDlg.CreateScrollBar("ScrollBar1", Array(20, 20, 60, 15), MaxValue := 1000)

##### В Python

         myScrollBar = dialog.CreateScrollBar('ScrollBar1', (20, 20, 60, 15), MaxValue = 1000)

## CreateTableControl

Creates a new control of type TableControl in the current dialog.

### Синтаксис:

svc.CreateTableControl(ControlName: str, Place: any, Border: str = "3D", RowHeaders: bool = True, ColumnHeaders: bool = True, ScrollBars: str = "N", GridLines: bool = False): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

RowHeaders: when True (default), the row Headers are shown

ColumnHeaders: when True (default), the column Headers are shown

ScrollBars: possible values are: "H" or "Horizontal" (horizontal scrollbars), "V" or "Vertical" (vertical scrollbars); "B" or "Both" (both scrollbars); "N" or "None" (default) for no scrollbars. Scrollbars appear dynamically when they are needed.

GridLines: when True (default = False) horizontal and vertical lines are painted between the grid cells

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myTableControl = oDlg.CreateTableControl("TableControl1", Array(20, 20, 60, 15), ScrollBars := "B")

##### В Python

         myTableControl = dlg.CreateTableControl('TableControl1', (20, 20, 60, 15), ScrollBars = 'B')

## CreateTabPageContainer

Creates a new control of type TabPageContainer in the current dialog. Tabs are spread over separate lines inside the dialog when necessary. Multiple TabPageContainer are not supported.

TagePageContainer control creation comes always last in a dialog creation.

### Синтаксис:

svc.CreateTabPageContainer(ControlName: str, Place: any, TabHeaders: str[1..*], Border: str = "3D"): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

TabHeaders: An array of strings defining each individual label for tabs

Border: "3D" (default), "FLAT" or "NONE"

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myTabPageContainer = oDlg.CreateTabPageContainer("someContainer", Array(20, 20, 60, 15), TabHeaders := Array("Modules", "Dialogs", "Libraries"))

##### В Python

         myTabPageContainer = dlg.CreateTabPageContainer('theTabs', TabHeaders=('Modules', 'Dialogs', 'Libraries'), place=(20, 20, 60, 15))

## CreateTextField

Creates a new control of type TextField in the current dialog.

### Синтаксис:

svc.CreateTextField(ControlName: str, Place: any, Border: str = "3D", MultiLine: bool = False, MaximumLength: num = 0, PasswordCharacter: str = ""): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

MultiLine: When True (default = False), the caption may be displayed on more than one line

MaximumLength: the maximum character count (default = 0 meaning unlimited)

PasswordCharacter: a single character specifying the echo for a password text field (default = "")

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

    Set myTextField = oDlg.CreateTextField("TextField1", Array(20, 20, 120, 50), MultiLine := True)

##### В Python

         myTextField = dlg.CreateTextField('TextField1', (20, 20, 120, 50), MultiLine = True)

## CreateTimeField

Creates a new control of type TimeField in the current dialog.

### Синтаксис:

svc.CreateTimeField(ControlName: str, Place: any, Border: str = "3D", MinTime: num = 0, MaxTime: num = 24): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

MinTime: the smallest time that can be entered in the control. Default = 0

MaxTime: the largest time that can be entered in the control. Default = 24h

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myTimeField = oDlg.CreateTimeField("TimeField1", Array(20, 20, 60, 15))

##### В Python

         myTimeField = dlog.CreateTimeField('TimeField1', (20, 20, 60, 15))

## CreateTreeControl

Creates a new control of type TreeControl in the current dialog.

### Синтаксис:

svc.CreateTreeControl(ControlName: str, Place: any, Border = "3D"): svc

### Параметри:

ControlName: името на новата контрола. То още не трябва да съществува.

Place: едно от следните:

- масив на Basic (Array) или кортеж на Python с 4 елемента: (X, Y, ширина, височина)

- обект com.sun.star.awt.Rectangle [X, Y, Ширина, Височина]

Всички елементи са в единици Map AppFont.

Border: "3D" (default), "FLAT" or "NONE"

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set myTreeControl = oDlg.CreateTreeControl("TreeControl1", Array(20, 20, 60, 15))

##### В Python

         myTreeControl = dlg.CreateTreeControl('TreeControl1', (20, 20, 60, 15))

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

### Синтаксис:

svc.EndExecute(returnvalue: int)

### Параметри:

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

### Пример:

##### В Basic

          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

##### В 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 LibreOffice Application Programming Interface (API).

## Execute

Display the dialog box and, when modal, wait for its termination by the user. The returned value is either:

- 0 : Cancel button pressed

- 1 : OK button pressed

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

### Синтаксис:

svc.Execute(modal: bool = True): int

### Параметри:

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")
          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:
             # ...

## GetTextsFromL10N

Replaces all fixed text strings in a dialog by their translated versions based on a L10N service instance. This method translates the following strings:

- The title of the dialog.

- The caption of the following control types: Button, CheckBox, FixedLine, FixedText, GroupBox and RadioButton.

- Static strings in ListBoxes and ComboBoxes.

- The tooltip or help text displayed when the mouse hovers over the control.

The method returns True if successful.

To create a list of translatable strings in a dialog use the AddTextsFromDialog method from the L10N service.

### Синтаксис:

svc.GetTextsFromL10N(l10n: svc): bool

### Параметри:

l10n: A L10N service instance from which translated strings will be retrieved.

### Пример:

The following example loads translated strings and applies them to the dialog "MyDialog".

##### В Basic

         oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
         myPO = CreateScriptService("L10N", "/home/user/po_files/")
         oDlg.GetTextsFromL10N(myPO)
         oDlg.Execute()

##### В Python

         dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
         myPO = CreateScriptService("L10N", "/home/user/po_files/")
         dlg.GetTextsFromL10N(myPO)
         dlg.Execute()

Read the L10N service help page to learn more about how PO and POT files are handled.

## ImportControl

Import and duplicate an existing control of any type from one dialog to the actual dialog. The duplicated control is left unchanged. The new control can be renamed and relocated. Events handlers, when present, may be imported too.

### Синтаксис:

svc.ImportControl(SourceDialog: svc, SourceName: str, opt ControlName: str, Page: num = 0, OffsetX: num = 0, OffsetY:num = 0, IncludeOnProperties: bool = False): svc

### Параметри:

SourceDialog: an SFDialogs.Dialog class instance.

SourceName: the name of the control to import.

ControlName: the name of the new control. It must not exist yet. Default is SourceName

Page: the page number of the new control. Default = 0

OffsetX, OffsetY: the number of pixels to add to the source control coordinates in "Map AppFont" units. Default = 0, may be negative.

IncludeOnProperties: include the On... event properties. Default = False.

### Тип на резултата:

Екземпляр на услугата SFDialogs.DialogControl или Nothing.

### Пример:

##### В Basic

         Set mCtrl = oDlg.ImportControl(srceDlg, "someCtrlName")

##### В Python

         dlg.ImportControl(srceDlg, 'aCtrlName', includeOnProperties=true)

## OrderTabs

Set the tabulation index of a series of controls. The sequence of controls are given as an array of control names from the first to the last.

Controls with an index >= 1 are not accessible with the TAB key if:
- they are omitted from the given list
- their type is FixedLine, GroupBox or ProgressBar
- they are disabled

### Синтаксис:

svc.TabsList(TabsList: num, Start: num = 1, Increment: num = 1): bool

### Параметри:

TabsList: an array of valid control names in the order of tabulation

Start: the tab index to be assigned to the 1st control in the list. Default = 1

Increment: the difference between 2 successive tab indexes. Default = 1

### Тип на резултата:

Връща True при успех.

### Пример:

##### В Basic

         oDlg.OrderTabs(Array("myListBox", "myTextField", "myNumericField"), Start := 10)

##### В Python

         dlg.OrderTabs(('myListBox', 'myTextField', 'myNumericField'), Start = 10)

## Resize

Moves the topleft corner of a dialog to new coordinates and/or modify its dimensions. All distances are expressed in AppFont units. Without arguments, the method resets the initial dimensions. Return True if the resize was successful.

### Синтаксис:

svc.Resize(opt Left: num, opt Top: num, opt Width: num, opt Height: num): bool

### Параметри:

Left: the horizontal distance from the top-left corner

Top: the vertical distance from the top-left corner

Width: the width of the rectangle containing the dialog

Height: the height of the rectangle containing the dialog

Missing arguments are left unchanged

### Пример:

##### В Basic

         oDlg.Resize(1000, 2000, Height := 6000) ' Width is not changed

##### В Python

         dlg.Resize(1000, 2000, Height = 6000)  # Width is not changed

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

##### В Basic

        oDlg.SetPageManager(PilotControls := "aPageList", _
                               WizardControls := "btnPrevious,btnNext", _
                               LastPage := 3)
        oDlg.Execute()

##### В Python

        dlg.SetPageManager(pilotcontrols="aPageList",
                           wizardcontrols="btnPrevious,btnNext",
                           lastpage=3)
        dlg.Execute()

## Terminate

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

### Синтаксис:

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:

##### В Basic

         oDlg = CreateScriptService("SFDialogs.Dialog","GlobalScope","ScriptForge","DlgConsole")
         oDlg.Execute(modal:=False)
         Wait 5000
         oDlg.Terminate()

##### В Python

         from time import sleep
         dlg = CreateScriptService('SFDialogs.Dialog',"GlobalScope",'Access2Base',"dlgTrace")
         dlg.Execute(modal=False)
         sleep 5
         dlg.Terminate()

В ScriptForge всички подпрограми или идентификатори на Basic с префикс „_“ са запазени за вътрешна употреба. Те не са предназначени за използване в макроси на Basic.

Теми, свързани с показаната

SFDialogs.DialogControl service

ScriptForge.UI service

Моля, подкрепете ни!