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

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

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

AddCheckBox

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

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

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.

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

      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.

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

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.

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

      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.

svc.AddRadioButton(menuitem: str, opt name: str, opt status: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int

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.

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

      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.