FmFolder

## FmFolder FmFolder — Folder loading and monitoring. |

## Synopsis

                        FmFolder;
    struct              FmFolderClass;
    void                fm_folder_block_updates             (FmFolder *folder);
    FmFolder *          fm_folder_find_by_path              (FmPath *path);
    FmFolder *          fm_folder_from_gfile                (GFile *gf);
    FmFolder *          fm_folder_from_path                 (FmPath *path);
    FmFolder *          fm_folder_from_path_name            (const char *path);
    FmFolder *          fm_folder_from_uri                  (const char *uri);
    FmFileInfo *        fm_folder_get_file_by_name          (FmFolder *folder,
                                                             const char *name);
    FmFileInfoList *    fm_folder_get_files                 (FmFolder *folder);
    gboolean            fm_folder_get_filesystem_info       (FmFolder *folder,
                                                             guint64 *total_size,
                                                             guint64 *free_size);
    FmFileInfo *        fm_folder_get_info                  (FmFolder *folder);
    FmPath *            fm_folder_get_path                  (FmFolder *folder);
    gboolean            fm_folder_is_empty                  (FmFolder *folder);
    gboolean            fm_folder_is_incremental            (FmFolder *folder);
    gboolean            fm_folder_is_loaded                 (FmFolder *folder);
    gboolean            fm_folder_is_valid                  (FmFolder *folder);
    gboolean            fm_folder_make_directory            (FmFolder *folder,
                                                             const char *name,
                                                             GError **error);
    void                fm_folder_query_filesystem_info     (FmFolder *folder);
    void                fm_folder_reload                    (FmFolder *folder);
    void                fm_folder_unblock_updates           (FmFolder *folder);

## Object Hierarchy

      GObject
       +----FmFolder

## Signals

      "changed"                                        : Run First
      "content-changed"                                : Run First
      "error"                                          : Run Last
      "files-added"                                    : Run First
      "files-changed"                                  : Run First
      "files-removed"                                  : Run First
      "finish-loading"                                 : Run First
      "fs-info"                                        : Run First
      "removed"                                        : Run First
      "start-loading"                                  : Run First
      "unmount"                                        : Run First

## Description

`include`: libfm/fm.h

The FmFolder object allows to open and monitor items of some directory (either local or remote), i.e. files and directories, to have fast access to their info and to info of the directory itself as well.

## Details

### FmFolder

    typedef struct _FmFolder FmFolder;

### struct FmFolderClass

    struct FmFolderClass {
        GObjectClass parent_class;

        void (*files_added)(FmFolder* dir, GSList* files);
        void (*files_removed)(FmFolder* dir, GSList* files);
        void (*files_changed)(FmFolder* dir, GSList* files);
        void (*start_loading)(FmFolder* dir);
        void (*finish_loading)(FmFolder* dir);
        void (*unmount)(FmFolder* dir);
        void (*changed)(FmFolder* dir);
        void (*removed)(FmFolder* dir);
        void (*content_changed)(FmFolder* dir);
        void (*fs_info)(FmFolder* dir);
        guint (*error)(FmFolder* dir, GError* err, guint severity);
    };

GObjectClass `parent_class`; | the parent class
`files_added` () | the class closure for "files-added" signal
`files_removed` () | the class closure for "files-removed" signal
`files_changed` () | the class closure for "files-changed" signal
`start_loading` () | the class closure for "start-loading" signal
`finish_loading` () | the class closure for "finish-loading" signal
`unmount` () | the class closure for "unmount" signal
`changed` () | the class closure for "changed" signal
`removed` () | the class closure for "removed" signal
`content_changed` () | the class closure for "content-changed" signal
`fs_info` () | the class closure for "fs-info" signal
`error` () | the class closure for "error" signal

### fm_folder_block_updates ()

    void                fm_folder_block_updates             (FmFolder *folder);

Blocks emitting signals for changes in folder, i.e. if some file was added, changed, or removed in folder after this API, no signal will be sent until next call to `fm_folder_unblock_updates()`.

`folder` : | folder to apply

Since 1.2.0

### fm_folder_find_by_path ()

    FmFolder *          fm_folder_find_by_path              (FmPath *path);

Checks if folder by `path` is already in use.

`path` : | path descriptor
Returns : | found folder or `NULL`. [transfer full]

Since 1.2.0

### fm_folder_from_gfile ()

    FmFolder *          fm_folder_from_gfile                (GFile *gf);

Retrieves a folder corresponding to `gf`. Returned data may be freshly created or already loaded. Caller should call `g_object_unref()` on the returned data after usage.

Before 1.0.0 this call had name fm_folder_get_for_gfile.

`gf` : | GFile file descriptor
Returns : | FmFolder corresponding to `gf`. [transfer full]

Since 0.1.1

