## FmBookmarks FmBookmarks — Bookmarks support for libfm. |

## Synopsis

    #define             FM_BOOKMARKS_TYPE
    struct              FmBookmarkItem;
    struct              FmBookmarks;
    struct              FmBookmarksClass;
    FmBookmarkItem *    fm_bookmark_item_ref                (FmBookmarkItem *item);
    void                fm_bookmark_item_unref              (FmBookmarkItem *item);
    #define             fm_bookmarks_append                 (bookmarks,
                                                             path,
                                                             name)
    FmBookmarks *       fm_bookmarks_dup                    (void);
    GList *             fm_bookmarks_get_all                (FmBookmarks *bookmarks);
    FmBookmarkItem *    fm_bookmarks_insert                 (FmBookmarks *bookmarks,
                                                             FmPath *path,
                                                             const char *name,
                                                             int pos);
    const GList *       fm_bookmarks_list_all               (FmBookmarks *bookmarks);
    void                fm_bookmarks_remove                 (FmBookmarks *bookmarks,
                                                             FmBookmarkItem *item);
    void                fm_bookmarks_rename                 (FmBookmarks *bookmarks,
                                                             FmBookmarkItem *item,
                                                             const char *new_name);
    void                fm_bookmarks_reorder                (FmBookmarks *bookmarks,
                                                             FmBookmarkItem *item,
                                                             int pos);

## Object Hierarchy

      GObject
       +----FmBookmarks

## Signals

      "changed"                                        : Run First

## Description

`include`: libfm/fm.h

The application that uses libfm can use user-wide bookmark list via class FmBookmarks.

## Details

### FM_BOOKMARKS_TYPE

    #define FM_BOOKMARKS_TYPE               (fm_bookmarks_get_type())

### struct FmBookmarkItem

    struct FmBookmarkItem {
        char* name;
        FmPath* path;
    };

char *`name`; | display name of bookmark
FmPath *`path`; | path to bookmarked directory

### struct FmBookmarks

    struct FmBookmarks;

### struct FmBookmarksClass

    struct FmBookmarksClass {
        GObjectClass parent_class;
        void (*changed)(FmBookmarks*);
    };

GObjectClass `parent_class`; | the parent class
`changed` () | the class closure for "changed" signal

### fm_bookmark_item_ref ()

    FmBookmarkItem *    fm_bookmark_item_ref                (FmBookmarkItem *item);

Increases reference counter on `item`.

`item` : | an item
Returns : | `item`.

Since 1.0.2

### fm_bookmark_item_unref ()

    void                fm_bookmark_item_unref              (FmBookmarkItem *item);

Decreases reference counter on `item` and frees data when it reaches 0.

`item` : | item to be freed

Since 1.0.2

### fm_bookmarks_append()

    #define fm_bookmarks_append(bookmarks, path, name)  fm_bookmarks_insert(bookmarks, path, name, -1)

### fm_bookmarks_dup ()

    FmBookmarks *       fm_bookmarks_dup                    (void);

Returns reference to bookmarks list singleton descriptor.

This API is not thread-safe and should be used only in default context.

Returns : | a reference to bookmarks list. [transfer full]

Since 0.1.99

### fm_bookmarks_get_all ()

    GList *             fm_bookmarks_get_all                (FmBookmarks *bookmarks);

Returns list of FmBookmarkItem retrieved from bookmarks list. Returned list should be freed with g_list_free_full(list, fm_bookmark_item_unref).

`bookmarks` : | bookmarks list
Returns : | list of bookmark items. [transfer full][element-type FmBookmarkItem]

Since 1.0.2

### fm_bookmarks_insert ()

    FmBookmarkItem *    fm_bookmarks_insert                 (FmBookmarks *bookmarks,
                                                             FmPath *path,
                                                             const char *name,
                                                             int pos);

Adds a bookmark into bookmark list. Returned structure is managed by bookmarks list and should not be freed by caller. If you want to save returned data then call `fm_bookmark_item_ref()` on it.

`bookmarks` : | bookmarks list
`path` : | path requested to add to bookmarks
`name` : | name new bookmark will be seen in list with
`pos` : | where to insert a bookmark into list
Returns : | new created bookmark item. [transfer none]

Since 0.1.0

### fm_bookmarks_list_all ()

    const GList *       fm_bookmarks_list_all               (FmBookmarks *bookmarks);

### Warning

`fm_bookmarks_list_all` has been deprecated since version 1.0.2 and should not be used in newly-written code. Use `fm_bookmarks_get_all()` instead.

Returns list of FmBookmarkItem retrieved from bookmarks list. Returned list is owned by bookmarks list and should not be freed by caller.

`bookmarks` : | bookmarks list
Returns : | list of bookmark items. [transfer none][element-type FmBookmarkItem]

Since 0.1.0

### fm_bookmarks_remove ()

    void                fm_bookmarks_remove                 (FmBookmarks *bookmarks,
                                                             FmBookmarkItem *item);

Removes a bookmark from bookmark list.

`bookmarks` : | bookmarks list
`item` : | bookmark item for deletion

Since 0.1.0

### fm_bookmarks_rename ()

    void                fm_bookmarks_rename                 (FmBookmarks *bookmarks,
                                                             FmBookmarkItem *item,
                                                             const char *new_name);

Changes name of existing bookmark item.

`bookmarks` : | bookmarks list
`item` : | bookmark item which will be changed
`new_name` : | new name for bookmark item to be seen in list

Since 0.1.0

### fm_bookmarks_reorder ()

    void                fm_bookmarks_reorder                (FmBookmarks *bookmarks,
                                                             FmBookmarkItem *item,
                                                             int pos);

Changes position of existing bookmark item.

`bookmarks` : | bookmarks list
`item` : | bookmark item which will be changed
`pos` : | new position for bookmark item in list

Since 0.1.0

## Signal Details

### The `"changed"` signal

    void                user_function                      (FmBookmarks *bookmarks,
                                                            gpointer     user_data)      : Run First

The "changed" signal is emitted when some bookmark item is changed, added, or removed.

`bookmarks` : | pointer to bookmarks list singleton descriptor
`user_data` : | user data set when the signal handler was connected.

Since 0.1.0