Contenuto

# 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

##### In Basic

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

##### In Python

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.

##### In Basic

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

##### In Python

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

## AddCheckBox

Inserisce una casella di controllo nel menu. Restituisce un valore intero che identifica l'elemento inserito.

### Sintassi:

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

### Parametri:

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.

### Esempio:

##### In Basic

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

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

Inserisce l'etichetta di una voce nel menu. Restituisce un valore intero che identifica la voce inserita.

### Sintassi:

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

### Parametri:

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.

### Esempio:

##### In Basic

          oMenu.AddItem("Voce A", Tooltip := "Messaggio descrittivo")

##### In Python

          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.

### Sintassi:

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

### Parametri:

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.

### Esempio:

##### In Basic

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

##### In Python

          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.

Argomenti correlati

Servizio SFWidgets.PopupMenu

Servizio SFDocuments.Document