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