May 21

In this article I explore the gtkdialog EventBox object and its uses by example. EventBox can be used, among other things, to provide background colour to other objects, intercept and handle events and add frames around gtkdialog objects to help visualise the space they occupy.

This is the next article in a series of articles on gtkdialog, “gtkdialog Exploration – articles and examples”, which can be found at http://blogs.czapski.id.au/2017/04/gtkdialog-exploration.

The examples in this article demonstrate the following uses of the EventBox:

  1. Providing background colour to HBox / VBox objects
  2. Applying font styles to text within EventBox and its content
  3. Unsing the EventBox to intercept mouse clicks on objects contained inside the EventBox
  4. Using the EventBox and styles to add a colour border to a window
  5. Using the EventBox and styles to add a “right-click” menu to an application
  6. Using the EventBox and styles to add visible borders to any/all gtldialog components

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 http://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 http://blogs.czapski.id.au/2017/04/virtualbox-image-with-content-as-built-so-far.

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

EventBox Object Model

gtkdialog, based as it is on the GTK object model, leverages the GTK object hierarchy. Consider the reference for the EventBox object at http://01micko.com/reference/eventbox.html.

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

In the GTK object hierarchy, https://developer.gnome.org/gtk2/2.24/GtkEventBox.html#GtkEventBox.object-hierarchy, the EventBox object is some levels below the GObject, the topmost object.

The GtkEventBox, and consequently the gtkdialog EventBox, object inherits from the objects higher up in the hierarchy. This will come into play when we explore attributes that can be set for an EventBox, and actions that can be configured for an EventBox.

EventBox Attributes

The gtkdialog EventBox object is a container, of a sort, to which styles can be applied, which can be “shown”/”hidden” and which can be “positioned” in the object hierarchy in such a way that all of the children which it contains are “beneath” it, so that the EventBox and not the children receives mouse clicks.

An example of an interface, which uses the EventBox object, and which will be developed in this article, is shown here.

Reference documentation for the gtkdialog EventBox object, http://01micko.com/reference/eventbox.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 eventbox widget are defined in the widget’s reference page see https://developer.gnome.org/gtk2/2.24/GtkEventBox.html, section Properties – https://developer.gnome.org/gtk2/2.24/GtkEventBox.html#GtkEventBox.properties

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 notebook frame and the notebook content, is inherited from the GtkContainer.

Similarly, sensitive property is inherited from the GtkWidget and when set to true effectively disables everything inside the eventbox container.

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

To work out what attributes are actually supported, in this case by the eventbox 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. The “Works?” column indicates whether the attribute has a visible effect (Y), does not have a visible effect (N) or I have not figured out a way to test whether it works or not.

The table below summarised EventBox 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 Works? In
EventBox
space-expand Pack widget expanding into space true or false Y gtkdialog
space-fill Pack widget filling space true or false Y gtkdialog
block-function-signals Block signal emissions from functions true or false gtkdialog
Inherited from GtkEventBox
above-child Whether the event-trapping window of the eventbox is above the window of the child widget as opposed to below it. If true no clicks will be delivered to the objects underneath the eventbox. true or false false Y GtkEventBox
visible-window Whether the event box is visible, as opposed to invisible and only used to trap events. true or false false Y GtkEventBox
Inherited from gtkContainer
border-width The width of the empty border outside the containers children <=65535 0 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 Maybe

Makes no sense for this

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 Maybe

Makes no sense for this

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 Maybe

Makes no sense for this

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 Maybe

Makes no sense for this

GtkWidget
has-tooltip Whether this widget has a tooltip.

Disables tooltip display if tooltip is defined for the Window

true or false false Y GtkWidget
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 Y GtkWidget
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 Maybe

Makes no sense for this

GtkWidget
name The name of the widget.

It can be used to address styling directves to a named object

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 Maybe

Makes no sense for this

GtkWidget
sensitive Whether the widget responds to input.

FALSE disables all components contained in the eventbox.

true or false TRUE Y 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 Y GtkWidget
tooltip-text The contents of the tooltip for this widget.

Ineffective if tooltip-disabled is TRUE.

string NULL Y GtkWidget
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 Y GtkWidget
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 or if an outer container has a width-request set.

>=0 -1 Y GtkWidget

The following example includes just about every attrivute which can be set for the EventBox. We will explore what the various attribute settings do below.

First, let’s create an enumerations script which will supply human-readable versions of enumerations and other numeric constants that may be used in the scripts I show. See https://github.com/GNOME/gtk/blob/master/gdk/gdktypes.h, and elsewhere, for sources of these enumerations.

If you have this enumerations source because you worked through the Notebook example than you don’t need to re-create it. No new constants have been added.

mkdir -pv /tmp/scripts
cd /tmp/scripts
cat <<-'EOSOURCE' > gtkdialog.constants
# gtkdialog.constants
#
cstVersion=1.0.0
echo "Loading ${BASH_SOURCE[0]} version ${cstVersion} ..." 1>&2

# I prefer symbolic constants to numeric literals so I defined a bunch
# see https://github.com/GNOME/gtk/blob/master/gdk/gdktypes.h for specifics
#
BTN_IMG_POS_LEFT=0
BTN_IMG_POS_RIGHT=1
BTN_IMG_POS_ABOVE=2
BTN_IMG_POS_BELOW=3
WIN_ICON=access
WIN_DECORATED=true
WIN_RESIZABLE=true
GTK_WIN_POS_CENTER=1
GTK_WIN_POS_MOUSE=2
WIN_POS=${GTK_WIN_POS_CENTER}
WIN_SKIP_TASKBAR_HINT=false
WIN_ALLOW_GROW=true
XALIGN_LEFT=0
XALIGN_RIGHT=1
XALIGN_CENTRE=0.5
YALIGN_TOP=0
YALIGN_BOTTOM=1
YALIGN_CENTRE=0.5
VSCROLLBAR_ALWAYS=0
VSCROLLBAR_AUTOMATIC=1
VSCROLLBAR_NEVER=2
HSCROLLBAR_ALWAYS=0
HSCROLLBAR_AUTOMATIC=1
HSCROLLBAR_NEVER=2
GTK_JUSTIFY_LEFT=0
GTK_JUSTIFY_RIGHT=1
GTK_JUSTIFY_CENTRE=2
TREE_SELECTION_MODE_NONE=0
TREE_SELECTION_MODE_SINGLE=1
TREE_SELECTION_MODE_BROWSE=2
TREE_SELECTION_MODE_MULTIPLE=3
TAB_POS_LEFT=0
TAB_POS_RIGHT=1
TAB_POS_ABOVE=2
TAB_POS_BELOW=3

EOSOURCE

above-child and visible-window attributes

In this section we will explore how the above-child and visible-window attributes of the eventbox, combined with appropriate styles, affect the appearance and function of the eventbox and its contents.

To create and exercise the first example execute the following commands, noting that you will need to copy and paste the code into an editor window because it is too large for a “here document”.

mkdir /tmp/scripts
cd /tmp/scripts
> /tmp/scripts/ex34.sh
chmod ug+x /tmp/scripts/ex34.sh

geany /tmp/scripts/ex34.sh & # until ## EOSCRIPT
#!/bin/bash

