gtkmm  4.8.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>

Inherits Glib::Object, and Gio::ListModel.

Public Member Functions

 DirectoryList (DirectoryList && src) noexcept
 
DirectoryListoperator= (DirectoryList && src) noexcept
 
 ~DirectoryList () noexcept override
 
GtkDirectoryList * gobj ()
 Provides access to the underlying C GObject. More...
 
const GtkDirectoryList * gobj () const
 Provides access to the underlying C GObject. More...
 
GtkDirectoryList * gobj_copy ()
 Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
 
void set_file (const Glib::RefPtr< Gio::File > & file)
 Sets the file to be enumerated and starts the enumeration. More...
 
Glib::RefPtr< Gio::File > get_file ()
 Gets the file whose children are currently enumerated. More...
 
Glib::RefPtr< const Gio::File > get_file () const
 Gets the file whose children are currently enumerated. More...
 
void set_attributes (const std::string & attributes)
 Sets the attributes to be enumerated and starts the enumeration. More...
 
std::string get_attributes () const
 Gets the attributes queried on the children. More...
 
void set_io_priority (int io_priority)
 Sets the IO priority to use while loading directories. More...
 
int get_io_priority () const
 Gets the IO priority set via set_io_priority(). More...
 
bool is_loading () const
 Returns true if the children enumeration is currently in progress. More...
 
Glib::Error get_error () const
 Gets the loading error, if any. More...
 
void set_monitored (bool monitored=true)
 Sets whether the directory list will monitor the directory for changes. More...
 
bool get_monitored () const
 Returns whether the directory list is monitoring the directory for changes. More...
 
Glib::PropertyProxy< std::stringproperty_attributes ()
 The attributes to query. More...
 
Glib::PropertyProxy_ReadOnly< std::stringproperty_attributes () const
 The attributes to query. More...
 
Glib::PropertyProxy_ReadOnly< Glib::Error > property_error () const
 Error encountered while loading files. More...
 
Glib::PropertyProxy< Glib::RefPtr< Gio::File > > property_file ()
 File to query. More...
 
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Gio::File > > property_file () const
 File to query. More...
 
Glib::PropertyProxy< int > property_io_priority ()
 Priority used when loading. More...
 
Glib::PropertyProxy_ReadOnly< int > property_io_priority () const
 Priority used when loading. More...
 
Glib::PropertyProxy_ReadOnly< GType > property_item_type () const
 The type of items. More...
 
Glib::PropertyProxy_ReadOnly< bool > property_loading () const
 true if files are being loaded. More...
 
Glib::PropertyProxy< bool > property_monitored ()
 true if the directory is monitored for changed. More...
 
Glib::PropertyProxy_ReadOnly< bool > property_monitored () const
 true if the directory is monitored for changed. More...
 
Glib::PropertyProxy_ReadOnly< unsigned int > property_n_items () const
 The number of items. More...
 

Static Public Member Functions

static GType get_type ()
 Get the GType for this class, for use with the underlying GObject type system. More...
 
static Glib::RefPtr< DirectoryListcreate (const std::string & attributes, const Glib::RefPtr< Gio::File > & file={})
 

Protected Member Functions

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

Related Functions

(Note that these are not member functions.)

Glib::RefPtr< Gtk::DirectoryListwrap (GtkDirectoryList * object, bool take_copy=false)
 A Glib::wrap() method for this object. More...
 

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, no attributes will be queried, but a list of Gio::FileInfos will still be created.

Parameters
attributesThe 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
fileThe 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_priorityIO 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
monitoredtrue 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
objectThe C instance.
take_copyFalse 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.