SFDialogs.Dialog serviço

O serviço Dialog contribui para a gestão de caixas de diálogo criadas com o Editor de Diálogos do Basic ou criadas dinamicamente. Cada instância da classe atual representa uma única caixa de diálogo apresentada ao utilizador.

Uma caixa de diálogo pode ser apresentada nos modos modal ou não modal.

No modo modal, a caixa é apresentada e a execução do processo da macro é suspensa até que seja premido um dos botões «OK» ou «Cancelar». Entretanto, as ações do utilizador realizadas na caixa podem desencadear ações específicas.

No modo não modal, a caixa de diálogo fica «flutuante» no ambiente de trabalho do utilizador e a execução do processo da macro prossegue normalmente. Uma caixa de diálogo não modal fecha-se quando é encerrada com o método Terminate() ou quando a sessão LibreOfficeDev termina. O botão de fecho da janela fica inativo nas caixas de diálogo não modais.

Uma caixa de diálogo desaparece da memória após o seu encerramento explícito.

O serviço SFDialogs.Dialog está intimamente relacionado com o serviço SFDialogs.DialogControl.

Invocação e utilização do serviço

Antes de utilizar o serviço Dialog, é necessário carregar ou importar a biblioteca ScriptForge:

• As macros básicas requerem o carregamento da biblioteca ScriptForge através da seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Os scripts Python requerem a importação do módulo scriptforge:
from scriptforge import CreateScriptService

O serviço Dialog é invocado através do método CreateScriptService. Este requer três argumentos posicionais adicionais para especificar a caixa de diálogo a ativar:

Contentor: "GlobalScope" para bibliotecas pré-instaladas ou um nome de janela, conforme definido pelo serviço ScriptForge.UI. O valor por predefinição, a cadeia vazia "", representa o documento atual.

Biblioteca: O nome, que distingue maiúsculas de minúsculas, de uma biblioteca contida no contentor. O valor predefinido é «Standard».

DialogName: Uma cadeia de caracteres que distingue maiúsculas de minúsculas e que identifica a caixa de diálogo.

Os exemplos abaixo, em Basic e Python, apresentam a caixa de diálogo dlgConsole que pertence à biblioteca partilhada 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")
      '... a inicialização dos controlos faz-se aqui...'
      lButton = oDlg.Execute()
      'Modo predefinido = Modal
      If lButton = oDlg.OKBUTTON Then
      '... Controlar o processo e fazer o que for necessário aqui'
      End If
      oDlg.Terminate()
  

Ou utilizando Python:

    dlg = CreateScriptService('SFDialogs.Dialog', 'GlobalScope', 'ScriptForge', 'dlgConsole')
    # ... a inicialização dos controlos vai aqui...
    rc = dlg.Execute()
    # O modo predefinido é «Modal»
    if rc == dlg.OKBUTTON:
        # ... Controlar o processo e fazer o que for necessário aqui
    dlg.Terminate()
  

Utilize a cadeia de caracteres «GlobalScope» como argumento container quando a caixa de diálogo estiver guardada em As minhas macros e caixas de diálogo ou em Macros e caixas de diálogo da aplicação.

O serviço de caixas de diálogo oferece métodos que criam novos controlos dinamicamente numa caixa de diálogo existente, pré-definida com o Editor de Caixas de Diálogo. Uma caixa de diálogo é inicializada com controlos no Editor de Caixas de Diálogo e é possível adicionar novos controlos em tempo de execução, antes ou depois da instrução Execute() da caixa de diálogo.

O serviço Dialog também pode ser invocado — através do método CreateScriptService — ao criar caixas de diálogo em tempo real. Requer dois argumentos posicionais adicionais após o nome do serviço ad hoc «NewDialog»:

DialogName: Uma cadeia de caracteres que distingue maiúsculas de minúsculas e que identifica a caixa de diálogo.

Local: A localização da janela da caixa de diálogo pode ser:

• um Array do Basic ou uma tupla do Python com 4 elementos: (X, Y, largura, altura)

• um objeto com.sun.star.awt.Rectangle [X, Y, Largura, Altura]

Todos os elementos são expressos em unidades Map AppFont.

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

Ou utilizando Python:

    def newDialog():
       dlg = CreateScriptService('NewDialog', 'myDialog1', (100, 200, 40, 110))
       # ... Controlar o processo e fazer o que for necessário
  

