Chapter 18. Decomposition of GUI, loading an XML file
Loading multiple XML files in a single panel
loadGui = "[String]script, [boolean] update" [String] is the script to call, returning an XML-GUI file [boolean] a true or false terminal string. Used
One of the strengths of Bambookit GUI is the ability to decompose an application view into
multiple XML documents. These documents will be loaded as needed, also these XML documents can be
easily re-used in other applications.
Let's load a static xml file into a panel
Now let us assume in the previous example, '1.xml' is replaced with a script.
This script will dynamically generate the required XML document. Since this script
is dynamically generated a small change is made to the main widget.
We set caching to false (the default is true). This way we would be able to load
the XML-GUI panels dynamically.
Now referred to as 1.php (so the webserver will process the scripts first).
It fetches the time from the script setting the label of the button.
All panels by default cache their views. Even if you load (loadGui) a dynamic script, the name of the script is noted and compared, if it has already called this scripts (the name matches), the cached view will be used instead. For dynamic scripts the panel that does the loading needs to add the additional flag, setCache="false" (the default setting is setCache="true").
Updating the XML GUI file.
This is set by loadGui="somefile.script,true"
What happens when setting the update flag to true in the loadGui method?
The 'true' flag instructs the parser to find a 'matching' widget name in the panel it is loading to and ONLY update
the attributes in the XML GUI script that it is loading (no new objects are created).
If the update flag is false the panel that is loading the new GUI file is cleared of all children before
the parser begins adding/creating new children nodes in the panel.
If the update flag is true, the panel is NOT cleared of its children and, as each widget is parsed, the name is matched
with the existing widget and the attributes are modified.
Tip: The match that the parser makes can apply to ANY widget with the same name in the applet,
not just the children of the panel that is bieng loaded.
Tip: For an XML GUI script that is an update, it is important that the first attribute defined
after the element tag is the setName attribute so the parser can match the object to the existing list of widgets on file
as soon as possible.
All attributes that are defined BEFORE the setName attribute is ignored
Here are an example of this functionality. We use a button to fetch the time from the server.
We present two examples.
the 'gettime' widget is a child widget of 'panel'
Since the 'gettime' widget is a child of the loading panel, the whole panel is disabled until the script finishes
its download. Since the parent gets disabled so does 'gettime' widget.
the 'gettime' widget is NOT a child widget of 'panel'
In this example the widget 'gettime' is NOT a child of the loading panel, however it gets updated. Why? because the
widget lookup is done purely based on the name on NOT on the hierachy of the widget controls. This means that
care needs to be taken not to 'name' two widgets the same. Since doing so will result in an undefined behaviour.
The above examples and tutorials have been simplified to demonstrate the few key attributes of the loadGui
mechanism, how it can be used, and how it caches views and their affect on dynamically created scripts.