# make directory for temporary files and have it and the content blown away at exit
#
export LOCAL_DATA_DIR="/dev/shm/$(basename ${0})"
mkdir -p ${LOCAL_DATA_DIR}

fnHlrRemoveTmporaryFilesOnExit() {
    mkdir -p ${LOCAL_DATA_DIR}
    rm -R -f ${LOCAL_DATA_DIR}
}
trap fnHlrRemoveTmporaryFilesOnExit 0 # clean up after any program end.

# name temporary files and place them in the directory which will get deleted on termination of the script (most of the time)
export MAIN_DIALOG_FILE="${LOCAL_DATA_DIR}/MAIN_DIALOG_FILE_${USER}_${BASHPID}.gtkdialog"

##====================================================
[ -z ${GTKDIALOG:-} ] && GTKDIALOG=gtkdialog

# load symbolic constants I use instead of numeric values
source $(dirname ${0})/gtkdialog.constants

# window title
WIN_TITLE="EventBox Example"

# Size of the notebook and all content panels
#
_WIDTH_REQUEST=400
export _DATE_FORMAT_RFC3339_NS="--rfc-3339=ns"
export _DATE_FORMAT_TIMESTAMP="+%Y%m%d-%H%M%S.%N%z"

# construct UI
cat <<-EODECK > ${MAIN_DIALOG_FILE}
<window title="${WIN_TITLE}" icon-name="${WIN_ICON}" decorated="${WIN_DECORATED}" resizable="${WIN_RESIZABLE}"
        window_position="${WIN_POS}" skip_taskbar_hint="${WIN_SKIP_TASKBAR_HINT}" allow-grow="${WIN_ALLOW_GROW}"
        auto-refresh="true" name="win0">
    <vbox width-request="${_WIDTH_REQUEST}">

        <hbox>
            <hbox homogenous="true" space-fill="true" space-expand="true">
                <text><label>Some content goes here</label></text>
            </hbox>
        </hbox>

        $(: visible-window="false" blocks delivery of clicks to the content objects, including inner eventbox objects )
        $(: but it does not prevent keystrokes from selecting buttons and pressing on them, for example )
        <eventbox above-child="false" visible-window="true">
            <frame  Outer Frame  >
                <hbox>
                    <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true"
                      can-default="true" xx-info="has-default must have can-default"
                      has-default="true" xx-info="has-default and can-default must both be true for default to work"
                      >
                        <label> _Refresh </label>
                        <input file icon="system-config-date"></input>
                        <width>16</width>
                        <action condition="command_is_true(fnDateFormatToggleNeeded '${_DATE_FORMAT_RFC3339_NS}' )">refresh:vDateFormatToggle</action>
                        <action function="refresh">vWindow</action>
                    </button>
                    <text xpad="1"><label>""</label></text>
                </hbox>

                $(: both above-child and visible-window have to be true for the event box to "block" clicks to the content )
                $(: both above-child and visible-window have to be true for the event box background colour to be seen )
                <eventbox above-child="false" visible-window="true" has-tooltip="true" tooltip-markup="This is <b>tooltip</b> for eventbox"
                          height-request="100" sensitive="true" visible="true" width-request="600">
                    <frame  Inner Frame  >
                        <hbox>
                            <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true">
                                <label> _Update </label>
                                <input file icon="system-config-date"></input>
                                <width>16</width>
                                <action condition="command_is_true(fnDateFormatToggleNeeded '${_DATE_FORMAT_TIMESTAMP}')">refresh:vDateFormatToggle</action>
                                <action function="refresh">vWindow</action>
                            </button>
                        </hbox>
                    </frame> $(: inner frame)
                   
                    <variable>vEventBoxOuter</variable>
                </eventbox>

            </frame> $(: outer frame)

            <variable>vEventBoxOuter</variable>
        </eventbox>

        <hbox>
            <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true"
              can-default="true" has-default="true">
                <label> _Quit </label>
                <input file icon="gtk-quit"></input>
                <width>16</width>
                <action function="exit">QUIT</action>
            </button>
            <text xpad="5"><label>""</label></text>
        </hbox>

        <entry visible="false">
            <default>false</default>
            <variable>vDateFormatToggle</variable>
            <input>fnDateFormatToggle</input>
        </entry>

    </vbox>


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

#== Styles ==========================================
export GTK2_RC_FILES=${LOCAL_DATA_DIR}/gtkrc
cat <<-'EOSTYLEDEF' > ${GTK2_RC_FILES}
style "outerFrameStyle" {
    bg[NORMAL]      = "slateblue"
    fg[NORMAL]      = "white"
    font_name="URW Gothic L Book 14"
}
style "innerFrameStyle" {
    bg[NORMAL]      = "white"
    fg[NORMAL]      = "navy"
    font_name="URW Gothic L Demi Oblique 10"
}

widget_class "<GtkWindow><GtkVBox><GtkEventBox>" style "outerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame>" style "outerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkLabel>" style "outerFrameStyle"
# below will not show background of the eventbox if eventbox attribute visible="false"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkContainer><GtkEventBox>" style "innerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkContainer><GtkEventBox><GtkFrame>" style "innerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkContainer><GtkEventBox><GtkFrame><GtkLabel>" style "innerFrameStyle"
EOSTYLEDEF

## -- post UI construction ---------------------
# fnDateFormatToggleNeeded '--rfc-3339=ns' or '-R'
fnDateFormatToggleNeeded() {
    local vWhatFormat="${1}"
    [[ "${vDateFormatToggle}" == "${vWhatFormat}" ]] && echo "false" || echo "true"
}
export -f fnDateFormatToggleNeeded

# fnDateFormatToggle
fnDateFormatToggle() {
    [[ "${vDateFormatToggle}" == "${_DATE_FORMAT_RFC3339_NS}" ]] && echo "${_DATE_FORMAT_TIMESTAMP}" || echo "${_DATE_FORMAT_RFC3339_NS}"
}
export -f fnDateFormatToggle

# fnShowTimestamp
fnShowTimestamp() {
    date ${vDateFormatToggle}
}
export -f fnShowTimestamp

# -- run the UI -----------------------------------------------------------------------------------------------

case ${1:-} in
    -d | --dump) more "${MAIN_DIALOG_FILE}" ;;
    -f | --file) $GTKDIALOG --center --file=${MAIN_DIALOG_FILE} ;;
    -v | --variable) export MAIN_DIALOG=$(cat ${MAIN_DIALOG_FILE}); $GTKDIALOG --center --program=MAIN_DIALOG ;;
    *) $GTKDIALOG --file=${MAIN_DIALOG_FILE} ;;
esac

## EOSCRIPT

/tmp/scripts/ex34.sh

Executing this example unmodified produces the window which looks like that shown earlier – reproduced for completeness:

Because some of the attributes of the EventBox, such as the above-child and the visible-window do not produce visual effects but affect the behaviour of the application it will be necessary to describe the outcome rather than simply show a screenshot of it.

Click the Refresh and the Update buttons to see the window title change in accordance with the date formatting logic triggered by each. Note that the title window changes to display a timestamp and that the format of the timestamp changes depending on which of the two buttons is clicked.

