grub-dev: GUI Components
12.3 GUI Components
===================
The graphical menu implements a GUI component system that supports a
container-based layout system. Components can be added to containers,
and containers (which are a type of component) can then be added to
other containers, to form a tree of components. Currently, the root
component of this tree is a 'canvas' component, which allows manual
layout of its child components.
Components (non-container):
* label
* image
* progress_bar
* circular_progress
* list (currently hard coded to be a boot menu list)
Containers:
* canvas
* hbox
* vbox
The GUI component instances are created by the theme loader in
'gfxmenu/theme_loader.c' when a theme is loaded. Theme files specify
statements such as '+vbox{ +label { text="Hello" } +label{ text="World"
} }' to add components to the component tree root. By nesting the
component creation statements in the theme file, the instantiated
components are nested the same way.
When a component is added to a container, that new child is
considered *owned* by the container. Great care should be taken if the
caller retains a reference to the child component, since it will be
destroyed if its parent container is destroyed. A better choice instead
of storing a pointer to the child component is to use the component ID
to find the desired component. Component IDs do not have to be unique
(it is often useful to have multiple components with an ID of
"__timeout__", for instance).
In order to access and use components in the component tree, there
are two functions (defined in 'gfxmenu/gui_util.c') that are
particularly useful:
* 'grub_gui_find_by_id (root, id, callback, userdata)':
This function ecursively traverses the component tree rooted at
ROOT, and for every component that has an ID equal to ID, calls the
function pointed to by CALLBACK with the matching component and the
void pointer USERDATA as arguments. The callback function can do
whatever is desired to use the component passed in.
* 'grub_gui_iterate_recursively (root, callback, userdata)':
This function calls the function pointed to by CALLBACK for every
component that is a descendant of ROOT in the component tree. When
the callback function is called, the component and the void pointer
USERDATA as arguments. The callback function can do whatever is
desired to use the component passed in.
Info Catalog
grub-dev: Startup Sequence
grub-dev: Graphical Menu Software Design
grub-dev: Command Line Window