Dienst SFWidgets.Menu

Der Dienst Menu kann zum Erstellen und Entfernen von Menüs aus der Menüleiste eines Collabora Office-Dokumentfensters verwendet werden. Jeder Menüeintrag kann einem Skript oder einem UNO-Befehl zugeordnet werden. Dieser Dienst bietet die folgenden Funktionen:

Erstellung von Menüs mit benutzerdefinierten Einträgen, Markierfeldern, Optionsfeldern und Trennzeichen.
Dekoration von Menüpunkten mit Symbolen und Infoboxen.

Mit diesem Dienst erstellte Menüs sind nur für ein bestimmtes Dokumentfenster verfügbar. Sie werden nicht im Dokument oder als Anwendungseinstellungen gespeichert. Durch Schließen und Öffnen des Dokuments werden die Standardeinstellungen der Menüleiste wiederhergestellt.

Wenn OLE-Objekte wie mathematische Formeln oder Calc-Diagramme innerhalb eines Dokuments bearbeitet werden, konfiguriert Collabora Office die Menüleiste entsprechend dem Objekt neu. In diesem Fall werden die mit dem Dienst Menu erstellten Menüs entfernt und nach der Bearbeitung des OLE-Objekts nicht wiederhergestellt.

Dienstaufruf

Vor der Verwendung des Dienstes Menu muss die Bibliothek ScriptForge geladen oder importiert werden:

• Grundlegende Makros erfordern das Laden der Bibliothek ScriptForge mit der folgenden Anweisung:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-Skripte erfordern einen Import aus dem Modul scriptforge:
from scriptforge import CreateScriptService

In Basic

Der Service Menu wird durch Aufrufen der Methode CreateMenu aus dem Dienst Document instanziiert. Der folgende Codeschnipsel erstellt ein Menü namens Mein Menü im aktuellen Dokumentfenster mit zwei Einträgen Eintrag A und Eintrag B.


    Sub CreateMenu()
        GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
        Dim oDoc as Object, oMenu as Object
        Set oDoc = CreateScriptService("Document")
        Set oMenu = oDoc.CreateMenu("Mein Menü")
        With oMenu
            .AddItem("Eintrag A", Command := "About")
            .AddItem("Eintrag B", Script := "vnd.sun.star.script:Standard.Module1.ItemB_Listener?language=Basic&location=application")
            .Dispose()
        End With
    End Sub

Nach dem Erstellen des Menüs wird empfohlen, die Methode Dispose aufzurufen, um die von der Dienstinstanz Menu verwendeten Ressourcen freizugeben.

Im obigen Beispiel ist Eintrag A dem UNO-Befehl .uno:About zugeordnet, während Eintrag B dem Skript ItemB_Listener zugeordnet ist, definiert in Module1 der Bibliothek Standard des Containers My Macros.

Das folgende Beispiel definiert ItemB_Listener, der aufgerufen wird, wenn auf Eintrag B geklickt wird. Dieser Listener teilt einfach die an Sub übergebene Argumentzeichenfolge und zeigt sie in einem Meldungsfeld an.


    Sub ItemB_Listener(args As String)
        ' Die an den Listener übergebene Argumentzeichenfolge verarbeiten
        Dim sArgs as Object
        sArgs = Split(args, ",")
        MsgBox "Menüname: "   & sArgs(0) & Chr(13) & _
               "Menüeintrag: "   & sArgs(1) & Chr(13) & _
               "Eintrag-ID: "     & sArgs(2) & Chr(13) & _
               "Eintrag-Status: " & sArgs(3)
    End Sub

Wie im obigen Beispiel gezeigt, erhalten mit einem Skript verknüpfte Menüeinträge eine durch Kommata getrennte Zeichenfolge mit den folgenden Werten:

Der Name der obersten Ebene des Menüs.
Die Zeichenfolgen-ID des ausgewählten Menüeintrags.
Die numerische ID des ausgewählten Menüeintrags.
Der aktuelle Zustand des Menüpunkts. Dies ist nützlich für Markier- und Optionsfelder. Wenn der Eintrag markiert ist, wird der Wert „1“ zurückgegeben, andernfalls wird „0“ zurückgegeben.

