Conteúdo

# SFDatabases.Datasheet service

O serviço Datasheet permite visualizar o conteúdo das tabelas da base de dados, bem como os resultados de consultas e instruções SQL, utilizando a Visualização de Dados do Base. Além disso, este serviço permite:

- Coloque o cursor numa célula específica da visualização de dados.

- Aceder aos valores em posições específicas da visualização de dados.

- Coloque o cursor numa célula específica da visualização de dados.

## Chamada de serviço

Antes de utilizar o serviço Datasheet, é 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

##### Em Basic

O serviço Datasheet pode ser invocado de duas formas diferentes, dependendo se o ficheiro da base de dados está aberto.

O exemplo abaixo parte do princípio de que o ficheiro da base de dados está aberto; por isso, o serviço UI pode ser utilizado para recuperar o documento e o método OpenTable do serviço Database é utilizado para obter uma instância do serviço Datasheet.

        Dim ui As Object, oBase As Object, oSheet As Object
        Set ui = CreateScriptService("UI")
        ' O objeto oBase é uma instância do serviço Base
        Set oBase = ui.GetDocument("C:\Documents\myDB.odb")
        ' O objeto oSheet é uma instância do serviço Datasheet
        Set oSheet = oBase.OpenTable("Customers")

No exemplo acima, também é possível utilizar o método OpenQuery do serviço Base para obter uma instância de Datasheet.

Para invocar o serviço Datasheet quando o ficheiro da base de dados não estiver aberto, utilize os métodos OpenTable, OpenQuery ou OpenSql do serviço Database. O exemplo abaixo utiliza o método OpenTable para abrir uma tabela existente no ficheiro da base de dados:

        Dim oDatabase As Object, oSheet As Object
        ' O objeto oDatabase é uma instância do serviço Database
        Set oDatabase = CreateScriptService("Database", "C:\Documents\myDB.odb")
        ' O objeto oSheet é uma instância do serviço Datasheet
        Set oSheet = oDatabase.OpenTable("Customers")

##### Em Python

Os exemplos acima podem ser traduzidos para Python da seguinte forma:

        from scriptforge import CreateScriptService
        ui = CreateScriptService("UI")
        base_doc = ui.GetDocument(r"C:\Documents\MyFile.odb")
        sheet = base_doc.OpenTable("Customers")

        database = CreateScriptService("Database", r"C:\Documents\myDB.odb")
        sheet = database.OpenTable("Customers")

## Propriedades

As seguintes propriedades estão disponíveis no serviço Datasheet:

Nome | Apenas leitura | Tipo | Descrição
--- | --- | --- | ---
ColumnHeaders | Sim | Matriz de cadeias de caracteres | Devolve um Array com os nomes dos cabeçalhos das colunas da folha de dados.
CurrentColumn | Sim | String | Devolve o nome da coluna atualmente selecionada.
CurrentRow | Sim | Integer | Devolve o número da linha atualmente selecionada, começando por 1.
DatabaseFileName | Sim | String | Devolve o nome do ficheiro «Base» no formato FSO.FileNaming.
Filter | Não | String | Especifica um filtro a aplicar à folha de dados, expresso como a cláusula WHERE de uma consulta SQL, sem a palavra-chave WHERE. Se for especificada uma cadeia de caracteres vazia, o Filtro ativo é removido.
IsAlive | Sim | Boolean | True quando a ficha técnica não foi fechada (por exemplo, por ação do utilizador).
LastRow | Sim | Integer | Devolve o número de linhas da folha de dados.
MenuHeaders | Sim | String array | Devolve uma lista com os nomes dos menus presentes na barra de menus.
OrderBy | Não | String | Especifica a ordem em que os registos são apresentados, expressa como a cláusula ORDER BY de uma consulta SQL, sem a palavra-chave ORDER BY. Se for especificada uma cadeia de caracteres vazia, a cláusula OrderBy ativa é removida.
ParentDatabase | Sim | Objeto | Devolve a instância do serviço Database à qual a ficha de dados pertence.
Source | Sim | String | Devolve uma cadeia de caracteres que representa a fonte de dados, que pode ser uma instrução SQL, o nome de uma tabela ou o nome de uma consulta.
SourceType | Sim | String | Devolve o tipo da fonte de dados, que pode ser um dos seguintes valores: «SQL», «TABLE» ou «QUERY».
XComponent | Sim | Objeto UNO | Devolve o objeto UNO com.sun.star.lang.XComponent que representa a ficha de dados.
XControlModel | Sim | Objeto UNO | Devolve o objeto com.sun.star.awt.XControl UNO que representa a ficha de dados.
XTabControllerModel | Sim | Objeto UNO | Devolve o objeto UNO com.sun.star.awt.XTabControllerModel que representa a ficha de dados.

## Métodos

Lista de métodos do serviço «Ficha técnica»
Activate CloseDatasheet CreateMenu | GetText GetValue GoToCell | RemoveMenu Toolbars

## Activate

Traz para o primeiro plano a janela de visualização de dados a que se refere a instância Datasheet.

### Sintaxe:

svc.Activate()

### Exemplo:

##### Em Basic

          oSheet.Activate()

##### Em Python

          sheet.Activate()

## CloseDatasheet

Fecha a janela de visualização de dados a que se refere a instância Datasheet.

### Sintaxe:

svc.CloseDatasheet()

### Exemplo:

##### Em Basic

          oSheet.CloseDatasheet()

##### Em Python

          sheet.CloseDatasheet()

## CreateMenu

