bancaldo™

torna all’indice degli appunti

FileChooserDialog

Il widget Gtk.FileChooserDialog è un box dialog utilizzato per l’apertura/salvataggio di un file.
Implementa l’interfaccia Gtk.FileChooser
in modo da poterne utilizzare tutti i metodi.
Qualora si decidesse di utilizzare il FileChooserDialog nativo dell’OS in uso, utilizzare la
classe Gtk.FileChooserNative.
Il FileChooserDialog, eredita dal widget Gtk.Dialog, il metodo run() che lo rende
modale e ritorna il response alla window genitore.

Per creare un message dialog si utilizza il costruttore Gtk.FileChooserDialog (*args, **kwargs).

La property principale dell’oggetto filechooserdialog è :

Name	Short Description
parent	la top-level window che genera il filechooserdialog

Le altre properties sono quelle ereditate da Gtk.FileChooser:

Name	Type	Flags	Short Description
action	Gtk.FileChooserAction	r/w	Il tipo di operazione che il file selector può eseguire
create-folders	bool	r/w	un boolean che permette di creare un directory in open mode
do-overwrite-confirmation	bool	r/w	un boolean che setta in save mode la conferma di sovrascrittura per un file esistente
extra-widget	Gtk.Widget	r/w	l’oggetto Gtk.FileFilter utilizzato per la visualizzazione dei files nel filechooser
filter	Gtk.FileFilter	r/w	The current filter for selecting which files are displayed
local-only	bool	r/w	un boolean per decidere se i file selezionati devono essere locali
preview-widget	Gtk.Widget	r/w	un widget extra fornito da Application per le anteprime (previews) personalizzate
preview-widget-active	bool	r/w	un boolean che setta se il widget extra fornito da Application per le previews debba essere visualizzato
select-multiple	bool	r/w	un boolean che permette la selezione di file multipli (True)
show-hidden	bool	r/w	un boolean per la visualizzazione di file nascosti (True)
use-preview-label	bool	r/w/td>	un boolean per visualizzare una stock label col il nome del file previewed

Segnali

I segnali principali sono:

Name	Short Description
confirm-overwrite	questo segnale viene emesso quando l’utente seleziona un file esistente ed è appropriato visualizzare un messaggio di conferma
current-folder-changed	segnale emesso quando la directory corrente cambia
file-activated	segnale emesso quando l’utente attiva un file nel filechooser
selection-changed	segnale emesso quando la selezione di file, cambia
update-preview	segnale emesso quando l’anteprima nel filechooser deve essere rigenerata

Metodi

Come già anticipato il widget Gtk.FileChooserDialog non possiede metodi propri.
Da Gtk.Dialog eredita:

add_buttons(*args)

Aggiunge multipli bottoni al dialog usando i dati relativi al bottone da aggiungere, ovvero il
button text (o uno STOCK_ID) e il tipo di response che questo button genera.
Questo metodo equivale a chiamare ripetutamente il metodo add_button.
I dati del bottone viaggiano in coppia, ad esempio per inserire 2 Buttons “OPEN” e “CLOSE”, faremo:

>>> dialog = Gtk.FileChooserDialog(title="Choose a file", action=Gtk.FileChooserAction.OPEN)
>>> dialog.add_buttons(Gtk.STOCK_CANCEL, Gtk.ResponseType.CANCEL,
...                    Gtk.STOCK_OK, Gtk.ResponseType.OK)

run()

Si blocca in un loop e rimane bloccato fino a che il filechooserdialog non emette un segnale
“response”, oppure viene distrutto.
Se il dialog viene distrutto durante la chiamata a Gtk.Dialog.run(), lo stesso
metodo ritorna un response di tipo Gtk.ResponseType.NONE.
Altrimenti ritorna il response_ID dall’emissione del segnale “response”.
Prima di entrare nel loop, Gtk.Dialog.run() chiama il metodo Gtk.Widget.show() sul dialog per visualizzarlo.

Dall’interfaccia Gtk.FileChooser eredita invece:

add_choice(id, label, options, option_labels)

Aggiunge una scelta (choice) al filechooser. Generalmente viene implementata come una combobox,
o per le scelte True/False con un checkbutton.
Possiamo selezionare un valore usando il metodo Gtk.FileChooser.set_choice(), prima che il dialog
sia visualizzato e possiamo recuperare il valore selezionato dall’utente, nell’handler del segnale
“response”, usando il metodo Gtk.FileChooser.get_choice().
Parametri:
id: un stringa (str) cheindica l’id della choice aggiunta;
label: la stringa visibile all’utente per la “choice” aggiunta;
options: una lista di stringhe di id relativi alle opzioni della
choice, o None per una choice di tipo True/False;
option_labels: una lista di stringhe corrispondenti ai precedenti ids.
La lunghezza della lista deve essere identica a quella di options;

