Ajuda do LibreOffice 24.8
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.
Antes de usar o serviço PopupMenu a biblioteca ScriptForge precisa ser carregada ou importada:
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
  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()
  | 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 é >. | 
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.
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.
      myMenu.AddItem("Item A", Icon := "cmd/sc_newdoc.svg")
    
      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.
| Lista de Métodos do Serviço PopupMenu | ||
|---|---|---|
Insere uma caixa de seleção no menu de pop-up. Retorna um valor inteiro que identifica o item inserido.
svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: 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.
      myPopup.AddCheckBox("Option A", Status := True)
    
      my_popup.AddCheckBox("Option A", status=True)
    Insere uma entrada no menu de popup. Retorna um valor inteiro que identifica o item inserido.
svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: 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.
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.
      myPopup.AddItem("Item A", Tooltip := "Uma mensagem explicativa")
    
      my_popup.AddItem("Item A", tooltip = "Uma mensagem explicativa")
    Insere um botão de opção no menu de popup. Retorna o valor inteiro que identifica o item inserido.
svc.AddRadioButton(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: 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.
      myPopup.AddRadioButton("Option A", Name := "A", Status := True)
    
      my_popup.AddRadioButton("Option A", name="A", status=True)
    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.
svc.Execute(opt returnid: bool = True): any
returnid: Se True a ID do item selecionado é retornada. Se False o método retorna o nome do item (Padrão = True).
Nos exemplos abaixo, um menu de popup é criado e o nome do item é retornado porque o argumento returnid foi definido como False.
      myPopup.AddItem("Item A", Name := "A")
      myPopup.AddItem("Item B", Name := "B")
      Dim vResponse as Variant
      vResponse = myPopup.Execute(False)
    
      my_popup.AddItem("Item A", name="A")
      my_popup.AddItem("Item B", name="B")
      response = my_popup.Execute(False)