Now change the value of the attribute above-child to “true” and click the two buttons as before. The code fragment here after this change is made is reproduced below:

<eventbox above-child="true" visible-window="true" has-tooltip="true"
           tooltip-markup="This is <b>tooltip</b> for eventbox"
           height-request="100" sensitive="true" visible="true" width-request="600">
                    <frame  Inner Frame  >
                        <hbox>

Note that clicking on the “Update” button produces no effect. The above-child=”true” places all elements contained inside the eventbox “beneath” it so that it is the EventBox object that receives mouse clicks. If the event box had a signal handler attached to it, as it does not in this case, this event handler would intercept the clicks. Since there is no handler the clicks are simply ignored. Note however that if you use the Tab key to “tab to” the “Update” button, and it is selected, then pressing the Enter key will cause the action associated with this button to be executed event when the above-child is set to true.

Now change the above-child back to false and visible-window to true, as shown in the code fragment below, then run the example.

<eventbox above-child="false" visible-window="false"
          has-tooltip="true" tooltip-markup="This is <b>tooltip</b> for eventbox"
          height-request="100" sensitive="true" visible="true" width-request="600">

Note that the appearance of the window has changed:

Because the inner EventBox’s visible-window property is set to false the visual effects of the EventBox are not there – the background of the EventBox, which was white when the visible-window property was true is no longer white. The area of the inner EventBox takes on the appearance of the outer EventBox with its background colour of slateblue. But, the inner eventbox still intercepts the clicks made inside its borders even though the above-child is set to false – click on the Update button and see.

Now set the outer eventbox visible-window attribute to false and see the effect on the background colour and on the clickability of the Refresh button and run the example – the Refresh button is no longer clickable and the entire area of the outer EventBox, with its contained inner EventBox, has the default window colour.

Now set the inner eventbox visible-window attribute to true and run the example. The background colour of the inner EventBox is white but the Update button is still not clickable even though both eventboxes have the above-child attribute set to false.

This behaviour is, to me at least, counterintuitive but that’s what it is. Go figure.

Using eventbox to create a framed “help window”

A handy trick, which nested eventbox elements afford, is the ability to create a coloured “frame” around arbitrary content. The example below takes advantage of this trick to create a framed “help window”.

The screenshot below shows what is meant:

The window with the red border and the white background is shown when the Help button is clicked. Clicking on it or anywhere else other than on the Help button makes this window disappear.

The red border and the white background to the content inside are accomplished with the aid of the nested eventbox objects.

Execute the following commands, including copying and pasting the body of the example between geany and EOSCRIPT.

Note the sections highlighted in bold. These are the major adifferences between this example and the previous example.

mkdir /tmp/scripts
cd /tmp/scripts
> /tmp/scripts/ex35.sh
chmod ug+x /tmp/scripts/ex35.sh

geany /tmp/scripts/ex35.sh & # until ## EOSCRIPT
#!/bin/bash

# make directory for temporary files and have it and the content blown away at exit
#
export LOCAL_DATA_DIR="/dev/shm/$(basename ${0})"
mkdir -p ${LOCAL_DATA_DIR}

fnHlrRemoveTmporaryFilesOnExit() {
    mkdir -p ${LOCAL_DATA_DIR}
    rm -R -f ${LOCAL_DATA_DIR}
}
trap fnHlrRemoveTmporaryFilesOnExit 0 # clean up after any program end.

# name temporary files and place them in the directory which will get deleted on termination of the script (most of the time)
export MAIN_DIALOG_FILE="${LOCAL_DATA_DIR}/MAIN_DIALOG_FILE_${USER}_${BASHPID}.gtkdialog"
export HELP_DIALOG_FILE="${LOCAL_DATA_DIR}/HELP_DIALOG_FILE_${USER}_${BASHPID}.gtkdialog"

##====================================================
[ -z ${GTKDIALOG:-} ] && GTKDIALOG=gtkdialog

# load symbolic constants I use instead of numeric values
source $(dirname ${0})/gtkdialog.constants

# Size of the notebook and all content panels
#
_WIDTH_REQUEST=400
export _DATE_FORMAT_RFC3339_NS="--rfc-3339=ns"
export _DATE_FORMAT_TIMESTAMP="+%Y%m%d-%H%M%S.%N%z"

# construct UI
## Help UI
##
# window title
WIN_TITLE="Help on Event Box Example"

## =========================================================
## construct help panel
##
cat > ${HELP_DIALOG_FILE} <<-EODECK
<window 
    decorated="false" 
    skip_taskbar_hint="true"
    window_position="${GTK_WIN_POS_CENTER}"

    <eventbox xwidth-request="200" name="outer_colour" above-child="false" visible-window="true" visible="true">
        <vbox border-width="3">
            <eventbox name="inner_colour" above-child="false" visible-window="true" visible="true">
                <text xpad="6" ypad="6" xalign="${XALIGN_LEFT}" justify="${GTK_JUSTIFY_LEFT}" selectable="false" use-markup="true">
                    <label>
"<span size='large'><b>${WIN_TITLE}</b></span>

This text goes into the help popup. This text goes into the help popup. This text goes into the help popup.
This text goes into the help popup.
This text goes into the help popup.
This text goes into the help popup.
This text goes into the help popup.

<span size='x-small'>Enjoy.</span>"
                    </label>
                </text>
            </eventbox>
        </vbox>
    </eventbox>

    <variable>HELP_DIALOG</variable>
    <action signal="button-press-event" condition="command_is_true( [[ \$PTR_BTN == 1 ]] && echo true )">closewindow:HELP_DIALOG</action> 
    <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">closewindow:HELP_DIALOG</action> 
    <action signal="focus-out-event">closewindow:HELP_DIALOG</action>
</window>
EODECK
export HELP_DIALOG=$(cat ${HELP_DIALOG_FILE})

## main UI
##
# window title
WIN_TITLE="EventBox Example"