add_filter(filter)

Aggiunge un filter alla lista dei filters che l’utente può selezionare dal menu nel filechooser.
Solo i file che passeranno questo filter, verranno visualizzati nel filechooser.
Parametri:
filter: l’oggetto di tipo Gtk.FileFilter,
che si occupa di filtrare i files.

add_shortcut_folder(folder)

Aggiunge una folder nella sezione scorciatoie del filechooser.
Parametri:
folder: la stringa che identifica il percorso della folder da aggiungere;

add_shortcut_folder_uri(uri)

Aggiunge una URI di una folder nella sezione scorciatoie del filechooser.
Parametri:
uri: la stringa che identifica la URI della directory da visualizzare nelle shortcuts del filechooser;

get_action()

Ritorna il tipo di “action” (Gtk.FileChooserAction)
impostata nel filechooser (vedere set_action(action) per i dettagli).

>>> dialog = Gtk.FileChooserDialog(title="File Chooser", parent=None,
...                                action=Gtk.FileChooserAction.OPEN)
>>> dialog.get_action()
<enum GTK_FILE_CHOOSER_ACTION_OPEN of type Gtk.FileChooserAction>

get_choice(id)

Ritorna la “choice” selezionata nel filechooser, con l’id passato come argomento (vedi add_choice()).
Parametri:
id: la stringa dell’ID della “choice” effettuata;

get_create_folders()

Ritorna True se il filechooser visualizza il bottone che permette di creare una nuova folder (attiva di default).

get_current_folder()

Ritorna il percorso completo della folder corrente, ovvero la folder che il filechooser visualizza.

get_current_folder_file()

Ritorna l’oggetto Gio.File della folder corrente del filechooser.

get_current_folder_uri()

Ritorna l’URI della folder corrente. Questa è la folder che il filechooser sta visualizzando.

get_current_name()

Ritorna il raw text della entry “Name” del filechooser.

get_do_overwrite_confirmation()

Ritorna True se il filechooser presenterà un boxdialog di conferma di sovrascrittura di un file esistente.

get_extra_widget()

Ritorna l’extra widget corrente del filechooser.

get_file()

Ritorna l’oggetto Gio.File del file selezionato. Se il filechooser è in modalità folder, ritorna appunto la folder selezionata.

get_filename()

Ritorna il nome del file selezionato (str), o None se nessun file è stato selezionato.
Se il filechooser è in modalità folder, ritorna la folder selezionata.

get_filenames()

Ritorna un oggetto GLib.SList contenente i nome di tutti i file selezionati (path assoluti e completi) e le subfolders della folder corrente.

get_files()

Ritorna un oggetto GLib.SList contenente un oggetto Gio.File per ogni file selezionato, o subfolders della folder corrente.

get_filter()

Ritorna il filtro corrente (Gtk.FileFilter), o None se non impostato.

get_local_only()

Ritorna True se solo i file locali possono essere selezinati.

get_preview_file()

Ritorna l’oggetto Gio.File relativo al file in anteprima (preview), o None se nessun file è selezionato.

get_preview_filename()

Ritorna il nome del file (str) che in anteprima (preview), o None se nessun file è selezionato.

get_preview_uri()

Ritorna la URI del file in anteprima, o None se nessun file è selezionato.

get_preview_widget()

Ritorna il widget corrente che si occupa dell’anteprima (preview), o None se non previsto.

get_preview_widget_active()

Ritorna True se il widget responsabile della preview è attivo.

get_select_multiple()

Ritorna True se è attiva la possibilità di selezionare file multiple.

get_show_hidden()

Ritorna True se il filechooser visualizza anche file e dirs nascoste.

get_uri()

Ritorna la URI selezionata. Se Gtk.FileChooser.set_local_only() è settato a True, ritorna una URI
locale per ogni FUSE locations. Se il filechooser è in modalità folder, ritorna la folder selezionata.

get_uris()

Ritorna una lista contenente le URIs di tutti i file selezionati e di tutte le subfolders della folder corrente.

get_use_preview_label()

Ritorna True se il filechooser visualizza una label con il nome del file in anteprima.

list_filters()

Ritorna una lista contenente i filtri selezionabili dall’utente, nel filechooser.

list_shortcut_folder_uris()