In Python

Die obigen Beispiele können wie folgt in Python geschrieben werden:


    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"Menünname: {s_args[0]}\n"
        msg += f"Menüeintrag: {s_args[1]}\n"
        msg += f"Eintrag-ID: {s_args[2]}\n"
        msg += f"Eintrag-Status: {s_args[3]}"
        bas.MsgBox(msg)

Eigenschaften

Name	Schreibgeschützt	Typ	Beschreibung
ShortcutCharacter	Nein	String	Zeichen, das verwendet wird, um die Zugriffstaste eines Menüpunkts zu definieren. Das Standardzeichen ist "~".
SubmenuCharacter	Nein	String	Zeichen oder Zeichenfolge, die definiert, wie Menüelemente verschachtelt sind. Das Standardzeichen ist ">".

Menü und Untermenüs

Um ein Menü mit Untermenüs zu erstellen, verwenden Sie das in der Eigenschaft SubmenuCharacter definierte Zeichen, während Sie den Menüeintrag erstellen, um zu definieren, wo er platziert wird. Betrachten Sie beispielsweise die folgende Menü-/Untermenü-Hierarchie.


    ' 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

Der folgende Code verwendet das standardmäßige Untermenüzeichen „>“, um die oben definierte Menü-/Untermenühierarchie zu erstellen:


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

Die Zeichenfolge --- wird verwendet, um Trennlinien in Menüs oder Untermenüs zu definieren.

Symbole verwenden

Elemente im Menü können Symbole haben, die als Argumente in den Methoden AddCheckBox, AddItem und AddRadioButton angegeben werden.

Alle in Collabora Office verfügbaren Symbole können verwendet werden, indem ihr Pfad relativ zu dem Ordner angegeben wird, in dem sich die Symboldateien im Installationsordner befinden. Symbole befinden sich im folgenden Ordner:

INSTALLDIR/share/config

Verwenden Sie die Eigenschaft InstallFolder des Dienstes FileSystem, um festzustellen, wo Collabora Office in Ihrem System installiert ist.

Dieser Ordner enthält eine Reihe von ZIP-Dateien, welche die Bilddateien jedes verfügbaren Symbolsatzes enthalten. Die Bilder in diesen ZIP-Dateien sind in Ordnern organisiert. Um ein Symbol zu verwenden, geben Sie die Symboldatei mit dem Pfad zu ihrem Speicherort in der ZIP-Datei an.

Das folgende Beispiel verwendet das Symbol „sc_newdoc.svg“, das sich im Ordner „cmd“ befindet. Der Schrägstrich „/“ wird unabhängig vom Betriebssystem als Pfadtrennzeichen verwendet.

In Basic


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

In Python


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

Alle Icon-Sets haben die gleiche interne Struktur. Das tatsächlich angezeigte Symbol hängt von dem derzeit verwendeten Symbolsatz ab.

Methoden

Liste der Methoden im Dienst "Menu"
AddCheckBox	AddItem	AddRadioButton

AddCheckBox

Fügt ein Markierfeld in das Menü ein. Gibt einen ganzzahligen Wert zurück, der das eingefügte Element identifiziert.

Syntax:

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

Parameter:

menuitem: Definiert den im Menü anzuzeigenden Text. Dieses Argument definiert auch die Hierarchie des Elements innerhalb des Menüs, indem es das Untermenüzeichen verwendet.

name: Zeichenfolge zur Identifizierung des Menüpunkts. Standardmäßig wird die letzte Komponente der Menühierarchie verwendet.

status: Definiert, ob das Element ausgewählt ist, wenn das Menü erstellt wird (Standard = False).

icon: Pfad und Name des anzuzeigenden Symbols ohne führenden Pfadtrenner. Das tatsächlich angezeigte Symbol hängt vom verwendeten Symbolsatz ab.

tooltip: Text, der als Infobox angezeigt werden soll.

command: Der Name eines UNO-Befehls ohne das Präfix .uno:. Wenn der Befehlsname nicht existiert, passiert nichts.

script: Die URI für ein Basic- oder Python-Skript, das ausgeführt wird, wenn auf das Element geklickt wird.

