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