## FmDirListJob

FmDirListJob — Job to get listing of directory.

## Functions

FmDirListJob * | fm_dir_list_job_new ()
FmDirListJob * | fm_dir_list_job_new2 ()
FmDirListJob * | fm_dir_list_job_new_for_gfile ()
FmFileInfoList * | fm_dir_list_job_get_files ()
void | fm_dir_list_job_set_incremental ()
void | fm_dir_list_job_add_found_file ()

## Signals

void | files-found | Run Last

## Types and Values

enum | FmDirListJobFlags

## Object Hierarchy

        GObject
        ╰── FmJob
            ╰── FmDirListJob

## Description

`include` : libfm/fm.h

The FmDirListJob can be used to gather list of FmFileInfo that some directory contains.

## Functions

### fm_dir_list_job_new ()

    FmDirListJob *
    fm_dir_list_job_new (FmPath *path,
                         gboolean dir_only);

`fm_dir_list_job_new` has been deprecated since version 1.2.0 and should not be used in newly-written code.

Use `fm_dir_list_job_new2()` instead.

Creates a new FmDirListJob for directory listing. If `dir_only` is `TRUE` then objects other than directories will be omitted from the listing.

#### Parameters

path | path to directory to get listing |
dir_only | `TRUE` to include only directories in the list |

#### Returns

a new FmDirListJob object.

[transfer full]

Since: 0.1.0

### fm_dir_list_job_new2 ()

    FmDirListJob *
    fm_dir_list_job_new2 (FmPath *path,
                          FmDirListJobFlags flags);

Creates a new FmDirListJob for directory listing.

#### Parameters

path | path to directory to get listing |
flags | listing output mode for new job |

#### Returns

a new FmDirListJob object.

[transfer full]

Since: 1.2.0

### fm_dir_list_job_new_for_gfile ()

    FmDirListJob *
    fm_dir_list_job_new_for_gfile (GFile *gf);

Creates a new FmDirListJob for listing of directory `gf` .

#### Parameters

gf | descriptor of directory to get listing |

#### Returns

a new FmDirListJob object.

[transfer full]

Since: 0.1.0

### fm_dir_list_job_get_files ()

    FmFileInfoList *
    fm_dir_list_job_get_files (FmDirListJob *job);

Retrieves gathered listing from the `job` . This function may be called only from “finished” signal handler. Returned data is owned by the `job` and should be not freed by caller.

Before 1.0.1 this call had name fm_dir_dist_job_get_files due to typo.

#### Parameters

job | the job that collected listing |

#### Returns

list of gathered data.

[transfer none]

Since: 0.1.0

### fm_dir_list_job_set_incremental ()

    void
    fm_dir_list_job_set_incremental (FmDirListJob *job,
                                     gboolean set);

Sets whether `job` should send the “files-found” signal on found files before the `job` is finished or not. This should only be called before the `job` is launched.

#### Parameters

job | the job descriptor |
set | `TRUE` if job should send the “files-found” signal |

Since: 1.0.2

### fm_dir_list_job_add_found_file ()

    void
    fm_dir_list_job_add_found_file (FmDirListJob *job,
                                    FmFileInfo *file);

This API may be called by the classes derived of FmDirListJob only. Application developers should not use this API. When a new file is found in the dir being listed, implementations of FmDirListJob should call this API with the info of the newly found file. The FmFileInfo will be added to the found file list.

If emission of the “files-found” signal is turned on by `fm_dir_list_job_set_incremental()`, the signal will be emitted for the newly found files after several new files are added. See the document for the signal for more detail.

#### Parameters

job | the job that collected listing |
file | a FmFileInfo of the newly found file |

Since: 1.0.2

## Types and Values

### enum FmDirListJobFlags

#### Members

FM_DIR_LIST_JOB_FAST | default listing mode with minimized I/O |
FM_DIR_LIST_JOB_DIR_ONLY | skip non-directories in output |
FM_DIR_LIST_JOB_DETAILED | listing with test files content types |

## Signal Details

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

    void
    user_function (FmDirListJob *job,
                   gpointer      files,
                   gpointer      user_data)

The “files-found” signal is emitted for every file found during directory listing. By default the signal is not emitted for performance reason. This can be turned on by calling `fm_dir_list_job_set_incremental()`.

#### Parameters

job | a job that emitted the signal |
files | GSList of found files. | [element-type FmFileInfo]
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 1.0.2