XAppFavorites: XApp Reference Manual

## XAppFavorites XAppFavorites — Keeps track of favorite files. |

## Functions

XAppFavorites * | xapp_favorites_get_default ()
GList * | xapp_favorites_get_favorites ()
gint | xapp_favorites_get_n_favorites ()
XAppFavoriteInfo * | xapp_favorites_find_by_display_name ()
XAppFavoriteInfo * | xapp_favorites_find_by_uri ()
void | xapp_favorites_add ()
void | xapp_favorites_remove ()
void | xapp_favorites_launch ()
void | xapp_favorites_rename ()
XAppFavoriteInfo * | xapp_favorite_info_copy ()
void | xapp_favorite_info_free ()
void | (*XAppFavoritesItemSelectedCallback) ()
GtkWidget * | xapp_favorites_create_menu ()
GList * | xapp_favorites_create_actions ()

## Signals

void | changed | Action

## Types and Values

#define | XAPP_TYPE_FAVORITES
struct | XAppFavoriteInfo
| XAppFavorites

## Object Hierarchy

        GBoxed
        ╰── XAppFavoriteInfo
        GObject
        ╰── XAppFavorites

## Description

The XAppFavorites class allows applications display frequently-used files and provide a safe mechanism for launching them.

A list of XAppFavoriteInfos can be retrieved in full, or only for specific mimetypes.

A favorites uri scheme is also available if the xapp gtk3 module is loaded and this also makes the uri available as a shortcut in file dialogs.

XAppFavorites are new for 2.0

## Functions

### xapp_favorites_get_default ()

    XAppFavorites *
    xapp_favorites_get_default (void);

Returns the XAppFavorites instance.

#### Returns

the XAppFavorites instance for the process. Do not free.

[transfer none]

Since: 2.0

### xapp_favorites_get_favorites ()

    GList *
    xapp_favorites_get_favorites (XAppFavorites *favorites,
                                  const gchar * const *mimetypes);

Gets a list of all favorites. If mimetype is not `NULL`, the list will contain only favorites with that mimetype.

#### Parameters

favorites | The XAppFavorites |
mimetypes | The mimetypes to filter by for results. | [nullable][array zero-terminated=1]

#### Returns

a list of XAppFavoriteInfos. Free the list with g_list_free, free elements with xapp_favorite_info_free.

[element-type XAppFavoriteInfo][transfer full]

Since: 2.0

### xapp_favorites_get_n_favorites ()

    gint
    xapp_favorites_get_n_favorites (XAppFavorites *favorites);

#### Parameters

favorites | The XAppFavorites |

#### Returns

The number of favorite files

Since: 2.0

### xapp_favorites_find_by_display_name ()

    XAppFavoriteInfo *
    xapp_favorites_find_by_display_name (XAppFavorites *favorites,
                                         const gchar *display_name);

Looks for an XAppFavoriteInfo that corresponds to `display_name` .

#### Parameters

favorites | The XAppFavorites |
display_name | The display name to lookup info for. | [not nullable]

#### Returns

an XAppFavoriteInfo or NULL if one was not found. This is owned by the favorites manager and should not be freed.

[transfer none]

Since: 2.0

### xapp_favorites_find_by_uri ()

    XAppFavoriteInfo *
    xapp_favorites_find_by_uri (XAppFavorites *favorites,
                                const gchar *uri);

Looks for an XAppFavoriteInfo that corresponds to `uri` .

#### Parameters

favorites | The XAppFavorites |
uri | The uri to lookup info for. | [not nullable]

#### Returns

an XAppFavoriteInfo or NULL if one was not found. This is owned by the favorites manager and should not be freed.

[transfer none]

Since: 2.0

### xapp_favorites_add ()

    void
    xapp_favorites_add (XAppFavorites *favorites,
                        const gchar *uri);

Adds a new favorite. If the uri already exists, this does nothing.

#### Parameters

favorites | The XAppFavorites |
uri | The uri the favorite is for |

Since: 2.0

### xapp_favorites_remove ()

    void
    xapp_favorites_remove (XAppFavorites *favorites,
                           const gchar *uri);

Removes a favorite from the list.

