GnuiEmblemPicker: GNUIsance Reference Manual

GnuiEmblemPicker

GnuiEmblemPicker — An emblem picker

Stability Level

Unstable, unless otherwise indicated

Functions

gboolean	(*GnuiEmblemPickerForeachFunc) ()
gboolean	(*GnuiEmblemPickerForeachSavedFileFunc) ()
GtkWidget *	gnui_emblem_picker_new ()
gboolean	gnui_emblem_picker_save ()
void	gnui_emblem_picker_refresh_states ()
gboolean	gnui_emblem_picker_toggle_emblem ()
gboolean	gnui_emblem_picker_set_emblem_state ()
const GList *	gnui_emblem_picker_peek_mapped_files ()
GList *	gnui_emblem_picker_get_mapped_files ()
void	gnui_emblem_picker_set_mapped_files ()
const gchar * const *	gnui_emblem_picker_peek_forbidden_emblems ()
gchar **	gnui_emblem_picker_get_forbidden_emblems ()
void	gnui_emblem_picker_set_forbidden_emblems ()
gboolean	gnui_emblem_picker_get_ensure_standard ()
void	gnui_emblem_picker_set_ensure_standard ()
gboolean	gnui_emblem_picker_get_modified ()
void	gnui_emblem_picker_set_modified ()
gboolean	gnui_emblem_picker_get_reveal_changes ()
void	gnui_emblem_picker_set_reveal_changes ()
void	gnui_emblem_picker_foreach ()
void	gnui_emblem_picker_undo_all_selections ()
void	gnui_emblem_picker_set_all_selections ()
void	(*GnuiEmblemPickerSignalHandlerEmblemSelected) ()
void	(*GnuiEmblemPickerSignalHandlerModifiedChanged) ()

Properties

gboolean	ensure-standard	Read / Write / Construct
GStrv	forbidden-emblems	Read / Write / Construct
gpointer	mapped-files	Read / Write / Construct
gboolean	modified	Read / Write / Construct
gboolean	reveal-changes	Read / Write / Construct

Signals

void	emblem-selected	Run First
void	modified-changed	Run First

Types and Values

#define	GNUI_TYPE_EMBLEM_PICKER
enum	GnuiEmblemState
enum	GnuiEmblemPickerSaveFlags
enum	GnuiEmblemPickerSaveResult
	GnuiEmblemPicker

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GnuiEmblemPicker

Implemented Interfaces

GnuiEmblemPicker implements GtkAccessible, GtkBuildable and GtkConstraintTarget.

Includes

#include <gnuisance/gnui-emblem-picker.h>

Description

The GnuiEmblemPicker widget allows interactively to manipulate the emblem metadata of one or more files, providing support for inconsistent states.

Functions

GnuiEmblemPickerForeachFunc ()

gboolean
(*GnuiEmblemPickerForeachFunc) (GnuiEmblemPicker *self,
                                const gchar *emblem_name,
                                GnuiEmblemState saved_state,
                                GnuiEmblemState current_state,
                                const GList *inconsistent_group,
                                gpointer user_data);

A callback function type for gnui_emblem_picker_foreach()

Parameters

self	The emblem picker.	[auto][not nullable]
emblem_name	The emblem's name.	[auto][not nullable]
saved_state	The last saved state of the emblem.	[auto]
current_state	The current state of the emblem.	[auto]
inconsistent_group	The inconsistent group of `GFile` handles that can have the emblem assigned independently of the other files.	[auto][transfer none][nullable]
user_data	The custom data provided by the user.	[auto][nullable][closure]

Returns

true if the for-each loop must continue, false otherwise

GnuiEmblemPickerForeachSavedFileFunc ()

gboolean
(*GnuiEmblemPickerForeachSavedFileFunc)
                               (GFile *location,
                                const gchar * const *added_emblems,
                                const gchar * const *removed_emblems,
                                GnuiEmblemPickerSaveResult result,
                                const GError *error,
                                gpointer user_data);

A callback function type for each saved file

Parameters

