Tartalom

# 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

##### A Basic nyelvben

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

##### A Python nyelvben

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

Név | Írásvédett | Típus | Leírás
--- | --- | --- | ---
ShortcutCharacter | Nem | String | Character used to define the access key of a menu item. The default character is ~.
SubmenuCharacter | Nem | String | Character or string that defines how menu items are nested. The default character is >.

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

##### A Basic nyelvben

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

##### A Python nyelvben

          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

List of Methods in the PopupMenu Service
AddCheckBox AddItem | AddRadioButton | Execute

## AddCheckBox

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

### Szintaxis:

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

### Paraméterek:

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.

### Példa:

##### A Basic nyelvben

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

##### A Python nyelvben

          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.

### Szintaxis:

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

### Paraméterek:

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.

### Példa:

##### A Basic nyelvben

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

##### A Python nyelvben

          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.

### Szintaxis:

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

### Paraméterek:

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.

### Példa:

##### A Basic nyelvben

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

##### A Python nyelvben

          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.

### Szintaxis:

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

### Paraméterek:

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

### Példa:

In the examples below, a popup menu is created and the item's name is returned because the returnid argument is set to False.

##### A Basic nyelvben

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

##### A Python nyelvben

          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.

Kapcsolódó témakörök

SFDialogs.Dialog service

SFDialogs.DialogControl service

SFWidgets.Menu service