gtkmm: Gtk::DirectoryList Class Reference

gtkmm 4.10.0

Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gtk::DirectoryList Class Reference

A list model for directory listings. More...

`#include <gtkmm/directorylist.h>`

Inheritance diagram for Gtk::DirectoryList:
[legend]

## Public Member Functions
| DirectoryList (DirectoryList && src) noexcept
DirectoryList & | operator= (DirectoryList && src) noexcept
| ~DirectoryList () noexcept override
GtkDirectoryList * | gobj ()
| Provides access to the underlying C GObject.
const GtkDirectoryList * | gobj () const
| Provides access to the underlying C GObject.
GtkDirectoryList * | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
void | set_file (const Glib::RefPtr< Gio::File > & file)
| Sets the file to be enumerated and starts the enumeration.
Glib::RefPtr< Gio::File > | get_file ()
| Gets the file whose children are currently enumerated.
Glib::RefPtr< const Gio::File > | get_file () const
| Gets the file whose children are currently enumerated.
void | set_attributes (const std::string & attributes)
| Sets the attributes to be enumerated and starts the enumeration.
std::string | get_attributes () const
| Gets the attributes queried on the children.
void | set_io_priority (int io_priority)
| Sets the IO priority to use while loading directories.
int | get_io_priority () const
| Gets the IO priority set via set_io_priority().
bool | is_loading () const
| Returns `true` if the children enumeration is currently in progress.
Glib::Error | get_error () const
| Gets the loading error, if any.
void | set_monitored (bool monitored=true)
| Sets whether the directory list will monitor the directory for changes.
bool | get_monitored () const
| Returns whether the directory list is monitoring the directory for changes.
Glib::PropertyProxy< std::string > | property_attributes ()
| The attributes to query.
Glib::PropertyProxy_ReadOnly< std::string > | property_attributes () const
| The attributes to query.
Glib::PropertyProxy_ReadOnly< Glib::Error > | property_error () const
| Error encountered while loading files.
Glib::PropertyProxy< Glib::RefPtr< Gio::File > > | property_file ()
| File to query.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Gio::File > > | property_file () const
| File to query.
Glib::PropertyProxy< int > | property_io_priority ()
| Priority used when loading.
Glib::PropertyProxy_ReadOnly< int > | property_io_priority () const
| Priority used when loading.
Glib::PropertyProxy_ReadOnly< GType > | property_item_type () const
| The type of items.
Glib::PropertyProxy_ReadOnly< bool > | property_loading () const
| `true` if files are being loaded.
Glib::PropertyProxy< bool > | property_monitored ()
| `true` if the directory is monitored for changed.
Glib::PropertyProxy_ReadOnly< bool > | property_monitored () const
| `true` if the directory is monitored for changed.
Glib::PropertyProxy_ReadOnly< unsigned int > | property_n_items () const
| The number of items.
Public Member Functions inherited from Glib::Object
| Object (const Object &)=delete
Object & | operator= (const Object &)=delete
| Object (Object &&src) noexcept
Object & | operator= (Object &&src) noexcept
void * | get_data (const QueryQuark &key)
void | set_data (const Quark &key, void *data)
void | set_data (const Quark &key, void *data, DestroyNotify notify)
void | remove_data (const QueryQuark &quark)
void * | steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false)
Public Member Functions inherited from Glib::ObjectBase
| ObjectBase (const ObjectBase &)=delete
ObjectBase & | operator= (const ObjectBase &)=delete
void | set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void | get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void | set_property (const Glib::ustring &property_name, const PropertyType &value)
void | get_property (const Glib::ustring &property_name, PropertyType &value) const
PropertyType | get_property (const Glib::ustring &property_name) const
sigc::connection | connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)
sigc::connection | connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)
void | freeze_notify ()
void | thaw_notify ()
virtual void | reference () const
virtual void | unreference () const
GObject * | gobj ()
const GObject * | gobj () const
GObject * | gobj_copy () const
Public Member Functions inherited from Gio::ListModel
| ListModel (ListModel &&src) noexcept
ListModel & | operator= (ListModel &&src) noexcept
| ~ListModel () noexcept override
GListModel * | gobj ()
const GListModel * | gobj () const
GType | get_item_type () const
guint | get_n_items () const
Glib::RefPtr< Glib::ObjectBase > | get_object (guint position)
Glib::RefPtr< const Glib::ObjectBase > | get_object (guint position) const
Glib::SignalProxy< void(guint, guint, guint)> | signal_items_changed ()
Glib::RefPtr< Gio::ListModel > | wrap (GListModel *object, bool take_copy=false)
Public Member Functions inherited from Glib::Interface
| Interface ()
| Interface (Interface &&src) noexcept
Interface & | operator= (Interface &&src) noexcept
| Interface (const Glib::Interface_Class &interface_class)
| Interface (GObject *castitem)
| ~Interface () noexcept override
| Interface (const Interface &)=delete
Interface & | operator= (const Interface &)=delete
GObject * | gobj ()
const GObject * | gobj () const

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system.
static Glib::RefPtr< DirectoryList > | create (const std::string & attributes, const Glib::RefPtr< Gio::File > & file={})
Static Public Member Functions inherited from Gio::ListModel
static void | add_interface (GType gtype_implementer)
static GType | get_type ()

