# File Explorer (/auxiliary-modules/file_explorer)



`lv_file_explorer` provides a UI enabling the end user to browse the contents of a
file system.  Its main area is called the "Browsing Area" and provides the list of
files contained in the currently-viewed directory.

When enabled, there is also a "Quick-Access" panel on the left, which provides a
convenient way to reach parts of the file system that are frequently accessed.
Available "Quick-Access" destinations are:

* File System,
* HOME,
* Video,
* Pictures,
* Music, and
* Documents.

You specify what paths these lead to during `lv_file_explorer`'s initialization.

`lv_file_explorer` only provides the file browsing and events caused by user
activity (e.g. clicking a file), but does not provide the actual file operations.
Client code must hook various events and decide what to do when they are emitted
(e.g. a click or double-click on a file).  The actions taken might to open the file,
display it, send it to some other part of the application, etc..
`lv_file_explorer` passes the full path and name of file that was clicked to the
event callback functions.  What happens next is up to the application designer.

`lv_file_explorer` uses the [Table (lv\_table)](/widgets/table) Widget for the "Browsing Area", and the
[List (lv\_list)](/widgets/list) Widget for the "Quick-Access" panel when it is enabled.  Thus,
<ApiLink name="LV_USE_TABLE" /> macro must be set to a non-zero value in `lv_conf.h` in
order to use `lv_file_explorer`, and and <ApiLink name="LV_USE_LIST" /> must be set to a
non-zero value to use the "Quick-Access" panel.

<Callout type="info">
  In order to use File Explorer, [File System (lv\_fs\_drv)](/main-modules/fs) has to be set up and
  know about all the drive letters you use when passing paths to File System
  (described below).
</Callout>

Prerequisites [#prerequisites]

If you haven't already done so, you will need to learn about the LVGL [File
System abstraction](/main-modules/fs), since it must be set up and be functional
for File Explorer to work.

