Gtk.DirectoryList

class — extends GObject.Object, Gio.ListModel

A list model that wraps Gio.File.enumerate_children_async.

It presents a GListModel and fills it asynchronously with the GFileInfos returned from that function.

Enumeration will start automatically when the DirectoryList.file property is set.

While the GtkDirectoryList is being filled, the DirectoryList.loading property will be set to True. You can listen to that property if you want to show information like a GtkSpinner or a "Loading..." text.

If loading fails at any point, the DirectoryList.error property will be set to give more indication about the failure.

The GFileInfos returned from a GtkDirectoryList have the "standard::file" attribute set to the GFile they refer to. This way you can get at the file that is referred to in the same way you would via Gio.FileEnumerator.get_child. This means you do not need access to the GtkDirectoryList, but can access the GFile directly from the GFileInfo when operating with a GtkListView or similar.

Constructors

new

@classmethod
def new(cls, attributes: str | None = ..., file: Gio.File | None = ...) -> DirectoryList

Creates a new GtkDirectoryList.

The GtkDirectoryList is querying the given file with the given attributes.

Parameters:

• attributes — The attributes to query with
• file — The file to query

Methods

get_attributes

def get_attributes(self) -> str | None

Gets the attributes queried on the children.

get_error

def get_error(self) -> GLib.Error | None

Gets the loading error, if any.

If an error occurs during the loading process, the loading process will finish and this property allows querying the error that happened. This error will persist until a file is loaded again.

An error being set does not mean that no files were loaded, and all successfully queried files will remain in the list.

get_file

def get_file(self) -> Gio.File | None

Gets the file whose children are currently enumerated.

get_io_priority

def get_io_priority(self) -> int

Gets the IO priority set via DirectoryList.set_io_priority.

get_monitored

def get_monitored(self) -> bool

Returns whether the directory list is monitoring the directory for changes.

is_loading

def is_loading(self) -> bool

Returns True if the children enumeration is currently in progress.

Files will be added to self from time to time while loading is going on. The order in which are added is undefined and may change in between runs.

set_attributes

def set_attributes(self, attributes: str | None = ...) -> None

Sets the attributes to be enumerated and starts the enumeration.

If attributes is None, the list of file infos will still be created, it will just not contain any extra attributes.

Parameters:

• attributes — the attributes to enumerate

set_file

def set_file(self, file: Gio.File | None = ...) -> None

Sets the file to be enumerated and starts the enumeration.

If file is None, the result will be an empty list.

Parameters:

• file — the GFile to be enumerated

set_io_priority

def set_io_priority(self, io_priority: int) -> None

Sets the IO priority to use while loading directories.

Setting the priority while self is loading will reprioritize the ongoing load as soon as possible.

The default IO priority is GLib.PRIORITY_DEFAULT, which is higher than the GTK redraw priority. If you are loading a lot of directories in parallel, lowering it to something like GLib.PRIORITY_DEFAULT_IDLE may increase responsiveness.

Parameters:

• io_priority — IO priority to use

set_monitored

def set_monitored(self, monitored: bool) -> None

Sets whether the directory list will monitor the directory for changes.

If monitoring is enabled, the ::items-changed signal will be emitted when the directory contents change.

When monitoring is turned on after the initial creation of the directory list, the directory is reloaded to avoid missing files that appeared between the initial loading and when monitoring was turned on.

Parameters:

• monitored — True to monitor the directory for changes

Properties

attributes

attributes: str  # read/write

The attributes to query.

error

error: GLib.Error  # read-only

Error encountered while loading files.

file

file: Gio.File  # read/write

File to query.

io_priority

io_priority: int  # read/write

Priority used when loading.

item_type

item_type: type | GObject.Type  # read-only

The type of items. See Gio.ListModel.get_item_type.

loading

loading: bool  # read-only

True if files are being loaded.

monitored

monitored: bool  # read/write

True if the directory is monitored for changed.

n_items

n_items: int  # read-only

The number of items. See Gio.ListModel.get_n_items.