Sumário

# Serviço SFWidgets.ToolbarButton

O serviço ToolbarButton permite recuperar informações relacionadas aos botões da barra de ferramentas disponíveis em uma determinada barra de ferramentas. Com este serviço é possível:

- Alternar a visibilidade dos elementos da barra de ferramentas.

- Executar o comando associado a um determinado botão da barra de ferramentas.

## Invocação do serviço

Antes de usar o serviço ToolbarButton 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

O serviço ToolbarButton é invocado usando o método ToolbarButtons do serviço Toolbar.

##### Em Basic

O exemplo abaixo recupera os nomes de todos os botões disponíveis na barra de ferramentas Padrão.

        oDoc = CreateScriptService("Document", ThisComponent)
        oToolbar = oDoc.Toolbars("standardbar")
        arrToolbarButtons = oToolbar.ToolbarButtons()
        MsgBox SF_String.Represent(arrToolbarButtons)

Use o método ToolbarButtons sem argumentos para recuperar uma lista com todos os nomes de botões disponíveis na barra de ferramentas.

O exemplo abaixo alterna a visibilidade do botão Imprimir na barra de ferramentas Padrão:

        oDoc = CreateScriptService("Document", ThisComponent)
        oToolbar = oDoc.Toolbars("standardbar")
        oToolbarButton = oToolbar.ToolbarButtons("Imprimir")
        oToolbarButton.Visible = Not oToolbarButton.Visible

O nome do botão passado como argumento para o método ToolbarButtons é o nome do botão localizado definido na caixa de diálogo Ferramentas - Personalizar - Barras de ferramentas.

As barras de ferramentas inativas não possuem botões. Portanto, chamar o método ToolbarButtons tornará a barra de ferramentas visível.

##### Em Python

        bas = CreateScriptService("Basic")
        doc = CreateScriptService("Document", bas.ThisComponent)
        toolbar = doc.Toolbars("standardbar")
        arr_toolbar_buttons = toolbar.ToolbarButtons()
        bas.MsgBox(repr(arr_toolbar_buttons))

        bas = CreateScriptService("Basic")
        doc = CreateScriptService("Document", bas.ThisComponent)
        toolbar = doc.Toolbars("standardbar")
        toolbar_button = toolbar.ToolbarButtons("Imprimir")
        toolbar_button.Visible = not toolbar_button.Visible

## Propriedades

Nome | Somente leitura | Tipo | Descrição
--- | --- | --- | ---
Caption | Sim | String | Retorna o nome do botão.
Height | Sim | Long | Retorna a altura do botão, em pixels.
Index | Sim | Long | Retorna o índice do botão em sua barra de ferramentas pai.
OnClick | Não | String | Comando UNO ou script executado quando o botão é pressionado. Leia a página Scripting Framework URI Specification para aprender mais sobre como definir uma string URI.
Parent | Sim | Serviço Toolbar | Retorna uma instância do serviço Toolbar correspondente à barra de ferramentas pai do botão da barra de ferramentas atual.
TipText | Não | String | Especifica o texto da dica de ferramenta mostrado quando o usuário passa o mouse sobre o botão da barra de ferramentas.
Visible | Não | Boolean | Especifica se o botão da barra de ferramentas é visível ou não.
Width | Sim | Long | Retorna a largura do botão, em pixels.
X | Sim | Long | Retorna a coordenada X (horizontal) do botão, a partir do canto superior esquerdo, em pixels.
Y | Sim | Long | Retorna a coordenada Y (vertical) do botão, a partir do canto superior esquerdo, em pixels.

## Uso do serviço ToolbarButton juntamente com o serviço PopupMenu

Um caso de uso comum das propriedades X e Y descritas acima é abrir um menu pop-up na posição onde o botão da barra de ferramentas está localizado.

Suponha que você crie o script abaixo e o associe a um botão chamado "Meu botão" na barra de ferramentas standardbar. Ao clicar no botão, um menu pop-up será mostrado com 3 opções para o usuário selecionar.

##### Em Basic

        Sub OpenPopupMenu()
            GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
            oDoc = CreateScriptService("Document", ThisComponent)
            oToolbar = oDoc.Toolbars("standardbar")
            oButton = oToolbar.ToolbarButtons("Meu Botão")
            oPopup = CreateScriptService("SFWidgets.PopupMenu", , oButton.X, oButton.Y + oButton.Height)
            oPopup.AddItem("Item A", "A")
            oPopup.AddItem("Item B", "B")
            oPopup.AddItem("Item C", "C")
            strResponse = oPopup.Execute(False)
            MsgBox "Sua escolha: " & strResponse
        End Sub

##### Em Python

        def open_popup_menu(args=None):
            bas = CreateScriptService("Basic")
            doc = CreateScriptService("Document", bas.ThisComponent)
            toolbar = doc.Toolbars("standardbar")
            toolbutton = toolbar.ToolbarButtons("Meu Botão")
            popup = CreateScriptService("PopupMenu", None, toolbutton.X, toolbutton.Y + toolbutton.Height)
            popup.AddItem("Item A", "A")
            popup.AddItem("Item B", "B")
            popup.AddItem("Item C", "C")
            response = popup.Execute(False)
            bas.MsgBox(f"Sua escolha: {response}")

Lista de Métodos no Serviço ToolbarButton
Execute |  |

## Execute

Executa o comando ou script associado ao botão da barra de ferramentas.

Este método retorna o valor retornado pelo comando ou script executado.

Use a propriedade OnClick para determinar o comando ou script que deve ser executado. Se o comando/script não retornar nenhum valor, então Null será retornado.

### Sintaxe:

svc.Execute(): any

### Exemplo:

O exemplo abaixo executa o botão Imprimir da barra de ferramentas Padrão:

##### Em Basic

          oDoc = CreateScriptService("Document", ThisComponent)
          oToolbar = oDoc.Toolbars("standardbar")
          oToolbarButton = oToolbar.ToolbarButtons("Imprimir")
          oToolbarButton.Execute()

##### Em Python

          bas = CreateScriptService("Basic")
        doc = CreateScriptService("Document", bas.ThisComponent)
        toolbar = doc.Toolbars("standardbar")
        toolbar_button = toolbar.ToolbarButtons("Imprimir")
        toolbar_button.Execute()

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

♥ Doe para nosso projeto! ♥