Ritorna una lista di URIs (str) relativi alle dirs presenti nelle shortcut folders (scorciatoie).

list_shortcut_folders()

Ritorna una lista di nomi di dirs (folders), o None se non ci sono “scorciatoie”.

remove_choice(id)

Rimuove la “choice” con nome “id”, aggiunta con il metodo Gtk.FileChooser.add_choice().
Parametri:
id: la stringa corrispondente alla choice che vogliamo rimuovere

remove_filter(filter)

Rimuove il filtro dalla lista di filters del filechooser.
Parametri:
filter: l’oggetto Gtk.FileFilter da rimuovere;

remove_shortcut_folder(folder)

Rimuove una folder dalla lista delle shortcuts.
Parametri:
folder: il nome (str) della folder da rimuovere dalle shortcuts.

remove_shortcut_folder_uri(uri)

Rimuove una URI di una folder dalla lista delle shortcuts.
Parametri:
uri: la URI (str) della folder da rimuovere;

select_all()

Seleziona tutti i file dell folder corrente visualizzata nel filechooser.

select_file(file)

Seleziona il file passato come argomento.
Parametri:
file: un oggetto Gio.File rappresentante il file da selezionare;

select_filename(filename)

Seleziona il file passato come argomento.
Parametri:
filename: il nome (str) del file da selezionare;

select_uri(uri)

Seleziona il file passato come argomento.
Parametri:
uri: la URI (str) del file da selezionare;

set_action(action)

Setta il tipo di operazione che il filechooser deve eseguire.
action è un enum di tipo Gtk.FileChooserAction
che può avere i seguenti valori:
OPEN (0): setta il dialog in modalità open, cioà lascia all’utente solo la
possibilità si scegliere un file;
SAVE (1): setta il dialog in modalità save, cioè la possibilità di salvare su un
file esistente o crearne uno nuovo;
SELECT_FOLDER (2): setta il dialog in modalità select folder, cioè la possibilità
di scegliere una folder esistente;
CREATE_FOLDER (3): setta il dialog in modalità create folder, cioè la possibilità
di creare una nuova dir;
Parametri:
action: l’enum Gtk.FileChooserAction da settare;

set_choice(id, option)

Seleziona un’opzione in una “choice”, aggiunta con il metodo Gtk.FileChooser.add_choice().
Se la “choice” è di tipo boolean, le opzioni possibili sono ovviamente “true” e “false”.
Parametri:
id: l’ID (str) della choice da settare;
option: l’ID (str) della opzione della choice da scegliere;

set_create_folders(create_folders)

Settata a True, visualizza un bottone “Create Folder” nel filechooser.
Parametri:
create_folders: un boolean che settato a True, visualizza il bottone “Create Folder”

set_current_folder(filename)

Setta la “current folder” nel filechooser e rende visibile tutto il suo contenuto.
Parametri:
filename: il full-path (str) della nuova folder corrente che vogliamo settare;

set_current_folder_file(file)

Setta la folder corrente da un oggetto Gio.File e ritorna True in caso di successo.
Parametri:
file: l’oggetto Gio.File utilizzato per settare la dir.

set_current_folder_uri(uri)
Setta la folder corrente da un URI e ritorna True in caso di successo.
Parametri:
uri: l’URI con cui settare la folder corrente;

set_current_name(name)

Setta il nome corrente nel file selector, come se fosse stato digitato dallo user.
In una situazione di “Save as”, funge da suggerimento preimpostato.
Parametri:
name: il filename da preimpostare (str);

set_do_overwrite_confirmation(do_overwrite_confirmation)

Setta il dialog di conferma quando si digita il nome di un file esistente in modalità
Gtk.FileChooserAction.SAVE.
Parametri:
do_overwrite_confirmation: il boolean che settato a True attiva la conferma di sovrascrittura;

set_extra_widget(extra_widget)

Setta un extra-widget per fornire allo user delle opzioni supplementari.
Parametri:
extra_widget: un oggetto Gtk.Widget per le opzioni extra;

set_file(file)

Setta il filename corrente nel filechooser partendo da un oggetto Gio.File, selezionandone la
parent folder e selezionando il file stesso nella lista.
Se siamo in modalità Gtk.FileChooserAction.SAVE il nome del file apparirà nella entry “file name”
del filechooser.
Parametri:
file: l’oggetto Gio.File da utilizzare per settare il file e la folder corrente;

set_filename(filename)

Setta il filename corrente nel filechooser partendo da una stringa, selezionandone la parent
folder e selezionando il file stesso nella lista.
Parametri:
filename: il file name da utilizzare per settare il file e la folder corrente;

