1.. _file_explorer: 2 3============= 4File Explorer 5============= 6 7``lv_file_explorer`` provides a UI enabling the end user to browse the contents of a 8file system. Its main area is called the "Browsing Area" and provides the list of 9files contained in the currently-viewed directory. 10 11When enabled, there is also a "Quick-Access" panel on the left, which provides a 12convenient way to reach parts of the file system that are frequently accessed. 13Available "Quick-Access" destinations are: 14 15- File System, 16- HOME, 17- Video, 18- Pictures, 19- Music, and 20- Documents. 21 22You specify what paths these lead to during ``lv_file_explorer``\ 's initialization. 23 24``lv_file_explorer`` only provides the file browsing and events caused by user 25activity (e.g. clicking a file), but does not provide the actual file operations. 26Client code must hook various events and decide what to do when they are emitted 27(e.g. a click or double-click on a file). The actions taken might to open the file, 28display it, send it to some other part of the application, etc.. 29``lv_file_explorer`` passes the full path and name of file that was clicked to the 30event callback functions. What happens next is up to the application designer. 31 32``lv_file_explorer`` uses the :ref:`lv_table` Widget for the "Browsing Area", and the 33:ref:`lv_list` Widget for the "Quick-Access" panel when it is enabled. Thus, 34:c:macro:`LV_USE_TABLE` macro must be set to a non-zero value in ``lv_conf.h`` in 35order to use ``lv_file_explorer``, and and :c:macro:`LV_USE_LIST` must be set to a 36non-zero value to use the "Quick-Access" panel. 37 38.. note:: 39 40 In order to use File Explorer, :ref:`overview_file_system` has to be set up and 41 know about all the drive letters you use when passing paths to File System 42 (described below). 43 44 45 46Prerequisites 47************* 48 49If you haven't already done so, you will need to learn about the LVGL :ref:`File 50System abstraction <overview_file_system>`, since it must be set up and be functional 51for File Explorer to work. 52 53 54 55.. _file_explorer_usage: 56 57Usage 58***** 59 60Set :c:macro:`LV_USE_FILE_EXPLORER` to a non-zero value in ``lv_conf.h``. 61 62First use :cpp:expr:`lv_file_explorer_create(lv_screen_active())` to create a File 63Explorer. The default size is the screen size. After that, you can 64customize the style like any Widget. 65 66The size of the ``current_path`` buffer is set by :c:macro:`LV_FILE_EXPLORER_PATH_MAX_LEN` 67in ``lv_conf.h``. 68 69The object hierarchy of a freshly-created File Explorer looks like this: 70 71- ``File Explorer``: occupies full area of parent Widget, typically a Screen (Flex-Flow COLUMN) 72 73 - ``Container``: occupies full area of File Explorer (Flex grow 1) 74 75 - ``Quick-Access Panel``: 76 77 - ``Device List``: grows to accommodate children 78 79 - ``File System``: button 80 81 - ``Places List``: grows to accommodate children 82 83 - ``HOME``: button 84 - ``Video``: button 85 - ``Pictures``: button 86 - ``Music``: button 87 - ``Documents``: button 88 89 - ``Browser Panel``: 90 91 - ``Header``: 14% of ``Browser Panel`` height 92 93 - ``Current Path``: label 94 95 - ``File Table``: with 1 column, 86% of ``Browser Panel`` height 96 97 - Fields: 98 99 - ``home_dir`` = NULL 100 - ``video_dir`` = NULL 101 - ``pictures_dir`` = NULL 102 - ``music_dir`` = NULL 103 - ``docs_dir`` = NULL 104 - ``fs_dir`` = NULL 105 - ``current_path`` = [empty buffer] 106 - ``sel_fn`` (selected file) 107 - ``sort`` (default :cpp:enumerator:`LV_EXPLORER_SORT_NONE`) 108 109 110Accessing the Parts 111------------------- 112 113This list of functions provides access to the parts shown in diagram above: 114 115- :cpp:expr:`lv_file_explorer_get_selected_file_name(explorer)` (pointer 116 to NUL-terminated string containing file-path user selected; typically used inside 117 an :cpp:enumerator:`LV_EVENT_CLICKED` event) 118- :cpp:expr:`lv_file_explorer_get_current_path(explorer)` (pointer to ``current_path`` ``char`` buffer) 119- :cpp:expr:`lv_file_explorer_get_file_table(explorer)` (pointer to ``File Table`` :ref:`lv_table` Widget) 120- :cpp:expr:`lv_file_explorer_get_header(explorer)` (pointer to ``Header`` :ref:`base_widget` Widget) 121- :cpp:expr:`lv_file_explorer_get_path_label(explorer)` (pointer to ``Current Path Label`` :ref:`lv_label` Widget) 122- :cpp:expr:`lv_file_explorer_get_quick_access_area(explorer)` (pointer to ``Quick-Access Panel`` :ref:`base_widget`) 123- :cpp:expr:`lv_file_explorer_get_places_list(explorer)` (pointer to ``Places List`` :ref:`lv_list` Widget) 124- :cpp:expr:`lv_file_explorer_get_device_list(explorer)` (pointer to ``Device List`` :ref:`lv_list` Widget) 125 126 127Quick-Access Panel 128------------------ 129 130The ``Quick-Access Panel`` behaves like a typical navigation panel and appears on the 131left, while the ``Browser Panel`` appears on the right 132 133This panel is optional. If you set :c:macro:`LV_FILE_EXPLORER_QUICK_ACCESS` to ``0`` 134in ``lv_conf.h``, the ``Quick-Access Panel`` will not be created. This saves only a 135little bit of memory. 136 137Soon after the File Explorer is created, you typically use 138:cpp:expr:`lv_file_explorer_set_quick_access_path(explorer, LV_EXPLORER_XXX_DIR, "path")` 139to set the path that will be navigated to when the buttons in the ``Quick-Access Panel`` 140are clicked, which is currently a fixed list. The corresponding values you will need 141to pass as the 2nd argument are the following: 142 143- :cpp:enumerator:`LV_EXPLORER_HOME_DIR` 144- :cpp:enumerator:`LV_EXPLORER_MUSIC_DIR` 145- :cpp:enumerator:`LV_EXPLORER_PICTURES_DIR` 146- :cpp:enumerator:`LV_EXPLORER_VIDEO_DIR` 147- :cpp:enumerator:`LV_EXPLORER_DOCS_DIR` 148- :cpp:enumerator:`LV_EXPLORER_FS_DIR` 149 150 151.. _file_explorer_sort: 152 153Sort 154---- 155 156You can use 157:cpp:expr:`lv_file_explorer_set_sort(explorer, LV_EXPLORER_SORT_XX)` to set 158the sorting method. 159 160These are the possible sorting methods: 161 162- :cpp:enumerator:`LV_EXPLORER_SORT_NONE` (default) 163- :cpp:enumerator:`LV_EXPLORER_SORT_KIND` 164 165:cpp:expr:`lv_file_explorer_get_sort(explorer)` returns the current sorting method. 166 167 168 169.. _file_explorer_events: 170 171Events 172****** 173 174- :cpp:enumerator:`LV_EVENT_READY` Sent when a directory is opened, which can happen: 175 176 - when the File Explorer is initially opened, 177 - after a user clicks on a ``Quick-Access Panel`` navigation button, and 178 - after the user clicks on a directory displayed in the ``Browser Panel``. 179 180 You can use it to, for example, customize the file sort. 181 182- :cpp:enumerator:`LV_EVENT_VALUE_CHANGED` Sent once when any item (file) in the 183 ``Brwoser Panel``\ 's file list is clicked. 184 185- :cpp:enumerator:`LV_EVENT_CLICKED` Sent twice when an item in the ``Browser Panel`` 186 is clicked: once as a result of the input-device :cpp:enumerator:`LV_EVENT_RELEASED` 187 event and a second as a result of the input device :cpp:enumerator:`LV_EVENT_CLICKED` 188 event. This applies to files, directories, and the "< Back" item in the ``Browser Panel``. 189 190In these events you can use :cpp:func:`lv_file_explorer_get_current_path` to get the 191current path and :cpp:func:`lv_file_explorer_get_selected_file_name` to get the name 192of the currently selected file in the event processing function. For example: 193 194.. code-block:: c 195 196 static void file_explorer_event_handler(lv_event_t * e) 197 { 198 lv_event_code_t code = lv_event_get_code(e); 199 lv_obj_t * obj = lv_event_get_target(e); 200 201 if(code == LV_EVENT_VALUE_CHANGED) { 202 char * cur_path = lv_file_explorer_get_current_path(widget); 203 char * sel_fn = lv_file_explorer_get_selected_file_name(widget); 204 LV_LOG_USER("%s%s", cur_path, sel_fn); 205 } 206 } 207 208You can also save the obtained **path** and **file** name into an array 209through functions such as :cpp:func:`strcpy` and :cpp:func:`strcat` for later use. 210 211 212 213.. _file_explorer_example: 214 215Example 216******* 217 218.. include:: ../../examples/others/file_explorer/index.rst 219 220 221 222.. _file_explorer_api: 223 224API 225*** 226 227
