For the complete QT and Kommander novice, a lot of this theory may be glanced over and returned to once they have taken a look at the examples.
Text widgets are the core concept of Kommander. They are widgets just like any other widget in the QT and KDE libraries, except that they have some extra functionality that allows them to have what we have chosen to call “text associations”.
A text association of a widget can be thought of as a piece of text, specified by the creator of the dialog, that is 'associated' or 'bound' to a widget's particular state. The text does not have anything to do with the way the widget looks or behaves superficially and is purely a concept specific to our system. The fact that a text association is specific to a widget's state means that if a widget has x state(s), it also has x text associations; the two are synchronized. Please note that the kinds of states a widget has are specific to that widget. Consider a radio button widget. In our system, this widget has two states - “checked” and “unchecked”. This means you may have two text associations for this widget - one for the “checked” state and one for the “unchecked” state. On the other hand, a line edit widget only has one state called “default”. If a widget only has one state, it is always called “default” in our system.
So by now you(hopefully) understand that a widget may have pieces of text associated with each of its states, whatever they may be. This associated text will most likely contain some static text written by you, such as a portion of a web page or perhaps an element of a command line to a program for example. However, static text isn't the only thing you can put in your text associations. You can have dynamic text added by use of “specials”.
Specials in a text association take the form of @identifier. Whereever this form exists in a text association, an attempt is made to recognize and expand it to the text it represents, just like a shell expansion if you're familiar with that concept. The names of identifiers can be one of the following -
- The identifier “widgetText”
This is a special identifier recognised by our system, that expands to what we call the “widget text” of the widget. The widget text, like the kinds of states, is specific to the widget in question. For a text edit widget, the “widget text” is the text contained inside the widget. So if the text association of a text edit widget was simply “@widgetText” for state “default”, the text association for state “default” after expansion would resolve to the text inside the text edit at that point in time. Don't worry if this isn't clear in your head straight away, as it is made clear by some examples later in the documentation. Also, note that including the special @widgetText inside a text edit is a very common practice, because the text inside the text edit is nearly always inherent to its purpose in the dialog and in the resulting text generation.
- QT Object name of another widget in the dialog
For those of you not familiar with QT or even object oriented concepts, just realise that all widgets in Kommander have a name. When “@anotherWidgetName” is in the text association of a widget, it is expanded to the evaluated text association of the widget specified. Note that when Kommander goes to evaluate what the text association of the specified widget is, it will automatically select the text association for the current state of the widget, perform any necessary expansions(which again could include widget names, which means recursion) and then that text replaces this special. This creates a tree like dependency of text associations between all the widgets in the dialog, and is a fundamental concept to the overall text generation. We discuss this further later in this section.
- A special builtin in identifier
We have implemented various special identifiers that will expand to various text, for example the “@exec” special that expands to the standard output of the program it runs.
Please consult the reference section of Part IV for a full description of the implemented specials. We will come back to these later.
In this section we will see how the information we've learned is woven together, so that entire pieces of text and documents can be generated based on the states of widgets.
In the previous section, we saw how a text association of a widget could contain the expanded text association of another widget in the dialog by including “@identifier” in the text association, where identifier is the name of another widget. With this, you can create a tree structure of text associations, which is how the text is ultimately generated. The best way of grasping this concept like most things is through visualisation. Please examine the image below.
The above image represents the corresponding dialog's text associations in a graphical, tree form. As we noted previously line edits only have one state “default”, and therefore they can only have one text association. Every widget in the above representation has a text association simply containing the special “@widgetText”. Remember from the previous section, that this special expands to the widget's text which in the case of a line edit is the text inside the line edit.
The group box also has a single state, and ultimately a single text association. Its text association's contents are a little different from the line edits', however. The text association is the names of all the line edit's contained in the group box, in the order they appear, prefixed with “@”. Recall from the previous section that when you include another widget's name prefixed with “@” in a text association, it will be expanded to the evaluated text association of the specified widget. We already worked out that any particular line edit's text association will be the text inside the line edit, therefore the text association of the group box will end up as, after being expanded, the text inside all of the line edits combined and in order.
Let's apply a scenario to this theoretical dialog we're analysing. Suppose we enter information into the line edits so the dialog looks like this.
lineEditOne contains the text “This”, lineEditTwo contains “is”, lineEditThree contains “a”, lineEditFour contains “sentence”, and lineEditFive contains “�”. Remember that we said that the text associations of all line edits are “@widgetText”, therefore their text association simply evaluates to the text inside them. Our groupbox's association is “@lineEditOne @lineEditTwo @lineEditThree @lineEditFour @lineEditFive”. This means, if the group box's text association was evaluated in the state given in the scenario screenshot, the text association of the group box would be This is a sentence!.
But it doesn't get evaluated? You're right! In this contrived example the text association of the GroupBox, and therefore of the LineEdits never gets evaluated because nothing references the text association of the GroupBox. We did this purely to see how the text association of one widget can be made up of another, in theory. Imagine though, if we could use the text association of the GroupBox in some way, All that is left is to adjust the total size of your dialog by clicking the lower right corner of the dialog and resizing, and then save your dialog if you haven't done so already. Do this by going to File->Save. Select the directory and set the filename you wish to save to and click OK. You've just saved your first functional Kommander dialog. In the next section, we run the dialog by using the Executor component of Kommander. perhaps write it to a file or do some other processing. We can do this, and we're going to see how in the next section. For the moment, just be comfortable with the fact that one widget's text association can be made up of another's. If you can see how this allows the generating of text like the words into a sentence as in this example, you're well on your way to doing some cool things with Kommander.