### fm_folder_from_path ()

    FmFolder *          fm_folder_from_path                 (FmPath *path);

Retrieves a folder corresponding to `path`. Returned data may be freshly created or already loaded. Caller should call `g_object_unref()` on the returned data after usage.

Before 1.0.0 this call had name fm_folder_get.

`path` : | path descriptor for the folder
Returns : | FmFolder corresponding to `path`. [transfer full]

Since 0.1.1

### fm_folder_from_path_name ()

    FmFolder *          fm_folder_from_path_name            (const char *path);

Retrieves a folder corresponding to `path`. Returned data may be freshly created or already loaded. Caller should call `g_object_unref()` on the returned data after usage.

Before 1.0.0 this call had name fm_folder_get_for_path_name.

`path` : | POSIX path to the folder
Returns : | FmFolder corresponding to `path`. [transfer full]

Since 0.1.0

### fm_folder_from_uri ()

    FmFolder *          fm_folder_from_uri                  (const char *uri);

Retrieves a folder corresponding to `uri`. Returned data may be freshly created or already loaded. Caller should call `g_object_unref()` on the returned data after usage.

Before 1.0.0 this call had name fm_folder_get_for_uri.

`uri` : | URI for the folder
Returns : | FmFolder corresponding to `uri`. [transfer full]

Since 0.1.0

### fm_folder_get_file_by_name ()

    FmFileInfo *        fm_folder_get_file_by_name          (FmFolder *folder,
                                                             const char *name);

Tries to find a file with basename `name` in the `folder`. Returned data is owned by FmFolder and should be not freed by caller.

`folder` : | folder to search
`name` : | basename of file in `folder`
Returns : | info descriptor of file or `NULL` if no file was found. [transfer none]

Since 0.1.16

### fm_folder_get_files ()

    FmFileInfoList *    fm_folder_get_files                 (FmFolder *folder);

Retrieves list of currently known files and subdirectories in the `folder`. Returned list is owned by FmFolder and should be not modified by caller. If caller wants to keep a reference to the returned list it should do fm_file_info_list_ref() on the returned data.

Before 1.0.0 this call had name fm_folder_get.

`folder` : | folder to retrieve file list
Returns : | list of items that `folder` currently contains. [transfer none]

Since 0.1.1

### fm_folder_get_filesystem_info ()

    gboolean            fm_folder_get_filesystem_info       (FmFolder *folder,
                                                             guint64 *total_size,
                                                             guint64 *free_size);

Retrieves info about total and free space on the filesystem which contains the `folder`.

`folder` : | folder to retrieve info
`total_size` : | pointer to counter of total size of the filesystem
`free_size` : | pointer to counter of free space on the filesystem
Returns : | `TRUE` if information can be retrieved.

Since 0.1.16

### fm_folder_get_info ()

    FmFileInfo *        fm_folder_get_info                  (FmFolder *folder);

Retrieves FmFileInfo data about the folder itself. Returned data is owned by FmFolder and should be not modified or freed by caller.

`folder` : | folder to retrieve info
Returns : | info descriptor of the `folder`. [transfer none]

Since 1.0.0

### fm_folder_get_path ()

    FmPath *            fm_folder_get_path                  (FmFolder *folder);

Retrieves path of the folder. Returned data is owned by FmFolder and should be not modified or freed by caller.

`folder` : | folder to retrieve path
Returns : | path of the folder. [transfer none]

Since 1.0.0

### fm_folder_is_empty ()

    gboolean            fm_folder_is_empty                  (FmFolder *folder);

Checks if folder has no files or subdirectories.

`folder` : | folder to test
Returns : | `TRUE` if folder is empty.

Since 1.0.0

### fm_folder_is_incremental ()

    gboolean            fm_folder_is_incremental            (FmFolder *folder);

Checks if a folder is incrementally loaded. After an FmFolder object is obtained from calling `fm_folder_from_path()`, if it's not yet loaded, it begins loading the content of the folder and emits "start-loading" signal. Most of the time, the info of the files in the folder becomes available only after the folder is fully loaded. That means, after the "finish-loading" signal is emitted. Before the loading is finished, `fm_folder_get_files()` returns nothing. You can tell if a folder is still being loaded with `fm_folder_is_loaded()`.

However, for some special FmFolder types, such as the ones handling search:// URIs, we want to access the file infos while the folder is still being loaded (the search is still ongoing). The content of the folder grows incrementally and `fm_folder_get_files()` returns files currently being loaded even when the folder is not fully loaded. This is what we called incremental. `fm_folder_is_incremental()` tells you if the FmFolder has this feature.

`folder` : | folder to test
Returns : | `TRUE` if `folder` is incrementally loaded

Since 1.0.2

### fm_folder_is_loaded ()

    gboolean            fm_folder_is_loaded                 (FmFolder *folder);

Checks if all data for `folder` is completely loaded.