cat <<-EODECK > ${MAIN_DIALOG_FILE}
<window title="${WIN_TITLE}" icon-name="${WIN_ICON}" decorated="${WIN_DECORATED}" resizable="${WIN_RESIZABLE}"
        window_position="${WIN_POS}" skip_taskbar_hint="${WIN_SKIP_TASKBAR_HINT}" allow-grow="${WIN_ALLOW_GROW}"
        auto-refresh="true" name="win0">
    <vbox width-request="${_WIDTH_REQUEST}">

        <hbox>
            <hbox homogenous="true" space-fill="true" space-expand="true">
                <text><label>Some content goes here</label></text>
            </hbox>
        </hbox>

        $(: visible-window="false" blocks delivery of clicks to the content objects, including inner eventbox objects )
        $(: but it does not prevent keystrokes from selecting buttons and pressing on them, for example )
        <eventbox above-child="false" visible-window="true">
            <frame  Outer Frame  >
                <hbox>
                    <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true"
                      can-default="true" xx-info="has-default must have can-default"
                      has-default="true" xx-info="has-default and can-default must both be true for default to work"
                      >
                        <label> _Refresh </label>
                        <input file icon="system-config-date"></input>
                        <width>16</width>
                        <action condition="command_is_true(fnDateFormatToggleNeeded '${_DATE_FORMAT_RFC3339_NS}' )">refresh:vDateFormatToggle</action>
                        <action function="refresh">vWindow</action>
                    </button>
                    <text xpad="1"><label>""</label></text>
                </hbox>

                $(: both above-child and visible-window have to be true for the event box to "block" clicks to the content )
                $(: both above-child and visible-window have to be true for the event box background colour to be seen )
                <eventbox above-child="false" visible-window="true" has-tooltip="true" tooltip-markup="This is <b>tooltip</b> for eventbox"
                          height-request="100" sensitive="true" visible="true" width-request="600">
                    <frame  Inner Frame  >
                        <hbox>
                            <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true">
                                <label> _Update </label>
                                <input file icon="system-config-date"></input>
                                <width>16</width>
                                <action condition="command_is_true(fnDateFormatToggleNeeded '${_DATE_FORMAT_TIMESTAMP}')">refresh:vDateFormatToggle</action>
                                <action function="refresh">vWindow</action>
                            </button>
                        </hbox>

                    </frame> $(: inner frame)
                 
                    <variable>vEventBoxOuter</variable>
                </eventbox>

            </frame> $(: outer frame)

            <variable>vEventBoxOuter</variable>
        </eventbox>

        <hbox>
            <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true">
                <label> _Help </label>
                <input file icon="gtk-help"></input>
                <width>16</width>
                <action>launch:HELP_DIALOG</action>
            </button>

            <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true"
              can-default="true" has-default="true">
                <label> _Quit </label>
                <input file icon="gtk-quit"></input>
                <width>16</width>
                <action function="exit">QUIT</action>
            </button>
            <text xpad="5"><label>""</label></text>
        </hbox>

        $(: 'invisible entry box for persisting the state of date format togge')
        <entry visible="false">
            <default>false</default>
            <variable>vDateFormatToggle</variable>
            <input>fnDateFormatToggle</input>
        </entry>

    </vbox>

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

#== Styles ==========================================
export GTK2_RC_FILES=${LOCAL_DATA_DIR}/gtkrc
cat <<-'EOSTYLEDEF' > ${GTK2_RC_FILES}
style "outerFrameStyle" {
    bg[NORMAL]      = "slateblue"
    fg[NORMAL]      = "white"
    font_name="URW Gothic L Book 14"
}
style "innerFrameStyle" {
    bg[NORMAL]      = "white"
    fg[NORMAL]      = "navy"
    font_name="URW Gothic L Demi Oblique 10"
}

widget_class "<GtkWindow><GtkVBox><GtkEventBox>" style "outerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame>" style "outerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkLabel>" style "outerFrameStyle"
# below will not show background of the eventbox if eventbox attribute visible="false"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkContainer><GtkEventBox>" style "innerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkContainer><GtkEventBox><GtkFrame>" style "innerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkContainer><GtkEventBox><GtkFrame><GtkLabel>" style "innerFrameStyle"

style "outer_colour" { bg[NORMAL] = "#ff0000" }
widget "*outer_colour" style "outer_colour"
style "inner_colour" { bg[NORMAL] = "#ffffff" }
widget "*inner_colour" style "inner_colour"

EOSTYLEDEF

## -- post UI construction ---------------------
# fnDateFormatToggleNeeded '--rfc-3339=ns' or '-R'
fnDateFormatToggleNeeded() {
    local vWhatFormat="${1}"
    [[ "${vDateFormatToggle}" == "${vWhatFormat}" ]] && echo "false" || echo "true"
}
export -f fnDateFormatToggleNeeded

# fnDateFormatToggle
fnDateFormatToggle() {
    [[ "${vDateFormatToggle}" == "${_DATE_FORMAT_RFC3339_NS}" ]] && echo "${_DATE_FORMAT_TIMESTAMP}" || echo "${_DATE_FORMAT_RFC3339_NS}"
}
export -f fnDateFormatToggle

# fnShowTimestamp
fnShowTimestamp() {
    date ${vDateFormatToggle}
}
export -f fnShowTimestamp

# -- run the UI -----------------------------------------------------------------------------------------------

case ${1:-} in
    -d | --dump) more "${MAIN_DIALOG_FILE}" ;;
    -f | --file) $GTKDIALOG --center --file=${MAIN_DIALOG_FILE} ;;
    -v | --variable) export MAIN_DIALOG=$(cat ${MAIN_DIALOG_FILE}); $GTKDIALOG --center --program=MAIN_DIALOG ;;
    *) $GTKDIALOG --file=${MAIN_DIALOG_FILE} ;;

esac

##EOSCRIPT

 

/tmp/scripts/ex35.sh

There are a number of objects and patterns, apart from the eventbox, which this example introduces. They will not be discussed here. Of passing note are the use of the <eventbox><vbox><eventbox> construct to create the red border around the inner eventbox and its content, the escape key and focus-out-event handlers and the launch:HELP_WINDOW in the main window’s Help button, and closewindow:HELP_WINDOW in the help window itself.

Run the example and click the Help button. The application will launch the help window and make it disappear when the the escape key is pressed or when the mouse is clicked anywhere outside the boundaries of the Help button.

Using eventbox to create a Popup Menu

In this example we expand the use of the nested evenboxes to create a right-click popup menu.

The screenshot below shows what is meant:

The window with the red border and the white background, and the two checkboxes, is shown when the right mouse button is clicked. Setting and unsetting checkboxes is done as expected – click the checkbox or its label, use the keyboard to alternate between selecting one or the other checkbox, press enter or space to change the state of the selected checkbox. Clicking anywhere else outside the boundaries of the menu makes this menu disappear.

The menu and menu handling in this example was inspired by the example at http://blog.puppylinux.com/?viewDetailed=00030.

The red border and the white background to the content inside are accomplished with the aid of the nested eventbox objects. Checkboxes and their handling are the same regardless of what sor of window they are in.

In this example the state of the checkboxes must be persisted when the menu is closed. Since gtkdialog does not have the mechanism to have a signal handler directly programmatically set the value of a variable (push model) two functionas are introduced to set and get the value of the checkbox using a file in the file system for persistence. This was inspired by one of the gtkdialog examples and may be explored in another article. For now it should suffice to say that checking and unchecking one of the checkboxes casues the value of the checkbox (true/false, checked/unchecked) to be written to a corresponding file and the state of he checkboxes is read form these files whenever the popup menu is shown. The values of the checkboxes are read in the Refresh and Update button handler to control its logic.

Execute the following commands, including copying and pasting the body of the example between geany and EOSCRIPT.

Note the sections highlighted in bold. These are the major adifferences between this example and the previous example.

mkdir /tmp/scripts
cd /tmp/scripts
> /tmp/scripts/ex36.sh
chmod ug+x /tmp/scripts/ex36.sh

geany /tmp/scripts/ex36.sh & # until ## EOSCRIPT
#!/bin/bash

# make directory for temporary files and have it and the content blown away at exit
#
export LOCAL_DATA_DIR="/dev/shm/$(basename ${0})"
mkdir -p ${LOCAL_DATA_DIR}

fnHlrRemoveTmporaryFilesOnExit() {
    mkdir -p ${LOCAL_DATA_DIR}
    rm -R -f ${LOCAL_DATA_DIR} 
}
trap fnHlrRemoveTmporaryFilesOnExit 0 # clean up after any program end.

