Service SFWidgets.PopupMenu

Le service PopupMenu permet de créer des menus contextuels pouvant être associés à des événements ou exécutés par des scripts. Ce service offre les fonctionnalités suivantes :

• Création de menus contextuels avec des entrées personnalisées, des cases à cocher et des boutons radio.

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

Invocation du service

Avant d'utiliser le service PopupMenu, 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 PopupMenu peut être instancié de plusieurs façons. L'exemple ci-dessous crée un menu contextuel sans l'associer à un événement de souris ou d'application.

    Sub ShowPopup
        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim myPopup As Object
        Set myPopup = CreateScriptService("SFWidgets.PopupMenu", , 300, 300)
        myPopup.AddItem("Item ~A")
        myPopup.AddItem("Item ~B")
        vResponse = myPopup.Execute()
        MsgBox("Selected item ID: " & vResponse)
        myPopup.Dispose()
    End Sub
  

L'exécution de Sub défini ci-dessus créera un menu contextuel avec deux entrées à la position X=300 et Y=300 à l'écran.

Le préfixe SFWidgets peut être supprimé lors de l'appel du service PopupMenu.

L'exemple suivant définit un Sub qui peut être associé à un événement de souris :

    Sub MyPopupClick(Optional poMouseEvent as Object)
        Dim myPopup As Object
        Set myPopup = CreateScriptService("PopupMenu", poMouseEvent)
        ' Remplir le menu contextuel avec des éléments
        Dim vResponse As Variant
        vResponse = myPopup.Execute(False)
        ' Faire quelque chose basé sur vResponse
        ' ...
        myPopup.Dispose()
    End Sub
  

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

Il est également possible d'associer un menu contextuel à des événements déclenchés par des applications LibreOffice, des contrôles de formulaire et de boîte de dialogue. Des événements tels que "bouton de la souris enfoncé" et "bouton de la souris relâché" sont généralement associés aux menus contextuels.

    Sub MyPopupClick(Optional poEvent as Object)
        Dim myPopup As Object
        Set myPopup = CreateScriptService("PopupMenu", poEvent)
        ' ...
    End Sub
  

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

    from scriptforge import CreateScriptService
    
    def show_popup(args=None):
        my_popup = CreateScriptService("SFWidgets.PopupMenu", None, 300, 300)
        bas = CreateScriptService("Basic")
        my_popup.AddItem("Item ~A")
        my_popup.AddItem("Item ~B")
        response = my_popup.Execute()
        bas.MsgBox(f"Selected item ID: {response}")
        my_popup.Dispose()
  

    def my_popup_click(poEvent=None):
        my_popup = CreateScriptService("SFWidgets.PopupMenu", poEvent)
        # Remplir le menu contextuel avec des éléments
        response = my_popup.Execute()
        # Faire quelque chose basé sur response
        my_popup.Dispose()
  

Propriétés

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

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

AddCheckBox

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

svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: 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.

name : 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é.

status : 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.

      myPopup.AddCheckBox("Option A", Status := True)
    

      my_popup.AddCheckBox("Option A", status=True)
    

AddItem

Insère une entrée de menu dans le menu contextuel. 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): 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.

name : 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é.

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

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

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

AddRadioButton

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

svc.AddRadioButton(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: 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.

name : 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é.

status : 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.

      myPopup.AddRadioButton("Option A", Name := "A", Status := True)
    

      my_popup.AddRadioButton("Option A", name="A", status=True)
    

Execute

Affiche le menu contextuel et attend une action de l'utilisateur. Renvoie l'élément cliqué par l'utilisateur.

Si l'utilisateur clique en dehors du menu contextuel ou appuie sur la touche Esc, aucun élément n'est sélectionné. Dans de tels cas, la valeur renvoyée dépend du paramètre returnid. Si returnid = True et qu'aucun élément n'est sélectionné, alors la valeur 0 (zéro) est renvoyée. Sinon, une chaîne vide "" est renvoyée.

svc.Execute(opt returnid: bool = True): any

returnid : Si True l'ID de l'élément sélectionné est renvoyé. Si False la méthode renvoie le nom de l'élément (par défaut = True).

Dans les exemples ci-dessous, un menu contextuel est créé et le nom de l'élément est renvoyé car l'argument returnid est défini sur False.

      myPopup.AddItem("Item A", Name := "A")
      myPopup.AddItem("Item B", Name := "B")
      Dim vResponse as Variant
      vResponse = myPopup.Execute(False)
    

      my_popup.AddItem("Item A", name="A")
      my_popup.AddItem("Item B", name="B")
      response = my_popup.Execute(False)
    

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.