Pro PHP-GTK
Scott Mattocks
6137ch00FM.qxd 3/14/06 1:52 PM Page i
Pro PHP-GTK
Copyright © 2006 by Scott Mattocks
All rights reserved. No part of this work may be reproduced or transmitted in any form or by any means,
electronic or mechanical, including photocopying, recording, or by any information storage or retrieval
system, without the prior written permission of the copyright owner and the publisher.
ISBN-13: 978-1-59059-613-5
ISBN-10: 1-59059-613-7
Printed and bound in the United States of America 9 8 7 6 5 4 3 2 1
Trademarked names may appear in this book. Rather than use a trademark symbol with every occurrence
of a trademarked name, we use the names only in an editorial fashion and to the benefit of the trademark
owner, with no intention of infringement of the trademark.
Lead Editor: Jason Gilmore
Technical Reviewers: Christian Weiske, Steph Fox
Editorial Board: Steve Anglin, Dan Appleman, Ewan Buckingham, Gary Cornell, Jason Gilmore,
Jonathan Hassell, James Huddleston, Chris Mills, Matthew Moodie, Dominic Shakeshaft, Jim Sumser,
Matt Wade
Project Manager: Kylie Johnston
Copy Edit Manager: Nicole LeClerc
Copy Editors: Marilyn Smith, Jennifer Whipple
Assistant Production Director: Kari Brooks-Copony
Production Editor: Ellie Fountain
Compositor: Kinetic Publishing Services, LLC
Proofreader: Dan Shaw
Indexer: Valerie Perry
Cover Designer: Kurt Krames
Manufacturing Director: Tom Debolski
Distributed to the book trade worldwide by Springer-Verlag New York, Inc., 233 Spring Street, 6th Floor,

New York, NY 10013. Phone 1-800-SPRINGER, fax 201-348-4505, e-mail , or
visit .
For information on translations, please contact Apress directly at 2560 Ninth Street, Suite 219, Berkeley, CA
94710. Phone 510-549-5930, fax 510-549-5939, e-mail , or visit .
The information in this book is distributed on an “as is” basis, without warranty. Although every precaution
has been taken in the preparation of this work, neither the author(s) nor Apress shall have any liability to
any person or entity with respect to any loss or damage caused or alleged to be caused directly or indirectly
by the information contained in this work.
The source code for this book is available to readers at in the Source Code section.
6137ch00FM.qxd 3/14/06 1:52 PM Page ii
To my wife Cristina:
Thanks for giving me the courage to start this book
and for having the patience to let me finish.
6137ch00FM.qxd 3/14/06 1:52 PM Page iii
6137ch00FM.qxd 3/14/06 1:52 PM Page iv
Contents at a Glance
About the Author. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
About the Technical Reviewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
■CHAPTER 1 Introducing PHP-GTK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
■CHAPTER 2 Installing PHP-GTK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
■CHAPTER 3 Understanding PHP-GTK Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
■CHAPTER 4 Handling Events and Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
■CHAPTER 5 Getting an Application Up and Running . . . . . . . . . . . . . . . . . . . . . . . . . 65
■CHAPTER 6 Laying Out Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
■CHAPTER 7 Displaying and Collecting Simple Data . . . . . . . . . . . . . . . . . . . . . . . . 119
■CHAPTER 8 Using Multiline Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
■CHAPTER 9 Working with Trees and Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
■CHAPTER 10 Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
■CHAPTER 11 Adding Menus and Toolbars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

