Last modification Mon Jun 20 23:46:21 2005
Sandino "tigrux" Flores <tigrux_at_ximian_dot_com>

SimpleGladeApp

Description

Module that provides an object oriented abstraction to pygtk and libglade.
Copyright (C) 2004 Sandino Flores Moreno

Index

Functions

def bindtextdomain(app_name, locale_dir=None)

Bind the domain represented by app_name to the locale directory locale_dir.
It has the effect of loading translations, enabling applications for different languages.

I18nGladeApp is an example of internationalization.

app_name:
a domain to look for translations, tipically the name of an application.
i18n_dir:
a directory with locales like i18n_dir/lang_isocode/LC_MESSAGES/app_name.mo
If omitted or None, then the current binding for app_name is used.

Classes

class SimpleGladeApp

Attributes

self.glade
An gtk.glade.XML object internally used for getting widgets and autoconnecting callbacks.
self.glade_path
Full path to the glade file.
self.main_widget
Root widget of the user interface, or None if omitted in the contructor.

def __init__(self, path, root=None, domain=None, **kwargs)

Load a glade file specified by path, using root as the name of the root widget and domain as the domain for translations.
If it receives extra named arguments (argname=value), then they are used as attributes of the instance.

path:
path to a glade filename. If glade_filename cannot be found, then it will be searched in the same directory of the program (sys.argv[0])
root:
the name of the widget that is the root of the user interface, usually a window or dialog (a top level widget).
If None or ommited, the full user interface is loaded.
domain:
A domain to use for loading translations.
If None or ommited, no translation is loaded.
**kwargs:
a dictionary representing the named extra arguments. It is useful to set attributes of new instances, for example:
glade_app = SimpleGladeApp("ui.glade", foo="some value", bar="another value")
sets two attributes (foo and bar) to glade_app.

ParentChildGladeApp is a very simple example of using named arguments to enable bidirectional communication between a parent window and a child dialog.

def new(self)

Method called when the user interface is loaded and ready to be used.
At this moment, the widgets are loaded and can be refered as self.widget_name
It does not matter if the widget has prefixes or not.

def add_callbacks(self, callbacks_proxy)

It uses the methods of callbacks_proxy as callbacks.
The callbacks are specified by using the properties dialog in glade (or any other gui designer like gazpacho).
See image 1

Methods of classes inheriting from SimpleGladeApp are used as callbacks automatically.

FirstGladeApp is a very simple example of using callbacks as methods.

callbacks_proxy:
an instance with methods as code of callbacks.
It means it has methods like on_button1_clicked, on_entry1_activate, etc.
01-properties-signals.png
01-properties-signals.png

def normalize_names(self)

It is internally used to normalize the name of the widgets.
It means a widget named foo:vbox-dialog in glade is refered self.vbox_dialog in the code.

It also sets a data "prefixes" with the list of prefixes a widget has for each widget.

def add_prefix_actions(self, prefix_actions_proxy)

By using a gui designer (glade, gazpacho, etc) widgets can have a prefix in theirs names like foo:entry1 or foo:label3
It means entry1 and label3 has a prefix action named foo.
See image 2

Then, prefix_actions_proxy must have a method named prefix_foo which is called everytime a widget with prefix foo is found, using the found widget as argument.

PrefixGladeApp is an example of prefix actions which uses them for validating input.
PrefixDBGladeApp is another example of prefix actions which uses them for binding a database to a window.

prefix_actions_proxy:
An instance with methods as prefix actions.
It means it has methods like prefix_foo, prefix_bar, etc.
02-properties-widget.png
02-properties-widget.png

def custom_handler(self, glade, function_name, widget_name, str1, str2, int1, int2)

Generic handler for creating custom widgets, internally used to enable custom widgets (custom widgets of glade).

The custom widgets have a creation function specified in design time.
See image 3

Those creation functions are always called with str1,str2,int1,int2 as arguments, that are values specified in design time.

Methods of classes inheriting from SimpleGladeApp are used as creation functions automatically.

If a custom widget has create_foo as creation function, then the method named create_foo is called with str1,str2,int1,int2 as arguments.

MozEmbedGladeApp is a very simple example that uses a custom widget for displaying html (using gtkmozembed).
TournamentGladeApp is another example of custom widgets very useful when playing videogames with friends.
BonoboMozillaGladeApp is a more complex example of custom widgets that uses them for displaying html (using gtkmozembed) and pdf documents (using bonobo).

03-properties-widget-custom.png
03-properties-widget-custom.png

def gtk_widget_show(self, widget, *args)

Predefined callback.
The widget is showed.
Equivalent to widget.show()

SignalGladeApp is an example that uses gtk_widget_show to make a widget visible with no code.

def gtk_widget_hide(self, widget, *args)

Predefined callback.
The widget is hidden.
Equivalent to widget.hide()

def gtk_widget_grab_focus(self, widget, *args)

Predefined callback.
The widget grabs the focus.
Equivalent to widget.grab_focus()

def gtk_widget_destroy(self, widget, *args)

Predefined callback.
The widget is destroyed.
Equivalent to widget.destroy()

ParentChildGladeApp is an example that uses gtk_widget_destroy for destroying a dialog when pressing a button of it.

def gtk_window_activate_default(self, window, *args)

Predefined callback.
The default widget of the window is activated.
Equivalent to window.activate_default()

def gtk_true(self, *args)

Predefined callback.
Equivalent to return True in a callback.
Useful for stopping propagation of signals.

PrefixDBGladeApp is an example that uses gtk_true to make an horizontal scale unmodificable.

def gtk_false(self, *args)

Predefined callback.
Equivalent to return False in a callback.

def gtk_main_quit(self, *args)

Predefined callback.
Equivalent to self.quit()

def main(self)

Starts the main loop of processing events.
The default implementation calls gtk.main()

Useful for applications that needs a non gtk main loop.
For example, applications based on gstreamer needs to override this method with gst.main()

Do not directly call this method in your programs. Use the method run() instead.

GstPlayerGladeApp is an example of overriding main() and quit()

def quit(self)

Quit processing events.
The default implementation calls gtk.main_quit()

Useful for applications that needs a non gtk main loop.
For example, applications based on gstreamer needs to override this method with gst.main_quit()
GstPlayerGladeApp is an example of overriding main() and quit()

def run(self)

Starts the main loop of processing events checking for Control-C.
The default implementation checks wheter a Control-C is pressed, then calls on_keyboard_interrupt().

Use this method for starting programs.
This method must be called just once per program, because gtk programs use an infinite loop for processing events.

def on_keyboard_interrupt(self)

This method is called by the default implementation of run() after a program is finished by pressing Control-C.