SFWidgets.Menu serviço

O serviço Menu pode ser utilizado para criar e remover menus da barra de menus de uma janela de documento LibreOffice. Cada entrada do menu pode ser associada a um script ou a um comando UNO. Este serviço oferece as seguintes funcionalidades:

• Criação de menus com entradas personalizadas, caixas de seleção, botões de opção e separadores.

• Decoração dos itens do menu com ícones e dicas de informação.

Os menus criados com este serviço estão disponíveis apenas para uma janela de documento específica. Não são guardados no documento nem como definições da aplicação. Ao fechar e abrir o documento, as definições predefinidas da barra de menus serão restauradas.

Quando objetos OLE, como fórmulas matemáticas ou gráficos do Calc, são editados a partir de um documento, o LibreOffice reconfigura a barra de menus de acordo com o objeto. Quando isso acontece, os menus criados com o serviço Menu são removidos e não são restaurados após a edição do objeto OLE.

Chamada de serviço

Antes de utilizar o serviço Menu, é 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 Menu é instanciado através da chamada ao método CreateMenu do serviço Document. O trecho de código abaixo cria um menu denominado My Menu na janela do documento atual, com duas entradas: Item A e Item B.

    Sub CreateMenu()
        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim oDoc as Object, oMenu as Object
        Set oDoc = CreateScriptService("Document")
        Set oMenu = oDoc.CreateMenu("O meu menu")
        With oMenu
            .AddItem("Item A", Command := "Sobre")
            .AddItem("Item B", Script := "vnd.sun.star.script:Standard.Module1.ItemB_Listener?language=Basic&location=application")
            .Dispose()
        End With
    End Sub
  

Após criar o menu, recomenda-se chamar o método Dispose para libertar os recursos utilizados pela instância do serviço Menu.

No exemplo acima, o Item A está associado ao comando UNO .uno:About, enquanto que o Item B está associado ao script ItemB_Listener definido no Módulo1 da biblioteca Padrão do contentor As minhas macros.

O exemplo seguinte define ItemB_Listener, que será chamado quando se clicar em Item B. Este ouvinte limita-se a dividir a cadeia de caracteres passada como argumento à função Sub e a apresentá-la numa caixa de mensagem.

    Sub ItemB_Listener(args As String)
        ' Processar a cadeia de caracteres do argumento passada ao ouvinte
        Dim sArgs as Object
        sArgs = Split(args, ",")
        MsgBox "Nome do menu: "   & sArgs(0) & Chr(13) & _
               "Opção do menu: "   & sArgs(1) & Chr(13) & _
               "ID do artigo: "     & sArgs(2) & Chr(13) & _
               "Estado do artigo: " & sArgs(3)
    End Sub
  

Conforme ilustrado no exemplo acima, as entradas de menu associadas a um script recebem um argumento de cadeia de caracteres separado por vírgulas com os seguintes valores:

• O nome principal do menu.

• O ID da string da opção de menu selecionada.

• O identificador numérico da opção de menu selecionada.

• O estado atual do item do menu. Isto é útil para caixas de seleção e botões de opção. Se o item estiver marcado, é devolvido o valor «1»; caso contrário, é devolvido «0».

Os exemplos acima podem ser escritos em Python da seguinte forma:

    from scriptforge import CreateScriptService
    
    def create_menu(args=None):
        oDoc = CreateScriptService("Document")
        oMenu = oDoc.CreateMenu("My Menu")
        oMenu.AddItem("Item A", command="About")
        oMenu.AddItem("Item B", script="vnd.sun.star.script:my_macros.py$item_b_listener?language=Python&location=user")
        oMenu.Dispose()
  

    def item_b_listener(args):
        bas = CreateScriptService("Basic")
        s_args = args.split(",")
        msg = f"Nome do menu: {s_args[0]}\n"
        msg += f"Item do menu: {s_args[1]}\n"
        msg += f"ID do artigo: {s_args[2]}\n"
        msg += f"Estado do artigo: {s_args[3]}"
        bas.MsgBox(msg)
  

Características

Menu e submenus

Para criar um menu com submenus, utilize o carácter definido na propriedade SubmenuCharacter ao criar a entrada do menu, para definir onde esta será colocada. Por exemplo, considere a seguinte hierarquia de menus e submenus.

    ' Item A
    ' Item B > Item B.1
    '          Item B.2
    ' ------ (line separator)
    ' Item C > Item C.1 > Item C.1.1
    '                     Item C.1.2
    ' Item C > Item C.2 > Item C.2.1
    '                     Item C.2.2
    '                     ------ (line separator)
    '                     Item C.2.3
    '                     Item C.2.4
  

O código abaixo utiliza o carácter padrão do submenu «>» para criar a hierarquia de menus e submenus definida acima:

    oMenu.AddItem("Item A")
    oMenu.AddItem("Item B>Item B.1")
    oMenu.AddItem("Item B>Item B.2")
    oMenu.AddItem("---")
    oMenu.AddItem("Item C>Item C.1>Item C.1.1")
    oMenu.AddItem("Item C>Item C.1>Item C.1.2")
    oMenu.AddItem("Item C>Item C.2>Item C.2.1")
    oMenu.AddItem("Item C>Item C.2>Item C.2.2")
    oMenu.AddItem("Item C>Item C.2>---")
    oMenu.AddItem("Item C>Item C.2>Item C.2.3")
    oMenu.AddItem("Item C>Item C.2>Item C.2.4")
  

A sequência --- é utilizada para definir linhas separadoras em menus ou submenus.

Utilização de ícones

Os itens do menu podem ter ícones, que são especificados como argumentos nos métodos AddCheckBox, AddItem e AddRadioButton.

