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