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

Borda: «3D» (predefinição), «FLAT» ou «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

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

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

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

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

MaximumLength: o número máximo de caracteres (valor predefinido = 0, o que significa ilimitado)

PasswordCharacter: um único carácter que especifica o texto de eco para um campo de texto de palavra-passe (valor predefinido = "")

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

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

CreateTimeField

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

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

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

MinTime: o valor mínimo de tempo que pode ser introduzido no controlo. Valor predefinido = 0

MaxTime: o valor máximo de tempo que pode ser introduzido no controlo. Valor predefinido = 24h

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

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

CreateTreeControl

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

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

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

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

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

EndExecute

Encerra a exibição de uma caixa de diálogo modal e devolve o argumento como valor de retorno para a ação Execute() atualmente em execução.

EndExecute() surge normalmente no âmbito do processamento de uma macro acionada por um evento de caixa de diálogo ou de controlo.

svc.EndExecute(returnvalue: int)

returnvalue: O valor passado ao método Execute() em execução.

      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)
   

As menções acima a com.sun.star.lang.EventObject são opcionais. Essas anotações ajudam a identificar a Interface de Programação de Aplicações (API) do LibreOffice.

Execute

Apresentar a caixa de diálogo e, caso seja modal, aguardar que o utilizador a feche. O valor devolvido pode ser:

• 0 : Botão Cancelar premido

• 1 : Botão OK premido

• Caso contrário, a caixa de diálogo foi interrompida por uma instrução EndExecute() emitida por um evento da caixa de diálogo ou do controlo

No caso das caixas de diálogo não modais, o método devolve sempre 0 e a execução da macro prossegue.

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

modal: False no caso de uma caixa de diálogo não modal. Valor predefinido = True.

Neste exemplo básico, a caixa de diálogo myDialog está armazenada na biblioteca Standard do documento atual.

      Dim oDlg As Object, lReturn As Long
      Set oDlg = CreateScriptService("SFDialogs.Dialog", , , "myDialog")
      lReturn = oDlg.Execute(Modal := False)
      Select Case lReturn
          ' ...
      End Select
   

Este código Python apresenta a caixa de diálogo modal DlgConvert da biblioteca Basic partilhada Euro.

     dlg = CreateScriptService("SFDialogs.Dialog", 'GlobalScope', 'Euro', "DlgConvert")
     rc = dlg.Execute()
     if rc == dlg.CANCELBUTTON:
         # ...
   

GetTextsFromL10N

Substitui todas as cadeias de texto fixas numa caixa de diálogo pelas respetivas versões traduzidas, com base numa instância do serviço L10N. Este método traduz as seguintes cadeias de texto:

O método devolve True se for bem-sucedido.

Para criar uma lista de cadeias traduzíveis numa caixa de diálogo, utilize o método AddTextsFromDialog do serviço L10N.

svc.GetTextsFromL10N(l10n: svc): bool

l10n: Uma instância do serviço L10N a partir da qual serão recuperadas as cadeias traduzidas.

O exemplo seguinte carrega as cadeias traduzidas e aplica-as à caixa de diálogo «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()
   

Leia a página de ajuda do serviço L10N para saber mais sobre como os ficheiros PO e POT são tratados.

ImportControl

Importar e duplicar um controlo existente de qualquer tipo de uma caixa de diálogo para a caixa de diálogo atual. O controlo duplicado permanece inalterado. O novo controlo pode ser renomeado e reposicionado. Os manipuladores de eventos, quando existentes, também podem ser importados.

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

SourceDialog: uma instância da classe SFDialogs.Dialog.

SourceName: o nome do controlo a importar.

ControlName: o nome do novo controlo. Este nome ainda não pode existir. O valor predefinido é SourceName

Página: o número da página do novo controlo. Valor predefinido = 0

OffsetX, OffsetY: o número de píxeis a adicionar às coordenadas do controlo de origem em unidades «Map AppFont». Valor predefinido = 0; pode ser negativo.

IncludeOnProperties: inclui as propriedades do evento On.... Valor predefinido = False.

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

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

OrderTabs

Define o índice de tabulação de uma série de controlos. A sequência de controlos é indicada como uma matriz de nomes de controlos, do primeiro ao último.

Os controlos com um índice >= 1 não são acessíveis com a tecla TAB se:
- estiverem omitidos da lista indicada
- forem do tipo FixedLine, GroupBox ou ProgressBar
- estiverem desativados

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

