Spis treści

# Usługa SFWidgets.Menu

Usługa Menu może być używana do tworzenia i usuwania menu z paska menu okna dokumentu LibreOffice. Każda pozycja menu może być powiązana ze skryptem lub poleceniem UNO. Ta usługa zapewnia następujące możliwości:

- Tworzenie menu z niestandardowymi wpisami, polami wyboru, przyciskami opcji i separatorami.

- Dodanie ikon i podpowiedzi do pozycji menu.

Menu utworzone za pomocą tej usługi są dostępne tylko dla określonego okna dokumentu. Nie są one zapisywane w dokumencie ani jako ustawienia aplikacji. Zamknięcie i otwarcie dokumentu spowoduje przywrócenie domyślnych ustawień paska menu.

Kiedy obiekty OLE, takie jak formuły matematyczne lub wykresy Calc, są edytowane w dokumencie, LibreOffice ponownie konfiguruje pasek menu zgodnie z obiektem. Gdy tak się stanie, menu utworzone za pomocą usługi Menu zostaną usunięte i nie zostaną przywrócone po edycji obiektu OLE.

## Wywoływanie usługi

Przed użyciem usługi Menu należy załadować lub zaimportować bibliotekę ScriptForge:

• Podstawowe makra wymagają załadowania biblioteki ScriptForge przy użyciu następującej instrukcji:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Skrypty Pythona wymagają importu z modułu scriptforge:
from scriptforge import CreateScriptService

##### W języku Basic

Instancja usługi Menu jest tworzona poprzez wywołanie metody CreateMenu z usługi Document. Poniższy fragment kodu tworzy menu o nazwie Moje menu w bieżącym oknie dokumentu z dwoma wpisami Element A i Element B.

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

Po utworzeniu menu zaleca się wywołać metodę Dispose w celu zwolnienia zasobów wykorzystywanych przez instancję usługi Menu.

W powyższym przykładzie Element A jest powiązany z poleceniem UNO .uno:About, natomiast Element B jest powiązany ze skryptem ItemB_Listener zdefiniowany w Module1 biblioteki Standard kontenera Moje makra.

Poniższy przykład definiuje ItemB_Listener, który zostanie wywołany po kliknięciu Element B. Ten słuchacz po prostu dzieli ciąg argumentów przekazany do Sub i wyświetla go w oknie komunikatu.

        Sub ItemB_Listener(args As String)
            ' Przetwórz ciąg argumentu przekazany do słuchacza
            Dim sArgs as Object
            sArgs = Split(args, ",")
            MsgBox "Nazwa menu: "   & sArgs(0) & Chr(13) & _
                   "Element menu: "   & sArgs(1) & Chr(13) & _
                   "Identyfikator elementu: "     & sArgs(2) & Chr(13) & _
                   "Stan elementu: " & sArgs(3)
        End Sub

Jak pokazano w powyższym przykładzie, pozycje menu powiązane ze skryptem otrzymują argument w postaci ciągu znaków oddzielonych przecinkami o następujących wartościach:

- Nazwa najwyższego poziomu menu.

- Identyfikator ciągu wybranego wpisu menu.

- Numeryczny identyfikator wybranej pozycji menu.

- Bieżący stan elementu menu. Jest to przydatne w przypadku pól wyboru i przycisków opcji. Jeśli element jest zaznaczony, zwracana jest wartość "1", w przeciwnym razie zwracane jest "0".

##### W języku Python

Powyższe przykłady można zapisać w Pythonie w następujący sposób:

        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"Nazwa menu: {s_args[0]}\n"
            msg += f"Element menu: {s_args[1]}\n"
            msg += f"Identyfikator elementu: {s_args[2]}\n"
            msg += f"Stan elementu: {s_args[3]}"
            bas.MsgBox(msg)

## Właściwości

Nazwa | Tylko do odczytu | Typ | Opis
--- | --- | --- | ---
ShortcutCharacter | Nie | String | Znak używany do określenia klawisza skrótu dla elementu menu. Domyślnym znakiem jest "~".
SubmenuCharacter | Nie | String | Znak lub ciąg definiujący sposób zagnieżdżenia elementów menu. Domyślnym znakiem jest ">".

## Menu i podmenu

Aby utworzyć menu za pomocą podmenu, użyj znaku zdefiniowanego we właściwości SubmenuCharacter podczas tworzenia wpisu menu, aby określić, gdzie zostanie umieszczony. Na przykład rozważ następującą hierarchię menu/podmenu.

        ' 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

Poniższy kod używa domyślnego znaku podmenu ">", aby utworzyć określoną powyżej hierarchię menu/podmenu:

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

Ciąg --- służy do definiowania wiersza separatora w menu lub podmenu.

### Korzystanie z ikon

Elementy menu mogą mieć ikony określone jako argumenty w metodach AddCheckBox, AddItem i AddRadioButton

Ze wszystkich ikon dostępnych w LibreOffice można skorzystać podając ich ścieżkę względem folderu, w którym znajdują się pliki ikon, w folderze instalacyjnym. Ikony znajdują się w następującym folderze:

INSTALLDIR/share/config

Użyj właściwości InstallFolder usługi FileSystem, aby określić, gdzie w systemie jest zainstalowany LibreOffice.

