PyGTK 2.0 Tutorial

John Finlay

Version 2.5

March 2, 2006

Revision History
Revision 2.4April 13, 2005
Update example programs
Revision 2.3December 24, 2004
Add more PyGTK 2.4 widgets
Revision 2.2August 3, 2004
Add new PyGTK 2.2 and some PyGTK 2.4 widgets
Revision 2.1July 6, 2004
More TreeView
Revision 2.0May 24, 2004
First release for PyGTK 2.0

Abstract

This tutorial describes the use of the Python PyGTK module.


Table of Contents

1. Introduction
1.1. Exploring PyGTK
2. Getting Started
2.1. Hello World in PyGTK
2.2. Theory of Signals and Callbacks
2.3. Events
2.4. Stepping Through Hello World
3. Moving On
3.1. More on Signal Handlers
3.2. An Upgraded Hello World
4. Packing Widgets
4.1. Theory of Packing Boxes
4.2. Details of Boxes
4.3. Packing Demonstration Program
4.4. Packing Using Tables
4.5. Table Packing Example
5. Widget Overview
5.1. Widget Hierarchy
5.2. Widgets Without Windows
6. The Button Widget
6.1. Normal Buttons
6.2. Toggle Buttons
6.3. Check Buttons
6.4. Radio Buttons
7. Adjustments
7.1. Creating an Adjustment
7.2. Using Adjustments the Easy Way
7.3. Adjustment Internals
8. Range Widgets
8.1. Scrollbar Widgets
8.2. Scale Widgets
8.2.1. Creating a Scale Widget
8.2.2. Methods and Signals (well, methods, at least)
8.3. Common Range Methods
8.3.1. Setting the Update Policy
8.3.2. Getting and Setting Adjustments
8.4. Key and Mouse Bindings
8.5. Range Widget Example
9. Miscellaneous Widgets
9.1. Labels
9.2. Arrows
9.3. The Tooltips Object
9.4. Progress Bars
9.5. Dialogs
9.5.1. Message Dialogs
9.6. Images
9.6.1. Pixmaps
9.7. Rulers
9.8. Statusbars
9.9. Text Entries
9.10. Spin Buttons
9.11. Combo Widget
9.12. Calendar
9.13. Color Selection
9.14. File Selections
9.15. Font Selection Dialog
10. Container Widgets
10.1. The EventBox
10.2. The Alignment widget
10.3. Fixed Container
10.4. Layout Container
10.5. Frames
10.6. Aspect Frames
10.7. Paned Window Widgets
10.8. Viewports
10.9. Scrolled Windows
10.10. Button Boxes
10.11. Toolbar
10.12. Notebooks
10.13. Plugs and Sockets
10.13.1. Plugs
10.13.2. Sockets
11. Menu Widget
11.1. Manual Menu Creation
11.2. Manual Menu Example
11.3. Using ItemFactory
11.4. Item Factory Example
12. Drawing Area
12.1. Graphics Context
12.2. Drawing Methods
13. TextView Widget
13.1. TextView Overview
13.2. TextViews
13.3. Text Buffers
13.3.1. TextBuffer Status Information
13.3.2. Creating TextIters
13.3.3. Text Insertion, Retrieval and Deletion
13.3.4. TextMarks
13.3.5. Creating and Applying TextTags
13.3.6. Inserting Images and Widgets
13.4. Text Iters
13.4.1. TextIter Attributes
13.4.2. Text Attributes at a TextIter
13.4.3. Copying a TextIter
13.4.4. Retrieving Text and Objects
13.4.5. Checking Conditions at a TextIter
13.4.6. Checking Location in Text
13.4.7. Moving Through Text
13.4.8. Moving to a Specific Location
13.4.9. Searching in Text
13.5. Text Marks
13.6. Text Tags and Tag Tables
13.6.1. Text Tags
13.6.2. Text Tag Tables
13.7. A TextView Example
14. Tree View Widget
14.1. Overview
14.2. The TreeModel Interface and Data Stores
14.2.1. Introduction
14.2.2. Creating TreeStore and ListStore Objects
14.2.3. Referring to TreeModel Rows
14.2.4. Adding Rows
14.2.5. Removing Rows
14.2.6. Managing Row Data
14.2.7. Python Protocol Support
14.2.8. TreeModel Signals
14.2.9. Sorting TreeModel Rows
14.3. TreeViews
14.3.1. Creating a TreeView
14.3.2. Getting and Setting the TreeView Model
14.3.3. Setting TreeView Properties
14.4. CellRenderers
14.4.1. Overview
14.4.2. CellRenderer Types
14.4.3. CellRenderer Properties
14.4.4. CellRenderer Attributes
14.4.5. Cell Data Function
14.4.6. CellRendererText Markup
14.4.7. Editable Text Cells
14.4.8. Activatable Toggle Cells
14.4.9. Editable and Activatable Cell Example Program
14.5. TreeViewColumns
14.5.1. Creating TreeViewColumns
14.5.2. Managing CellRenderers
14.6. Manipulating TreeViews
14.6.1. Managing Columns
14.6.2. Expanding and Collapsing Child Rows
14.7. TreeView Signals
14.8. TreeSelections
14.8.1. Getting the TreeSelection
14.8.2. TreeSelection Modes
14.8.3. Retrieving the Selection
14.8.4. Using a TreeSelection Function
14.8.5. Selecting and Unselecting Rows
14.9. TreeView Drag and Drop
14.9.1. Drag and Drop Reordering
14.9.2. External Drag and Drop
14.9.3. TreeView Drag and Drop Example
14.10. TreeModelSort and TreeModelFilter
14.10.1. TreeModelSort
14.10.2. TreeModelFilter
14.11. The Generic TreeModel
14.11.1. GenericTreeModel Overview
14.11.2. The GenericTreeModel Interface
14.11.3. Adding and Removing Rows
14.11.4. Memory Management
14.11.5. Other Interfaces
14.11.6. Applying The GenericTreeModel
14.12. The Generic CellRenderer
15. New Widgets in PyGTK 2.2
15.1. Clipboards
15.1.1. Creating A Clipboard
15.1.2. Using Clipboards with Entry, Spinbutton and TextView
15.1.3. Setting Data on a Clipboard
15.1.4. Retrieving the Clipboard Contents
15.1.5. A Clipboard Example
16. New Widgets in PyGTK 2.4
16.1. The Action and ActionGroup Objects
16.1.1. Actions
16.1.2. ActionGroups
16.2. ComboBox and ComboBoxEntry Widgets
16.2.1. ComboBox Widgets
16.2.2. ComboBoxEntry Widgets
16.3. ColorButton and FontButton Widgets
16.3.1. ColorButton Widgets
16.3.2. FontButton Widgets
16.4. EntryCompletion Objects
16.5. Expander Widgets
16.6. File Selections using FileChooser-based Widgets
16.7. The UIManager
16.7.1. Overview
16.7.2. Creating a UIManager
16.7.3. Adding and Removing ActionGroups
16.7.4. UI Descriptions
16.7.5. Adding and Removing UI Descriptions
16.7.6. Accessing UI Widgets
16.7.7. A Simple UIManager Example
16.7.8. Merging UI Descriptions
16.7.9. UIManager Signals
17. Undocumented Widgets
17.1. Accel Label
17.2. Option Menu
17.3. Menu Items
17.3.1. Check Menu Item
17.3.2. Radio Menu Item
17.3.3. Separator Menu Item
17.3.4. Tearoff Menu Item
17.4. Curves
17.5. Gamma Curve
18. Setting Widget Attributes
18.1. Widget Flag Methods
18.2. Widget Display Methods
18.3. Widget Accelerators
18.4. Widget Name Methods
18.5. Widget Styles
19. Timeouts, IO and Idle Functions
19.1. Timeouts
19.2. Monitoring IO
19.3. Idle Functions
20. Advanced Event and Signal Handling
20.1. Signal Methods
20.1.1. Connecting and Disconnecting Signal Handlers
20.1.2. Blocking and Unblocking Signal Handlers
20.1.3. Emitting and Stopping Signals
20.2. Signal Emission and Propagation
21. Managing Selections
21.1. Selection Overview
21.2. Retrieving the Selection
21.3. Supplying the Selection
22. Drag-and-drop (DND)
22.1. DND Overview
22.2. DND Properties
22.3. DND Methods
22.3.1. Setting Up the Source Widget
22.3.2. Signals On the Source Widget
22.3.3. Setting Up a Destination Widget
22.3.4. Signals On the Destination Widget
23. GTK's rc Files
23.1. Functions For rc Files
23.2. GTK's rc File Format
23.3. Example rc file
24. Scribble, A Simple Example Drawing Program
24.1. Scribble Overview
24.2. Event Handling
24.2.1. Scribble - Event Handling
24.3. The DrawingArea Widget, And Drawing
25. Tips For Writing PyGTK Applications
25.1. The user should drive the interface, not the reverse
25.2. Separate your data model from your interface
25.3. How to Separate Callback Methods From Signal Handlers
25.3.1. Overview
25.3.2. Inheritance
25.3.3. Inheritance Applied To PyGTK
26. Contributing
27. Credits
27.1. Original GTK+ Credits
27.2. PyGTK Tutorial Credits
28. Tutorial Copyright and Permissions Notice
A. GTK Signals
A.1. GtkObject
A.2. GtkWidget
A.3. GtkData
A.4. GtkContainer
A.5. GtkCalendar
A.6. GtkEditable
A.7. GtkNotebook
A.8. GtkList
A.9. GtkMenuShell
A.10. GtkToolbar
A.11. GtkButton
A.12. GtkItem
A.13. GtkWindow
A.14. GtkHandleBox
A.15. GtkToggleButton
A.16. GtkMenuItem
A.17. GtkCheckMenuItem
A.18. GtkInputDialog
A.19. GtkColorSelection
A.20. GtkStatusBar
A.21. GtkCurve
A.22. GtkAdjustment
B. Code Examples
B.1. scribblesimple.py
C. ChangeLog

