Service SFWidgets.ContextMenu

Contenu

# Service SFWidgets. ContextMenu

Les menus contextuels sont prédéfinis à l'installation de LibreOffice. Ils peuvent être personnalisés dans la boîte de dialogue Outils+Personnaliser.

Le service ContextMenu fournit les fonctionnalités suivantes :

- Remplacer temporairement tous les éléments d'un menu contextuel spécifique.

- Ajouter temporairement des nouveaux éléments de menu en bas d'un menu contextuel prédéfini.

- Rendre le menu contextuel temporairement inactif.

Les nouveaux paramètres du menu ne sont enregistrés nulle part. Ni dans le document, ni dans les paramètres de LibreOffice.

Un menu contextuel est généralement affiché par un clic droit sur une zone spécifique d'un document. Pensez par exemple à cliquer dans une cellule ou sur un onglet de feuille dans un document Calc.

## Invocation du service

Avant d'utiliser le service ContextMenu, la bibliothèque ScriptForge doit être chargée ou importée :

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Les scripts Python nécessitent un import depuis le module scriptforge :
from scriptforge import CreateScriptService

##### En Basic :

Le service ContextMenu est instancié uniquement à partir des méthodes SF_Document.ContextMenus() et 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

L'exécution de Sub définie ci-dessus redéfinit le menu contextuel associé à une zone spécifique du document, en l'occurrence une cellule appartenant à un document Calc.

La nouvelle définition restera active jusqu'à la fermeture du document ou jusqu'à ce que le menu contextuel soit de nouveau défini.

Utilisez la méthode Dispose pour libérer des ressources après l'exécution du menu contextuel.

##### En Python

L'exemple ci-dessus peut être écrit en Python de la façon suivante :

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

## Propriétés

Nom | En lecture seule | Type | Description
--- | --- | --- | ---
ParentDocument | Oui | Object | L'instance de la classe de document parente (ou de l'une de ses sous-classes).
ShortcutCharacter | Oui | String | Caractère utilisé pour définir la touche d'accès d'un élément de menu. Le caractère par défaut est ~.
SubmenuCharacter | Oui | String | Caractère ou chaîne définissant la manière dont les éléments de menu sont imbriqués. Le caractère par défaut est >.

## Menu et sous menus

Pour créer un menu contextuel avec des sous menus, utilisez le caractère défini dans la propriété SubmenuCharacter lors de la création de l'entrée de menu afin de définir son emplacement. Prenons par exemple la hiérarchie menu/sous-menu suivante.

        ' 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

Le code ci-dessous utilise le caractère de sous menu par défaut > pour créer la hiérarchie menu/sous menu définie ci-dessus :

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

La chaîne --- est utilisée pour définir des lignes de séparateur dans les menus ou sous menus.

## Utilisation d'icônes

Contrairement aux menus popup, les éléments de menu contextuel ne doivent contenir aucune icône.

## Méthodes

Liste des méthodes dans le service ContextMenu
Activate | AddItem | RemoveAllItems

## Activate

Rendez les éléments ajoutés du menu contextuel stocké dans le document disponibles pour l'exécution ou, à l'inverse, désactivez-les, selon l'argument.

### Syntaxe :

svc.Activate(opt enable: bool = True)

### Paramètres :

enable : lorsque True (par défaut), le menu local enregistré dans le document est activé. Lorsque False, le menu local est ignoré et le menu global défini au niveau de LibreOffice prend la précédence.

## AddItem

Insère une entrée de menu dans le menu contextuel

### Syntaxe :

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

### Paramètres :

menuitem : définit le texte à afficher dans le menu. Cet argument définit également la hiérarchie de l'élément au sein du menu grâce au caractère de sous-menu. Définissez le dernier composant sur "---" pour créer une ligne de séparation.

command : le nom de la commande UNO qui sera exécutée lors d'un clic sur l'élément, sans le préfixe .uno:. Si le nom de la commande n'existe pas ou n'est pas applicable, rien ne se passera.

script : l'URI d'un script Basic ou Python qui sera exécuté lorsque l'élément sera cliqué. Notez que le script indiqué ne recevra aucun argument.

### Exemple :

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

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

Supprimer tous les éléments, les deux

- prédéfini avec Outils+Personnaliser et enregistré dans le document

- ajouté avec contextmenu.AddItem()

Cette action ne peut pas être annulée excepté en fermant et en ouvrant de nouveau le document.

Ensuite, le cas échéant, utilisez AddItem() pour insérer de nouveaux éléments de menu.

### Syntaxe :

svc.RemoveAllItems()

### Exemple :

Associez ensuite Sub/def à l'événement clic avec le bouton droit d'une feuille. Le menu personnalisé s'affiche lors d'un clic avec le bouton droit dans la colonne C de la feuille Calc ; sinon, le comportement habituel est conservé.

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

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

Toutes les routines ou identifiants de base ScriptForge qui sont préfixés par un caractère de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans des macros de base ou des scripts Python.

Rubriques connexes

Service SFWidgets.PopupMenu

Service SFWidgets.Menu

Aidez-nous !