set_filter(filter)

Setta il filter corrente nel filechooser.
Parametri:
filter: l’oggetto Gtk.FileFilter che si occuperà di filtrare i file da visualizzare nel filechooser.

set_local_only(local_only)

Setta se solo i file locali possono essere selezionati nel filechooser.
Parametri:
local_only: il boolean che settato a True permette di selezionare solo i file locali.

set_preview_widget(preview_widget)

Setta il widget dedicato alla visualizzazione dell’anteprima del file selezionato.
Per implementare un’anteprima, dopo aver settato il widget dedicato a tale compito, è necessario
connettersi al segnale “update-preview” e chiamare i metodi Gtk.FileChooser.get_preview_filename(),
o Gtk.FileChooser.get_preview_uri() ad ogni cambiamento e soprattutto rendere attivo il widget
con il metodo set_preview_widget_active(True).
Parametri:
preview_widget: l’oggetto Gtk.Widget dedicato alla preview;

set_preview_widget_active(active)

Se il widget per la preview, è stato settato con il metodo Gtk.FileChooser.set_preview_widget(),
settando a True, viene visualizzato per il nome file corrente.
Quando active=False, il filechooser tenta di visualizzare una anteprima generata internamente,
o può non visualizzare niente.
Parametri:
active: il boolean che attiva il widget preposto all’anteprima

set_select_multiple(select_multiple)

Setta la possibilità di selezionare multipli files.
Parametri:
select_multiple: il boolean che settato a True, attiva la selazione multiple;

set_show_hidden(show_hidden)

Setta la visualizzazione dei file nascosti.
Parametri:
show_hidden: il boolean che settato a True attiva la visualizzazione dei file nascosti;

set_uri(uri)

Setta il filename corrente nel filechooser partendo dalla URI, selezionandone la parent folder e
selezionando il file stesso nella lista.
Se siamo in modalità Gtk.FileChooserAction.SAVE il nome del file apparirà nella entry “file name”
del filechooser.
Parametri:
uri: la URI (str) da settare come file corrente;

set_use_preview_label(use_label)

Setta se il filechooser debba visualizzare o meno una stock-label con il nome del file in anteprima.
Se vogliamo che le applicazioni disegnino l’intera anteprima da sè, settare a False il boolean “use_label”.
Parametri:
use_label: il boolean che settato a True visualizza una stock-label con il file in anteprima;

unselect_all()

Deseleziona tutti i files.

unselect_file(file)

Deseleziona il file indicato dall’oggetto Gio.File, passato come argomento.
Parametri:
file: l’oggetto Gio.File che fa riferimento al file da deselezionare;

unselect_filename(filename)

Deseleziona il file indicato dalla nome passato come argomento.
Parametri:
filename: il nome del file (str) da deselezionare;

unselect_uri(uri)

Deseleziona il file indicato dalla URI passata come argomento.
Parametri:
uri: la URI del file (str) da deselezionare;

FileFilter

Una componente molto importante del FileChooserDialog è il filefilter che utilizziamo per filtrare
i file contenuti in una folder.
Il Gtk.FileFilter è un oggetto utilizzato per restringere le visualizzazioni all’interno di un
filechooser dialog.
Possiamo decidere di filtrare i file in base al proprio nome, utilizzando il metodo
Gtk.FileFilter.add_pattern()), in base al proprio mime type, utilizzando il metodo
Gtk.FileFilter.add_mime_type(), o con l’utilizzo di una funzione di filter,
con il metodo Gtk.FileFilter.add_custom().

Filtrare per mime types gestisce gli alias e le sottoclassi dei mime types, ad esempio filtrando
per text/plain visualizzerebbe anche mime type di tipo application/rtf,
inquanto application/rtf è una sottoclasse di text/plain.

Metodi

I metodi principali per il filter sono:

add_custom(needed, func, *data)

Un metodo che si appoggia ad una funzione personalizzata che testa il file con determinate regole,
se la funzione ritorna True, il file verrà visualizzato nel filechooser.
Parametri:
needed: un bitfield di tipo Gtk.FileFilterFlags,
ovvero il gruppo di flags indicanti le informazioni di cui ha bisogno la funzione del filtro
personalizzato.
Queste flags indicano quale parte del Gtk.FileFilterInfo
devono essere “riempite”. Le flags sono:
FILENAME (1): il nome del file che deve essere testato;
URI (2): la URI del file che deve essere testato;
DISPLAY_NAME (4): la stringa che verrà usata per visualizzare il file nel filechooser;
MIME_TYPE (8): il mime-type del file;