■CHAPTER 12 Adding Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
■CHAPTER 13 Drag-and-Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
■CHAPTER 14 Using Selectors & Dialogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
■CHAPTER 15 Doing Background Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
■CHAPTER 16 Changing the Look and Feel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
■CHAPTER 17 Distributing PHP-GTK Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
■INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
v
6137ch00FM.qxd 3/14/06 1:52 PM Page v
6137ch00FM.qxd 3/14/06 1:52 PM Page vi
Contents
About the Author. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
About the Technical Reviewer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
■CHAPTER 1 Introducing PHP-GTK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
A Real-World Project. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
GUI Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
What Is PHP? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Object-Oriented PHP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
PHP’s DOM and SOAP Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
What Is GTK? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
What Is PHP-GTK?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Why Use PHP-GTK?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Further Resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
■CHAPTER 2 Installing PHP-GTK. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Installing PHP-GTK 2 on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Installing PHP-GTK 2 on Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Using PEAR and PECL Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Installing PEAR Packages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Installing PECL Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Running PHP-GTK Applications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
vii
6137ch00FM.qxd 3/14/06 1:52 PM Page vii
■CHAPTER 3 Understanding PHP-GTK Basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Widgets and Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
The GtkObject Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Parents and Children. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Containers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Top-Level and Parent Widgets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Adding and Removing Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
■CHAPTER 4 Handling Events and Signals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Events and Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Interacting with Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Creating Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Blocking and Destroying Signal Handlers . . . . . . . . . . . . . . . . . . . . . . 49
Listening for New Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Using the GtkEventBox Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Adding Events to a Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
■CHAPTER 5 Getting an Application Up and Running . . . . . . . . . . . . . . . . . . . 65
Windows and Other Top-Level Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Types of Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Window Decorations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Window Positioning and Sizing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Getting and Setting the Window’s Height and Width . . . . . . . . . . . . . 73
Centering a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Maximizing Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Setting the z-Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Modal Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Window Titles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
The GTK Loop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Starting the Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Stopping the Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Stepping Through the Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
■CONTENTSviii
6137ch00FM.qxd 3/14/06 1:52 PM Page viii
■CHAPTER 6 Laying Out Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
The Sample Application Layout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Setting the Label Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Setting the Border Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Creating Vertical and Horizontal Boxes . . . . . . . . . . . . . . . . . . . . . . . . 91
Packing Widgets into a Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Nesting Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Button Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Constructing the Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Attaching Children . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Tables vs. Boxes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Fixed Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Putting Widgets in a Fixed Container . . . . . . . . . . . . . . . . . . . . . . . . . 105
Using Fixed Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Notebooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Defining the Notebook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Adding, Moving, and Removing Notebook Pages. . . . . . . . . . . . . . . 111
Navigating Notebook Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Decorating a Notebook . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
■CHAPTER 7 Displaying and Collecting Simple Data. . . . . . . . . . . . . . . . . . . 119
Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Simple Labels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Complex Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Entry Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Input Box Size and Character Limits. . . . . . . . . . . . . . . . . . . . . . . . . . 137
Automatic Completion. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Combo Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Flat Text Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
GtkComboBox with a Custom Model . . . . . . . . . . . . . . . . . . . . . . . . . 142
Scales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
Scale Adjustment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Scale Precision. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Value Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
■CONTENTS ix
6137ch00FM.qxd 3/14/06 1:52 PM Page ix
Spin Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Standard Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Stock Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
■CHAPTER 8 Using Multiline Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153

The Text-Editing Tool Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Text Marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Referencing Marks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Creating Marks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Moving Marks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Iterators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Creating Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Moving Iterators. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Tags and Tag Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Creating Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Adding Tags to the Tag Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Applying and Removing Tags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Text Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Creating Text Buffers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Adding Text to a Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Removing Text from a Buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Copying and Pasting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Text Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Using Multiple Views with a Single Buffer. . . . . . . . . . . . . . . . . . . . . 169
Scrolling in a View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Setting the Buffer Appearance and Editability . . . . . . . . . . . . . . . . . 171
Putting It All Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
A Multiline Text Display Tool. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
A Text-Editing Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
■CHAPTER 9 Working with Trees and Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Models. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
The GtkListStore Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
The GtkTreeStore Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Model Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191

Model Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
■CONTENTSx
6137ch00FM.qxd 3/14/06 1:52 PM Page x
Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
Cell Renderers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196
View Columns. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Tree Views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Row Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Putting It All Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
The News Article Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
The Product Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
■CHAPTER 10 Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Scrolled Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Setting the Scrollbar Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221
Controlling Child Placement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Setting a Shadow. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
View Ports. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Custom Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Creating the Scrollbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
Creating the Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
■CHAPTER 11 Adding Menus and Toolbars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231
Creating Menu Bars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Adding Menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Creating Menu Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
Creating Tear-Off Menus. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243
Creating Context Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Toolbars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

Creating a Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
Adding Tooltips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Adding Tool Buttons. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
■CHAPTER 12 Adding Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Creating an Image Object. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Scaling Images. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Setting Transparency. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
■CONTENTS xi
6137ch00FM.qxd 3/14/06 1:52 PM Page xi
Animations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Widget Shaping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
■CHAPTER 13 Drag-and-Drop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Drag-and-Drop Destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Setting the Drag Destination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Handling the drag-data-received Signal . . . . . . . . . . . . . . . . . . . . . . 272
Drag-and-Drop Sources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Setting the Drag Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
Handling the drag-data-get Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . 276
Setting Drag Source Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
■CHAPTER 14 Using Selectors & Dialogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Dialogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Displaying a Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Managing the User’s Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Adding Items to the Top of a Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 286
Adding Items to the Bottom of a Dialog . . . . . . . . . . . . . . . . . . . . . . . 287
Selectors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289

