Tjenesten SFWidgets.Menu
Tjenesten Menu kan bruges til at oprette og fjerne menuer fra menulinjen i et LibreOffice dokumentvindue. Hvert menupunkt kan tilknyttes til et script eller til en UNO-kommando. Tjenesten giver disse muligheder:
-
Oprettelse af menuer med tilpassede elementer, afkrydsningsfelter, alternativknapper og skilletegn.
-
Udstyrelse af menuelementer med ikoner og værktøjstips.
Menuer, der er oprettet med denne tjeneste, er kun tilgængelige i et bestemt dokumentvindue. De gemmes ikke i dokumentet eller som programindstillinger. Lukning og åbning af dokumentet vil gendanne menulinjens standardindstillinger.
Når OLE-objekter såsom Math-formler eller Calc-diagrammer redigeres inde i et dokument, genkonfigurerer LibreOffice menulinjen i overestemmelse med objektet. Når dette sker, fjernes menuer, der er oprettet med tjenesten Menu, og gendannes ikke efter redigering af OLE-objektet.
Kald af tjeneste
Før brug af tjenesten Menu skal biblioteket ScriptForge være indlæst eller importeret:
• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService
Tjenesten Menu er instatiereret ved kald af metoden CreateMenu (Opret_menu) i tjenesten Document (Dokument). Kodestumpen herunder opretter en menu ved navn Min menu i det aktuelle dokumentvindue med to elementer Element A og Element B.
Sub CreateMenu()
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
Dim oDoc as Object, oMenu as Object
Set oDoc = CreateScriptService("Document")
Set oMenu = oDoc.CreateMenu("Min menu")
With oMenu
.AddItem("Item A", Command := "Om")
.AddItem("Item B", Script := "vnd.sun.star.script:Standard.Module1.ItemB_Listener?language=Basic&location=application")
.Dispose()
End With
End Sub
Når menuen er oprettet, anbefales det at kalde metoden Dispose (Bortskaf) for at frigøre ressourcer, der bruges af en forekomst af tjenesten Menu.
I eksemplet herover er Element A knyttet til UNO-kommandoen .uno:About (uno:om), mens Element B er knyttet til scriptet ItemB_Listener defineret i Module1 i biblioteket Standard i containeren My Macros.
Det følgende eksempel definerer ItemB_Listener, som kaldes, når der klikkes på Element B. Denne listener (lytter) deler simpelthen den argumentstreng, der videregives til Sub (Undermodulet) og viser den i beskedfeltet.
Sub ItemB_Listener(args As String)
' Bearbejd argumentstrengen, der er videregivet til the listener (lytteren)
Dim sArgs as Object
sArgs = Split(args, ",")
MsgBox "Menu name: " & sArgs(0) & Chr(13) & _
"Menu item: " & sArgs(1) & Chr(13) & _
"Item ID: " & sArgs(2) & Chr(13) & _
"Item status: " & sArgs(3)
End Sub
Som vist i eksemplet herover får menuelementer, der er knyttet til et script, et komma-opdelt strengargument med følgende værdier:
-
Menuens topniveau-navn.
-
Det valgte menuelements streng-ID.
-
Det valgte menuelements numeriske ID.
-
Menuelementets aktuelle tilstand. Dette er nyttig i forhold til afkrydsningsfelter og alternativknapper. Hvis elementet er markeret, returneres værdien "1", ellers returneres "0".
Eksemplet herover kan skrives i Python på denne måde:
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"Menunavn: {s_args[0]}\n"
msg += f"menuelement: {s_args[1]}\n"
msg += f"Item ID: {s_args[2]}\n"
msg += f"Item status: {s_args[3]}"
bas.MsgBox(msg)
Egenskaber
|
Navn |
Skrivebeskyttet |
Type |
Beskrivelse |
|---|---|---|---|
|
ShortcutCharacter |
Nej |
String |
Tegn, der bruges til at definere adgangsnøglen til et menuelement. Standardtegnet er "~". |
|
SubmenuCharacter |
Nej |
String |
Tegn eller streng, der definerer, hvordan menuelementer indlejres. Standardtegnet er ">". |
Menu og undermenuer
Til at oprette en menu med undermenuer bruger du det tegn, der er defineret i egenskaben SubmenuCharacter, mens du opretter menuelementer for at definere, hvor det skal placeres. Overvej for eksempel det følgende menu/undermenu-hierarki.
' 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
Koden herunder bruger standard undermenu-tegnet ">" til oprette det menu/undermenu-hierarki, der er defineret ovenfor:
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")
The string --- is used to define separator lines in menus or submenus.
Brug af ikoner
Elementer i menuen kan have ikoner, som er angivet som argumenter i metoderne AddCheckBox, AddItem og AddRadioButton.
Alle tilgængelige koder i LibreOffice kan bruges ved at angive deres sti i forhold til den mappe, hvor ikonfilerne er placeret installationsmappen. Ikoner er placeret i denne mappe:
INSTALLDIR/share/config
Brug egenskaben InstallFolder (installer_mappe) i tjenesten FileSystem til at bestemme, hvor LibreOffice er installeret på dit system.
Denne mappe indeholder en serie ZIP-filer, der indeholder hvert tilgængeligt ikonsæts billedfiler. Billederne i disse ZIP-filer er organiseret i mapper. For at bruge et ikon angiver du ikonfilen med stien til dens placering inde i ZIP-filen.
Eksemplet herunder bruger ikonet "sc_newdoc.svg", der er placeret inde i mappen "cmd". Tegnet Skråstreg "/" bruges som sti-skilletegn uanset operativsystemet.
myMenu.AddItem("Item A", Icon := "cmd/sc_newdoc.svg")
myMenu.AddItem("Item A", icon="cmd/sc_newdoc.svg")
Alle ikonsæt har den samme interne struktur. Det faktisk viste ikon afhænger af det ikonsæt, der aktuelt er brug.
Metoder
Liste over metoder i tjenesten Menu |
||
|---|---|---|
AddCheckBox
Indsætter et afkrydsningsfelt i menuen. Returnerer en heltalsværdi, der identificerer det indsatte element.
svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int
menuitem: (menuelement) Definerer den tekst, der skal vises i menuen. Dette argument definerer også elementets hierarki i menuen ved af bruge undermenu-tegnet.
name: (navn) Strengværdi, brugt til at identificere menuelementet. Som standard bruges det sidste element i menuhierarkiet.
status: Definerer, om elementet er valgt, når menuen oprettes (Standard = False - falsk).
ikon: Sti til og navn på ikonet, der skal vises, uden det indledende stiskilletegn. Det faktisk viste ikon afhænger af det anvendte ikonsæt.
tooltip (værktøjstip): Tekst, der skal vises som værktøjstip.
command (kommando): Navnet på en UNO-kommando uden forstavelsen .uno:. Hvis kommandoen ikke findes, sker der intet.
script: URIen til et Basic eller Python-script, der bliver udført, når der klikkes på elementet.
Argumenterne command (kommando) og script (script) udelukker gensidigt hinanden, derfor kan der kun sættes en af dem i hvert menuelement.
Read Scripting Framework URI Specification to learn more about the URI syntax used in the script argument.
' Menuelement tilknyttet kommandoen .uno:Paste
oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")
' Kører Basic-scriptet Standard.Module1.MyListener, de er lagret i dokumentet
oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
' Kører Python-scriptet MyListener (Min_lytter) placeret i filen myScripts.py i mappen Brugerscripts
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
Indsætter et etiket-element i menuen. Returnerer en heltalsværdi, der identificerer det indsatte element.
svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int
menuitem (menuelement): Definerer teksten, der skal vises i menuen. Dette argument definerer også elementets plads i menuhierarkiet ved hjælp af undermenu-tegnet.
navn: Strengværdi, der skal returneres, når der klikkes på elementet. Som standard bruges det sidste element i menuhierarkiet.
ikon: Sti til og navn på ikonet, der skal vises, uden det indledende stiskilletegn. Det faktisk viste ikon afhænger af det anvendte ikonsæt.
værktøjstip: Tekst, der skal vises som værktøjstip.
command (kommando): Navnet på en UNO-kommando uden forstavelsen .uno:. Hvis kommandoen ikke findes, sker der intet.
script: URIen til et Basic eller Python-script, der bliver udført, når der klikkes på elementet.
Argumenterne command (kommando) og script (script) udelukker gensidigt hinanden, derfor kan der kun sættes en af dem i hvert menuelement.
Read Scripting Framework URI Specification to learn more about the URI syntax used in the script argument.
oMenu.AddItem("Item A", Tooltip := "En beskrivende besked")
oMenu.AddItem("Item A", tooltip = "En beskrivende besked")
AddRadioButton
Indsætter et alternativknap-element i menuen. Returnerer en heltalsværdi, der identificerer det indsatte element.
svc.AddRadioButton(menuitem: str, opt name: str, opt status: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int
menuitem (menuelement): Definerer teksten, der skal vises i menuen. Dette argument definerer også elementets plads i menuhierarkiet ved hjælp af undermenu-tegnet.
navn: Strengværdi, der skal returneres, når der klikkes på elementet. Som standard bruges det sidste element i menuhierarkiet.
status: Definerer, om elementet er valgt, når menuen oprettes (Standard = False - falsk).
ikon: Sti til og navn på ikonet, der skal vises, uden det indledende stiskilletegn. Det faktisk viste ikon afhænger af det anvendte ikonsæt.
værktøjstip: Tekst, der skal vises som værktøjstip.
command (kommando): Navnet på en UNO-kommando uden forstavelsen .uno:. Hvis kommandoen ikke findes, sker der intet.
script: URIen til et Basic eller Python-script, der bliver udført, når der klikkes på elementet.
Argumenterne command (kommando) og script (script) udelukker gensidigt hinanden, derfor kan der kun sættes en af dem i hvert menuelement.
Read Scripting Framework URI Specification to learn more about the URI syntax used in the script argument.
oMenu.AddRadioButton("Item A", Name := "A", Status := True)
oMenu.AddRadioButton("Item A", name="A", status=True)
Alle ScriptForge Basic-rutiner eller identifikatorer, der er indledet med et understreget tegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.