diff --git a/docs/widgets/btn.md b/docs/widgets/btn.md index 9acbd6320..7fb0ef978 100644 --- a/docs/widgets/btn.md +++ b/docs/widgets/btn.md @@ -6,60 +6,28 @@ ## Overview -Buttons are simple rectangle-like objects. They are derived from [Containers](/widgets/cont) so [layout](/widgets/cont#layout) and [fit](/widgets/cont#fit) are also available. -Besides, it can be enabled to automatically go to checked state on click. +Buttons has no new features compared to the [Base object](/widgets/obj). It usufule for semantic purposes and has slightly different default settings. +Buttons differ from Base object in the following points by default: +- Not scrollable +- Added to the default group +- Its default height and width is `LV_SIZE_CONTENT` ## Parts and Styles -The buttons has only a main style called `LV_BTN_PART_MAIN` and it can use all the properties from the following groups: -- background -- border -- outline -- shadow -- value -- pattern -- transitions - -It also uses the *padding* properties when *layout* or *fit* is enabled. +- `LV_PART_MAIN` The background of the button. It uses the typical background style properties. ## Usage -### States -To make buttons usage simpler the button's state can be get with `lv_btn_get_state(btn)`. It returns one of the following values: -- **LV_BTN_STATE_RELEASED** -- **LV_BTN_STATE_PRESSED** -- **LV_BTN_STATE_CHECKED_RELEASED** -- **LV_BTN_STATE_CHECKED_PRESSED** -- **LV_BTN_STATE_DISABLED** -- **LV_BTN_STATE_CHECKED_DISABLED** - -With `lv_btn_set_state(btn, LV_BTN_STATE_...)` the buttons state can be changed manually. - -If a more precise description of the state is required (e.g. focused) the general `lv_obj_get_state(btn)` can be used. - - -### Checkable -You can configure the buttons as *toggle button* with `lv_btn_set_checkable(btn, true)`. In this case, on click, the button goes to `LV_STATE_CHECKED` state automatically, or back when clicked again. - - -### Layout and Fit -Similarly to [Containers](/widgets/cont), buttons also have layout and fit attributes. -- `lv_btn_set_layout(btn, LV_LAYOUT_...) `set a layout. The default is `LV_LAYOUT_CENTER`. -So, if you add a label, then it will be automatically aligned to the middle and can't be moved with `lv_obj_set_pos()`. -You can disable the layout with `lv_btn_set_layout(btn, LV_LAYOUT_OFF)`. -- `lv_btn_set_fit/fit2/fit4(btn, LV_FIT_..)` enables to set the button width and/or height automatically according to the children, parent, and fit type. - +There are no new features compared to [Base object](/widgets/obj). ## Events -Besides the [Generic events](../overview/event.html#generic-events) the following [Special events](../overview/event.html#special-events) are sent by the buttons: - - **LV_EVENT_VALUE_CHANGED** - sent when the button is toggled. +- `LV_EVENT_VALUE_CHANGED` when the `LV_OBJ_FLAG_CHECKABLE` flag is enabled and the obejct clicked (on transition to/from the checked state) + Learn more about [Events](/overview/event). ## Keys -The following *Keys* are processed by the Buttons: -- **LV_KEY_RIGHT/UP** - Go to toggled state if toggling is enabled. -- **LV_KEY_LEFT/DOWN** - Go to non-toggled state if toggling is enabled. +If `LV_OBJ_FLAG_CHECKABLE` is enabled `LV_KEY_RIGHT` and `LV_KEY_UP` makes the object checked, and `LV_KEY_LEFT` and `LV_KEY_DOWN` makes it unchecked. Note that, the state of `LV_KEY_ENTER` is translated to `LV_EVENT_PRESSED/PRESSING/RELEASED` etc. diff --git a/docs/widgets/btnmatrix.md b/docs/widgets/btnmatrix.md index ca2c9eed0..594e340ce 100644 --- a/docs/widgets/btnmatrix.md +++ b/docs/widgets/btnmatrix.md @@ -6,82 +6,75 @@ ## Overview -The Button Matrix objects can display **multiple buttons** in rows and columns. +The Button Matrix objects can display multiple buttons in rows and columns. -The main reasons for wanting to use a button matrix instead of a container and individual button objects are: -- The button matrix is simpler to use for grid-based button layouts. -- The button matrix consumes a lot less memory per button. +The Button matrix object is very light weighted because the buttons are not created just virtually drawn on the fly. +This way, 1 button use only 8 extra bytes instead of the ~100-150 byte size of a normal [Button](/widgets/btn) object and other ~100 byte for the size of the [Label](/widgets/label) object. +The Button matrix is added to the deafult group (if it is set). Besides the Button matrix is an editable object to allow selecting and clicing the buttons with encoder navigation too. ## Parts and Styles -The Button matrix's main part is called `LV_BTNMATRIX_PART_BG`. It draws a background using the typical background style properties. - -`LV_BTNMATRIX_PART_BTN` is virtual part and it refers to the buttons on the button matrix. It also uses all the typical background properties. - -The top/bottom/left/right padding values from the background are used to keep some space on the sides. Inner padding is applied between the buttons. +- `LV_PART_MAIN` The bacground of the button matrix. It uses the typical background style properties. `pad_row` and `pad_column` sets the space between the buttons. +- `LV_PART_ITEMS` The buttons and they all use the text and typical background style properties expect translations and transformations. ## Usage ### Button's text There is a text on each button. To specify them a descriptor string array, called *map*, needs to be used. The map can be set with `lv_btnmatrix_set_map(btnm, my_map)`. -The declaration of a map should look like `const char * map[] = {"btn1", "btn2", "btn3", ""}`. -Note that **the last element has to be an empty string**! +The declaration of a map should look like `const char * map[] = {"btn1", "btn2", "btn3", NULL}`. +Note that, the last element has to be `NULL` or an empty string (`""`)! Use `"\n"` in the map to make **line break**. E.g. `{"btn1", "btn2", "\n", "btn3", ""}`. Each line's buttons have their width calculated automatically. +So in the example the first row will have 2 buttons each with 50% width and a second row with 1 button having 100% width. ### Control buttons -The **buttons width** can be set relative to the other button in the same line with `lv_btnmatrix_set_btn_width(btnm, btn_id, width)` +The buttons' width can be set relative to the other button in the same row with `lv_btnmatrix_set_btn_width(btnm, btn_id, width)` E.g. in a line with two buttons: *btnA, width = 1* and *btnB, width = 2*, *btnA* will have 33 % width and *btnB* will have 66 % width. It's similar to how the [`flex-grow`](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow) property works in CSS. +The width's value mus be in the \[1..7\] range and the deafult width is 1. -In addition to width, each button can be customized with the following parameters: -- **LV_BTNMATRIX_CTRL_HIDDEN** - make a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable) -- **LV_BTNMATRIX_CTRL_NO_REPEAT** - disable repeating when the button is long pressed -- **LV_BTNMATRIX_CTRL_DISABLED** - make a button disabled -- **LV_BTNMATRIX_CTRL_CHECKABLE** - enable toggling of a button -- **LV_BTNMATRIX_CTRL_CHECK_STATE** - set the toggle state -- **LV_BTNMATRIX_CTRL_CLICK_TRIG** - if 0, the button will react on press, if 1, will react on release +In addition to the width, each button can be customized with the following parameters: +- `LV_BTNMATRIX_CTRL_HIDDEN` Makes a button hidden (hidden buttons still take up space in the layout, they are just not visible or clickable) +- `LV_BTNMATRIX_CTRL_NO_REPEAT` Disable repeating when the button is long pressed +- `LV_BTNMATRIX_CTRL_DISABLED` Makes a button disabled Like `LV_STATE_DISABLED` on normal objects +- `LV_BTNMATRIX_CTRL_CHECKABLE` Enable toggling of a button. I.e. `LV_STATE_CHECHED` will be added/removed as the button is clicked +- `LV_BTNMATRIX_CTRL_CHECKED` MAke the button checked. It will use the `LV_STATE_CHECHKED` styles. +- `LV_BTNMATRIX_CTRL_CLICK_TRIG` Enabled: send LV_EVENT_VALUE_CHANGE on CLICK, Disabled: send LV_EVENT_VALUE_CHANGE on PRESS*/ +- `LV_BTNMATRIX_CTRL_RECOLOR` Enable recoloring of button texts with `#`. E.g. `"It's #ff0000 red#"` +- `LV_BTNMATRIX_CTRL_CUSTOM_1` Custom free to use flag +- `LV_BTNMATRIX_CTRL_CUSTOM_2` Custom free to use flag -The set or clear a button's control attribute, use `lv_btnmatrix_set_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_...)` and -`lv_btnmatrix_clear_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_...)` respectively. More `LV_BTNM_CTRL_...` values can be *Or*ed +By deafult all flags are disabled. -The set/clear the same control attribute for all buttons of a button matrix, use `lv_btnmatrix_set_btn_ctrl_all(btnm, btn_id, LV_BTNM_CTRL_...)` and -`lv_btnmatrix_clear_btn_ctrl_all(btnm, btn_id, LV_BTNM_CTRL_...)`. +To set or clear a button's control attribute, use `lv_btnmatrix_set_btn_ctrl(btnm, btn_id, LV_BTNM_CTRL_...)` and +`lv_btnmatrix_clear_btn_ctrl(btnm, btn_id, LV_BTNMATRIX_CTRL_...)` respectively. More `LV_BTNM_CTRL_...` values can be OR-ed + +To set/clear the same control attribute for all buttons of a button matrix, use `lv_btnmatrix_set_btn_ctrl_all(btnm, btn_id, LV_BTNM_CTRL_...)` and +`lv_btnmatrix_clear_btn_ctrl_all(btnm, btn_id, LV_BTNMATRIX_CTRL_...)`. The set a control map for a button matrix (similarly to the map for the text), use `lv_btnmatrix_set_ctrl_map(btnm, ctrl_map)`. -An element of `ctrl_map` should look like `ctrl_map[0] = width | LV_BTNM_CTRL_NO_REPEAT | LV_BTNM_CTRL_TGL_ENABLE`. +An element of `ctrl_map` should look like `ctrl_map[0] = width | LV_BTNM_CTRL_NO_REPEAT | LV_BTNM_CTRL_CHECHKABLE`. The number of elements should be equal to the number of buttons (excluding newlines characters). ### One check -The "One check" feature can be enabled with `lv_btnmatrix_set_one_check(btnm, true)` to allow only one button to be checked (toggled) at once. - -### Recolor -The **texts** on the button can be **recolored** similarly to the recolor feature for [Label](/widgets/label) object. To enable it, use `lv_btnmatrix_set_recolor(btnm, true)`. -After that a button with `#FF0000 Red#` text will be red. - -### Aligning the button's text -To align the text on the buttons, use `lv_btnmatrix_set_align(roller, LV_LABEL_ALIGN_LEFT/CENTER/RIGHT)`. -All text items in the button matrix will conform to the alignment proprty as it is set. - -### Notes -The Button matrix object is very light weighted because the buttons are not created just virtually drawn on the fly. -This way, 1 button use only 8 extra bytes instead of the ~100-150 byte size of a normal [Button](/widgets/btn) object (plus the size of its container and a label for each button). - -The disadvantage of this setup is that the ability to style individual buttons to be different from others is limited (aside from the toggling feature). -If you require that ability, using individual buttons is very likely to be a better approach. +The "One check" feature can be enabled with `lv_btnmatrix_set_one_check(btnm, true)` to allow only one button to be checked at once. ## Events -Besides the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the button matrices: - - **LV_EVENT_VALUE_CHANGED** - sent when the button is pressed/released or repeated after long press. The event data is set to the ID of the pressed/released button. +- `LV_EVENT_VALUE_CHANGED` Sent when a button is pressed/released or repeated after long press. The event paramter is set to the ID of the pressed/released button. +- `LV_EVENT_DRAW_PART_BEGIN` and `LV_EVENT_DRAW_PART_END` are sent for both the main and the items (buttons) parts to allow hooking the drawing. +The for more detail on the main part see the [Base object](/widgets/obj#events)'s documentation. +For the buttons the following fields are used: `clip_area`, `draw_area`, `rect_dsc`, `rect_dsc`, `part`, `id` (index of the button being drawn). + +`lv_btnmatrix_get_selected_btn(btnm)` returns the index of the lastly pressed, released or focused button or `LV_BTNMATRIX_BTN_NONE` if no such button. + +`lv_btnmatrix_get_btn_text(btnm, btn_id)` returns a pointer to the text of `btn_id`th button. Learn more about [Events](/overview/event). ## Keys - -The following *Keys* are processed by the Buttons: -- **LV_KEY_RIGHT/UP/LEFT/RIGHT** - To navigate among the buttons to select one -- **LV_KEY_ENTER** - To press/release the selected button +- `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons to select one +- `LV_KEY_ENTER` To press/release the selected button Learn more about [Keys](/overview/indev). diff --git a/docs/widgets/calendar.md b/docs/widgets/calendar.md index e14cb0f39..97c905b22 100644 --- a/docs/widgets/calendar.md +++ b/docs/widgets/calendar.md @@ -7,63 +7,61 @@ ## Overview The Calendar object is a classic calendar which can: +- can show the days of any month in a 7x7 matrix +- Show the name of the days - highlight the current day - highlight any user-defined dates -- display the name of the days -- go the next/previous month by button click -- highlight the clicked day +The Calendar is added to the deafult group (if it is set). Besides the Calendar is an editable object to allow selecting and clicing the dates with encoder navigation too. + +To make the Calendar flexible, by default it doesn't show the curent year or month. Instead, there external "headers" that can be attached to the calendar. ## Parts and Styles -The calendar's main part is called `LV_CALENDAR_PART_BG`. It draws a background using the typical background style properties. - -Besides the following virtual parts exist: -- `LV_CALENDAR_PART_HEADER` The upper area where the current year and month's name is shown. It also has buttons to move the next/previous month. -It uses typical background properties plus padding to adjust its size and margin to set the distance from the top of the calendar and the day names below it. -- `LV_CALENDAR_PART_DAY_NAMES` Shows the name of the days below the header. It uses the *text* style properties padding to keep some distance from the background (left, right), header (top) and dates (bottom). -- `LV_CALENDAR_PART_DATES` Show the date numbers from 1..28/29/30/31 (depending on current month). Different "state" of the states are drawn according to the states defined in this part: - - normal dates: drawn with `LV_STATE_DEFAULT` style - - pressed date: drawn with `LV_STATE_PRESSED` style - - today: drawn with `LV_STATE_FOCUSED` style - - highlighted dates: drawn with `LV_STATE_CHECKED` style - +The calendar object uses the [Button matrix](/widgets/btnmatrix) object under the hood to arrange the days into a matrix. +- `LV_PART_MAIN` +- `LV_PART_ITEMS` Refers to the dates and day names. Button matrix control flags are set the to differentiate the buttons and a custom drawer event modifies the properties of the buttons + - day names haev no border, no background, drawn with a grey color + - days of the previous and next month have `LV_BTNMATRIX_CTRL_DISABLED` flag + - today has a ticker border with the themes primary color + - highlighted day have 40% opacity with the themes primary color. ## Usage - -## Overview - -To set and get dates in the calendar, the `lv_calendar_date_t` type is used which is a structure with `year`, `month` and `day` fields. - +Some funnctions uses the `lv_calendar_date_t` type is used which is a structure with `year`, `month` and `day` fields. ### Current date -To set the current date (today), use the `lv_calendar_set_today_date(calendar, &today_date)` function. +To set the current date (today), use the `lv_calendar_set_today_date(calendar, year, month, day)` function. `month` needs to be in 1..12 range and `day` in 1..31 range ### Shown date -To set the shown date, use `lv_calendar_set_shown_date(calendar, &shown_date)`; +To set the shown date, use `lv_calendar_set_shown_date(calendar, year, month)`; ### Highlighted days -The list of highlighted dates should be stored in a `lv_calendar_date_t` array loaded by `lv_calendar_set_highlighted_dates(calendar, &highlighted_dates)`. + +The list of highlighted dates should be stored in a `lv_calendar_date_t` array loaded by `lv_calendar_set_highlighted_dates(calendar, highlighted_dates, date_num)`. Only the arrays pointer will be saved so the array should be a static or global variable. ### Name of the days The name of the days can be adjusted with `lv_calendar_set_day_names(calendar, day_names)` where `day_names` looks like `const char * day_names[7] = {"Su", "Mo", ...};` +Only the pointer of the day names is saved so the array should be a static, global or constant variables. -### Name of the months -Similarly to `day_names`, the name of the month can be set with `lv_calendar_set_month_names(calendar, month_names_array)`. +## Headers +### Arrow buttons + +`lv_calendar_header_arrow_create(parent, calendar, button_size)` creates a header that contains a left and right arrow on the sides and atext with the current year and month between them. + +### Dropdown +`lv_calendar_header_dropdown_create(parent, calendar)` creates a header that contains 2 drop-drown lists: one for the year and an other for the month. + ## Events -Besides the [Generic events](../overview/event.html#generic-events), the following [Special events](../overview/event.html#special-events) are sent by the calendars: -**LV_EVENT_VALUE_CHANGED** is sent when the current month has changed. - -In *Input device related* events, `lv_calendar_get_pressed_date(calendar)` tells which day is currently being pressed or return `NULL` if no date is pressed. +- `LV_EVENT_VALUE_CHANGED` Sent is a data is clicked. `lv_calendar_get_pressed_date(calendar, &date)` tells which day is currently being pressed. Returns `LV_RES_OK` if theres is valid pressed data, else `LV_RES_INV`. ## Keys -No *Keys* are processed by the object type. +- `LV_KEY_RIGHT/UP/LEFT/RIGHT` To navigate among the buttons to dates +- `LV_KEY_ENTER` To press/release the selected date Learn more about [Keys](/overview/indev). - ## Example ```eval_rst diff --git a/docs/widgets/cont.md b/docs/widgets/cont.md deleted file mode 100644 index 27b43110b..000000000 --- a/docs/widgets/cont.md +++ /dev/null @@ -1,72 +0,0 @@ -```eval_rst -.. include:: /header.rst -:github_url: |github_link_base|/widgets/cont.md -``` -# Container (lv_cont) - -## Overview - -The containers are essentially a **basic object** with layout and automatic sizing features features. - - -## Parts and Styles -The containers has only a main style called `LV_CONT_PART_MAIN` and it can use all the typicaly bacground properties properties and padding for layout auto sizing. - -## Usage - - -### Layout -You can apply a layout on the containers to automatically order their children. The layout spacing comes from the style's `pad` properties. The possible layout options: - -- **LV_LAYOUT_OFF** - Do not align the children. -- **LV_LAYOUT_CENTER** - Align children to the center in column and keep `pad_inner` space between them. -- **LV_LAYOUT_COLUMN_LEFT** - Align children in a left-justified column. Keep `pad_left` space on the left, `pad_top` space on the top and `pad_inner` space between the children. -- **LV_LAYOUT_COLUMN_MID** - Align children in centered column. Keep `pad_top` space on the top and `pad_inner` space between the children. -- **LV_LAYOUT_COLUMN_RIGHT** - Align children in a right-justified column. Keep `pad_right` space on the right, `pad_top` space on the top and `pad_inner` space between the children. -- **LV_LAYOUT_ROW_TOP** - Align children in a top justified row. Keep `pad_left` space on the left, `pad_top` space on the top and `pad_inner` space between the children. -- **LV_LAYOUT_ROW_MID** - Align children in centered row. Keep `pad_left` space on the left and `pad_inner` space between the children. -- **LV_LAYOUT_ROW_BOTTOM** - Align children in a bottom justified row. Keep `pad_left` space on the left, `pad_bottom` space on the bottom and `pad_inner` space between the children. -- **LV_LAYOUT_PRETTY_TOP** - Put as many objects as possible in a row (with at least `pad_inner` space and `pad_left/right` space on the sides). Divide the space in each line equally between the children. -If here are children with different height in a row align their top edge. -- **LV_LAYOUT_PRETTY_MID** - Same as `LV_LAYOUT_PRETTY_TOP` but if here are children with different height in a row align their middle line. -- **LV_LAYOUT_PRETTY_BOTTOM** - Same as `LV_LAYOUT_PRETTY_TOP` but if here are children with different height in a row align their bottom line. -- **LV_LAYOUT_GRID** - Similar to `LV_LAYOUT_PRETTY` but not divide horizontal space equally just let `pad_left/right` on the edges and `pad_inner` space between the elements. - -### Autofit -Container have an autofit feature which can automatically change the size of the container according to its children and/or its parent. The following options exist: -- **LV_FIT_NONE** - Do not change the size automatically. -- **LV_FIT_TIGHT** - Shrink-wrap the container around all of its children, while keeping `pad_top/bottom/left/right` space on the edges. -- **LV_FIT_PARENT** - Set the size to the parent's size minus `pad_top/bottom/left/right` (from the parent's style) space. -- **LV_FIT_MAX** - Use `LV_FIT_PARENT` while smaller than the parent and `LV_FIT_TIGHT` when larger. It will ensure that the container is, at minimum, the size of its parent. - -To set the auto fit mode for all directions, use `lv_cont_set_fit(cont, LV_FIT_...)`. -To use different auto fit horizontally and vertically, use `lv_cont_set_fit2(cont, hor_fit_type, ver_fit_type)`. -To use different auto fit in all 4 directions, use `lv_cont_set_fit4(cont, left_fit_type, right_fit_type, top_fit_type, bottom_fit_type)`. - -## Events -Only the [Generic events](../overview/event.html#generic-events) are sent by the object type. - -Learn more about [Events](/overview/event). - -## Keys -No *Keys* are processed by the object type. - -Learn more about [Keys](/overview/indev). - - -## Example - -```eval_rst - -.. include:: /lv_examples/src/lv_ex_widgets/lv_ex_cont/index.rst - -``` - -## API - -```eval_rst - -.. doxygenfile:: lv_cont.h - :project: lvgl - -``` diff --git a/docs/widgets/obj.md b/docs/widgets/obj.md index 7b30136cf..1b0254f55 100644 --- a/docs/widgets/obj.md +++ b/docs/widgets/obj.md @@ -147,13 +147,12 @@ Once, an object is added to *group* with `lv_group_add_obj(group, obj)` the obje By default, the objects can be clicked only on their coordinates, however, this area can be extended with `lv_obj_set_ext_click_area(obj, size)`. ## Events -Besides the following special event(s) are sent by the base object: - `LV_EVENT_VALUE_CHANGED` when the `LV_OBJ_FLAG_CHECKABLE` flag is enabled and the obejct clicked (on transition to/from the checked state) Learn more about [Events](/overview/event). ## Keys -If `LV_OBJ_FLAG_CHECKABLE` is enabled `LV_KEY_RIGHT` and `LV_KEY_UP` makes the object checked, and `LV_KEY_LEFT` and `LV_KEY_DOWN` makes i unchcked. +If `LV_OBJ_FLAG_CHECKABLE` is enabled `LV_KEY_RIGHT` and `LV_KEY_UP` makes the object checked, and `LV_KEY_LEFT` and `LV_KEY_DOWN` makes it unchecked. Learn more about [Keys](/overview/indev).