Il Gtk.FileFilterInfo, ovvero il bitfield (struct) usato per passare informazioni
sul file da testare, al filter, è infatti così strutturato:
“contains”: Flags indicante quali dei seguenti campi devono essere riempiti;
“display_name”: la stringa che verrà usata per visualizzare il file nel filechooser,
vedi la flag DISPLAY_NAME di Gtk.FileFilterFlags;
“filename”: il nome del file che deve essere testato, vedi la flag FILENAME di Gtk.FileFilterFlags;
“mime_type”: il mime-type del file che deve essere testato,
vedi la flag MIME-TYPE di Gtk.FileFilterFlags;
“uri”: la URI del file che deve essere testato, vedi la flag URI di Gtk.FileFilterFlags;

func: la callback che si occuperà del test.
Se ritorna True, il file verrà visualizzato nel filechooser;
data: i dati da passare alla callback;

add_mime_type(mime_type)

Aggiunge un mime-type come regola per il filter.
Parametri:
mime_type: il nome (str) del MIME type da utilizzare come filtro;

add_pattern(pattern)

Aggiunge un pattern come regola per il filter.
Parametri:
pattern: un glob (str) in stile shell, da utilizzare come filtro;

add_pixbuf_formats()

Aggiunge una regola che passi i file immagine nel formato supportato da GdkPixbuf.Pixbuf.

filter(filter_info)

Testa se un file debba essere visualizzato, in accordo con le regole settate nel filter.
L’oggetto Gtk.FileFilterInfo filter_info dovrebbe includere i cambi ritornati
con il metodo Gtk.FileFilter.get_needed().
Parametri:
filter_info: l’oggetto Gtk.FileFilterInfo) che contiene le
informazioni del file;

get_name()

Ritorna il nome del filter.

get_needed()

Ritorna i campi che devono essere compilati per l’oggetto Gtk.FileFilterInfo da passare a
Gtk.FileFilter.filter().

set_name(name)

Setta il nome del filter.
Parametri:
name: il nome da dare al filter;

Di seguito un codice di esempio:

import gi
gi.require_version('Gtk', '3.0')
from gi.repository import Gtk


class GWindow(Gtk.Window):

    def __init__(self):
        super().__init__(title="FileChooser Example")
        self.set_default_size(250, 100)

        button1 = Gtk.Button(label="Choose File")
        button2 = Gtk.Button(label="Choose Folder")
        # Bindings
        button1.connect("clicked", self.on_file_clicked)
        button2.connect("clicked", self.on_folder_clicked)
        # Layout
        box = Gtk.Box(spacing=6)
        box.set_homogeneous(True)
        box.add(button1)
        box.add(button2)
        self.add(box)

    def on_file_clicked(self, widget):
        dialog = Gtk.FileChooserDialog(title="Choose a file", parent=self,
                                       action=Gtk.FileChooserAction.OPEN)
        dialog.add_buttons(Gtk.STOCK_CANCEL, Gtk.ResponseType.CANCEL,
                           Gtk.STOCK_OK, Gtk.ResponseType.OK)
        # add dialog filters
        for name, pattern in [("Text files", "*.txt*"), ("all files", "*.*")]:
            filter = Gtk.FileFilter()
            filter.set_name(name)
            filter.add_pattern(pattern)
            dialog.add_filter(filter)
        response = dialog.run()
        if response == Gtk.ResponseType.OK:
            print("INFO: file selected > %s" % dialog.get_filename())
        elif response == Gtk.ResponseType.CANCEL:
            print("INFO: aborted.")
        dialog.destroy()

    def on_folder_clicked(self, widget):
        dialog = Gtk.FileChooserDialog(
            title="Choose a folder", parent=self,
            action=Gtk.FileChooserAction.SELECT_FOLDER)
        dialog.add_buttons(Gtk.STOCK_CANCEL, Gtk.ResponseType.CANCEL,
                           "Select", Gtk.ResponseType.OK)
        dialog.set_default_size(800, 400)
        response = dialog.run()
        if response == Gtk.ResponseType.OK:
            print("INFO: Folder selected > %s" % dialog.get_filename())
        elif response == Gtk.ResponseType.CANCEL:
            print("INFO: aborted.")
        dialog.destroy()


if __name__ == "__main__":
    win = GWindow()
    win.connect("destroy", Gtk.main_quit)
    win.show_all()
    Gtk.main()

link di riferimento:

torna all’indice degli appunti
Gtk3 FileChooserDialog
Gtk3 FileChooser
Gtk3 FileFilter