acid-drop

- Hacking the planet from a LilyGo T-Deck using custom firmware
git clone git://git.acid.vegas/acid-drop.git
Log | Files | Refs | Archive | README | LICENSE

quick-overview.md (11254B)

      1 ```eval_rst
      2 .. include:: /header.rst
      3 :github_url: |github_link_base|/get-started/quick-overview.md
      4 ```
      5 
      6 # Quick overview
      7 
      8 Here you can learn the most important things about LVGL.
      9 You should read this first to get a general impression and read the detailed [Porting](/porting/index) and [Overview](/overview/index) sections after that.
     10 
     11 ## Get started in a simulator
     12 
     13 Instead of porting LVGL to embedded hardware straight away, it's highly recommended to get started in a simulator first.
     14 
     15 LVGL is ported to many IDEs to be sure you will find your favorite one.
     16 Go to the [Simulators](/get-started/pc-simulator) section to get ready-to-use projects that can be run on your PC.
     17 This way you can save the time of porting for now and get some experience with LVGL immediately.
     18 
     19 ## Add LVGL into your project
     20 If you would rather try LVGL on your own project follow these steps:
     21 
     22 - [Download](https://github.com/lvgl/lvgl/archive/master.zip) or clone the library from GitHub with `git clone https://github.com/lvgl/lvgl.git`.
     23 - Copy the `lvgl` folder into your project.
     24 - Copy `lvgl/lv_conf_template.h` as `lv_conf.h` next to the `lvgl` folder, change the first `#if 0` to `1` to enable the file's content and set the `LV_COLOR_DEPTH` defines.
     25 - Include `lvgl/lvgl.h` in files where you need to use LVGL related functions.
     26 - Call `lv_tick_inc(x)` every `x` milliseconds in a Timer or Task (`x` should be between 1 and 10). It is required for the internal timing of LVGL.
     27 Alternatively, configure `LV_TICK_CUSTOM` (see `lv_conf.h`) so that LVGL can retrieve the current time directly.
     28 - Call `lv_init()`
     29 - Create a draw buffer: LVGL will render the graphics here first, and send the rendered image to the display.
     30 The buffer size can be set freely but 1/10 screen size is a good starting point.
     31 ```c
     32 static lv_disp_draw_buf_t draw_buf;
     33 static lv_color_t buf1[DISP_HOR_RES * DISP_VER_RES / 10];                        /*Declare a buffer for 1/10 screen size*/
     34 lv_disp_draw_buf_init(&draw_buf, buf1, NULL, MY_DISP_HOR_RES * MY_DISP_VER_SER / 10);  /*Initialize the display buffer.*/
     35 ```
     36 - Implement and register a function which can copy the rendered image to an area of your display:
     37 ```c
     38 static lv_disp_drv_t disp_drv;        /*Descriptor of a display driver*/
     39 lv_disp_drv_init(&disp_drv);          /*Basic initialization*/
     40 disp_drv.flush_cb = my_disp_flush;    /*Set your driver function*/
     41 disp_drv.draw_buf = &draw_buf;        /*Assign the buffer to the display*/
     42 disp_drv.hor_res = MY_DISP_HOR_RES;   /*Set the horizontal resolution of the display*/
     43 disp_drv.ver_res = MY_DISP_VER_RES;   /*Set the vertical resolution of the display*/
     44 lv_disp_drv_register(&disp_drv);      /*Finally register the driver*/
     45 
     46 void my_disp_flush(lv_disp_drv_t * disp, const lv_area_t * area, lv_color_t * color_p)
     47 {
     48     int32_t x, y;
     49     /*It's a very slow but simple implementation.
     50      *`set_pixel` needs to be written by you to a set pixel on the screen*/
     51     for(y = area->y1; y <= area->y2; y++) {
     52         for(x = area->x1; x <= area->x2; x++) {
     53             set_pixel(x, y, *color_p);
     54             color_p++;
     55         }
     56     }
     57 
     58     lv_disp_flush_ready(disp);         /* Indicate you are ready with the flushing*/
     59 }
     60 
     61 ```
     62 - Implement and register a function which can read an input device. E.g. for a touchpad:
     63 ```c
     64 static lv_indev_drv_t indev_drv;           /*Descriptor of a input device driver*/
     65 lv_indev_drv_init(&indev_drv);             /*Basic initialization*/
     66 indev_drv.type = LV_INDEV_TYPE_POINTER;    /*Touch pad is a pointer-like device*/
     67 indev_drv.read_cb = my_touchpad_read;      /*Set your driver function*/
     68 lv_indev_drv_register(&indev_drv);         /*Finally register the driver*/
     69 
     70 void my_touchpad_read(lv_indev_t * indev, lv_indev_data_t * data)
     71 {
     72     /*`touchpad_is_pressed` and `touchpad_get_xy` needs to be implemented by you*/
     73     if(touchpad_is_pressed()) {
     74       data->state = LV_INDEV_STATE_PRESSED;
     75       touchpad_get_xy(&data->point.x, &data->point.y);
     76     } else {
     77       data->state = LV_INDEV_STATE_RELEASED;
     78     }
     79 
     80 }
     81 ```
     82 - Call `lv_timer_handler()` periodically every few milliseconds in the main `while(1)` loop or in an operating system task.
     83 It will redraw the screen if required, handle input devices, animation etc.
     84 
     85 For a more detailed guide go to the [Porting](/porting/index) section.
     86 
     87 ## Learn the basics
     88 
     89 ### Widgets
     90 
     91 The graphical elements like Buttons, Labels, Sliders, Charts etc. are called objects or widgets. Go to [Widgets](/widgets/index) to see the full list of available widgets.
     92 
     93 Every object has a parent object where it is created. For example, if a label is created on a button, the button is the parent of label.
     94 
     95 The child object moves with the parent and if the parent is deleted the children will be deleted too.
     96 
     97 Children can be visible only within their parent's bounding area. In other words, the parts of the children outside the parent are clipped.
     98 
     99 A Screen is the "root" parent. You can have any number of screens.
    100 
    101 To get the current screen call `lv_scr_act()`, and to load a screen use `lv_scr_load(scr1)`.
    102 
    103 You can create a new object with `lv_<type>_create(parent)`. It will return an `lv_obj_t *` variable that can be used as a reference to the object to set its parameters.
    104 
    105 For example:
    106 ```c
    107 lv_obj_t * slider1 = lv_slider_create(lv_scr_act());
    108 ```
    109 
    110 To set some basic attributes `lv_obj_set_<parameter_name>(obj, <value>)` functions can be used. For example:
    111 ```c
    112 lv_obj_set_x(btn1, 30);
    113 lv_obj_set_y(btn1, 10);
    114 lv_obj_set_size(btn1, 200, 50);
    115 ```
    116 
    117 Along with the basic attributes, widgets can have type specific parameters which are set by `lv_<widget_type>_set_<parameter_name>(obj, <value>)` functions. For example:
    118 ```c
    119 lv_slider_set_value(slider1, 70, LV_ANIM_ON);
    120 ```
    121 
    122 To see the full API visit the documentation of the widgets or the related header file (e.g. [lvgl/src/widgets/lv_slider.h](https://github.com/lvgl/lvgl/blob/master/src/widgets/lv_slider.h)).
    123 
    124 
    125 
    126 ### Events
    127 Events are used to inform the user that something has happened with an object.
    128 You can assign one or more callbacks to an object which will be called if the object is clicked, released, dragged, being deleted, etc.
    129 
    130 A callback is assigned like this:
    131 
    132 ```c
    133 lv_obj_add_event_cb(btn, btn_event_cb, LV_EVENT_CLICKED, NULL); /*Assign a callback to the button*/
    134 
    135 ...
    136 
    137 void btn_event_cb(lv_event_t * e)
    138 {
    139     printf("Clicked\n");
    140 }
    141 ```
    142 
    143 `LV_EVENT_ALL` can be used instead of `LV_EVENT_CLICKED` to invoke the callback for any event.
    144 
    145 From `lv_event_t * e` the current event code can be retrieved with:
    146 ```c
    147 lv_event_code_t code = lv_event_get_code(e);
    148 ```
    149 
    150 The object that triggered the event can be retrieved with:
    151 ```c
    152 lv_obj_t * obj = lv_event_get_target(e);
    153 ```
    154 
    155 To learn all features of the events go to the [Event overview](/overview/event) section.
    156 
    157 ### Parts
    158 Widgets might be built from one or more *parts*. For example, a button has only one part called `LV_PART_MAIN`.
    159 However, a [Slider](/widgets/core/slider) has `LV_PART_MAIN`, `LV_PART_INDICATOR` and `LV_PART_KNOB`.
    160 
    161 By using parts you can apply different styles to sub-elements of a widget. (See below)
    162 
    163 Read the widgets' documentation to learn which parts each uses.
    164 
    165 ### States
    166 LVGL objects can be in a combination of the following states:
    167 - `LV_STATE_DEFAULT`  Normal, released state
    168 - `LV_STATE_CHECKED`  Toggled or checked state
    169 - `LV_STATE_FOCUSED` Focused via keypad or encoder or clicked via touchpad/mouse
    170 - `LV_STATE_FOCUS_KEY`  Focused via keypad or encoder but not via touchpad/mouse
    171 - `LV_STATE_EDITED` Edit by an encoder
    172 - `LV_STATE_HOVERED` Hovered by mouse (not supported now)
    173 - `LV_STATE_PRESSED` Being pressed
    174 - `LV_STATE_SCROLLED` Being scrolled
    175 - `LV_STATE_DISABLED` Disabled
    176 
    177 For example, if you press an object it will automatically go to the `LV_STATE_FOCUSED` and `LV_STATE_PRESSED` states and when you release it the `LV_STATE_PRESSED` state will be removed while focus remains active.
    178 
    179 To check if an object is in a given state use `lv_obj_has_state(obj, LV_STATE_...)`. It will return `true` if the object is currently in that state.
    180 
    181 To manually add or remove states use:
    182 ```c
    183 lv_obj_add_state(obj, LV_STATE_...);
    184 lv_obj_clear_state(obj, LV_STATE_...);
    185 ```
    186 
    187 ### Styles
    188 A style instance contains properties such as background color, border width, font, etc. that describe the appearance of objects.
    189 
    190 Styles are represented with `lv_style_t` variables. Only their pointer is saved in the objects so they need to be defined as static or global.
    191 Before using a style it needs to be initialized with `lv_style_init(&style1)`. After that, properties can be added to configure the style. For example:
    192 ```
    193 static lv_style_t style1;
    194 lv_style_init(&style1);
    195 lv_style_set_bg_color(&style1, lv_color_hex(0xa03080))
    196 lv_style_set_border_width(&style1, 2))
    197 ```
    198 See the full list of properties [here](/overview/style.html#properties).
    199 
    200 
    201 Styles are assigned using the ORed combination of an object's part and state. For example to use this style on the slider's indicator when the slider is pressed:
    202 ```c
    203 lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR | LV_STATE_PRESSED);
    204 ```
    205 
    206 If the *part* is `LV_PART_MAIN` it can be omitted:
    207 ```c
    208 lv_obj_add_style(btn1, &style1, LV_STATE_PRESSED); /*Equal to LV_PART_MAIN | LV_STATE_PRESSED*/
    209 ```
    210 
    211 Similarly, `LV_STATE_DEFAULT` can be omitted too:
    212 ```c
    213 lv_obj_add_style(slider1, &style1, LV_PART_INDICATOR); /*Equal to LV_PART_INDICATOR | LV_STATE_DEFAULT*/
    214 ```
    215 
    216 For `LV_STATE_DEFAULT` and `LV_PART_MAIN` simply write `0`:
    217 ```c
    218 lv_obj_add_style(btn1, &style1, 0); /*Equal to LV_PART_MAIN | LV_STATE_DEFAULT*/
    219 ```
    220 
    221 
    222 Styles can be cascaded (similarly to CSS). It means you can add more styles to a part of an object.
    223 For example `style_btn` can set a default button appearance, and `style_btn_red` can overwrite the background color to make the button red:
    224 ```c
    225 lv_obj_add_style(btn1, &style_btn, 0);
    226 lv_obj_add_style(btn1, &style1_btn_red, 0);
    227 ```
    228 
    229 
    230 If a property is not set on for the current state, the style with `LV_STATE_DEFAULT` will be used. A default value is used if the property is not defined in the default state.
    231 
    232 Some properties (typically the text-related ones) can be inherited. This means if a property is not set in an object it will be searched for in its parents too.
    233 For example, you can set the font once in the screen's style and all text on that screen will inherit it by default.
    234 
    235 
    236 Local style properties also can be added to objects. This creates a style which resides inside the object and is used only by the object:
    237 ```c
    238 lv_obj_set_style_bg_color(slider1, lv_color_hex(0x2080bb), LV_PART_INDICATOR | LV_STATE_PRESSED);
    239 ```
    240 
    241 To learn all the features of styles see the [Style overview](/overview/style) section.
    242 
    243 
    244 ### Themes
    245 
    246 Themes are the default styles for objects. Styles from a theme are applied automatically when objects are created.
    247 
    248 The theme for your application is a compile time configuration set in `lv_conf.h`.
    249 
    250 ## Examples
    251 
    252 ```eval_rst
    253 
    254 .. include:: ../../examples/get_started/index.rst
    255 ```
    256 
    257 ## Micropython
    258 Learn more about [Micropython](/get-started/micropython).
    259 ```python
    260 # Create a Button and a Label
    261 scr = lv.obj()
    262 btn = lv.btn(scr)
    263 btn.align(lv.scr_act(), lv.ALIGN.CENTER, 0, 0)
    264 label = lv.label(btn)
    265 label.set_text("Button")
    266 
    267 # Load the screen
    268 lv.scr_load(scr)
    269 ```
    270