Hello.
First of all, I'd like to apologize for not making more than 2 tutorials, though that was more than one and half year ago. My focus shifted from one project to another, and making GUIs was suddenly far away in the future again.
This time I find myself in a slightly different position, but the goal is still to make a small GUI. TWL is pretty easy to get on a high level; You define themes in XML, load a theme XML file and all the Widgets you make look as they should. Actually doing this is a whole different story though.
First of all, the
documentation for the theme file format is excellent. It shows just how simple it is to define everything the way you want, without being overly complicated. So you open up simple.xml and simple.png from the examples, and see the first few 40 or so lines of it and it's very easy to see the connection between the XML file and the image file. Then things turn insane.
Code:
<alias name="frame.resizeIcon" ref="-iconC"/>
So this line sets the resize icon of a frame. What's a frame? What does the resize icon do? Maximize? Minimize? Allow you to resize a "frame" in some way?
Code:
<composed name="frame.resizeable-title" border="25,5,5,5">
<alias ref="-borderA"/>
<grid weightsX="0,1,0" weightsY="0,1" inset="4">
<alias ref="none"/>
<select sizeOverwriteV="18">
<alias ref="-gradA" if="keyboardFocus | hasOpenPopups"/>
<alias ref="-gradB"/>
</select>
<alias ref="none"/>
<alias ref="none"/>
<alias ref="none"/>
<alias ref="none"/>
</grid>
</composed>
Why the name "frame.resizeable-title"? Oh, "keyboardFocus" and "hasOpenPopups" were keywords you could use for if="" statements. I wonder what other ones there are. Sadly I can't find a list of them.
The following are things I don't understand from simple.xml:
- What is allowWildcard? The theme format description just describes it as "wildcard child theme resolution".
- What are the possible strings for if="..."? The possible values seem to be dependent on what you're working on (a font, a widget, e.t.c).
Code:
<fontDef name="combobox" filename="font.fnt" color="black">
<fontParam if="comboboxKeyboardFocus" color="white"/>
</fontDef>
It's completely impossible to figure out that "comboboxKeyboardFocus" was a valid value without a tutorial or even some kind of documentation.
- Available action names for inputMapDefs?
- Not even half of these param names are in the theme file format description.
Code:
<theme name="-defaults">
<param name="background"><image>none</image></param>
<param name="overlay"><image>none</image></param>
<param name="font"><font>normal</font></param>
<param name="textAlignment"><enum type="alignment">left</enum></param>
<param name="minWidth"><int>0</int></param>
<param name="minHeight"><int>0</int></param>
<param name="maxWidth"><int>0</int></param>
<param name="maxHeight"><int>0</int></param>
<param name="inputMap"><inputMap>-defaultInputMap</inputMap></param>
<!--
a wildcard import in the base theme allows to use
any top level theme which has allowWildcard="true"
as child theme in any other theme (unless overriden).
-->
<theme name="" ref="*"/>
</theme>
The one most puzzling one is the last one. Even though there's a comment about it, I don't get what it does... ._.
And that's the main problem: There doesn't seem to be any documentation at all about what param names are valid for what Widget. Some Widgets also require a certain sub-theme to work, but this at least shows an error, but it's still ridiculous to have to figure out which themes are required through trial and error.
So let me summarize: TWL is awesome. The XML is pretty clean and the Java code is really nice, but the documentation isn't even bad, it's non-existent for the premade Widgets. It's sad to see a great library fall flat due to the lack of documentation.
I think this can be solved in 2 ways:
1) Add more documentation, duh. Again, we need more information on Widget specific ifs, params, actions, e.t.c, or the built-in Widgets are worthless.
2) Remove the built-in Widgets and encourage users to create their own Widgets. This could spawn sub-libraries (with hopefully better documentation) targeted at different projects. A simple one with very few XML settings at the cost of flexibility would benefit beginners or just people who want to get results quickly, while more advanced ones could use the full capabilities of the TWL, which again are frankly amazing. I believe this to be the best option. We still need some more documentation on which params are available for the Widget base class though...
EDIT: I realized most of this information could be found in the source code, but still... ._.
Login
Register
FAQ
Search