# name temporary files and place them in the directory which will get deleted on termination of the script (most of the time)
export MAIN_DIALOG_FILE="${LOCAL_DATA_DIR}/MAIN_DIALOG_FILE_${USER}_${BASHPID}.gtkdialog"
export HELP_DIALOG_FILE="${LOCAL_DATA_DIR}/HELP_DIALOG_FILE_${USER}_${BASHPID}.gtkdialog"
export RCLK_DIALOG_FILE="${LOCAL_DATA_DIR}/RCLK_DIALOG_FILE_${USER}_${BASHPID}.gtkdialog"

##====================================================
[ -z ${GTKDIALOG:-} ] && GTKDIALOG=gtkdialog

# load symbolic constants I use instead of numeric values
source $(dirname ${0})/gtkdialog.constants

# Size of the notebook and all content panels
#
_WIDTH_REQUEST=400
export _DATE_FORMAT_RFC3339_NS="--rfc-3339=ns"
export _DATE_FORMAT_TIMESTAMP="+%Y%m%d-%H%M%S.%N%z"

##### construct UI #############################
## pre-ui ccreate functions
# show right-click menu on right mouse button press in main window
#
fnAddRightClickActionsInline() {
echo "<action signal=\"button-press-event\" condition=\"command_is_true( [[ \$PTR_BTN == 3 ]] && echo true )\">\
launch:RIGHT_CLICK_DIALOG\
</action>"
}

:<<'NONFUNCTIONAL--------------------------------------------------------'
    fnUtlVarGet
    -----------
    Get a variable [maintained as a file] from the local data directory.
    On entry: $1 = name
    On exit: echoes value
NONFUNCTIONAL--------------------------------------------------------
fnUtlVarGet() {
    [[ ! -e $LOCAL_DATA_DIR/$1 ]] && touch $LOCAL_DATA_DIR/$1
    local input
    read -r input < $LOCAL_DATA_DIR/$1
    echo -n "$input"
}
export -f fnUtlVarGet
 
:<<'NONFUNCTIONAL--------------------------------------------------------'
    fnUtlVarSet
    -----------
    Set a variable [maintained as a file] within the local data directory.
    On entry: $1 = name
              $2 = value
NONFUNCTIONAL--------------------------------------------------------
fnUtlVarSet() {
    [[ ! -e $LOCAL_DATA_DIR/$1 ]] && touch $LOCAL_DATA_DIR/$1
    echo "$2" > $LOCAL_DATA_DIR/$1
}
export -f fnUtlVarSet
## right-click settings UI
##
 
## =========================================================
## construct right-click menu
##

fnUtlVarSet 'cbkShowRequest' "false"   # init right-click menu checkboxes to unset
fnUtlVarSet 'cbkShowResponse' "false"  # init right-click menu checkboxes to unset

cat > ${RCLK_DIALOG_FILE} <<-EODECK
<window 
    decorated="false" 
    skip_taskbar_hint="true"
    window_position="${GTK_WIN_POS_MOUSE}"


$(:<<'COMMENT--------------------------------------------------'
This stuff was inspired by Gtkdialog right-click menu - http://blog.puppylinux.com/?viewDetailed=00030

COMMENT--------------------------------------------------
)
    <eventbox xwidth-request="200" name="outer_colour" above-child="false" visible-window="true" visible="true">
        <vbox border-width="3">
            <eventbox name="inner_colour" above-child="false" visible-window="true" visible="true">
                <vbox border-width="10">
                    <vbox>
                        <checkbox tooltip-text="Selecting this option will display the Requests which will govern date format" label="Show Date Format Request?" xalign="${XALIGN_LEFT}">
                            <variable>cbkShowRequest</variable>
                            <action condition="active_is_true(cbkShowRequest)">fnUtlVarSet 'cbkShowRequest' 'true'</action>
                            <action condition="active_is_false(cbkShowRequest)">fnUtlVarSet 'cbkShowRequest' 'false'</action>
                            <input>fnUtlVarGet 'cbkShowRequest'</input>
                        </checkbox>
                    </vbox>
                    <vbox>
                        <checkbox tooltip-text="Selecting this option will display the formatted date" label="Show Formatted Date?" xalign="${XALIGN_LEFT}">
                            <variable>cbkShowResponse</variable>
                            <action condition="active_is_true(cbkShowResponse)">fnUtlVarSet 'cbkShowResponse' 'true'</action>
                            <action condition="active_is_false(cbkShowResponse)">fnUtlVarSet 'cbkShowResponse' 'false'</action>
                            <input>fnUtlVarGet 'cbkShowResponse'</input>
                        </checkbox>
                    </vbox>
                </vbox>
            </eventbox>
        </vbox>
    </eventbox>
 
    <variable>RIGHT_CLICK_DIALOG</variable>

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

export RIGHT_CLICK_DIALOG=$(cat ${RCLK_DIALOG_FILE})

## Help UI
##
# window title
WIN_TITLE="Help on Event Box Example"

## =========================================================
## construct help panel
##
cat > ${HELP_DIALOG_FILE} <<-EODECK
<window 
 decorated="false" 
 skip_taskbar_hint="true"
 window_position="${GTK_WIN_POS_CENTER}"
> 
 <eventbox xwidth-request="200" name="outer_colour" above-child="false" visible-window="true" visible="true">
 <vbox border-width="3">
 <eventbox name="inner_colour" above-child="false" visible-window="true" visible="true">
 <text xpad="6" ypad="6" xalign="${XALIGN_LEFT}" justify="${GTK_JUSTIFY_LEFT}" selectable="false" use-markup="true">
 <label>
"<span size='large'><b>${WIN_TITLE}</b></span>

This text goes into the help popup. This text goes into the help popup. This text goes into the help popup.
This text goes into the help popup.
This text goes into the help popup.
This text goes into the help popup.
This text goes into the help popup.

<span size='x-small'>Enjoy.</span>"
 </label>
 </text>
 </eventbox>
 </vbox>
 </eventbox>

 <variable>HELP_DIALOG</variable>
 <action signal="button-press-event" condition="command_is_true( [[ \$PTR_BTN == 1 ]] && echo true )">closewindow:HELP_DIALOG</action> 
 <action this-is-window="escape" signal="key-press-event" condition="command_is_true( [[ \$KEY_RAW = 0x9 ]] && echo true )">closewindow:HELP_DIALOG</action> 
 <action signal="focus-out-event">closewindow:HELP_DIALOG</action>
</window>
EODECK
export HELP_DIALOG=$(cat ${HELP_DIALOG_FILE})
## main UI
##
# window title
WIN_TITLE="EventBox Example"

