Obsah

# Služba SFWidgets.PopupMenu

Službu PopupMenu je možné použít k vytváření vyskakovacích nabídek, které lze propojovat s událostmi nebo spouštět pomocí skriptů. Služba nabízí následující možnosti:

- Vytváření vyskakovacích nabídek s vlastními položkami, zaškrtávacími poli a přepínači.

- Doplnění ikon a tipů k položkám nabídky.

## Volání služby

Před používáním služby PopupMenu je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService

##### V Basicu

Instanci služby PopupMenu lze vytvořit několika způsoby. V níže uvedeném příkladu je vyskakovací nabídka vytvořena, aniž by byla přiřazena k události myši nebo aplikace.

        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("ID vybrané položky: " & vResponse)
            myPopup.Dispose()
        End Sub

Spuštění tohoto kódu vytvoří vyskakovací nabídku se dvěma položkami, umístěnou na souřadnicích obrazovky X=300 a Y=300.

Předponu SFWidgets je možné při vytváření služby PopupMenu vynechat.

V následujícím příkladu je definován podprogram Sub, který lze přiřadit k události myši:

        Sub MyPopupClick(Optional poMouseEvent as Object)
            Dim myPopup As Object
            Set myPopup = CreateScriptService("PopupMenu", poMouseEvent)
            ' Naplní vyskakovací nabídku položkami
            Dim vResponse As Variant
            vResponse = myPopup.Execute(False)
            ' Provedení něčeho podle hodnoty vResponse
            ' ...
            myPopup.Dispose()
        End Sub

Po provedení kódu s vyskakovací nabídkou uvolněte zdroje pomocí metody Dispose.

Vyskakovací nabídku lze také propojit s událostmi spouštěnými aplikacemi, formuláři a dialogovými okny LibreOffice. Obvykle bývají k vyskakovacím nabídkám přiřazovány události jako „Stisknuto tlačítko myši“ či „Uvolněno tlačítko myši“.

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

##### V Pythonu

V Pythonu lze výše uvedené příklady zapsat následovně:

        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)
            # Naplní vyskakovací nabídku položkami
            response = my_popup.Execute()
            # Provedení něčeho podle hodnoty response
            my_popup.Dispose()

## Vlastnosti

Název | Pouze pro čtení | Typ | Popis
--- | --- | --- | ---
ShortcutCharacter | ne | String | Znak použitý pro určení přístupové klávesy pro položku nabídky. Výchozím znakem je ~.
SubmenuCharacter | ne | String | Znak nebo řetězec určující, jak jsou položky nabídky vnořeny. Výchozím znakem je >.

## Nabídka a podnabídky

Chcete-li vytvořit vyskakovací nabídku s podnabídkami, použijte při vytváření položky znak definovaný vlastností SubmenuCharacter, kterým určíte umístění položky. Příkladem může být následující hierarchie nabídky a podnabídek.

        ' 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

V následujícím kódu je pro vytvoření výše uvedené hierarchie nabídky a podnabídek použit výchozí znak pro podnabídky >:

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

Řetězcem --- se definuje oddělovací čára v nabídkách nebo podnabídkách.

## Použití ikon

Položky nabídky mohou mít ikony, které se zadávají jako argumenty metod AddCheckBox, AddItem a AddRadioButton.

Použít můžete jakoukoliv ikonu dostupnou v LibreOffice, a to tím, že určíte její cestu relativně k cestě, kde jsou soubory s ikonami v rámci složky s instalací umístěny. Ikony jsou umístěny v následující složce:

INSTALLDIR/share/config

To, kde je LibreOffice v systému nainstalován, určíte pomocí vlastnosti InstallFolder ze služby FileSystem.

V této složce jsou umístěny soubory ZIP obsahující soubory s obrázky pro každou dostupnou sadu ikon. Obrázky jsou v těchto souborech ZIP uspořádány do složek. Při použití ikony zadáte soubor s ikonou včetně cesty k jejímu umístění v rámci souboru ZIP.

