FmFolder: Libfm Reference Manual

## FmFolder FmFolder — Folder loading and monitoring. |

## Functions

FmFolder * | fm_folder_from_path ()
FmFolder * | fm_folder_from_gfile ()
FmFolder * | fm_folder_from_path_name ()
FmFolder * | fm_folder_from_uri ()
FmFolder * | fm_folder_find_by_path ()
void | fm_folder_block_updates ()
void | fm_folder_unblock_updates ()
FmFileInfo * | fm_folder_get_info ()
FmPath * | fm_folder_get_path ()
FmFileInfoList * | fm_folder_get_files ()
gboolean | fm_folder_is_empty ()
FmFileInfo * | fm_folder_get_file_by_name ()
gboolean | fm_folder_is_loaded ()
gboolean | fm_folder_is_valid ()
gboolean | fm_folder_is_incremental ()
void | fm_folder_reload ()
gboolean | fm_folder_get_filesystem_info ()
void | fm_folder_query_filesystem_info ()
gboolean | fm_folder_make_directory ()

## Signals

void | changed | Run First
void | content-changed | Run First
guint | error | Run Last
void | files-added | Run First
void | files-changed | Run First
void | files-removed | Run First
void | finish-loading | Run First
void | fs-info | Run First
void | removed | Run First
void | start-loading | Run First
void | unmount | Run First

## Object Hierarchy

        GObject
        ╰── FmFolder

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

## Functions

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

#### Parameters

path | path descriptor for the folder |

#### Returns

FmFolder corresponding to `path` .

[transfer full]

Since: 0.1.1

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

#### Parameters

gf | GFile file descriptor |

#### Returns

FmFolder corresponding to `gf` .

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

#### Parameters

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.

#### Parameters

uri | URI for the folder |

#### Returns

FmFolder corresponding to `uri` .

[transfer full]

Since: 0.1.0

### fm_folder_find_by_path ()

    FmFolder *
    fm_folder_find_by_path (FmPath *path);

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

#### Parameters

path | path descriptor |

#### Returns

found folder or `NULL`.

[transfer full]

Since: 1.2.0

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

#### Parameters

folder | folder to apply |

Since: 1.2.0

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

#### Parameters

folder | folder to apply |

Since: 1.2.0

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

#### Parameters

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.

#### Parameters

folder | folder to retrieve path |

#### Returns

path of the folder.

[transfer none]

Since: 1.0.0

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

#### Parameters

folder | folder to retrieve file list |

#### Returns

list of items that `folder` currently contains.

[transfer none]

Since: 0.1.1

### fm_folder_is_empty ()

    gboolean
    fm_folder_is_empty (FmFolder *folder);

Checks if folder has no files or subdirectories.

#### Parameters

folder | folder to test |

#### Returns

`TRUE` if folder is empty.

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

#### Parameters

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

#### Parameters

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.

#### Parameters

folder | folder to test |

#### Returns

`TRUE` if `folder` describes a valid existing directory.

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.

#### Parameters

folder | folder to test |

#### Returns

`TRUE` if `folder` is incrementally loaded

Since: 1.0.2

### fm_folder_reload ()

    void
    fm_folder_reload (FmFolder *folder);

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

#### Parameters

folder | folder to be reloaded |

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

#### Parameters

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

#### Parameters

folder | folder to retrieve info |

Since: 0.1.16

### fm_folder_make_directory ()

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

Creates new directory in given `folder` .

#### Parameters

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

## Signal Details

### The `“changed”` signal

    void
    user_function (FmFolder *folder,
                   gpointer  user_data)

The “changed” signal is emitted when the folder itself was changed.

#### Parameters

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

Flags: Run First

Since: 0.1.16

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

    void
    user_function (FmFolder *folder,
                   gpointer  user_data)

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

#### Parameters

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

Flags: Run First

Since: 0.1.16

### The `“error”` signal

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

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

#### Parameters

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.

Flags: Run Last

Since: 0.1.1

### The `“files-added”` signal

    void
    user_function (FmFolder *folder,
                   gpointer  list,
                   gpointer  user_data)

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

#### Parameters

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

Flags: Run First

Since: 0.1.0

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

    void
    user_function (FmFolder *folder,
                   gpointer  list,
                   gpointer  user_data)

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

#### Parameters

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

Flags: Run First

Since: 0.1.0

### The `“files-removed”` signal

    void
    user_function (FmFolder *folder,
                   gpointer  list,
                   gpointer  user_data)

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

#### Parameters

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

Flags: Run First

Since: 0.1.0

### The `“finish-loading”` signal

    void
    user_function (FmFolder *folder,
                   gpointer  user_data)

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

#### Parameters

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

Flags: Run First

Since: 1.0.0

### The `“fs-info”` signal

    void
    user_function (FmFolder *folder,
                   gpointer  user_data)

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

#### Parameters

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

Flags: Run First

Since: 0.1.16

### The `“removed”` signal

    void
    user_function (FmFolder *folder,
                   gpointer  user_data)

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

#### Parameters

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

Flags: Run First

Since: 0.1.16

### The `“start-loading”` signal

    void
    user_function (FmFolder *folder,
                   gpointer  user_data)

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

#### Parameters

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

Flags: Run First

Since: 1.0.0

### The `“unmount”` signal

    void
    user_function (FmFolder *folder,
                   gpointer  user_data)

The “unmount” signal is emitted when the folder was unmounted.

#### Parameters

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

Flags: Run First

Since: 0.1.1