location	The file for which the function is being called.	[auto][not nullable]
added_emblems	The emblems added to the file, or `NULL`.	[auto][transfer none][nullable]
removed_emblems	The emblems removed from the file, or `NULL`.	[auto][transfer none][nullable]
result	The result of the save operation.	[auto]
error	The error.	[auto][transfer none][nullable]
user_data	The custom data provided by the user.	[auto][nullable][closure]

Returns

true if the saving operations must carry on, false otherwise

gnui_emblem_picker_new ()

GtkWidget *
gnui_emblem_picker_new (GList * const file_selection,
                        const gboolean enforce_xdg,
                        const gchar * const * const forbidden_emblems);

Create a new emblem picker widget

For the list of XDG standard emblems, please refer to Icon Naming Specification, Table 6. Standard Emblem Icons.

Parameters

file_selection	A `GList` containing `GFile` handles to map for their emblems.	[transfer none][nullable]
enforce_xdg	If `true`, always show XDG standard emblems in the emblem picker, even if these are not supported by the current theme
forbidden_emblems	The emblems to exclude.	[transfer none][nullable]

Returns

The newly created emblem picker widget

gnui_emblem_picker_save ()

gboolean
gnui_emblem_picker_save (GnuiEmblemPicker * const self,
                         const GnuiEmblemPickerForeachSavedFileFunc for_each_file,
                         const GnuiEmblemPickerSaveFlags flags,
                         GCancellable * const cancellable,
                         GError ** const error,
                         const gpointer for_each_data);

Save the emblems currently selected into the files' metadata

Parameters

self	The emblem picker.	[not nullable]
for_each_file	A function to call for each saved file according to the conditions expressed by the `flag` parameter.	[nullable]
flags	Save options flags
cancellable	A `GCancellable`.	[nullable]
error	A `GError` or `NULL`; ignored unless `GNUI_EMBLEM_PICKER_SAVE_FLAG_ABORT_MODE` is present in `flags` .	[nullable]
for_each_data	The custom data to pass to `for_each_file` .	[nullable]

Returns

true if all the emblems were successfully saved, false otherwise

gnui_emblem_picker_refresh_states ()

void
gnui_emblem_picker_refresh_states (GnuiEmblemPicker * const self);

Refresh the emblem picker's indicator glyphs

This function is useless unless you have just invoked gnui_emblem_picker_save() with GNUI_EMBLEM_PICKER_SAVE_FLAG_DONT_REFRESH.

Parameters

self

The emblem picker.

[not nullable]

gnui_emblem_picker_toggle_emblem ()

gboolean
gnui_emblem_picker_toggle_emblem (GnuiEmblemPicker * const self,
                                  const gchar * const emblem_name);

Toggle/untoggle an emblem picker's emblem

This function behaves exactly like toggling/untoggling an emblem via user input.

Parameters

self	The emblem picker.	[not nullable]
emblem_name	The name of the emblem to toggle.	[transfer none][not nullable]

gnui_emblem_picker_set_emblem_state ()

gboolean
gnui_emblem_picker_set_emblem_state (GnuiEmblemPicker * const self,
                                     const gchar * const emblem_name,
                                     const GnuiEmblemState state,
                                     const gboolean add_if_missing);

Toggle/untoggle an emblem picker's emblem

When add_if_missing is set to false this function behaves exactly like toggling/untoggling an emblem via user input.

Parameters

self	The emblem picker.	[not nullable]
emblem_name	The name of the emblem to set.	[transfer none][not nullable]
state	The state to assign to the emblem
add_if_missing	If `true`, create the emblem when the emblem is not found

gnui_emblem_picker_peek_mapped_files ()

const GList *
gnui_emblem_picker_peek_mapped_files (GnuiEmblemPicker * const self);

Get the const list of the files mapped by an emblem picker

[get-property mapped-files]

Parameters

self

The emblem picker.

[not nullable]

Returns

A GList containing GFile handles (do not free or modify it).

[transfer none]

gnui_emblem_picker_get_mapped_files ()

GList *
gnui_emblem_picker_get_mapped_files (GnuiEmblemPicker * const self);

Get the list of the files mapped by an emblem picker