Die Argumente command und script schließen sich gegenseitig aus, daher kann für jeden Menüpunkt nur eines davon gesetzt werden.

Lesen Sie Scripting Framework URI Specification, um mehr über die verwendete URI-Syntax im Argument script zu erfahren.

Beispiel:

In Basic


      ' Menüeintrag, der dem Befehl .uno:Paste zugeordnet ist
      oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")
      ' Führt das im Dokument gespeicherte Basic-Skript Standard.Module1.MyListener aus
      oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
      ' Führt das Python-Skript MyListener aus, das sich in der Datei myScripts.py im Benutzerskriptordner befindet
      oMenu.AddCheckBox("Item C", Status := True, Script := "vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")

In Python


      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

Fügt einen Beschriftungs-Eintrag in das Menü ein. Gibt einen ganzzahligen Wert zurück, der das eingefügte Element identifiziert.

Syntax:

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

Parameter:

menuitem: Legt den im Menü anzuzeigenden Text fest. Dieses Argument definiert auch die Hierarchie des Elements innerhalb des Menüs, indem es das Untermenüzeichen verwendet.

name: Zeichenfolge, die zurückgegeben wird, wenn auf das Element geklickt wird. Standardmäßig wird die letzte Komponente der Menühierarchie verwendet.

icon: Pfad und Name des anzuzeigenden Symbols ohne führenden Pfadtrenner. Das tatsächlich angezeigte Symbol hängt vom verwendeten Symbolsatz ab.

tooltip: Text, der als Infobox angezeigt werden soll.

command: Der Name eines UNO-Befehls ohne das Präfix .uno:. Wenn der Befehlsname nicht existiert, passiert nichts.

script: Die URI für ein Basic- oder Python-Skript, das ausgeführt wird, wenn auf das Element geklickt wird.

Die Argumente command und script schließen sich gegenseitig aus, daher kann für jeden Menüpunkt nur eines davon gesetzt werden.

Lesen Sie Scripting Framework URI Specification, um mehr über die verwendete URI-Syntax im Argument script zu erfahren.

Beispiel:

In Basic


      oMenu.AddItem("Eintrag A", Tooltip := "Eine beschreibende Nachricht")

In Python


      oMenu.AddItem("Eintrag A", Tooltip = "Eine beschreibende Nachricht")

AddRadioButton

Fügt einen Optionsfeld-Eintrag in das Menü ein. Gibt einen ganzzahligen Wert zurück, der das eingefügte Element identifiziert.

Syntax:

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

Parameter:

menuitem: Legt den im Menü anzuzeigenden Text fest. Dieses Argument definiert auch die Hierarchie des Elements innerhalb des Menüs, indem es das Untermenüzeichen verwendet.

name: Zeichenfolge, die zurückgegeben wird, wenn auf das Element geklickt wird. Standardmäßig wird die letzte Komponente der Menühierarchie verwendet.

status: Definiert, ob das Element ausgewählt ist, wenn das Menü erstellt wird (Standard = False).

icon: Pfad und Name des anzuzeigenden Symbols ohne führenden Pfadtrenner. Das tatsächlich angezeigte Symbol hängt vom verwendeten Symbolsatz ab.

tooltip: Text, der als Infobox angezeigt werden soll.

command: Der Name eines UNO-Befehls ohne das Präfix .uno:. Wenn der Befehlsname nicht existiert, passiert nichts.

script: Die URI für ein Basic- oder Python-Skript, das ausgeführt wird, wenn auf das Element geklickt wird.

Die Argumente command und script schließen sich gegenseitig aus, daher kann für jeden Menüpunkt nur eines davon gesetzt werden.

Lesen Sie Scripting Framework URI Specification, um mehr über die verwendete URI-Syntax im Argument script zu erfahren.

Beispiel:

In Basic


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

In Python


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

Alle ScriptForge Basic-Routinen oder Bezeichner, denen ein Unterstrich "_" vorangestellt ist, sind für den internen Gebrauch reserviert. Sie sind nicht für die Verwendung in Basic-Makros oder Python-Skripten vorgesehen.

Dienst SFWidgets.PopupMenu

Dienst SFDocuments.Document