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:

note

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.


warning

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:

note

• 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 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
  
note

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:

Em Python

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

Nome

Somente de leitura

Tipo

Descrição

ShortcutCharacter

Não

String

Caractere usado para definir a tecla de acesso do item de menu. O caractere padrão é "~".

SubmenuCharacter

Não

String

Caractere ou string usada para definir como itens no menu são aninhados. O caractere padrão é ">".


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")
  
note

A string "---" é usada para inserir separadores de linha em menus e submenus.


Usando ícones

Items in the menu can have icons, which are specified as arguments in the AddCheckBox, AddItem and AddRadioButton methods.

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

tip

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")
    
note

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


Métodos

Lista de métodos do serviço Menu

AddCheckBox

AddItem

AddRadioButton


AddCheckBox

Insere uma caixa de verificação no menu. Retorna um valor inteiro que identifica o item inserido.

Sintaxe:

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

Parâmetros:

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.

note

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


tip

Read Scripting Framework URI Specification to learn more about the URI syntax used in the script argument.


Exemplo:

Em Basic

      ' 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")
      ' Runs the Python script MyListener located in file myScripts.py in the user scripts folder
      oMenu.AddCheckBox("Item C", Status := True, Script := "vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")
    
Em Python

      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

Inserts a label entry in the menu. Returns an integer value that identifies the inserted item.

Sintaxe:

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

Parâmetros:

menuitem: Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.

name: String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.

icon: Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.

tooltip: Text to be displayed as tooltip.

command: The name of a UNO command without the .uno: prefix. If the command name does not exist, nothing happens.

script: The URI for a Basic or Python script that will be executed when the item is clicked.

note

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


tip

Read Scripting Framework URI Specification to learn more about the URI syntax used in the script argument.


Exemplo:

Em Basic

      oMenu.AddItem("Item A", Tooltip := "A descriptive message")
    
Em Python

      oMenu.AddItem("Item A", tooltip = "A descriptive message")
    

AddRadioButton

Inserts a radio button entry in the menu. Returns an integer value that identifies the inserted item.

Sintaxe:

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

Parâmetros:

menuitem: Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.

name: String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.

status: Defines whether the item is selected when the menu is created (Default = False).

icon: Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.

tooltip: Text to be displayed as tooltip.

command: The name of a UNO command without the .uno: prefix. If the command name does not exist, nothing happens.

script: The URI for a Basic or Python script that will be executed when the item is clicked.

note

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


tip

Read Scripting Framework URI Specification to learn more about the URI syntax used in the script argument.


Exemplo:

Em Basic

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

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

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.