Parameters

self

The emblem picker.

[not nullable]

Returns

A newly allocated GList containing GFile handles (free it with g_list_free_full(mapped_files, g_object_unref)).

[transfer full]

gnui_emblem_picker_set_mapped_files ()

void
gnui_emblem_picker_set_mapped_files (GnuiEmblemPicker * const self,
                                     const GList * const file_selection);

Set the list of the files mapped by an emblem picker

Changing the emblem picker's files is similar to starting a new session (i.e. creating a new emblem picker). The current emblem selection will be lost.

[set-property mapped-files]

Parameters

self	The emblem picker.	[not nullable]
file_selection	A `GList` containing `GFile` handles to map for their emblems.	[transfer none][nullable]

gnui_emblem_picker_peek_forbidden_emblems ()

const gchar * const *
gnui_emblem_picker_peek_forbidden_emblems
                               (GnuiEmblemPicker * const self);

Get the const array of strings of the emblems that must not be displayed in the emblem picker

[get-property forbidden-emblems]

Parameters

self

The emblem picker.

[not nullable]

Returns

An array of strings containing the names of the emblems that must not be displayed in the emblem picker (do not free or modify it).

[transfer none]

gnui_emblem_picker_get_forbidden_emblems ()

gchar **
gnui_emblem_picker_get_forbidden_emblems
                               (GnuiEmblemPicker * const self);

Get the emblems that must not be displayed in the emblem picker

Parameters

self

The emblem picker.

[not nullable]

Returns

A newly allocated array of strings containing the names of the emblems that must not be displayed in the emblem picker (free the returned array with g_strfreev()).

[transfer full]

gnui_emblem_picker_set_forbidden_emblems ()

void
gnui_emblem_picker_set_forbidden_emblems
                               (GnuiEmblemPicker * const self,
                                const gchar * const * const forbidden_emblems);

Set the emblems that must not be displayed in the emblem picker

[set-property forbidden-emblems]

Parameters

self	The emblem picker.	[not nullable]
forbidden_emblems	An array of strings containing the names of the emblems that must not be displayed in the emblem picker.	[transfer none]

gnui_emblem_picker_get_ensure_standard ()

gboolean
gnui_emblem_picker_get_ensure_standard
                               (GnuiEmblemPicker * const self);

Get whether XDG standard emblems must always be displayed, even if the current icon theme does not support them

For the list of XDG standard emblems, please refer to Icon Naming Specification, Table 6. Standard Emblem Icons.

[get-property ensure-standard]

Parameters

self

The emblem picker.

[not nullable]

Returns

true if XDG standard emblems must always be displayed, false otherwise

gnui_emblem_picker_set_ensure_standard ()

void
gnui_emblem_picker_set_ensure_standard
                               (GnuiEmblemPicker * const self,
                                gboolean ensure_standard);

Set whether XDG standard emblems must always be displayed, even if the current icon theme does not support them

For the list of XDG standard emblems, please refer to Icon Naming Specification, Table 6. Standard Emblem Icons.

[set-property ensure-standard]

Parameters

self	The emblem picker.	[not nullable]
ensure_standard	`true` if XDG standard emblems must always be displayed, even if the current icon theme does not support them; `false` otherwise

gnui_emblem_picker_get_modified ()

gboolean
gnui_emblem_picker_get_modified (GnuiEmblemPicker * const self);

Get whether the emblem selection has been modified by the user

[get-property modified]

Parameters

self

The emblem picker.

[not nullable]

Returns

Whether the emblem selection has been modified by the user

gnui_emblem_picker_set_modified ()

void
gnui_emblem_picker_set_modified (GnuiEmblemPicker * const self,
                                 gboolean modified);

Set whether the emblem selection has been modified by the user

[set-property modified]

Parameters

self	The emblem picker.	[not nullable]
modified	`true` if the emblem picker's state must be set to "modified", `false` otherwise

gnui_emblem_picker_get_reveal_changes ()

gboolean
gnui_emblem_picker_get_reveal_changes (GnuiEmblemPicker * const self);

Get whether an indicator glyph must be displayed for each emblem whose selection state has changed since last save

