Conteúdo

# 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

Nome | Somente leitura | Tipo | Descrição
--- | --- | --- | ---
OKBUTTON | Sim | Integer | Valor = 1. Foi premido o botão «OK».
CANCELBUTTON | Sim | Integer | Valor = 0. Foi premido o botão «Cancelar».
Caption | Não | String | Indique o título da caixa de diálogo.
Height | Não | Long | Especifique a altura da caixa de diálogo.
IsAlive | Sim | Boolean | True quando a caixa de diálogo não tiver sido fechada (por exemplo, por uma ação do utilizador).
Modal | Sim | Boolean | Especifica se a caixa de diálogo está atualmente a ser executada no modo modal.
Name | Sim | String | O nome da caixa de diálogo
Page | Não | Integer | Uma caixa de diálogo pode ter várias páginas que o utilizador pode percorrer passo a passo. A propriedade Page do objeto Dialog define qual a página da caixa de diálogo que está ativa
Visible | Não | Boolean | Especifique se a caixa de diálogo está visível no ambiente de trabalho. Por predefinição, não está visível até que o método Execute() seja executado, tornando-se visível a seguir.
XDialogModel | Sim | objeto UNO | O objeto UNO que representa o modelo de diálogo. Consulte XControlModel e UnoControlDialogModel na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.
XDialogView | Sim | objeto UNO | O objeto UNO que representa a vista de diálogo. Consulte XControl e UnoControlDialog na documentação da Interface de Programação de Aplicações (API) para obter informações detalhadas.
Width | Não | Long | Especifique a largura da caixa de diálogo.

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

Nome | Descrição básica do IDE
--- | ---
OnFocusGained | Ao receber o foco
OnFocusLost | Quando se perde a concentração
OnKeyPressed | Tecla premida
OnKeyReleased | Chave libertada
OnMouseDragged | O rato moveu-se enquanto se premiam as teclas
OnMouseEntered | Rato dentro
OnMouseExited | Rato lá fora
OnMouseMoved | O rato moveu-se
OnMousePressed | Botão do rato premido
OnMouseReleased | Botão do rato solto

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.

Lista de métodos do Serviço de Diálogo
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

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.

### Sintaxe:

svc.Activate(): bool

### Exemplo:

          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.

### Sintaxe:

svc.Center(opt Parent: obj): bool

### Parâmetros:

Pai: Um objeto opcional que pode ser…

- um objeto de caixa de diálogo do ScriptForge

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

### Exemplo:

##### Em Basic

         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

##### Em Python

         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.

### Sintaxe:

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

### Parâmetros:

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.

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

         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

### Sintaxe:

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

svc.Controls(controlname: str): svc

### Parâmetros:

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.

### Exemplo:

          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.

### Sintaxe:

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

### Parâmetros:

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)

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateCheckBox

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateComboBox

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

### Sintaxe:

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

### Parâmetros:

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.

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)

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateCurrencyField

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateDateField

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateFileControl

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateFixedLine

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateFixedText

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

### Sintaxe:

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

### Parâmetros:

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.

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»

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateFormattedField

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateGroupBox

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

### Sintaxe:

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

### Parâmetros:

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.

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateHyperlink

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

### Sintaxe:

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

### Parâmetros:

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.

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»

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateImageControl

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

### Sintaxe:

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

### Parâmetros:

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.

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

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateListBox

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

         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.

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreatePatternField

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

         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.

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateRadioButton

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateScrollBar

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateTableControl

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

         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.

### Sintaxe:

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

### Parâmetros:

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.

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

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

         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.

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateTimeField

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

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

## CreateTreeControl

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

### Sintaxe:

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

### Parâmetros:

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.

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

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

         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.

### Sintaxe:

svc.EndExecute(returnvalue: int)

### Parâmetros:

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

### Exemplo:

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

##### Em Python

         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.

### Sintaxe:

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

### Parâmetros:

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

### Exemplo:

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:

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

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.

### Sintaxe:

svc.GetTextsFromL10N(l10n: svc): bool

### Parâmetros:

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

### Exemplo:

O exemplo seguinte carrega as cadeias traduzidas e aplica-as à caixa de diálogo «MyDialog».

##### Em Basic

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

##### Em Python

         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.

### Sintaxe:

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

### Parâmetros:

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.

### Tipo de retorno:

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

### Exemplo:

##### Em Basic

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

##### Em Python

         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

### Sintaxe:

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

### Parâmetros:

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

### Tipo de retorno:

Devolve True em caso de sucesso.

### Exemplo:

##### Em Basic

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

##### Em Python

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

## Resize

Devolve True em caso de sucesso.

### Sintaxe:

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

### Parâmetros:

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

### Exemplo:

##### Em Basic

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

##### Em Python

         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.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

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.

##### Em Basic

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

##### Em Python

        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.

### Sintaxe:

svc.Terminate(): bool

### Exemplo:

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:

##### Em Basic

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

##### Em Python

         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.

Tópicos relacionados

SFDialogs.DialogControl serviço

ScriptForge.UI service

Necessitamos da sua ajuda!