cat <<-EODECK > ${MAIN_DIALOG_FILE}
<window title="${WIN_TITLE}" icon-name="${WIN_ICON}" decorated="${WIN_DECORATED}" resizable="${WIN_RESIZABLE}"
        window_position="${WIN_POS}" skip_taskbar_hint="${WIN_SKIP_TASKBAR_HINT}" allow-grow="${WIN_ALLOW_GROW}"
        auto-refresh="true" name="win0">
    <vbox width-request="${_WIDTH_REQUEST}">

        <hbox>
            <hbox homogenous="true" space-fill="true" space-expand="true">
                <text><label>Some content goes here</label></text>
            </hbox>
        </hbox>

        $(: visible-window="false" blocks delivery of clicks to the content objects, including inner eventbox objects )
        $(: but it does not prevent keystrokes from selecting buttons and pressing on them, for example )
        <eventbox above-child="false" visible-window="true">
            <frame  Outer Frame  >
                <hbox>
                    <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true"
                      can-default="true" xx-info="has-default must have can-default"
                      has-default="true" xx-info="has-default and can-default must both be true for default to work"
                      >
                        <label> _Refresh </label>
                        <input file icon="system-config-date"></input>
                        <width>16</width>
                        <action condition="command_is_true(fnDateFormatToggleNeeded '${_DATE_FORMAT_RFC3339_NS}' )">refresh:vDateFormatToggle</action>
                        <action function="refresh">vWindow</action>
                    </button>
                    <text xpad="1"><label>""</label></text>
                </hbox>

                $(: both above-child and visible-window have to be true for the event box to "block" clicks to the content )
                $(: both above-child and visible-window have to be true for the event box background colour to be seen )
                <eventbox above-child="false" visible-window="true" has-tooltip="true" tooltip-markup="This is <b>tooltip</b> for eventbox"
                          height-request="100" sensitive="true" visible="true" width-request="600">
                    <frame  Inner Frame  >
                        <hbox>
                            <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true">
                                <label> _Update </label>
                                <input file icon="system-config-date"></input>
                                <width>16</width>
                                <action condition="command_is_true(fnDateFormatToggleNeeded '${_DATE_FORMAT_TIMESTAMP}')">refresh:vDateFormatToggle</action>
                                <action function="refresh">vWindow</action>
$(fnAddRightClickActionsInline eventbox)
                            </button>
                        </hbox>

                    </frame> $(: inner frame)

                    <variable>vEventBoxOuter</variable>
                </eventbox>
            </frame> $(: outer frame)

            <variable>vEventBoxOuter</variable>
$(fnAddRightClickActionsInline eventbox)
        </eventbox>

        <hbox>
            <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true">
                <label> _Help </label>
                <input file icon="gtk-help"></input>
                <width>16</width>
                <action>launch:HELP_DIALOG</action>
            </button>

            <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true"
              can-default="true" has-default="true">
                <label> _Quit </label>
                <input file icon="gtk-quit"></input>
                <width>16</width>
                <action function="exit">QUIT</action>
            </button>
            <text xpad="5"><label>""</label></text>
        </hbox>

        $(: 'invisible entry box for persisting the state of date format togge')
        <entry visible="false">
            <default>false</default>
            <variable>vDateFormatToggle</variable>
            <input>fnDateFormatToggle</input>
        </entry>

    </vbox>

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

#== Styles ==========================================
export GTK2_RC_FILES=${LOCAL_DATA_DIR}/gtkrc
cat <<-'EOSTYLEDEF' > ${GTK2_RC_FILES}
style "outerFrameStyle" {
    bg[NORMAL]      = "slateblue"
    fg[NORMAL]      = "white"
    font_name="URW Gothic L Book 14"
}
style "innerFrameStyle" {
    bg[NORMAL]      = "white"
    fg[NORMAL]      = "navy"
    font_name="URW Gothic L Demi Oblique 10"
}

widget_class "<GtkWindow><GtkVBox><GtkEventBox>" style "outerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame>" style "outerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkLabel>" style "outerFrameStyle"
# below will not show background of the eventbox if eventbox attribute visible="false"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkContainer><GtkEventBox>" style "innerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkContainer><GtkEventBox><GtkFrame>" style "innerFrameStyle"
widget_class "<GtkWindow><GtkVBox><GtkEventBox><GtkFrame><GtkContainer><GtkEventBox><GtkFrame><GtkLabel>" style "innerFrameStyle"

style "outer_colour" { bg[NORMAL] = "#ff0000" }
widget "*outer_colour" style "outer_colour"
style "inner_colour" { bg[NORMAL] = "#ffffff" }
widget "*inner_colour" style "inner_colour"

EOSTYLEDEF

## -- post UI construction ---------------------
# fnDateFormatToggleNeeded '--rfc-3339=ns' or '-R'
fnDateFormatToggleNeeded() {
    local vWhatFormat="${1}"
    [[ "${vDateFormatToggle}" == "${vWhatFormat}" ]] && echo "false" || echo "true"
}
export -f fnDateFormatToggleNeeded

# fnDateFormatToggle
fnDateFormatToggle() {
    [[ "${vDateFormatToggle}" == "${_DATE_FORMAT_RFC3339_NS}" ]] && echo "${_DATE_FORMAT_TIMESTAMP}" || echo "${_DATE_FORMAT_RFC3339_NS}"
}
export -f fnDateFormatToggle

# fnShowTimestamp
fnShowTimestamp() {
    [[ "${cbkShowRequest}" = "true" ]] && yad \
        --center --width=400 --image="gtk-dialog-info" --window-icon="gtk-dialog-info" --title="Date format" --text="Requesting date format ${vDateFormatToggle}" \
        --button=" Dismiss!gtk-ok!Dismiss this dialogue:0"
    vDate="$(date ${vDateFormatToggle})"
    [[ "${cbkShowResponse}" = "true" ]] && yad \
        --center --width=400 --image="gtk-dialog-info" --window-icon="gtk-dialog-info" --title="Formatted Date" --text="Formatted date: ${vDate}" \
        --button=" Dismiss!gtk-ok!Dismiss this dialogue:0"
    echo ${vDate}
}
export -f fnShowTimestamp

# -- run the UI -----------------------------------------------------------------------------------------------

case ${1:-} in
    -d | --dump) more "${MAIN_DIALOG_FILE}" ;;
    -f | --file) $GTKDIALOG --center --file=${MAIN_DIALOG_FILE} ;;
    -v | --variable) export MAIN_DIALOG=$(cat ${MAIN_DIALOG_FILE}); $GTKDIALOG --center --program=MAIN_DIALOG ;;
    *) $GTKDIALOG --file=${MAIN_DIALOG_FILE} ;;
esac
## EOSCRIPT

/tmp/scripts/ex36.sh

The screenshot shown before illustrates the application appearance when the right-click menu is show. In the screenshot below one of the results of checking the checkbox is shown, as an illustration of what the button handler does when the checkboxes is checked.

Using eventboxes to add frames to objects

It may be hard to work out what space the various objects in a gtkdialog application actually occupy on the screen because most, like text labels, horizontal and vertical boxes, and others, do not have visible bounding boxes which could be used to gauge that. In this example I demonstrate hos nested event boxes can be used to add visible borders to all objects and how to quickly remove them / make them invisible. This use of eventboxes is somewhat off-field but somebody muight have a use for it, during development if not in an actual useful applications.

The following screenshot illustrates one of the manifestations of this.

Execute the following commands, including copying and pasting the body of the example between geany and EOSCRIPT.

mkdir /tmp/scripts
cd /tmp/scripts
> /tmp/scripts/ex37.sh
chmod ug+x /tmp/scripts/ex37.sh

