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

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
  

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à

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.

      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

AddCheckBox

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

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

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

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

AddItem

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

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

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

      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.

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

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

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

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

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

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

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

      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.