FmFolderModel: Libfm Reference Manual

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

## Functions

gboolean | (*FmFolderModelFilterFunc) ()
FmFolderModel * | fm_folder_model_new ()
void | fm_folder_model_set_folder ()
FmFolder * | fm_folder_model_get_folder ()
FmPath * | fm_folder_model_get_folder_path ()
void | fm_folder_model_set_item_userdata ()
gpointer | fm_folder_model_get_item_userdata ()
gboolean | fm_folder_model_get_show_hidden ()
void | fm_folder_model_set_show_hidden ()
void | fm_folder_model_file_created ()
void | fm_folder_model_file_deleted ()
void | fm_folder_model_file_changed ()
gboolean | fm_folder_model_find_iter_by_filename ()
void | fm_folder_model_set_icon_size ()
guint | fm_folder_model_get_icon_size ()
void | fm_folder_model_add_filter ()
void | fm_folder_model_remove_filter ()
void | fm_folder_model_apply_filters ()
void | fm_folder_model_set_sort ()
gboolean | fm_folder_model_get_sort ()
gboolean | fm_folder_model_extra_file_add ()
gboolean | fm_folder_model_extra_file_remove ()
const char * | fm_folder_model_col_get_title ()
gboolean | fm_folder_model_col_is_sortable ()
const char * | fm_folder_model_col_get_name ()
FmFolderModelCol | fm_folder_model_get_col_by_name ()
gint | fm_folder_model_col_get_default_width ()
gboolean | fm_folder_model_col_is_valid ()
FmFolderModelCol | fm_folder_model_add_custom_column ()

## Signals

void | filter-changed | Run First
void | row-deleting | Run First

## Types and Values

enum | FmFolderModelCol
#define | FM_FOLDER_MODEL_COL_UNSORTED
#define | FM_FOLDER_MODEL_COL_DEFAULT
#define | FmFolderModelViewCol
#define | COL_FILE_GICON
#define | COL_FILE_ICON
#define | COL_FILE_NAME
#define | COL_FILE_SIZE
#define | COL_FILE_DESC
#define | COL_FILE_PERM
#define | COL_FILE_OWNER
#define | COL_FILE_MTIME
#define | COL_FILE_INFO
#define | COL_FILE_UNSORTED
struct | FmFolderModelClass
enum | FmFolderModelExtraFilePos
struct | FmFolderModelColumnInit
#define | FM_MODULE_gtk_folder_col_VERSION
extern FmFolderModelColumnInit | fm_module_init_gtk_folder_col

## Object Hierarchy

        GObject
        ╰── FmFolderModel

## Description

`include` : libfm/fm-gtk.h

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

## Functions

### FmFolderModelFilterFunc ()

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

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

#### Parameters

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_folder_model_new ()

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

Creates new folder model for the `dir` .

#### Parameters

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_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.

#### Parameters

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

Since: 0.1.0

### 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.

#### Parameters

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.

#### Parameters

model | the folder model instance |

#### Returns

the path of the folder of the model.

[transfer none]

Since: 1.0.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()`.

#### Parameters

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_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.

#### Parameters

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.

#### Parameters

model | the folder model instance |

#### Returns

`TRUE` if hidden files are visible within `model` .

Since: 0.1.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` .

#### Parameters

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

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` .

#### Parameters

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` .

#### Parameters

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

Since: 0.1.0

### fm_folder_model_file_changed ()

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

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

#### Parameters

model | a folder model instance |
file | a 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.

#### Parameters

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_set_icon_size ()

    void
    fm_folder_model_set_icon_size (FmFolderModel *model,
                                   guint icon_size);

Changes the size of icons in `model` data.

#### Parameters

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

Since: 0.1.0

### fm_folder_model_get_icon_size ()

    guint
    fm_folder_model_get_icon_size (FmFolderModel *model);

Retrieves the size of icons in `model` data.

#### Parameters

model | the folder model instance |

#### Returns

size of icons in pixels.

Since: 0.1.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.

#### Parameters

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_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.

#### Parameters

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.

#### Parameters

