Contenu

# Service SFWidgets.Menu

Le service Menu permet de créer et de supprimer des menus de la barre de menus d'une fenêtre de document LibreOffice. Chaque entrée de menu peut être associée à un script ou à une commande UNO. Ce service offre les fonctionnalités suivantes :

- Création de menus avec des entrées personnalisées, des cases à cocher, des boutons radio et des séparateurs.

- Décoration des éléments de menu avec des icônes et des info-bulles.

Les menus créés avec ce service sont disponibles uniquement pour une fenêtre de document spécifiée. Ils ne sont pas enregistrés dans le document ou en tant que paramètres d'application. La fermeture et l'ouverture du document restaureront les paramètres de la barre de menus par défaut.

Lorsque des objets OLE tels que des formules mathématiques ou des diagrammes Calc sont modifiés à partir d'un document, LibreOffice reconfigure la barre de menus en fonction de l'objet. Lorsque cela se produit, les menus créés avec le service Menu sont supprimés et ne sont pas restaurés après la modification de l'objet OLE.

## Invocation du service

Avant d'utiliser le service Menu, 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 Menu est instancié en appelant la méthode CreateMenu depuis le service Document. L'extrait de code ci-dessous crée un menu nommé Mon menu dans la fenêtre du document actuel avec deux entrées Élément A et Élément B.

        Sub CreateMenu()
            GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
            Dim oDoc as Object, oMenu as Object
            Set oDoc = CreateScriptService("Document")
            Set oMenu = oDoc.CreateMenu("Mon Menu")
            With oMenu
                .AddItem("Élément A", Command := "About")
                .AddItem("Élément B", Script := "vnd.sun.star.script:Standard.Module1.ItemB_Listener?language=Basic&location=application")
                .Dispose()
            End With
        End Sub

Après avoir créé le menu, il est recommandé d'appeler la méthode Dispose pour libérer les ressources utilisées par l'instance de service Menu.

Dans l'exemple ci-dessus, Élément A est associé à la commande UNO .uno:About tandis que Élément B est associé au script ItemB_Listener défini dans Module1 de la bibliothèque Standard du conteneur My Macros.

L'exemple suivant définit ItemB_Listener qui sera appelé lorsque Élément B est cliqué. Cet écouteur divise simplement la chaîne d'arguments transmise au Sub et les affiche dans une boîte de message.

        Sub ItemB_Listener(args As String)
            ' Traite la chaîne d'arguments transmise à l'écouteur
            Dim sArgs as Object
            sArgs = Split(args, ",")
            MsgBox "Menu name: "   & sArgs(0) & Chr(13) & _
                   "Menu item: "   & sArgs(1) & Chr(13) & _
                   "Item ID: "     & sArgs(2) & Chr(13) & _
                   "Item status: " & sArgs(3)
        End Sub

Comme illustré dans l'exemple ci-dessus, les entrées de menu associées à un script reçoivent un argument de chaîne séparé par des virgules avec les valeurs suivantes :

- Le nom de niveau supérieur du menu.

- ID de chaîne de l'entrée de menu sélectionnée.

- ID numérique de l'entrée de menu sélectionnée.

- L'état actuel de l'élément de menu. Ceci est utile pour les cases à cocher et les boutons radio. Si la rubrique est cochée, la valeur "1" est renvoyée, sinon "0" est renvoyé.

##### En Python

Les exemples ci-dessus peuvent être écrits en Python comme suit :

        from scriptforge import CreateScriptService

        def create_menu(args=None):
            oDoc = CreateScriptService("Document")
            oMenu = oDoc.CreateMenu("My Menu")
            oMenu.AddItem("Item A", command="About")
            oMenu.AddItem("Item B", script="vnd.sun.star.script:my_macros.py$item_b_listener?language=Python&location=user")
            oMenu.Dispose()

        def item_b_listener(args):
            bas = CreateScriptService("Basic")
            s_args = args.split(",")
            msg = f"Menu name: {s_args[0]}\n"
            msg += f"Menu item: {s_args[1]}\n"
            msg += f"Item ID: {s_args[2]}\n"
            msg += f"Item status: {s_args[3]}"
            bas.MsgBox(msg)