Ten folder zawiera serię plików ZIP zawierających pliki obrazów każdego dostępnego zestawu ikon. Obrazy znajdujące się w tych plikach ZIP są zorganizowane w folderach. Aby użyć ikony, określ plik ikony ze ścieżką do jej lokalizacji w pliku ZIP.

Poniższy przykład wykorzystuje ikonę "sc_newdoc.svg", która znajduje się w folderze "cmd". Znak ukośnika "/" jest używany jako separator ścieżki niezależnie od systemu operacyjnego.

##### W języku Basic

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

##### W języku Python

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

Wszystkie zestawy ikon mają tę samą strukturę wewnętrzną. Rzeczywista wyświetlana ikona zależy od aktualnie używanego zestawu ikon.

## Metody

Lista metod w usłudze Menu
AddCheckBox | AddItem | AddRadioButton

## AddCheckBox

Wstawia pole wyboru w menu. Zwraca wartość całkowitą, która identyfikuje wstawiony element.

### Składnia:

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: definiuje tekst, który ma być wyświetlany w menu. Ten argument określa również hierarchię elementu wewnątrz menu za pomocą znaku podmenu.

name: wartość ciągu używana do identyfikacji elementu menu. Domyślnie używany jest ostatni element hierarchii menu.

status: określa, czy element jest wybierany po utworzeniu menu (domyślnie = False).

icon: ścieżka i nazwa ikony, które należy wyświetlić bez wiodącego separatora ścieżki. Rzeczywista pokazana ikona zależy od zastosowanego zestawu ikony.

tooltip: tekst do wyświetlenia jako podpowiedź.

command: nazwa polecenia UNO bez prefiks .uno:. Jeśli nazwa polecenia nie istnieje, nic się nie dzieje.

script: URI dla skryptu podstawowego lub Pythona, który zostanie wykonany po kliknięciu elementu.

Argumenty command i script są wzajemnie wykluczające się, dlatego tylko jeden z nich można ustawić dla każdego elementu menu.

Przeczytaj Scripting Framework URI Specification, aby dowiedzieć się więcej o używanej składni URI w argumencie script.

### Przykład:

##### W języku Basic

          ' Wpis menu powiązany z poleceniem .uno:Paste
          oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")
          ' Uruchamia skrypt Basic Standard.Module1.MyListener zapisany w dokumencie
          oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
          ' Uruchamia skrypt Pythona MyListener zlokalizowany w pliku myScripts.py w folderze skryptów użytkownika
          oMenu.AddCheckBox("Item C", Status := True, Script := "vnd.sun.star.script:myScripts.py$MyListener?language=Python&location=user")

##### W języku 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

Wstawia element z etykietą w menu. Zwraca wartość całkowitą wskazującą wstawiony element.

### Składnia:

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

### Parametry:

menuitem: definiuje tekst, który ma być wyświetlany w menu. Ten argument określa również hierarchię elementu wewnątrz menu za pomocą znaku podmenu.

name: wartość ciągu, którą należy zwrócić po kliknięciu elementu. Domyślnie używany jest ostatni element hierarchii menu.

icon: ścieżka i nazwa ikony, które należy wyświetlić bez wiodącego separatora ścieżki. Rzeczywista pokazana ikona zależy od zastosowanego zestawu ikony.

tooltip: tekst do wyświetlenia jako podpowiedź.

command: nazwa polecenia UNO bez prefiks .uno:. Jeśli nazwa polecenia nie istnieje, nic się nie dzieje.

script: URI dla skryptu podstawowego lub Pythona, który zostanie wykonany po kliknięciu elementu.

Argumenty command i script są wzajemnie wykluczające się, dlatego tylko jeden z nich można ustawić dla każdego elementu menu.

Przeczytaj Scripting Framework URI Specification, aby dowiedzieć się więcej o używanej składni URI w argumencie script.

### Przykład:

##### W języku Basic

          oMenu.AddItem("Element A", Tooltip := "Opisowy komunikat")

##### W języku Python

          oMenu.AddItem("Element A", tooltip = "Opisowy komunikat")

## AddRadioButton

Wstawia wpis przycisku opcji w menu. Zwraca wartość całkowitą, która identyfikuje wstawiony element.

### Składnia:

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: definiuje tekst, który ma być wyświetlany w menu. Ten argument określa również hierarchię elementu wewnątrz menu za pomocą znaku podmenu.

name: wartość ciągu, którą należy zwrócić po kliknięciu elementu. Domyślnie używany jest ostatni element hierarchii menu.

status: określa, czy element jest wybierany po utworzeniu menu (domyślnie = False).

icon: ścieżka i nazwa ikony, które należy wyświetlić bez wiodącego separatora ścieżki. Rzeczywista pokazana ikona zależy od zastosowanego zestawu ikony.

tooltip: tekst do wyświetlenia jako podpowiedź.

command: nazwa polecenia UNO bez prefiks .uno:. Jeśli nazwa polecenia nie istnieje, nic się nie dzieje.

script: URI dla skryptu podstawowego lub Pythona, który zostanie wykonany po kliknięciu elementu.

Argumenty command i script są wzajemnie wykluczające się, dlatego tylko jeden z nich można ustawić dla każdego elementu menu.

Przeczytaj Scripting Framework URI Specification, aby dowiedzieć się więcej o używanej składni URI w argumencie script.

### Przykład:

##### W języku Basic

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

##### W języku Python

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

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.

Tematy pokrewne

Usługa SFWidgets.PopupMenu

Usługa SFDocuments.Document