Serviço SFWidgets.Menu

O serviço Menu pode ser usado para criar e remover menus da barra de menus de uma janela de documento do LibreOffice. Cada entrada do menu pode ser associada a uma macro ou comando UNO. Este serviço fornece as seguintes possibilidades:

• Criação de menus com entradas customizadas, que podem ser comandos simples, caixas de verificação, botões de opção e separadores.

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

Menus criados com este serviço estão disponíveis apenas para uma janela de documento específica. Eles não são salvos ao documento ou às configurações de aplicação. Fechar e reabrir o documento fará com que as configurações padrão da barra de menus sejam restauradas.

Quando objetos OLE tais como fórmulas do Math ou gráficos do Calc são editados a partir de uma janela de documento, o LibreOffice reconfigura a barra de menus de acordo com o objeto sendo editado. Quando isso acontece, os menus criados com o serviço Menu são removidos e não são restaurados após o término da edição do objeto OLE.

Invocação do serviço

Antes de usar o serviço Menu 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 Menu é instanciado ao chamar o método CreateMenu do serviço Document. O trecho de código abaixo cria um menu chamado Meu Menu na janela de documento atual e adiciona duas entradas chamadas 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("Meu Menu")
        With oMenu
            .AddItem("Item A", Command := "About")
            .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, é recomendável chamar o método Dispose para liberar os recursos usados pela instância do serviço Menu.

No exemplo acima, Item A está associado ao comando UNO .uno:About e Item B está associado ao script ItemB_Listener definido em Module1 da biblioteca Standard do contêiner Minhas macros.

O exemplo a seguir define o procedimento ItemB_Listener que será chamado quando a entrada Item B for clicada. Este procedimento simplesmente separa a string de argumento passada ao Sub e mostra os resultados em uma caixa de mensagem.

    Sub ItemB_Listener(args As String)
        ' Processa a string de argumentos passada ao procedimento
        Dim sArgs as Object
        sArgs = Split(args, ",")
        MsgBox "Nome do menu: "   & sArgs(0) & Chr(13) & _
               "Item do menu: "   & sArgs(1) & Chr(13) & _
               "ID do Item: "     & sArgs(2) & Chr(13) & _
               "Status do item: " & sArgs(3)
    End Sub
  

Como mostrado no exemplo acima, entradas do menu associadas a scripts recebem uma string como argumento com os seguintes valores separados por vírgula:

• Nome do menu de primeiro nível

• String contendo a ID do item de menu selecionado

• ID numérico do item de menu selecionado

• Estado atual do item do menu. Esta informação é útil para caixas de verificação e botões de opção. Se o item estiver marcado, então o valor "1" é retornado. Caso contrário o valor "0" é retornado.

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

    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 Item: {s_args[2]}\n"
        msg += f"Status do item: {s_args[3]}"
        bas.MsgBox(msg)
  

Propriedades

Menus e Submenus

Para criar um menu com submenus, use o caractere definido na propriedade SubmenuCharacter durante a criação do item do menu para definir onde ele será posicionado. Por exemplo, considere a hierarquia de menu/submenus definida a seguir:

    ' 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 usa o caractere padrão ">" de definição de submenus para criar a hierarquia de menu/submenu 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 string --- é usada para definir linhas separadoras em menus ou submenus.

Usando ícones

Itens em menus podem ter ícones, os quais são especificados como argumentos nos métodos AddCheckBox, AddItem e AddRadioButton.

Todos os ícones disponíveis no LibreOffice podem ser usados para especificar seu caminho relativo à pasta onde os arquivos de ícones se encontram no diretório de instalação. Ícones estão localizados no seguinte diretório:

INSTALLDIR/share/config

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

Esta pasta contém uma série de arquivos ZIP contendo os arquivos de imagens de todos os temas de ícones. As imagens dentro desses arquivos ZIP são organizados em pastas. Para usar um ícone, especifique o arquivo de ícone com o caminho para sua localização dentro do arquivo ZIP.

O exemplo abaixo usa o ícone "sc_newdoc.svg" que está localizado dentro da pasta "cmd". A barra "/" é usada como separador de pastas independentemente do sistema operacional.

Em Basic

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

Em Python

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

Todos os temas de ícones possuem a mesma estrutura interna. O ícone exibido depende do tema de ícone atualmente em uso.

Métodos

AddCheckBox

Insere uma caixa de verificação no menu. Retorna 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

menuitem: Define o texto a ser mostrado no menu. Este argumento também define a hierarquia do item dentro do menu usando o caractere de submenu.

name: String usada para identificar o item de menu. Por padrão, o último componente da hierarquia do menu é usado.

status: Define se o item está selecionado quando o menu é criado (Padrão = False).

icon: Caminho e nome do ícone a ser mostrado sem o separador de caminho no início. O ícone que efetivamente será mostrado depende do tema de ícone em uso.

tooltip: Texto de ajuda a ser associado ao item.

command: Nome do comando UNO associado ao item do menu sem o prefixo .uno:. Se o nome do comando não existir, nada acontecerá.

script: Endereço URI para um script Basic e Python que será executado quando o item for clicado.

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

Leia a página Scripting Framework URI Specification para aprender mais sobre a sintaxe URI usada pelo argumento script.

      ' Entrada de menu associada ao comando .uno:Paste
      oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")
      ' Executa o script Basic Standard.Module1.MyListener armazenado no documento
      oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
      ' Roda o script Python chamado MyListener localizado no arquivo myScripts.py na pasta de scripts de usuário
      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

Insere uma entrada de rótulo no menu. Retorna 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

menuitem: Define o texto a ser mostrado no menu. Este argumento também define a hierarquia do item dentro do menu usando o caractere de submenu.

name: String a ser retornada quando o item é clicado. Por padrão, o último componente da hierarquia do menu é utilizada.

icon: Caminho e nome do ícone a ser mostrado sem o separador inicial do caminho. O ícone efetivamente mostrado depende do estilo dos ícones sendo utilizado.

tooltip: Texto de dica a ser apresentado.

command: Nome do comando UNO sem o prefixo .uno:. Se o nome do comando não existir, nada acontecerá.

script: Endereço URI para um script em Basic ou Python que será executado quando o item for clicado.

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

Leia a página Scripting Framework URI Specification para aprender mais sobre a sintaxe URI usada pelo argumento script.

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

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

AddRadioButton

Insere um Botão de Opção no menu. Retorna o 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

menuitem: Define o texto a ser mostrado no menu. Este argumento também define a hierarquia do item dentro do menu usando o caractere de submenu.

name: Valor string que será retornado quando o item for clicado. Por padrão, o último componente da hierarquia do menu é usado.

status: Define se o item está selecionado quando o menu é criado (Padrão = False).

icon: Caminho e nome do ícone a ser mostrado sem o separador de caminho no início. O ícone que efetivamente será mostrado depende do tema de ícone em uso.

tooltip: Texto de ajuda a ser associado ao item.

command: Nome do comando UNO associado ao item do menu sem o prefixo .uno:. Se o nome do comando não existir, nada acontecerá.

script: Endereço URI para um script em Basic ou Python que será executado quando o item for clicado.

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

Leia a página Scripting Framework URI Specification para aprender mais sobre a sintaxe URI usada pelo 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 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.