[get-property reveal-changes]

Parameters

self

The emblem picker.

[not nullable]

Returns

true if an indicator glyph must be displayed for each emblem whose selection state has changed, false otherwise

gnui_emblem_picker_set_reveal_changes ()

void
gnui_emblem_picker_set_reveal_changes (GnuiEmblemPicker * const self,
                                       const gboolean reveal_changes);

Set whether an indicator glyph must be displayed for each emblem whose selection state has changed since last save

[set-property reveal-changes]

Parameters

self	The emblem picker.	[not nullable]
reveal_changes	`true` if an indicator glyph must be displayed for each emblem whose selection state has changed, `false` otherwise

gnui_emblem_picker_foreach ()

void
gnui_emblem_picker_foreach (GnuiEmblemPicker * const self,
                            const GnuiEmblemPickerForeachFunc foreach_func,
                            const gpointer user_data);

Call a custom function for each emblem displayed by the emblem picker

Parameters

self	The emblem picker.	[not nullable]
foreach_func	A function called for each emblem displayed by the emblem picker.	[not nullable]
user_data	The closure to pass to `foreach_func` .	[nullable][closure]

gnui_emblem_picker_undo_all_selections ()

void
gnui_emblem_picker_undo_all_selections
                               (GnuiEmblemPicker * const self);

Bring an emblem picker selection state back to the last saved state

Parameters

self

The emblem picker.

[not nullable]

gnui_emblem_picker_set_all_selections ()

void
gnui_emblem_picker_set_all_selections (GnuiEmblemPicker * const self,
                                       const gboolean selected);

Set the selection state of all the emblems of an emblem picker

Parameters

self	The emblem picker.	[not nullable]
selected	`true` if the selection state must be set to `selected`, `false` for the opposite

GnuiEmblemPickerSignalHandlerEmblemSelected ()

void
(*GnuiEmblemPickerSignalHandlerEmblemSelected)
                               (GnuiEmblemPicker *self,
                                const gchar *emblem_name,
                                GnuiEmblemState saved_state,
                                GnuiEmblemState current_state,
                                const GList *inconsistent_group,
                                gpointer user_data);

A handler function type for the “emblem-selected” signal

Parameters

self	The emblem picker.	[auto][not nullable]
emblem_name	The emblem name.	[auto][transfer none][not nullable]
saved_state	(auto) The last saved state of the emblem
current_state	(auto) The current state of the emblem
inconsistent_group	The inconsistent group of `GFile` handles that can have the emblem assigned independently from the other files, or `NULL`.	[auto][transfer none][nullable]
user_data	The custom data passed to the signal.	[auto][nullable][closure]

GnuiEmblemPickerSignalHandlerModifiedChanged ()

void
(*GnuiEmblemPickerSignalHandlerModifiedChanged)
                               (GnuiEmblemPicker *self,
                                gboolean modified,
                                gpointer user_data);

A handler function type for the “modified-changed” signal

Parameters

self	The emblem picker.	[auto][not nullable]
modified	The current state of the `"modified"` property.	[auto]
user_data	The custom data passed to the signal.	[auto][nullable][closure]

Types and Values

GNUI_TYPE_EMBLEM_PICKER

#define GNUI_TYPE_EMBLEM_PICKER (gnui_emblem_picker_get_type())

The GType of GnuiEmblemPicker

enum GnuiEmblemState

Possible states of an emblem cell

Members

GNUI_EMBLEM_STATES_WITH_PREFIX

enum GnuiEmblemPickerSaveFlags

Possible options for gnui_emblem_picker_save()

Members