Cria uma nova entrada de menu na janela de visualização de dados e devolve uma instância do serviço SFWidgets.Menu, com a qual é possível adicionar itens de menu por via de programação.

Os menus adicionados através do método CreateMenu desaparecem assim que a janela de visualização de dados for fechada.

### Sintaxe:

svc.CreateMenu(menuheader: str, opt before: any, opt submenuchar: str): obj

### Parâmetros:

menuheader: O nome do novo menu.

antes de: Este argumento pode ser o nome de uma entrada de menu existente, antes da qual o novo menu será colocado, ou um número que indique a posição do novo menu. Se este argumento for deixado em branco, o novo menu será colocado como a última entrada.

submenuchar: O delimitador utilizado nas árvores de menus (Predefinição = ">")

### Exemplo:

##### Em Basic

          Dim oMenu As Object
          Set oMenu = oSheet.CreateMenu("O meu menu", Before := "Dados")
          With oMenu
              .AddItem("Item 1", Command := ".uno:About")
              ' ...
              .Dispose()
          End With

##### Em Python

          menu = sheet.CreateMenu("O meu menu", before="Dados")
          menu.AddItem("Item 1", command=".uno:About")
          # ...
          menu.Dispose()

Leia a página de ajuda do serviço Menu para saber mais sobre como criar entradas de menu e submenu e associar comandos.

## GetText

Devolve o texto de uma determinada coluna da linha atual.

Este método não altera a posição do cursor na janela de visualização de dados.

### Sintaxe:

svc.GetText(column: any): str

### Parâmetros:

coluna: O nome da coluna como uma String ou a posição da coluna (a partir de 1). Se for indicada uma posição superior ao número de colunas, é devolvida a última coluna.

### Exemplo:

##### Em Basic

          oSheet.GetText("FirstName")

##### Em Python

          sheet.GetText("FirstName")

## GetValue

Devolve o valor de uma determinada coluna da linha atual como um tipo Basic válido.

Os tipos que podem ser devolvidos são: String, Integer, Long, Single, Double, Date e Null.

Os tipos binários são devolvidos como um valor Long que indica o comprimento do campo binário.

É devolvido um valor Empty se não for possível recuperar o valor necessário.

Este método não altera a posição do cursor na janela de visualização de dados.

### Sintaxe:

svc.GetValue(column: any): any

### Parâmetros:

coluna: O nome da coluna como uma String ou a posição da coluna (começando em 1). Se for indicada uma posição superior ao número de colunas, é devolvida a última coluna.

### Exemplo:

##### Em Basic

          oSheet.GetValue("Address")

##### Em Python

          sheet.GetValue("Address")

## GoToCell

Desloca o cursor para a linha e coluna especificadas.

### Sintaxe:

svc.GoToCell(opt row: int, opt column: any): bool

### Parâmetros:

linha: O número da linha como um valor numérico, começando em 1. Se a linha solicitada exceder o número de linhas existentes, o cursor é deslocado para a última linha. Se este argumento não for especificado, a linha não é alterada.

coluna: O nome da coluna como uma String ou a posição da coluna (começando em 1). Se a coluna solicitada exceder o número de colunas existentes, o cursor é deslocado para a última coluna. Se este argumento não for especificado, a coluna não é alterada.

### Exemplo:

##### Em Basic

          ' Desloca o cursor para a coluna «LastName» na linha 4
          oSheet.GoToCell(4, "Apelido")
          ' Desloca o cursor para a terceira coluna da linha atual
          oSheet.GoToCell(Column := 3)
          ' Desloca o cursor uma linha para baixo, mantendo-o na mesma coluna
          oSheet.GoToCell(Row := oSheet.CurrentRow + 1)
          ' Passa para a última coluna da última linha
          Dim LastColumn As Integer : LastColumn = UBound(oSheet.ColumnHeaders) + 1
          oSheet.GoToCell(oSheet.LastRow, LastColumn)

##### Em Python

          sheet.GoToCell(4, "Apelido")
          sheet.GoToCell(column=3)
          sheet.GoToCell(row=sheet.CurrentRow + 1)
          sheet.GoToCell(sheet.LastRow, len(sheet.ColumnHeaders))

## RemoveMenu

Remove uma entrada do menu da visualização de dados com base no seu nome.

Este método permite remover menus que fazem parte da interface de utilizador padrão, bem como menus que foram adicionados programaticamente através do método CreateMenu. A remoção dos menus padrão não é permanente e estes voltarão a aparecer depois de a janela ser fechada e reaberta.

### Sintaxe:

svc.RemoveMenu(menuheader: str): bool

### Parâmetros:

menuheader: O nome do menu a remover, em que se distingue entre maiúsculas e minúsculas. O nome não pode incluir o carácter til ("~").

### Exemplo:

##### Em Basic

          oSheet.RemoveMenu("Data")

##### Em Python

          sheet.RemoveMenu("Data")

### Toolbars

Este método devolve uma lista dos nomes das barras de ferramentas disponíveis no documento em questão ou uma instância do serviço SFWidgets.Toolbar.

### Sintaxe:

svc.Toolbars(opt toolbarname: str): svc
svc.Toolbars(): str[0..]

### Parâmetros:

nome-da-barra-de-ferramentas: O nome habitual de uma das barras de ferramentas disponíveis.

### Exemplo:

##### Em Basic

        Dim oToolbar As Object
        Set oToolbar = oDoc.Toolbars("standard")

##### Em Python

        a_list = doc.Toolbars()

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

Serviço SFDatabases.Database

ScriptForge.UI service

Necessitamos da sua ajuda!