Obsah

# Služba SFWidgets.Menu

Službu Menu je možné použít k vytváření a odstraňování nabídek v hlavní nabídce okna LibreOffice s dokumentem. Každé položce nabídky lze přiřadit skript nebo příkaz UNO. Služba nabízí následující možnosti:

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

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

Nabídky vytvořené tímto způsobem jsou dostupné pouze pro určené okno. Nejsou uloženy do dokumentu nebo jako nastavení aplikace. Zavření a otevření dokumentu obnoví výchozí nastavení hlavní nabídky.

Jestliže jsou v dokumentu upravovány objekty OLE, například vzorce aplikace Math nebo grafy aplikace Calc, LibreOffice změní nastavení hlavní nabídky podle upravovaného objektu. V tom případě jsou nabídky vytvořené službou Menu odstraněny a po ukončení úprav objektu OLE se již neobnoví.

## Volání služby

Před používáním služby Menu 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

Instance služby Menu je vytvořena voláním metody CreateMenu ze služby Document. V níže uvedené části kódu se vytvoří v okně aktuálního dokumentu nabídka s názvem Moje nabídka obsahující dvě položky, pojmenované Položka A a Položka B.

        Sub CreateMenu()
            GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
            Dim oDoc as Object, oMenu as Object
            Set oDoc = CreateScriptService("Document")
            Set oMenu = oDoc.CreateMenu("Moje nabídka")
            With oMenu
                .AddItem("Položka A", Command := "About")
                .AddItem("Položka B", Script := "vnd.sun.star.script:Standard.Module1.ItemB_Listener?language=Basic&location=application")
                .Dispose()
            End With
        End Sub

Po vytvoření nabídky je doporučeno zavolat metodu Dispose a uvolnit tím zdroje použité instancí službyMenu.

Ve výše uvedeném příkladu je k Položce A přiřazen příkaz UNO .uno:About, zatímco k Položce B je přiřazen skript ItemB_Listener definovaný v modulu Module1 knihovny Standard z kontejneru Moje makra.

V následujícím příkladu je definován podprogram ItemB_Listener, která se zavolá při klepnutí na Položku B. Tento posluchač pouze rozdělí řetězec z předaného argumentu a jednotlivé části zobrazí v dialogu.

        Sub ItemB_Listener(args As String)
            ' Zpracuje řetězec z argumentu předaného posluchači
            Dim sArgs as Object
            sArgs = Split(args, ",")
            MsgBox "Název nabídky: "   & sArgs(0) & Chr(13) & _
                   "Položka nabídky: "   & sArgs(1) & Chr(13) & _
                   "ID položky: "     & sArgs(2) & Chr(13) & _
                   "Stav položky: " & sArgs(3)
        End Sub

Jak je ukázáno v příkladu výše, položkám nabídek přiřazených ke skriptu je předán jako argument řetězec následujících hodnot oddělených čárkou:

- Název nejvyšší úrovně nabídky.

- Řetězec s identifikátorem vybrané položky nabídky.

- Číselný identifikátor vybrané položky nabídky.

- Aktuální stav položky nabídky. Je užitečný pro zaškrtávací pole a tlačítka přepínače. Pokud je položka zaškrtnutá, vrátí se hodnota "1", v opačném případě se vrátí hodnota "0".

##### V Pythonu

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

        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"Název nabídky: {s_args[0]}\n"
            msg += f"Položka nabídky: {s_args[1]}\n"
            msg += f"ID položky: {s_args[2]}\n"
            msg += f"Stav položky: {s_args[3]}"
            bas.MsgBox(msg)

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

Při vytváření podnabídek použijte k určení jejich umístění znak, který byl definován vlastností SubmenuCharacter při vytváření položky nabídky. 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 ">":

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

Ř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 Menu
AddCheckBox | AddItem | AddRadioButton

## AddCheckBox

Vloží do 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, opt icon: str, opt tooltip: str, opt command: str, opt script: 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 použití pro identifikaci položky nabídky. 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.

command: Název příkazu UNO bez předpony .uno:. Pokud příkaz se zadaným názvem neexistuje, nic se neprovede.

script: URI skriptu v Basicu nebo v Pythonu, který se spustí po klepnutí na položku.

Argumenty command a script se vzájemně vylučují, pro každou položku nabídky tak může být nastaven pouze jediný z nich.

Další informace o syntaxi identifikátoru URI použitého v argumentu script naleznete na stránce Scripting Framework URI Specification.

### Příklad:

##### V Basicu

          ' Položka nabídky s přiřazeným příkazem .uno:Paste
          oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")
          ' Spustí skript Basicu Standard.Module1.MyListener uložený v dokumentu
          oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
          ' Spustí skript Pythonu MyListener umístěný v souboru myScripts.py ve složce uživatelských skriptů
          oMenu.AddCheckBox("Item C", Status := True, Script := "vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")

##### V Pythonu

          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

Vloží do nabídky položku s popiskem. 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, opt command: str, opt script: 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.

command: Název příkazu UNO bez předpony .uno:. Pokud příkaz se zadaným názvem neexistuje, nic se neprovede.

script: URI skriptu v Basicu nebo v Pythonu, který se spustí po klepnutí na položku.

Argumenty command a script se vzájemně vylučují, pro každou položku nabídky tak může být nastaven pouze jediný z nich.

Další informace o syntaxi identifikátoru URI použitého v argumentu script naleznete na stránce Scripting Framework URI Specification.

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## AddRadioButton

Vloží do 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: str, opt icon: str, opt tooltip: str, opt command: str, opt script: 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.

command: Název příkazu UNO bez předpony .uno:. Pokud příkaz se zadaným názvem neexistuje, nic se neprovede.

script: URI skriptu v Basicu nebo v Pythonu, který se spustí po klepnutí na položku.

Argumenty command a script se vzájemně vylučují, pro každou položku nabídky tak může být nastaven pouze jediný z nich.

Další informace o syntaxi identifikátoru URI použitého v argumentu script naleznete na stránce Scripting Framework URI Specification.

### Příklad:

##### V Basicu

          oMenu.AddRadioButton("Item A", Name := "A", Status := True)

##### V Pythonu

          oMenu.AddRadioButton("Item A", name="A", status=True)

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 SFWidgets.PopupMenu

Služba SFDocuments.Document