Color Selection Dialogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289
Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
Color Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Font Selection Dialogs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Font Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
File Chooser Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
File Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
About Dialogs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
■CHAPTER 15 Doing Background Work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Progress Bars. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
Creating a Progress Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Using set_orientation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
Iterating the Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
■CONTENTSxii
6137ch00FM.qxd 3/14/06 1:52 PM Page xii
Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310
Adding a Timeout. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
Removing a Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Idle Work. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
■CHAPTER 16 Changing the Look and Feel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Resource Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
Creating an RC File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320
Applying the RC File to the Application . . . . . . . . . . . . . . . . . . . . . . . 322
Styles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Modifying a Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Setting a Background Pixmap for a Style . . . . . . . . . . . . . . . . . . . . . 330
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
■CHAPTER 17 Distributing PHP-GTK Applications . . . . . . . . . . . . . . . . . . . . . . . 333

Downloading and Installing an Application . . . . . . . . . . . . . . . . . . . . . . . . . 333
Setting Up the Channel Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334
Creating the Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
Updating an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Checking for Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Obtaining the User’s Permission to Upgrade. . . . . . . . . . . . . . . . . . . 340
Performing the Upgrade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
Uninstalling an Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
Using PHP Compilers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346
■INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
■CONTENTS xiii
6137ch00FM.qxd 3/14/06 1:52 PM Page xiii
6137ch00FM.qxd 3/14/06 1:52 PM Page xiv
About the Author
■SCOTT MATTOCKS is a PHP developer with OnForce.com. Scott has been
working with PHP and PHP-GTK for almost his entire career. Not only has
Scott been working with these tools, but he has also been contributing back
to the community in many ways. Scott spent many hours to help improve
the first set of documentation for PHP-GTK and is listed as one of the authors
for the PHP-GTK 2 documentation. He has also contributed several PHP-GTK
classes to PEAR and added code to more traditional PEAR packages such as
PHPUnit and Console_Getargs. Scott can be contacted at scottmattocks@php.
net. Read more about what he’s up to at .
xv
6137ch00FM.qxd 3/14/06 1:52 PM Page xv
6137ch00FM.qxd 3/14/06 1:52 PM Page xvi
About the Technical Reviewer
■CHRISTIAN WEISKE is student of Information Technologies in Leipzig, Germany. He has been
a member of the PHP-GTK documentation team for several years and is a regular contributor

to the PEAR project.
In his spare time, Christian works on various PHP-GTK 2 tools, translates programs into his
native German language, and writes articles for PHP Magazine. He also works as a freelancer,
creating PHP-GTK applications for those who need them. You can reach him by email at
or at his website, .
xvii
6137ch00FM.qxd 3/14/06 1:52 PM Page xvii
6137ch00FM.qxd 3/14/06 1:52 PM Page xviii
Introduction
The PHP-GTK extension is a powerful solution for creating stand-alone GUI applications. It
takes the benefits of programming with PHP and combines them with the visual capabilities
of GTK (the GIMP Toolkit). The goal of this book is to get you started developing your own
desktop applications with PHP-GTK.
This book isn’t just a rehashing of PHP-GTK’s documentation. There is really no point in
that. The documentation does a perfect job of providing an API reference. If you want to know
the interface for a given method, then the online documentation is the best place for you. If,
however, you want to know which is the best widget for displaying a list of airline reservations
that can be sorted by departure or arrival times, the documentation isn’t going to be much help.
Here, I’ll give you problem-based analysis of PHP-GTK, as opposed to the function-based
analysis you get with the documentation. I may refer you to the documentation from time to
time, because in some situations, it is the best resource around. But in other situations, the
documentation just isn’t designed to allow you to understand the why behind a decision.
I feel the best way to learn is by getting your hands dirty and experiencing things for yourself.
Throughout this book, I’ll ask you to implement the examples that I talk about to see for your-
self exactly what is happening. PHP-GTK is designed to interact with the user. You need to click
certain places in the application and drag things around the screen. Only when you see firsthand
how parts of a program react can you be ready to make an informed decision.
This book is packed full of examples and screenshots, but I beg you to not be satisfied with
just what I have provided. You should always be asking, “Well, what if I changed this part . . . ?”
The more you question what I am trying to explain, the deeper your understanding will be. If