Todos os ícones disponíveis no LibreOffice podem ser utilizados indicando o seu caminho relativo à pasta onde se encontram os ficheiros de ícones na pasta de instalação. Os ícones encontram-se na seguinte pasta:

INSTALLDIR/share/config

Utilize a propriedade InstallFolder do serviço FileSystem para determinar onde o LibreOffice está instalado no seu sistema.

Esta pasta contém uma série de ficheiros ZIP com os ficheiros de imagem de cada conjunto de ícones disponível. As imagens contidas nestes ficheiros ZIP estão organizadas em pastas. Para utilizar um ícone, especifique o ficheiro do ícone indicando o caminho para a sua localização dentro do ficheiro ZIP.

O exemplo abaixo utiliza o ícone «sc_newdoc.svg», que se encontra na pasta «cmd». O carácter barra «/» é utilizado como separador de caminho, independentemente do sistema operativo.

Em Basic

      myMenu.AddItem("Item A", Icon := "cmd/sc_newdoc.svg")
    

Em Python

      myMenu.AddItem("Item A", icon="cmd/sc_newdoc.svg")
    

Todos os conjuntos de ícones têm a mesma estrutura interna. O ícone efetivamente apresentado depende do conjunto de ícones que está a ser utilizado nesse momento.

Métodos

AddCheckBox

Inserir uma caixa de seleção no menu. Devolve um valor inteiro que identifica o item inserido.

svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

item do menu: Define o texto a apresentar no menu. Este argumento também define a hierarquia do item dentro do menu, utilizando o carácter de submenu.

nome: Valor de tipo String utilizado para identificar o item do menu. Por predefinição, é utilizado o último componente da hierarquia do menu.

estado: Define se o item está selecionado quando o menu é criado (Predefinição = False).

ícone: Caminho e nome do ícone a apresentar, sem o separador de caminho inicial. O ícone efetivamente apresentado depende do conjunto de ícones que estiver a ser utilizado.

dica: Texto a apresentar como dica.

comando: O nome de um comando UNO sem o prefixo .uno:. Se o nome do comando não existir, nada acontece.

script: O URI de um script Basic ou Python que será executado quando se clicar no item.

Os argumentos command e script são mutuamente exclusivos, pelo que apenas um deles pode ser definido para cada item do menu.

Leia Especificação da Estrutura de Scripts URI para saber mais sobre a sintaxe URI utilizada no argumento script.

      ' Opção do menu associada ao comando .uno:Paste
      oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")
      ' Executa o script Basic Standard.Module1.MyListener guardado no documento
      oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
      Executa o script Python «MyListener», localizado no ficheiro «myScripts.py», na pasta de scripts do utilizador
      oMenu.AddCheckBox("Item C", Status := True, Script := "vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")
    

      oMenu.AddCheckBox("Item A", status=True, tooltip="Paste values", command="Paste")
      oMenu.AddCheckBox("Item B", status=False, script="vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
      oMenu.AddCheckBox("Item C", Status=True, Script="vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")
    

AddItem

Inserir uma entrada de etiqueta no menu. Devolve um valor inteiro que identifica o item inserido.

svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

item do menu: Define o texto a apresentar no menu. Este argumento também define a hierarquia do item dentro do menu, utilizando o carácter de submenu.

nome: Valor de cadeia de caracteres a ser devolvido quando se clicar no item. Por predefinição, é utilizado o último componente da hierarquia do menu.

ícone: Caminho e nome do ícone a apresentar, sem o separador de caminho inicial. O ícone efetivamente apresentado depende do conjunto de ícones que estiver a ser utilizado.

dica: Texto a apresentar como dica.

comando: O nome de um comando UNO sem o prefixo .uno:. Se o nome do comando não existir, nada acontece.

script: O URI de um script Basic ou Python que será executado quando se clicar no item.

Os argumentos command e script são mutuamente exclusivos, pelo que apenas um deles pode ser definido para cada item do menu.

Leia Especificação da Estrutura de Scripts URI para saber mais sobre a sintaxe URI utilizada no argumento script.

      oMenu.AddItem("Item A", Tooltip := "Uma mensagem descritiva")
    

      oMenu.AddItem("Item A", tooltip = "Uma mensagem descritiva")
    

AddRadioButton

Inserir um botão de opção no menu. Devolve um valor inteiro que identifica o item inserido.

svc.AddRadioButton(menuitem: str, opt name: str, opt status: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

item do menu: Define o texto a apresentar no menu. Este argumento também define a hierarquia do item dentro do menu, utilizando o carácter de submenu.

nome: Valor de cadeia de caracteres a ser devolvido quando se clicar no item. Por predefinição, é utilizado o último componente da hierarquia do menu.

estado: Define se o item está selecionado quando o menu é criado (Predefinição = False).

ícone: Caminho e nome do ícone a apresentar, sem o separador de caminho inicial. O ícone efetivamente apresentado depende do conjunto de ícones que estiver a ser utilizado.

dica: Texto a apresentar como dica.

comando: O nome de um comando UNO sem o prefixo .uno:. Se o nome do comando não existir, nada acontece.

script: O URI de um script Basic ou Python que será executado quando se clicar no item.

Os argumentos command e script são mutuamente exclusivos, pelo que apenas um deles pode ser definido para cada item do menu.

Leia Especificação da Estrutura de Scripts URI para saber mais sobre a sintaxe URI utilizada no argumento script.

      oMenu.AddRadioButton("Item A", Name := "A", Status := True)
    

      oMenu.AddRadioButton("Item A", name="A", status=True)
    

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.