Usage [#usage]

Set <ApiLink name="LV_USE_FILE_EXPLORER" /> to a non-zero value in `lv_conf.h`.

First use <ApiLink name="lv_file_explorer_create" display="lv_file_explorer_create(lv_screen_active())" /> to create a File
Explorer.  The default size is the screen size.  After that, you can
customize the style like any Widget.

The size of the `current_path` buffer is set by <ApiLink name="LV_FILE_EXPLORER_PATH_MAX_LEN" />
in `lv_conf.h`.

The object hierarchy of a freshly-created File Explorer looks like this:

* `File Explorer`:  occupies full area of parent Widget, typically a Screen (Flex-Flow COLUMN)

  * `Container`:  occupies full area of File Explorer (Flex grow 1)

    * `Quick-Access Panel`:

      * `Device List`:  grows to accommodate children

        * `File System`:  button

      * `Places List`:  grows to accommodate children

        * `HOME`:  button
        * `Video`:  button
        * `Pictures`:  button
        * `Music`:  button
        * `Documents`:  button

    * `Browser Panel`:

      * `Header`:  14% of `Browser Panel` height

        * `Current Path`:  label

      * `File Table`:  with 1 column, 86% of `Browser Panel` height

  * Fields:

    * `home_dir` = NULL
    * `video_dir` = NULL
    * `pictures_dir` = NULL
    * `music_dir` = NULL
    * `docs_dir` = NULL
    * `fs_dir` = NULL
    * `current_path` = \[empty buffer]
    * `sel_fn` (selected file)
    * `sort` (default <ApiLink name="LV_EXPLORER_SORT_NONE" />)

Accessing the Parts [#accessing-the-parts]

This list of functions provides access to the parts shown in diagram above:

* <ApiLink name="lv_file_explorer_get_selected_file_name" display="lv_file_explorer_get_selected_file_name(explorer)" />  (pointer
  to NUL-terminated string containing file-path user selected; typically used inside
  an <ApiLink name="LV_EVENT_CLICKED" /> event)
* <ApiLink name="lv_file_explorer_get_current_path" display="lv_file_explorer_get_current_path(explorer)" /> (pointer to `current_path` `char` buffer)
* <ApiLink name="lv_file_explorer_get_file_table" display="lv_file_explorer_get_file_table(explorer)" />  (pointer to `File Table` [Table (lv\_table)](/widgets/table) Widget)
* <ApiLink name="lv_file_explorer_get_header" display="lv_file_explorer_get_header(explorer)" />  (pointer to `Header` [base widget](/widgets/base_widget) Widget)
* <ApiLink name="lv_file_explorer_get_path_label" display="lv_file_explorer_get_path_label(explorer)" />  (pointer to `Current Path Label` [Label (lv\_label)](/widgets/label) Widget)
* <ApiLink name="lv_file_explorer_get_quick_access_area" display="lv_file_explorer_get_quick_access_area(explorer)" />  (pointer to `Quick-Access Panel` [base widget](/widgets/base_widget))
* <ApiLink name="lv_file_explorer_get_places_list" display="lv_file_explorer_get_places_list(explorer)" />    (pointer to `Places List` [List (lv\_list)](/widgets/list) Widget)
* <ApiLink name="lv_file_explorer_get_device_list" display="lv_file_explorer_get_device_list(explorer)" />    (pointer to `Device List` [List (lv\_list)](/widgets/list) Widget)

Quick-Access Panel [#quick-access-panel]

The `Quick-Access Panel` behaves like a typical navigation panel and appears on the
left, while the `Browser Panel` appears on the right

This panel is optional.  If you set <ApiLink name="LV_FILE_EXPLORER_QUICK_ACCESS" /> to `0`
in `lv_conf.h`, the `Quick-Access Panel` will not be created.  This saves only a
little bit of memory.

Soon after the File Explorer is created, you typically use

<ApiLink name="lv_file_explorer_set_quick_access_path" display="lv_file_explorer_set_quick_access_path(explorer, LV_EXPLORER_XXX_DIR, &#x22;path&#x22;)" />

to set the path that will be navigated to when the buttons in the `Quick-Access Panel`
are clicked, which is currently a fixed list.  The corresponding values you will need
to pass as the 2nd argument are the following:

* <ApiLink name="LV_EXPLORER_HOME_DIR" />
* <ApiLink name="LV_EXPLORER_MUSIC_DIR" />
* <ApiLink name="LV_EXPLORER_PICTURES_DIR" />
* <ApiLink name="LV_EXPLORER_VIDEO_DIR" />
* <ApiLink name="LV_EXPLORER_DOCS_DIR" />
* <ApiLink name="LV_EXPLORER_FS_DIR" />

Sort [#sort]

You can use
<ApiLink name="lv_file_explorer_set_sort" display="lv_file_explorer_set_sort(explorer, LV_EXPLORER_SORT_XX)" /> to set
the sorting method.

These are the possible sorting methods:

* <ApiLink name="LV_EXPLORER_SORT_NONE" /> (default)
* <ApiLink name="LV_EXPLORER_SORT_KIND" />

<ApiLink name="lv_file_explorer_get_sort" display="lv_file_explorer_get_sort(explorer)" /> returns the current sorting method.

Events [#events]

* <ApiLink name="LV_EVENT_READY" /> Sent when a directory is opened, which can happen:

  * when the File Explorer is initially opened,
  * after a user clicks on a `Quick-Access Panel` navigation button, and
  * after the user clicks on a directory displayed in the `Browser Panel`.

  You can use it to, for example, customize the file sort.
* <ApiLink name="LV_EVENT_VALUE_CHANGED" /> Sent once when any item (file) in the
  `Browser Panel`'s file list is clicked.
* <ApiLink name="LV_EVENT_CLICKED" /> Sent twice when an item in the `Browser Panel`
  is clicked:  once as a result of the input-device <ApiLink name="LV_EVENT_RELEASED" />
  event and a second as a result of the input device <ApiLink name="LV_EVENT_CLICKED" />
  event.  This applies to files, directories, and the "\< Back" item in the `Browser Panel`.

In these events you can use <ApiLink name="lv_file_explorer_get_current_path" /> to get the
current path and <ApiLink name="lv_file_explorer_get_selected_file_name" /> to get the name
of the currently selected file in the event processing function. For example:

```c title=" " lineNumbers=1
static void file_explorer_event_handler(lv_event_t * e)
{
    lv_event_code_t code = lv_event_get_code(e);
    lv_obj_t * obj = lv_event_get_target(e);

    if(code == LV_EVENT_VALUE_CHANGED) {
        char * cur_path =  lv_file_explorer_get_current_path(widget);
        char * sel_fn = lv_file_explorer_get_selected_file_name(widget);
        LV_LOG_USER("%s%s", cur_path, sel_fn);
    }
}
```

You can also save the obtained **path** and **file** name into an array
through functions such as <ApiLink name="strcpy" /> and <ApiLink name="strcat" /> for later use.

Examples [#examples]

Simple File Explorer [#simple-file-explorer]

<LvglExample name="lv_example_file_explorer_1" path="others/file_explorer/lv_example_file_explorer_1" />

Control File Explorer [#control-file-explorer]

<LvglExample name="lv_example_file_explorer_2" path="others/file_explorer/lv_example_file_explorer_2" />

Custom sort [#custom-sort]

<LvglExample name="lv_example_file_explorer_3" path="others/file_explorer/lv_example_file_explorer_3" />

API [#api]