GTK+ 2.0 Tutorial
Tony Gale
Ian Main
& the GTK team
GTK+ 2.0 Tutorial
by Tony Gale, Ian Main, and & the GTK team
This is a tutorial on how to use GTK (the GIMP Toolkit) through its C interface.
Table of Contents
1. Tutorial Availability ..................................................................................................1
2. Introduction ................................................................................................................3
3. Getting Started ...........................................................................................................5
Hello World in GTK ..............................................................................................6
Compiling Hello World........................................................................................8
Theory of Signals and Callbacks.........................................................................8
Events....................................................................................................................10
Stepping Through Hello World.........................................................................11
4. Moving On ................................................................................................................15
Data Types ............................................................................................................15
More on Signal Handlers ...................................................................................15
An Upgraded Hello World ................................................................................15
5. Packing Widgets.......................................................................................................19
Theory of Packing Boxes ....................................................................................19
Details of Boxes....................................................................................................19
Packing Demonstration Program......................................................................20
Packing Using Tables ..........................................................................................25
Table Packing Example.......................................................................................26
6. Widget Overview .....................................................................................................29
Casting ..................................................................................................................29
Widget Hierarchy ................................................................................................29
Widgets Without Windows................................................................................31
7. The Button Widget...................................................................................................33
Normal Buttons ...................................................................................................33
Toggle Buttons .....................................................................................................34
Check Buttons......................................................................................................35
Radio Buttons.......................................................................................................36
8. Adjustments..............................................................................................................39
Creating an Adjustment .....................................................................................39
Using Adjustments the Easy Way.....................................................................39
Adjustment Internals ..........................................................................................40
9. Range Widgets..........................................................................................................43
Scrollbar Widgets ................................................................................................43
Scale Widgets .......................................................................................................43
Creating a Scale Widget ............................................................................43
Functions and Signals (well, functions, at least) ...................................44
Common Range Functions.................................................................................44
Setting the Update Policy .........................................................................44
Getting and Setting Adjustments ............................................................45
Key and Mouse bindings ...................................................................................45
Example ................................................................................................................46
10. Miscellaneous Widgets.........................................................................................51
Labels ....................................................................................................................51
Arrows ..................................................................................................................53
The Tooltips Object..............................................................................................55
Progress Bars........................................................................................................56
Dialogs ..................................................................................................................60
Rulers ....................................................................................................................61
Statusbars .............................................................................................................64
Text Entries...........................................................................................................66
Spin Buttons.........................................................................................................68
Combo Box ...........................................................................................................74
Calendar ...............................................................................................................76
Color Selection.....................................................................................................85
File Selections.......................................................................................................88
iii
11. Container Widgets .................................................................................................91
The EventBox .......................................................................................................91
The Alignment widget........................................................................................92
Fixed Container ...................................................................................................92
Layout Container ................................................................................................94
Frames...................................................................................................................95
Aspect Frames......................................................................................................97
Paned Window Widgets.....................................................................................98
Viewports ...........................................................................................................101
Scrolled Windows..............................................................................................102
Button Boxes ......................................................................................................105
Toolbar ................................................................................................................107
Notebooks ..........................................................................................................112
12. Menu Widget ........................................................................................................119
Manual Menu Creation ....................................................................................119
Manual Menu Example....................................................................................121
Using ItemFactory.............................................................................................123
ItemFactory entries..................................................................................123
Creating an ItemFactory.........................................................................126
Making use of the menu and its menu items ......................................127
Item Factory Example.......................................................................................127
13. Undocumented Widgets .....................................................................................131
Accel Label .........................................................................................................131
Option Menu......................................................................................................131
Menu Items ........................................................................................................131
Check Menu Item ....................................................................................131
Radio Menu Item .....................................................................................131
Separator Menu Item ..............................................................................131
Tearoff Menu Item ...................................................................................131
Curves.................................................................................................................131
Drawing Area ....................................................................................................131
Font Selection Dialog........................................................................................131
Message Dialog..................................................................................................131
Gamma Curve....................................................................................................131
Image...................................................................................................................131
Plugs and Sockets..............................................................................................132
Tree View ............................................................................................................132
Text View ............................................................................................................132
14. Setting Widget Attributes ..................................................................................133
15. Timeouts, IO and Idle Functions ......................................................................135
Timeouts .............................................................................................................135
Monitoring IO ....................................................................................................135
Idle Functions ....................................................................................................135
16. Advanced Event and Signal Handling ............................................................137
Signal Functions ................................................................................................137
Connecting and Disconnecting Signal Handlers ................................137
Blocking and Unblocking Signal Handlers..........................................137
Emitting and Stopping Signals ..............................................................137
Signal Emission and Propagation ...................................................................138
17. Managing Selections ...........................................................................................139
Overview ............................................................................................................139
Retrieving the selection ....................................................................................139
Supplying the selection ....................................................................................141
18. Drag-and-drop (DND) ........................................................................................145
Overview ............................................................................................................145
Properties............................................................................................................145
Functions ............................................................................................................146
Setting up the source widget..................................................................146
Signals on the source widget: ................................................................146
Setting up a destination widget:............................................................147
Signals on the destination widget: ........................................................147
iv
19. GLib........................................................................................................................149
Definitions ..........................................................................................................149
Doubly Linked Lists..........................................................................................150
Singly Linked Lists............................................................................................151
Memory Management ......................................................................................151
Timers..................................................................................................................152
String Handling .................................................................................................152
Utility and Error Functions..............................................................................153
20. GTK’s rc Files........................................................................................................155
Functions For rc Files........................................................................................155
GTK’s rc File Format.........................................................................................155
Example rc file ...................................................................................................156
21. Writing Your Own Widgets................................................................................159
Overview ............................................................................................................159
The Anatomy Of A Widget..............................................................................159
Creating a Composite widget..........................................................................160
Introduction..............................................................................................160
Choosing a parent class ..........................................................................160
The header file..........................................................................................160
The _get_type() function.....................................................................162
The _class_init() function ................................................................162
The _init() function .............................................................................164
And the rest... ...........................................................................................164
Creating a widget from scratch.......................................................................166
Introduction..............................................................................................166
Displaying a widget on the screen ........................................................167
The origins of the Dial Widget...............................................................167
The Basics..................................................................................................168
gtk_dial_realize() .............................................................................171
Size negotiation........................................................................................172
gtk_dial_expose() ...............................................................................173
Event handling.........................................................................................174
Possible Enhancements...........................................................................178
Learning More ...................................................................................................178
22. Scribble, A Simple Example Drawing Program ............................................181
Overview ............................................................................................................181
Event Handling .................................................................................................181
The DrawingArea Widget, And Drawing .....................................................184
Adding XInput support....................................................................................186
Enabling extended device information ................................................187
Using extended device information......................................................188
Finding out more about a device...........................................................189
Further sophistications ...........................................................................190
23. Tips For Writing GTK Applications.................................................................193
24. Contributing .........................................................................................................195
25. Credits....................................................................................................................197
26. Tutorial Copyright and Permissions Notice ...................................................199
A. GTK Signals...........................................................................................................201
GtkObject............................................................................................................201
GtkWidget ..........................................................................................................201
GtkData...............................................................................................................203
GtkContainer .....................................................................................................203
GtkCalendar.......................................................................................................204
GtkEditable ........................................................................................................204
GtkNotebook......................................................................................................205
GtkList.................................................................................................................205
GtkMenuShell ....................................................................................................205
GtkToolbar..........................................................................................................205
GtkButton ...........................................................................................................205
GtkItem ...............................................................................................................206
GtkWindow........................................................................................................206
v