you just read through this book, you will be ready to make some pretty decent applications.
But if you implement the examples and see what happens when you change a few values, there
won’t be anything you can’t accomplish within the limits of PHP-GTK.
Who This Book Is For
This book is intended for PHP developers of all skill levels who want to break free from the
web browser and create desktop applications. You’ll find it easier going if you’re familiar with
PHP 5.1 and are comfortable with the principles of object-oriented programming.
xix
6137ch00FM.qxd 3/14/06 1:52 PM Page xix
What You’ll Find in This Book
Pro PHP-GTK guides you through PHP-GTK’s key capabilities, beginning with an introduction
to fundamental aspects of building desktop applications and a discussion of how PHP-GTK
implements these features. Subsequent chapters explain how to lay out and manage widgets
such as windows, labels, buttons, and text fields; manage events to control the behavior of an
application; and accept and manipulate user input. You will also learn how to customize an
application’s look and feel, implement drag-and-drop capabilities, and package an application
for distribution to users.
Throughout the book, you’ll develop a real-world project to help you learn how to use
PHP-GTK to satisfy critical business needs. The source code for all of the examples is available
from the Source Code section of the Apress website ().
Here’s a quick rundown of the chapter contents:
• Chapter 1 discusses the basics of GUI, PHP, and PHP-GTK. It also introduces the sample
application you will work with throughout the book.
• Chapter 2 covers installing and configuring the software you need to begin developing
applications with PHP-GTK.
• Chapter 3 examines how the pieces of PHP-GTK interoperate to allow you to build
a complete working application.
• Chapter 4 goes over how a PHP-GTK application interacts with the user. These topics
are crucial to making an application react to both user and application requests.
• Chapter 5 talks about setting up the basics of an application. After that chapter, you’ll

have an application that brings up a window, shows some data, and shuts down cleanly.
• Chapter 6 deals with designing the application. It demonstrates how to lay out the
application so you can work on one piece at a time and add features as they are ready.
• Chapter 7 shows you how to display and collect simple data. You’ll start small with single
lines.
• Chapter 8 describes how to work with multiline text and PHP-GTK’s powerful text-editing
capabilities.
• Chapter 9 focuses on displaying large sets of data, like trees and lists, which often overflow
the space they are given.
• Chapter 10 goes over the details of making scrollable spaces on the screen to accommo-
date data that can’t be shown all at once.
• Chapter 11 looks at how to organize user tasks with menus and toolbars.
• Chapter 12 covers creating and displaying images.
• Chapter 13 tackles one of the more advanced features of PHP-GTK: drag-and-drop. It
will show you how to make objects on the screen draggable and allow other elements
on the screen to accept those objects.
■INTRODUCTIONxx
6137ch00FM.qxd 3/14/06 1:52 PM Page xx
• Chapter 14 provides information pertaining to selectors and dialogs. These are windows
that are used for things like selecting files or verifying that a user wants to delete some
data.
• Chapter 15 talks about ways to make applications more efficient by doing work in the
background. This allows the user to keep working while time-consuming processes are
handled by the application.
• Chapter 16 shows you how to change the look and feel of an application, not only to
customize the application, but also to improve its usability.
• Chapter 17 talks about how to get an application into the user’s hands. You’ll learn
about PHP “compilers” and different distribution methods.
■INTRODUCTION xxi
6137ch00FM.qxd 3/14/06 1:52 PM Page xxi

6137ch00FM.qxd 3/14/06 1:52 PM Page xxii
1
CHAPTER 1
■ ■ ■
Introducing PHP-GTK
This book takes a problem-based approach to learning. Each chapter discusses a particular
issue, and then shows which tools can be used to solve that issue. You will also walk through
a real-world project to help you learn how to use PHP-GTK to develop a desktop application to
solve the problem of a fictional company. This first chapter introduces the sample project, and
then discusses the basics of graphical user interface (GUI) applications, PHP, and PHP-GTK.
A Real-World Project
Learning about programming through a book can sometimes be difficult. Oftentimes, a book
will break down the problems into such tiny pieces that it is hard to put them back together to
understand how they are related. You want to learn how to solve problems, not determine what
problems exist to be solved. Keeping that in mind, you are going to work with a real-world proj-
ect to help you learn how to use PHP-GTK to satisfy critical business needs. You are going to go
through the entire process of developing a desktop application for a fictional online retailer,
Crisscott, Inc. We will start out with a brief analysis of the retailer’s problem and move on to
designing a solution, then implementing the solution, and, finally, distributing and maintain-
ing the application.
I am not just going to throw a list of classes and methods at you, and expect you to be able
to put together an enterprise-level application. Instead, I am going to look at the problems and
help you make the right choices for solving them. I am not going to say, “If you find yourself in
situation A, use widget X.” That helps only if you are trying to do exactly what I have done before.
What happens if you find that you need a slightly different solution? By the time you’re finished
with this book, you will be able to recognize which tools are best for your needs, not mine.
You will be able to build a solution designed specifically to solve the problems you are facing.
Together, we will look at all the ways something can be done and discuss the advantages and
disadvantages of each.
In order to help keep us on the right track, this book is going to focus on the development

