14.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 recursively 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.