FmFolderModel

## FmFolderModel FmFolderModel — A model for folder view window. |

## Synopsis

    #define             FM_FOLDER_MODEL_COL_DEFAULT
    #define             FM_FOLDER_MODEL_COL_UNSORTED
                        FmFolderModel;
    struct              FmFolderModelClass;
    enum                FmFolderModelCol;
    struct              FmFolderModelColumnInit;
    enum                FmFolderModelExtraFilePos;
    gboolean            (*FmFolderModelFilterFunc)          (FmFileInfo *file,
                                                             gpointer user_data);
    #define             FM_MODULE_gtk_folder_col_VERSION
    extern FmFolderModelColumnInit fm_module_init_gtk_folder_col;
    FmFolderModelCol    fm_folder_model_add_custom_column   (const char *name,
                                                             FmFolderModelColumnInit *init);
    void                fm_folder_model_add_filter          (FmFolderModel *model,
                                                             FmFolderModelFilterFunc func,
                                                             gpointer user_data);
    void                fm_folder_model_apply_filters       (FmFolderModel *model);
    gint                fm_folder_model_col_get_default_width
                                                            (FmFolderModel *model,
                                                             FmFolderModelCol col_id);
    const char *        fm_folder_model_col_get_name        (FmFolderModelCol col_id);
    const char *        fm_folder_model_col_get_title       (FmFolderModel *model,
                                                             FmFolderModelCol col_id);
    gboolean            fm_folder_model_col_is_sortable     (FmFolderModel *model,
                                                             FmFolderModelCol col_id);
    gboolean            fm_folder_model_col_is_valid        (FmFolderModelCol col_id);
    gboolean            fm_folder_model_extra_file_add      (FmFolderModel *model,
                                                             FmFileInfo *file,
                                                             FmFolderModelExtraFilePos where);
    gboolean            fm_folder_model_extra_file_remove   (FmFolderModel *model,
                                                             FmFileInfo *file);
    void                fm_folder_model_file_changed        (FmFolderModel *model,
                                                             FmFileInfo *file);
    void                fm_folder_model_file_created        (FmFolderModel *model,
                                                             FmFileInfo *file);
    void                fm_folder_model_file_deleted        (FmFolderModel *model,
                                                             FmFileInfo *file);
    gboolean            fm_folder_model_find_iter_by_filename
                                                            (FmFolderModel *model,
                                                             GtkTreeIter *it,
                                                             const char *name);
    FmFolderModelCol    fm_folder_model_get_col_by_name     (const char *str);
    FmFolder *          fm_folder_model_get_folder          (FmFolderModel *model);
    FmPath *            fm_folder_model_get_folder_path     (FmFolderModel *model);
    guint               fm_folder_model_get_icon_size       (FmFolderModel *model);
    gpointer            fm_folder_model_get_item_userdata   (FmFolderModel *model,
                                                             GtkTreeIter *it);
    gboolean            fm_folder_model_get_show_hidden     (FmFolderModel *model);
    gboolean            fm_folder_model_get_sort            (FmFolderModel *model,
                                                             FmFolderModelCol *col,
                                                             FmSortMode *mode);
    FmFolderModel *     fm_folder_model_new                 (FmFolder *dir,
                                                             gboolean show_hidden);
    void                fm_folder_model_remove_filter       (FmFolderModel *model,
                                                             FmFolderModelFilterFunc func,
                                                             gpointer user_data);
    void                fm_folder_model_set_folder          (FmFolderModel *model,
                                                             FmFolder *dir);
    void                fm_folder_model_set_icon_size       (FmFolderModel *model,
                                                             guint icon_size);
    void                fm_folder_model_set_item_userdata   (FmFolderModel *model,
                                                             GtkTreeIter *it,
                                                             gpointer user_data);
    void                fm_folder_model_set_show_hidden     (FmFolderModel *model,
                                                             gboolean show_hidden);
    void                fm_folder_model_set_sort            (FmFolderModel *model,
                                                             FmFolderModelCol col,
                                                             FmSortMode mode);

## Object Hierarchy

      GObject
       +----FmFolderModel

## Implemented Interfaces