GNUI_EMBLEM_PICKER_SAVE_FLAG_NONE	No flags
GNUI_EMBLEM_PICKER_SAVE_FLAG_SAVE_UNMODIFIED	Re-write the files' metadata even if there are no changes
GNUI_EMBLEM_PICKER_SAVE_FLAG_ABORT_MODE	Stop the save operations as soon as a file cannot be saved (without it the save operations will continue until the end)
GNUI_EMBLEM_PICKER_SAVE_FLAG_DONT_REFRESH	Do not refresh the state indicators (useful if this is a last save before destroying the emblem picker widget)
GNUI_EMBLEM_PICKER_SAVE_FLAG_CLEAN_INCONSISTENCY	Erase the information about the emblem's original inconsistency if this is not saved as inconsistent
GNUI_EMBLEM_PICKER_SAVE_FLAG_CALLBACK_ON_ERROR	Invoke the user-given callback on errors
GNUI_EMBLEM_PICKER_SAVE_FLAG_CALLBACK_ON_SUCCESS	Invoke the user-given callback when the file was successfully updated with the new emblems
GNUI_EMBLEM_PICKER_SAVE_FLAG_CALLBACK_ON_NOACTION	Invoke the user-given callback when no actions were performed on the file
GNUI_EMBLEM_PICKER_SAVE_FLAGGROUP_ALL_CALLBACKS	Always invoke the user-given callback, no matter what the save result is
GNUI_EMBLEM_PICKER_SAVE_FLAGGROUP_ALL_FLAGS_SET	Convenience identifier in which all flags are set

enum GnuiEmblemPickerSaveResult

Possible results of gnui_emblem_picker_save() on each file

Members

GNUI_EMBLEM_PICKER_ERROR	The file's emblem metadata could not be saved
GNUI_EMBLEM_PICKER_NOACTION	No actions were necessary for the file's metadata
GNUI_EMBLEM_PICKER_SUCCESS	The file's emblem metadata were successfully saved

GnuiEmblemPicker

typedef struct _GnuiEmblemPicker GnuiEmblemPicker;

The GnuiEmblemPicker widget

Property Details

The `“ensure-standard”` property

  “ensure-standard”          gboolean

Whether to ensure XDG emblems, even when not supported by the current theme.

Owner: GnuiEmblemPicker

Flags: Read / Write / Construct

Default value: FALSE

The `“forbidden-emblems”` property

  “forbidden-emblems”        GStrv

Array of strings containing the names of the emblems to ignore.

[transfer none]

Owner: GnuiEmblemPicker

Flags: Read / Write / Construct

The `“mapped-files”` property

  “mapped-files”             gpointer

GList of GFile objects to map.

[transfer none]

Owner: GnuiEmblemPicker

Flags: Read / Write / Construct

The `“modified”` property

  “modified”                 gboolean

Whether the emblems have changed since last save.

Owner: GnuiEmblemPicker

Flags: Read / Write / Construct

Default value: FALSE

The `“reveal-changes”` property

  “reveal-changes”           gboolean

Whether changes since last save must be visible.

Owner: GnuiEmblemPicker

Flags: Read / Write / Construct

Default value: FALSE

Signal Details

The `“emblem-selected”` signal

void
user_function (GnuiEmblemPicker *self,
               char             *emblem_name,
               int               saved_state,
               int               current_state,
               gpointer          inconsistent_group,
               gpointer          user_data)

Signal emitted when an emblem is selected/unselected

GnuiEmblemPickerSignalHandlerEmblemSelected is the function type of reference for this signal, which takes parameters' constness into account.

Parameters

self	The emblem picker that emitted the signal.	[auto][non-nullable]
emblem_name	The emblem name (do not free or modify it).	[auto][transfer none][non-nullable]
saved_state	The last saved state of the emblem.	[auto]
current_state	The current state of the emblem.	[auto]
inconsistent_group	The inconsistent group of files that can have the emblem assigned independently from the other files or `NULL`.	[auto][transfer none][nullable]
user_data	user data set when the signal handler was connected.

Flags: Run First

The `“modified-changed”` signal

void
user_function (GnuiEmblemPicker *self,
               gboolean          modified,
               gpointer          user_data)

Signal emitted when the “modified” property changes

GnuiEmblemPickerSignalHandlerModifiedChanged is the function type of reference for this signal, which takes parameters' constness into account.

Parameters

self	The emblem picker that emitted the signal.	[auto][non-nullable]
modified	The new value of the “modified” property.	[auto]
user_data	user data set when the signal handler was connected.

Flags: Run First