V níže uvedeném příkladu je použita ikona "sc_newdoc.svg", která se nachází ve složce "cmd". Znak lomítka "/" se používá jako oddělovač cesty bez ohledu na operační systém.

##### V Basicu

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

##### V Pythonu

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

Všechny sady ikon mají stejnou vnitřní strukturu. To, jaká ikona se zobrazí, závisí na tom, jaká sada ikon se aktuálně používá.

## Metody

Seznam metod služby PopupMenu
AddCheckBox AddItem | AddRadioButton | Execute

## AddCheckBox

Vloží do vyskakovací nabídky zaškrtávací pole. Vrátí celočíselnou hodnotu označující vloženou položku.

### Syntaxe:

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

### Parametry:

menuitem: Určuje text, který se má v nabídce zobrazit. Při použití znaku pro podnabídku tento argument rovněž udává hierarchii položky v rámci nabídky.

name: Řetězec vrácený při klepnutí na položku. Ve výchozím nastavení se použije poslední součást hierarchie nabídky.

status: Určuje, zda je položka při vytvoření nabídky vybrána (výchozí = False).

icon: Cesta a název ikony (bez úvodního oddělovače cesty), která se má zobrazit. Vzhled skutečně zobrazené ikony závisí použité sadě ikon.

tooltip: Text zobrazený pro položku jako tip.

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## AddItem

Vloží do vyskakovací nabídky položku. Vrátí celočíselnou hodnotu označující vloženou položku.

### Syntaxe:

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

### Parametry:

menuitem: Určuje text, který se má v nabídce zobrazit. Při použití znaku pro podnabídku tento argument rovněž udává hierarchii položky v rámci nabídky.

name: Řetězec vrácený při klepnutí na položku. Ve výchozím nastavení se použije poslední součást hierarchie nabídky.

icon: Cesta a název ikony (bez úvodního oddělovače cesty), která se má zobrazit. Vzhled skutečně zobrazené ikony závisí použité sadě ikon.

tooltip: Text zobrazený pro položku jako tip.

### Příklad:

##### V Basicu

          myPopup.AddItem("Položka A", Tooltip := "Popisek položky")

##### V Pythonu

          my_popup.AddItem("Položka A", tooltip = "Popisek položky")

## AddRadioButton

Vloží do vyskakovací nabídky přepínač. Vrátí celočíselnou hodnotu označující vloženou položku.

### Syntaxe:

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

### Parametry:

menuitem: Určuje text, který se má v nabídce zobrazit. Při použití znaku pro podnabídku tento argument rovněž udává hierarchii položky v rámci nabídky.

name: Řetězec vrácený při klepnutí na položku. Ve výchozím nastavení se použije poslední součást hierarchie nabídky.

status: Určuje, zda je položka při vytvoření nabídky vybrána (výchozí = False).

icon: Cesta a název ikony (bez úvodního oddělovače cesty), která se má zobrazit. Vzhled skutečně zobrazené ikony závisí použité sadě ikon.

tooltip: Text zobrazený pro položku jako tip.

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## Execute

Zobrazí vyskakovací nabídku a počká na akci uživatele. Vrátí položku, na kterou uživatel klepne.

Jestliže uživatele klepne mimo vyskakovací menu nebo stiskne klávesu Esc, nevybere se žádná položka. V takovém případě závisí návratová hodnota na parametru returnid. Je-li returnid = True a položka není vybrána, vrátí se hodnota 0 (nula). V opačném případě se vrátí prázdný řetězec "".

### Syntaxe:

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

### Parametry:

returnid: Je-li True, vrátí se ID vybrané položky. Je-li False, metoda vrátí název položky (výchozí = True).

### Příklad:

V níže uvedených příkladech se vytvoří vyskakovací nabídka a vrátí se název položky, protože argument returnid je nastaven na False.

##### V Basicu

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

##### V Pythonu

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

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.

Související témata

Služba SFDialogs.Dialog

Služba SFDialogs.DialogControl

Služba SFWidgets.Menu