Serviço SFWidgets.PopupMenu

O serviço PopupMenu pode ser usado para criar menus de popup que podem ser associados a eventos ou executados por scripts. O serviço fornece as seguintes funcionalidades:

Criação de menus de popup com entradas customizadas, caixas de seleção e botões de opção.
Decoração de itens do menu com ícones e textos com dicas.

Invocação do serviço

Antes de usar o serviço PopupMenu 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 PopupMenu pode ser instanciado de múltiplas maneiras. O exemplo abaixo cria um menu de popup sem associá-lo com um evento de mouse ou aplicação.


    Sub ShowPopup
        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim myPopup As Object
        Set myPopup = CreateScriptService("SFWidgets.PopupMenu", , 300, 300)
        myPopup.AddItem("Item ~A")
        myPopup.AddItem("Item ~B")
        vResponse = myPopup.Execute()
        MsgBox("ID do item selecionado: " & vResponse)
        myPopup.Dispose()
    End Sub

A execução da Sub definida acima criará um menu de popup com duas entradas na posição X=300 e Y=300 da tela.

O prefixo SFWidgets pode ser suprimido ao invocar o serviço PopupMenu.

O seguinte exemplo define uma Sub que pode ser associada a um evento de mouse:


    Sub MyPopupClick(Optional poMouseEvent as Object)
        Dim myPopup As Object
        Set myPopup = CreateScriptService("PopupMenu", poMouseEvent)
        ' Preenche o menu de popup com itens
        Dim vResponse As Variant
        vResponse = myPopup.Execute(False)
        ' Faz algo com base em vResponse
        ' ...
        myPopup.Dispose()
    End Sub

Use o método Dispose para liberar recursos após o término da execução do menu de popup.

Também é possível associar um menu de popup com eventos disparados por aplicativos do LibreOffice, bem como por controles de formulários e caixas de diálogo. Eventos como "Botão do mouse pressionado" e "Botão do mouse liberado" são comumente associados a menus de popup.


    Sub MyPopupClick(Optional poEvent as Object)
        Dim myPopup As Object
        Set myPopup = CreateScriptService("PopupMenu", poEvent)
        ' ...
    End Sub

Em Python

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


    from scriptforge import CreateScriptService
    
    def show_popup(args=None):
        my_popup = CreateScriptService("SFWidgets.PopupMenu", None, 300, 300)
        bas = CreateScriptService("Basic")
        my_popup.AddItem("Item ~A")
        my_popup.AddItem("Item ~B")
        response = my_popup.Execute()
        bas.MsgBox(f"Selected item ID: {response}")
        my_popup.Dispose()


    def my_popup_click(poEvent=None):
        my_popup = CreateScriptService("SFWidgets.PopupMenu", poEvent)
        # Preenche o menu de popup com itens
        response = my_popup.Execute()
        # Faz algo com base no valor de response
        my_popup.Dispose()

Propriedades

Nome	Somente de leitura	Tipo	Descrição
ShortcutCharacter	Não	String	Caractere usado para definir a chave de acesso de um item de menu. O caractere padrão é ~.
SubmenuCharacter	Não	String	Caractere ou string que define como itens do menu são aninhados. O caractere padrão é >.

Menus e Submenus

Para criar um menu de popup 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/submenu 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 submenu > para criar a hierarquia de menu/submenu definida acima:


    myPopup.AddItem("Item A")
    myPopup.AddItem("Item B>Item B.1")
    myPopup.AddItem("Item B>Item B.2")
    myPopup.AddItem("---")
    myPopup.AddItem("Item C>Item C.1>Item C.1.1")
    myPopup.AddItem("Item C>Item C.1>Item C.1.2")
    myPopup.AddItem("Item C>Item C.2>Item C.2.1")
    myPopup.AddItem("Item C>Item C.2>Item C.2.2")
    myPopup.AddItem("Item C>Item C.2>---")
    myPopup.AddItem("Item C>Item C.2>Item C.2.3")
    myPopup.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

Lista de Métodos do Serviço PopupMenu
AddCheckBox AddItem	AddRadioButton	Execute

AddCheckBox

Insere uma caixa de seleção no menu de pop-up. Retorna um valor inteiro que identifica o item inserido.

Sintaxe:

svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: 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: 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.

Exemplo:

Em Basic


      myPopup.AddCheckBox("Option A", Status := True)

Em Python


      my_popup.AddCheckBox("Option A", status=True)

AddItem

Insere uma entrada no menu de popup. Retorna um valor inteiro que identifica o item inserido.

Sintaxe:

svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: 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: Valor string que será retornado quando o item for clicado. Por padrão, o último componente da hierarquia do menu é usado.

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.

Exemplo:

Em Basic


      myPopup.AddItem("Item A", Tooltip := "Uma mensagem explicativa")

Em Python


      my_popup.AddItem("Item A", tooltip = "Uma mensagem explicativa")

AddRadioButton

Insere um botão de opção no menu de popup. Retorna o valor inteiro que identifica o item inserido.

Sintaxe:

svc.AddRadioButton(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: 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: 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.

Exemplo:

Em Basic


      myPopup.AddRadioButton("Option A", Name := "A", Status := True)

Em Python


      my_popup.AddRadioButton("Option A", name="A", status=True)

Execute

Mostra o menu de popup e espera alguma ação do usuário. Retorna o item clicado pelo usuário.

Se o usuário clicar fora do menu de popup ou se pressionar a tecla Esc, então nenhum item do menu foi selecionado. Em tais casos, o valor retornado depende do parâmetro returnid. Se returnid = True e nenhum item for selecionado, então o valor 0 (zero) será retornado. Caso contrário, uma string vazia "" será retornada.

Sintaxe:

svc.Execute(opt returnid: bool = True): any

Parâmetros:

returnid: Se True a ID do item selecionado é retornada. Se False o método retorna o nome do item (Padrão = True).

Exemplo:

Nos exemplos abaixo, um menu de popup é criado e o nome do item é retornado porque o argumento returnid foi definido como False.

Em Basic


      myPopup.AddItem("Item A", Name := "A")
      myPopup.AddItem("Item B", Name := "B")
      Dim vResponse as Variant
      vResponse = myPopup.Execute(False)

Em Python


      my_popup.AddItem("Item A", name="A")
      my_popup.AddItem("Item B", name="B")
      response = my_popup.Execute(False)

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.

Serviço SFDialogs.Dialog

Serviço SFDialogs.DialogControl

Serviço SFWidgets.Menu