Servizio SFWidgets.Menu
Il servizio Menu può essere usato per creare ed eliminare dei menu dalla barra dei menu della finestra dei documenti di LibreOffice. Ogni voce di menu può essere associata a uno script o a un comando UNO. Questo servizio fornisce le seguenti capacità:
-
Creazione di menu con voci, caselle di controllo, pulsanti di scelta e separatori personalizzati.
-
Decorazione delle voci di menu con icone e suggerimenti.
I menu creati con questo servizio sono disponibili solo per una specifica finestra del documento. Non vengono salvati nel documento o come impostazioni del programma. La chiusura e la riapertura del documento ripristinerà le impostazioni predefinite della barra dei menu.
Quando degli oggetti OLE come le formule di Math o i grafici di Calc vengono modificati all'interno di un documento, LibreOffice riconfigura la barra dei menu a seconda dell'oggetto. Quando ciò accade, i menu creati con il servizio Menu sono eliminati e non vengono ripristinati al termine della modifica dell'oggetto OLE.
Invocazione del servizio
Prima di usare il servizio Menu è necessario caricare o importare le librerie ScriptForge:
• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Gli script in Python richiedono un'importazione dal modulo scriptforge:
from scriptforge import CreateScriptService
Il servizio Menu viene istanziato chiamando il metodo CreateMenu del servizio Document. Il frammento di codice sottostante crea nella finestra del documento corrente un menu denominato Mio Menu con due voci Voce A e Voce B.
Sub CreateMenu()
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
Dim oDoc as Object, oMenu as Object
Set oDoc = CreateScriptService("Document")
Set oMenu = oDoc.CreateMenu("Mio Menu")
With oMenu
.AddItem("Voce A", Command := "Informazioni")
.AddItem("Voce B", Script := "vnd.sun.star.script:Standard.Module1.ItemB_Listener?language=Basic&location=application")
.Dispose()
End With
End Sub
Dopo aver creato il menu, si raccomanda di chiamare il metodo Dispose per liberare le risorse usate dall'istanza del servizio Menu.
Nell'esempio qui sopra, Voce A è associata al comando UNO .uno:About mentre Voce B è associata allo script ItemB_Listener definito in Module1 della libreria Standard del contenitore Macro personali.
L'esempio seguente definisce ItemB_Listener che sarà chiamato quando si farà clic su Voce B. Questo "ascoltatore" semplicemente spezza la stringa passata come argomento alla Sub e la visualizza in un riquadro di dialogo.
Sub ItemB_Listener(args As String)
' Elabora la stringa passata come argomento allo "ascoltatore"
Dim sArgs as Object
sArgs = Split(args, ",")
MsgBox "Nome menu: " & sArgs(0) & Chr(13) & _
"Voce del menu: " & sArgs(1) & Chr(13) & _
"ID della voce: " & sArgs(2) & Chr(13) & _
"Stato della voce: " & sArgs(3)
End Sub
Come mostrato nell'esempio qui sopra, le voci del menu associate a uno script ricevono come argomento una stringa separata da virgole contenente i seguenti valori:
-
Il nome del livello superiore del menu.
-
La stringa con l'ID della voce del menu selezionata.
-
L'ID numerico della voce del menu selezionata.
-
Lo stato attuale della voce del menu. Questo è utile per le caselle di controllo e per i pulsanti di scelta. Se la voce è selezionata, è restituito il valore "1", altrimenti "0".
Gli esempi qui sopra possono essere scritti in Python come segue:
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"Nome del menu: {s_args[0]}\n"
msg += f"Voce del menu: {s_args[1]}\n"
msg += f"ID della voce: {s_args[2]}\n"
msg += f"Stato della voce: {s_args[3]}"
bas.MsgBox(msg)
Proprietà
|
Nome |
Sola lettura |
Tipo |
Descrizione |
|---|---|---|---|
|
ShortcutCharacter |
No |
String |
Carattere usato per definire la chiave di accesso alla voce del menu. Il carattere predefinito è "~". |
|
SubmenuCharacter |
No |
String |
Carattere o stringa che definisce in quale modo le voci del menu sono nidificate. Il carattere predefinito è ">". |
Menu e sottomenu
Per creare un menu con dei sottomenu, usate il carattere definito nella proprietà SubmenuCharacter per creare la voce di menu che definisce dove saranno posizionati. Per esempio, prendete in considerazione la seguente gerarchia di menu/sottomenu.
' 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
Il codice sottostante usa il carattere predefinito ">" per i sottomenu in modo da creare la gerarchia menu/sottomenu definita in precedenza:
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")
La stringa --- è usata per definire delle linee di separazione nei menu o nei sottomenu.
Uso di icone
Le voci del menu possono avere delle icone, che sono specificate come argomenti dei metodi AddCheckBox, AddItem e AddRadioButton.
Tutte le icone disponibili in LibreOffice possono essere usate specificando il loro percorso relativo alla cartella nella quale i file con le icone sono memorizzati all'interno della cartella d'installazione. Le icone si trovano nella seguente cartella:
INSTALLDIR/share/config
Usate la proprietà InstallFolder del servizio FileSystem per determinare dove LibreOffice è installato nel vostro sistema.
Questa cartella contiene una serie di file compressi (ZIP) che contengono i file con le immagini di ogni tema di icone. Le immagini all'interno dei file ZIP sono organizzate in cartelle. Per usare un'icona, specificate il suo file con il percorso della sua posizione all'interno del file ZIP.
L'esempio sottostante usa l'icona "sc_newdoc.svg" che si trova all'interno della cartella "cmd". Il carattere della barra inversa "/" è usato come separatore del percorso indipendentemente dal sistema operativo.
myMenu.AddItem("Item A", Icon := "cmd/sc_newdoc.svg")
myMenu.AddItem("Item A", icon="cmd/sc_newdoc.svg")
Tutti i temi di icone hanno la stessa struttura interna. L'icona effettivamente visualizzata dipende dal tema di icone correntemente in uso.
Metodi
Elenco dei metodi del servizio Menu |
||
|---|---|---|
AddCheckBox
Inserisce una casella di controllo nel menu. Restituisce un valore intero che identifica l'elemento inserito.
svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int
menuitem: definisce il testo da visualizzare nel menu. Questo argomento definisce anche la gerarchia della voce all'interno del menu attraverso l'uso del carattere che indica i sottomenu.
name: valore in formato stringa che identifica la voce del menu. Per impostazione predefinita, viene usato l'ultimo componente nella gerarchia del menu.
status: definisce se la voce è selezionata al momento della creazione del menu (predefinito = False).
icon: percorso e nome dell'icona da visualizzare senza il separatore di percorso iniziale. L'icona effettivamente visualizzata dipende dal tema di icone in uso.
tooltip: testo da visualizzare come suggerimento.
command: il nome del comando UNO senza il prefisso .uno:. Se il nome del comando non esiste, non succede nulla.
script: l'URI dello script Basic o Python che sarà eseguito quando la voce riceve un clic.
Gli argomenti command e script si escludono a vicenda, perciò è possibile impostare uno solo dei due per ciascuna voce del menu.
Per saperne di più sulla sintassi degli URI usati nell'argomento script, leggere le Specifiche URI del framework di scripting.
' Voce del menu associata al comando .uno:Paste
oMenu.AddCheckBox("Item A", Status := True, ToolTip := "Paste values", Command := "Paste")
' Esegue lo script in Basic Standard.Module1.MyListener memorizzato nel documento
oMenu.AddCheckBox("Item B", Status := False, Script := "vnd.sun.star.script:Standard.Module1.MyListener?language=Basic&location=document")
' Esegue lo script in Python MyListener situato nel file myScripts.py all'interno della cartella degli script personali
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
Inserisce l'etichetta di una voce nel menu. Restituisce un valore intero che identifica la voce inserita.
svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int
menuitem: definisce il testo da visualizzare nel menu. Questo argomento definisce anche la gerarchia della voce all'interno del menu attraverso l'uso del carattere che indica i sottomenu.
name: valore in formato stringa da restituire quando la voce riceve un clic. Per impostazione predefinita, viene usato l'ultimo componente nella gerarchia del menu.
icon: percorso e nome dell'icona da visualizzare senza il separatore di percorso iniziale. L'icona effettivamente visualizzata dipende dal tema di icone in uso.
tooltip: testo da visualizzare come suggerimento.
command: il nome del comando UNO senza il prefisso .uno:. Se il nome del comando non esiste, non succede nulla.
script: l'URI dello script Basic o Python che sarà eseguito quando la voce riceve un clic.
Gli argomenti command e script si escludono a vicenda, perciò è possibile impostare uno solo dei due per ciascuna voce del menu.
Per saperne di più sulla sintassi degli URI usati nell'argomento script, leggere le Specifiche URI del framework di scripting.
oMenu.AddItem("Voce A", Tooltip := "Messaggio descrittivo")
oMenu.AddItem("Voce A", tooltip = "Messaggio descrittivo")
AddRadioButton
Inserisce nel menu una voce con pulsante di scelta. Restituisce un valore intero che identifica la voce inserita.
svc.AddRadioButton(menuitem: str, opt name: str, opt status: str, opt icon: str, opt tooltip: str, opt command: str, opt script: str): int
menuitem: definisce il testo da visualizzare nel menu. Questo argomento definisce anche la gerarchia della voce all'interno del menu attraverso l'uso del carattere che indica i sottomenu.
name: valore in formato stringa da restituire quando la voce riceve un clic. Per impostazione predefinita, viene usato l'ultimo componente nella gerarchia del menu.
status: specifica se la voce è selezionata al momento della creazione del menu (predefinito = False).
icon: percorso e nome dell'icona da visualizzare senza il separatore di percorso iniziale. L'icona effettivamente visualizzata dipende dal tema di icone in uso.
tooltip: testo da visualizzare come suggerimento.
command: il nome del comando UNO senza il prefisso .uno:. Se il nome del comando non esiste, non succede nulla.
script: l'URI dello script Basic o Python che sarà eseguito quando la voce riceve un clic.
Gli argomenti command e script si escludono a vicenda, perciò è possibile impostare uno solo dei due per ciascuna voce del menu.
Per saperne di più sulla sintassi degli URI usati nell'argomento script, leggere le Specifiche URI del framework di scripting.
oMenu.AddRadioButton("Item A", Name := "A", Status := True)
oMenu.AddRadioButton("Item A", name="A", status=True)
Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.