Todas as propriedades e métodos aplicáveis às caixas de diálogo predefinidas estão disponíveis para essas novas caixas de diálogo. Em particular, a série de métodos CreateXXX() para a adição de novos controlos às caixas de diálogo.

Recuperar a instância do Dialog que desencadeou um evento de diálogo

É possível recuperar uma instância do serviço Dialog através do serviço SFDialogs.DialogEvent, desde que a caixa de diálogo tenha sido iniciada com o serviço Dialog. No exemplo abaixo, oDlg contém a instância Dialog que desencadeou o evento da caixa de diálogo.

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

Ou utilizando Python:

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

Note-se que, nos exemplos anteriores, o prefixo "SFDialogs." pode ser omitido quando se considerar adequado.

Tratamento de exceções nos manipuladores de eventos

Ao criar um manipulador de eventos para eventos de caixa de diálogo, é boa prática tratar os erros dentro da própria sub-rotina. Por exemplo, suponha que o manipulador de eventos abaixo seja chamado quando o botão do rato for premido na janela de diálogo.

    Sub OnMouseButtonPressed(ByRef oEvent As Object)
    On Local Error GoTo Catch
        Dim oDialog As Object
        oDialog = CreateScriptService("DialogEvent", oEvent)
        ' Processar o evento
        Exit Sub
    Catch:
        MsgBox SF_Exception.Description
        SF_Exception.Clear
    End Sub
  

Chame SF_Exception.Clear se não quiser que o erro se propague após o término da execução da caixa de diálogo.

Em Python, utilize blocos try/except nativos para o tratamento de exceções, conforme ilustrado abaixo:

    def on_mouse_button_pressed(event=None):
        try:
            dlg = CreateScriptService("DialogEvent", event)
            # Processar o evento
        except Exception as e:
            # O objeto «bas» é uma instância do serviço Basic
            bas.MsgBox(str(e))
  

Propriedades

Propriedades do evento

As propriedades de evento On… são cadeias de caracteres URI que fazem referência a um script acionado por um evento. Consulte a respetiva especificação na especificação URI da estrutura de scripting.

Dica: Todas as propriedades On… podem ser definidas programaticamente.
O exemplo Como apresentar dados num controlo de árvore na Wiki do LibreOfficeDev ilustra isso mesmo.

A atribuição de eventos através do IDE Básico e a atribuição de eventos através de macros são mutuamente exclusivas.

Os controlos TabPageContainer não estão disponíveis no Editor de Caixas de Diálogo.

O dimensionamento de uma caixa de diálogo é feito utilizando Map AppFont units. Um modelo de caixa de diálogo ou de controlo também utiliza unidades AppFont. Por outro lado, as respetivas vistas utilizam píxeis.

Activate

Estabelece o foco na instância atual de Dialog. Devolve True se o foco tiver sido estabelecido com sucesso.

Este método é chamado a partir de um evento de caixa de diálogo ou de controlo, ou quando uma caixa de diálogo é apresentada em modo não modal.

svc.Activate(): bool

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

Os exemplos básicos em Python e LibreOfficeDev partem do princípio de que a caixa de diálogo está armazenada na biblioteca Standard do documento atual.

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

Center

Centraliza a instância atual da caixa de diálogo no meio de uma janela pai. Sem argumentos, o método centraliza a caixa de diálogo no meio da janela atual.

Devolve True em caso de sucesso.

svc.Center(opt Parent: obj): bool

Pai: Um objeto opcional que pode ser…

• um objeto de caixa de diálogo do ScriptForge

• um objeto de documento do ScriptForge (Calc, Base, ...)

     Sub TriggerEvent(oEvent As Object)
         Dim oDialog1 As Object, oDialog2 As Object, lExec As Long
         Set oDialog1 = CreateScriptService("DialogEvent", oEvent) ' A caixa de diálogo que provocou o evento
         Set oDialog2 = CreateScriptService("Dialog", ...) ' Abrir uma segunda caixa de diálogo
         oDialog2.Center(oDialog1)
         lExec = oDialog2.Execute()
         Select Case lExec
             ...
     End Sub
  

     def triggerEvent(event: uno):
       dlg1 = CreateScriptService('DialogEvent.Dialog', event)  # A caixa de diálogo que provocou o evento
       dlg2 = CreateScriptService('Dialog', ...)  # Abrir uma segunda caixa de diálogo
       dlg2.Center(dlg1)
       rc = dlg2.Execute()
       if rc is False:
         # ...
   