geany /tmp/scripts/ex37.sh & # until ## EOSCRIPT
#!/bin/bash

# make directory for temporary files and have it and the content blown away at exit
#
export LOCAL_DATA_DIR="/dev/shm/$(basename ${0})"
mkdir -p ${LOCAL_DATA_DIR}

fnHlrRemoveTmporaryFilesOnExit() {
    mkdir -p ${LOCAL_DATA_DIR}
    rm -R -f ${LOCAL_DATA_DIR} 
}
trap fnHlrRemoveTmporaryFilesOnExit 0 # clean up after any program end.

# name temporary files and place them in the directory which will get deleted on termination of the script (most of the time)
export MAIN_DIALOG_FILE="${LOCAL_DATA_DIR}/MAIN_DIALOG_FILE_${USER}_${BASHPID}.gtkdialog"

##====================================================
[ -z ${GTKDIALOG:-} ] && GTKDIALOG=gtkdialog

# load symbolic constants I use instead of numeric values
source $(dirname ${0})/gtkdialog.constants

# local constants
#
_WIDTH_REQUEST=400
_SPACING=0

##### construct UI #############################

## pre-ui create functions
##
#_beginFrame() { echo -n '<eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">'; }
#endFrame_() { echo -n '</hbox></eventbox></vbox></eventbox>'; }
_beginFrame() { echo -n ''; }
endFrame_() { echo -n ''; }

## right-click settings UI
##

## main UI
##
# window title
WIN_TITLE="EventBox Example $(basename $0)"

cat <<-EODECK > ${MAIN_DIALOG_FILE}
<window title="${WIN_TITLE}" icon-name="${WIN_ICON}" decorated="${WIN_DECORATED}" resizable="${WIN_RESIZABLE}"
        window_position="${WIN_POS}" skip_taskbar_hint="${WIN_SKIP_TASKBAR_HINT}" allow-grow="${WIN_ALLOW_GROW}"
        auto-refresh="true" name="win0">
$(_beginFrame)
    <vbox width-request="${_WIDTH_REQUEST}" spacing="${_SPACING}">
$(_beginFrame)
        <vbox spacing="${_SPACING}">
$(_beginFrame)
            <hbox spacing="${_SPACING}">
$(_beginFrame)
                <hbox spacing="${_SPACING}">
$(_beginFrame)
                    <text ypad="10" xpad="50" xalign="${XALIGN_LEFT}"><label>Some content goes here</label></text>
$(endFrame_)
$(_beginFrame)
                    <text xpad="50" label=""></text>
$(endFrame_)
                </hbox>
$(endFrame_)
            </hbox>
$(endFrame_)
        </vbox>
$(endFrame_)

$(_beginFrame)
        <vbox spacing="${_SPACING}">
$(_beginFrame)
            <hbox spacing="${_SPACING}">
$(_beginFrame)
                <hbox spacing="${_SPACING}">
$(_beginFrame)
                    <text xpad="30" label="CCCC"></text>
$(endFrame_)
$(_beginFrame)
                    <text xpad="30" label="BBBB"></text>
$(endFrame_)
$(_beginFrame)
                    <text xpad="30" label="AAAA"></text>
$(endFrame_)
$(_beginFrame)
                    <text xpad="45" label=""></text>
$(endFrame_)
                </hbox>
$(endFrame_)
            </hbox>
$(endFrame_)
        </vbox>
$(endFrame_)

$(_beginFrame)
        <vbox spacing="${_SPACING}">
$(_beginFrame)
            <hbox spacing="${_SPACING}">
$(_beginFrame)
                <button width-request="100" homogenous="true" image-position="${BTN_IMG_POS_LEFT}" use-underline="true"
                  can-default="true" has-default="true">
                    <label> _Quit </label>
                    <input file icon="gtk-quit"></input>
                    <width>16</width>
                    <action function="exit">QUIT</action>
                </button>
$(endFrame_)
$(_beginFrame)
                <text xpad="5"><label>""</label></text>
$(endFrame_)
            </hbox>
$(endFrame_)
        </vbox>

$(endFrame_)
    </vbox>
$(endFrame_)

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

#== Styles ==========================================
export GTK2_RC_FILES=${LOCAL_DATA_DIR}/gtkrc
cat <<-'EOSTYLEDEF' > ${GTK2_RC_FILES}
style "outer_colour" { bg[NORMAL] = "blue" }
widget "*outer_colour" style "outer_colour"
style "inner_colour" { bg[NORMAL] = "green" }
widget "*inner_colour" style "inner_colour"

EOSTYLEDEF

## -- post UI construction ---------------------
# fnDateFormatToggleNeeded '--rfc-3339=ns' or '-R'
fnDateFormatToggleNeeded() {
    local vWhatFormat="${1}"
    [[ "${vDateFormatToggle}" == "${vWhatFormat}" ]] && echo "false" || echo "true"
}
export -f fnDateFormatToggleNeeded

# fnDateFormatToggle
fnDateFormatToggle() {
    [[ "${vDateFormatToggle}" == "${_DATE_FORMAT_RFC3339_NS}" ]] && echo "${_DATE_FORMAT_TIMESTAMP}" || echo "${_DATE_FORMAT_RFC3339_NS}"
}
export -f fnDateFormatToggle

# fnShowTimestamp
fnShowTimestamp() {
    [[ "${cbkShowRequest}" = "true" ]] && yad \
        --center --width=400 --image="gtk-dialog-info" --window-icon="gtk-dialog-info" --title="Date format" --text="Requesting date format ${vDateFormatToggle}" \
        --button=" Dismiss!gtk-ok!Dismiss this dialogue:0"
    vDate="$(date ${vDateFormatToggle})"
    [[ "${cbkShowResponse}" = "true" ]] && yad \
        --center --width=400 --image="gtk-dialog-info" --window-icon="gtk-dialog-info" --title="Formatted Date" --text="Formatted date: ${vDate}" \
        --button=" Dismiss!gtk-ok!Dismiss this dialogue:0"
    echo ${vDate}
}
export -f fnShowTimestamp

# -- run the UI -----------------------------------------------------------------------------------------------

case ${1:-} in
    -d | --dump) more "${MAIN_DIALOG_FILE}" ;;
    -f | --file) $GTKDIALOG --center --file=${MAIN_DIALOG_FILE} ;;
    -v | --variable) export MAIN_DIALOG=$(cat ${MAIN_DIALOG_FILE}); $GTKDIALOG --center --program=MAIN_DIALOG ;;
    *) $GTKDIALOG --file=${MAIN_DIALOG_FILE} ;;
esac

## EOSCRIPT

 

/tmp/scripts/ex37.sh

Executing this script using the command above produces:

It is difficult to say, looking at the screenshot, what are the boundaries of the various objects which are present inside the window.

Let’s consider the following code snippet:

$(_beginFrame)
    <vbox width-request="${_WIDTH_REQUEST}" spacing="${_SPACING}">
$(_beginFrame)
        <vbox spacing="${_SPACING}">
$(_beginFrame)
            <hbox spacing="${_SPACING}">
$(_beginFrame)
                <hbox spacing="${_SPACING}">