FmFolderModel implements GtkTreeModel, GtkTreeSortable, GtkTreeDragSource and GtkTreeDragDest.

## Signals

      "filter-changed"                                 : Run First
      "row-deleting"                                   : Run First

## Description

`include`: libfm/fm-gtk.h

The FmFolderModel is used by widgets such as FmFolderView to arrange items of folder.

## Details

### FM_FOLDER_MODEL_COL_DEFAULT

    #define FM_FOLDER_MODEL_COL_DEFAULT ((FmFolderModelCol)-1)

value which means do not change sorting column.

### FM_FOLDER_MODEL_COL_UNSORTED

    #define FM_FOLDER_MODEL_COL_UNSORTED FM_FOLDER_MODEL_COL_INFO

for 'Unsorted' folder view use 'FileInfo' column which is ambiguous for sorting

### FmFolderModel

    typedef struct _FmFolderModel FmFolderModel;

### struct FmFolderModelClass

    struct FmFolderModelClass {
        GObjectClass parent;
        void (*row_deleting)(FmFolderModel* model, GtkTreePath* tp,
                             GtkTreeIter* iter, gpointer data);
        void (*filter_changed)(FmFolderModel* model);
    };

GObjectClass `parent`; | the parent class
`row_deleting` () | the class closure for the "row-deleting" signal
`filter_changed` () | the class closure for the "filter-changed" signal

### enum FmFolderModelCol

    typedef enum {
        FM_FOLDER_MODEL_COL_GICON = 0,
        FM_FOLDER_MODEL_COL_ICON,
        FM_FOLDER_MODEL_COL_NAME,
        FM_FOLDER_MODEL_COL_SIZE,
        FM_FOLDER_MODEL_COL_DESC,
        FM_FOLDER_MODEL_COL_PERM,
        FM_FOLDER_MODEL_COL_OWNER,
        FM_FOLDER_MODEL_COL_MTIME,
        FM_FOLDER_MODEL_COL_INFO,
        FM_FOLDER_MODEL_COL_DIRNAME,
        FM_FOLDER_MODEL_COL_EXT,
    } FmFolderModelCol;

Columns of folder view

`FM_FOLDER_MODEL_COL_GICON` | (GIcon *) icon descriptor
`FM_FOLDER_MODEL_COL_ICON` | (GdkPixbuf *) icon image
`FM_FOLDER_MODEL_COL_NAME` | (gchar *) file display name
`FM_FOLDER_MODEL_COL_SIZE` | (gchar *) file size text
`FM_FOLDER_MODEL_COL_DESC` | (gchar *) file MIME description
`FM_FOLDER_MODEL_COL_PERM` | (gchar *) file permissions like "rw-r--r--"
`FM_FOLDER_MODEL_COL_OWNER` | (gchar *) file owner username
`FM_FOLDER_MODEL_COL_MTIME` | (gchar *) modification time text
`FM_FOLDER_MODEL_COL_INFO` | (FmFileInfo *) file info
`FM_FOLDER_MODEL_COL_DIRNAME` | (gchar *) path of dir containing the file
`FM_FOLDER_MODEL_COL_EXT` | (gchar *) (since 1.2.0) last suffix of file name

### struct FmFolderModelColumnInit

    struct FmFolderModelColumnInit {
        const char *title;
        gint default_width;
        GType (*get_type)(void);
        void (*get_value)(FmFileInfo *fi, GValue *value);
        gint (*compare)(FmFileInfo *fi1, FmFileInfo *fi2);
    };

This structure is used for "gtk_folder_col" module initialization. The key for module of this type is new unique column name.

