The biggest hurdle for a gtkdialog newbe, or at least so it was for me, was getting handle on how to structure the code, where to find documentation and how to use it, where to find examples and how to add comments to the code or comment out blocks of code without braking scripts.
In this article I go over these topics in some detail. It seems necessary to consider the basics before launching into more ambitious topics.
This is the next article in a series of articles on gtkdialog, “gtkdialog Exploration – articles and examples”, which can be found at https://blogs.czapski.id.au/2017/04/gtkdialog-exploration.
Creadits:
Gtkdialog – A small utility for fast and easy GUI building.
2003-2007 László Pere <pipas@linux.pte.hu>
2011-2012 Thunor thunorsif@hotmail.com
Project site: https://code.google.com/archive/p/gtkdialog/
Original documentation: http://linux.pte.hu/~pipas/gtkdialog/
Most recent documentation (not very recent) http://xpt.sourceforge.net/techdocs/language/gtkdialog/gtkde03-GtkdialogUserManual/.
The project home page contains links to other resources which are worth looking at.
Pre-Requisites
This article assumes that the Virtual Box Machine Image created in accordance with the instructions in the blog article to be found at https://blogs.czapski.id.au/2016/10/configure-virtual-box-virtual-machine-and-install-centos-6-8-base-image is available but it is expected that pretty much any Linux environment will do just as well so long as it supports yad and gtkdialog.
For convenience I posted the export of the VirtualBox image which would have been built if the reader followed all the articles in the series “Build a Linux-based Infrastructure Solution Demonstration Series” to date, that is to the 8th of March 2017. The link to the main article is https://blogs.czapski.id.au/2017/04/virtualbox-image-with-content-as-built-so-far.
gtkdialog application structure and basic interaction with the environment
A gtkdialog application UI is, in effect, a window with content. Perhaps the simplest reasonable gtkdialog application with gtkdialog GUI definition is shown below:
touch /tmp/ex01.sh
chmod ug+x /tmp/ex01.sh
cat <<-'EOSCRIPT' > /tmp/ex01.sh
#!/bin/bash
MAIN_DIALOG_FILE=/tmp/ex01.gtkd
cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE}
<window>
<vbox>
<text>
<label>I am a window.</label>
</text>
<button ok></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;;
esac
rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT
/tmp/ex01.sh
This application’s UI looks like this:
Note that the standard window controls, close, maximise, minimise and window menu are provided, as is the title bar with some title even though we specified neither in the UI definition.
The application has a text box with literal text we provided and a button with the label we provided. Clicking the button will cause the UI to exit with the following text emitted to stdout.
EXIT="OK"
The gtkdialog application consists of a GUI definition, expressed as gtkdialog-specific XML structure, provided to a gtkdialog executable as a file or as a shell variable.
The GUI definition specifies all the visual components, event handlers, actions, etc.. More on the event handlers, actions and similar in a later article. For now we will keep things simple.
Common GUI definition convention
In a typical gtkdialog example online, and in the examples found under ~/gtkdialog-0.8.3/examples/ you will see the following idiom for defining and using gtkdialog UIs:
touch /tmp/ex02.sh
chmod ug+x /tmp/ex02.sh
cat <<-'EOSCRIPT' > /tmp/ex02.sh
#!/bin/bash
MAIN_DIALOG='
<window>
<vbox>
<text>
<label>I am a window.</label>
</text>
<button ok></button>
</vbox>
</window>
'
export MAIN_DIALOG
case ${1} in
-d | --dump) echo ${MAIN_DIALOG} ;;
*) gtkdialog --center ${MAIN_DIALOG} ;;
esac
EOSCRIPT
/tmp/ex02.sh
Here the GUI definition is explicitly assigned to a shell variable with “hard” quotes surrounding it. I don’t like this idiom and I don’t use this idiom. The reason is that shell quoting becomes quite tricky and error-prone as soon as the GUI definition becomes more complex and GUI components invoke external commands or shell functions with parameters, etc..
Instead, I use the ‘”here document” piped to a file’ idiom, like in the ex01.sh example above. This is the idiom I will continue to use so you will need to “translate” examples I use to examples provided with gtkdialog and seen online, or translate them to my way of doing things, whichever you prefer.
How can gtkdialog application interact with the environment (basic)
It was briefly mentioned in the text following ex01.sh that when the OK button is clicked the GUI is closed and gtkdialog emits to the stdout
EXIT="OK"
If there were other buttons and other variables defined and populated in the GUI their names and values would similarly be emitted to the stdout.
Let’s try the following example to demonstrate this:
touch /tmp/ex03.sh
chmod ug+x /tmp/ex03.sh
cat <<-'EOSCRIPT' > /tmp/ex03.sh
#!/bin/bash
MAIN_DIALOG_FILE=${0}.gtkd
cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE}
<window>
<vbox>
<text>
<label>I am a window.</label>
<variable>vLabelVariable</variable>
</text>
<button ok></button>
<button cancel></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;;
esac
rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT
/tmp/ex03.sh
When the Cancel button is pressed the following is emitted to the stdout
vLabelVariable="I am a window."
EXIT="Cancel"
When the OK button is pressed the following is emitted to the stdout
vLabelVariable="I am a window."
EXIT="OK"
A script can intercept the value of the variables, for example the EXIT variable, and alter subsequent processing as required.
Let’s modify the script so that it recognises the value of the EXIT variable.
cat <<-'EOSCRIPT' > /tmp/ex03.sh
#!/bin/bash
MAIN_DIALOG_FILE=${0}.gtkd
cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE}
<window>
<vbox>
<text>
<label>I am a window.</label>
<variable>vLabelVariable</variable>
</text>
<button ok></button>
<button cancel></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) RESULTS=$(gtkdialog --center --file=${MAIN_DIALOG_FILE}) ;;
esac
I=$IFS; IFS=""
for STATEMENTS in "${RESULTS}"; do
echo 'STATEMENTS:-->>'"${STATEMENTS}"'<<--'
eval $STATEMENTS
done
IFS=$I
if [[ "$EXIT" = "OK" ]]; then
echo "You clicked OK with vLabelVariable containing '${vLabelVariable}'"
else
echo "You pressed the Cancel button."
fi
rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT
/tmp/ex03.sh
Executing this script produces:
STATEMENTS:-->>vLabelVariable="I am a window."
EXIT="OK"<<--
You clicked OK with vLabelVariable containing 'I am a window.'
A shell scripter will undoubtedly come up with alternate ways of getting at the variable names and values.
Note that the content of the vLabelVariable is also emitted. This may or may not be useful. It is possible to prevent the variable being emitted by providing the export=”false” attribute when defining the variable in the GUI. The script variant below illustrates this.
cat <<-'EOSCRIPT' > /tmp/ex03.sh
#!/bin/bash
MAIN_DIALOG_FILE=${0}.gtkd
cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE}
<window>
<vbox>
<text>
<label>I am a window.</label>
<variable export="false">vLabelVariable</variable>
</text>
<button ok></button>
<button cancel></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) RESULTS=$(gtkdialog --center --file=${MAIN_DIALOG_FILE}) ;;
esac
I=$IFS; IFS=""
for STATEMENTS in "${RESULTS}"; do
echo 'STATEMENTS:-->>'"${STATEMENTS}"'<<--'
eval $STATEMENTS
done
IFS=$I
if [[ "$EXIT" = "OK" ]]; then
echo "You clicked OK with vLabelVariable containing '${vLabelVariable}'"
else
echo "You pressed the Cancel button."
fi
rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT
/tmp/ex03.sh
Executing the modified script produces the following:
STATEMENTS:-->>EXIT="OK"<<--
You clicked OK with vLabelVariable containing ''
The variable vLabelVariable was not exported and its value is not available.
I am jumping ahead a bit here by making a reference to a forward topic. The topic of bash functions used as callbacks and action logic will be dealt with later. For now one needs to know that whether to use export=”false” is a reasonably important decision because any variable defined with export=”false” will not be visible in the shell environment of the callback/action functions so will either be inaccessible or will have to be passed as an argument to a callback/action function. I don’t see harm in not specifying export=”false”. Perhaps there is a performance benefit is so doing.
More on the topic of callbacks and actions in a later article.
Explore examples
I confess that without the examples provided with the gtkdialog source distribution and also available online at https://github.com/01micko/gtkdialog/tree/master/examples I would have given up on gtkdialog. The reference documentation is just that – reference – a place to go to look up a specific piece of information knowing that such information can be looked up in the reference.
A newbie needs to understand the broad capabilities, concepts and functionality, and needs some elaboration. This sort of documentation is missing. True, there are a few tutorials but they are hard to find and are pretty limited in the coverage and scope, so examples are the best means of finding out what can be done and how, unless a comprehensive tutorial becomes available.
Until it does, spend time looking at examples to see what the various tags and attributes exist and what they accomplish. For this set of articles I installed examples locally to ~/gtkdialog-0.8.3/examples. There is no index so explore each on its own, or use the indexed and accessible source at the github URL quoted above.
The simplest way is to invoke each example as a shells script, which is what most of them are, and see what is shown, and then look at the script source to see how it does it.
For example:
~/gtkdialog-0.8.3/examples/window/window
Then see what the GUI definition looks like
~/gtkdialog-0.8.3/examples/window/window --dump
<window>
<vbox>
<frame Description>
<text>
<label>This is an example window.</label>
</text>
</frame>
<hbox>
<button ok></button>
<button cancel></button>
</hbox>
</vbox>
</window>
And finally, look at the source:
geany ~/gtkdialog-0.8.3/examples/window/window &
#!/bin/sh
GTKDIALOG=gtkdialog
MAIN_DIALOG='
<window>
<vbox>
<frame Description>
<text>
<label>This is an example window.</label>
</text>
</frame>
<hbox>
<button ok></button>
<button cancel></button>
</hbox>
</vbox>
</window>
'
export MAIN_DIALOG
case $1 in
-d | --dump) echo "$MAIN_DIALOG" ;;
*) $GTKDIALOG --program=MAIN_DIALOG ;;
esac
Reference Documentation
Reference documentation is available in a number of places, and is more or less useful, depending on a bunch of factors.
In the demo image it is available at ~/gtkdialog-0.8.3/doc/reference/. Again, there is no index so pick the first HTML document that comes to hand and view it in a web browser. Internal links will allow you to navigate from object to object so this is not much of a drama. An index is available online at http://01micko.com/reference/. So, locally:
firefox ~/gtkdialog-0.8.3/doc/reference/button.html &
For a newbie the first glance at this is somewhat off-putting. Still, note the following:
- At the bottom of the page, and all other pages, is a list of hyperlinks to the various gtkdialog objects so you can navigate form button to text to window and so on
- The definition lists all the valid tags and discusses the various attributes, signals, functions, etc. – more on these topics in subsequent articles
- The tag attributes section lists all attributes specific to this tag, BUT it does not list these attributes which can be applied to the tag but which are inherited from the parent objects in the object hierarchy
- In this case the innocuous sentence “See the GtkButton widget and ancestor class properties.” hints that there may be other properties that can be applied to the button and links to the page which contains more on the topic. Note that this is an external link so an Internet connection will be needed to access it.
- The external source for GtkButton contains, amongst other things, the object hierarchy of which the button object is a child as well as a list of properties defined for that object. The hierarchy is navigable and inherited parent properties can be discovered by following the links.
- Not all defined properties, signals and functions are mapped by, and visible to, gtkdialog or useable from it. For example, the border-width property of the GtkContainer, which is a grandparent of the GtkButton, is useable from the GtkButton but the other two properties are not visible or useable
- One has to exercise one’s mind a bit to translate data types to what can/should be specified as the attribute value for a particular attribute/property, for example one would specify ‘<window border-width=”6″ …’.
As I practice it, gtkdialog is pretty easy to work with to try various things. Exploration of what the various attributes do to a GUI is pretty painless, particularly once one knows how to effectively comment out blocks of gtkdialog GUI definition XML for various experiments.
The following are links to material that I found useful when dealing with specific topics in my work with gtkdialog so far. They are collected here for ease of reference.
gtkdialog Refrences and Examples
Themes and Styles
Object Hierarchy – Window
Commenting out blocks of XML
One of the reasons I use ‘”here documents” piped to a file’ for persisting gtkdialog GUI definitions is because I can easily comment out blocks of XML without breaking gtkdialog at runtime.
Let’s consider what a person familiar with XML would try first:
touch /tmp/ex04.sh
chmod ug+x /tmp/ex04.sh
cat <<-'EOSCRIPT' > /tmp/ex04.sh
#!/bin/bash
MAIN_DIALOG_FILE=${0}.gtkd
cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE}
<window>
<vbox>
<!--
<text>
<label>I am a window.</label>
</text>
-->
<button ok></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;;
esac
rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT
/tmp/ex04.sh
Executing this script produces the following:
** ERROR **: gtkdialog: Error in line 4, near token 'string': syntax error
aborting...
/tmp/ex04.sh: line 18: 5569 Aborted (core dumped) gtkdialog --center --file=${MAIN_DIALOG_FILE}
Opps – no banana. Not only that, but the message is pretty cryptic, the line number reference is to a line number in XML GUI definition and the error may not actually be in the line being referenced. With large GUI definitions debugging could be a headache.
One way to try to zoom in on the line number in the XML is to do the following, bearing in mind that the line number in the error message may not be the line number where the error is caused, and that some breakages prevent XML being generated so this may not work at all:
/tmp/ex04.sh --dump | cat -n | more
1 <window>
2 <vbox>
3 <!--
4 <text>
5 <label>I am a window.</label>
6 </text>
7 -->
8 <button ok></button>
9 </vbox>
10 </window>
Note, too, that the script’s error line number is useless – it is the number of the line where gtkdialog command is invoked. This will be particularly useless when we start working with bash functions and errors will be reported with respect to the line numbers inside the functions. But I am getting ahead of myself.
Clearly, standard XML <!– commented out –> syntax does not work.
Let’s try a combination of shell techniques to do the job. Consider this script:
scriptName=ex05
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh
cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash
MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window>
<vbox>
$(:<<-'COMMENT--------------------'
<text>
<label>I am a window.</label>
</text>
COMMENT--------------------
)
<button ok></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;;
esac
rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT
/tmp/${scriptName}.sh --dump
This produces the following:
<window>
<vbox>
<button ok></button>
</vbox>
</window>
Notice that the entire section of XML between and including <text>…</text> tags has gone missing.
Let’s analyse what is happening.
- Inner “Here document” syntax “
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}” is different from the outer “Here document” syntax “cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh“. Note the hard quotes around the here document delimiter ‘EOSCRIPT’. Quoting the document delimiter prevents bash from expanding commands and shell variables at the time the document is created. Let’s see what the document looks like after it is created:
cat /tmp/${scriptName}.sh
#!/bin/bash
MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window>
<vbox>
$(:<<-'COMMENT--------------------'
<text>
<label>I am a window.</label>
</text>
COMMENT--------------------
)
<button ok></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;;
esac
rm -f ${MAIN_DIALOG_FILE}
|
Note that the variables which would be expanded if the here document delimiter was not hard quoted are not expanded.
- At runtime, when this script is executed, the inner “here document” will be created. This time the here document delimiter is not quoted so commands and variables will be expanded by the shell, resulting in the $() construct being executed. This construct is a “execute in a subshell” construct, causing bash to create a subshell and execute whatever is inside $() as a stream of commands right there and then, when the here document is being created, so that whatever output is produced by the subshell, if any, will get incorporated into the here document in its place.
See, for example, http://unix.stackexchange.com/questions/147420/what-is-in-a-command for a discussion
- The command ‘:’ is a no-operation, or a null command for bash so there is no command to execute. Everything following ‘:’ will be ignored except for variable substitution and interpretation of shell-special characters. See http://stackoverflow.com/questions/3224878/what-is-the-purpose-of-the-colon-gnu-bash-builtin for a discussion.
- “
<<-'COMMENT--------------------'” and everything following it until “COMMENT--------------------” is a “here document” which is ignored since ‘:’ causes it to be ignored. Hard-quoting the delimiter “COMMENT--------------------” prevents any $xxxx present in the text form being expanded by the shell and any shell-special characters, like <>|{}, etc. from being interpreted, causing errors
In essence the entire $(….) disappears when the script executes and does not get embedded in the xml document which gtkdialog executes. Great way to comment out large chunks of XML when exploring with alternatives.
Short comments inside gtkdialog XML
Two other techniques can be used to provide comments inside the gtkdialog GUI XML.
I am again running ahead a bit but this is in a good cause 🙂 Each object in gtkdialog except “frame” can be decorated with a bunch of object-specific attributes. Gtkdialog parser is very forgiving of attribute names which it does not recognise so a sneaky way takes advantage of that fact is making it possible to invent a tag name and have its value contain some comment text. Consider the following script:
scriptName=ex06
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh
cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash
MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window xx-window-comment="this is a comment on the window tag">
<vbox>
<text xx-text-comment="I am using an unrecognised attribute to provide a comment">
<label>I am a window.</label>
</text>
<button ok></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;;
esac
rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT
/tmp/${scriptName}.sh
The script happily executed because unknown attributes were ignored yet the comment text is in the XML as can be readily seen:
/tmp/${scriptName}.sh --dump
<window xx-window-comment="this is a comment on the window tag">
<vbox>
<text xx-text-comment="I am using an unrecognised attribute to provide a comment">
<label>I am a window.</label>
</text>
<button ok></button>
</vbox>
</window>
Note that if a future version of gtkdialog tightens up parsing and rejects unknown attribute names then scripts which use this technique will break.
The second method is a variation on the $(:…) technique, discussed above.
Consider the following script
scriptName=ex07
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh
cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash
MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window>
<vbox>
$(: this is a single line comment - to continue it over multiple lines \
one must provide line continuation to shell, \, and carry on. \
The $() construct must be closed with the )
<text>
<label>I am a window.</label>
</text>
<button ok></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;;
esac
rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT
/tmp/${scriptName}.sh
Again, everything inside $() disappeared.
/tmp/${scriptName}.sh --dump
<window>
<vbox>
<text>
<label>I am a window.</label>
</text>
<button ok></button>
</vbox>
</window>
|
Note that everything inside $() is expanded by the shell and special characters are acted upon. Including < >, for example, will cause breakage – try it. Consider the following script
scriptName=ex08
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh
cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash
MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window>
<vbox>
$(: this is a single line comment - to continue it over multiple lines \
one must provide line continuation to shell, \, and carry on. \
The $() construct < > must be closed with the )
<text>
<label>I am a window.</label>
</text>
<button ok></button>
</vbox>
</window>
EOUIDFEINITION
case ${1} in
-d | --dump) cat ${MAIN_DIALOG_FILE} ;;
*) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;;
esac
rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT
/tmp/${scriptName}.sh
/tmp/ex08.sh: command substitution: line 6: syntax error near unexpected token `>'
/tmp/ex08.sh: command substitution: line 6: `: this is a single line comment - to continue it over multiple lines one must provide line continuation to shell, \, and carry on. The $() construct < > must be closed with the )'
** ERROR **: Error opening file '/tmp/ex08.sh.gtkd': No such file or directory
aborting...
/tmp/ex08.sh: line 19: 6225 Aborted (core dumped) gtkdialog --center --file=${MAIN_DIALOG_FILE}
|
If you use these kinds of comments watch out for shell-special characters. Clearly this kind of comments is not suitable for commenting out chunks of XML. While one can use these kinds comments it seems to me safer to use undefined attributes for short comments and $(:<<-‘….’…) comments for large comments and for commenting out blocks of XML in the gtkdialog GUI definitions.
Introduction to gtkdialog – application structure, examples and documentation
The biggest hurdle for a gtkdialog newbe, or at least so it was for me, was getting handle on how to structure the code, where to find documentation and how to use it, where to find examples and how to add comments to the code or comment out blocks of code without braking scripts.
In this article I go over these topics in some detail. It seems necessary to consider the basics before launching into more ambitious topics.
This is the next article in a series of articles on gtkdialog, “gtkdialog Exploration – articles and examples”, which can be found at https://blogs.czapski.id.au/2017/04/gtkdialog-exploration.
Creadits:
Gtkdialog – A small utility for fast and easy GUI building.
2003-2007 László Pere <pipas@linux.pte.hu>
2011-2012 Thunor thunorsif@hotmail.com
Project site: https://code.google.com/archive/p/gtkdialog/
Original documentation: http://linux.pte.hu/~pipas/gtkdialog/
Most recent documentation (not very recent) http://xpt.sourceforge.net/techdocs/language/gtkdialog/gtkde03-GtkdialogUserManual/.
The project home page contains links to other resources which are worth looking at.
Pre-Requisites
This article assumes that the Virtual Box Machine Image created in accordance with the instructions in the blog article to be found at https://blogs.czapski.id.au/2016/10/configure-virtual-box-virtual-machine-and-install-centos-6-8-base-image is available but it is expected that pretty much any Linux environment will do just as well so long as it supports yad and gtkdialog.
For convenience I posted the export of the VirtualBox image which would have been built if the reader followed all the articles in the series “Build a Linux-based Infrastructure Solution Demonstration Series” to date, that is to the 8th of March 2017. The link to the main article is https://blogs.czapski.id.au/2017/04/virtualbox-image-with-content-as-built-so-far.
gtkdialog application structure and basic interaction with the environment
A gtkdialog application UI is, in effect, a window with content. Perhaps the simplest reasonable gtkdialog application with gtkdialog GUI definition is shown below:
touch /tmp/ex01.sh chmod ug+x /tmp/ex01.sh cat <<-'EOSCRIPT' > /tmp/ex01.sh #!/bin/bash MAIN_DIALOG_FILE=/tmp/ex01.gtkd cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE} <window> <vbox> <text> <label>I am a window.</label> </text> <button ok></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;; esac rm -f ${MAIN_DIALOG_FILE} EOSCRIPT /tmp/ex01.shThis application’s UI looks like this:
Note that the standard window controls, close, maximise, minimise and window menu are provided, as is the title bar with some title even though we specified neither in the UI definition.
The application has a text box with literal text we provided and a button with the label we provided. Clicking the button will cause the UI to exit with the following text emitted to stdout.
The gtkdialog application consists of a GUI definition, expressed as gtkdialog-specific XML structure, provided to a gtkdialog executable as a file or as a shell variable.
The GUI definition specifies all the visual components, event handlers, actions, etc.. More on the event handlers, actions and similar in a later article. For now we will keep things simple.
Common GUI definition convention
In a typical gtkdialog example online, and in the examples found under ~/gtkdialog-0.8.3/examples/ you will see the following idiom for defining and using gtkdialog UIs:
touch /tmp/ex02.sh chmod ug+x /tmp/ex02.sh cat <<-'EOSCRIPT' > /tmp/ex02.sh #!/bin/bash MAIN_DIALOG=' <window> <vbox> <text> <label>I am a window.</label> </text> <button ok></button> </vbox> </window> ' export MAIN_DIALOG case ${1} in -d | --dump) echo ${MAIN_DIALOG} ;; *) gtkdialog --center ${MAIN_DIALOG} ;; esac EOSCRIPT /tmp/ex02.shHere the GUI definition is explicitly assigned to a shell variable with “hard” quotes surrounding it. I don’t like this idiom and I don’t use this idiom. The reason is that shell quoting becomes quite tricky and error-prone as soon as the GUI definition becomes more complex and GUI components invoke external commands or shell functions with parameters, etc..
Instead, I use the ‘”here document” piped to a file’ idiom, like in the ex01.sh example above. This is the idiom I will continue to use so you will need to “translate” examples I use to examples provided with gtkdialog and seen online, or translate them to my way of doing things, whichever you prefer.
How can gtkdialog application interact with the environment (basic)
It was briefly mentioned in the text following ex01.sh that when the OK button is clicked the GUI is closed and gtkdialog emits to the stdout
If there were other buttons and other variables defined and populated in the GUI their names and values would similarly be emitted to the stdout.
Let’s try the following example to demonstrate this:
touch /tmp/ex03.sh chmod ug+x /tmp/ex03.sh cat <<-'EOSCRIPT' > /tmp/ex03.sh #!/bin/bash MAIN_DIALOG_FILE=${0}.gtkd cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE} <window> <vbox> <text> <label>I am a window.</label> <variable>vLabelVariable</variable> </text> <button ok></button> <button cancel></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;; esac rm -f ${MAIN_DIALOG_FILE} EOSCRIPT /tmp/ex03.shWhen the Cancel button is pressed the following is emitted to the stdout
When the OK button is pressed the following is emitted to the stdout
A script can intercept the value of the variables, for example the EXIT variable, and alter subsequent processing as required.
Let’s modify the script so that it recognises the value of the EXIT variable.
cat <<-'EOSCRIPT' > /tmp/ex03.sh #!/bin/bash MAIN_DIALOG_FILE=${0}.gtkd cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE} <window> <vbox> <text> <label>I am a window.</label> <variable>vLabelVariable</variable> </text> <button ok></button> <button cancel></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) RESULTS=$(gtkdialog --center --file=${MAIN_DIALOG_FILE}) ;; esac I=$IFS; IFS="" for STATEMENTS in "${RESULTS}"; do echo 'STATEMENTS:-->>'"${STATEMENTS}"'<<--' eval $STATEMENTS done IFS=$I if [[ "$EXIT" = "OK" ]]; then echo "You clicked OK with vLabelVariable containing '${vLabelVariable}'" else echo "You pressed the Cancel button." fi rm -f ${MAIN_DIALOG_FILE} EOSCRIPT /tmp/ex03.shExecuting this script produces:
A shell scripter will undoubtedly come up with alternate ways of getting at the variable names and values.
Note that the content of the vLabelVariable is also emitted. This may or may not be useful. It is possible to prevent the variable being emitted by providing the export=”false” attribute when defining the variable in the GUI. The script variant below illustrates this.
cat <<-'EOSCRIPT' > /tmp/ex03.sh #!/bin/bash MAIN_DIALOG_FILE=${0}.gtkd cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE} <window> <vbox> <text> <label>I am a window.</label> <variable export="false">vLabelVariable</variable> </text> <button ok></button> <button cancel></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) RESULTS=$(gtkdialog --center --file=${MAIN_DIALOG_FILE}) ;; esac I=$IFS; IFS="" for STATEMENTS in "${RESULTS}"; do echo 'STATEMENTS:-->>'"${STATEMENTS}"'<<--' eval $STATEMENTS done IFS=$I if [[ "$EXIT" = "OK" ]]; then echo "You clicked OK with vLabelVariable containing '${vLabelVariable}'" else echo "You pressed the Cancel button." fi rm -f ${MAIN_DIALOG_FILE} EOSCRIPT /tmp/ex03.shExecuting the modified script produces the following:
The variable vLabelVariable was not exported and its value is not available.
I am jumping ahead a bit here by making a reference to a forward topic. The topic of bash functions used as callbacks and action logic will be dealt with later. For now one needs to know that whether to use export=”false” is a reasonably important decision because any variable defined with export=”false” will not be visible in the shell environment of the callback/action functions so will either be inaccessible or will have to be passed as an argument to a callback/action function. I don’t see harm in not specifying export=”false”. Perhaps there is a performance benefit is so doing.
More on the topic of callbacks and actions in a later article.
Explore examples
I confess that without the examples provided with the gtkdialog source distribution and also available online at https://github.com/01micko/gtkdialog/tree/master/examples I would have given up on gtkdialog. The reference documentation is just that – reference – a place to go to look up a specific piece of information knowing that such information can be looked up in the reference.
A newbie needs to understand the broad capabilities, concepts and functionality, and needs some elaboration. This sort of documentation is missing. True, there are a few tutorials but they are hard to find and are pretty limited in the coverage and scope, so examples are the best means of finding out what can be done and how, unless a comprehensive tutorial becomes available.
Until it does, spend time looking at examples to see what the various tags and attributes exist and what they accomplish. For this set of articles I installed examples locally to ~/gtkdialog-0.8.3/examples. There is no index so explore each on its own, or use the indexed and accessible source at the github URL quoted above.
The simplest way is to invoke each example as a shells script, which is what most of them are, and see what is shown, and then look at the script source to see how it does it.
For example:
Then see what the GUI definition looks like
And finally, look at the source:
Reference Documentation
Reference documentation is available in a number of places, and is more or less useful, depending on a bunch of factors.
In the demo image it is available at ~/gtkdialog-0.8.3/doc/reference/. Again, there is no index so pick the first HTML document that comes to hand and view it in a web browser. Internal links will allow you to navigate from object to object so this is not much of a drama. An index is available online at http://01micko.com/reference/. So, locally:
For a newbie the first glance at this is somewhat off-putting. Still, note the following:
As I practice it, gtkdialog is pretty easy to work with to try various things. Exploration of what the various attributes do to a GUI is pretty painless, particularly once one knows how to effectively comment out blocks of gtkdialog GUI definition XML for various experiments.
The following are links to material that I found useful when dealing with specific topics in my work with gtkdialog so far. They are collected here for ease of reference.
gtkdialog Refrences and Examples
Themes and Styles
Object Hierarchy – Window
Commenting out blocks of XML
One of the reasons I use ‘”here documents” piped to a file’ for persisting gtkdialog GUI definitions is because I can easily comment out blocks of XML without breaking gtkdialog at runtime.
Let’s consider what a person familiar with XML would try first:
touch /tmp/ex04.sh chmod ug+x /tmp/ex04.sh cat <<-'EOSCRIPT' > /tmp/ex04.sh #!/bin/bash MAIN_DIALOG_FILE=${0}.gtkd cat <<-'EOUIDFEINITION' > ${MAIN_DIALOG_FILE} <window> <vbox> <!-- <text> <label>I am a window.</label> </text> --> <button ok></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;; esac rm -f ${MAIN_DIALOG_FILE} EOSCRIPT /tmp/ex04.shExecuting this script produces the following:
** ERROR **: gtkdialog: Error in line 4, near token 'string': syntax error aborting... /tmp/ex04.sh: line 18: 5569 Aborted (core dumped) gtkdialog --center --file=${MAIN_DIALOG_FILE}Opps – no banana. Not only that, but the message is pretty cryptic, the line number reference is to a line number in XML GUI definition and the error may not actually be in the line being referenced. With large GUI definitions debugging could be a headache.
One way to try to zoom in on the line number in the XML is to do the following, bearing in mind that the line number in the error message may not be the line number where the error is caused, and that some breakages prevent XML being generated so this may not work at all:
Note, too, that the script’s error line number is useless – it is the number of the line where gtkdialog command is invoked. This will be particularly useless when we start working with bash functions and errors will be reported with respect to the line numbers inside the functions. But I am getting ahead of myself.
Clearly, standard XML <!– commented out –> syntax does not work.
Let’s try a combination of shell techniques to do the job. Consider this script:
scriptName=ex05 touch /tmp/${scriptName}.sh chmod ug+x /tmp/${scriptName}.sh cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh #!/bin/bash MAIN_DIALOG_FILE=${0}.gtkd cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE} <window> <vbox> $(:<<-'COMMENT--------------------' <text> <label>I am a window.</label> </text> COMMENT-------------------- ) <button ok></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;; esac rm -f ${MAIN_DIALOG_FILE} EOSCRIPT /tmp/${scriptName}.sh --dumpThis produces the following:
Notice that the entire section of XML between and including <text>…</text> tags has gone missing.
Let’s analyse what is happening.
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}” is different from the outer “Here document” syntax “cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh“. Note the hard quotes around the here document delimiter ‘EOSCRIPT’. Quoting the document delimiter prevents bash from expanding commands and shell variables at the time the document is created. Let’s see what the document looks like after it is created:cat /tmp/${scriptName}.sh#!/bin/bash MAIN_DIALOG_FILE=${0}.gtkd cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE} <window> <vbox> $(:<<-'COMMENT--------------------' <text> <label>I am a window.</label> </text> COMMENT-------------------- ) <button ok></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;; esac rm -f ${MAIN_DIALOG_FILE}Note that the variables which would be expanded if the here document delimiter was not hard quoted are not expanded.
See, for example, http://unix.stackexchange.com/questions/147420/what-is-in-a-command for a discussion
<<-'COMMENT--------------------'” and everything following it until “COMMENT--------------------” is a “here document” which is ignored since ‘:’ causes it to be ignored. Hard-quoting the delimiter “COMMENT--------------------” prevents any $xxxx present in the text form being expanded by the shell and any shell-special characters, like <>|{}, etc. from being interpreted, causing errorsIn essence the entire $(….) disappears when the script executes and does not get embedded in the xml document which gtkdialog executes. Great way to comment out large chunks of XML when exploring with alternatives.
Short comments inside gtkdialog XML
Two other techniques can be used to provide comments inside the gtkdialog GUI XML.
I am again running ahead a bit but this is in a good cause 🙂 Each object in gtkdialog except “frame” can be decorated with a bunch of object-specific attributes. Gtkdialog parser is very forgiving of attribute names which it does not recognise so a sneaky way takes advantage of that fact is making it possible to invent a tag name and have its value contain some comment text. Consider the following script:
scriptName=ex06 touch /tmp/${scriptName}.sh chmod ug+x /tmp/${scriptName}.sh cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh #!/bin/bash MAIN_DIALOG_FILE=${0}.gtkd cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE} <window xx-window-comment="this is a comment on the window tag"> <vbox> <text xx-text-comment="I am using an unrecognised attribute to provide a comment"> <label>I am a window.</label> </text> <button ok></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;; esac rm -f ${MAIN_DIALOG_FILE} EOSCRIPT /tmp/${scriptName}.shThe script happily executed because unknown attributes were ignored yet the comment text is in the XML as can be readily seen:
/tmp/${scriptName}.sh --dumpNote that if a future version of gtkdialog tightens up parsing and rejects unknown attribute names then scripts which use this technique will break.
The second method is a variation on the $(:…) technique, discussed above.
Consider the following script
scriptName=ex07 touch /tmp/${scriptName}.sh chmod ug+x /tmp/${scriptName}.sh cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh #!/bin/bash MAIN_DIALOG_FILE=${0}.gtkd cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE} <window> <vbox> $(: this is a single line comment - to continue it over multiple lines \ one must provide line continuation to shell, \, and carry on. \ The $() construct must be closed with the ) <text> <label>I am a window.</label> </text> <button ok></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;; esac rm -f ${MAIN_DIALOG_FILE} EOSCRIPT /tmp/${scriptName}.shAgain, everything inside $() disappeared.
/tmp/${scriptName}.sh --dumpNote that everything inside $() is expanded by the shell and special characters are acted upon. Including < >, for example, will cause breakage – try it. Consider the following script
scriptName=ex08 touch /tmp/${scriptName}.sh chmod ug+x /tmp/${scriptName}.sh cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh #!/bin/bash MAIN_DIALOG_FILE=${0}.gtkd cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE} <window> <vbox> $(: this is a single line comment - to continue it over multiple lines \ one must provide line continuation to shell, \, and carry on. \ The $() construct < > must be closed with the ) <text> <label>I am a window.</label> </text> <button ok></button> </vbox> </window> EOUIDFEINITION case ${1} in -d | --dump) cat ${MAIN_DIALOG_FILE} ;; *) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;; esac rm -f ${MAIN_DIALOG_FILE} EOSCRIPT /tmp/${scriptName}.sh/tmp/ex08.sh: command substitution: line 6: syntax error near unexpected token `>' /tmp/ex08.sh: command substitution: line 6: `: this is a single line comment - to continue it over multiple lines one must provide line continuation to shell, \, and carry on. The $() construct < > must be closed with the )' ** ERROR **: Error opening file '/tmp/ex08.sh.gtkd': No such file or directory aborting... /tmp/ex08.sh: line 19: 6225 Aborted (core dumped) gtkdialog --center --file=${MAIN_DIALOG_FILE}If you use these kinds of comments watch out for shell-special characters. Clearly this kind of comments is not suitable for commenting out chunks of XML. While one can use these kinds comments it seems to me safer to use undefined attributes for short comments and $(:<<-‘….’…) comments for large comments and for commenting out blocks of XML in the gtkdialog GUI definitions.