:right-sidebar: True DirectoryList =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: DirectoryList(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gio.ListModel` ``GtkDirectoryList`` is a list model that wraps :func:`~gi.repository.Gio.File.enumerate_children_async`. It presents a ``GListModel`` and fills it asynchronously with the ``GFileInfo``'s returned from that function. Enumeration will start automatically when the :obj:`~gi.repository.Gtk.DirectoryList.props.file` property is set. While the ``GtkDirectoryList`` is being filled, the :obj:`~gi.repository.Gtk.DirectoryList.props.loading` property will be set to :const:`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 :obj:`~gi.repository.Gtk.DirectoryList.props.error` property will be set to give more indication about the failure. The ``GFileInfo``'s 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 :func:`~gi.repository.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 ------------ .. rst-class:: interim-class .. class:: DirectoryList :no-index: .. classmethod:: new(attributes: str | None = None, file: ~gi.repository.Gio.File | None = None) -> ~gi.repository.Gtk.DirectoryList Creates a new ``GtkDirectoryList``. The ``GtkDirectoryList`` is querying the given ``file`` with the given ``attributes``. :param attributes: The attributes to query with :param file: The file to query Methods ------- .. rst-class:: interim-class .. class:: DirectoryList :no-index: .. method:: get_attributes() -> str | None Gets the attributes queried on the children. .. method:: get_error() -> ~gi.repository.GLib.GError | 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. .. method:: get_file() -> ~gi.repository.Gio.File | None Gets the file whose children are currently enumerated. .. method:: get_io_priority() -> int Gets the IO priority set via :func:`~gi.repository.Gtk.DirectoryList.set_io_priority`. .. method:: get_monitored() -> bool Returns whether the directory list is monitoring the directory for changes. .. method:: is_loading() -> bool Returns :const:`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. .. method:: set_attributes(attributes: str | None = None) -> None Sets the ``attributes`` to be enumerated and starts the enumeration. If ``attributes`` is :const:`None`, the list of file infos will still be created, it will just not contain any extra attributes. :param attributes: the attributes to enumerate .. method:: set_file(file: ~gi.repository.Gio.File | None = None) -> None Sets the ``file`` to be enumerated and starts the enumeration. If ``file`` is :const:`None`, the result will be an empty list. :param file: the ``GFile`` to be enumerated .. method:: set_io_priority(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 ``%G_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 ``%G_PRIORITY_DEFAULT_IDLE`` may increase responsiveness. :param io_priority: IO priority to use .. method:: set_monitored(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. :param monitored: :const:`True` to monitor the directory for changes Properties ---------- .. rst-class:: interim-class .. class:: DirectoryList :no-index: .. attribute:: props.attributes :type: str The attributes to query. .. attribute:: props.error :type: ~gi.repository.GLib.GError Error encountered while loading files. .. attribute:: props.file :type: ~gi.repository.Gio.File File to query. .. attribute:: props.io_priority :type: int Priority used when loading. .. attribute:: props.item_type :type: type The type of items. See :obj:`~gi.repository.Gio.ListModel.get_item_type`. .. versionadded:: 4.8 .. attribute:: props.loading :type: bool :const:`True` if files are being loaded. .. attribute:: props.monitored :type: bool :const:`True` if the directory is monitored for changed. .. attribute:: props.n_items :type: int The number of items. See :obj:`~gi.repository.Gio.ListModel.get_n_items`. .. versionadded:: 4.8