TabsList: um array de nomes de controlos válidos, por ordem de tabulação

Início: o índice de tabulação a atribuir ao primeiro controlo da lista. Valor predefinido = 1

Incremento: a diferença entre dois índices de tabulação sucessivos. Valor predefinido = 1

Devolve True em caso de sucesso.

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

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

Resize

Devolve True em caso de sucesso.

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

Esquerda: a distância horizontal a partir do canto superior esquerdo

Top: a distância vertical a partir do canto superior esquerdo

Largura: a largura do retângulo que contém a caixa de diálogo

Altura: a altura do retângulo que contém a caixa de diálogo

Os argumentos em falta permanecem inalterados

     oDlg.Resize(1000, 2000, Height := 6000) ' A largura não é alterada
   

     dlg.Resize(1000, 2000, Height = 6000)  # A largura não é alterada
   

SetPageManager

Define quais os controlos numa caixa de diálogo que são responsáveis pela alternância entre páginas, facilitando a gestão da propriedade Page de uma caixa de diálogo e dos seus controlos.

As caixas de diálogo podem ter várias páginas e a página atualmente visível é definida pela propriedade Page da caixa de diálogo. Se a propriedade Page não for alterada, a página visível por predefinição é igual a 0 (zero), o que significa que não está definida nenhuma página específica e que todos os controlos visíveis são apresentados, independentemente do valor definido na respetiva propriedade Page.

Quando a propriedade Page de uma caixa de diálogo é alterada para outro valor, como 1, 2, 3 e assim por diante, apenas os controlos cuja propriedade Page corresponda à página atual da caixa de diálogo serão apresentados.

Ao utilizar o método SetPageManager, é possível definir quatro tipos de gestores de páginas:

• Caixa de lista ou caixa combinada: neste caso, cada entrada na caixa de lista ou na caixa combinada corresponde a uma página. O primeiro item refere-se à Página 1, o segundo item refere-se à Página 2 e assim sucessivamente.

• Grupo de botões de opção: define um grupo de botões de opção que determinará qual a página que fica visível.

• Sequência de botões: define um conjunto de botões, cada um dos quais correspondendo a uma página da caixa de diálogo. Isto pode ser utilizado para simular uma interface com separadores, colocando os botões lado a lado na caixa de diálogo.

• Botões Anterior/Seguinte: define quais os botões da caixa de diálogo que serão utilizados para navegar para a página Anterior/Seguinte na caixa de diálogo.

É possível utilizar mais do que um mecanismo de gestão de páginas ao mesmo tempo.

Este método deve ser chamado apenas uma vez antes de se chamar o método Execute. As chamadas subsequentes são ignoradas.

Se for bem-sucedido, este método devolve True.

svc.SetPageManager(pilotcontrols: str = "", tabcontrols: str = "", wizardcontrols: str = "", opt lastpage: int): bool

pilotcontrols: uma lista separada por vírgulas de nomes de controlos ListBox, ComboBox ou RadioButton utilizados como gestores de páginas. No caso dos controlos RadioButton, especifique o nome do primeiro controlo do grupo a utilizar.

tabcontrols: uma lista, separada por vírgulas, de nomes de botões que serão utilizados como gestores de páginas. A ordem em que são especificados neste argumento corresponde ao número da página a que estão associados.

wizardcontrols: uma lista separada por vírgulas com os nomes de dois botões que serão utilizados como botões «Anterior»/«Seguinte».

lastpage: o número da última página disponível. Recomenda-se especificar este valor ao utilizar o gestor de páginas Anterior/Seguinte.

Considere uma caixa de diálogo com três páginas. A caixa de diálogo possui um controlo ListBox denominado «aPageList», que será utilizado para controlar a página visível. Além disso, existem dois botões denominados «btnPrevious» e «btnNext», que serão utilizados como botões «Anterior» e «Seguinte» na caixa de diálogo.

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

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

Terminate

Encerra o serviço Dialog para a instância atual. Devolve True se o encerramento tiver sido bem-sucedido.

svc.Terminate(): bool

Os exemplos em Basic e Python abaixo abrem as caixas de diálogo não modais DlgConsole e dlgTrace. Estas estão armazenadas, respetivamente, nas bibliotecas partilhadas ScriptForge e Access2Base. Os botões de fecho das caixas de diálogo estão desativados e o encerramento explícito é efetuado no final de um processo em execução.

Neste exemplo, um botão no DlgConsole impede o encerramento da janela:

     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.