SFWidgets.PopupMenu service

The PopupMenu service can be used to create popup menus that can be associated with events or executed by scripts. This service provides the following capabilities:

• Creation of popup menus with custom entries, checkboxes and radio buttons.

• Decoration of menu items with icons and tooltips.

A szolgáltatás igénybevétele

Before using the PopupMenu service the ScriptForge library needs to be loaded or imported:

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService

The PopupMenu service can be instantiated in multiple ways. The example below creates a popup menu without associating it with a mouse or application event.

    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
  

Running the Sub defined above will create a popup menu with two entries in the position X=300 and Y=300 on the screen.

The prefix SFWidgets can be suppressed while invoking the PopupMenu service.

The following example defines a Sub that can be associated with a mouse event:

    Sub MyPopupClick(Optional poMouseEvent as Object)
        Dim myPopup As Object
        Set myPopup = CreateScriptService("PopupMenu", poMouseEvent)
        ' Populate popupmenu with items
        Dim vResponse As Variant
        vResponse = myPopup.Execute(False)
        ' Do something based on vResponse
        ' ...
        myPopup.Dispose()
    End Sub
  

Use the Dispose method to free resources after executing the popup menu.

Lehetőség van arra is, hogy felugró menüt társítson a LibreOffice alkalmazások, űrlapok és párbeszédablakok által kiváltott eseményekhez. Az olyan eseményeket, mint az "Egérgomb lenyomása" és az "Egérgomb elengedése", gyakran társítják a felugró menükhöz.

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

The examples above can be written in Python as follows:

    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)
        # Populate popupmenu with items
        response = my_popup.Execute()
        # Do something based on response
        my_popup.Dispose()
  

Tulajdonságok

Menu and Submenus

Almenüvel rendelkező felugró menü létrehozásához a menübejegyzés létrehozásakor használja a SubmenuCharacter tulajdonságban meghatározott karaktert, hogy meghatározza, hova kerüljön. Vegyük például a következő menü/almenü hierarchiát.

    ' 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
  

The code below uses the default submenu character > to create the menu/submenu hierarchy defined above:

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

The string --- is used to define separator lines in menus or submenus.

Ikonok használata

Items in the menu can have icons, which are specified as arguments in the AddCheckBox, AddItem and AddRadioButton methods.

A LibreOffice mappában elérhető összes ikon használható, ha megadjuk az ikonfájlok telepítési mappájában található ikonfájlok mappájához viszonyított elérési útjukat. Az ikonok a következő mappában találhatók:

INSTALLDIR/share/config

Use the InstallFolder property of the FileSystem service to determine where LibreOffice is installed in your system.

Ez a mappa egy sor ZIP-fájlt tartalmaz, amelyek az egyes elérhető ikonkészletek képfájljait tartalmazzák. A ZIP-fájlokban lévő képek mappákba vannak rendezve. Egy ikon használatához adja meg az ikonfájlt a ZIP-fájlon belüli helyének elérési útvonalával együtt.

The example below uses the icon "sc_newdoc.svg" that is located inside the "cmd" folder. The forward slash "/" character is used as the path separator regardless of the operating system.

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

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

All icon sets have the same internal structure. The actual icon displayed depends on the icon set currently in use.

Metódusok

AddCheckBox

Inserts a check box in the popup menu. Returns an integer value that identifies the inserted item.

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

menuitem: Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.

name: String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.

status: Defines whether the item is selected when the menu is created (Default = False).

icon: Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.

tooltip: Text to be displayed as tooltip.

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

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

AddItem

Inserts a menu entry in the popup menu. Returns an integer value that identifies the inserted item.

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

menuitem: Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.

name: String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.

icon: Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.

tooltip: Text to be displayed as tooltip.

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

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

AddRadioButton

Inserts a radio button entry in the popup menu. Returns an integer value that identifies the inserted item.

svc.AddRadioButton(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: str): int

menuitem: Defines the text to be displayed in the menu. This argument also defines the hierarchy of the item inside the menu by using the submenu character.

name: String value to be returned when the item is clicked. By default, the last component of the menu hierarchy is used.

status: Defines whether the item is selected when the menu is created (Default = False).

icon: Path and name of the icon to be displayed without the leading path separator. The actual icon shown depends on the icon set being used.

tooltip: Text to be displayed as tooltip.

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

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

Execute

Displays the popup menu and waits for a user action. Returns the item clicked by the user.

Ha a felhasználó a felugró menün kívülre kattint, vagy megnyomja az Esc billentyűt, akkor nem kerül kiválasztásra semmilyen elem. Ilyen esetekben a visszaadott érték a returnid paramétertől függ. Ha returnid = True és nincs kiválasztott elem, akkor a rendszer a 0 (nulla) értéket adja vissza. Ellenkező esetben egy üres karakterlánc "" kerül visszaadásra.

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

returnid: If True the selected item ID is returned. If False the method returns the item's name (Default = True).

In the examples below, a popup menu is created and the item's name is returned because the returnid argument is set to 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)
    

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.