Serviço SFDatabases.Datasheet

Sumário

# Serviço SFDatabases.Datasheet service

O serviço Datasheet permite visualizar o conteúdo das tabelas do banco de dados, bem como os resultados das consultas e instruções SQL usando o Data View do Base. Adicionalmente, este serviço permite:

- Adicionar menus personalizados à exibição de dados.

- Acessar valores em posições específicas da exibição de dados.

- Posicionar o cursor em uma célula específica da exibição de dados.

## Invocação do serviço

Antes de usar o serviço Datasheet, a biblioteca ScriptForge precisa ser carregada ou importada:

• Macros BASIC precisam carregar a biblioteca ScriptForge usando a seguinte instrução:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Scripts Python exigem uma importação do módulo scriptforge:
from scriptforge import CreateScriptService

##### Em Basic

O serviço Datasheet pode ser invocado de duas maneiras diferentes dependendo se o arquivo de banco de dados estiver aberto.

O exemplo abaixo considera que o arquivo do banco de dados está aberto, assim o serviço UI pode ser usado para recuperar o documento e o método OpenTable do serviço Database é usado para obter a 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 usar o método OpenQuery do serviço Base para obter uma instância do serviço Datasheet.

Para invocar o serviço Datasheet quando o arquivo do banco de dados não estiver aberto, use os métodos OpenTable, OpenQuery ou OpenSql do serviço Database. O exemplo abaixo usa o método OpenTable para abrir uma tabela que existe no arquivo de banco 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 maneira:

        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 | Somente leitura | Tipo | Descrição
--- | --- | --- | ---
ColumnHeaders | Sim | Array de Strings | Retorna um Array com os nomes dos cabeçalhos das colunas em uma folha de dados.
CurrentColumn | Sim | String | Retorna o nome da coluna atualmente selecionada.
CurrentRow | Sim | Integer | Retorna o número da linha atualmente selecionada, começando em 1.
DatabaseFileName | Sim | String | Retorna o nome do arquivo Base no formato FSO.FileNaming.
Filter | Não | String | Especifica um filtro a ser aplicado à folha de dados expresso como uma cláusula WHERE de uma consulta SQL sem a palavra-chave WHERE. Se uma String vazia for fornecida então o filtro Filter ativo é removido.
IsAlive | Sim | Boolean | True when the datasheet has not been closed (f.i. by a user action).
LastRow | Sim | Integer | Retorna o número de linhas na folha de dados.
MenuHeaders | Sim | String array | Returns a list with the menu names present in the menubar.
OrderBy | Não | String | Especifica a ordem em que os registros são mostrados expresso como uma cláusula ORDER BY de uma consulta SQL sem a palavra-chave ORDER BY. Se uma string vazia for especificada o valor OrderBy ativo é removido.
ParentDatabase | Sim | Objeto | Retorna a instância do serviço Database à qual a folha de dados pertence.
Source | Sim | String | Retorna uma String representando a fonte de dados, a qual pode ser um comando SQL, um nome de tabela ou um nome de consulta.
SourceType | Sim | String | Retorna o tipo da fonte de dados, o qual pode ser um dos seguintes valores: "SQL", "TABLE" ou "QUERY".
XComponent | Sim | Objeto UNO | Retorna o objeto UNO com.sun.star.lang.XComponent que representa a folha de dados.
XControlModel | Sim | Objeto UNO | Retorna o objeto UNO com.sun.star.awt.XControl que representa a folha de dados.
XTabControllerModel | Sim | Objeto UNO | Retorna o objeto UNO com.sun.star.awt.XTabControllerModel que representa a folha de dados.

## Métodos

Lista de Métodos no Serviço Datasheet
Activate CloseDatasheet CreateMenu | GetText GetValue GoToCell | RemoveMenu Toolbars

## Activate

Traz para frente a janela de vista de dados correspondente à instância Datasheet.

### Sintaxe:

svc.Activate()

### Exemplo:

##### Em Basic

          oSheet.Activate()

##### Em Python

          sheet.Activate()

## CloseDatasheet

Fecha a janela de vista de dados correspondente à 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 vista de dados e retorna uma instância do serviço SFWidgets.Menu, com a qual itens de menu podem ser adicionados programaticamente.