CloneControl

Duplique um controlo existente de qualquer tipo na caixa de diálogo atual. O controlo duplicado permanece inalterado e pode ser reposicionado.

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

SourceName: O nome do controlo a duplicar.

ControlName: Um nome de controlo válido, expresso como uma cadeia de caracteres que distingue maiúsculas de minúsculas. Não pode já existir.

Esquerda, Topo: As coordenadas do novo controlo expressas em unidades Map AppFont.

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

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

Controls

Devolva uma das seguintes opções:

• a lista dos controlos contidos na caixa de diálogo

• uma instância da classe DialogControl com base no seu nome

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

svc.Controls(controlname: str): svc

ControlName : Um nome de controlo válido, expresso como uma cadeia de caracteres que distingue maiúsculas de minúsculas. Se não for indicado, a lista de nomes de controlos é devolvida como um array com índice a partir de zero.

      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

Cria um novo controlo do tipo Button na caixa de diálogo atual.

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

ControlName: o nome do novo controlo. Este ainda não pode existir.

Local: ou …

• um Array do Basic ou uma tupla do Python com 4 elementos: (X, Y, largura, altura)

• um objeto com.sun.star.awt.Rectangle [X, Y, Largura, Altura]

Todos os elementos são expressos em unidades Map AppFont.

Alternar: quando True, é criado um botão de alternância. Valor predefinido = False

Clicar em: «OK», «CANCELAR» ou «» (predefinição)

Uma instância do serviço SFDialogs.DialogControl ou Nothing.

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

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

CreateCheckBox

Cria um novo controlo do tipo CheckBox na caixa de diálogo atual.

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

MultiLine: Quando True (valor predefinido = False), a legenda pode ser apresentada em mais do que uma linha.

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

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

CreateComboBox

Cria um novo controlo do tipo ComboBox na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

DropDown: Quando True (por predefinição), é apresentado um botão de menu suspenso

LineCount: Especifica o número máximo de linhas apresentadas no menu suspenso (valor predefinido = 5)

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

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

CreateCurrencyField

Cria um novo controlo do tipo CurrencyField na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

SpinButton: quando True (valor predefinido = False), existe um botão giratório

MinValue: o valor mais baixo que pode ser introduzido no controlo. Valor predefinido = -1000000

MaxValue: o valor máximo que pode ser introduzido no controlo. Valor predefinido = +1000000

Incremento: o valor em que o botão giratório avança quando é premido. Padrão = 1

Precisão: especifica a precisão decimal. Valor predefinido = 2 algarismos decimais

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

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

CreateDateField

Cria um novo controlo do tipo DateField na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

DropDown: quando True (valor predefinido = False), é apresentado um botão de menu suspenso

MinDate: a data mais antiga que pode ser introduzida no controlo. Valor predefinido = 1900-01-01

MaxDate: a data mais tardia que pode ser introduzida no controlo. Valor predefinido = 31-12-2200

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

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

CreateFileControl

Cria um novo controlo do tipo FileControl na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

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

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

CreateFixedLine

Cria um novo controlo do tipo FixedLine na caixa de diálogo atual.

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

Orientação: para a orientação horizontal, utilize «H» ou «Horizontal»; para a orientação vertical, utilize «V» ou «Vertical».

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

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

CreateFixedText

Cria um novo controlo do tipo FixedText na caixa de diálogo atual.

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

Borda: «NENHUMA» (predefinição), «PLANA» ou «3D»

Multiline: Quando True (valor predefinido = False), a legenda pode ser apresentada em mais do que uma linha

Alinhar: alinhamento horizontal, «LEFT» (padrão), «CENTER» ou «RIGHT»

VerticalAlign: alinhamento vertical, «TOP» (padrão), «MIDDLE» ou «BOTTOM»

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

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

CreateFormattedField

Cria um novo controlo do tipo FormattedField na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

SpinButton: quando True (valor predefinido = False), existe um botão giratório

MinValue: o valor mais baixo que pode ser introduzido no controlo. Valor predefinido = -1000000

MaxValue: o valor máximo que pode ser introduzido no controlo. Valor predefinido = +1000000

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

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

CreateGroupBox

Cria um novo controlo do tipo GroupBox na caixa de diálogo atual.

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

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

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

CreateHyperlink

Cria um novo controlo do tipo Hyperlink na caixa de diálogo atual.

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