const char *`title`; | column title
gint `default_width`; | default width for column (0 means auto)
`get_type` () | function to get GType of column data
`get_value` () | function to retrieve column data
`compare` () | sorting routine (`NULL` if column isn't sortable)

Since 1.2.0

### enum FmFolderModelExtraFilePos

    typedef enum {
        FM_FOLDER_MODEL_ITEMPOS_SORTED = 0,
        FM_FOLDER_MODEL_ITEMPOS_PRE,
        FM_FOLDER_MODEL_ITEMPOS_POST
    } FmFolderModelExtraFilePos;

Where the `fm_folder_model_extra_file_add()` should insert extra file item.

`FM_FOLDER_MODEL_ITEMPOS_SORTED` | insert extra item into main sorted list
`FM_FOLDER_MODEL_ITEMPOS_PRE` | insert extra item before main list
`FM_FOLDER_MODEL_ITEMPOS_POST` | insert extra item after main list

### FmFolderModelFilterFunc ()

    gboolean            (*FmFolderModelFilterFunc)          (FmFileInfo *file,
                                                             gpointer user_data);

A callback used by FmFolderModel to filter visible items in the model.

`file` : | the file to check filtering
`user_data` : | data supplied to `fm_folder_model_add_filter()`
Returns : | `TRUE` if `file` should be visible.

Since 1.0.2

### FM_MODULE_gtk_folder_col_VERSION

    #define FM_MODULE_gtk_folder_col_VERSION 1

### fm_module_init_gtk_folder_col

    extern FmFolderModelColumnInit fm_module_init_gtk_folder_col;

### fm_folder_model_add_custom_column ()

    FmFolderModelCol    fm_folder_model_add_custom_column   (const char *name,
                                                             FmFolderModelColumnInit *init);

Registers custom columns in FmFolderModel handlers.

`name` : | unique name of column
`init` : | setup data for column
Returns : | new column ID or FM_FOLDER_MODEL_COL_DEFAULT in case of failure.

Since 1.2.0

### fm_folder_model_add_filter ()

    void                fm_folder_model_add_filter          (FmFolderModel *model,
                                                             FmFolderModelFilterFunc func,
                                                             gpointer user_data);

Install a filter function to filter out and hide some items. This only install a filter function and does not update content of the model. You need to call `fm_folder_model_apply_filters()` to refilter the model.

`model` : | the folder model instance
`func` : | a filter function
`user_data` : | user data passed to the filter function

Since 1.0.2

### fm_folder_model_apply_filters ()

    void                fm_folder_model_apply_filters       (FmFolderModel *model);

After changing the filters by `fm_folder_model_add_filter()` or `fm_folder_model_remove_filter()`, you have to call this function to really apply the filter to the model content. This is for performance reason. You can add many filter functions and also remove some, and then call `fm_folder_model_apply_filters()` to update the content of the model once.

If you forgot to call `fm_folder_model_apply_filters()`, the content of the model may be incorrect.

`model` : | the folder model instance

Since 1.0.2

### fm_folder_model_col_get_default_width ()

    gint                fm_folder_model_col_get_default_width
                                                            (FmFolderModel *model,
                                                             FmFolderModelCol col_id);

Retrieves preferred width for `col_id`.

`model` : | model to check. [allow-none]
`col_id` : | column id
Returns : | default width.

Since 1.2.0

### fm_folder_model_col_get_name ()

    const char *        fm_folder_model_col_get_name        (FmFolderModelCol col_id);

Retrieves the name of the column specified, or `NULL` if the specified `col_id` is invalid. The name of column may be used for config save or another similar purpose. Returned data are owned by implementation and should be not freed by caller.

`col_id` : | column id
Returns : | the name associated with column.

Since 1.0.2

### fm_folder_model_col_get_title ()

    const char *        fm_folder_model_col_get_title       (FmFolderModel *model,
                                                             FmFolderModelCol col_id);

Retrieves the title of the column specified, or `NULL` if the specified `col_id` is invalid. Returned data are owned by implementation and should be not freed by caller.

`model` : | the folder model. [allow-none]
`col_id` : | column id
Returns : | title of column in current locale.

Since 1.0.2

### fm_folder_model_col_is_sortable ()

    gboolean            fm_folder_model_col_is_sortable     (FmFolderModel *model,
                                                             FmFolderModelCol col_id);

Checks if model can be sorted by `col_id`.

`model` : | model to check. [allow-none]
`col_id` : | column id
Returns : | `TRUE` if model can be sorted by `col_id`.

Since 1.0.2

### fm_folder_model_col_is_valid ()

    gboolean            fm_folder_model_col_is_valid        (FmFolderModelCol col_id);

Checks if `col_id` can be handled by FmFolderModel. This API makes things similar to `gtk_tree_model_get_n_columns()` but it doesn't operate the model instance.

`col_id` : | column id
Returns : | `TRUE` if `col_id` is valid.

Since 1.2.0

### fm_folder_model_extra_file_add ()

    gboolean            fm_folder_model_extra_file_add      (FmFolderModel *model,
                                                             FmFileInfo *file,
                                                             FmFolderModelExtraFilePos where);

Adds `file` into `model`. Added file will stay at defined position after any folder change.

See also: `fm_folder_model_set_folder()`, `fm_folder_model_extra_file_remove()`.

`model` : | the folder model instance
`file` : | the file into
`where` : | position where to put `file` in folder model
Returns : | `FALSE` if adding was failed.

Since 1.2.0

### fm_folder_model_extra_file_remove ()

    gboolean            fm_folder_model_extra_file_remove   (FmFolderModel *model,
                                                             FmFileInfo *file);

Removes `file` from `model` if `file` was added to the model using `fm_folder_model_extra_file_add()`.

`model` : | the folder model instance
`file` : | the file into
Returns : | `FALSE` if `file` cannot be removed.

Since 1.2.0

### fm_folder_model_file_changed ()

    void                fm_folder_model_file_changed        (FmFolderModel *model,
                                                             FmFileInfo *file);

Updates info for the `file` in the `model`.

`model` : | a folder model instance
`file` : | a file into

Since 0.1.0

### fm_folder_model_file_created ()

    void                fm_folder_model_file_created        (FmFolderModel *model,
                                                             FmFileInfo *file);

Adds new created `file` into `model`.

`model` : | the folder model instance
`file` : | new file into

Since 0.1.0

### fm_folder_model_file_deleted ()

    void                fm_folder_model_file_deleted        (FmFolderModel *model,
                                                             FmFileInfo *file);

Removes a `file` from `model`.

`model` : | the folder model instance
`file` : | removed file into

Since 0.1.0

### fm_folder_model_find_iter_by_filename ()

    gboolean            fm_folder_model_find_iter_by_filename
                                                            (FmFolderModel *model,
                                                             GtkTreeIter *it,
                                                             const char *name);

Searches `model` for existance of some file in it. If file was found then sets `it` to match found file.

`model` : | the folder model instance
`it` : | pointer to iterator to fill
`name` : | file name to search
Returns : | `TRUE` if file was found.

Since 0.1.0

### fm_folder_model_get_col_by_name ()

    FmFolderModelCol    fm_folder_model_get_col_by_name     (const char *str);

Finds a column which has associated name equal to `str`.

`str` : | a column name
Returns : | column id or (FmFolderModelCol)-1 if no such column exists.

Since 1.0.2

### fm_folder_model_get_folder ()

    FmFolder *          fm_folder_model_get_folder          (FmFolderModel *model);

Retrieves a folder that `model` is created for. Returned data are owned by the `model` and should not be freed by caller.

`model` : | the folder model instance
Returns : | the folder descriptor. [transfer none]

Since 1.0.0

### fm_folder_model_get_folder_path ()

    FmPath *            fm_folder_model_get_folder_path     (FmFolderModel *model);

Retrieves path of folder that `model` is created for. Returned data are owned by the `model` and should not be freed by caller.

`model` : | the folder model instance
Returns : | the path of the folder of the model. [transfer none]

Since 1.0.0

### fm_folder_model_get_icon_size ()

    guint               fm_folder_model_get_icon_size       (FmFolderModel *model);

Retrieves the size of icons in `model` data.

`model` : | the folder model instance
Returns : | size of icons in pixels.

Since 0.1.0

### fm_folder_model_get_item_userdata ()

    gpointer            fm_folder_model_get_item_userdata   (FmFolderModel *model,
                                                             GtkTreeIter *it);

Returns the data that was set by last call of `fm_folder_model_set_item_userdata()` on that row.

`model` : | the folder model instance
`it` : | iterator of row to retrieve data
Returns : | user data that was set on that row

Since 1.0.0

### fm_folder_model_get_show_hidden ()

    gboolean            fm_folder_model_get_show_hidden     (FmFolderModel *model);

Retrieves info whether folder model includes hidden files.

`model` : | the folder model instance
Returns : | `TRUE` if hidden files are visible within `model`.

Since 0.1.0

### fm_folder_model_get_sort ()

    gboolean            fm_folder_model_get_sort            (FmFolderModel *model,
                                                             FmFolderModelCol *col,
                                                             FmSortMode *mode);

Retrieves current sorting criteria for `model`.

`model` : | model to query
`col` : | location to store sorting column. [out][allow-none]
`mode` : | location to store sorting mode. [out][allow-none]
Returns : | `TRUE` if `model` is valid.

Since 1.0.2

### fm_folder_model_new ()

    FmFolderModel *     fm_folder_model_new                 (FmFolder *dir,
                                                             gboolean show_hidden);

Creates new folder model for the `dir`.

`dir` : | the folder to create model
`show_hidden` : | whether show hidden files initially or not
Returns : | a new FmFolderModel object. [transfer full]

Since 0.1.0

### fm_folder_model_remove_filter ()

    void                fm_folder_model_remove_filter       (FmFolderModel *model,
                                                             FmFolderModelFilterFunc func,
                                                             gpointer user_data);

Remove a filter function previously installed by `fm_folder_model_add_filter()` This only remove the filter function and does not update content of the model. You need to call `fm_folder_model_apply_filters()` to refilter the model.

`model` : | the folder model instance
`func` : | a filter function
`user_data` : | user data passed to the filter function

Since 1.0.2

### fm_folder_model_set_folder ()

    void                fm_folder_model_set_folder          (FmFolderModel *model,
                                                             FmFolder *dir);

Changes folder which model handles. This call allows reusing the model for different folder, in case, e.g. directory was changed.

Items added to `model` with `fm_folder_model_extra_file_add()` are not affected by this API.

`model` : | a folder model instance
`dir` : | a new folder for the model

Since 0.1.0

### fm_folder_model_set_icon_size ()

    void                fm_folder_model_set_icon_size       (FmFolderModel *model,
                                                             guint icon_size);

Changes the size of icons in `model` data.

`model` : | the folder model instance
`icon_size` : | new size for icons in pixels

Since 0.1.0

### fm_folder_model_set_item_userdata ()

    void                fm_folder_model_set_item_userdata   (FmFolderModel *model,
                                                             GtkTreeIter *it,
                                                             gpointer user_data);

Sets the data that can be retrieved by `fm_folder_model_get_item_userdata()`.

`model` : | the folder model instance
`it` : | iterator of row to set data
`user_data` : | user data that will be associated with the row

Since 1.0.0

### fm_folder_model_set_show_hidden ()

    void                fm_folder_model_set_show_hidden     (FmFolderModel *model,
                                                             gboolean show_hidden);

Changes visibility of hodden files within `model`.

`model` : | the folder model instance
`show_hidden` : | whether show hidden files or not

Since 0.1.0

### fm_folder_model_set_sort ()

    void                fm_folder_model_set_sort            (FmFolderModel *model,
                                                             FmFolderModelCol col,
                                                             FmSortMode mode);

Changes sorting of `model` items in accordance to new `col` and `mode`. If new parameters are not different from previous then nothing will be changed (nor any signal emitted).

`model` : | model to apply
`col` : | new sorting column
`mode` : | new sorting mode

Since 1.0.2

## Signal Details

### The `"filter-changed"` signal

    void                user_function                      (FmFolderModel *model,
                                                            gpointer       user_data)      : Run First

This signal is emitted when model data were changed due to filter changes.

`model` : | folder model instance that received the signal
`user_data` : | user data set when the signal handler was connected.

Since 1.0.2

### The `"row-deleting"` signal

    void                user_function                      (FmFolderModel *model,
                                                            GtkTreePath   *row,
                                                            GtkTreeIter   *iter,
                                                            gpointer       data,
                                                            gpointer       user_data)      : Run First

This signal is emitted before row is deleted.

It can be used if view has some data associated with the row so those data can be freed safely.

`model` : | folder model instance that received the signal
`row` : | path to row that is about to be deleted
`iter` : | iterator of row that is about to be deleted
`data` : | user data associated with the row
`user_data` : | user data set when the signal handler was connected.

Since 1.0.0