Attention: Here be dragons
This is the latest
(unstable) version of this documentation, which may document features
not available in or compatible with released stable versions of Godot.
Checking the stable version of the documentation...
FileDialog
Eredita: ConfirmationDialog < AcceptDialog < Window < Viewport < Node < Object
Ereditato da: EditorFileDialog
Una finestra di dialogo per selezionare file o cartelle nel file system.
Descrizione
FileDialog è una finestra di dialogo preimpostata utilizzata per scegliere file e cartelle nel file system. Supporta maschere di filtro. FileDialog imposta automaticamente il titolo della sua finestra in base a file_mode. Se si desidera usare un titolo personalizzato, disattivalo impostando mode_overrides_title su false.
Nota: FileDialog è inizialmente invisibile. Per renderlo visibile, chiama uno dei metodi popup_* da Window sul nodo, come ad esempio Window.popup_centered_clamped().
Proprietà
|
||
|
||
dialog_hide_on_ok |
|
|
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
size |
|
|
title |
|
|
|
Metodi
void |
add_filter(filter: String, description: String = "", mime_type: String = "") |
void |
add_option(name: String, values: PackedStringArray, default_value_index: int) |
void |
|
void |
|
void |
|
get_favorite_list() static |
|
get_option_default(option: int) const |
|
get_option_name(option: int) const |
|
get_option_values(option: int) const |
|
get_recent_list() static |
|
get_selected_options() const |
|
get_vbox() |
|
void |
|
is_customization_flag_enabled(flag: Customization) const |
|
void |
|
void |
set_customization_flag_enabled(flag: Customization, enabled: bool) |
void |
set_favorite_list(favorites: PackedStringArray) static |
void |
set_get_icon_callback(callback: Callable) static |
void |
set_get_thumbnail_callback(callback: Callable) static |
void |
set_option_default(option: int, default_value_index: int) |
void |
set_option_name(option: int, name: String) |
void |
set_option_values(option: int, values: PackedStringArray) |
void |
set_recent_list(recents: PackedStringArray) static |
Proprietà del tema
|
||
|
||
|
||
|
||
Segnali
Emesso quando l'utente seleziona una cartella.
Emesso quando l'utente seleziona un file cliccando due volte su di esso o premendo il pulsante OK.
filename_filter_changed(filter: String) 🔗
Emesso quando il filtro per i nomi dei file cambia.
files_selected(paths: PackedStringArray) 🔗
Emesso quando l'utente seleziona più file.
Enumerazioni
enum FileMode: 🔗
FileMode FILE_MODE_OPEN_FILE = 0
La finestra di dialogo consente di selezionare solamente un file.
FileMode FILE_MODE_OPEN_FILES = 1
La finestra di dialogo consente di selezionare più file.
FileMode FILE_MODE_OPEN_DIR = 2
La finestra di dialogo consente solo la selezione di una cartella, non consentendo la selezione di alcun file.
FileMode FILE_MODE_OPEN_ANY = 3
La finestra di dialogo nativa dei file consente di selezionare un file o una cartella.
FileMode FILE_MODE_SAVE_FILE = 4
La finestra di dialogo avviserà quando esiste un file.
enum Access: 🔗
Access ACCESS_RESOURCES = 0
La finestra di dialogo consente l'accesso solo ai file nel percorso per i Resource (res://).
Access ACCESS_USERDATA = 1
La finestra di dialogo consente l'accesso solo ai file nel percorso dei dati utente (user://).
Access ACCESS_FILESYSTEM = 2
La finestra di dialogo consente di accedere ai file dell'intero file system.
enum DisplayMode: 🔗
DisplayMode DISPLAY_THUMBNAILS = 0
La finestra di dialogo visualizza i file come una griglia di miniature. Usa thumbnail_size per regolarne le dimensioni.
DisplayMode DISPLAY_LIST = 1
La finestra di dialogo visualizza i file come un elenco di nomi di file.
enum Customization: 🔗
Cambia la visibilità del pulsante per aggiungere ai preferiti, e dell'elenco dei preferiti sul lato sinistro della finestra di dialogo.
Equivale a favorites_enabled.
Customization CUSTOMIZATION_CREATE_FOLDER = 1
Se abilitato, mostra il pulsante per la creazione di nuove cartella (quando si utilizza FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY o FILE_MODE_SAVE_FILE).
Equivale a folder_creation_enabled.
Customization CUSTOMIZATION_FILE_FILTER = 2
Se abilitato, mostra il pulsante per attivare/disattivare il filtro file.
Equivale a file_filter_toggle_enabled.
Customization CUSTOMIZATION_FILE_SORT = 3
Se abilitato, mostra il pulsante per le opzioni di ordinamento dei file.
Equivale a file_sort_options_enabled.
Customization CUSTOMIZATION_FAVORITES = 4
Se abilitato, mostra il pulsante per aggiungere ai preferiti e l'elenco dei preferiti sul lato sinistro della finestra di dialogo.
Equivale a favorites_enabled.
Customization CUSTOMIZATION_RECENT = 5
Se abilitato, mostra l'elenco delle cartelle recenti sul lato sinistro della finestra di dialogo.
Equivale a recent_list_enabled.
Customization CUSTOMIZATION_LAYOUT = 6
Se abilitato, mostra i pulsanti per cambiare layout (elenco/miniature).
Equivale a layout_toggle_enabled.
Customization CUSTOMIZATION_OVERWRITE_WARNING = 7
Se abilitato, il FileDialog avviserà l'utente prima di sovrascrivere i file in modalità salvataggio.
Equivale a overwrite_warning_enabled.
Customization CUSTOMIZATION_DELETE = 8
Se abilitato, il menu contestuale mostrerà l'opzione "Elimina", che consente di spostare file e cartelle nel cestino.
Equivale a deleting_enabled.
Descrizioni delle proprietà
L'ambito di accesso al file system.
Attenzione: Nelle build Web, FileDialog non può accedere al file system dell'host. Negli ambienti Linux e macOS in sandbox, use_native_dialog è utilizzato automaticamente per consentire un accesso limitato al file system dell'host.
La cartella di lavoro attuale della finestra di dialogo dei file.
Nota: Per le finestre di dialogo dei file native, questa proprietà viene trattata solo come un suggerimento e potrebbe non essere rispettata da alcune implementazioni del sistema operativo.
Il file attualmente selezionato nella finestra di dialogo dei file.
Il percorso di file attualmente selezionato nella finestra di dialogo dei file.
bool deleting_enabled = true 🔗
void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const
Se true, il menu contestuale mostrerà l'opzione "Elimina", che consente di spostare file e cartelle nel cestino.
DisplayMode display_mode = 0 🔗
void set_display_mode(value: DisplayMode)
DisplayMode get_display_mode()
Modalità di visualizzazione dell'elenco dei file nella finestra di dialogo.
bool favorites_enabled = true 🔗
void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const
Se true, mostra il pulsante per aggiungere ai preferiti, e dell'elenco dei preferiti sul lato sinistro della finestra di dialogo.
bool file_filter_toggle_enabled = true 🔗
void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const
Se true, mostra il pulsante per attivare/disattivare il filtro file.
La modalità di apertura o salvataggio della finestra di dialogo, che influenza il comportamento di selezione.
bool file_sort_options_enabled = true 🔗
void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const
Se true, mostra il pulsante per le opzioni di ordinamento dei file.
Il filtro per i nomi dei file (non sensibile alle maiuscole/minuscole). Se impostato su una stringa non vuota, saranno mostrati solo i file che contengono la sottostringa. È possibile modificare filename_filter dall'utente con il pulsante filtro in cima alla finestra di dialogo dei file.
Vedi anche filters, che si dovrebbe utilizzare per limitare i tipi di file selezionabili, invece di filename_filter che dovrebbe essere impostato dall'utente.
PackedStringArray filters = PackedStringArray() 🔗
void set_filters(value: PackedStringArray)
PackedStringArray get_filters()
I filtri di tipo file disponibili. Ogni stringa di filtro nell'array dovrebbe essere formattata in questo modo: *.png,*.jpg,*.jpeg;Image Files;image/png,image/jpeg. Il testo descrittivo del filtro è facoltativo e può essere omesso. Sia le estensioni file sia il tipo MIME dovrebbero essere sempre impostati.
Nota: Sia le finestre di dialogo dei file che sono incorporate, sia quelle su Windows supportano solo le estensioni dei file, mentre su Android, Linux e macOS esse supportano anche i tipi MIME.
Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.
bool folder_creation_enabled = true 🔗
void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const
Se true, mostra il pulsante per creare nuove cartelle (quando si utilizza FILE_MODE_OPEN_DIR, FILE_MODE_OPEN_ANY o FILE_MODE_SAVE_FILE), e il menu contestuale includerà l'opzione "Nuova cartella...".
void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const
Se true, mostra il pulsante per cambiare la visibilità dei file nascosti.
bool layout_toggle_enabled = true 🔗
void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const
Se true, mostra i pulsanti per cambiare layout (elenco/miniature).
bool mode_overrides_title = true 🔗
Se true, modificando la proprietà file_mode si imposterà di conseguenza il titolo della finestra (ad esempio, impostando file_mode su FILE_MODE_OPEN_FILE il titolo della finestra cambierà in "Apri un file").
Numero di OptionButton e CheckBox aggiuntivi nella finestra di dialogo.
int option_{index}/default = 0 🔗
Il valore predefinito per l'opzione all'indice index.
Nota: index è un valore compreso nell'intervallo 0 .. option_count - 1.
String option_{index}/name = "" 🔗
Il nome per l'opzione all'indice index.
Nota: index è un valore compreso nell'intervallo 0 .. option_count - 1.
PackedStringArray option_{index}/values = PackedStringArray() 🔗
La lista di valori per l'opzione all'indice index.
Nota: index è un valore compreso nell'intervallo 0 .. option_count - 1.
Note: The returned array is copied and any changes to it will not update the original property value. See PackedStringArray for more details.
bool overwrite_warning_enabled = true 🔗
void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const
Se true, il FileDialog avviserà l'utente prima di sovrascrivere i file in modalità salvataggio.
bool recent_list_enabled = true 🔗
void set_customization_flag_enabled(flag: Customization, enabled: bool)
bool is_customization_flag_enabled(flag: Customization) const
Se true, mostra l'elenco delle cartelle recenti sul lato sinistro della finestra di dialogo.
Se non è vuoto, la sottocartella specificata sarà la "radice" di questo FileDialog, ovvero l'utente non sarà in grado di andare alla sua cartella madre.
Nota: Questa proprietà è ignorata dalle finestre di dialogo native dei file.
Se true, la finestra di dialogo mostrerà i file nascosti.
Nota: Questa proprietà è ignorata dalle finestre di dialogo native dei file su Android e Linux.
bool use_native_dialog = false 🔗
Se true, e se supportato dal DisplayServer attuale, sarà utilizzata una finestra di dialogo nativa del sistema operativo anziché quella personalizzata.
Nota: Su Android, ciò è supportato solo sui dispositivi Android 10+ e se si utilizza ACCESS_FILESYSTEM. Per le modalità di accesso ACCESS_RESOURCES e ACCESS_USERDATA, il sistema ritornerà al FileDialog personalizzato.
Nota: Su Linux e macOS, le app in sandbox utilizzano sempre le finestre di dialogo native per accedere al file system dell'host.
Nota: Su macOS, le app in sandbox salveranno i segnalibri con ambito di sicurezza per mantenere l'accesso alle cartelle aperte in più sessioni. Usa OS.get_granted_permissions() per ottenere una lista dei segnalibri salvati.
Nota: Le finestre di dialogo native sono isolate dal processo base, le proprietà della finestra di dialogo del file non si possono cambiare una volta che la finestra di dialogo viene mostrata.
Note: Questa proprietà è ignorata in EditorFileDialog.
Descrizioni dei metodi
void add_filter(filter: String, description: String = "", mime_type: String = "") 🔗
Aggiunge un'opzione di filtro (filter) e un tipo MIME (mime_type), entrambi delimitati da virgole, per il FileDialog con una descrizione (description) facoltativa, che limita i file che si possono selezionare.
filter dovrebbe essere del formato "filename.extension", dove filename ed extension possono essere * per corrispondere a qualsiasi stringa. I filtri che iniziano con . (ad esempio i nomi vuoti dei file) non sono consentiti.
Ad esempio, un filter di "*.png, *.jpg", un mime_type di image/png, image/jpeg e una description di "Immagini " generano il testo del filtro "Immagini (*.png, *.jpg)".
Nota: Le finestre di dialogo incorporate dei file e quelle di Windows supportano solo le estensioni dei file, mentre quelle di Android, Linux e macOS supportano anche i tipi MIME.
void add_option(name: String, values: PackedStringArray, default_value_index: int) 🔗
Aggiunge un OptionButton aggiuntivo alla finestra di dialogo dei file. Se values è vuoto, viene aggiunto un CheckBox.
default_value_index dovrebbe essere un indice del valore in values. Se values è vuoto, dovrebbe essere 1 (selezionato) o 0 (non selezionato).
void clear_filename_filter() 🔗
Svuota il filtro per i nomi dei file.
void clear_filters() 🔗
Cancella tutti i filtri aggiunti nella finestra di dialogo.
void deselect_all() 🔗
Cancella tutti gli elementi attualmente selezionati nella finestra di dialogo.
PackedStringArray get_favorite_list() static 🔗
Restituisce l'elenco delle cartelle preferite, condiviso da tutti i nodi FileDialog. Utile per memorizzare l'elenco delle cartelle preferite tra più sessioni di un progetto. Questo metodo si può chiamare solo dal thread principale.
Restituisce il LineEdit per il file selezionato.
Attenzione: Questo è un nodo interno obbligatorio, rimuoverlo e liberarlo potrebbe causare un crash. Se desideri nascondere esso o uno dei suoi figli, usa la loro proprietà CanvasItem.visible.
int get_option_default(option: int) const 🔗
Restituisce l'indice di valore predefinito dell'OptionButton o della CheckBox con l'indice option.
String get_option_name(option: int) const 🔗
Restituisce il nome dell'OptionButton o della CheckBox con l'indice option.
PackedStringArray get_option_values(option: int) const 🔗
Restituisce un array di valori dell'OptionButton con l'indice option.
PackedStringArray get_recent_list() static 🔗
Restituisce l'elenco delle cartelle recenti, condiviso da tutti i nodi FileDialog. Utile per memorizzare l'elenco delle cartelle recenti tra più sessioni di un progetto. Questo metodo si può chiamare solo dal thread principale.
Dictionary get_selected_options() const 🔗
Restituisce un Dictionary con i valori selezionati degli OptionButton e/o CheckBox aggiuntivi. Le chiavi del Dictionary sono i nomi e i valori sono gli indici dei valori selezionati.
VBoxContainer get_vbox() 🔗
Restituisce il contenitore verticale della finestra di dialogo, a cui è possibile aggiungere controlli personalizzati.
Attenzione: Questo è un nodo interno necessario, rimuoverlo e liberarlo potrebbe causare un crash. Se si desidera nascondere esso o uno dei suoi figli, utilizza le loro proprietà CanvasItem.visible.
Nota: Le modifiche apportate a questo nodo vengono ignorate dalle finestre native di dialogo dei file. Utilizza invece add_option() per aggiungere elementi personalizzati alla finestra di dialogo.
void invalidate() 🔗
Invalida e aggiorna l'elenco dei contenuti in questa finestra di dialogo.
Nota: Questo metodo non fa nulla sulle finestre di dialogo native dei file.
bool is_customization_flag_enabled(flag: Customization) const 🔗
Restituisce true se il flag specificato è abilitato.
void popup_file_dialog() 🔗
Mostra il FileDialog nelle dimensioni e posizione predefinite per le finestre di dialogo dei file, e seleziona il nome del file se è presente un file attuale.
void set_customization_flag_enabled(flag: Customization, enabled: bool) 🔗
Imposta il flag di personalizzazione specificato, consentendo di personalizzare le funzionalità disponibili in questo FileDialog.
void set_favorite_list(favorites: PackedStringArray) static 🔗
Imposta l'elenco delle cartelle preferite, condiviso da tutti i nodi FileDialog. Utile per ripristinare l'elenco dei preferiti salvato con get_favorite_list(). Questo metodo si può chiamare solo dal thread principale.
Nota: FileDialog aggiornerà il suo ItemList interno dei preferiti quando cambia la sua visibilità. Assicurati di chiamare questo metodo prima se vuoi che le modifiche abbiano effetto.
void set_get_icon_callback(callback: Callable) static 🔗
Imposta il callback utilizzato dai nodi FileDialog per ottenere un'icona file, quando è utilizzata la modalità DISPLAY_LIST. Il callback deve accettare un singolo argomento String (percorso del file) e restituire una Texture2D. Se viene restituita una texture non valida, verrà utilizzata l'icona file.
void set_get_thumbnail_callback(callback: Callable) static 🔗
Imposta il callback utilizzato dai nodi FileDialog per ottenere un'icona file, quando è utilizzata la modalità DISPLAY_THUMBNAILS. Il callback deve accettare un singolo argomento String (percorso del file) e restituire una Texture2D. Se viene restituita una texture non valida, verrà utilizzata l'icona file_thumbnail.
Le miniature sono generalmente più complesse e potrebbe volerci tempo per caricarle. Per evitare di bloccare l'applicazione, è possibile utilizzare ImageTexture per creare la miniatura in modo asincrono.
func _ready():
FileDialog.set_get_thumbnail_callback(thumbnail_method)
func thumbnail_method(path):
var image_texture = ImageTexture.new()
make_thumbnail_async(path, image_texture)
return image_texture
func make_thumbnail_async(path, image_texture):
var thumbnail_texture = await generate_thumbnail(path) # Un metodo che genera una miniatura.
image_texture.set_image(thumbnail_texture.get_image())
void set_option_default(option: int, default_value_index: int) 🔗
Imposta l'indice di valore predefinito dell'OptionButton o della CheckBox con l'indice option.
void set_option_name(option: int, name: String) 🔗
Imposta il nome dell'OptionButton o della CheckBox con l'indice option.
void set_option_values(option: int, values: PackedStringArray) 🔗
Imposta i valori di opzione dell'OptionButton con l'indice option.
void set_recent_list(recents: PackedStringArray) static 🔗
Imposta l'elenco delle cartelle recenti, condiviso da tutti i nodi FileDialog. Utile per ripristinare l'elenco delle cartelle recenti salvato con set_recent_list(). Questo metodo si può chiamare solo dal thread principale.
Nota: FileDialog aggiornerà il suo ItemList interno delle cartelle recenti quando cambia la sua visibilità. Assicurati di chiamare questo metodo prima se vuoi che le modifiche abbiano effetto.
Descrizioni delle proprietà del tema
Color file_disabled_color = Color(1, 1, 1, 0.25) 🔗
La tinta di colore per i file disabilitati (quando FileDialog è usato in modalità cartella aperta).
Color file_icon_color = Color(1, 1, 1, 1) 🔗
Il colore di modulazione applicato all'icona del file.
Color folder_icon_color = Color(1, 1, 1, 1) 🔗
Il colore di modulazione applicato all'icona della cartella.
La dimensione delle icone in miniatura quando DISPLAY_THUMBNAILS è abilitato.
Icona personalizzata per la freccia indietro.
Icona personalizzata per il pulsante Crea cartella.
Icona personalizzata per il pulsante Preferiti delle cartelle.
Icona personalizzata per il pulsante per spostare in basso una voce aggiunta ai preferiti.
Icona personalizzata per il pulsante per spostare in alto una voce aggiunta ai preferiti.
Icona personalizzata per i file.
Icona per i file in modalità miniatura.
Icona personalizzata per le cartelle.
Icona per le cartelle in modalità miniatura.
Icona personalizzata per la freccia avanti.
Icona per il pulsante che abilita la modalità elenco.
Icona per l'opzione "Copia percorso" nel menu contestuale.
Icona per l'opzione "Elimina" nel menu contestuale.
Icona per l'opzione "Nuova cartella..." del menu contestuale. Di solito dovrebbe essere uguale a create_folder; lasciala vuota se non vuoi che il menu contestuale mostri icone.
Icona per l'opzione "Mostra contenuto del pacchetto" del menu contestuale. L'opzione apparirà solo per i pacchetti macOS.
Icona per l'opzione "Aggiorna" del menu contestuale. Di solito dovrebbe essere uguale a reload; lasciala vuota se non vuoi che il menu contestuale mostri icone.
Icona per l'opzione "Mostra nel gestore dei file " del menu contestuale.
Icona personalizzata per la freccia della cartella padre.
Icona personalizzata per il pulsante di ricarica.
Icona personalizzata per il menu delle opzioni di ordinamento.
Icona per il pulsante che abilita la modalità miniatura.
Texture2D toggle_filename_filter 🔗
Icona personalizzata per l'Interruttore del filtro per i nomi di file.
Icona personalizzata per l'Interruttore dei file nascosti.