PyGTK 2.0 Quick Start Guide By Jeremy Bongio

Table of Contents “Overview” of Python Concepts of GTK Implementing pyGTK

“Overview” of Python ● Basic Layout – Interpreted – Space sensitive ● Classes ● Functions ● Conditionals ● Variables ● Lists ● Refer to intro_to_python.py

Concepts of GTK ● Widgets ● Signals and Signal Handlers ● Callbacks ● Events ● Packing Widgets ● Basic program structure

Widgets ● A widget is a general term for any of the components in a window, including: – Scrollbars – Buttons – Menus – Tabs – Tables – Sliders – Text – text boxes – Labels – etc.

Signals and Signal Handlers ● A signal is a message that is emitted when certain actions are done to a widget. For example, a widget may be “toggled”, “clicked”, “destroyed”, etc. ● A signal handler waits until a specific signal is presented. Then the handler executes a predetermined function in response.

Callback Functions and Events ● The function that is run by a signal handler in response to a signal is called a Callback function.

Events ● Not only can callback functions be executed in response to signals, but they can be attached to events. ● An event is basically a signal, but it is does not originate from a widget. Examples: button_press_event, destroy_event, scroll_event, focus_in_event, key_press_event, etc.

Packing Widgets into Windows ● By default, a window doesn't apply any order to the widgets it contains. To remedy this, there are packing widgets. ● Widgets are put inside of packing widgets, including other packing widgets.

Types of Packing Widgets ● Horizontal Box ● Vertical Box ● Tables ● And more!

Basic Program Structure ● Generally, building a GUI in GTK goes something like this. – Include path to python and import needed libraries – Create first window – Create a widget packing scheme – Create the necessary widgets – Connect widgets to signal handlers – Pack widgets into window – Show everything starting with small things and working up to the main window.

The Source Code

Initial Setup ● First thing's first, make sure you have #!/usr/bin/env python as the very first line of the program. ● Next, import the gtk and pygtk libraries as follows: – Import pygtk – Import gtk ● And to make things run smoother in the future you can include the line: – pygtk.require('2.0')

First Thing's First, A Window ● self.window = gtk.Window(gtk.WINDOW_TOPLEVEL) ● This creates a new, invisible window completely blank, containing no widgets. ● Later you may want to close a particular window. self.window.destroy() will do the trick. ● Or else close the program entirely with gtk.main_quit()

Horizontal Box Packaging ● To create a horizontal box widget to pack other widgets into: h_box=gtk.HBox(homogeneous=False,spacing=0) ● Spacing is the number of pixels that will separate each widget in this package. ● If homogeneous is true, all widgets in this package will be of the same dimensions. ● To add a widget to this box: h_box.pack_start(button,expand=False,fill=False,padding=20)

Vertical Box Packaging ● To create a vertical box widget to pack other widgets into: v_box=gtk.VBox(homogeneous=False,spacing=0) ● To add a widget to this box: v_box.pack_start(button,expand=False,fill=False,padding=20) ● Expand allows this widget to grow as the window size changes. ● Fill allows this widget to fill any white space that is formed when window resizes. ● Padding is the number of pixels that will separate this widget from the others.

Table Packaging ● To create a table widget to pack other widgets into: table=gtk.Table(rows=2,columns=2,homogeneous=False) ● To add a widget to the top left of this table: table.attach(button,0,1,0,1) ● The first two numbers define the top column. The last two numbers define the row. ● The widgets in this table automatically fill whitespace and enlarge as the window is resized.

Common Buttons ● Normal button ● Radio button ● Checklist Button ● Toggle Button

Implementing a Common Buttons ● For a normal button: button=gtk.Button(“This is the label”) ● For the first radio button in a line: button=gtk.RadioButton(None,”Label”) ● Before adding more radio buttons, pack this button first. Otherwise you redefine the first button. OR just use different names for each. ● For the rest of the radio buttons: button=gtk.RadioButton(button,”Label”)

Common Buttons Continued ● For a toggle button: button=gtk.ToggleButton(“label”) ● For a checklist button: button=gtk.CheckButton(“label”) ● Of course, what good is a button if it doesn't do anything?

Signals and Signal Handlers Implemented ● First, you must create a function that will act as the callback function. Example: def button_clicked(self, widget, data): self.window1 = gtk.Window(gtk.WINDOW_TOPLEVEL) label = gtk.Label("title") label.set_text("You clicked on button "+data+"!!!") label.show() self.window1.add(label) self.window1.connect("destroy", self.kill_window) self.window1.show()

Signal Handlers ● To connect a button to this new callback function: button.connect(“clicked”,self.button_clicked,”data”) ● The first argument is the signal that will trigger this signal handler. ● The second argument is the name of the callback function. ● The third argument is any data that you want the callback function to know, or None if you don't want anymore information.

Displaying Information to User ● Label: label=gtk.Label(“title of label”) label.set_text(“the displayed text”) ● Tool tips: tooltip=gtk.Tooltips() tooltip.set_tip(button,”displayed tip”) ● Scrollable lists of dynamic data. UGH, ask me later!

Text Entry ● Text entry allows for user input through a text window. Examples of use: ● entry=gtk.Entry(max=0) ● entry.set_max_length(max) ● entry.set_text(text) ● entry.set_editable(True) ● To get text the user typed in box: ● text=entry.get_text()

At the End ● Important, remember that every window and widget that you want to show up on the screen must be specifically told to “.show()” ● Like: button.show(), window.show(), h_box.show()

Glade – Rapid Development Tool

Example of Glade Use ● self.glade_xml=gtk.glade.XML(gladepath,'MigrationWindow') ● self.glade_xml.signal_autoconnect({ “on_close_clicked” : self.close}) ● gladepath = “file.glade”

Where to Go for More ● l/A very thorough tutorial. Go here for any questions you have or clarifications you need. l/ ● A tutorial on how to use gtk 2.0 in C. Basically the same, just in C syntax. ● Another tutorial, learn all about python.

Questions?