#### Parameters

favorites | The XAppFavorites |
uri | The uri for the favorite being removed |

Since: 2.0

### xapp_favorites_launch ()

    void
    xapp_favorites_launch (XAppFavorites *favorites,
                           const gchar *uri,
                           guint32 timestamp);

Opens a favorite in its default app.

#### Parameters

favorites | The XAppFavorites |
uri | The uri for the favorite to launch |
timestamp | The timestamp from an event or 0 |

Since: 2.0

### xapp_favorites_rename ()

    void
    xapp_favorites_rename (XAppFavorites *favorites,
                           const gchar *old_uri,
                           const gchar *new_uri);

Removes old_uri and adds new_uri. This is mainly for file managers to use as a convenience instead of add/remove, and guarantees the result, without having to worry about multiple dbus calls (gsettings).

#### Parameters

old_uri | the old favorite's uri. |
new_uri | The new uri. |

Since: 2.0

### xapp_favorite_info_copy ()

    XAppFavoriteInfo *
    xapp_favorite_info_copy (const XAppFavoriteInfo *info);

Makes an exact copy of an existing XAppFavoriteInfo.

#### Parameters

info | The XAppFavoriteInfo to duplicate. |

#### Returns

a new XAppFavoriteInfo. Free using xapp_favorite_info_free.

Since 2.0.

[transfer full]

### xapp_favorite_info_free ()

    void
    xapp_favorite_info_free (XAppFavoriteInfo *info);

Destroys the XAppFavoriteInfo.

Since 2.0

#### Parameters

info | The XAppFavoriteInfo to free. |

### XAppFavoritesItemSelectedCallback ()

    void
    (*XAppFavoritesItemSelectedCallback) (XAppFavorites *favorites,
                                          const gchar *uri,
                                          gpointer user_data);

### xapp_favorites_create_menu ()

    GtkWidget *
    xapp_favorites_create_menu (XAppFavorites *favorites,
                                const gchar **mimetypes,
                                XAppFavoritesItemSelectedCallback callback,
                                gpointer user_data,
                                GDestroyNotify func);

Generates a GtkMenu widget populated with favorites. The callback will be called when a menu item has been activated, and will include the uri of the respective item.

#### Parameters

favorites | The XAppFavorites instance. |
mimetypes | The mimetypes to filter for, or NULL to include all favorites. | [nullable]
callback | (closure user_data): The callback to use when a menu item has been selected. | [scope notified]
user_data | The data to pass to the callback. | [closure]
func | Destroy function for user_data |

#### Returns

a new GtkMenu populated with a list of favorites, or NULL if there are no favorites.

[transfer full]

Since: 2.0

### xapp_favorites_create_actions ()

    GList *
    xapp_favorites_create_actions (XAppFavorites *favorites,
                                   const gchar **mimetypes);

Generates a list of favorite GtkActions.

#### Parameters

favorites | The XAppFavorites instance. |
mimetypes | The mimetypes to filter for, or NULL to include all favorites. | [nullable]

#### Returns

a new GtkActionGroup populated with a list of favorites, or NULL if there are no favorites.

[element-type Gtk.Action][transfer full]

Since: 2.0

## Types and Values

### XAPP_TYPE_FAVORITES

    #define XAPP_TYPE_FAVORITES           (xapp_favorites_get_type ())

### struct XAppFavoriteInfo

    struct XAppFavoriteInfo {
        gchar *uri;
        gchar *display_name;
        gchar *cached_mimetype;
    };

Information related to a single favorite file.

#### Members

gchar *`uri`; | The uri to the favorite file. |
gchar *`display_name`; | The name for use when displaying the item. This may not exactly match the filename if there are files with the same name but in different folders. |
gchar *`cached_mimetype`; | The mimetype calculated for the uri when it was added to favorites. |

### XAppFavorites

    typedef struct _XAppFavorites XAppFavorites;

## Signal Details

### The `“changed”` signal

    void
    user_function (XAppFavorites *xappfavorites,
                   gpointer       user_data)

Notifies when the favorites list has changed.

#### Parameters

user_data | user data set when the signal handler was connected. |

Flags: Action