Conteúdo

# SFWidgets.ContextMenu serviço

Os menus de contexto são predefinidos durante a instalação do LibreOffice. 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 LibreOffice.

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

##### Em Basic

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.

##### Em Python

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

Nome | Somente leitura | Tipo | Descrição
--- | --- | --- | ---
ParentDocument | Sim | Object | A instância da classe do documento pai (ou de uma das suas subclasses).
ShortcutCharacter | Sim | String | Caractere utilizado para definir a tecla de atalho de um item de menu. O caractere predefinido é ~.
SubmenuCharacter | Sim | String | Caractere ou cadeia de caracteres que define a forma como os itens do menu são aninhados. O caractere predefinido é >.

## 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

Lista de métodos do serviço ContextMenu
Activate | AddItem | RemoveAllItems

## 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.

### Sintaxe:

svc.Activate(opt enable: bool = True)

### Parâmetros:

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 LibreOffice tem prioridade.

## AddItem

Inserir uma opção no menu de contexto.

### Sintaxe:

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

### Parâmetros:

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.

### Exemplo:

##### Em Basic

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

##### Em Python

          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.

### Sintaxe:

svc.RemoveAllItems()

### Exemplo:

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.

##### Em Basic

          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

##### Em Python

            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.

Tópicos relacionados

SFWidgets.PopupMenu service

SFWidgets.Menu service

Necessitamos da sua ajuda!