Before 1.0.0 this call had name fm_folder_get_is_loaded.

`folder` : | folder to test
Returns : | `TRUE` is loading of folder is already completed.

Since 0.1.16

### fm_folder_is_valid ()

    gboolean            fm_folder_is_valid                  (FmFolder *folder);

Checks if directory described by `folder` exists.

`folder` : | folder to test
Returns : | `TRUE` if `folder` describes a valid existing directory.

Since 1.0.0

### fm_folder_make_directory ()

    gboolean            fm_folder_make_directory            (FmFolder *folder,
                                                             const char *name,
                                                             GError **error);

Creates new directory in given `folder`.

`folder` : | folder to apply
`name` : | display name for new directory
`error` : | location to save error. [allow-none][out]
Returns : | `TRUE` in case of success.

Since 1.2.0

### fm_folder_query_filesystem_info ()

    void                fm_folder_query_filesystem_info     (FmFolder *folder);

Queries to retrieve info about filesystem which contains the `folder` if the filesystem supports such query.

`folder` : | folder to retrieve info

Since 0.1.16

### fm_folder_reload ()

    void                fm_folder_reload                    (FmFolder *folder);

Causes to retrieve all data for the `folder` as if folder was freshly opened.

`folder` : | folder to be reloaded

Since 0.1.1

### fm_folder_unblock_updates ()

    void                fm_folder_unblock_updates           (FmFolder *folder);

Unblocks emitting signals for changes in folder. If some changes were in folder after previous call to `fm_folder_block_updates()` then these changes will be sent after this call.

`folder` : | folder to apply

Since 1.2.0

## Signal Details

### The `"changed"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  user_data)      : Run First

The "changed" signal is emitted when the folder itself was changed.

`folder` : | the monitored directory
`user_data` : | user data set when the signal handler was connected.

Since 0.1.16

### The `"content-changed"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  user_data)      : Run First

The "content-changed" signal is emitted when content of the folder is changed (some files are added, removed, or changed).

`folder` : | the monitored directory
`user_data` : | user data set when the signal handler was connected.

Since 0.1.16

### The `"error"` signal

    guint               user_function                      (FmFolder *folder,
                                                            GError   *error,
                                                            guint     severity,
                                                            gpointer  user_data)      : Run Last

The "error" signal is emitted when some error happens. A case if more than one handler is connected to this signal is ambiguous.

`folder` : | the monitored directory
`error` : | error descriptor
`severity` : | FmJobErrorSeverity of the error
`user_data` : | user data set when the signal handler was connected.
Returns : | FmJobErrorAction that should be performed on that error.

Since 0.1.1

### The `"files-added"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  list,
                                                            gpointer  user_data)      : Run First

The "files-added" signal is emitted when there is some new file created in the directory.

`folder` : | the monitored directory
`list` : | GList of newly added FmFileInfo
`user_data` : | user data set when the signal handler was connected.

Since 0.1.0

### The `"files-changed"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  list,
                                                            gpointer  user_data)      : Run First

The "files-changed" signal is emitted when some file in the directory was changed.

`folder` : | the monitored directory
`list` : | GList of FmFileInfo that were changed
`user_data` : | user data set when the signal handler was connected.

Since 0.1.0

### The `"files-removed"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  list,
                                                            gpointer  user_data)      : Run First

The "files-removed" signal is emitted when some file was deleted from the directory.

`folder` : | the monitored directory
`list` : | GList of FmFileInfo that were deleted
`user_data` : | user data set when the signal handler was connected.

Since 0.1.0

### The `"finish-loading"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  user_data)      : Run First

The "finish-loading" signal is emitted when the content of the folder is loaded. This signal may be emitted more than once and can be induced by calling `fm_folder_reload()`.

`folder` : | the monitored directory
`user_data` : | user data set when the signal handler was connected.

Since 1.0.0

### The `"fs-info"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  user_data)      : Run First

The "fs-info" signal is emitted when filesystem information is available.

`folder` : | the monitored directory
`user_data` : | user data set when the signal handler was connected.

Since 0.1.16

### The `"removed"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  user_data)      : Run First

The "removed" signal is emitted when the folder itself was deleted.

`folder` : | the monitored directory
`user_data` : | user data set when the signal handler was connected.

Since 0.1.16

### The `"start-loading"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  user_data)      : Run First

The "start-loading" signal is emitted when the folder is about to be reloaded.

`folder` : | the monitored directory
`user_data` : | user data set when the signal handler was connected.

Since 1.0.0

### The `"unmount"` signal

    void                user_function                      (FmFolder *folder,
                                                            gpointer  user_data)      : Run First

The "unmount" signal is emitted when the folder was unmounted.

`folder` : | the monitored directory
`user_data` : | user data set when the signal handler was connected.

Since 0.1.1