FmDirListJob

## FmDirListJob FmDirListJob — Job to get listing of directory. |

## Synopsis

    struct              FmDirListJob;
    struct              FmDirListJobClass;
    enum                FmDirListJobFlags;
    void                fm_dir_list_job_add_found_file      (FmDirListJob *job,
                                                             FmFileInfo *file);
    FmFileInfoList *    fm_dir_list_job_get_files           (FmDirListJob *job);
    FmDirListJob *      fm_dir_list_job_new                 (FmPath *path,
                                                             gboolean dir_only);
    FmDirListJob *      fm_dir_list_job_new2                (FmPath *path,
                                                             FmDirListJobFlags flags);
    FmDirListJob *      fm_dir_list_job_new_for_gfile       (GFile *gf);
    void                fm_dir_list_job_set_incremental     (FmDirListJob *job,
                                                             gboolean set);

## Object Hierarchy

      GObject
       +----FmJob
             +----FmDirListJob

## Signals

      "files-found"                                    : Run Last

## Description

`include`: libfm/fm.h

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

## Details

### struct FmDirListJob

    struct FmDirListJob {
        FmJob parent;
        FmPath* dir_path;
        FmDirListJobFlags flags;
        FmFileInfo* dir_fi;
        FmFileInfoList* files;
    };

FmJob `parent`; | the parent object
FmPath *`dir_path`; | directory to get listing
FmDirListJobFlags `flags`; | flags for the job
FmFileInfo *`dir_fi`; | file info of the directory
FmFileInfoList *`files`; | the listing of the directory

### struct FmDirListJobClass

    struct FmDirListJobClass {
    };

### enum FmDirListJobFlags

    typedef enum {
        FM_DIR_LIST_JOB_FAST = 0,
        FM_DIR_LIST_JOB_DIR_ONLY = 1 << 0,
        FM_DIR_LIST_JOB_DETAILED = 1 << 1
    } FmDirListJobFlags;

`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

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

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

Since 1.0.2

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

`job` : | the job that collected listing
Returns : | list of gathered data. [transfer none]

Since 0.1.0

### fm_dir_list_job_new ()

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

### Warning

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

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

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

`gf` : | descriptor of directory to get listing
Returns : | a new FmDirListJob object. [transfer full]

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.

`job` : | the job descriptor
`set` : | `TRUE` if job should send the "files-found" signal

Since 1.0.2

## Signal Details

### The `"files-found"` signal

    void                user_function                      (FmDirListJob *job,
                                                            gpointer      files,
                                                            gpointer      user_data)      : Run Last

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

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

Since 1.0.2