List of Figures

2.1. Simple PyGTK Window
2.2. Hello World Example Program
3.1. Upgraded Hello World Example
4.1. Packing: A Single Widget in a Container
4.2. Packing: Two Widgets in a Container
4.3. Packing: Five Variations
4.4. Packing with Spacing and Padding
4.5. Packing with pack_end()
4.6. Packing using a Table
6.1. Button with Pixmap and Label
6.2. Toggle Button Example
6.3. Check Button Example
6.4. Radio Buttons Example
8.1. Range Widgets Example
9.1. Label Examples
9.2. Arrows Buttons Examples
9.3. Tooltips Example
9.4. ProgressBar Example
9.5. Example Images in Buttons
9.6. Pixmap in a Button Example
9.7. Wheelbarrow Example Shaped Window
9.8. Rulers Example
9.9. Statusbar Example
9.10. Entry Example
9.11. Spin Button Example
9.12. Calendar Example
9.13. Color Selection Dialog Example
9.14. File Selection Example
9.15. Font Selection Dialog
10.1. Event Box Example
10.2. Fixed Example
10.3. Layout Example
10.4. Frame Example
10.5. Aspect Frame Example
10.6. Paned Example
10.7. Scrolled Window Example
10.8. Toolbar Example
10.9. Notebook Example
11.1. Menu Example
11.2. Item Factory Example
12.1. Drawing Area Example
13.1. Basic TextView Example
13.2. TextView Example
14.1. Basic TreeView Example Program
14.2. TreeViewColumns with CellRenderers
14.3. CellRenderer Data Function
14.4. File Listing Example Using Cell Data Functions
14.5. CellRendererText Markup
14.6. Editable and Activatable Cells
14.7. Expander Arrow in Second Column
14.8. TreeView Drag and Drop Example
14.9. TreeModelSort Example
14.10. TreeModelFilter Visibility Example
14.11. Generic TreeModel Example Program
15.1. Clipboard Example Program
16.1. Simple Action Example
16.2. Basic Action Example
16.3. Actions Example
16.4. ActionGroup Example
16.5. Basic ComboBox
16.6. ComboBox with Wrapped Layout
16.7. Basic ComboBoxEntry
16.8. ColorButton Example
16.9. FontButton Example
16.10. EntryCompletion
16.11. Expander Widget
16.12. File Selection Example
16.13. Simple UIManager Example
16.14. UIMerge Example
21.1. Get Selection Example
21.2. Set Selection Example
22.1. Drag and Drop Example
24.1. Scribble Drawing Program Example
24.2. Simple Scribble Example

List of Tables

22.1. Source Widget Signals
22.2. Destination Widget Signals