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
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é.
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.
myMenu.AddItem("Item A", Icon := "cmd/sc_newdoc.svg")
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
Insère une case à cocher dans le menu. Renvoie une valeur entière qui identifie l'élément inséré.
svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int
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.
' 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")
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é.
svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int
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.
oMenu.AddItem("Item A", Tooltip := "A descriptive message")
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é.
svc.AddRadioButton(menuitem: str, opt name: str, opt status: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int
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.
oMenu.AddRadioButton("Item A", Name := "A", Status := True)
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.