summaryrefslogtreecommitdiff
path: root/lib/lvgl/docs/others/gridnav.md
diff options
context:
space:
mode:
Diffstat (limited to 'lib/lvgl/docs/others/gridnav.md')
m---------lib/lvgl0
-rw-r--r--lib/lvgl/docs/others/gridnav.md56
2 files changed, 56 insertions, 0 deletions
diff --git a/lib/lvgl b/lib/lvgl
deleted file mode 160000
-Subproject 0732400e7b564dd0e7dc4a924619d8e19c5b23a
diff --git a/lib/lvgl/docs/others/gridnav.md b/lib/lvgl/docs/others/gridnav.md
new file mode 100644
index 00000000..1e863d45
--- /dev/null
+++ b/lib/lvgl/docs/others/gridnav.md
@@ -0,0 +1,56 @@
+# Grid navigation
+
+Grid navigation (gridnav for short) is a feature that changes the currently focused child object as arrow keys are pressed.
+
+If the children are arranged into a grid-like layout then the up, down, left and right arrows move focus to the nearest sibling
+in the respective direction.
+
+It doesn't matter how the children are positioned, as only the current x and y coordinates are considered.
+This means that gridnav works with manually positioned children, as well as [Flex](/layouts/flex) and [Grid](/layouts/grid) layouts.
+
+Gridnav also works if the children are arranged into a single row or column.
+That makes it useful, for example, to simplify navigation on a [List widget](/widgets/extra/list).
+
+Gridnav assumes that the object to which gridnav is added is part of a [group](/overview/indev.html#groups).
+This way, if the object with gridnav is focused, the arrow key presses are automatically forwarded to the object
+so that gridnav can process the arrow keys.
+
+To move the focus to the next widget of the group use `LV_KEY_NEXT/PREV` or `lv_group_focus_next/prev()` or the `TAB` key on keyboard as usual.
+
+If the container is scrollable and the focused child is out of the view, gridnav will automatically scroll the child into view.
+
+## Usage
+
+To add the gridnav feature to an object use `lv_gridnav_add(cont, flags)`.
+
+`flags` control the behavior of gridnav:
+- `LV_GRIDNAV_CTRL_NONE` Default settings
+- `LV_GRIDNAV_CTRL_ROLLOVER` If there is no next/previous object in a direction,
+the focus goes to the object in the next/previous row (on left/right keys) or first/last row (on up/down keys
+- `LV_GRIDNAV_CTRL_SCROLL_FIRST` If an arrow is pressed and the focused object can be scrolled in that direction
+then it will be scrolled instead of going to the next/previous object. If there is no more room for scrolling the next/previous object will be focused normally
+
+`lv_gridnav_remove(cont)` Removes gridnav from an object.
+
+## Focusable objects
+
+An object needs to be clickable or click focusable (`LV_OBJ_FLAG_CLICKABLE` or `LV_OBJ_FLAG_CLICK_FOCUSABLE`)
+and not hidden (`LV_OBJ_FLAG_HIDDEN`) to be focusable by gridnav.
+
+
+## Example
+
+```eval_rst
+
+.. include:: ../../examples/others/gridnav/index.rst
+
+```
+## API
+
+
+```eval_rst
+
+.. doxygenfile:: lv_gridnav.h
+ :project: lvgl
+
+```