## Protected Member Functions
| DirectoryList (const std::string & attributes, const Glib::RefPtr< Gio::File > & file={})
Protected Member Functions inherited from Glib::Object
| Object ()
| Object (const Glib::ConstructParams &construct_params)
| Object (GObject *castitem)
| ~Object () noexcept override
Protected Member Functions inherited from Glib::ObjectBase
| ObjectBase ()
| ObjectBase (const char *custom_type_name)
| ObjectBase (const std::type_info &custom_type_info)
| ObjectBase (ObjectBase &&src) noexcept
ObjectBase & | operator= (ObjectBase &&src) noexcept
virtual | ~ObjectBase () noexcept=0
void | initialize (GObject *castitem)
void | initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)
Protected Member Functions inherited from Gio::ListModel
| ListModel ()
void | items_changed (guint position, guint removed, guint added)
virtual GType | get_item_type_vfunc ()
virtual guint | get_n_items_vfunc ()
virtual gpointer | get_item_vfunc (guint position)

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gtk::DirectoryList > | wrap (GtkDirectoryList * object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Additional Inherited Members
Public Types inherited from Glib::Object
typedef void(*)(gpointer data | DestroyNotify)

## Detailed Description

A list model for directory listings.

Gtk::DirectoryList is a list model that wraps Gio::File::enumerate_children_async(). It presents a Gio::ListModel and fills it asynchronously with the Gio::FileInfos returned from that function.

Enumeration will start automatically when the property_file() property is set.

While the Gtk::DirectoryList is being filled, the property_loading() property will be set to `true`. You can listen to that property if you want to show information like a Gtk::Spinner or a "Loading..." text.

If loading fails at any point, the property_error() property will be set to give more indication about the failure.

The Gio::FileInfos returned from a Gtk::DirectoryList have the "standard::file" attribute set to the Gio::File they refer to. This way you can get at the file that is referred to in the same way you would via Gio::File::enumerator_get_child(). This means you do not need access to the Gtk::DirectoryList but can access the Gio::File directly from the Gio::FileInfo when operating with a Gtk::ListView or similar.

See also
  Gio::ListModel, Gio::File::enumerate_children()

Since gtkmm 3.98:

## Constructor & Destructor Documentation

## ◆ DirectoryList() [1/2]

Gtk::DirectoryList::DirectoryList | ( | DirectoryList && | src | ) |
| noexcept

## ◆ ~DirectoryList()

Gtk::DirectoryList::~DirectoryList | ( |  | ) |
| overridenoexcept

## ◆ DirectoryList() [2/2]

Gtk::DirectoryList::DirectoryList | ( | const std::string & | attributes,
|  | const Glib::RefPtr< Gio::File > & | file = `{}`
| ) |  |
| explicitprotected

## Member Function Documentation

## ◆ create()

static Glib::RefPtr< DirectoryList > Gtk::DirectoryList::create | ( | const std::string & | attributes,
|  | const Glib::RefPtr< Gio::File > & | file = `{}`
| ) |  |
| static

## ◆ get_attributes()

std::string Gtk::DirectoryList::get_attributes | ( |  | ) | const

Gets the attributes queried on the children.

Returns
  The queried attributes.

## ◆ get_error()

Glib::Error Gtk::DirectoryList::get_error | ( |  | ) | const

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.

Returns
  The loading error or `nullptr` if loading finished successfully.

## ◆ get_file() [1/2]

Glib::RefPtr< Gio::File > Gtk::DirectoryList::get_file | ( |  | ) |

Gets the file whose children are currently enumerated.

Returns
  The file whose children are enumerated.

## ◆ get_file() [2/2]

Glib::RefPtr< const Gio::File > Gtk::DirectoryList::get_file | ( |  | ) | const

Gets the file whose children are currently enumerated.

Returns
  The file whose children are enumerated.

## ◆ get_io_priority()

int Gtk::DirectoryList::get_io_priority | ( |  | ) | const

Gets the IO priority set via set_io_priority().

Returns
  The IO priority.

## ◆ get_monitored()

bool Gtk::DirectoryList::get_monitored | ( |  | ) | const

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

Returns
  `true` if the directory is monitored.

## ◆ get_type()

static GType Gtk::DirectoryList::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ gobj() [1/2]

GtkDirectoryList * Gtk::DirectoryList::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const GtkDirectoryList * Gtk::DirectoryList::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ gobj_copy()

GtkDirectoryList * Gtk::DirectoryList::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## ◆ is_loading()

bool Gtk::DirectoryList::is_loading | ( |  | ) | const

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.

Returns
  `true` if self is loading.

## ◆ operator=()

DirectoryList & Gtk::DirectoryList::operator= | ( | DirectoryList && | src | ) |
| noexcept

## ◆ property_attributes() [1/2]

Glib::PropertyProxy< std::string > Gtk::DirectoryList::property_attributes | ( |  | ) |

The attributes to query.

Default value: ""

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_attributes() [2/2]

Glib::PropertyProxy_ReadOnly< std::string > Gtk::DirectoryList::property_attributes | ( |  | ) | const

The attributes to query.

Default value: ""

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_error()

Glib::PropertyProxy_ReadOnly< Glib::Error > Gtk::DirectoryList::property_error | ( |  | ) | const

Error encountered while loading files.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_file() [1/2]

Glib::PropertyProxy< Glib::RefPtr< Gio::File > > Gtk::DirectoryList::property_file | ( |  | ) |

File to query.

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_file() [2/2]

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Gio::File > > Gtk::DirectoryList::property_file | ( |  | ) | const

File to query.

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_io_priority() [1/2]

Glib::PropertyProxy< int > Gtk::DirectoryList::property_io_priority | ( |  | ) |

Priority used when loading.

Default value: 0

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_io_priority() [2/2]

Glib::PropertyProxy_ReadOnly< int > Gtk::DirectoryList::property_io_priority | ( |  | ) | const

Priority used when loading.

Default value: 0

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_item_type()

Glib::PropertyProxy_ReadOnly< GType > Gtk::DirectoryList::property_item_type | ( |  | ) | const

The type of items.

See Gio::ListModel::get_item_type().

Since gtkmm 4.8:

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_loading()

Glib::PropertyProxy_ReadOnly< bool > Gtk::DirectoryList::property_loading | ( |  | ) | const

`true` if files are being loaded.

Default value: `false`

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_monitored() [1/2]

Glib::PropertyProxy< bool > Gtk::DirectoryList::property_monitored | ( |  | ) |

`true` if the directory is monitored for changed.

Default value: `true`

Returns
  A PropertyProxy that allows you to get or set the value of the property, or receive notification when the value of the property changes.

## ◆ property_monitored() [2/2]

Glib::PropertyProxy_ReadOnly< bool > Gtk::DirectoryList::property_monitored | ( |  | ) | const

`true` if the directory is monitored for changed.

Default value: `true`

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_n_items()

Glib::PropertyProxy_ReadOnly< unsigned int > Gtk::DirectoryList::property_n_items | ( |  | ) | const

The number of items.

See Gio::ListModel::get_n_items().

Since gtkmm 4.8:

Default value: 0

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ set_attributes()

void Gtk::DirectoryList::set_attributes | ( | const std::string & | attributes | ) |

Sets the attributes to be enumerated and starts the enumeration.

If attributes is `nullptr`, 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()

void Gtk::DirectoryList::set_file | ( | const Glib::RefPtr< Gio::File > & | file | ) |

Sets the file to be enumerated and starts the enumeration.

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

Parameters

  file | The `Gio::File` to be enumerated.

## ◆ set_io_priority()

void Gtk::DirectoryList::set_io_priority | ( | int | io_priority | ) |

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()

void Gtk::DirectoryList::set_monitored | ( | bool | monitored = `true` | ) |

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

If monitoring is enabled, the signal_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.

## Friends And Related Function Documentation

## ◆ wrap()

Glib::RefPtr< Gtk::DirectoryList > wrap | ( | GtkDirectoryList * | object,
|  | bool | take_copy = `false`
| ) |  |
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.