$(_beginFrame)
                    <text ypad="10" xpad="50" xalign="${XALIGN_LEFT}"><label>Some content goes here</label></text>
$(endFrame_)
$(_beginFrame)
                    <text xpad="50" label=""></text>
$(endFrame_)
                </hbox>
$(endFrame_)
            </hbox>
$(endFrame_)
        </vbox>
$(endFrame_)

Note the $(_beginFrame) and $(endFrame_) constructs.

Bash functions with the names _beginFrame and endFrame_ are executed at the time the gtkdialog XML file is being written using the 'cat <<-EODECK > ${MAIN_DIALOG_FILE}' “here document” construct. Whatever these functions write to the stdout becomes injected into the here document at that place.

In the following code fragment in the source given above note that the first pair of _beginFrame and endFrame_ funcions is commented out and the second pair is “active”. The active functions write an empty string to their stdout consequently only a newline is injected into the gtkdialog definition at the places they are invoked.

## pre-ui create functions
##
#_beginFrame() { echo -n '<eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">'; }
#endFrame_() { echo -n '</hbox></eventbox></vbox></eventbox>'; }
_beginFrame() { echo -n ''; }
endFrame_() { echo -n ''; }

 Execute the following on the command line to see this. The following fragment illustrates this:

/tmp/scripts/ex37.sh --dump | cat -n | more

     5        <vbox width-request="400" spacing="0">
     6   
     7            <vbox spacing="0">
     8   
     9                <hbox spacing="0">
    10   
    11                    <hbox spacing="0">
    12   
    13                        <text ypad="10" xpad="50" xalign="0"><label>Some content goes here</label></text>
    14   
    15   
    16                        <text xpad="50" label=""></text>
    17   
    18                    </hbox>
    19   
    20                </hbox>
    21   
    22            </vbox>

Now comment out the active functions and uncomment the inactive functions as shown:

## pre-ui create functions
##
_beginFrame() { echo -n '<eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">'; }
endFrame_() { echo -n '</hbox></eventbox></vbox></eventbox>'; }
#_beginFrame() { echo -n ''; }
#endFrame_() { echo -n ''; }

Execute the same command as before and note the output.

     4    <eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">
     5        <vbox width-request="400" spacing="0">
     6    <eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">
     7            <vbox spacing="0">
     8    <eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">
     9                <hbox spacing="0">
    10    <eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">
    11                    <hbox spacing="0">
    12    <eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">
    13                        <text ypad="10" xpad="50" xalign="0"><label>Some content goes here</label></text>
    14    </hbox></eventbox></vbox></eventbox>
    15    <eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">
    16                        <text xpad="50" label=""></text>
    17    </hbox></eventbox></vbox></eventbox>
    18                    </hbox>
    19    </hbox></eventbox></vbox></eventbox>
    20                </hbox>
    21    </hbox></eventbox></vbox></eventbox>
    22            </vbox>
    23    </hbox></eventbox></vbox></eventbox>

 Text in bold highlights the code which was injected into the definition of the UI.

Executing the example produces the visual appearance shown in the earlier screenshot, repeated here:

To understand what this code does let’s have a look at the artefacts which are “injected”.

The _beginFrame function emits the following code, here distributed over multiple lines for ease of reading:

<eventbox name="outer_colour" border-width="1">
    <vbox border-width="1">
        <eventbox name="inner_colour" border-width="1">
            <hbox border-width="1">

The outer eventbox sets the background colour of all it contains to whatever the style defines for the “outer_colour”, which in the example happens to be blue.

The vbox with the width of 1 causes a 1 pixel wide border to be shown. That border’s colour is inherited from the outer eventbox and is of the colour that eventbox’s style defines.

The inner eventbox sets the background colour of all of its content to the inner_colour, which happens to be green.

The innermost hbox adds a 1 pixel border around anything it contains and that border inherits the inner eventbox’s background colour.

Not the green 1 pixel border around the Quit button.

The injected _beginFrame code “starts” definitions of 4 containers. These containers must be “finished”/”closed” so the endFrame_ function supplied the closures:

            </hbox>
        </eventbox>
    </vbox>
</eventbox>

Now change the code for the _beginFrame so that it reads as follows and execute the example:

## pre-ui create functions
##
_beginFrame() { echo -n '<eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="0">'; }
endFrame_() { echo -n '</hbox></eventbox></vbox></eventbox>'; }

The ending hbox no longer provides the 1 pixel green inner border so the application window now looks like:

Note that, for all intents and purposes the green 1 pixel border around the Quit button is gone. The 1 pixel green borders around all the other components is also gone, though it is harder to see. Scroll back to the previous screenshot and compare them.

Now change the definitno so that the vbox border is 0 pixels and execute the example:

## pre-ui create functions
##
_beginFrame() { echo -n '<eventbox name="outer_colour" border-width="1"><vbox border-width="0"><eventbox name="inner_colour" border-width="1"><hbox border-width="0">'; }
endFrame_() { echo -n '</hbox></eventbox></vbox></eventbox>'; }

This results in the following appearance:

The blue lines are even closer together.

Now change the border-width of the outer eventbox to 0 and execute the example:

_beginFrame() { echo -n '<eventbox name="outer_colour" border-width="0"><vbox border-width="0"><eventbox name="inner_colour" border-width="1"><hbox border-width="0">'; }
endFrame_() { echo -n '</hbox></eventbox></vbox></eventbox>'; }

Now change the border-width of the inner eventbox to 0 and execute the example:

_beginFrame() { echo -n '<eventbox name="outer_colour" border-width="0"><vbox border-width="0"><eventbox name="inner_colour" border-width="0"><hbox border-width="0">'; }
endFrame_() { echo -n '</hbox></eventbox></vbox></eventbox>'; }

The remaining blue areas are there because:

  1. The first text element definition adds 10 pixels padding above and below the text, ‘<text ypad=”10″ ‘ but the second does not
  2. The button is “taller” than the text to the right of it

Reset the values of the 4 border-width attribtes back to 1.

Notice that the vbox and hbox objects which are injected by the _beginFrame function carry the spacing=”${_SPACING}” attribute. In the original source the value of this attribute is defined as 0:

_SPACING=0

Change the value to 10 and execute the example:

_SPACING=10

Notice that extra space was added between the vboxes and between the hboxes.

Comment out the _beginFrame and endFrame_ functions which inject the extra code, uncomment the _beginFrame and endFrame_ functions which do not inject the code and execute the example.

###_beginFrame() { echo -n '<eventbox name="outer_colour" border-width="1"><vbox border-width="1"><eventbox name="inner_colour" border-width="1"><hbox border-width="1">'; }
###endFrame_() { echo -n '</hbox></eventbox></vbox></eventbox>'; }
_beginFrame() { echo -n ''; }
endFrame_() { echo -n ''; }

Compare the original windows and the window with the extra spacing added by the hbox and vbox elements.

If one does not have a way to see the bounding boxes of the various elements it is pretty much impossible to see what adds spaces, where and how much.

Summary

We explored the styling of the notebook object and its content, reviewing in the process how one can derive paths to various UI components which the widget_class requires to apply styles.

Leave a Reply

preload preload preload