## Propriétés

Nom | Lecture seule | Type | Description
--- | --- | --- | ---
ShortcutCharacter | Non | String | Caractère utilisé pour définir la clé d'accès d'un élément de menu. Le caractère par défaut est "~".
SubmenuCharacter | Non | String | Caractère ou chaîne qui définit 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 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 pour définir où elle sera placée. Par exemple, considérez la hiérarchie de 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 :

        oMenu.AddItem("Item A")
        oMenu.AddItem("Item B>Item B.1")
        oMenu.AddItem("Item B>Item B.2")
        oMenu.AddItem("---")
        oMenu.AddItem("Item C>Item C.1>Item C.1.1")
        oMenu.AddItem("Item C>Item C.1>Item C.1.2")
        oMenu.AddItem("Item C>Item C.2>Item C.2.1")
        oMenu.AddItem("Item C>Item C.2>Item C.2.2")
        oMenu.AddItem("Item C>Item C.2>---")
        oMenu.AddItem("Item C>Item C.2>Item C.2.3")
        oMenu.AddItem("Item C>Item C.2>Item C.2.4")

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

### Utilisation d'icônes

Les éléments du menu peuvent avoir des icônes, qui sont spécifiées comme arguments dans les méthodes AddCheckBox, AddItem et AddRadioButton.

Toutes les icônes disponibles dans LibreOffice peuvent être utilisées en spécifiant leur chemin relatif au dossier où se trouvent les fichiers d'icônes dans le dossier d'installation. Les icônes se trouvent dans le dossier suivant :

INSTALLDIR/share/config

Utilisez la propriété InstallFolder du service FileSystem pour déterminer où LibreOffice est installé sur votre système.

Ce dossier contient une série de fichiers ZIP contenant les fichiers image de chaque jeu d'icônes disponible. Les images à l'intérieur de ces fichiers ZIP sont organisées en dossiers. Pour utiliser une icône, spécifiez le fichier d'icône avec le chemin d'accès à son emplacement dans le fichier ZIP.

L'exemple ci-dessous utilise l'icône "sc_newdoc.svg" qui se trouve dans le dossier "cmd". Le caractère barre oblique "/" est utilisé comme séparateur de chemin quel que soit le système d'exploitation.

##### En Basic :

          myMenu.AddItem("Item A", Icon := "cmd/sc_newdoc.svg")

##### En Python

          myMenu.AddItem("Item A", icon="cmd/sc_newdoc.svg")

Tous les jeux d'icônes ont la même structure interne. L'icône réelle affichée dépend du jeu d'icônes actuellement utilisé.

## Méthodes

Liste des méthodes dans le service Menu
AddCheckBox | AddItem | AddRadioButton

## AddCheckBox

Insère une case à cocher dans le menu. Renvoie une valeur entière qui identifie l'élément inséré.

### Syntaxe :

svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

### Paramètres :

menuitem : définit le texte à afficher dans le menu. Cet argument définit également la hiérarchie de l'élément à l'intérieur du menu en utilisant le caractère de sous-menu.

nom : valeur de chaîne utilisée pour identifier l'élément de menu. Par défaut, le dernier composant de la hiérarchie des menus est utilisé.

statut : définit si l'élément est sélectionné lors de la création du menu (par défaut = False).

icon : chemin et nom de l'icône à afficher sans le séparateur de chemin initial. L'icône réelle affichée dépend du jeu d'icônes utilisé.

info-bulle : texte à afficher sous forme d'info-bulle.

command : le nom d'une commande UNO sans le préfixe .uno :. Si le nom de la commande n'existe pas, rien ne se passe.

script : l'URI d'un script Basic ou Python qui sera exécuté lorsque l'élément sera cliqué.