Menus adicionados usando o método CreateMenu são perdidos assim que a janela de vista de dados é fechada.

### Sintaxe:

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

### Parâmetros:

menuheader: Nome do novo menu.

before: Este argumento pode ser o nome de uma entrada existente no menu antes da qual o novo menu será posicionado ou um número expressando a posição do novo menu. Se este argumento estiver em branco o novo menu será colocado na última posição.

submenuchar: Delimitador usado em árvores de menu (Padrão=">")

### Exemplo:

##### Em Basic

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

##### Em Python

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

Leia a página de ajuda do serviço Menu para aprender mais sobre como criar menus, submenus e associar comandos a eles.

## GetText

Retorna o texto em uma dada coluna da linha atual.

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

### Sintaxe:

svc.GetText(column: any): str

### Parâmetros:

column: O nome da coluna como uma String or a posição da coluna (começando em 1). Se uma posição maior que o número de colunas for dada, a última coluna é retornada.

### Exemplo:

##### Em Basic

          oSheet.GetText("FirstName")

##### Em Python

          sheet.GetText("FirstName")

## GetValue

Retorna o valor em uma dada coluna da linha atual como um tipo de dados Basic válido.

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

Tipos binários são retornados como um valor Long indicando o comprimento do campo binário.

Um valor Empty é retornado se o valor requerido não pode ser recuperado.

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

### Sintaxe:

svc.GetValue(column: any): any

### Parâmetros:

column: O nome da coluna como uma String or a posição da coluna (começando em 1). Se uma posição maior que o número de colunas for dada, a última coluna é retornada.

### Exemplo:

##### Em Basic

          oSheet.GetValue("Address")

##### Em Python

          sheet.GetValue("Address")

## GoToCell

Move o cursor para a linha e coluna especificadas.

### Sintaxe:

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

### Parâmetros:

row: Número da linha como um valor numérico começando em 1. Se a linha requerida exceder o número existente de linhas, o cursor é movido para a última linha. Se este argumento não for especificado, então a linha não é modificada.

column: O nome da coluna como uma String ou a posição da coluna (começando em 1). Se a coluna requerida exceder o número existente de colunas, o cursor é movido para a última coluna. Se este argumento não for especificado, então a coluna não é modificada.

### Exemplo:

##### Em Basic

          ' Move o cursor para a coluna "UltimoNome" na linha 4
          oSheet.GoToCell(4, "UltimoNome")
          ' Move o cursor para a terceira coluna da linha atual
          oSheet.GoToCell(Column := 3)
          ' Move o cursor uma linha para baixo deixando-o na mesma coluna
          oSheet.GoToCell(Row := oSheet.CurrentRow + 1)
          ' Move o cursor 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, "UltimoNome")
          sheet.GoToCell(column=3)
          sheet.GoToCell(row=sheet.CurrentRow + 1)
          sheet.GoToCell(sheet.LastRow, len(sheet.ColumnHeaders))

## RemoveMenu

Remove uma entrada do menu da janela de vista de dados com base em seu nome.

Este método é capaz de remover menus que pertencem à interface de usuário padrão e menus que foram adicionados programaticamente com o método CreateMenu. A remoção de menus padrão não é permanente e eles serão restaurados após a janela ter sido fechada e aberta novamente.

### Sintaxe:

svc.RemoveMenu(menuheader: str): bool

### Parâmetros:

menuheader: Nome do menu a ser removido, sensível à caixa. O nome não deve incluir o caractere til ("~").

### Exemplo:

##### Em Basic

          oSheet.RemoveMenu("Data")

##### Em Python

          sheet.RemoveMenu("Data")

### Toolbars

Este método retorna uma lista dos nomes das barras de ferramentas disponíveis no documento atual ou uma SFWidgets.Toolbarinstância do serviço.

### Sintaxe:

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

### Parâmetros:

toolbarname: The usual name of one of the available toolbars.

### 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 em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.

Tópicos relacionados

Serviço SFDatabases.Database

Serviço ScriptForge.UI

♥ Doe para nosso projeto! ♥