A GUI description language - purpose¶

The class Layout is a class that understands a GUI description language to create GUI on the fly, with minimal effort by the programmers, that doesn’t need to know a lot of Gtk details.

You cannot do any possible thing you would do with gtk, but methods are provided to refine the layout and it isn’t difficult to add GtkObjects or features.

The purpose is to easy things with simple setup, not to cover any possible graphical layout. The main purpose is to be used in designing layout of record editor (Features) for db, but it can be used with any other program as well.

Layout is not an interactive tool: it uses gtk.Builder xml to create the GUI, ie: it produces xml for gtk.Builder.

Note

gtk.Builder

up to 0.9.2 sqlkit used glade. This dependancy has been dropped in favor of gtk.Builder that is directly available in standard GTK installation.

Care must be used to create names for the elements that are unique in the single layout, so as to be able to reach any single object, not only to refine configuration but also to interact with the GtkObj in the program. This reflects in the fact that the name is unique.

A normal GUI is plenty of labels and tooltip. At the moment of this writing no localization is provided but gettext support is in program.

Description of the language¶

a starting example:

layout = """
   el=first_name  el=last_name
   el=address     -
"""

A layout is a sequence of tokens and display modifiers.

token:

describes a GtkObject (Button, Entry...), may also be a compound. An example: el=first_name. They will normally start with a description key, followed by a ‘=’ and then followed by a string possibly separated by a ‘/’ and.or a:

key=string/variable:wid1.wid2

or in regexp notation and more precise:

(key=)string(.[0-9a-z])?(/variable)((:width.)(width)([-<>]))?
 key   txt    id          var        width1   width2  align

no element is needed apart the ‘string’, the key defaults to ‘el’ (Entry + Label), the variable defaults to the string, wid1 and wid2 (described below) use GtkWidget defaults.

The string part may end with .[a-z0-9] just to be able to refer in a unique way to single elements that are apparently equal (see element names)

an indication of the desidered alignment may be given using one of (‘-‘, ‘<’, ‘>’). this take effect oly if the element is position in a gtk.Alignment (eg. ‘ae’ element ie: entry with width). in that case:

>: right alignment (xalign = 1)

<: left alignment (xalign = 0)

-: xscale of the alignment is set to 1 i.e. the child of the alignment (the entry in the example will grow when more space is given to the widget)

spare token:

A token may further be:

@: it is equivalent to a newline (in fact I figure it like spinning ;-)

-: forces the previous element to span one more column to the left

^: forces the element above it to span one more row down

%.*: the element is a label for a notebook (see ‘notebook’ method)

display modifiers:

A modifier is an element that modifies the way elements are arranged, mainly it modifies the packing info or the container, but can also modify the display eg: label and entry on the same line or one above the other. A modifier is:

{}:
a pair of curly braces

[XTHVbNPSvhpOBmMFA](.id):

(possibly) followed (w/out spaces) by some opts as in {V r=man/sex r=woman}, this will create a nester layout with 2 radiobutton packed into a GtkVBox. For an explanation of the (.id) part see below (container naming)

Possible opts are XTHVbNPSvhpOBmMFA:

T: gtkTable

H: gtkHBox

V: gtkVBox

N: gtkNotebook

F: gtkFrame

M: gtkMenubar

t: gtkToolBar

h: gtkHPaned

v: gtkVPaned

S: gtkScrolledWindow

B: gtkMenuBar

M: gtkMenu

m: gtkMenuItem

O: gtkToolbar

W: Window

E: EventBox

X: Expander

p: ViewPort

A: Alignment

Elements will be packed in a table widget unless changed by a option when instantiating the class as in:

lay = Layout(lay, opts="V=")

Other values for opts are [>=-|] - to be confirmed

=:	implies that label and entry will be displayed one over the other (this is the default)
-:	implies that label and entry will be displayed on the same line.
\|:	will draw a line around the widgets, using a frame. That means a GtkFrame and a GtkAlignment are silently created. You can set properties of the silently created expander using key F.id
>:	will encapsulate the result into an Expander that allows to collapse all its content via a click on a little arrow. You can set properties of the silently created expander using key X.id. A double ‘>>’ results in an expanded expander. The id is used as label for the expander. so that ‘>>.clients’, will be expanded in an oped expander with a label “clients”

a longer example¶

el=first_name                  el=last_name
el=address                     -
{V r=man/sex      r=woman/sex}  b=register

Comment¶

A ‘#’ sign starts a comment. Anything till the end of the line will be discarded, as usual...

el element¶

the most used element will probably turn out to be a Label + Entry widget that can be constructed as in el=first name. It will really be understood as:

{ l=first_name el=first_name }

or:

{ l=first_name
  el=first_name }