Borda: «NENHUMA» (predefinição), «PLANA» ou «3D»

MultiLine: Quando True (valor predefinido = False), a legenda pode ser apresentada em mais do que uma linha

Alinhar: alinhamento horizontal, «ESQUERDA» (predefinição), «CENTRO» ou «DIREITA»

VerticalAlign: alinhamento vertical, «TOP» (padrão), «MIDDLE» ou «BOTTOM»

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

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

CreateImageControl

Cria um novo controlo do tipo ImageControl na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

Escala: Um dos seguintes valores: «FITTOSIZE» (padrão), «KEEPRATIO» ou «NO»

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

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

CreateListBox

Cria um novo controlo do tipo ListBox na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

DropDown: Quando True (por predefinição), é apresentado um botão de menu suspenso

LineCount: Especifica o número máximo de linhas apresentadas no menu suspenso (valor predefinido = 5)

MultiSelect: Quando True, é possível selecionar mais de uma entrada. Valor predefinido = False

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

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

CreateNumericField

Cria um novo controlo do tipo NumericField na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

SpinButton: quando True (valor predefinido = False), existe um botão giratório

MinValue: o valor mais baixo que pode ser introduzido no controlo. Valor predefinido = -1000000

MaxValue: o valor máximo que pode ser introduzido no controlo. Valor predefinido = +1000000

Incrimento: o valor em que o botão giratório avança quando é premido. Valor predefinido = 1

Precisão: especifica a precisão decimal. Valor predefinido = 2 algarismos decimais

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

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

CreatePatternField

Cria um novo controlo do tipo PatternField na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

EditMask: um código de caractere que determina o que o utilizador pode introduzir
Consulte Pattern_Field na wiki para obter mais informações.

LiteralMask: contém os valores iniciais que são apresentados no campo de padrão

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

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

CreateProgressBar

Cria um novo controlo do tipo ProgressBar na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

MinValue: o valor mais baixo que pode ser introduzido no controlo. Valor predefinido = 0

MaxValue: o valor máximo que pode ser introduzido no controlo. Valor predefinido = 100

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

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

CreateRadioButton

Cria um novo controlo do tipo RadioButton na caixa de diálogo atual.

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

MultiLine: Quando True (valor predefinido = False), a legenda pode ser apresentada em mais do que uma linha

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

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

CreateScrollBar

Cria um novo controlo do tipo ScrollBar na caixa de diálogo atual.

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

Orientação: para a orientação horizontal, utilize «H» ou «Horizontal»; para a orientação vertical, utilize «V» ou «Vertical».

Borda: «3D» (predefinição), «FLAT» ou «NONE»

MinValue: o valor mais baixo que pode ser introduzido no controlo. Valor predefinido = 0

MaxValue: o valor máximo que pode ser introduzido no controlo. Valor predefinido = 100

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

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

CreateTableControl

Cria um novo controlo do tipo TableControl na caixa de diálogo atual.

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

Borda: «3D» (predefinição), «FLAT» ou «NONE»

RowHeaders: quando True (por predefinição), os cabeçalhos das linhas são apresentados

ColumnHeaders: quando True (por predefinição), os cabeçalhos das colunas são apresentados

Barras de deslocamento: os valores possíveis são: «H» ou «Horizontal» (barras de deslocamento horizontais), «V» ou «Vertical» (barras de deslocamento verticais); «B» ou «Both» (ambas as barras de deslocamento); «N» ou «None» (predefinição) para não apresentar barras de deslocamento. As barras de deslocamento aparecem dinamicamente quando são necessárias.

GridLines: quando True (valor predefinido = False), são desenhadas linhas horizontais e verticais entre as células da grelha

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

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

CreateTabPageContainer

Cria um novo controlo do tipo TabPageContainer na caixa de diálogo atual. As separadores são distribuídas por linhas separadas dentro da caixa de diálogo, quando necessário. Não é suportada a existência de vários TabPageContainer.

A criação do controlo TabPageContainer ocorre sempre em último lugar na criação de uma caixa de diálogo.

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

TabHeaders: Um conjunto de cadeias de caracteres que define cada rótulo individual das separadores

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

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

     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

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 = "")

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

     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

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

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

     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

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

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

     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.

      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
   

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

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

     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.

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

     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

Returns True when successful.

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

     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

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

     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.

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

    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:

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

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

Todas as rotinas ou identificadores do ScriptForge Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.