of a distributed product inventory management system, or PIMS, for Crisscott, Inc. At the
conclusion of the book, you will have an entire application that is ready for use in the real
world.
You will pretend to be a developer hired to help Crisscott, Inc. with product management
issues. You will assume that Crisscott is an online shop that sells goods for PHP-GTK program-
mers. Its products range from books, such as this one, to downloadable applications, such as
integrated development environments (IDEs) or documentation browsers.
6137ch01.qxd 3/14/06 1:58 PM Page 1
CHAPTER 1 ■ INTRODUCING PHP-GTK2
Crisscott is having a problem managing its product information. It sells products from
many different suppliers, all of which currently report their data and inventories in different
ways. Managing this data is a real problem for Crisscott. It has to spend too much time fixing
data problems and trying to track inventory. To solve this, Crisscott is putting the data in the
hands of the people who know it best, the suppliers. It wants to distribute a tool to all of its sup-
pliers that will allow them to quickly and easily make changes, add products, remove products,
and update inventory levels. If the tool isn’t easy to set up and use, the suppliers will never
accept it. Crisscott doesn’t just want to offload its work onto the suppliers; it wants to make life
easier for everyone. Preserving relationships with the suppliers is a high priority of the project.
The PIMS application must provide a user-friendly interface for updating product informa-
tion. It also needs to be compatible with any platform the suppliers are using and cannot be
dependent on the suppliers having any particular third-party software installed. The applica-
tion should allow the suppliers to work online or off. They must be able to edit data, save it,
and upload it later. The application needs to be able to grab data for the supplier from multi-
ple sources. It needs to get the latest information from Crisscott, pull information from a file,
or get data from a database. The application also needs to be easily updated when bug fixes
are found or new features are added. Finally, the application needs to be able to display news
and announcements that Crisscott may wish to pass on to its suppliers.
As you develop this application for Crisscott, Inc., you will learn how to use PHP-GTK to
make a seemingly difficult task relatively easy. You will analyze all the tools PHP-GTK provides
and determine when each tool is most suitable. You will also learn how PHP-GTK easily inter-

acts with “normal” PHP code. You will need to generate XML, get and display RSS news feeds
from a central location, send the product data to a web service using SOAP, connect to a local
database, and do many other tasks. It does not stop there, though. As with any project, develop-
ment is not the end of the line. Finally, we will discuss techniques for distributing and updating
the application once the implementation stage is finished.
GUI Applications
Applications involving a GUI have helped to bring computers to the masses. It is much easier to
click a button than it is to remember which command to type on a command line. GUI appli-
cations also make computers more usable by presenting information in an organized visual
context. Yet many people take for granted the computer applications they use on a daily basis.
All they know is that they type into a little box, hit the Send button, and, magically, Grandma
has an email message waiting for her. Few people ever stop to wonder how that Send button is
able to get that message from the box and send it to Granny, let alone how that button even got
on the screen. This chapter lays the groundwork for this book, helping you understand some
of the fundamental aspects of these GUI-based applications, introducing PHP and PHP-GTK,
and discussing what will be covered in later chapters.
Unlike web applications, which function within the context of a web browser, stand-alone
GUI applications function in their own context, and they are often developed to organize tasks
and data that might be too cumbersome or too confusing to represent through a web browser.
Analyzing and organizing complex data into an understandable format is the goal of most com-
puter applications. If the data were simple, you wouldn’t need a program to help you out. Think
about all the things you use GUI applications for on a daily basis. Web browsers, email clients,
6137ch01.qxd 3/14/06 1:58 PM Page 2