2017 April

Apr 28

yad – styling a dialog with a label and a button

By Czapski Michael Demo Building, yad No Comments »

It turns out that yad dialog boxes can be styles using exactly the same technique as that I documented in the previous article for styling gtkdialog applications. In this article I document the serendipitous discovery I made when working with styles for gtkdialog applications so that you can take advantage of it if you feel the need.

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.

It also assumes that yad is installed, as discussed in the article “Install yad and gtkdialog” (https://blogs.czapski.id.au/2017/04/gtkdialog-for-rapid-prototyping-of-linux-applications-install-gtkialog-and-yad)

Applying styles to a yad dialog box with a label and a button

See my earlier article, “gtkdialog – Applying styles to gtkdialog applications”, at https://blogs.czapski.id.au/2017/04/gtkdialog-applying-styles-to-gtkdialog-applications, for context to this article – specifically for the discussion, references and examples of styles that can be applied to GTK objects, both these that are used by the gtkdialog applicaitns and evidently also by yad “applications”.

I am providing the example here, since the styling is covered in the previous article, and the yad “application” in this example is trivial.

So, consider the following set of commands and a Bash script:

> /tmp/yadstyling_01.sh
chmod ug+x /tmp/yadstyling_01.sh
cat <<-'EODECK' > /tmp/yadstyling_01.sh
#!/bin/bash

export GTK2_RC_FILES=/tmp/gtkrc

cat <<-'EOSTYLEDEF' > ${GTK2_RC_FILES}

pixmap_path "/usr/share/backgrounds/cosmos/:/usr/share/backgrounds/nature/:/usr/share/backgrounds/scenery/:/usr/share/icons/gnome/scalable/actions"

style "windowStyle" {
    engine "pixmap" {
    image
      {
          function        = FLAT_BOX
          file            = "Garden.jpg"
          border          = { 0, 0, 0, 0 }
          stretch         = TRUE
          overlay_file    = "media-playback-pause.svg"
          overlay_stretch = FALSE
      }
  }
}

style "contentStyle" {
    fg[NORMAL]      = "brown"    # colour of the content text
    font_name="CM Roman CE Regular 10"
    GtkLabel::use-markup = TRUE
}

style "buttonStyle" {
    fg[NORMAL]      = "white"   # button label text colour
    fg[PRELIGHT]    = "yellow"  # button label text colour when mouse is over the button
    bg[NORMAL]      = "blue"    # button background colour
    bg[PRELIGHT]    = "navy"    # button background colour when mouse is over the button
    font_name       = "Fixed Italic 14"
    xthickness      = 6         # adds "border" on either side of the button
    ythickness      = 6         # adds "border" above and below the button
}

## the paths below apply the named styles to the yad dialog text and button

# gives the entire dialogue background colour
widget_class "<GtkWindow>" style "windowStyle"

# give the Button background colour
widget_class "<GtkWindow><GtkVBox><GtkContainer><GtkButton>" style "buttonStyle"

# gives the button text colour
widget_class "<GtkWindow><GtkVBox><GtkContainer><GtkButton><GtkContainer><GtkHBox><GtkLabel>" style "buttonStyle"

# gives the dialog text colour
widget_class "<GtkWindow><GtkVBox><GtkHBox><GtkVBox><GtkLabel>" style "contentStyle"

EOSTYLEDEF

yad \
    --center --width=400 --image="gtk-dialog-authentication" --window-icon="gtk-dialog-authentication" \
    --title="Succesful connection" \
    --text="Succesfully <b>connected</b> to <span size='large' color='black'>database</span> schema" \
    --button=" Dismiss!gtk-ok!Dismiss this dialogue:0"

EODECK

/tmp/yadstyling_01.sh

Executing this script produces the following:

Critical to the success of this endeavour are the wiget_class paths in the .gtkrc style definitions. The specific paths I am using I worked out by trial and error. This is the only way short of asking the authors, https://www.mankier.com/1/yad#Authors, for the GTK paths to the various variants of yad dialogues.

Experiment with the various style settings and see what you get.

Apr 22

gtkdialog – Applying styles to gtkdialog applications

By Czapski Michael gtkdialog 2 Comments »

In this article I explore application of styles, colours, backgrounds, fonts, etc., to various gtkdialog application objects.

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.

Pre-Requisites

It also assumes that yad and gtkdialog are installed, as discussed in the article “Install yad and gtkdialog” (https://blogs.czapski.id.au/2017/04/gtkdialog-for-rapid-prototyping-of-linux-applications-install-gtkialog-and-yad)

Example of styling – teaser

There is a way to “style” gtkdialog objects, which works in some instances, and which can be used as appropriate.

Consider the following example, which was implemented in an earlier article:

scriptName=ex19
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
    echo "$(date)"
}
export -f fnEchoDateTime

echo '
style "bgWhite" { bg[NORMAL] = "#FFFFFF" }
style "fgWhite" { fg[NORMAL] = "#FFFFFF" }
style "bgBlack" { bg[NORMAL] = "#000000" }
style "bgRed" { bg[NORMAL] = "#FF0000" }
style "fgRed" { fg[NORMAL] = "#FF0000" }
style "bgGreen" { bg[NORMAL] = "#FFFF00" }
style "fgGreen" { fg[NORMAL] = "#FFFF00" }
style "bgBlue" { bg[NORMAL] = "#0000FF" }
style "fgBlue" { fg[NORMAL] = "#0000FF" }

widget "MyWindowBg" style "bgBlack"
widget "MyWindowBg.GtkVBox.GtkHBox.MyButtonBg" style "bgGreen"

widget "MyWindowBg.GtkVBox.myEVB" style "bgBlue"

widget_class "*<GtkFrame>.GtkLabel" style "fgWhite"
widget_class "*<GtkFrame>.*.GtkLabel" style "fgGreen"
widget_class "*<GtkButton>.*.GtkLabel" style "fgRed"

' > /tmp/gtkrc_mono
export GTK2_RC_FILES=/tmp/gtkrc_mono

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My First Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    name="MyWindowBg"
> 
    <vbox>
        <eventbox name="myEVB" above-child="false" visible-window="true">
        <frame   Description  >
            <text><label>This is an example window.</label></text>
        </frame>
        </eventbox>
        <hbox>
            <button name="MyButtonBg" use-underline="true" tooltip-text="Refresh window variable - update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <input>fnEchoDateTime</input>
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action>
</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

Here we define and use GTK styles to change foreground and/or background colours of the various objects.

Here is how the application window looks.

This is just a brief teaser. How to apply styles to objects, what works and what does not, etc., is covered in the following sections.

Some Sources of Information

Let’s explore some sources of information for on styles that might work with gtkdialog objects.

https://en.wikibooks.org/wiki/GTK%2B_By_Example/Theming

http://www.cc.gatech.edu/data_files/public/doc/gtk/tutorial/gtk_tut.html – worth exploring for the underlying concepts and considerations

http://www.cc.gatech.edu/data_files/public/doc/gtk/tutorial/gtk_tut-19.html – specific discussion of styles

Constructing style and making gtkdialog use it

GTK loads and processes the GTK resource file, if one exists, which amongst other things can contain style definitions. This is the method we use to provide styles and define the objects to which they are to be applied. Consider the following excerpt from example ex21 in the next section:

GTKRC_LOCATION=/tmp
[[ ! -f ${GTKRC_LOCATION}/emblem-unreadable.png ]] && cp -v /usr/share/icons/gnome/32x32/emblems/emblem-unreadable.png ${GTKRC_LOCATION}

echo '
style "windowStyle" {
    bg_pixmap[NORMAL] = "emblem-unreadable.png"
}

widget "MyWindow" style "windowStyle"

' > ${GTKRC_LOCATION}/gtkrc_mono
export GTK2_RC_FILES=${GTKRC_LOCATION}/gtkrc_mono

The four key things to note are:

The named style is defined (there can be as many styles as are needed)
The style is associated with one or more “targets” – widget, widget_class or class (more on that in the next section)
The styles and associations are written to a GTK resource file
The shell variable GTK2_RC_FILES which points to that file is then exported so that it can be used by gtkdialog at runtime to locate the styles and objects to which to apply them

I am using different style resource files for different applications so that each of my gtkdialog scripts manages its own styles.

The style definition follows this pattern:

style "<name>" {
    <style definitions>
}

Style are specified using syntax defined by GTK for gtk resources.

Consult GTK resources for reference:

https://developer.gnome.org/gtk2/stable/ – Gnome GTK 2 developer documentation in general
https://developer.gnome.org/gtk2/stable/gtk2-Resource-Files.html#gtk2-Resource-Files.description – Specific section on GTK resource files

Other discussions can be consulted at:

http://www.cc.gatech.edu/data_files/public/doc/gtk/tutorial/gtk_tut-19.html – specific discussion of styles
https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes is tutorial on all manner of GTK appearance including styles.

Styling the Window object and its children

Styles can be applied to the Window object using the name attribute of the Window object and the appropriate definition of style.

Consider the following example to set the baseline for applying styles to a Window object:

scriptName=ex20
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKRC_LOCATION=/tmp

GTKDIALOG=gtkdialog

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    border-width="5"
    name="MyWindow"
> 
    <vbox>
        <frame   Description  >
            <text name="MyText">
                <label>This is an example window.</label>
            </text>
        </frame>
        <hbox>
            <button name="ButtonExit" use-underline="true" width-request="100" has-focus="true">
                <label> _Quit </label>
                <input file icon="gtk-quit"></input>
                <width>16</width>
                <action function="exit">vWindow</action>
            </button>
            <button name="ButtonCancel" use-underline="true" width-request="100">
                <label> _Cancel </label>
                <input file icon="gtk-cancel"></input>
                <width>16</width>
                <action function="closewindow">vWindow</action>
            </button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action>
</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

This produces:

This is the default appearance in my environment without applying any styles.

It is possible, if perhaps not as useful as might at first appear, to apply an image as a repeating motif to the window’s background. If the image is smaller than the window it will be repeated. If the image is larger than the window the top left portion of the image will be used.

Consider the following example:

scriptName=ex21
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKRC_LOCATION=/tmp

# pixmap images must be in the same folder as the gtkrc file 
# since the bg_pixmap style directive does not accept file path - just file name
#
# copy some images to the gtkrc file location
[[ ! -f ${GTKRC_LOCATION}/emblem-unreadable.png ]] && cp -v /usr/share/icons/gnome/32x32/emblems/emblem-unreadable.png ${GTKRC_LOCATION}

GTKDIALOG=gtkdialog

echo '
style "windowStyle" {
    bg_pixmap[NORMAL] = "emblem-unreadable.png"
}

widget "MyWindow" style "windowStyle"

' > ${GTKRC_LOCATION}/gtkrc_mono 
export GTK2_RC_FILES=${GTKRC_LOCATION}/gtkrc_mono

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    border-width="5"
    name="MyWindow"
> 
    <vbox>
        <frame   Description  >
            <text name="MyText">
                <label>This is an example window.</label>
            </text>
        </frame>
        <hbox>
            <button name="ButtonExit" use-underline="true" width-request="100" has-focus="true">
                <label> _Quit </label>
                <input file icon="gtk-quit"></input>
                <width>16</width>
                <action function="exit">vWindow</action>
            </button>
            <button name="ButtonCancel" use-underline="true" width-request="100">
                <label> _Cancel </label>
                <input file icon="gtk-cancel"></input>
                <width>16</width>
                <action function="closewindow">vWindow</action>
            </button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action>
</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

This produces the following:

Let’s consider the definition of the style:

GTKRC_LOCATION=/tmp
[[ ! -f ${GTKRC_LOCATION}/emblem-unreadable.png ]] && cp -v /usr/share/icons/gnome/32x32/emblems/emblem-unreadable.png ${GTKRC_LOCATION}

echo '
style "windowStyle" {
    bg_pixmap[NORMAL] = "emblem-unreadable.png"
}

widget "MyWindow" style "windowStyle"

' > ${GTKRC_LOCATION}/gtkrc_mono
export GTK2_RC_FILES=${GTKRC_LOCATION}/gtkrc_mono

Here we set the background pixmap to use the emblem-unreadable.png. This image will be repeated horizontally and vertically as the window background. The image file must reside in the same directory as the resource file containing this style definition (later in this article we will learn how to configure the gtkrc so that the image does not have to be copied over). In the example above, we copy it from its original location if it is not already there. You may or may not have this specific image in your environment. If you don’t have it use a different one.

The object to which the style is to be applied can be specified in a number of ways.

GTKRC_LOCATION=/tmp
[[ ! -f ${GTKRC_LOCATION}/emblem-unreadable.png ]] && cp -v /usr/share/icons/gnome/32x32/emblems/emblem-unreadable.png ${GTKRC_LOCATION}

echo '
style "windowStyle" {
    bg_pixmap[NORMAL] = "emblem-unreadable.png"
}

widget "MyWindow" style "windowStyle"

' > ${GTKRC_LOCATION}/gtkrc_mono
export GTK2_RC_FILES=${GTKRC_LOCATION}/gtkrc_mono

In the example above we use the name of the widget to which this style is to be applied. The name of the Window object, in this case, is used to make this association:

<window
    title="My Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    border-width="5"
    name="MyWindow"
> 
    <vbox>

Let’s modify this style so that it changes styles of other components. Consider the following example:

scriptName=ex22
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKRC_LOCATION=/tmp

# pixmap images must be in the same folder as the gtkrc file
# since the bg_pixmap style directive does not accept file path - just file name
#
# copy some images to the gtkrc file location
[[ ! -f ${GTKRC_LOCATION}/bits.xpm ]] && cp /usr/share/emacs/23.1/etc/images/ezimage/bits.xpm ${GTKRC_LOCATION} # same place as the rc file
[[ ! -f ${GTKRC_LOCATION}/kill-group.xpm ]] && cp /usr/share/emacs/23.1/etc/images/gnus/kill-group.xpm ${GTKRC_LOCATION}
[[ ! -f ${GTKRC_LOCATION}/emblem-unreadable.png ]] && cp /usr/share/icons/gnome/32x32/emblems/emblem-unreadable.png ${GTKRC_LOCATION}

GTKDIALOG=gtkdialog

echo '
style "windowStyle" {
#    bg_pixmap[NORMAL] = "kill-group.xpm"
#    bg_pixmap[NORMAL] = "bits.xpm"
    bg_pixmap[NORMAL] = "emblem-unreadable.png"
#    bg[NORMAL] = "#989898" # Grayish
    bg[NORMAL] = "lightblue"
    fg[NORMAL] = "darkblue"
#    fg[NORMAL] = "#FFFFFF"
}

widget "MyWindow" style "windowStyle"
#widget_class "<GtkWindow>*" style "windowStyle"

' > ${GTKRC_LOCATION}/gtkrc_mono
export GTK2_RC_FILES=${GTKRC_LOCATION}/gtkrc_mono

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    border-width="5"
    name="MyWindow"
> 
    <vbox>
        <frame   Description  >
            <text name="MyText">
                <label>This is an example window.</label>
            </text>
        </frame>
        <hbox>
            <button name="ButtonExit" use-underline="true" width-request="100" has-focus="true">
                <label> _Quit </label>
                <input file icon="gtk-quit"></input>
                <width>16</width>
                <action function="exit">vWindow</action>
            </button>
            <button name="ButtonCancel" use-underline="true" width-request="100">
                <label> _Cancel </label>
                <input file icon="gtk-cancel"></input>
                <width>16</width>
                <action function="closewindow">vWindow</action>
            </button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action>
</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

This produces the following:

Note that the window background acquires light blue tint. Note too that nothing shows the dark blue colour. This is because the window object does not have anything that has a visible foreground. The objects which have foreground, like text and buttons, are nested inside the window object but since the style is to be applied to the widget by name this style does not get propagated to child objects.

Edit the example and change the two lines from:

widget "MyWindow" style "windowStyle"
#widget_class "<GtkWindow>*" style "windowStyle"

#widget "MyWindow" style "windowStyle"
widget_class "<GtkWindow>*" style "windowStyle"

then re-execute the modified example. This produces the following:

Specifying ‘widget_class “<GtkWindow>*”‘ cause the style to be applied to the Window objects and all the child objects in the hierarchy. In this case the visible outcome is that the text of all the child objects (the only aspect of these objects that has foreground to which to apply a foreground colour) turned dark blue.

Experiment by changing style definition of fg[NORMAL] to use different colours. There is discussion of GTK colours and how they can be specified at https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes/SymbolicColors.

One can apply styles to named widgets, to widget classes (and child objects) and to GTK classes. There is a resource at https://www.cs.tut.fi/lintula/manual/gtk/gtk/gtk-resource-files.html which has a discussion of this topic in the section “Pathnames and patterns”.

Here we are going at a bit of a tangent, working with objects inside the Window, to see how the window style is inherited and overridden.

Change the style definition in the example to read as follows and execute to see the outcome:

echo '
style "windowStyle" {
#    bg_pixmap[NORMAL] = "kill-group.xpm"
#    bg_pixmap[NORMAL] = "bits.xpm"
    bg_pixmap[NORMAL] = "emblem-unreadable.png"
#    bg[NORMAL] = "#989898" # Grayish
    bg[NORMAL] = "lightblue"
    fg[NORMAL] = "darkblue"
#    fg[NORMAL] = "#FFFFFF"
}

style "buttonStyle" {
    bg[NORMAL] = "green"
    fg[NORMAL] = "brown"
}    

widget "MyWindow" style "windowStyle"
#widget_class "<GtkWindow>*" style "windowStyle"
class "GtkButton" style "buttonStyle"

' > ${GTKRC_LOCATION}/gtkrc_mono

This produces the following:

Please note that specifying targets to which to apply styles is a bit tricky and involves style merge priorities. For example the following will not produce the desired outcome:

#widget "MyWindow" style "windowStyle"
widget_class "<GtkWindow>*" style "windowStyle"
class "GtkButton" style "buttonStyle"

The windowStyle will be applied to all child objects and the style to be applied to class GtkButton will be ignored. This is the consequence of GTK style application priority – see https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes#Priority.

Change the definition as follows and re-execute the example:

#widget "MyWindow" style "windowStyle"
widget_class "<GtkWindow>*" style "windowStyle"
class "GtkButton" style : highest "buttonStyle"

This produces the following, which is what we expected to achieve in the first place:

The child foreground style is used for everything except the GtkButton class objects, because the GtkButton class style has the highest priority as far as button styles go. See https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes#Priority for discussion of this topic.

The style merging needs some exploration and some experimentation. Consider the following change:

style "buttonStyle" {
    bg[NORMAL] = "green"
    fg[NORMAL] = "brown"
}   

style "frameStyle" {
    bg[NORMAL] = "red"
    fg[NORMAL] = "maroon"
}   

#widget "MyWindow" style "windowStyle"
widget_class "<GtkWindow>*" style "windowStyle"
class "GtkButton" style : highest "buttonStyle"
#widget_class "*.GtkFrame.*" style "frameStyle"
class "GtkFrame" style : highest "frameStyle"

Execute the example and see that the frame acquired a red border but the label text and the text inside the frame are still the style of the window object.

Uncomment the ‘widget_class “*.GtkFrame.*” …’ and re-execute the example. Note that the Frame title is now maroon but so is the label text inside the text object. That’s because the specification “*.GtkFrame.*” applies the style to the Frame and all it contains.

Modify the specification to read as shown below and re-execute the example.

#widget "MyWindow" style "windowStyle"
widget_class "<GtkWindow>*" style "windowStyle"
class "GtkButton" style : highest "buttonStyle"
widget_class "*.GtkFrame.GtkLabel" style "frameStyle"
class "GtkFrame" style : highest "frameStyle"

Note that the frame label is still maroon but the text object’s label is dark blue, that is it inherits foreground colour from the Window style. This is because we restricted the style application to GtkLabel under the GtkFrame only.

Let’s now explore how text can be styled with font specification. Reference: https://developer.gnome.org/pango/stable/pango-Fonts.html.

Consider the following example:

scriptName=ex23
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKRC_LOCATION=/tmp

GTKDIALOG=gtkdialog

echo '
style "windowStyle" {
    bg[NORMAL] = "lightblue"
    fg[NORMAL] = "darkblue"
#    font_name="Bitstream Charter Italic 10"
#    font_name="Caladea Bold 10"
#    font_name="URW Gothic L Semi-Bold 12"
#    font_name="URW Chancery L Medium Italic 16"
#    font_name="Standard Symbols L 12"
#    font_name="Nimbus Sans L Condensed 14"
#    font_name="Fixed Bold 14"
    font_name="Carlito Bold 12"
}

style "buttonStyle" {
    bg[NORMAL] = "green"
    fg[NORMAL] = "brown"
}   

style "frameStyle" {
    bg[NORMAL] = "red"
    fg[NORMAL] = "maroon"
}   

widget_class "<GtkWindow>*" style "windowStyle"
class "GtkButton" style : highest "buttonStyle"
widget_class "*.GtkFrame.GtkLabel" style "frameStyle"
class "GtkFrame" style : highest "frameStyle"

' > ${GTKRC_LOCATION}/gtkrc_mono
export GTK2_RC_FILES=${GTKRC_LOCATION}/gtkrc_mono

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    border-width="5"
    name="MyWindow"
> 
    <vbox>
        <frame   Description  >
            <text name="MyText">
                <label>This is an example window.</label>
            </text>
        </frame>
        <hbox>
            <fontbutton name="ButtonFont" width-request="100">
                <variable>btnFont</variable>
            </fontbutton>
            <button name="ButtonExit" use-underline="true" width-request="100" has-focus="true">
                <label> _Quit </label>
                <input file icon="gtk-quit"></input>
                <width>16</width>
                <action function="exit">vWindow</action>
            </button>
            <button name="ButtonCancel" use-underline="true" width-request="100">
                <label> _Cancel </label>
                <input file icon="gtk-cancel"></input>
                <width>16</width>
                <action function="closewindow">vWindow</action>
            </button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action>
</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

Note the font_family style property. The string consists of the Font Family followed by font weight and font size.

Consider the font specifications. Uncomment one at a time and see the results.

style "windowStyle" {
    bg[NORMAL] = "lightblue"
    fg[NORMAL] = "darkblue"
#    font_name="Bitstream Charter Italic 10"
#    font_name="Caladea Bold 10"
#    font_name="URW Gothic L Semi-Bold 12"
#    font_name="URW Chancery L Medium Italic 16"
#    font_name="Standard Symbols L 12"
#    font_name="Nimbus Sans L Condensed 14"
#    font_name="Fixed Bold 14"
    font_name="Carlito Bold 12"
}

Use the font selection button to see what fonts, weights and sizes are available and copy a string to use when applying font style to specific objects.

Add different font specification to the frameStyle and see the results.

style "frameStyle" {
    bg[NORMAL] = "red"
    fg[NORMAL] = "maroon"
    font_name="URW Chancery L Medium Italic 18"
}

This produces the following:

The following example uses a different method to configure the window background image and specifies the pixmap_path so that images do not need to be copied to the same directory as the resource file. See some material at https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/PixmapEngine

scriptName=ex24
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKRC_LOCATION=/tmp

GTKDIALOG=gtkdialog

echo '

pixmap_path "/usr/share/backgrounds/cosmos/:/usr/share/backgrounds/nature/:/usr/share/backgrounds/scenery/:/usr/share/icons/gnome/scalable/actions"

style "windowStyle" {
  engine "pixmap" {
    image
      {
          function        = FLAT_BOX
          file            = "Garden.jpg"
#          file            = "gtk-execute.svg"
#          file            = "list-remove.svg"
#          file            = "media-playback-pause.svg"
          border          = { 0, 0, 0, 0 }
          stretch         = TRUE
          overlay_file    = "media-playback-pause.svg"
          overlay_stretch = FALSE
      }
  }
}

#widget "MyWindow" style "windowStyle"
widget_class "<GtkWindow>*" style "windowStyle"

' > ${GTKRC_LOCATION}/gtkrc_mono
export GTK2_RC_FILES=${GTKRC_LOCATION}/gtkrc_mono

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    border-width="5"
    name="MyWindow"
> 
    <vbox>
        <frame   Description  >
            <text name="MyText">
                <label>This is an example window.</label>
            </text>
        </frame>
        <hbox>
            <button name="ButtonExit" use-underline="true" width-request="100" has-focus="true">
                <label> _Quit </label>
                <input file icon="gtk-quit"></input>
                <width>16</width>
                <action function="exit">vWindow</action>
            </button>
            <button name="ButtonCancel" use-underline="true" width-request="100">
                <label> _Cancel </label>
                <input file icon="gtk-cancel"></input>
                <width>16</width>
                <action function="closewindow">vWindow</action>
            </button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action>
</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

This produces the following (note the “Pause” image over the top of the Garden image. I expected this image to repeat but it did not and there is no information on whether it can and how to make it.

We used the “pixmap” engine in the example above. That implies that there are other engines so set’s have a go at different theme engines to see what outcomes we will get.

Let’s install gtk2-engines* package.

sudo yum -y install gtk2-engines*

The following engines are now available.

ls -c1 /usr/lib64/gtk-2.0/2.10.0/engines | sort

libclearlooks.so
libcrux-engine.so
libglide.so
libhcengine.so
libindustrial.so
libmist.so
libpixmap.so
libredmond95.so
libsvg.so
libthinice.so

To work out the name of the engine strip the leading “lib” and the trailing “.so” and use what’s left.

Explore the results of executing the following example while successively uncommenting the different engine. The quick test of the differences is the dialog box which is produced after clicking on the Font button.

scriptName=ex25
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKRC_LOCATION=/tmp

GTKDIALOG=gtkdialog

echo '

pixmap_path "/usr/share/backgrounds/cosmos/:/usr/share/backgrounds/nature/:/usr/share/backgrounds/scenery/:/usr/share/icons/gnome/scalable/actions"

style "windowStyle" {
  # from /usr/lib64/gtk-2.0/2.10.0/engines
#  engine "clearlooks" {}
#  engine "crux-engine" {}
#  engine "glide" {}
#  engine "hcengine" {}
#  engine "industrial" {}
#  engine "mist" {} # https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/MistEngine
#  engine "pixmap" {} # https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/PixmapEngine
  engine "redmond95" {}
#  engine "thinice" {}
}

#widget "MyWindow" style "windowStyle"
widget_class "<GtkWindow>*" style "windowStyle"

' > ${GTKRC_LOCATION}/gtkrc_mono
export GTK2_RC_FILES=${GTKRC_LOCATION}/gtkrc_mono

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    border-width="5"
    name="MyWindow"
> 
    <vbox>
        <frame   Description  >
            <text name="MyText">
                <label>This is an example window.</label>
            </text>
        </frame>
        <hbox>
            <fontbutton></fontbutton>
            <button name="ButtonExit" use-underline="true" width-request="100" has-focus="true">
                <label> _Quit </label>
                <input file icon="gtk-quit"></input>
                <width>16</width>
                <action function="exit">vWindow</action>
            </button>
            <button name="ButtonCancel" use-underline="true" width-request="100">
                <label> _Cancel </label>
                <input file icon="gtk-cancel"></input>
                <width>16</width>
                <action function="closewindow">vWindow</action>
            </button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action>
</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

With the redmond95 engine I see something like this:

With the glide engine I see something like:

With clearlooks I see something like:

Unfortunately I could not find much information on what configuration options are available for each of these engines. About the most I could find was for the pixmap engine. Redmond95 is said to have no configuration options. I was not able to find any information about the industrial engine.

If you are inclined to explore the gtk themes there some information on the topic on the Internet. I did not follow up on this to any great extent as it si only marginally relevant to what I am trying to do in this series of articles.

There is some material on this topic at http://www.orford.org/gtk, particularly section on fonts.

https://git.enlightenment.org/themes/detourious.git/plain/gtk/detourious/gtk-2.0/gtkrc has a huge set of property specs which could be of interest for experimentation. Inspect what that you see there and have a go at styling the example. For example, change the style and target definitions in the example above to read as follows and see what you can see. Experiment with changing the target from widget_class to widget and changing foreground and background colours.

style "windowStyle" {
  # from /usr/lib64/gtk-2.0/2.10.0/engines
  engine "clearlooks" {}
#  engine "crux-engine" {}
#  engine "glide" {}
#  engine "hcengine" {}
#  engine "industrial" {}
#  engine "mist" {} # https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/MistEngine
#  engine "pixmap" {} # https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/PixmapEngine
#  engine "redmond95" {}
#  engine "thinice" {}

    base[NORMAL]      = "#ff0000"
    base[PRELIGHT]    = "#ffff00"
    base[ACTIVE]      = "#ff00ff"
    base[SELECTED]    = "#00ff00"
    base[INSENSITIVE] = "#0000ff"

#    fg[NORMAL]      = "#ff0000"
#    fg[PRELIGHT]    = "#ffff00"
#    fg[ACTIVE]      = "#ff00ff"
#    fg[SELECTED]    = "#00ff00"
#    fg[INSENSITIVE] = "#0000ff"

    bg[NORMAL]      = "#ff0000"
    bg[PRELIGHT]    = "#ffff00"
    bg[ACTIVE]      = "#ff00ff"
    bg[SELECTED]    = "#00ff00"
    bg[INSENSITIVE] = "#0000ff"

}

#widget "MyWindow" style "windowStyle"
widget_class "<GtkWindow>*" style "windowStyle"

I see the following:

There are more examples at https://people.kth.se/~e95_fla/ex/gtkrc and, undoubtedly, elsewhere.

Naming Style Targets

It is possible and I imagine quite desirable to be able to apply specific style to an individual component – say a label in a text object, the title of the frame object and similar.

Examples shown so far use the style definitions to define styles and associate these styles with specific objects by name (widget), specific widget “collections” (widget_class) or specific classes of widget (class).

Named Targets

The ‘widget “name” style “style-name”‘ assignment cause the named style to be applied to a named object. Consider example ex23. As given it produces the following look:

This is accomplished with the following specification that went into the gtk resource file:

style "windowStyle" {
    bg[NORMAL] = "lightblue"
    fg[NORMAL] = "darkblue"
    font_name="Carlito Bold 12"
}

style "buttonStyle" {
    bg[NORMAL] = "green"
    fg[NORMAL] = "brown"
}   

style "frameStyle" {
    bg[NORMAL] = "red"
    fg[NORMAL] = "maroon"
}   

widget_class "<GtkWindow>*" style "windowStyle"
class "GtkButton" style : highest "buttonStyle"
widget_class "*.GtkFrame.GtkLabel" style "frameStyle"
class "GtkFrame" style : highest "frameStyle"

Our GUI definition starts like this:
<window 
    title="My Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    border-width="5"
    name="MyWindow"
> 
...

Let’s modify the style and target definitions to read:

style "windowStyle" {
    bg[NORMAL] = "lightblue"
    fg[NORMAL] = "darkblue"
    font_name="Carlito Bold 12"
}

style "buttonStyle" {
    bg[NORMAL] = "green"
    fg[NORMAL] = "brown"
}   

style "frameStyle" {
    bg[NORMAL] = "red"
    fg[NORMAL] = "maroon"
}   

widget "MyWindow" style "windowStyle"
##widget_class "<GtkWindow>*" style "windowStyle"
##class "GtkButton" style : highest "buttonStyle"
##widget_class "*.GtkFrame.GtkLabel" style "frameStyle"
##class "GtkFrame" style : highest "frameStyle"

Executing the example with this change produces:

Because we are assigning the windowStyle to the object whose name is “MyWindow” the style only applies to that object. The window gets a light blue background but neither foreground colour nor font produce visible effects. This is because the window object does not have any elements to which foreground or font style directives can be applied.

This is an example of styling named objects.

Please note that styles are merged according to a set of built in rules so the effect you get may not be the effect you expect. This is discussed in passing elsewhere in this article but not formally or completely. Some experimentation will be required and some frustration is to be expected.

Containment Hierarchy Targets

Let’s say that we want to apply the foreground and background colours to all objects with components to which foreground and background colours can be applied, starting with the window object and going down the containment hierarch.

Change the style assignment definition to read:

##widget "MyWindow" style "windowStyle"
widget_class "<GtkWindow>*" style "windowStyle"
##class "GtkButton" style : highest "buttonStyle"
##widget_class "*.GtkFrame.GtkLabel" style "frameStyle"
##class "GtkFrame" style : highest "frameStyle"

Note the syntax: ‘<GtkWindow>*‘. Here the trailing asterisk means ‘and all down the hierarchy’

This produces the following:

Dark blue foreground colour has been applied to every component within the window containment hierarchy which has an element to which foreground colour can be applied. In this case these are labels of the text and button objects.

Light blue background colour has been applied to every component within the window containment hierarchy which has an element to which background colour can be applied. In this case these are the window background and the ‘border’ of the frame component.

Change the widget_class target to ‘<GtkWindow><GtkVBox><GtkFrame>*‘ and execute the example. This produces the following:

Note that the window colour reverted to the default as did the colour of the button labels text. This is because we explicitly targeted the style at the frame object and its content.

Let’s zoom in a bit more into the frame and apply styling to just the frame title with the following syntax: ‘<GtkWindow><GtkVBox><GtkFrame><GtkLabel>‘. Note that we explicitly target just the frame label and nothing else. Executing the example produces the following:

As we would expect only the frame title is explicitly styled.

This discussion introduces, in passing, the object hierarchy, or as I am calling it the containment hierarchy. Frame label is contained within the frame, which is contained within the vbox, which is contained within the window. This is almost the explicit hierarchy we have in our GUI definition in the example:

<window 
    title="My Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    border-width="5"
    name="MyWindow"
> 
    <vbox>
        <frame   Description  >
            <text name="MyText">
                <label>This is an example window.</label>
            </text>
        </frame>
        ...

“Almost” because the “label” (GtkLabel) object is not explicitly specified in the definition of the frame so one has to know or guess. Compare this to the definition of the text object in which label is explicitly defined.

One way to not have to know or guess is to specify the asterisk instead of <GtkLabel> in the target specification but that would style the frame label and everything else that takes foreground and background colour and is contained inside the frame as shown in the previous use case.

Let’s try the following – ‘<GtkWindow><GtkVBox><GtkFrame><GtkText><GtkLabel>‘. Executing the example with this change produces a plain window with no styling explicitly applied to any element.

Hang on, why is this not working? This is the object hierarchy, right? The GUI definition says so!

Well, here is where knowing to look at the “Widget Construction” section at the developer documentation at http://www.murga-linux.com/puppy/viewtopic.php?t=69188&start=2 may give clues as to what might be happening. See, for example, discussion of how the various button types are constructed, paying attention to the containment hierarchy. To quote an instance:

<button> containing a label and an image is a GtkButton containing a GtkHBox or GtkVBox itself containing a GtkLabel and GtkImage (stock images are loaded by a dedicated function and hardcoded to GTK_ICON_SIZE_BUTTON)

Right. With this hint we can perhaps deduce that the text object is actually a GtkHBox or a GtkVBox containing the GtkLabel object and we could try the following, in turn:

widget_class "<GtkWindow><GtkVBox><GtkFrame><GtkHBox><GtkLabel>" style "windowStyle"

Nope.

widget_class "<GtkWindow><GtkVBox><GtkFrame><GtkVBox><GtkLabel>" style "windowStyle"

Bingo! Only the inner text label got styled so this is the precise target specification for the label of the text object.

Note in passing that even though we have a background colour defined the label does not have a visible background.

Let’s see if the GtkVBox has a colourable background:

widget_class "<GtkWindow><GtkVBox><GtkFrame><GtkVBox>" style "windowStyle"

Nope. My experience is that neither HBox nor VBox have backgrounds that can be coloured.

So how would one go about providing a colour background to a label?

Let’s change the definition of the content of the frame to read as follows:

...
    name="MyWindow"
> 
    <vbox>
        <frame   Description  >
            <eventbox>
                <text name="MyText">
                    <label>This is an example window.</label>
                </text>
            </eventbox>
        </frame>
        ...

Let’s change the styling target to read:

widget_class "<GtkWindow><GtkVBox><GtkFrame><GtkVBox><GtkEventBox>" style "windowStyle"

Notice what is happening. The frame contains the inner vbox which contains whatever goes inside the frame. All the same, the <eventbox> object, which is normally invisible, can have its background coloured, and by extension can be used to apply styles to the objects it contains as would be achieved with the addition of the trailing asterisk to the specification.

Executing the example with this change produces the following:

The label now has background colour.

The bottom line here is that using precise widget_class targets requires the knowledge of how the hierarchy is implemented (see the web page quoted above), and some guesswork and experimentation, like in the case of a label within text within frame.

Targeting Classes

Finally, one can apply style classes of objects.

Let’s try the following change:

style "windowStyle" {
    bg[NORMAL] = "lightblue"
    fg[NORMAL] = "darkblue"
}
style "buttonStyle" {
    bg[NORMAL] = "green"
    fg[NORMAL] = "brown"
}   
style "frameStyle" {
    bg[NORMAL] = "red"
    fg[NORMAL] = "maroon"
}   
style "labelStyle" {
    fg[NORMAL] = "darkblue"
    font_name="Bitstream Charter Italic 10"
}    

widget_class "<GtkWindow><GtkVBox><GtkFrame><GtkVBox><GtkEventBox>" style "windowStyle"
class "GtkButton" style : highest "buttonStyle"
class "GtkFrame" style : highest "frameStyle"
class "GtkLabel" style "labelStyle"

Executing the modified example produces the following:

The class target targets all objects of the class, applying the same style to all.

Note the “style : highest” notation. This explicitly overrides the default style merge mechanism, somewhat discussed under the heading “binding styles to widget classes:” in http://www.orford.org/gtk/, and under the heading of “Priority” in https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes.

Though the document at http://www.orford.org/gtk/ is entitles “Gtk2 Theme Creation Guide” it is actually quite enlightening for anyone who wants to style objects in gtkdialog-based applications, as I have been doing in this article. The “GTK Theming Tutorial” at https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes is similarly useful in this context even tough it might appear off-topic at first glance.

Gtkrc Examples

Finally, review the gtkrc files for the various themes to see what you can see there and to see if any of it might be of use to you when styling gtkdialog widgets.

ls -C1 /usr/share/themes/*/gtk-2.0/gtkrc | sort

/usr/share/themes/ClearlooksClassic/gtk-2.0/gtkrc
/usr/share/themes/Clearlooks/gtk-2.0/gtkrc
/usr/share/themes/Crux/gtk-2.0/gtkrc
/usr/share/themes/Glider/gtk-2.0/gtkrc
/usr/share/themes/Glossy/gtk-2.0/gtkrc
/usr/share/themes/HighContrast/gtk-2.0/gtkrc
/usr/share/themes/HighContrastInverse/gtk-2.0/gtkrc
/usr/share/themes/HighContrastLargePrint/gtk-2.0/gtkrc
/usr/share/themes/HighContrastLargePrintInverse/gtk-2.0/gtkrc
/usr/share/themes/Industrial/gtk-2.0/gtkrc
/usr/share/themes/Inverted/gtk-2.0/gtkrc
/usr/share/themes/LargePrint/gtk-2.0/gtkrc
/usr/share/themes/LowContrast/gtk-2.0/gtkrc
/usr/share/themes/LowContrastLargePrint/gtk-2.0/gtkrc
/usr/share/themes/Mist/gtk-2.0/gtkrc
/usr/share/themes/Raleigh/gtk-2.0/gtkrc
/usr/share/themes/Simple/gtk-2.0/gtkrc
/usr/share/themes/Slider/gtk-2.0/gtkrc
/usr/share/themes/ThinIce/gtk-2.0/gtkrc

Tools for exploring widget styling and colours

gtk2-styles wizard

Andrew Karuse, who published the book “Foundations of GTK+ Development” (http://www.apress.com/us/book/9781590597934), made available at https://github.com/grayasm/git-main/tree/master/tutorial/andrew_krause_gtk%2B/13_all_together the source and related resources for a C++ application which allows one to visually work with GTK styles for the various GTK widgets and save the resulting GTK resources to a file. This in turn allows one to get the exact syntax needed to implement these styles for the various widgets.

There is a YouTube video on this: https://youtu.be/EzkQAbP4My8. Watch the video to see how to get and build the wizard, and how to use it construct a valid gtkrc resource file that can be used with gtkdialog.

I have not been able to find an archive containing the sources and resources for the convenience of the downloader and the zip archive downloadable from the publisher’s book site does not have this application. While this makes life a bit more difficult it is still possible to get and build the application.

The link quoted above gets one to this:

Download each file, one at a time, to a convenient directory, say gtk2-styles. Make sure to follow the links until you see the raw source or the image and download these.

cd ./gtk2-styles

In gtk2-styles.cpp change the declaration of the const char* rcfile so that it does not initialise. If it does the make will fail with C++ errors.

struct AppData
{
//     const char* rcfile=NULL;
       const char* rcfile;

Build the application

make -k

Run the application

./gtk2-styles

Change styles of things for which you want to change styles then File->Save As the file.

Copy the styles you changed into a gtkrc file which you use at runtime.

Here is an example of what the application looks like for a GtkButton:

Note the following:

One can change colours (click on the colour box and one will get the usual colour picker) and the changes will be immediately reflected in the UI.
One can change the numeric values for the various properties and the changes will be immediately reflected in the UI.
Once can check and uncheck the checkboxes and the changes will be immediately reflected in the UI.
One can hover over the buttons and click them to see the results of changes.

Explore the application and then File-Save As to a file to see what a gtkrc file would look like with the changes you made to the styles provided by the default theme. Note that the saved file will contain definitions for all the objects. If you make small changes use just the changes in your gtkdialog application’s rc file.

Note that if you do not make any changes and save the rc file it will be empty.

gpick Colour Picker

Sometimes one might want to match colours of the various elements in one’s application with colours in used in some other application. For example I had an occasion recently to build a gtkdialog-based applicaiotn that would invoke a filrefox with a web page which used specific colours for specific elements like table headers and fonts. To match the colour scheme I needed to know the hex values of the specific colours. The handy tool I found on line is the gpick colour picker. It is available at http://www.gpick.org/. The source distribution requires a bunch of tools to build so rather than building from sources I opted for finding and downloading the pre-built rpm.

cd ~/Downloads
wget ftp://fr2.rpmfind.net/linux/epel/6/x86_64/gpick-0.2.4-4.el6.x86_64.rpm
sudo yum localinstall -y gpick-0.2.4-4.el6.x86_64.rpm

gpick window looks like this when first started:

Note the Hex value of the colour under the cursor, which is what I was after. There are a bunch of options and functionality I did not go into. Explore.

Tagged with: bash gtkdialog • bash GUI • CentOS • create demo • create demonstration • demo • demonstration • GTK • GTK GUI • gtkdialog • gtkdialog background • gtkdialog bash • gtkdialog color • gtkdialog colour • gtkdialog comments • gtkdialog documentation • gtkdialog examples • gtkdialog reference • gtkdialog structure • gtkdialog styles • gtkdialog styling • gtkdialog visual styles • infrastructure demo • infrastructure demonstration • Linux demo • Linux demo image • Linux demonstration image • Linux GUI • Linux UI • technical demo • technical demonstration

Apr 09

gtkdialog – Exploring the Window object attributes and actions by example

By Czapski Michael gtkdialog No Comments »

In this article I explore the gtkdialog Window object, its attributes and actions. In passing. other gtkdialog objects will be used without much elaboration, that elaboration intended to follow in subsequent articles.

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.

It appears that gtkdialog, based as it seems to be on the GTK object model, leverages the GTK object hierarchy. Consider the reference for the Window object at http://01micko.com/reference/window.html.

The very first link points to a GtkWindow – http://developer.gnome.org/gtk2/2.24/GtkWindow.html.

In the GTK object hierarchy, https://developer.gnome.org/gtk2/2.24/GtkWindow.html#GtkWindow.object-hierarchy, the Window object is several levels below the GObject, the topmost object.

As briefly discussed in the previous article the GtkWindow, and consequently the gtkdialog Window, object inherit, as I understand it, from the objects higher up in the hierarchy. This will come into play when we explore attributes that can be set for a Window, and actions that can be configured for a Window.

Pre-Requisites

Window Object Attributes

The gtkdialog Window object is the outermost visible object in the hierarchy of gtkdialog objects.

We explored the window object to an extent in the previous article, while setting the context and discussing comments and similar matters. Let’s now explore the Window object attributes more.

Reference documentation for the gtkdialog Window object, http://01micko.com/reference/window.html, provides a table of attributes specific to this gtkdialog object and makes a reference to ancestor class properties.

Attributes that can be configured for the window widget are defined in the widget’s reference page see https://developer.gnome.org/gtk2/2.24/GtkWindow.html#GtkWindow.object-hierarchy, section Properties – https://developer.gnome.org/gtk2/2.24/GtkWindow.html#GtkWindow.properties

Some of them are useful and some of them are not, as far as I am concerned or can empirically determine. Changing values of some of them do not have visible consequences.

Not all attributes/properties are recognised and acted upon by gtkdialog. Some of the properties are inherited from the parent objects, like GtkContainer and GtkWidget. For example, border-width, which defines the amount of space between the window frame and the window content, is inherited from the GtkContainer.

Similarly, sensitive property is inherited from the GtkWidget and when set to true effectively disables everything inside the window, except for the window decorations like minimise, maximise and close. An “interesting” side effect of this is that setting sensitive to false and decorated to false will take away the means of closing the window except by killing the process which created the window 🙂

Properties like window-position take one of the pre-defined enumeration values.

For window-position see https://developer.gnome.org/gtk2/2.24/gtk2-Standard-Enumerations.html#GtkWindowPosition or http://gtk.php.net/manual/en/html/gtk/gtk.enum.windowposition.html (which is not directly related to gtkdialog as I use it but seems a good enough source of enumerations which GTK defines and supports.

By the way, tooltip-markup causes warnings to be emitted to the console, which, apart from being ugly, appear benign.

See the reference page: file:///home/demo/gtkdialog-0.8.3/doc/reference/window.html

To work out what attributes are actually supported, in this case by the window widget, we need to do some exploration. Discussion below goes into this to an extent and I provided most of the useful attributes that can be set, both from GtkWindow itself and inherited from GtkContainer and GtkWidget.

Let me reproduce the table and expand it to include inherited attributes which empirical observation leads me to believe have a visual impact on the window object.

The table below summarised Window attributes/properties and indicates which work with the gtkdialog and which do not as far as I can tell. “Do not” may well be a function of me not seeing any visible difference with the property set to different values. Some ancestor attributes/properties which are not really useable from gtkdialog are omitted.

Name	Description	Value	Default	From	Since	OK?
image-name	Image filename I could not figure out what this does for a Window object.			gtkdialog	0.8.1
block-function-signals	Block signal emissions from functions I am not quite sure what this does for a Window object. See reference for where this comes from. Perhaps you will get it. http://www.murga-linux.com/puppy/viewtopic.php?p=544704#544704	true or false	false	gtkdialog	0.7.21
file-monitor	Emit signal when input file(s) change If a file is specified as the value of the window’s <input file>xxxx</input> directive, and this property is set to true, and the content of the file changes then the signal of type “file-changed” will be emitted. If an <action signal=”file-changed”>xxx</action> or its variant is defined then the action will be executed.	true or false	false	gtkdialog	0.8.1	Y
auto-refresh	Auto refresh when input file(s) change. If a file is specified as the value of the window’s <input file>xxxx</input> directive, and this property is set to true, and the content of the file changes then the window’s title bar text will automatically display the content of the file (or some reasonable leading part of it). If this property is false then the input file change will not be reflected in the title bar.	true or false	false	gtkdialog	0.8.1	Y

accept-focus	Whether the window should receive the input focus. The title bar is greyed out on false but objects inside the window are still active, for example, buttons are clickable on and do their thing, but keystrokes are not delivered to the window.	true or false	true	GtkWindow		Y
allow-grow	If TRUE, users can expand the window beyond its minimum size.	true or false	true	GtkWindow		Y
allow-shrink	If TRUE, the window has no minimum size. Setting this to TRUE seems pretty useless and perhaps unfriendly.	true or false	true	GtkWindow		Y
decorated	Whether the window should be decorated by the window manager, that is whether it should have the title bar and the various buttons typically present there.	true or false	true	GtkWindow		Y
default-height	The default height of the window, used when initially showing the window. Must be >= -1. The value of this attribute overrides the height-request value if one is specified.	integer	-1	GtkWindow		Y
default-width	The default width of the window, used when initially showing the window. Must be >= -1. The value of this attribute overrides the width-request value if one is specified.	integer	-1	GtkWindow		Y
deletable	Whether the window frame should have a close button.	true or false	true	GtkWindow		Y
icon-name	The icon-name property specifies the name of the themed icon to use as the window icon.	File path		GtkWindow		Y
mnemonics-visible	Whether mnemonics are currently visible in this window. If buttons are defined and have “use-underline” attribute set to true and a mnemonic indicated with the “_” before the character in the label, or are “standard” buttons like OK or cancel, the indicated or default letter in the label will be underlined when the window is drawn if this property is set to true.	true or false	false	GtkWindow		Y
resizable	If TRUE, users can resize the window.	true or false	true	GtkWindow		Y
skip-pager-hint	TRUE if the window should not be shown in the pager.	true or false	false	GtkWindow		?
skip-taskbar-hint	TRUE if the window should not be shown in the task bar	true or false	false	GtkWindow		Y
title	The title of the window. Overwritten by the <label>…</label> directive if one is specified	string		GtkWindow		Y
type-hint	These are hints for the window manager that indicate what type of function the window has. The window manager can use this when determining decoration and behaviour of the window. See enumerations – link below. Does not seem useful in the gtkdialog context.	integer	0	GtkWindow		Y
window-position	The initial position of the window GTK_WIN_POS_NONE=0 GTK_WIN_POS_CENTER=1 GTK_WIN_POS_MOUSE=2	Integer [0..2]	0	GtkWindow		Y

border-width	The amount of whitespace between the window frame and the content of the window	Integer	5	GtkContainer		Y

can-default	Whether the widget can be the default widget. This does not seem to have any effect when applied to a Window object	true or false	false	GtkWidget		?
can-focus	Whether the widget can accept the input focus. This does not seem to have any effect when applied to a Window object	true or false	false	GtkWidget		?
has-default	Whether the widget is the default widget. This does not seem to have any effect when applied to a Window object	true or false	false	GtkWidget		?
has-focus	Whether the widget has the input focus. This does not seem to have any effect when applied to a Window object	true or false	false	GtkWidget		?
has-tooltip	Whether this widget has a tooltip. Disables tooltip display if tooltip is defined for the Window	true or false	false	GtkWidget		Y
height-request	Override for height request of the widget, or -1 if natural height should be used. Has not effect of default-height is specified.	>=0	-1	GtkWidget		Y
is-focus	Whether the widget is the focus widget within the toplevel. Does not seem to have any effect when applied to the Window object	true or false	false	GtkWidget		?
name	The name of the widget. Nothing visible happens when this attribute is provided with a value.	string	NULL	GtkWidget		?
receives-default	If TRUE, the widget will receive the default action when it is focused. I don’t know what that is supposed to accomplish. Nothing visible happens regardless of the property value.	true or false	false	GtkWidget		?
sensitive	Whether the widget responds to input. FALSE disables all components contained in the window.	true or false	TRUE	GtkWidget		Y
style		GtkStyle		GtkWidget		???
tooltip-markup	The contents of the tooltip for this widget. Simple markup can be used to call out parts of tooltip text in. See http://www.murga-linux.com/puppy/viewtopic.php?t=40418 for a markup explorer tool. Ineffective if tooltip-disabled is TRUE.	string	NULL	GtkWidget		Y
tooltip-text	The contents of the tooltip for this widget. Ineffective if tooltip-disabled is TRUE.	string	NULL	GtkWidget		Y
visible	Whether the widget is visible. It is somewhat self-defeating to make a window invisible on creation unless it is a “subsidiary” window and can be made visible form some other piece of logic.	true or false	true	GtkWidget		Y
width-request	Override for width request of the widget, or -1 if natural width should be used. Has not effect if default-width is specified.	>=0	-1	GtkWidget		Y

The following example includes just about every attribute that can be defined for a Window object. Experiment with the various settings to see what you can see.

scriptName=ex09
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
echo "$(date)"
}
export -f fnEchoDateTime

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2


MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    decorated="true" this="shows the title bar and its nprmal decorations"
    allow-grow="true" this="can resize to be bigger"
    allow-shrink="true" this="can resize to be smaller - including making it practically invisible"
    xx-default-height="200" remove="xx- to enable the attribute and see how that affects height-request"
    xx-default-width="400" remove="xx- to enable the attribute and see how that affects width-request"
    resizable="true" xx-resizable="overrides default-height and default-width if set to false"  this="works"
    deletable="true" xx-deletable="this keep (default) or remove the close button" this="works"
    icon-name="gtk-apply" this="works - shows designated icon at the left of the title bar"
    modal="false" this="does not seem to be doing anything different on true and on false"
    skip-pager-hint="true" this="does not seem to be doing anything different on tru and on false"
    skip-taskbar-hint="false" this="seems to be preventing the window being listed in the window selector when true"
    title="My First Window" this="is selfexplanatory and works"
    window-position="${GTK_WIN_POS_CENTER}"
    border-width="5" xx-border-width="is an inherited GtkContainer property - see object hierarchy at https://developer.gnome.org/gtk2/2.24/GtkWindow.html#GtkWindow.object-hierarchy"
    sensitive="true" xx-sensitive="is an inherited GtkWidget property that disables everything inside the window - see obect hierarchy"
    tooltip-markup="<span size='small'>This is a <b>window tooltip</b></span>"
    icon="gimp" this="does not do anything visible"
    mnemonics-visible="false" this="if buttons have underline for menemonics or are standard buttons mnemonics are initially underlined"
    accept-focus="true" this="if false makes window not focusaable (title bar is gray) - buttons are still clickable"
    window-position="${GTK_WIN_POS_CENTER}"
    auto-refresh="false" goes="with <input file>somefile</input>"
    border-width="5"
    can-default="false"
    can-focus="false"
    can-default="false"
    has-focus="false"
    has-tooltip="true"
    height-request="150" does="not have any effect if default-height is specified"
    width-request="400" does="not have any effect if default-width is specified"
    is-focus="true"
    name="myWindow"
    receives-focus="false"
    sensitive="true"
    xx-tooltip-text="This is a <b>window tooltip</b>"
    visible="true"
>
    <vbox>
        <frame   Description  >
            <text label="This is an example window."></text>
        </frame>
        <hbox>
            <button use-underline="true" tooltip-text="Refresh window variable - update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <label>Window Label</label>
    <variable>vWindow</variable>
    <input>fnEchoDateTime</input>
$(:<<'COMMENT'
    <input file>/tmp/aa.txt</input>
COMMENT
)
    
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 

</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

See https://github.com/GNOME/gtk/blob/master/gdk/gdktypes.h for enumerations.

Window Object Directives

Note that the window defines a bunch of window specific child objects, which the reference calls directives – label, variable, input, etc.. These must be specified after all the other window child objects else gtkdialog will throw a hissy fit.

The label directive provides window title if title attribute is not set. If it is set the label directive is ignored. Consider:

scriptName=ex10
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
echo "$(date)"
}
export -f fnEchoDateTime

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My First Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
>
    <vbox>
        <frame   Description  >
            <text label="This is an example window."></text>
        </frame>
        <hbox>
            <button use-underline="true" tooltip-text="Refresh window variable - update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <label>Window Label</label>
    <variable>vWindow</variable>
$(:<<'COMMENT'
    <input>fnEchoDateTime</input>
    <input file>/tmp/aa.txt</input>
COMMENT
)
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 

</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

Consider a variant where the title attribute to the Window object is not provided.

scriptName=ex11
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
echo "$(date)"
}
export -f fnEchoDateTime

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
>
    <vbox>
        <frame   Description  >
            <text label="This is an example window."></text>
        </frame>
        <hbox>
            <button use-underline="true" tooltip-text="Refresh window variable - update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <label>Window Label</label>
    <variable>vWindow</variable>
$(:<<'COMMENT'
    <input>fnEchoDateTime</input>
    <input file>/tmp/aa.txt</input>
COMMENT
)
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 

</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 sensitive directive does the same thing as the sensitive attribute to the window tag – enables or disables window content. Consider:

scriptName=ex12
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
echo "$(date)"
}
export -f fnEchoDateTime

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
>
    <vbox>
        <frame   Description  >
            <text label="This is an example window."></text>
        </frame>
        <hbox>
            <button use-underline="true" tooltip-text="Refresh window variable - update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <label>Window Label</label>
    <sensitive>false</sensitive>
    <variable>vWindow</variable>
$(:<<'COMMENT'
    <input>fnEchoDateTime</input>
    <input file>/tmp/aa.txt</input>
COMMENT
)
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 

</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 variable directive names the variable which can be used elsewhere to reference the window and act upon it, for example disable or enable, activate or deactivate, show or hide, refresh or clear, or set title. The example below provides a variable name vWindow to allow the button’s action directive to trigger the refresh action on the window. When the refresh action signal is processed the function fnEchoDateTime will be executed and its output will be provided to the Window object which will use it to set the window title. Consider the following example. Click the Refresh button a few times with at least 1 second between clicks and see what happens to the window title.

scriptName=ex13
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
echo "$(date)"
}
export -f fnEchoDateTime

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My First Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
>
    <vbox>
        <frame   Description  >
            <text label="This is an example window."></text>
        </frame>
        <hbox>
            <button use-underline="true" tooltip-text="Refresh window variable - update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
             <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <input>fnEchoDateTime</input>

    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 

</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 input directive can invoke logic which can return a string to which the window title will be set when triggered by refresh of the variable named as the window variable. See example above. This function, as all such functions invoked by the gtkdialog, is expected to write to the stdout whatever text is supposed to be the input to the object – in this case the window title.

The output file directive will cause the “value” of this object to be written to the named file if the save action is triggered. In the case of the window object the title will be written to the file. Consider:

scriptName=ex14
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
echo "$(date)"
}
export -f fnEchoDateTime

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My First Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
>
    <vbox>
        <frame   Description  >
            <text label="This is an example window."></text>
        </frame>
        <hbox>
            <button use-underline="true" tooltip-text="Save window data">
                <label> _Save </label>
                <input file icon="gtk-save"></input>
                <width>16</width>
              <action function="save">vWindow</action>
            </button>
            <button use-underline="true" tooltip-text="Refresh window variable - update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <input>fnEchoDateTime</input>

    <output file>/tmp/gtkd.out</output>

    <action signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 

</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 action directive provides a mechanism for invoking logic when certain kinds of events affecting the window object occur. The example above used the ‘<action function="save">…</action>‘ markup to add an action to a button object, to be invoked when the button is pressed. Another example would be invoking the close window logic when ESC key is pressed. In the example above, the key-press-event signal is intercepted in the action directive and if the raw key code was (0x9), the Escape key, the gtkdialog calls the exit logic and the window is closed.

Exploring the action directive

Let’s consider the following signals, defined in the Window object reference:

Name	Description	Content	Since
action signal=”type”	Execute command on signal	Shell command
action signal=”type”	Perform function on signal	function:parameter
action signal=”type” condition=”type”	Execute command on signal conditionally	Shell command	0.8.3
action signal=”type” condition=”type”	Perform function on signal conditionally	function:parameter	0.8.3

In ex13, above, we used the “action function” and “action signal”, to save the window title to a file and to exit the application respectively. Note that the reference does not include the “action function” variant but it is supported and works, as the example illustrates.

Explore the reference for the Window object, http://01micko.com/reference/window.html, to see the signals and the functions defined in that document.

The “action condition” construct is perhaps worth exploring as it is explained what the “_is_true”/
_is_false” is supposed to return. To cut to the chase, the command or the function is supposed to return the literal text “true” or “false”. The example below extends the example above by making the save action conditional on the file not already existing. This is contrived but makes the point.

Consider:

scriptName=ex15
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
    echo "$(date)"
}
export -f fnEchoDateTime

fnAlreadySaved() {
    vFileName="${1}"
    [[ -f ${vFileName} ]] && { echo "true" ; yad --title="File ${vFileName} exists" --text="File ${vFileName} exists - not saving" --center --image="gtk-dialog-error" --window-icon="gtk-dialog-error" --width=500 --height=100 --button="gtk-ok:0"; } || echo "false"
}
export -f fnAlreadySaved


GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My First Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
>
    <vbox>
        <frame   Description  >
            <text label="This is an example window."></text>
        </frame>
        <hbox>
            <button use-underline="true" tooltip-text="Save window data">
                <label> _Save </label>
                <input file icon="gtk-save"></input>
                <width>16</width>
                <action function="save" condition="command_is_false(fnAlreadySaved /tmp/gtkd.out)">vWindow</action>
            </button>
            <button use-underline="true" tooltip-text="Refresh window variable - update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <input>fnEchoDateTime</input>

    <output file>/tmp/gtkd.out</output>

    <action signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 

</window>
EOUIDFEINITION

case ${1} in
    -d | --dump) cat ${MAIN_DIALOG_FILE} ;;
    *) gtkdialog --center --file=${MAIN_DIALOG_FILE} ;;
esac

rm -f ${MAIN_DIALOG_FILE}
EOSCRIPT

touch /tmp/gtkd.out; rm /tmp/gtkd.out; /tmp/${scriptName}.sh

Exploring “action signal” directive

Let’s explore the “action signal” directive to see what sort of signals the Window object receives.

From the reference:

There is no default signal for this widget.

The “file-changed” signal is emitted if file-monitor is true and the input file being monitored has changed.

The following signals are connected-up for all widgets:

button-press-event
button-release-event
configure-event
enter-notify-event
leave-notify-event
focus-in-event
focus-out-event
hide
show
realize
key-press-event
key-release-event
map-event
unmap-event

From examples, additional events:

delete-event
destroy-event

Consider the following example, which is based on the /home/demo/gtkdialog-0.8.3/examples/miscellaneous/signals example.

scriptName=ex16
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window title="Signals" icon-name="gtk-dialog-warning">
    <vbox>
        <frame Widgets>
            <text>
                <label>Label</label>
                <action signal="button-press-event">echo Label: button-press-event</action>
                <action signal="button-release-event">echo Label: button-release-event</action>
                <action signal="configure-event">echo Label: configure-event</action>
                <action signal="enter-notify-event">echo Label: enter-notify-event</action>
                <action signal="leave-notify-event">echo Label: leave-notify-event</action>
                <action signal="focus-in-event">echo Label: focus-in-event</action>
                <action signal="focus-out-event">echo Label: focus-out-event</action>
                <action signal="key-press-event">echo Label: key-press-event</action>
                <action signal="key-release-event">echo Label: key-release-event</action>
                <action signal="hide">echo Label: hide</action>
                <action signal="show">echo Label: show</action>
                <action signal="realize">echo Label: realize</action>
                <action signal="map-event">echo Label: map-event</action>
                <action signal="unmap-event">echo Label: unmap-event</action>
            </text>
            <entry>
                <default>Entry</default>
                <action signal="button-press-event">echo Entry: button-press_event</action>
                <action signal="button-release-event">echo Entry: button-release-event</action>
                <action signal="configure-event">echo Entry: configure-event</action>
                <action signal="enter-notify-event">echo Entry: enter-notify-event</action>
                <action signal="leave-notify-event">echo Entry: leave-notify-event</action>
                <action signal="focus-in-event">echo Entry: focus-in-event</action>
                <action signal="focus-out-event">echo Entry: focus-out-event</action>
                <action signal="key-press-event">echo Entry: key-press-event</action>
                <action signal="key-release-event">echo Entry: key-release-event</action>
                <action signal="hide">echo Entry: hide</action>
                <action signal="show">echo Entry: show</action>
                <action signal="realize">echo Entry: realize</action>
                <action signal="map-event">echo Entry: map-event</action>
                <action signal="unmap-event">echo Entry: unmap-event</action>
            </entry>
        </frame>
        <hbox>
            <button ok>
                <action signal="button-press-event">echo Button: button-press_event</action>
                <action signal="button-release-event">echo Button: button-release-event</action>
                <action signal="configure-event">echo Button: configure-event</action>
                <action signal="enter-notify-event">echo Button: enter-notify-event</action>
                <action signal="leave-notify-event">echo Button: leave-notify-event</action>
                <action signal="focus-in-event">echo Button: focus-in-event</action>
                <action signal="focus-out-event">echo Button: focus-out-event</action>
                <action signal="key-press-event">echo Button: key-press-event</action>
                <action signal="key-release-event">echo Button: key-release-event</action>
                <action signal="hide">echo Button: hide</action>
                <action signal="show">echo Button: show</action>
                <action signal="realize">echo Button: realize</action>
                <action signal="map-event">echo Button: map-event</action>
                <action signal="unmap-event">echo Button: unmap-event</action>
            </button>
        </hbox>
    </vbox>
    <action signal="button-press-event">echo Window: button-press_event</action>
    <action signal="button-release-event">echo Window: button-release-event</action>
    <action signal="configure-event">echo Window: configure-event</action>
    <action signal="delete-event">echo Window: delete-event</action>
    <action signal="destroy-event">echo Window: destroy-event</action>
    <action signal="enter-notify-event">echo Window: enter-notify-event</action>
    <action signal="leave-notify-event">echo Window: leave-notify-event</action>
    <action signal="focus-in-event">echo Window: focus-in-event</action>
    <action signal="focus-out-event">echo Window: focus-out-event</action>
    <action signal="key-press-event">echo Window: key-press-event</action>
    <action signal="key-release-event">echo Window: key-release-event</action>
    <action signal="hide">echo Window: hide</action>
    <action signal="show">echo Window: show</action>
    <action signal="realize">echo Window: realize</action>
    <action signal="map-event">echo Window: map-event</action>
    <action signal="unmap-event">echo Window: unmap-event</action>
</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

Each if the events gives rise to an opportunity to hook in logic to be executed when the event is triggered.

In examples ex15, the following stanza illustrates the handling of the key-press-event in such a way that the exit function is called conditionally if the key which was pressed was the Escape key (0x9).

<action signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action>

Exploring “action function” directive

From the reference (http://01micko.com/reference/window.html):

The following functions can be performed upon this widget by any widget capable of emitting signals:

Type	Description	Parameter	Since
enable	Sensitise widget	Variable name
disable	Desensitise widget	Variable name
show	Show widget	Variable name	0.8.1
hide	Hide widget	Variable name	0.8.1
refresh	Reload input data[1]	Variable name	0.8.1
save	Save widget data	Variable name	0.8.1
clear	Remove all widget data	Variable name	0.8.1

We used the “save” function in example ex15. Now we will consider disable, enable, hide and show functions.

Let’s consider the following example:

scriptName=ex17
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
    echo "$(date)"
}
export -f fnEchoDateTime

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My First Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
>
    <vbox>
        <frame   Description  >
            <text>
                <label>"This is an example window."</label>
                <variable>vText</variable>
            </text>
        </frame>
        <hbox>
            <button use-underline="true" tooltip-text="Hide Text">
                <label> _Hide </label>
                <variable>vBtnHide</variable>
                <action function="hide" condition="visible_is_true(vText)">vText</action>
                <action function="hide" condition="visible_is_true(vBtnHide)">vBtnHide</action>
                <action function="show" condition="visible_is_false(vBtnShow)">vBtnShow</action>
            </button>
            <button visible="false" use-underline="true" tooltip-text="Show Text">
                <label> _Show </label>
                <variable>vBtnShow</variable>
                <action function="show" condition="visible_is_false(vText)">vText</action>
                <action function="show" condition="visible_is_false(vBtnHide)">vBtnHide</action>
                <action function="hide" condition="visible_is_true(vBtnShow)">vBtnShow</action>
            </button>

            <button use-underline="true" tooltip-text="Disable Text">
                <label> _Disable </label>
                <variable>vBtnDisable</variable>
                <action function="disable" condition="sensitive_is_true(vText)">vText</action>
                <action function="hide" condition="visible_is_true(vBtnDisable)">vBtnDisable</action>
                <action function="show" condition="visible_is_false(vBtnEnable)">vBtnEnable</action>
            </button>
            <button visible="false" use-underline="true" tooltip-text="Enable Text">
                <label> _Enable </label>
                <variable>vBtnEnable</variable>
                <action function="enable" condition="sensitive_is_false(vText)">vText</action>
                <action function="show" condition="visible_is_false(vBtnDisable)">vBtnDisable</action>
                <action function="hide" condition="visible_is_true(vBtnEnable)">vBtnEnable</action>
            </button>

            <button use-underline="true" tooltip-text="update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <input>fnEchoDateTime</input>

    <output file>/tmp/gtkd.out</output>

    <action signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 

</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

In the script above we are not hiding/showing and enabling/disabling the window, as we might, because as soon as we hide the window it will disappear and as soon as we disable it we will not be able to do anything to it except close it using the close “button” in the title bar. We are, instead, jumping ahead a bit, hiding and showing the text object and enabling and disabling the text object. This example also demonstrates how a “toggle” button can be implemented, in this case by alternately hiding and showing two different buttons (hide and show, disable/enable). The end-user impression will be that a single button changes the label and the button function on click (hide/how, disable/enable).

To see how to hide/show and disable/enable the window object consider the following, not particularly useful in practice, example:

scriptName=ex18
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
    echo "$(date)"
}
export -f fnEchoDateTime

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My First Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
>
    <vbox>
        <frame   Description  >
            <text>
                <label>"Click Hide or Disable and wait up to 5 seconds for the timer to trigger the reversal of the action."</label>
                <variable>vText</variable>
            </text>
        </frame>
        <hbox>
            <timer sensitive="false" milliseconds="true" interval="5000" visible="false" disabled="true">
                <variable>tmr0</variable>
                <action>show:vWindow</action>
            </timer>
            <timer sensitive="false" milliseconds="true" interval="5000" visible="false" disabled="true">
                <variable>tmr1</variable>
                <action>enable:vWindow</action>
            </timer>
            <button use-underline="true" tooltip-text="Hide Window">
                <label> _Hide </label>
                <action function="hide" condition="visible_is_true(vWindow)">vWindow</action>
                <action function="enable" condition="sensitive_is_false(tmr0)">tmr0</action>
            </button>
            <button use-underline="true" tooltip-text="Disable Window">
                <label> _Disable </label>
                <action function="disable" condition="sensitive_is_true(vWindow)">vWindow</action>
                <action function="enable" condition="sensitive_is_false(tmr1)">tmr1</action>
            </button>
            <button use-underline="true" tooltip-text="update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <input>fnEchoDateTime</input>

    <output file>/tmp/gtkd.out</output>

    <action signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 

</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

In the script above we are jumping ahead a bit and using timers to trigger events that will show the hidden window and enable the disabled content after an interval.

Perhaps provision of a bit of context is in order at this point for no other reason than to make the basic action processing explicit.

Consider the two actions defined for the Hide button.

<action function="hide" condition="visible_is_true(vWindow)">vWindow</action>

<action function="enable" condition="sensitive_is_false(tmr0)">tmr0</action>

The first action will hide the window. The condition “visible_is_true(vWindow)” is superfluous in this case because the button will only be visible if the window is visible but it is there as an example of a conditional action.

The second action will enable a timer which will trigger its own action to reverse the effect of the button press on the Window object after an interval of up to 5 seconds.

Unless told otherwise, of which in a later article, the button press will cause the two actions to be executed one after the other. There are some circumstances in which execution of an action in the action list will prevent actions defined after it being executed but these are rare circumstances, which will be discussed in a subsequent article. One can have several actions which a button press will trigger. Other active objects can have actions as well, as can be seen with the timer objects and will be also seen in subsequent articles in which other objects are discussed and used.

For the time being one can assume that all actions defined for an object, like a window or a button, will get evaluated sequentially and will be executed if appropriate (like for example if the condition is met).

The style attribute does nothing visible. It is quite likely that I don’t know how to define a style. There is an alternative way to “style” objects which works in some instances and can be used as appropriate.

Consider the following example:

scriptName=ex19
touch /tmp/${scriptName}.sh
chmod ug+x /tmp/${scriptName}.sh

cat <<-'EOSCRIPT' > /tmp/${scriptName}.sh
#!/bin/bash

GTKDIALOG=gtkdialog

fnEchoDateTime() {
echo "$(date)"
}
export -f fnEchoDateTime

echo '
style "bgWhite" { bg[NORMAL] = "#FFFFFF" }
style "fgWhite" { fg[NORMAL] = "#FFFFFF" }
style "bgBlack" { bg[NORMAL] = "#000000" }
style "bgRed" { bg[NORMAL] = "#FF0000" }
style "fgRed" { fg[NORMAL] = "#FF0000" }
style "bgGreen" { bg[NORMAL] = "#FFFF00" }
style "fgGreen" { fg[NORMAL] = "#FFFF00" }
style "bgBlue" { bg[NORMAL] = "#0000FF" }
style "fgBlue" { fg[NORMAL] = "#0000FF" }

widget "MyWindowBg" style "bgBlack"
widget "MyWindowBg.GtkVBox.GtkHBox.MyButtonBg" style "bgGreen"

widget "MyWindowBg.GtkVBox.myEVB" style "bgBlue"

widget_class "*<GtkFrame>.GtkLabel" style "fgWhite"
widget_class "*<GtkFrame>.*.GtkLabel" style "fgGreen"
widget_class "*<GtkButton>.*.GtkLabel" style "fgRed"

' > /tmp/gtkrc_mono 
export GTK2_RC_FILES=/tmp/gtkrc_mono

GTK_WIN_POS_NONE=0
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2

MAIN_DIALOG_FILE=${0}.gtkd
cat <<-EOUIDFEINITION > ${MAIN_DIALOG_FILE}
<window 
    title="My First Window"
    window-position="${GTK_WIN_POS_CENTER}"
    default-width="400"
    name="MyWindowBg"
>
    <vbox>
        <eventbox name="myEVB" above-child="false" visible-window="true">
        <frame   Description  >
            <text><label>This is an example window.</label></text>
        </frame>
        </eventbox>
        <hbox>
            <button name="MyButtonBg" use-underline="true" tooltip-text="Refresh window variable - update date in window title">
                <label> _Refresh </label>
                <input file icon="gtk-refresh"></input>
                <width>16</width>
                <action function="refresh">vWindow</action>
            </button>
            <button ok></button>
            <button cancel></button>
        </hbox>
    </vbox>

    <variable>vWindow</variable>
    <input>fnEchoDateTime</input>
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">EXIT:exit</action> 
</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

Here we define and use GTK styles to change foreground and/or background colours of the various objects.

Here is how the application window looks.

This is just a brief teaser. How to apply styles to objects, what works and what does not, etc., may be covered in a future article.

Exploring Window examples

In /home/demo/gtkdialog-0.8.3/examples/window there are 3 examples. Review the window GUI definitions and run the examples

/bin/sh /home/demo/gtkdialog-0.8.3/examples/window/window --dump

/bin/sh /home/demo/gtkdialog-0.8.3/examples/window/window

/bin/sh /home/demo/gtkdialog-0.8.3/examples/window/window_attributes --dump

/bin/sh /home/demo/gtkdialog-0.8.3/examples/window/window_attributes

/bin/sh /home/demo/gtkdialog-0.8.3/examples/window/window_signals --dump

/bin/sh /home/demo/gtkdialog-0.8.3/examples/window/window_signals

Tagged with: bash gtkdialog • bash GUI • CentOS • create demo • create demonstration • demo • demonstration • GTK • GTK GUI • gtkdialog • gtkdialog bash • gtkdialog bash examples • gtkdialog comments • gtkdialog documentation • gtkdialog examples • gtkdialog reference • gtkdialog structure • gtkdialog window • gtkdialog window attributes • gtkdialog window examples • gtkdialog window object • infrastructure demo • infrastructure demonstration • Linux demo • Linux demo image • Linux demonstration image • Linux GUI • Linux UI • technical demo • technical demonstration

Apr 09

Introduction to gtkdialog – application structure, examples and documentation

By Czapski Michael gtkdialog No Comments »

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

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 8^th 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

https://github.com/oshazard/gtkdialog/ – gtkdlialog distribution at github
http://01micko.com/reference/ – Index of reference pages for all gtkdialog objects
http://www.murga-linux.com/puppy/viewtopic.php?t=69188&start=2 – gtkdialog development discussion – by my light the most useful I found so far
http://www.murga-linux.com/puppy/viewtopic.php?p=544704#544704 – another gtkdialog development discussion
https://github.com/01micko/gtkdialog/tree/master/examples – gtkdialog online examples – also distributed in the source package
https://developer.gnome.org/gtk2/stable/ – Gnome GTK 2 developer documentation in general – what sits under the covers
https://developer.gnome.org/gtk2/2.24/gtk2-Standard-Enumerations.html#GtkWindowPosition – Various GTK Enumerations
http://www.orford.org/gtk – fonts, gtkrc files, engines
https://developer.gnome.org/gtk2/stable/gtk2-Resource-Files.html#gtk2-Resource-Files.description – Specific section on GTK resource files
http://www.murga-linux.com/puppy/viewtopic.php?t=40418 – gtkdialog markup text editor/wizard
http://www.murga-linux.com/puppy/viewtopic.php?t=69282 – Index of programs using gtkdialog

Themes and Styles

https://en.wikibooks.org/wiki/GTK%2B_By_Example/Theming – GTK Theming – to do with applying styles to GTKK applicaiton objects
http://www.cc.gatech.edu/data_files/public/doc/gtk/tutorial/gtk_tut-19.html – specific discussion of styles
https://git.enlightenment.org/themes/detourious.git/plain/gtk/detourious/gtk-2.0/gtkrc – a huge set of property specs
https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes – tutorial on all manner of GTK appearance including styles
https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/MistEngine – Mist GTK theme engine
https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkEngines/PixmapEngine – Pixmap GTK theme engine
https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes#Priority – Priority of style merging
https://wiki.gnome.org/Attic/GnomeArt/Tutorials/GtkThemes/SymbolicColors – Discussion on colours
https://www.cs.tut.fi/lintula/manual/gtk/gtk/gtk-resource-files.html – Discussion in “Pathnames and patterns”

Object Hierarchy – Window

https://developer.gnome.org/gtk2/2.24/GtkWindow.html#GtkWindow.object-hierarchy – GtkWindow Object hierarchy
https://developer.gnome.org/gtk2/2.24/GtkWindow.html#GtkWindow.properties – GtkWindow Object Properties

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.

Tagged with: CentOS • create demo • create demonstration • demo • demonstration • GTK • GTK GUI • gtkdialog • gtkdialog bash examples • gtkdialog comments • gtkdialog documentation • gtkdialog examples • gtkdialog reference • gtkdialog structure • infrastructure demo • infrastructure demonstration • Linux demo • Linux demo image • Linux demonstration image • Linux GUI • Linux UI • technical demo • technical demonstration

Apr 09

gtkdialog Exploration – articles and examples – series introduction

By Czapski Michael gtkdialog 3 Comments »

In this article I discuss my rationale for using gtkdialog and, more importantly, I provide links to a growing list of articles on topics related to gtkdialog – applying styles to gtkdialog applications, examples, exploration of the various gtkdialog objects and suchlike.

Here is the list of my articles on the topic of gtkdialog:

My demos are typically designed to showcase back-end infrastructure, with one or more integrated products delivering specific functionality to client applications. The implication of, and the very point of, the infrastructure is that it does deliver functionality to any front-end client application. It shelters the front-end application from the complexities of integration of multiple components, orchestrating functionality across disparate products and platforms, and the need for the front-end developers to possess the requisite skills to effectively work in such complex, multi-technology environments.

To prove the points I typically have technical artefacts stand in for the client applications, for example using curl (https://curl.haxx.se/) or httpie (https://httpie.org/). This approach strips all the non-essential, tool-induced fluff, and exposes the bare requests and bare responses that the application needs to exchange with the back-end to get the job done. In the case of SOAP Web Services it would be the SOAP Requests and SOAP Responses. In the case of REST web services it would be HTTP Requests, potentially with JSON POST data, and REST Responses.

Alas, there are occasions when audience is not knowledgeable enough to appreciate what the technical artefacts are doing and what that means for the developer of the front-end application.

In the late 1990s early 2000s I was developing very complex and sophisticated web applications for healthcare. I started modestly enough with a web browser-based laboratory results reporting application using HTML 2 and a CERN httpd web server with complex custom backend – see https://blogs.czapski.id.au/wp-content/uploads/2010/03/for_blog_mczapski1.html if you are curious what that looked like then. The paper as it looked when it was hosted by Charles Sturt University in 1997 – https://web.archive.org/web/19970607211224/http://www.csu.edu.au/special/conference/apwww95/papers95/mczapski/mczapski.html – was archived in the Internet Archive by the WayBack Machine – https://archive.org/web/). I progressed to HTML 4, JavaScript, Apache httpd and custom Apache module for all the back-end database access and dynamic HTML generation (that was before the days of AJAX and other server-side technologies, so I invented my own serverside scripting methodology for the occasion).

All this is to say that when I started considering what technology I would use to create demonstration applications to show the client-side of integration to the back-end infrastructure for which I was building the demos I naturally turned to the web technologies. That, it turned out, was a blind alley for me. The time and effort investment necessary to choose from the plethora of competing frameworks, the inevitable need to combine multiple frameworks and technologies (like for example AngularJS, Backbone.io, Node.js, jQuery, etc., to acquire sufficient skills to be reasonably proficient and to get the actual job done seemed excessive. From my point of view the return on investment simply was not there.

What I was after was a tool that would put a reasonably-looking UI on top of the raw request/response exchanges with no need to write 3gl compiled code or Java or such, install execution environments (like node.js, web servers or servlet containers). It would ideally be invoked from the Linux shell with bunch of command line arguments which would make it do what I needed it to do.

I turned to Linux UI tools, starting with zenity (https://help.gnome.org/users/zenity/stable/), progressing through yad (http://www.webupd8.org/2010/12/yad-zenity-on-steroids-display.html) and finally stumbling upon gtkdialog (http://www.tecmint.com/gtkdialog-create-graphical-interfaces-and-dialog-boxes/).

It turned out that yad is ideal for quick dialog boxes of the sort that shows information and asks for OK or Cancel. It can do plenty more than that but I am using it for just such simple things. There is enough information on line to get one up to speed with yad pretty quickly for simple tasks. I built some UIs using yad but I was not satisfied with the rigidity of the component layout mechanism and the consequent lack of control over the layout.

I stumbled on the references to gtkdialog and started exploration. Alas, documentation for gtkdialog is almost non-existent, and what information can be had is scattered over group posts, blog articles and rather opaque reference pages. This alone makes the entry cost pretty high. One has to be fairly motivated to persevere with gtkdialog with no prior experience. I was reasonably motivated but there was a point, which I documented in my internal notes, when I concluded that it was “probably waste of time”. Still I persevered and I built a few pretty sophisticated client applications using gtkdialog and bash – each between 600 and 2000 lines of bash script. If you relate to these numbers then you will appreciate that for me gtkdialog is very attractive. I can develop, test and deploy a pretty sophisticated UI in a couple of days using bash as a scripting language with ready access to all the tools and technologies I need to do the back-end integration quickly and effectively.

Tagged with: bash gtkdialog • bash GUI • CentOS • create demo • create demonstration • demo • demonstration • GTK • GTK GUI • gtkdialog • gtkdialog bash • gtkdialog bash examples • gtkdialog comments • gtkdialog documentation • gtkdialog examples • gtkdialog exploration • gtkdialog reference • gtkdialog structure • gtkdialog tutorials • infrastructure demo • infrastructure demonstration • Linux demo • Linux demo image • Linux demonstration image • Linux GUI • Linux UI • technical demo • technical demonstration

Apr 08

gtkdialog for rapid prototyping of Linux Applications – Install gtkialog and yad for Graphical User Interfaces for Bash

By Czapski Michael gtkdialog No Comments »

In this article I walk through the steps that get the yad, gtkdialog and geany installed and tested.

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.

Pre-Requisites

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 8^th of March 2017. The link to the main article is https://blogs.czapski.id.au/2016/10/build-a-linux-based-infrastructure-solution-demonstration-series.

In this article I am discussing how yad and gtkdialog can be obtained and installed on CentOS 6.8. yad because I use it for simple OK/Cancel dialog boxes and gtkdialog because I use it for the applications with reasonably sophisticated functionality for which yad would be too cumbersome to use.

Install yad

Download yad from https://sourceforge.net/projects/yad-dialog/, build and install.

cd ~/Downloads
wget https://downloads.sourceforge.net/project/yad-dialog/yad-0.38.2.tar.xz
tar xvf yad-0.38.2.tar.xz
cd yad-0.38.2
autoreconf -ivf
export CFLAGS="$CFLAGS -DPACKAGE_URL='\"http://yad-dialog.sf.net/\"'"
./configure
make
sudo make install

Is there help?

man yad

A simple information dialogue can be constructed as follows:

cat <<-'EODECK' > /tmp/yad01.sh
templateFile=/tmp/xml/GIndProv_template_request.xml
if [ ! -f ${templateFile} ]; then
    yad --title="Required XML Template does not exist" --text="Required XML Template\n${templateFile}\ndoes not exist - aborting" \
    --center --image="gtk-dialog-error" --window-icon="gtk-dialog-error" --width=500 --height=100 --button="gtk-ok:0"
    exit;
fi
EODECK

/bin/sh /tmp/yad01.sh

A more sophisticated dialog might look like this:

cat <<-'EODECK' > /tmp/yad_find_patient.sh
#!/bin/bash

fnUpdateFieldsSBR() {
    echo "3:${title:-MR}"
    echo "4:${lastName:-Smith}"
    echo "5:${gender:-Male}"
    echo "6:${ssn:-123456789}"

    echo "11:${firstName:-John}"
    echo "12:${suffix:-III}"
    echo "13:${dob:-10/10/1978}"
}
export -f fnUpdateFieldsSBR

yad \
--center \
--title="Find Patient by EUID" \
--text="<span size=\"xx-large\">Find Patient Details by EUID</span>\n" \
--form \
--width=550 \
--borders=5 \
--columns=2 \
--date-format="%m/%d/%Y" \
--align=right \
--field="Enterprise Unique ID" "${USAPatXEUIDX:-0001234567}" \
--field="Demographics:LBL" "" \
--field="Title:RO" "" \
--field="Last Name:RO" "" \
--field="Sex:RO" "" \
--field="Social Security Number:RO" "" \
--field="Options:LBL" "" \
--field="Show XML Request?:CHK" "FALSE" \
 \
--field "  Search!gtk-find:FBTN" "@bash -c \"fnUpdateFieldsSBR \"%16\" \"%8\" \"%1\"  \" " \
--field=":LBL" "" \
--field="First Name:RO" "" \
--field="Suffix:RO" "" \
--field="Date of Birth:RO" "" \
--field=".:LBL" "." \
--field=":LBL" "" \
--field="Show XML Response?:CHK" "FALSE" \
 \
--dialog-sep \
--button="Quit!gtk-quit:0"

EODECK
/bin/sh /tmp/yad_find_patient.sh

Install gtkdialog

Download gtkdialog from https://centos.pkgs.org/6/epel-x86_64/gtkdialog-0.8.3-8.el6.x86_64.rpm.html

# get and install the package
cd ~/Downloads
wget http://dl.fedoraproject.org/pub/epel/6/x86_64//gtkdialog-0.8.3-8.el6.x86_64.rpm
sudo yum localinstall -y gtkdialog-0.8.3-8.el6.x86_64.rpm

# get and install soruces for examples and documentation
wget https://fossies.org/linux/privat/old/gtkdialog-0.8.3.tar.gz
cd ~/
tar xvf ./Downloads/gtkdialog-0.8.3.tar.gz

Try a few examples provided in the source distribution to get some notion of what can be accomplished with gtkdialog:

~/gtkdialog-0.8.3/examples/menu/menu
~/gtkdialog-0.8.3/examples/comboboxentry/comboboxentry_advanced
~/gtkdialog-0.8.3/examples/button/button_attributes
~/gtkdialog-0.8.3/examples/notebook/notebook_advanced

Take a look at reference and other documentation:

firefox file:///home/demo/gtkdialog-0.8.3/doc/reference/window.html &
firefox http://gtk.php.net/manual/en/html/gdk/gdk.enum.windowtypehint.html &

Install geany

Download and install geany editor – it beats the gedit and other free alternatives in my opinion

cd ~/Downloads
wget http://download.geany.org/geany-1.24.1.tar.gz

tar xvf geany-1.24.1.tar.gz
cd geany-1.24.1
./autogen.sh
make
sudo make install

Test:

cp -v /home/demo/gtkdialog-0.8.3/examples/window/window /tmp/gtk_window.sh
geany /tmp/gtk_window.sh &

Inspect the code in geany and press F5 to execute it.

gtkdialog hello world

Create a modified script and experiment with the various settings of the window attributes

cat <<-'EODECK' > /tmp/gtk_window.sh
#!/bin/bash
GTKDIALOG=gtkdialog

MAIN_DIALOG='
<window \
decorated="true" \
allow-grow="true" \
allow-shrink="true" \
default-height="200" \
default-width="400" \
resizable="true" xx-resizable="overrides default-height and default-width if set to false" \
deletable="true" xx-deletable="this keep (default) or remove the close button from the window title bar" \
icon-name="gtk-refresh" \
modal="false" \
skip-pager-hint="true" \
skip-taskbar-hint="false" \
title="My First Window" \
window-position="1" \
border-width="5" xx-border-width="is an inherited GtkContainer property - see object hierarchy at https://developer.gnome.org/gtk2/2.24/GtkWindow.html#GtkWindow.object-hierarchy" \
sensitive="true" xx-sensitive="is an inherited GtkWidget property that disables everything inside the window - see obect hierarchy" \
tooltip-markup="This is a <b>window tooltip</b>" xx-tooltip-markup="is inherited from GtkWidget" \
>
    <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
EODECK

/tmp/gtk_window.sh

Experiment with the setting of the Window object attributes and see what effect the changes have on the appearance and behaviour of the window.

There is plenty more that can be done with gtkdialog. I intend to write more articles on this topic as the time goes by. This article provides the tooling for these later articles.

Tagged with: CentOS • create demo • create demonstration • demo • demonstration • gtkdialog • infrastructure demo • infrastructure demonstration • Linux demo • Linux demo image • Linux demonstration image • Linux UI • technical demo • technical demonstration • yad

Apr 08

VirtualBox Image with content as built so far – for download and import into VirtualBox

By Czapski Michael Demo Building No Comments »

Introduction

Please see the article “Build a Linux-based Infrastructure Solution Demonstration Series” (https://blogs.czapski.id.au/2016/10/build-a-linux-based-infrastructure-solution-demonstration-series) for how this image came about and “gtkdialog Exploration” (https://blogs.czapski.id.au/2017/04/gtkdialog-exploration) for the rationale, introduction and links to articles in this series.

In this post I provide the link to the 7zip archive parts which put together will provide the VirtualBox “.ova” export file. The “.ova” can be imported into the VirtualBox 5.1.x as a new VirtualBox Machine Image.

This VirtualBox Machine Image has been built following steps in the series of blog articles under the collective heading of “Build a Linux-based Infrastructure Solution Demonstration Series”, to be found at https://blogs.czapski.id.au/2016/10/build-a-linux-based-infrastructure-solution-demonstration-series. It can be used as the basis for exploring other topics discussed in subsequent blog articles whether in this series or in related series.

Pre-Requisites

This article assumes that the Virtual Box 5.1.x software (https://www.virtualbox.org/) for the appropriate host OS has been installed.

Download Image Parts

The 7zip archive consists of 4 parts of around 650MB each, for a total of reconstructed .ova file of 2.5GB. The imported machine will take about 6GB of disk space.

Download the following to a suitable directory:

https://blogs.czapski.id.au/wp-content/uploads/2017/04/demo_v1.1.3_20170408.7z.001

https://blogs.czapski.id.au/wp-content/uploads/2017/04/demo_v1.1.3_20170408.7z.002

https://blogs.czapski.id.au/wp-content/uploads/2017/04/demo_v1.1.3_20170408.7z.003

https://blogs.czapski.id.au/wp-content/uploads/2017/04/demo_v1.1.3_20170408.7z.004

Combine Parts into .ova

Copy the parts to a suitable directory in a file system with at least 3 GB of free space.

Open the first part with an archiver capable of dealing with 7zip archives and extract the file demo_v1.1.3_20170408.ova.

On Windows in a command box the command might be like the following (substitute drive letters and paths as appropriate, noting that -oO:\ points to the output drive and directory and that there is a space between it and the name of the output file which follows):

"C:\Program Files\7-Zip\7z.exe" e D:\demo_v1.1.3_20170408.7z.001 -oO:\ demo_v1.1.3_20170408.ova -y

7-Zip [64] 16.04 : Copyright (c) 1999-2016 Igor Pavlov : 2016-10-04

Scanning the drive for archives:
1 file, 681574400 bytes (650 MiB)

Extracting archive: D:\demo_v1.1.3_20170408.7z.001
--
Path = D:\demo_v1.1.3_20170408.7z.001
Type = Split
Physical Size = 681574400
Volumes = 4
Total Physical Size = 2546348186
----
Path = demo_v1.1.3_20170408.7z
Size = 2546348186
--
Path = demo_v1.1.3_20170408.7z
Type = 7z
Physical Size = 2546348186
Headers Size = 154
Method = Copy
Solid = -
Blocks = 1

Everything is Ok

Size:       2546348032
Compressed: 2546348186

Import Image

Use the VirtualBox Manager UI to import the .ova file.

Before you do, check where in your file system the machine directory will be created and change as appropriate, bearing in mind that the target directory must be on a device with at least 7GB of free space or that the directory has a quote of at least 7GB of space if your environment uses disk space quotas:

File->Preferences->General->Default Machine Folder: ???

Once you are happy that the machine will go into the directory appropriate for your environment import the machine image:

File->Import Appliance…

Locate the .ova file, change whatever machine settings seem in need of change, like increase the amount of memory, the number of CPUs, etc., and Import.

Agree to the copyright statement (in which I claim no copyright or any other rights).

On my machine the process takes about 2 minutes and produces a machine image directory which uses approximately 6.6GB of space.

Make and use Snapshots

So that I have a known place to revert to if I mess something up, the first this I always do after importing an image is to take a “as imported” snapshot. I also take snapshots at various points in my work so that I don’t have too much to re-do if I make am mistake and have to roll back and re-do some work. I recommend that you consider this as a piece of good advice.

073_import_vm.png

Credentials

As discussed in the article “Configure Virtual Box Virtual Machine and Install CentOS 6.8 Base Image”, https://blogs.czapski.id.au/2016/10/configure-virtual-box-virtual-machine-and-install-centos-6-8-base-image, all passwords configured to this point are “welcome1”. That includes the root password. Change as necessary.

The image is configured in such a way that on boot the user “demo” will be automatically logged in. That user is in the sudoers file and has passwordless sudo rights.

Tagged with: CentOS • centos virtual machine • create demo • create demonstration • demo • demo image vm • demonstration • gnome 2 • infrastructure demo • infrastructure demonstration • Linux demo • Linux demo image • Linux demonstration image • technical demo • technical demonstration • virtual machine • virtualbox • virtualbox image

Pre-Requisites

Applying styles to a yad dialog box with a label and a button

Pre-Requisites

Example of styling – teaser

Some Sources of Information

Constructing style and making gtkdialog use it

Styling the Window object and its children

Naming Style Targets

Named Targets

Containment Hierarchy Targets

Targeting Classes

Gtkrc Examples

Tools for exploring widget styling and colours

gtk2-styles wizard

gpick Colour Picker

Pre-Requisites

Window Object Attributes

Window Object Directives

Exploring the action directive

Exploring “action signal” directive

Exploring “action function” directive

Exploring Window examples

Creadits:

Pre-Requisites

gtkdialog application structure and basic interaction with the environment

Common GUI definition convention

How can gtkdialog application interact with the environment (basic)

Explore examples

Reference Documentation

Commenting out blocks of XML

Short comments inside gtkdialog XML

Pre-Requisites

Install yad

Install gtkdialog

Install geany

gtkdialog hello world

Introduction

Pre-Requisites

Download Image Parts

Combine Parts into .ova

Import Image

Make and use Snapshots

Credentials

Categories

Tags

Java CAPS BasicsI, the Book

Recent Posts

Archives

Twitter