According to the opt modifier = or -

list of elements¶

A partial list of elements:

l: Label,

L: EventLabel, a label in a GtkEventBox

e: Entry,

E: Event,

b: Button,

r: RadioButton,

c: CheckButton,

TV: TreeView,

TX: TextView,

TVS: ScrolledTreeView,

TXS: ScrolledTextView,

cal: Calendar,

sb: Statusbar,

le: ComboLE,

more symbols are in the source...

custom widgets¶

Occasionally you will find yourself in nee for a custom identifier. You can create one and register it. Have a look at the code in layoutgenerator module.

Calling Layout¶

def __init__(self, lay, level=0, parent_container="W", opts="T",
             elements={}, container_id='',title="Window",dbg=0):

parent_container:
lay:	the string describing the desired layout
level:	nested level (used only by layout itself)
	a flag among the container flags that says which is the container: determines the packing info for the result. Default is W (Window) as a toplevel window. In this case info for a toplevel window is built.
opts:	This string has the same meaning of the modifier string of a container that can be put directly after the ‘{‘ char. Mainly this is a way to force the use of a container for the outer call of layout. Default is to put all widgets in a GtkTable but any container can be chosen from the container flags. A special component of ‘opts’, is ‘s’ that asks to add a StatusBar. The method ‘sb’ is provided to talk with that Statusbar whose key name is sb=StBar.
addto:	follows the name of a container that will receive the resulting layout. Must be a container that accept ‘add’ method.

methods¶

NOTE: some methods can only be called after ‘show’ has being called. These methods use gtk directly, not glade.

xml(file=None):
will produce the xml needed for glade, may be write to file

show(action=function_name):

will directly call glade to display the GUI, returns a dict of Gtk objects whose keys are the element keys. After this method there is no point in changing elements[] properties. The action can be gtk.main.

elements:
a dict of all lwidgets. The keys are the element definitions. Any element can be configure up to the moment show is called.

conf(el,property):
will set a property for an element of the layout equivalent to:
elements['el_key'].properties['name'] = value
sig(list):
will set handlers for the signal for each widget. The list is a list of tuples of 3 elements:

el_key

handler

signal. If the last is missing, clicked is used

tip (el, text):
a tooltip for the element ‘el’. It tip is called before ‘show’, it will end up in xml+glade, otherwise it will call gtkTooltip directly

sb(text):
will push text on the StatusBar

menu(‘el_key’, (entry-name, handler, signal=activated), ‘i’), (), ():

Will add MenuItems (Stock ImageMenuItems if 4^ element is ‘i’)

notebook(‘el_key’, [‘label 1’, ‘label2’,...],position):

Adds the label to tabs and allow to set the position (top,left, right, bottom) for a GtkNotebook. There is another way to obtain this effect. You can add %label as first entry in the block that will be enclosed in the notebook. See below: notebook

frame(‘el_key’, ‘label’):

Adds a label to a frame, and writes it w/ bold face

prop(el_key,property_name, value):

Sets a property for element el_key

pack(el_key,property_name, value):

Sets a pack property for element el_key

element names¶

For each element of the layout we need to build a key for xml, so that we know how to refer to the gtk object in the program. Layout will build the name starting from what was written in the element description, if that results in being already used it builds a unique name adding a number, but that may result in difficulty to interact with it from inside the program.

If that’s an issue try being clear when creating the layout. Use ids, the string separated by a ‘.’ that you can add to element names and to container flags:

container:
{H.Z   {B.id0
element names:
e=name.id1/string

stock names¶

if the name of an element starts with ‘gtk-‘, use-stock = True is set for that element.

Notebook¶

A notebook need some labels to identify the tabs. These are other child of the GtkNotebook container interspersed with the content of the container. You can set them with the notebook method, or you can use a symbol in the describing string using % trailer:

{N.0  { %first_tab_RIGHT
      TXS=one }
    { %second_tab
      TXS=due
    }
}

will be equivalent to:

l.notepad('N.0', ['first tab','second tab'], 'right')

Please, note that you can enforce a position with a trailing _(LEFT|TOP|...) to the first label. Note also that any underscore will be substituted w/ a space.

Automatic name mechanism¶

A normal element definition is of the form:

  key=string/variable:width.height


* the :width.width part is discarded
* the rest is used as key, *but*
* if no 'key=' part was explicitly used as in 'first_name' two will be
  created: e=string, l=string

container naming¶

Containers need a name too. You are supposed to know which one is used: it will be GtkTable unless you asked for a different one. You need it in case you want to modify its properties.

Their name will be the container flag [THVbNPSvhpOBmMFA] possibly followed by a dot . and an identifier. The identifier will be a progressive counter, starting from 0 but may be imposed appending .id to the flags of the container, as in:

{V.my_id first_name last_name }

Functions¶

map_layouts(filename=None, buf=None)

This functions fills in a dictionary widgets.info whose structure is:

name : (label, tip)

when a widget is created w/ name ‘name’ the label will be set to ‘label’ and a tooltip will be set to ‘tip’. This can help a lot in many situations. Db field name will be mapped to user friendly labels, translation will be as easy as pointing to a different file.

The function can point to a filename or can read a string. You can write directly the info dictionary if you prefer...

Layout class implementation¶

Each layout live in a container (may be a toplevel Window) and creates a container to house its children. This can cause a little bit of confusion so I call parent_container the container in which a widget live and container the Gtk container (Table, HBox, VBox...) where I house layout children.

You can think at your layout as divided in blocks, each one named ‘cell’ in the code. A cell is or the definition of a gtkObj or a nested layout. You can see this list for debugging purposes with method _dbg_parse_layout.

You can think at these cells as displayed in a grid, each one defined by a row and a column. The constructor of Layout uses a dict named ‘cells’ with indices (row,col) to store the name of the corresponding LWidget or LContainer.

When the object is instantiated, Layout

creates a container (LContainer object)

splits the layout description into tokens that are or -a element descriptions - nested layouts (starts w/ ‘{‘) ...

For each token that describes a single element, creates the corresponding lwidget object, for each nested layout creates another instance of Layout.

LWidgets and LContainer¶

the difference between an LWidget and an LContainer is that an LContainer has children and must pack info for all the children when producing xml (apart from producing the xml for itself)

Window creation¶

Each call to Layout must create a container to house all its children, but the first (or outer) one needs normally to create also the TopLevel Window, that to us is nothing than another LContainer whose (only) child is just another container (the outer one for Layout).

Producing xml¶

Layout produces xml just asking to the toplevel (an LContainer object) to produce xml. LContainer xml, produces xml for itself and for its children, if some of them is a container the process iterates.

Table of contents

Questions?

A GUI description language - purpose¶

Description of the language¶

a longer example¶

Comment¶

el element¶

list of elements¶

custom widgets¶

Calling Layout¶

methods¶

element names¶

stock names¶

Notebook¶

Automatic name mechanism¶

container naming¶

Functions¶

Layout class implementation¶

LWidgets and LContainer¶

Window creation¶

Producing xml¶

l:	Label,
L:	EventLabel, a label in a GtkEventBox
e:	Entry,
E:	Event,
b:	Button,
r:	RadioButton,
c:	CheckButton,
TV:	TreeView,
TX:	TextView,
TVS:	ScrolledTreeView,
TXS:	ScrolledTextView,
cal:	Calendar,
sb:	Statusbar,
le:	ComboLE,

show(action=function_name):
xml(file=None):	will produce the xml needed for glade, may be write to file
	will directly call glade to display the GUI, returns a dict of Gtk objects whose keys are the element keys. After this method there is no point in changing elements[] properties. The action can be gtk.main.
elements:	a dict of all lwidgets. The keys are the element definitions. Any element can be configure up to the moment show is called.
conf(el,property):
	will set a property for an element of the layout equivalent to: elements['el_key'].properties['name'] = value
sig(list):	will set handlers for the signal for each widget. The list is a list of tuples of 3 elements: el_key handler signal. If the last is missing, clicked is used
tip (el, text):	a tooltip for the element ‘el’. It tip is called before ‘show’, it will end up in xml+glade, otherwise it will call gtkTooltip directly
sb(text):	will push text on the StatusBar
menu(‘el_key’, (entry-name, handler, signal=activated), ‘i’), (), ():
	Will add MenuItems (Stock ImageMenuItems if 4^ element is ‘i’)
notebook(‘el_key’, [‘label 1’, ‘label2’,...],position):
	Adds the label to tabs and allow to set the position (top,left, right, bottom) for a GtkNotebook. There is another way to obtain this effect. You can add %label as first entry in the block that will be enclosed in the notebook. See below: notebook
frame(‘el_key’, ‘label’):
	Adds a label to a frame, and writes it w/ bold face
prop(el_key,property_name, value):
	Sets a property for element el_key
pack(el_key,property_name, value):
	Sets a pack property for element el_key

Table of contents

Questions?

Quick search

License

A GUI description language - purpose¶

Description of the language¶

a longer example¶

Comment¶

el element¶

list of elements¶

custom widgets¶

Calling Layout¶

methods¶

element names¶

stock names¶

Notebook¶

Automatic name mechanism¶

container naming¶

Functions¶

Layout class implementation¶

LWidgets and LContainer¶

Window creation¶

Producing xml¶