Les arguments command et script sont mutuellement exclusifs, donc un seul d'entre eux peut être défini pour chaque élément de menu.

Lisez Spécification de l'environnement de script de l'URI pour en savoir plus sur la syntaxe de l'URI utilisée dans l'argument script.

### Exemple :

##### En Basic :

          ' Entrée de menu associée à la commande .uno:Paste
          oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")
          ' Exécute le script de base Standard.Module1.MyListener stocké dans le document
          oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
          ' Exécute le script Python MyListener situé dans le fichier myScripts.py dans le dossier des scripts utilisateur
          oMenu.AddCheckBox("Item C", Status := True, Script := "vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")

##### En Python

          oMenu.AddCheckBox("Item A", status=True, tooltip="Paste values", command="Paste")
          oMenu.AddCheckBox("Item B", status=False, script="vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
          oMenu.AddCheckBox("Item C", Status=True, Script="vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")

## AddItem

Insère une entrée d'étiquette dans le menu. Renvoie une valeur entière qui identifie l'élément inséré.

### Syntaxe :

svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

### Paramètres :

menuitem : définit le texte à afficher dans le menu. Cet argument définit également la hiérarchie de l'élément à l'intérieur du menu en utilisant le caractère de sous-menu.

nom : valeur de chaîne à renvoyer lorsque l'élément est cliqué. Par défaut, le dernier composant de la hiérarchie des menus est utilisé.

icon : Chemin et nom de l'icône à afficher sans le séparateur de chemin initial. L'icône réelle affichée dépend du jeu d'icônes utilisé.

info-bulle : texte à afficher sous forme d'info-bulle.

command : le nom d'une commande UNO sans le préfixe .uno :. Si le nom de la commande n'existe pas, rien ne se passe.

script : l'URI d'un script Basic ou Python qui sera exécuté lorsque l'élément sera cliqué.

Les arguments command et script sont mutuellement exclusifs, donc un seul d'entre eux peut être défini pour chaque élément de menu.

Lisez Spécification de l'environnement de script de l'URI pour en savoir plus sur la syntaxe de l'URI utilisée dans l'argument script.

### Exemple :

##### En Basic :

          oMenu.AddItem("Item A", Tooltip := "A descriptive message")

##### En Python

          oMenu.AddItem("Item A", tooltip = "A descriptive message")

## AddRadioButton

Insère une entrée de bouton radio dans le menu. Renvoie une valeur entière qui identifie l'élément inséré.

### Syntaxe :

svc.AddRadioButton(menuitem: str, opt name: str, opt status: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

### Paramètres :

menuitem : définit le texte à afficher dans le menu. Cet argument définit également la hiérarchie de l'élément à l'intérieur du menu en utilisant le caractère de sous-menu.

nom : valeur de chaîne à renvoyer lorsque l'élément est cliqué. Par défaut, le dernier composant de la hiérarchie des menus est utilisé.

statut : définit si l'élément est sélectionné lors de la création du menu (par défaut = False).

icon : Chemin et nom de l'icône à afficher sans le séparateur de chemin initial. L'icône réelle affichée dépend du jeu d'icônes utilisé.

tooltip : texte à afficher sous forme d'info-bulle.

command : le nom d'une commande UNO sans le préfixe .uno :. Si le nom de la commande n'existe pas, rien ne se passe.

script : l'URI d'un script Basic ou Python qui sera exécuté lorsque l'élément sera cliqué.

Les arguments command et script sont mutuellement exclusifs, donc un seul d'entre eux peut être défini pour chaque élément de menu.

Lisez Spécification de l'environnement de script de l'URI pour en savoir plus sur la syntaxe de l'URI utilisée dans l'argument script.

### Exemple :

##### En Basic :

          oMenu.AddRadioButton("Item A", Name := "A", Status := True)

##### En Python

          oMenu.AddRadioButton("Item A", name="A", status=True)

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 SFDocuments.Document