model | the folder model instance |

Since: 1.0.2

### 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).

#### Parameters

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

Since: 1.0.2

### fm_folder_model_get_sort ()

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

Retrieves current sorting criteria for `model` .

#### Parameters

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_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()`.

#### Parameters

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()`.

#### Parameters

model | the folder model instance |
file | the file into |

#### Returns

`FALSE` if `file` cannot be removed.

Since: 1.2.0

### 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.

#### Parameters

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` .

#### Parameters

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_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.

#### Parameters

col_id | column id |

#### Returns

the name associated with column.

Since: 1.0.2

### 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` .

#### Parameters

str | a column name |

#### Returns

column id or (FmFolderModelCol)-1 if no such column exists.

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` .

#### Parameters

model | model to check. | [allow-none]
col_id | column id |

#### Returns

default width.

Since: 1.2.0

### 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.

#### Parameters

col_id | column id |

#### Returns

`TRUE` if `col_id` is valid.

Since: 1.2.0

### fm_folder_model_add_custom_column ()

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

Registers custom columns in FmFolderModel handlers.

#### Parameters

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

## Types and Values

### enum FmFolderModelCol

Columns of folder view

#### Members

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 |

### 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

### FM_FOLDER_MODEL_COL_DEFAULT

    #define FM_FOLDER_MODEL_COL_DEFAULT ((FmFolderModelCol)-1)

value which means do not change sorting column.

### FmFolderModelViewCol

    #define FmFolderModelViewCol    FmFolderModelCol

`FmFolderModelViewCol` is deprecated and should not be used in newly-written code.

### COL_FILE_GICON

    #define COL_FILE_GICON          FM_FOLDER_MODEL_COL_GICON

`COL_FILE_GICON` is deprecated and should not be used in newly-written code.

### COL_FILE_ICON

    #define COL_FILE_ICON           FM_FOLDER_MODEL_COL_ICON

`COL_FILE_ICON` is deprecated and should not be used in newly-written code.

### COL_FILE_NAME

    #define COL_FILE_NAME           FM_FOLDER_MODEL_COL_NAME

`COL_FILE_NAME` is deprecated and should not be used in newly-written code.

### COL_FILE_SIZE

    #define COL_FILE_SIZE           FM_FOLDER_MODEL_COL_SIZE

`COL_FILE_SIZE` is deprecated and should not be used in newly-written code.

### COL_FILE_DESC

    #define COL_FILE_DESC           FM_FOLDER_MODEL_COL_DESC

`COL_FILE_DESC` is deprecated and should not be used in newly-written code.

### COL_FILE_PERM

    #define COL_FILE_PERM           FM_FOLDER_MODEL_COL_PERM

`COL_FILE_PERM` is deprecated and should not be used in newly-written code.

### COL_FILE_OWNER

    #define COL_FILE_OWNER          FM_FOLDER_MODEL_COL_OWNER

`COL_FILE_OWNER` is deprecated and should not be used in newly-written code.

### COL_FILE_MTIME

    #define COL_FILE_MTIME          FM_FOLDER_MODEL_COL_MTIME

`COL_FILE_MTIME` is deprecated and should not be used in newly-written code.

### COL_FILE_INFO

    #define COL_FILE_INFO           FM_FOLDER_MODEL_COL_INFO

`COL_FILE_INFO` is deprecated and should not be used in newly-written code.

### COL_FILE_UNSORTED

    #define COL_FILE_UNSORTED       FM_FOLDER_MODEL_COL_UNSORTED

`COL_FILE_UNSORTED` is deprecated and should not be used in newly-written code.

### struct FmFolderModelClass

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

#### Members

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 FmFolderModelExtraFilePos

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

#### Members

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 |

### 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.

#### Members

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

### 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;

## Signal Details

### The `“filter-changed”` signal

    void
    user_function (FmFolderModel *model,
                   gpointer       user_data)

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

#### Parameters

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

Flags: Run First

Since: 1.0.2

### The `“row-deleting”` signal

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

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.

#### Parameters

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

Flags: Run First

Since: 1.0.0