Contenuto

# Servizio SFWidgets.PopupMenu

Il servizio PopupMenu può essere usato per creare menu a comparsa che possono essere associati ad eventi o eseguiti da script. Questo servizio fornisce le seguenti funzionalità:

- creazione di menu a comparsa con voci personalizzate, caselle di controllo e pulsanti di scelta;

- decorazione delle voci di menu con icone e suggerimenti.

## Invocazione del servizio

Prima di usare il servizio PopupMenu è 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 PopupMenu può essere istanziato in diversi modi. L'esempio sottostante crea un menu a comparsa senza associarlo a un evento del mouse o dell'applicazione.

        Sub ShowPopup
            GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
            Dim myPopup As Object
            Set myPopup = CreateScriptService("SFWidgets.PopupMenu", , 300, 300)
            myPopup.AddItem("Item ~A")
            myPopup.AddItem("Item ~B")
            vResponse = myPopup.Execute()
            MsgBox("ID dell'elemento selezionato: " & vResponse)
            myPopup.Dispose()
        End Sub

L'esecuzione della Sub (subroutine) definita in precedenza creerà un menu a comparsa con due voci nella posizione X=300 e Y=300 sullo schermo.

Il prefisso SFWidgets può essere omesso durante l'invocazione del servizio PopupMenu.

L'esempio seguente definisce una Sub (subroutine) che può essere associata a un evento del mouse:

        Sub MyPopupClick(Optional poMouseEvent as Object)
            Dim myPopup As Object
            Set myPopup = CreateScriptService("PopupMenu", poMouseEvent)
            ' Popola il menu a comparsa con degli elementi
            Dim vResponse As Variant
            vResponse = myPopup.Execute(False)
            ' Esegue qualcosa a seconda di vResponse
            ' ...
            myPopup.Dispose()
        End Sub

Usate il metodo Dispose per liberare risorse dopo l'esecuzione del menu a comparsa.

È possibile associare un menu a comparsa anche agli eventi attivati dai controlli delle applicazioni di LibreOffice, dei formulari e delle finestre di dialogo. Eventi come "Pulsante del mouse premuto" e "Pulsante del mouse rilasciato" sono comunemente associati ai menu a comparsa.

        Sub MyPopupClick(Optional poEvent as Object)
            Dim myPopup As Object
            Set myPopup = CreateScriptService("PopupMenu", poEvent)
            ' ...
        End Sub

##### In Python

Gli esempi qui sopra possono essere scritti in Python come segue:

        from scriptforge import CreateScriptService

        def show_popup(args=None):
            my_popup = CreateScriptService("SFWidgets.PopupMenu", None, 300, 300)
            bas = CreateScriptService("Basic")
            my_popup.AddItem("Item ~A")
            my_popup.AddItem("Item ~B")
            response = my_popup.Execute()
            bas.MsgBox(f"Selected item ID: {response}")
            my_popup.Dispose()

        def my_popup_click(poEvent=None):
            my_popup = CreateScriptService("SFWidgets.PopupMenu", poEvent)
            # Popola il menu a comparsa con delle voci
            response = my_popup.Execute()
            # Esegue qualcosa a seconda della risposta
            my_popup.Dispose()

## Proprietà

Nome | Sola lettura | Tipo | Descrizione
--- | --- | --- | ---
ShortcutCharacter | No | String | Carattere usato per definire il tasto 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 a comparsa 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:

        myPopup.AddItem("Item A")
        myPopup.AddItem("Item B>Item B.1")
        myPopup.AddItem("Item B>Item B.2")
        myPopup.AddItem("---")
        myPopup.AddItem("Item C>Item C.1>Item C.1.1")
        myPopup.AddItem("Item C>Item C.1>Item C.1.2")
        myPopup.AddItem("Item C>Item C.2>Item C.2.1")
        myPopup.AddItem("Item C>Item C.2>Item C.2.2")
        myPopup.AddItem("Item C>Item C.2>---")
        myPopup.AddItem("Item C>Item C.2>Item C.2.3")
        myPopup.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 PopupMenu
AddCheckBox AddItem | AddRadioButton | Execute

## AddCheckBox

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

### Sintassi:

svc.AddCheckBox(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: 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.

### Esempio:

##### In Basic

          myPopup.AddCheckBox("Option A", Status := True)

##### In Python

          my_popup.AddCheckBox("Option A", status=True)

## AddItem

Inserisce una voce nel menu a comparsa. Restituisce un valore intero che identifica l'elemento inserito.

### Sintassi:

svc.AddItem(menuitem: str, opt name: str, opt icon: str, opt tooltip: 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.

### Esempio:

##### In Basic

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

##### In Python

          my_popup.AddItem("Voce A", tooltip = "Messaggio descrittivo")

## AddRadioButton

Inserisce una voce con pulsante di scelta nel menu a comparsa. Restituisce un valore intero che identifica la voce inserita.

### Sintassi:

svc.AddRadioButton(menuitem: str, opt name: str, opt status: bool = False, opt icon: str, opt tooltip: 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.

### Esempio:

##### In Basic

          myPopup.AddRadioButton("Option A", Name := "A", Status := True)

##### In Python

          my_popup.AddRadioButton("Option A", name="A", status=True)

## Execute

Visualizza il menu a comparsa ed attende l'azione dell'utente. Restituisce la voce selezionata dall'utente.

Se l'utente fa clic all'esterno del menu a comparsa o preme il tasto Esc, non viene selezionata alcuna voce. In tal caso, il valore restituito dipende del parametro returnid. Se returnid = True e non viene selezionata alcuna voce, viene restituito il valore 0 (zero). Altrimenti viene restituita una stringa vuota "".

### Sintassi:

svc.Execute(opt returnid: bool = True): any

### Parametri:

returnid: se è impostato su True sarà restituito l'ID della voce selezionata. Se è False il metodo restituisce il nome della voce (predefinito = True).

### Esempio:

Negli esempi sottostanti viene creato un menu a comparsa e viene restituito il nome della voce, questo perchè l'argomentoreturnid è impostato come False.

##### In Basic

          myPopup.AddItem("Item A", Name := "A")
          myPopup.AddItem("Item B", Name := "B")
          Dim vResponse as Variant
          vResponse = myPopup.Execute(False)

##### In Python

          my_popup.AddItem("Item A", name="A")
          my_popup.AddItem("Item B", name="B")
          response = my_popup.Execute(False)

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 SFDialogs.Dialog

Servizio SFDialogs.DialogControl

Servizio SFWidgets.Menu