SFWidgets.ContextMenu serviço

Os menus de contexto são predefinidos durante a instalação do LibreOfficeDev. Podem ser personalizados na caixa de diálogo Ferramentas + Personalizar.

O serviço ContextMenu oferece as seguintes funcionalidades:

• Substituir temporariamente todos os itens de um menu de contexto específico.

• Adicione temporariamente novos itens de menu na parte inferior de um menu de contexto predefinido.

• Desativar temporariamente o menu de contexto.

As novas definições do menu não são guardadas em lado nenhum. Nem no documento, nem nas definições do LibreOfficeDev.

Um menu de contexto é normalmente ativado ao clicar com o botão direito do rato numa área específica de um documento. Experimente clicar numa célula ou no separador de uma folha num documento do Calc.

Chamada de serviço

Antes de utilizar o serviço ContextMenu, é 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 ContextMenu é instanciado apenas a partir dos métodos SF_Document.ContextMenus() e SF_Datasheet. ContextMenus().

    Sub DefineContextMenu()
        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim calc As Object, menu As Object
        Set calc = CreateScriptService("Document", ThisComponent)
        Set menu = calc.ContextMenus("cell")  ' Right-click on a cell
        '  ... Define the context menu ...
        menu.Dispose()
    End Sub
  

Ao executar o Sub definido acima, redefine-se o menu de contexto associado a uma área específica do documento, neste caso, uma célula pertencente a um documento Calc.

A nova definição permanecerá ativa até que o documento seja fechado ou até que o menu de contexto seja redefinido novamente.

Utilize o método Dispose para libertar recursos após a execução do menu de contexto.

O exemplo acima pode ser escrito em Python da seguinte forma:

    from scriptforge import CreateScriptService
    
    def DefineContextMenu(args=None):
        basic = CreateScriptService("Basic")
        calc = CreateScriptService("Document", basic.ThisComponent)
        menu = calc.ContextMenus("cell")  # Right-click on a cell
        #  ... Define the context menu ...
        menu.Dispose()
  

Propriedades

Menu e submenus

Para criar um menu de contexto com submenus, utilize o caractere definido na propriedade SubmenuCharacter ao criar a entrada do menu, a fim de 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 caractere padrão de submenu > para criar a hierarquia de menus e submenus definida acima:

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

Ao contrário dos menus pop-up, os itens do menu de contexto não devem conter ícones.

Métodos

Activate

Torne os itens adicionados do menu de contexto armazenado no documento disponíveis para execução ou, pelo contrário, desative-os, dependendo do argumento.

svc.Activate(opt enable: bool = True)

enable: Quando True (padrão), o menu local armazenado no documento é ativado. Quando False, o menu local é ignorado e o menu global definido ao nível de LibreOfficeDev tem prioridade.

AddItem

Inserir uma opção no menu de contexto.

svc.AddItem(menuitem: str, opt command: str, opt script: str)

menuitem: Define o texto a ser exibido no menu. Este argumento também define a hierarquia do item dentro do menu através do uso do caractere de submenu. Defina o último componente como "---" para definir um separador de linha.

command: O nome do comando UNO que será executado quando se clicar no item, sem o prefixo .uno:. Se o nome do comando não existir ou não for aplicável, nada acontecerá.

script: O URI de um script Basic ou Python que será executado quando se clicar no item. Note que o script indicado não receberá nenhum argumento.

      menu.AddItem("Menu top>Item 1", command := "About")
      menu.AddItem("Menu top>Item 2", script := "vnd.sun.star.script:myLib.Module1.ThisSub?language=Basic&location=document")
    

      menu.AddItem('Menu top>Item 1', command = 'About')
      menu.AddItem('Menu top>Item 2', script = 'vnd.sun.star.script:Module1.py$thisdef?language=Python&location=document')
    

RemoveAllItems

Retire todos os itens, tanto

• predefinido em Ferramentas + Personalizar e guardado no documento

• adicionado com contextmenu.AddItem()

Esta ação não pode ser revertida, a não ser que se feche e se volte a abrir o documento.

Posteriormente, quando for necessário, utilize AddItem() para inserir novos itens de menu.

svc.RemoveAllItems()

Associe o Sub/def ao evento de clique com o botão direito do rato numa folha. O menu personalizado aparece ao clicar com o botão direito do rato na coluna C da folha do Calc; caso contrário, o comportamento normal é mantido.

      Sub OnRightClick1(Optional XRange)  '  Xrange is a com.sun.star.table.XCellRange object
      Dim calc As Object, menu As Object, in_column As Boolean
      Set calc = CreateScriptService("Calc", ThisComponent)
      Set menu = calc.ContextMenus("cell")
      menu.RemoveAllItems()
      in_column = ( Len(calc.Intersect("Sheet1.$C:$C", XRange.AbsoluteName)) > 0 )
      If in_column Then
          menu.AddItem("A", script := "vnd.sun.star.script:Standard.Module1.EnterA?language=Basic&location=document")
          ' ...
      End If
      menu.Activate(in_column)
      End Sub
    

        def OnRightClick1(XRange = None)  #  Xrange is a com.sun.star.table.XCellRange object
            basic = CreateScriptService('basic')
            calc = CreateScriptService('Calc', basic.ThisComponent)
            menu = calc.ContextMenus('cell')
            menu.RemoveAllItems()
            in_column = ( len(calc.Intersect("Sheet1.$C:$C", XRange.AbsoluteName)) > 0 )
            if in_column:
                menu.AddItem('A', script = 'vnd.sun.star.script:Module1.py$EnterA?language=Python&location=document")
                # ...
            menu.Activate(in_column)
    

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.