Gtk Programming In C Incl Toc Syd Logan download

https://ebookbell.com/product/gtk-programming-in-c-incl-toc-syd-
logan-46402782

Explore and download more ebooks at ebookbell.com

Here are some recommended products that we believe you will be
interested in. You can click the link to download.

Foundations Of Gtk Development Bookmarked 1st Ed 2007 Corr 2nd

Printing Andrew Krause

https://ebookbell.com/product/foundations-of-gtk-development-
bookmarked-1st-ed-2007-corr-2nd-printing-andrew-krause-4762496

Pro Php Gtk 1st Edition Scott Mattocks

https://ebookbell.com/product/pro-php-gtk-1st-edition-scott-
mattocks-926588

The Connection Forging Steel Gaston King

https://ebookbell.com/product/the-connection-forging-steel-gaston-
king-57405872
 GTK+
PROGRAMMING
IN (

ISBN 0-13-014264-6
90000

I
Another quality scan by
9 780130 142641
Kremilek and Vochomurka
EditoriallProduction SupervlSlon: Argosy
AcqUlsltJons Editor: Gregory Doench
Editonal Assistant: Brandt Kenna
Marketmg Manager: Debby vanDijk
Cover Design Director: Jerry Votta
Cover Designer: Talar Agasyan-Boorujy
Art Director: Gail Cocker-Bogusz
Project Coordinator: Anne R Garcia
Manufacturing Manager: Alexis Heydt-Long

© 2002 Prentice Hall PTR

Prentice-Hall, Inc,
Upper Saddle River, NJ 07458

All rights reserved. No part of this book may be reproduced, in any fonn or by any means, without pennission in
writing from the author and publisher.

The publisher offers discounts on this book when ordered 10 bulk quantitJes. For more infonnation contact:
Corporate Sales Department, Prentice Hall PTR, One Lake Street, Upper Saddle River, NJ 07458. Phone: 800-382-3419;
FAX: 201-236-7141; E-m?il: [email protected]

Names such as company names, trade names, font names, service names, and product names appearing in this
book may be registered or unregistered trademarks or service marks, whether or not identified as such. All such
names and all registered and unregistered trademarks, service marks, and logos appearing in the book or on its
cover are used for identification purposes only and are the property of their respective owners.

Printed in the United States of America

10 9 8 7 6 5 4 3 2

ISBN 0-13-014264-6

Pearson Education Ltd

Pearson Education Australia PTY, Ltd
Pearson Education Singapore, P te Ltd
Pearson Education North Asia Ltd
Pearson Education Canada, Ltd
Pearson Educaci6n de Mexico, S A de C V
Pearson Education -- Japan
Pearson Education Malaysia, P te Ltd
Pearson Education, Upper Saddle River, New Jersey
 GTK+
PROGRAMMING
IN (

SYD LOGAN

•
Prentice Hall PTR
Upper Saddle River, New Jersey 07458
www.phptr.com
 Library of Congress Cataloging. in· Publication Data

Logan, Syd.
Gtk+ programming in C / by Syd Logan.
p. cm.
ISBN 0·13·014264·6 (pbk.)
1. C (Computer programming language) 2. GTK+. 3. Graphical user interfaces (Computer systems)
1. Title.

QA76.73.C15 L63 2001

005.2' 84··dc21 2001032173
 TABLE OF (ONTENTS

I N T R O D V ( T I O N . . . . . . . . . . . . . . . . . . . . . . . . . . . . .X X I X

( H APTE R 1

G T K+ I N ( O N T E XT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1

The X Window System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Architecture of X ................................................ . . 2
.

The X Protocol ...............................................

. 2
The X Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 3
The Client (Xlib) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Toolkits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Window Managers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 6
Desktop Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

CDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
GNOME . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
KDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

( HAPTE R 2

H E L LO G T K+! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 1

B eginnings ...................................................... 11
.

A Simple Example: Hello Gtk+! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Adding Interactive Features to a
Console Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 3
A Paradigm Shift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 4
Understanding the Gtk+ Hello World Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
B uilding the S ample Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

v
vi Table of Contents

Debugging the S ample Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Application Startup, Termination, and Main Loop Functions . . . . . . . . . . . . . . . . 26
Application Startup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28. . . . . . . . . .

Debug Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Compile Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Runtime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Application Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32. . . . . . . . . .

Gtk+ Main Loop Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33. . . . . . . . . .

Terminating the Main Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Controlling the Main Loop . . . . . . . . . . . . . . . . . . . . . . . 33. . . . . . . . . .

Checking for Pending Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

lnit and Quit Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Destroying Objects When a Main Loop Exits . . . . .
. . . . 36
. . . . . . . . .

Timeouts and Idle Processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Adding a Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37. . . . . . . . . .

Removing a Timeout . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37. . . . . . . . . .

Timeout Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38. . . . . . . . . .

Timeout Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Idle Functions . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 39
Adding an Idle Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Idle Function Priorities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Destroying Idle Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Snooping Key Presses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41. . . . . . . . . .

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

( HAPTE R 3

S I G N AL. S, E V E N T S, O BJ E ( T S, A N D TY P E S . . . . . . . . . . . . 47

Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 7
An Example: GtkButton Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 7
Handling Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Client Callback Data Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 .

Events . . . . . . . . . . . . . . . . . . . . . . . . . . 51
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Event Callback Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
GdkEventExpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
GdkEventNoExpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
GdkEventVisibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
GdkEventMotion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
GdkEventButton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
GdkEventKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
GdkEventCrossing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
GdkEventFocus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
GdkEventConfigure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
GdkEventProperty . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Table of Contents vii

GdkEventSelection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Selection Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
GdkEventClient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
GdkEventAny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Signal and Event APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Signal Lookup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Emitting Signals . . . . . . . . 74 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Emitting S ignals-An Example 75 . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Analysis of the Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Controlling Signals . . . . . . . 78 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Objects . . . . . . . . . . . . . . . . . . . . 82 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Button Widgets a s Obj ects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Object API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 . . . . . . . . . . .

Obj ect Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Getting and Setting Obj ect Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Associating Client Data with a n Obj ect o r Widget . . . . . . . . . . . . . . . . . . . . 97
When to Use Client Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 03

C HAPTE R 4

W I D G E TS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5

Why Widgets? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 05
Simplifying User Interface Development . . . . . . . . . . . .
1 06 . . . . . . . . . . . . . .
API Simplification. . . . . . . . . . . . . . . . . . . . . . . . .
1 06 . . . . . . . . . . . . . .
Abstraction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1 06 . . . . . . . . . . . . . .
Simplification for Users . . . . . . . . . . . . . . . . . . . . . . . . .
1 08 . . . . . . . . . . . . . .
GtkWidget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1 08 . . . . . . . . . . . . . .
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 08
. . . . . . . . . . . . . . .

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 08

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 08
. . . . . . . . . . . . . . .

Miscellaneous Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 09
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 13
Supported Arguments . . ....................................... 118
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 19
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 25
Widget Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 25
Widget Reference Counts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 27
Destroying Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 28
Manipulating Widget Arguments .......................... . 130
Realizing, Mapping, and Drawing Widgets . . . . . . . . . . . . . . . . . . . 131
Showing Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 1 35
Hiding Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 1 36
Accelerators and Mnemonics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 38
Accelerator Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 39
Event-Related Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 42
Activating a Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 44
Vlll Table of Contents

Reparenting a Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . . . . 1 44
Showing a Widget at a Specific Location . . . . . . . . . . . . . . . . . . . .
. 1 45
Computing the Intersection of a Widget and an Area . . . . . . . . . . . . 1 45
Grabbing Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 145
Specifying Widget Sensitivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 46
S etting the Position and Size of a Widget . . . . . . . . . . . . . . . . . . . . . 1 47
Top-Level and Ancestor Widgets , and Transient Windows . . . . . . . 1 47
Querying the Pointer Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Colormap and Visual Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 49
Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Gtk+ Style System Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 54
Stacking Styles, Visuals, and Colormaps . . . . . . . . . . . . . . . . . . . . . 1 59
Style, Colormap, and Visual Defaults . . . . . . . . . . . . . . . . . . . . . . . . 161
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 63

( HAPTE R 5

LA B E L S A N D B VTTO N S . . . . . . . . . . . . . . . . . . . . . . . . 1 65

Controls and Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 65

GtkLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
1 66 . . . .
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
1 66 . . . .
Parent Class Name . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
1 66 . . . .
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
1 66 . . . .
Supported Arguments . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
1 66 . . . .
Application-Level API Synopsis . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
1 67 . . . .
Class Description . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
1 68 . . . .
Creating a Label Widget . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
168 . . . .
Setting and Retrieving Label Text . . . . .
. . . . . . . . . . . . . . . . .
1 68 . . . .

Label Attributes . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . 1 69
. . . .

Placing Underscores in the Label . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 72

B uttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
GtkButton . . . .
. . . . .
. . . .. .. . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 75
Class Name . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . .
. . . . . . . . . .
. . . . . . . . 1 75
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 75
Macros . .. . .. . . . .
. . . . . . . . . . . . . . . .
. . .
. . . . . . .
. . . . . . . . . . . . . . . . . 1 75
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 1 75
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 76
Application-Level API Synopsis . . . . .
. . . . . . . . . . . .
. . . . . .
. . . . . . . . . 1 76
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 77
Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 8
Creating a Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Changing the Label Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 79
Generating Synthetic Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 79
Relief Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 80
GtkToggleButton . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Macros . . . .. . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 181
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 182
Table of Contents IX

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 82
Signals . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 1 84
Creating Toggle Buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
Getting and Setting the State of a Toggle B utton . . . . . . . . . . . . . . . 1 84
Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 86
GtkCheckButton . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 1 87
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 87
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 87
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 87
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 87
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 87
Creating a Check Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
GtkRadioB utton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Class Name . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 88
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 88
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 88
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 89
Application-Level API Synopsis . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . 1 89
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 90
Creating a Radio-B utton Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 90
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . 1 93

C HAPTE R 6

L I STS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 95

GtkList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 96
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 1 96
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 96
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 96
. . . . . . . . . .

Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 97

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 97
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 1 98
Selection Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 99
Creating a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1
Setting the Selection Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1
Adding Items to the List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 1
Displaying Arbitrary Widget Content in a List . . . . . . . . . . . . . . . . . 203
Removing Items from a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Locating an Item in a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Selecting and Unselecting Items in a List . . . . . . . . .
. . . . . . . . . 206 . . .

GtkCList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 208
Class Name . .
. . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
. . . .

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208
. . .

Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 1
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 1
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 218
A S ample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Creating a Clist Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Adding and Removing Content from a Clist . . . . . . . . . . . . . . . . . . . 220
Getting and Setting Row Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 1
Displaying Pixmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
x Table of Contents

GDK Pixmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

GtkCList Pixmap Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 226
S etting the Shadow Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
Selection Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
B utton Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
Making a Clist Reorderable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
Freezing and Thawing a Clist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230
Column API. . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 230
Row and Cell API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Cell Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Associating Client Data with a Row . . . . . . . . . . . . . . . . . . . . 24 1
Selection Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245
Moving and Sorting Rows . . . . . . . . . . . . . . . . . . . . . . . . . . . . 247
S crollbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 260

( H A PT E R 7

W I N D OW S A N D D I A LO G S . . . . . . . . . . . . . . . . . . . . . . 261

GtkWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Supported Signals . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 262
S ignal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Class Description . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 264
Creating a Window Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
Window Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
S etting the Window Title . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
S etting the Window Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
S etting the Class of the Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
S etting Policy Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Making a Window Transient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
S etting Geometry Hints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
S etting the Default Size of a Window . . . . . . . . . . . . . . . . . . . . . . . . 273
Modal Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Window Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
The Focus Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
Default Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
GtkDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 279
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 . . . . . . . . . . . . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
. . . . . . . . . . . . . .

Application-Level API S ynopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Creating a Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 1
Dialog Sizing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Table of Contents xi

GtkFileSelection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Macros . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Class Description . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Creating an Instance of GtkFileSelection . . . . . . . . . . . . . . . . . . . . . 287
Modifying the File-Selection Widget . . . . . . . . . . . . . . . . . . . . . . . . 288
Showing and Hiding the Fileop Buttons . . . . . . . . . . . . . . . . . . . . . . 289
Responding t o OK and Cancel Buttons . . . . . . . . . . . . . . . . . . . . . . . 290
Adding Arbitrary Widget Content to a File-Selection Widget . . . .
. 292
GtkFontSelection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
Macros . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Font-Selection Widget User Interface . . . . . . . . . . . . . . . . . . . . . . . . 295
Creating a Font-Selection Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Modifying the Font-Selection Widget . . . . . . . . . . . . . . . . . . . . . . . . 298
Setting The Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Setting and Retrieving the Preview Text . . . . . . . . . . . . . . . . . 303
Initializing the Font Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 04
Retrieving the Font Selected by the User . . . . . . . . . . . . . . . . 3 04
GtkFontSelectionDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 305
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 306
Creating an Instance of GtkFontSelectionDialog . . . . . . . . . . . . . . . 308
GtkColorSelectionDialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 309
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Macros . . . . . . . .
. . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 09
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 309
Creating a Color-Selection Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 3 10
Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 10
GtkCoiorSe1ection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 313
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 13
Supported Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 3 14
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 314
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 14
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . 315
Creating a Color-Selection Widget . . . . . . . . . . . . . . . . . . . . . . . . . . 3 15
Color-Selection Widget Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . 315
What Is Opacity? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . .. 3 J 6
Setting and Retrieving Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 17
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 17
.
xiI Table of Contents

( HAPTE R 8

S E P A RATO R S, A R ROWS, I M A G E S, P I XM A P S,
A N D E N T RY W I D G E T S . . . . . . . . . . . . . . . . . . . . . . . . . 31 9

Separators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1 9
GtkSeparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 1
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 1
. . . . . . . . . . . . . . . . . . . .

Parent Class Name . . . . . . . . . . . . . . . . .

. . . . .
. . . . . 32 1
. . . . . . . . . . . . . . . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 32 1
. . . . . . . . . . . . . . . . . . .

Application-Level API Synopsis . . . . . . . . . . . . 32 1

. . . . . . . . . . . . . . . . . . . .

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . 32 1
. . . . . . . . . . . . . . . . . . .

GtkHSeparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
. . . . . . . . . . . . . . . . . . . .

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
. . . . . . . . . . . . . . . . . . . .

Application-Level API Synopsis . . . . . . . .

. . . . . . . . 322
. . . . . . . . . . . . . . . .

Class Description . . . . . . . . . . . . . . . . . . . . . . . . 322

. . . . . . . . . . . . . . . . . . . .

GtkVSeparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
. . . . . . . . . . . . . . . . . . . .

Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325

. . . . . . . . . . . . . . . . . . . .

Parent Class Name . . . . . . . . . . . . . .

. . . . . . . . . . . 325
. . . . . . . . . . . . . . . . . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
. . . . . . . . . . . . . . . . . . .

Application-Level API Synopsis . . . . . . . . . . . . . 326

. . . . . . . . . . . . . . . . . . .

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . 326

. . . . . . . . . . . . . . . . . .

GtkArrow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
. . . . . . . . . . . . . . . . . . . .

Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

Parent Class Name . . . . . . . . . . . . . . . . . . .
. . . . . 328
. . . . . . . . . . . . . . . . . . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
Supported Arguments . . . . . . . . . . .
. . . . . . . . . . 328
. . . . . . . . . . . . . . . . . . . .

Application-Level API Synopsis . . . . . . . . . . . . 329

. . . . . . . . . . . . . . . . . . . .

Class Description . . . . . . . . . . . . . . . . . . . . . . . . 329

. . . . . . . . . . . . . . . . . . . .

Arrow and Shadow Types . . . . . . . . . . . . . 329

. . . . . . . . . . . . . . . . . . . .

Creating an Arrow Widget . . . . . . . . . . . . 330

. . . . . . . . . . . . . . . . . . . .

Setting Arrow Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

Images and Pixmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 1
. . . . . . . . . . . . . . . . . . . .

GtkPixmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Creating a Pixmap Widget . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 333
Setting and Getting the Pixmap Data . . . . . . . . . . . . . . . . . . . . . . . . 333
GtkPixmap Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
Insensitive Pixmaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
GtkImage . . . . . .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Class Name . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Imaging i n G D K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
A n Example Us ing l ibtiff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Creating a n Image with G D K . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 1
Table of Contents XIll

Setting the Image Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 1

Reading a Pixel Value from an Image . . . . . . . . . . . . . . . . . . . . . . . 343
Destroying an Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Retrieving Image Data from a Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Creating the GtkImage Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344
Modifying the Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
Retrieving the Image Data and Clip Mask . . . . . . . . . . .
. . . . . . . . . 347
GtkEntry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 348
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 349
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Creating an Entry Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
Setting and Getting the Value of the Text Buffer . . . . . . . . . . . . . . . 350
Changing the Attributes o f a n Entry Widget . . . . . . . .
. . . . . . . . . . . 35 1
Changing the Editable Attribute of an Edit Widget . . . . . . . . . . . . . 352
Setting the Position o f the Caret . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
Simplifying Entry Widget Creation . . . . . . . . . . . . . . . . . . . . . . . . . 353
Selecting Text . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354

CH A PT E R 9

M E N VS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

GtkltemFactory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 357
Class Name . . .. . . . . .
. . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
. . . . . .

Parent Class Name . . . . .

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
. . . . . .

Macros . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
. . . . . .

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357

Class Description . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
. . . . . .

Creating a n Item Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

. . . . . .

Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Check Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
Radio Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364
Separators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 64
Tearoff Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Creating the Application Menu B ar and Menus . . . . . . . . . . . . . . . . 365
Creating the Item Factory . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
Adding Menu Items to the Item Factory . . . . . . . . . . . . . . . . . 366
Retrieving the Item Factory Widget . . . . . . . . . . . . . . . . . . . . 366
Retrieving the Widget Corresponding to an Item in the Menu . . . . . 367
Retrieving an Item Factory and Path from a Widget . . . . . . . . . . . . 3 67
Retrieving Widgets B ased on Action . . . . . . . . . . . . . . . . . . . . . . . . 368
Deleting Items from a n Item Factory . . . . . . . . . . . . . . . . . . ..... . 368
Pop-up Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Pop-up Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 1
Using Pop-up Menu Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372
Option Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
. . . .

Translating Menu Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377

XIV Table of Contents

GtkMenuB ar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
Class Description . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Creating a Menu B ar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Adding Menu Items t o the Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . 379
S etting the Shadow Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
GtkMenuItem . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Class Name . . . . . . .
. . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Parent Class Name . . . . .
. . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Macros . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Supported S ignals . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
S ignal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
Class Description . .
. . . . . .
. . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
Creating a Menu Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Submenus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
Right-Justifying Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
Selecting and Unselecting Menu Items . . . . . . . . . . . . . . . . . . . . . . . 3 84
An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
Creating the Menu B ar and Attaching the Accelerator Group 387
Creating the Menus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Adding Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Associating the Menu with Its Menu Item . . . . . . . . . . . . . . . 3 89
Check Menu Items and Radio Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
GtkCheckMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Supported Signals . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 390
S ignal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 39 1
Creating Check Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
U sing Check Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Setting the State of a Check Menu Item . . . . . . . . . . . . . . . . . . . . . . 393
GtkRadioMenultem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 395
Class Name . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . 395
. . . . . . .

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396

Creating a Radio Menu Item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Retrieving a Radio Button' s Radio Group . . . . . . . . . . . . 396
. . . . . . . .

An Example . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 397
Setting the Radio Group of a Radio Menu Item . . . . . . . . . . . . . . . 398
.

GtkTearoffMenuItem . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . 399
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 399 . . . . . . .

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . 399

. . . . . . . .
Table of Contents xv

Class Description . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 399
U sing a Tearoff Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
Creating a Tearoff Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
GtkMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 401
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 40 I
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 1
Macros . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 1
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 401
Class Description . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 402
Creating a Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Adding Menu Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Popping Up a Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 403
An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Popping Down a Pop-up Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 407
Getting and Setting the Active Menu Item in a Menu . . . . . . . . . . . 407
Accelerator Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 408
GtkOptionMenu . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 409
Class Name . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 409
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 409
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 409
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Class Description . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . 410
Creating an Option Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Setting and Getting the Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Initializing the Option Menu Selection . . . . . . . . . . . . . . . . . . . . . . . 414
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

CH A PT E R 10

CO N TA I N E R A N D B I N C LA S S E S . . . . . . . . . . . . . . . . . . 4 1 7

GtkContainer . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Parent Class Name . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 418
.

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Supported Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420
Class Description . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Setting the B order Widget of a Container . . . . . . . . . . . . . . . . . . . . . 421
Adding and Removing Children . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 1
Iterating a Container' s Children . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Retrieving a List of a Container' s Children . . . . . . . . . . . . . . . . . . . 424
Changing Focus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
GtkFixed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . 425
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 425
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 425
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Class Description . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Creating an Instance of GtkFixed . . . . . . . . . . . . . . . . . . . . . . . . . . . 426
Adding a Child Widget . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . 427
xvi Table of Contents

Moving a Child Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427

An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
GtkB ox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
Parent Class Name . . .. . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Macros . . . . . .. . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Supported Arguments . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 1
Box Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
B ox Placement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Box Nesting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Widget Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Packing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432
Homogeneous, Spacing, Expand, Fill, and Padding Attributes . . . . 438
Homogeneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 439
Spacing . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Expand . .. . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Fill . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439
Padding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 439
Packing Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 439
Making a Box Homogeneous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 1
S etting the Spacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 44 1
Repositioning Children . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 1
S etting and Getting Packing Attributes . . . . . . . . . . . . . . . . . . . . . . . 442
GtkVBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Class Name . . .. .. . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
Clas s Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 444
GtkHB ox. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
GtkButtonB ox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Class Name . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Macros . . . .. . . . . . . . . . . .. . .
. . . . .. .. . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 446
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
Setting and Getting the Layout Style . . . . . . . . . . . . . . . . . . . . . . . . 448
Setting and Getting the Default Child Size . . . . . . . . . . . . . . . . . . . . 450
Getting and Setting the Current Child Size Minimums . . . . . . . . . . 45 1
Setting and Getting the Child Internal Padding Values . . . . . . . . . . 45 1
Setting and Getting the Interchild Spacing . . . . . . . . . . . . . . . . . . . . 452
GtkVButtonB ox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 3
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453
Table of Contents x vii

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 454
Creating a Vertical Button Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454
Getting and Setting the Interchild Spacing . . . . . . . . . . . . . . . . . . . . 454
Setting and Getting the Layout Style . . . . . . . . . . . . . . . . . . . . . . . . 454
GtkHButtonB ox . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 455
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455
Class Description . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Creating a Horizontal B utton Box . . . . . . . . . . . . . . . . . . . . . . . . . . . 456
Getting and Setting Interchild Spacing . . . . . . . . . . . . . . . . . . . . . . . 456
Getting and Setting the Default Layout Style . . . . . . . . . . . . . . . . . . 456
GtkNotebook . . . . . . . . . . . . . .
. . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Class Name . . . . . . . . . . . . . . .
. . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Macros . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Supported S ignals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 457
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 457
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 46 1
Creating an Instance of GtkNotebook . . . . . . . . . . . . . . . . . . . . . . . . 464
Creating and Adding Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
Creating and Adding Pages to a Notebook: An Example . . . . . . . . . 465
Implementing a Pop-up menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
Removing a Page from a Notebook . . . . . . . . . . . . . . . . . . . . . . . . . 47 1
Reordering the Notebook Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 1
Page Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Traversing Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472
Preference Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473
Analysis of Listing 1 0.4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477
Setting the Orientation of the Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Scrollable Tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 479
Miscellaneous Tab Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479
Tab Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 480
Pop-up Menu Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 1
Tab Label Packing Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . 484

CH A PT E R 1 1

M O R E CO N TA I N E R C LA S S E S . . . . . . . . . . . . . . . . . . . . 48 5

GtkPaned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 486
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 487
Creating an Instance of GtkPaned . . . . . . . . . . . . . . . . . . . . . . . . . . . 489
Adding Children with Default Resize and Shrink Attributes . . . . . . 490
Controlling the Resize and Shrink Attributes . . . . . . . . . . . . . . . . . . 490
Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 491
XVlll Table of Contents

GtkVPaned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Class Name . . .
. . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Parent Class Name . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 492
Macros . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493
Class Description . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 493
GtkHPaned . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 494
GtkPacker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Creating a Packer Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Adding Children to a Packer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Nesting Packers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503
Fill X and Fill Y . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505
Expand Option. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
Anchoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 10
B order Width and Padding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 511
Reordering Children . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513
GtkFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Class Name . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 15
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 516
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 516
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 516
Class Description . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . . . 5 17
Creating a Frame Widget . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 517
An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 5 17
Setting the Frame Label . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 519
Setting the Alignment of the Label . . . . . . . . . . . . . .
. . . . . . . . . . . . 5 19
Setting the Shadow Type of the Frame . . . . . . . . . . .
. . . . . . . . . . . . 520
GtkAspectFrame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 520
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 520
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 520
Macros . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . 520
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 1
Creating an Aspect Frame Widget . . . . . . . . . . . .
. . . . . . . . . . . . . . 522
Setting the Aspect Frame Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 522
GtkTable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . 525
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Macros . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 526
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Table of Contents XIX

Cell Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 529
Cell Coordinates and Adding Children . . . . . . . . . . . . . . . . . . . .
. . . 529
Creating a Table Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 53 1
Resizing the Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 53 1
Changing the Homogeneous Setting . . . . . . . . . . . . . . . . . . . . . .
. . . 53 1
Adding Cells to a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 532
Adding a Table Cell with Defaults . . . . . . . . . . . . . . . . . . . . . . .
. . . 532
Setting Row and Column Spacings . . . . . . . . . . . . . . . . . . . . . . .
. . . 533
A n Example : Tic-Tac-Toe Board . . . . . . . . . . . . . . . . . . . . . . . .
. . . 533
GtkToolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 539
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 539
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 539
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 539
Supported Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 539
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 539
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 540
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 542
Creating a Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 543
Adding Toolbar Children . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 543
An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 544
Button Spacings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 547
Adding Children of Arbitrary Type . . . . . . . . . . . . . . . . . . . . . .
. . . 548
Convenience Functions . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . 552
Setting the Toolbar Orientation . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 553
Setting the Toolbar Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 553
Enabling and Disabling Tooltips . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 553
Setting and Getting the Button Relief Attribute . . . . . . . . . . . . .
. . . 554
GtkHandleBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 555
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . .
. . . 555
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 555
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 555
Supported Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 555
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 555
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 556
Creating a Handle-Box Widget . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 557
Setting the Shadow Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 558
Setting the Handle Location . . . . . . . . . . . . . . . . . . . . . . . .
. . . .
. . . 558
Setting the Snap Edge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 558
GtkEventB ox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . 559
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . .
. . . . . . 559
.

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

. . . . . . . 559
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 559
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 60
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Creating an Event B ox Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 64
GtkScrolledWindow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 565
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 566
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
Creating a Scrolled Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 567
Adding a Child to a Scrolled Window . . . . . . . . . . . . . . . . . . . . . . . 568
Setting and Getting the Horizontal and Vertical Adjustment Obj ects 568
Overriding the Default Adjustment Obj ects : An Example . . . . . . . . 568
xx Table of Contents

Setting the Scrolling Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

Controlling Scrollbar Placement . . . . . . . . . . . . . . . . . . . . . 574 . . . . . . .

GtkLayout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 576
Creating a Layout Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Adding a Child Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Repositioning a Child Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Setting the S ize of the Layout Virtual Area . . . . . . . . . . . . . . . . . . . 577
Adjustments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578
Handling Expose Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 579
Setting and Getting the Layout Adjustment Objects . . . . . . . . . . . . . 583
Layout Widgets : A Final Example . . . . . . . . . . . . . . . . . . . 583 . . . . . . .

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 586 . . . . . . .

( HAPTE R 1 2

TR E E S . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 87

Why Use Trees? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 87

Using GtkTree and GtkTreeltem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590
An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591
GtkTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . 599
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Miscellaneous Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
Supported S ignals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599
S ignal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 1
Creating an Instance of GtkTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 1
Adding Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Removing Items from a Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
Removing Items B ased on Position . . . . . . . . . . . . . . . . . . . . . . . . . 605
Selecting Items . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605
View Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608
GtkTreeltem . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Class Name . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Supported Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 609
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 610
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 1
Creating a Tree Item Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 1
Subtrees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Table of Contents xxi

Tree Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 617
Selecting and Deselecting Tree Items . . . . . . . . . . . . . . . . . . . 617
Expanding and Collapsing Tree Items . . . . . . . . . . . . . . . . . . . 618
GtkCTree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 619
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
Macros . . . . . . . . . . . . . . . . .. . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
Supported S ignals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 619
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . . . . 620
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 620
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 1
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 627
A First Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 628
Creating a GtkCTree Instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 1
Inserting Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 632
Analyzing the Sample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
A Second Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635
Displaying the Contents of a Directory . . . . . . . . . . . . . . . . . . . . . . . 637
Removing Nodes from a Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
Setting the Indentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640
Setting the Spacing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 64 1
Setting the Line Style of a CTree . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 1
Setting the Expander Style . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
S orting Functions . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . 643
Recursive Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . 644
Passing Client Data to a Traversal Function . . . . . . . . . . . . . . 645
Querying Tree and Node Attributes . . . . . . . . . . . . . . . . . . . . . . . . . 648
Attaching and Retrieving Client Data . . . . . . . . . . . . . . . . . . . . . . . . 649
Searching for Nodes B ased on Client Data . . . . . . . . . . . . . . . . . . . . 649
Performing Custom Searches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Moving, Expanding, Collapsing, and Selecting Rows . . . . . . . . . . . 652
Moving a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Expanding a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Collapsing a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Retrieving the State of a Node . . . . . . . . . . . . . . . . . . . . . . . . . 654
Recursively Expanding and Collapsing Nodes . . . . . . . . . . . . 654
U sing the Keyboard t o Collapse and Expand a Tree . . . . . . . . 654
Selecting and Unselecting Nodes . . . . . . . . . . . . . . . . . . . . . . . . . . . 655
Miscellaneous Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 656
Checking Whether a Coordinate Is in the Expander B ox . . . . 656
Setting and Getting the Text Displayed in a Column . . . . . . . 656
Setting and Getting Pixmap Data . . . . . . . . . . . . . . . . . . . . . . 657
Retrieving and Modifying Node Attributes . . . . . . . . . . . . . . . 659
Setting a Column Offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660
Getting and Setting the Selectable Attribute of a Node . . . . . . 660
Determining the Type of a Cell . . . . . . . . . . . . . . . . . . . . . . . . 660
Setting and Getting Style Obj ects . . . . . . . . . . . . . . . . . . . . . . 66 1
Setting Foreground and B ackground Colors . . . . . . . . . . . . . . 662
Determining Whether a Node Is Visible . . . . . . . . . . . . . . . . . 663
Scrolling a CTree to Make a Specific Node Visible . . . . . . . . 663
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663
XXll Table of Contents

( HA PTE R 1 3

RA N G E W I D G E TS A N D A DJ V S TM E N T O BJ E ( T S . . . . . 665

Scale Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

GtkHScale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 667
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 667
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 668
GtkVScale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 668
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
GtkScale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 670
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 67 1
Setting the Number of Significant Digits . . . . . . . . . . . . . . . . . . . . . 67 1
Showing and Hiding the Scale Value . . . . . . . . . . . . . . . . . . . . . . . . 67 1
S etting the Value Label Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 1
Miscellaneous Scale Widget Functions . . . . . . . . . . . . . . . . . . . . . . . 672
An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 672
S crollbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675
GtkHS crollbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 676
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
GtkVS crollbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 677
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
GtkScrollbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 678
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 8
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 678
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 679
Adjustment Obj ects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 679
Implementation of Adj ustment Obj ects . . . . . . . . . . . . . . . . . . 680
GtkAdjustment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 682
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
Table of Contents XXlll

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 682
Supported Signals . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 683
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 684
Creating a n Adjustment Obj ect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 684
Changing Adjustment Obj ect Attributes . . . . . . . . . . . . . . . . . . . . . . 684
Working with Adjustment Obj ects . . . . . . . . . . . . . . . . . . . . . . . . . . 685
GtkRange . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 690
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 690
Parent Class Name . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 1
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 1
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 69 1
Setting the Update Policy of a Range Widget . . . . . . . . . . . . . . . . . . 692
Setting the Range Widget Adjustment Obj ect . . . . . . . . . . . . . . . . . 692
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 693

( HAPTE R 1 4

T E XT A N D S P I N B VTTO N W I D G E T S . . . . . . . . . . . . . . 695

GtkText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695
. . . .

Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695

. . .

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 696
. . .

Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 696

Application-Level API Synopsis . . . . . . . . . . . . . . . . .
. . . . . . . . . . . 696
. . . .

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 697
Scrolling Text . . . .
. . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . .
. 698 . . .

Creating a Text Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698

Changing the Adjustment Obj ects . . . . . . . . . . . . . . . . . . . . . . . 699
. . . .

Making a Text Widget Editable or Read-Only . . . . . . . . . . . . . . . . . 699

Word Wrap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699
Text Widget Buffer Manipulation . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
The Insertion Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
Setting and Getting the Insertion Point . . . . . . . . . . . . . . . . 700 . .

Getting the Length of the Text B uffer . . . . . . . . . . . . . . . . . . . 700

Inserting and Deleting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 I
Deleting Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Freezing and Thawing the Text Widget . . . . . . . . . . . . . . . . . 703
Retrieving Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704
GtkSpinB utton . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
. . .

Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . 707
Keyboard and Mouse Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
Creating a Spin B utton Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709
Understanding the Climb Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Configuring the Spin B utton Widget . . . . . . . . . . . . . . . . . . . . . . . . 710
XXIV Table of Contents

Setting and Getting the Adjustment Object. . . . . . . . . . . . . . . . . . . . 710

Setting the Number of Significant Digits
D isplayed by a Spin Button . . . . . . . . . . . . . . . . . . . . . . . 711
. . . .

Setting and Getting the Value of a Spin Button . . . . . . . . . . . . . . . . 711

Changing the Spin Button Update Policy . . . . . . . . . . . . . . . . . 712
. . . .

Using Numeric Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 712

Setting the Value of a Spin Button . . . . . . . . . . . . . . . . . . . . . . 713
. . . .

Controlling the Wrapping of Values . . . . . . . . . . . . . . . . . . . . . 714

. . . .

Setting the Shadow Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 14

The Snap-to-Ticks Attribute . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 714
Causing the Spin Button to Redraw . . . . . . . . . . . . . . . . . . . . . . . . . 715
An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . 719
Handling Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Creating the Spin Button Controls . . . . . . . . . . . . . . . . . . . . . . 720
Implementing the value_changed Signal Function . . . . . 720
. . . .

Implementing the Next and Previous Buttons . . . . . . . . . 72 1

. . . .

Implementing the Slide Show . . . . . . . . . . . . . . . . . . . . . 72 1

. . . .

Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
. . . .

C HAPTE R 1 5

M I S C E L LA N E O V S W I D G E T S . . . . . . . . . . . . . . . . . . . . . 7 2 5

GtkRuler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . 726
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
. . . . . . . . . . .

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726

. . . . . . . . . . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
. . . . . . . . . . .

Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727
. . . . . . . . . . .

Setting the Ruler Metric . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727

Setting the Range of a Ruler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728
Tracking Mouse Movement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730
S ample Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 1
GtkHRuler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
. . . . . . . . . . .

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732

. . . . . . . . . . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732
. . . . . . . . . . .

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . 732

. . . . . . . . . . .

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732

. . . . . . . . . . .

GtkPreview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
Class Name . . . . .. . . .. . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 733
. . . . . . . . . . .

Parent Class Name . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733

. . . . . . . . . . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
. . . . . . . . . . .

Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733

. . . . . . . . . . .

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . 733

. . . . . . . . . . .

Class Description . . . . . . . . . . . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . 734

Creating a Preview Widget . . . . . . . . . . . . . . . . . . . . . 737
. . . . . . . . . . .

Setting the Image Size . . . . . . . . . . . . . . . . . . . . . . . . . 738

. . . . . . . . . . .

Setting the Expand Attribute . . . . . . . . . . . . . . . . . . . . 738

. . . . . . . . . . .

Setting the Image Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 739

Drawing the Image Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740
Miscellaneous GtkPreview Functions . . . . . . . . . . . . . . . . . . . . . . . . 741
Table of Contents xxv

Setting the Dither Preference . . . . . . . . . . . . . . . . . . . . . . . . . 74 1 .

Setting the Gamma . . .. . .742. . . . . . . . . . . . . . . . . . . . . . . . . . .

Retrieving Global Information About Preview Widgets . . . . . 742

GtkProgress . . . . . . . . . . . . . . . . . . . . . . . . .743. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Class Name . . . . . . . . . . . . . . . . . . . . .743. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Parent Class Name . . . . . . . . . .. . . . . .743. . . . . . . . . . . . . . . . . . . . . . . . . . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . .743. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Supported Arguments . . . . . . . . . . . . .743. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Application-Level API Synopsis . . . .744. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Class Description . . . . . . . . . . . . . . . .745. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Initialization . . . . . . . . . . .. . . . .746. . . . . . . . . . . . . . . . . . . . . . . . . . .

Text . . . . . . . . . . . . . . . . . . . .. . .747. . . . . . . . . . . . . . . . . . . . . . . . . . .

Value and Percentage . . . . . .. .. .749. . . . . . . . . . . . . . . . . . . . . . . . . .

Activity Mode . . . . . . . . . . . . . .749. . . . . . . . . . . . . . . . . . . . . . . . . . . .

GtkProgressBar . . . . . . . . . . . . . . . . . . . .. . . .750. . . . . . . . . . . . . . . . . . . . . . . . . . .

Class Name . . . . . . . . . . . . . . . . . .. .. . .750. . . . . . . . . . . . . . . . . . . . . . . . . .

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 750
Supported Arguments . . . . .. . . . . . . . .750. . . . . . . . . . . . . . . . . . . . . . . . . . .

Application-Level API Synopsis . . .. .75 1

. . . . . . . . . . . . . . . . . . . . . . . . . . .

Class Description . . . . . . . . . . . .. . . .
. . .752. . . . . . . . . . . . . . . . . . . . . . . . .

Creating Progress B ar Widgets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 5 3

Setting the Progress B ar Style . .753. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Controlling the Speed o f a n Activity Progress B ar . . . . . . . . . . . . . . 7 5 4

Setting the B ar Size o f a n Activity Progress B ar . 754 . . . . . . . . . . . . . .

Setting the Progress B ar Orientation . . . . . . . . . . . . . . . . . . . . . . . . . 7 5 5

Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 5 5
GtkTooltips . . . . . . . . . . . . . . . . . . . . . . . . . .761. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Class Name . . . . . . . . . . . . . . . . . . . . . 76 1
. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 1

Macros . . . . . . . . . . . . . . . . . .. . . . . . . .762. . . . . . . . . . . . . . . . . . . . . . . . . . .

Application-Level API Synopsis . . . .762. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 762

Using Tooltips . . . . . . . . . . . . . .763. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Displaying Context-Sensitive Help . 763 . . . . . . . . . . . . . . . . . . . .

Display Application Data 7 64

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Tooltips Widgets . . . . . . . . . . . .764. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating a Tooltips Widget . . . . . .7 64

. . . . . . . . . . . . . . . . . . . . . . . . . .

Setting the Widget-to-Tooltip Mapping . 7 64 . . . . . . . . . . . . . . . . . . . . .

Enabling and Disabling Tooltips . 765. . . . . . . . . . . . . . . . . . . . . . . . . . .

Setting the Tooltips Delay . .. . . .765. . . . . . . . . . . . . . . . . . . . . . . . . . .

Changing the Foreground and B ackground Colors . . . . . . . . . . . . . . 766

GtkTipsQuery . . . . . . . . . . . . . . . . . . . . . . .. .766. . . . . . . . . . . . . . . . . . . . . . . . . . .

Class Name . . . . . . . . . . . . . . . . . . . . .766. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Parent Class Name . . . . . . . . . . . . . . .766. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . .766. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Supported Arguments . . . . . . . . . . .. . .766. . . . . . . . . . . . . . . . . . . . . . . . . . .

Application-Level API Synopsis . . . . 767

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Class Description . . . . . . . . . . . . . . . .767. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Creating an Instance of GtkTipsQuery . . . . . . . . . . . . . . . . . . . . . . . 768

The widgecselected Signal . . . .. .768. . . . . . . . . . . . . . . . . . . . . . . . . .

Handling the widgecentered S ignal . 769 . . . . . . . . . . . . . . . . . . . . . . . .

Placing a Widget into Query Mode . 770 . . . . . . . . . . . . . . . . . . . . . . . . .

An Example Using GtkTipsQuery . . . . . . . . . . . . . . . . . . . . . . . . . 770 .

Leaving Query Mode . . . . . . . . 772

. . . . . . . . . . . . . . . . . . . . . . . . . . . .

Setting the Text Displayed by Widgets Without Tooltips 772 . . . . . . . .

XXVI Table of Contents

GtkCombo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 773
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
. . .

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
Creating a Combo Box Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
Setting the Combo Box Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
Enabling and Disabling Use of Arrow Keys . . . . . . . . . . . . . . . . . . . 780
Forcing Users to Match the Pop-up List Contents
During Data Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780
Disabling the Combo Widget Activate Function . . . . . . . . . . . . . . . 78 1
GtkStatusbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 1
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 1
. . .

Parent Class Name . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781

. . .

Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 1
Supported Signals . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. 782
. . .

Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782
. . .

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783

. . .

Creating a Statusbar Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784

Pushing a Status Message onto the Stack . . . . . . . . . . . . . . . . . . 785
. . .

Handl ing the texcpushed Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . 785

Getting a Context ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
Popping an Item from the Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
Substacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786
Handling the texCpopped Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
Removing an Arbitrary Item from the Stack . . . . . . . . . . . . . . . . . . . 787
Final Thoughts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
GtkAccelLabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 787
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
. . .

Macros . . . . . . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788
. . .

Supported Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788

. . .

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 788

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
Creating an Accel Label Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
Retrieving the Width of an Accel Label Widget . . . . . . . . . . . . . . . . 789
Mapping an Accel Label Widget to the Widget It Supports . . . . 789
. . .

GtkDrawingArea . . .. . . . . . . .. . . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790
Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 791
Creating a Drawing Area Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 1
Setting the Drawing Area Widget Size . . . . . . . . . . . . . . . . . . . . . . . 79 1
U sing the Drawing Area Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . 792
Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 797
GtkCalendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 802
Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
Parent Class Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
Macros . . .. . . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
Supported Signals . . .. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 802
Signal Function Prototypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . 802
Table of Contents xxvii

Application-Level API Synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

Class Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804
Creating a Calendar Widget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 805
Setting and Retrieving the Date Displayed by the Calendar . . . . . . . 805
Marking Days . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 806
Setting Display Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807
Freezing and Thawing the Calendar Display . . . . . . . . . . . . . . . . . . 808
Example Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 808
Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 1

AP P E N D IX

G T K+ 1 . 2 W I D G E T H I E RA R ( H Y 81 3

I N D EX . . . . . . . . . . . . . . . . . . . . .817
 I NT RO D V (T I O N

Gtk+ was originally developed by two University of California at Berkeley students,

Spencer Kimball and Peter Mattis. They had developed, as a part of a school project, an
image manipulation called The GNU Image Manipulation Program (The GIMP,
www.gimp. org). Originally it was written in Motif, but due to the (at the time) closed­
source nature of Motif and, as a result, its scarcity on freely available open-source UNIX
platforms, they decided to come up with an open-source toolkit, inspired by Motif, to
which The GIMP could then be ported. The goal was not to develop a general-purpose
toolkit for the X Window System, although that is what Gtk+ has become. Hundreds if
not thousands of programs have been written using Gtk+ to date, ensuring that Gtk+ will
be around for some time to come. More information on the history of Gtk+ (and The
GIMP) can be found at www. gimp. orgl-sjburgeslgimp-history.html.

About Th i s Book

This book covers the 1 . 2 version o f the GIMP Toolkit (Gtk+) and was written with
the following goals in mind:

• To provide a general introduction to programming applications with Gtk+ 1 . 2

• To provide a detailed description of the Gtk+ 1 . 2 widget set
• To provide a quick reference to the Gtk+ 1 .2 widget set for those programmers
already familiar with Gtk+

For those of you looking for an introduction to Gtk+ programming, I suggest

reading Chapters 1 through 4 first, followed by Chapter 1 0, "Container and B in
Classes." The first few chapters (Chapters 1 , 2, and 3) describe the architecture of
Gtk+ and provide information needed to program and build a simple Gtk+ appli­
cation. Most readers will want to skim through Chapter 4, "Widgets ," which
describes GtkWidget. GtkWidget is the parent class from which the remaining
widgets in the Gtk+ class hierarchy inherit much of their functionality. Container
widgets are used to organize the layout of other widgets in a window (or within
other containers) . The concept of container widgets is described in the first few
sections of Chapter 1 0 . The GtkBox widgets are by far the most versatile of the
container widgets implemented by Gtk+ 1 . 2 and, as a result, are the most com-

xxix
xxx Introduction

monly used. GtkB ox, GtkHB ox, and GtkVBox are all described in Chapter 1 0 of
this book.
The remaining chapters provide detailed descriptions of the bulk of the widget
classes implemented in Gtk+ 1 .2. I have made every effort to describe in detail the
application-level programming interfaces exposed by the Gtk+ widget sets covered in
this book. I have included most of the code I wrote while investigating the Gtk+ widget
set. In some cases, the source code consists of a full-size (although functionally lim­
ited) application. In all other cases, I simply present short code snippets that help to
illustrate points made in the surrounding text. Complete source-code examples for the
book can be found on my Web site at www.cts.comlcrashlslsloganlgtkbook.html.
I have placed Gtk+ widget reference material directly in the main body of the text
(as opposed to placing it at the end of the book in an appendix). The reference material
provides function prototypes for each of the application-level functions that have been
exposed by the widgets described in the book and a one-line sentence describing the
purpose of each of these functions. In the reference section, I also enumerate all of the
object attributes that can be set and/or retrieved on the widget (see the "Object
Attributes" section in Chapter 3, "Signals, Events, Objects, and Types") . I also list the
signals that can be generated by the widget, if any. For each signal, I supply the func­
tion prototype of the application-level signal handler invoked when the signal fires (see
the "Signals" section in Chapter 3). The reference material provides an introduction to
the widget for first-time programmers and can serve as a quick reference for program­
mers who are already familiar with widgets. More information about the structure of
the reference section is spelled out in Chapter 4 (see the reference section for the Gtk­
Widget widget) .
This book focuses on describing the Gtk+ widget set. This book does not cover
the Gtk+ Drawing Kit (GDK) , or the G Library (Glib), or widget writing in any
detail (except where unavoidable). For GDK and GLib, I refer you to one or both
of the following books : Developing Linux Applications with GTK+ and GDK by
Eric Harlow and GTK+IGnome Application Development by Havoc Pennington.
You can also find reference material on these topics at www. gtk. org. I do plan to
provide an additional chapter on Gtk+ widget development on my Web site ; it
should be available shortly after this book goes to press. Hopefully, this material
will be included in a subsequent edition of this book.

Sou rce Code

I have placed source code throughout the book to provide illustrative examples of
the concepts discussed. In some cases, line numbers are prefixed to each line of
source code, like thi s :

014 static void

015 C l i c ke dC a l l b ac k ( GtkWi dget *widg e t , GtkWidget * d i a l o g_w i ndow )
016 {
017 GtkWidget *wi ndow , * l ab e l F r ame , * l ab e 1 Te s t , * vbox ;
018
019 wi ndow = gtk_window_new ( GTK_W I N DOW_TOPLEVEL ) ;
020 g t k_wi ndow-po s i t i o n ( GTK_WI NDOW ( window ) , GTK_W I N_P O S_MOU S E ) ;
021 g t k_w i d get_s e t_ll s i z e ( window , 320 , -1 ) ;
Introduction XXXI

022 vbox = gtk_vbox_new ( FAL S E , 0);

023 gtk_c o n t a i n e r_add ( GTK_CONTA I N E R ( window ) , vbox ) ;

For code that is simple to read or relatively short (a few lines or so in length), I
will often omit the line numbers. Full (and, in some cases, incomplete but long)
listings of example code are prefixed with a listing number and title as follows :

Listing 1 . 1 GtkLabel Attribute S ample Code

001 #inc l ude < g t k / gtk . h

002 #inc l ude < s td i o . h>
003
004 s t a t i c G t kW idget * l e ftButton , * r i gh t B u t t o n , * c e nterButton ;
005 s t a t i c G t kW idget * t rueButton , * f a l s eButton ;
006
007 static void
008 Q u i tC a l l b ac k ( GtkWidget *widget , G t kW i d g e t * d i a l o g_window )
009 {
010 gt k_ma i n_qu i t ( ) ;
011 exit ( 0 ) ;

I plan to make the source code for this book available online. Please go to
www. users. cts. comlcrashlslsloganlgtkbook. html for further details .

O n wa rd . . .

By purchasing this book, you have decided to develop an application for Linuxl
UNIX, and you have also decided to develop this application using Gtk+. In addition
to learning about Gtk+, you should take some time to learn more about the desktop
environment(s) within which users will be executing your application. If you are tar­
geting GNOME-and some of you are-you should learn about developing for the
GNOME environment using the books and Internet resources available. This book
covers the Gtk+ toolkit, upon which all GNOME applications are based, but I do not
cover GNOME application development specifically within these covers.

Ackn owle d g m e nts

I'd like to thank several people for their help in the development of this book. First
of all, I'd like to thank Greg Doench at Prentice Hall for taking the time to discuss
this project with me when it was just an idea, for consenting to read my proposal,
and for making this project possible. I'd also like to thank Jim Markham, also at
Prentice Hall, for guiding me through the bulk of the editorial work. Amy Lepore
applied her substantial copy editing skills to the manuscript, and somehow turned
my gibberish into something that hopefully appeals to software developers and
English teachers alike. Caroline Roop coordinated the copy edit process and helped
to shape the format of the book which you now hold in your hands. To my reviewers ,
Ariel Rios (GNOME project) and Rob Flynn (maintainer of GAIM), I extend my
thanks for a j ob well done. Any errors that may remain in the text are, of course, my
xxxii Introduction

responsibility alone. Joe Hewitt produced the nonscreenshot figures for this book,
and for this I am most thankful . I would like to thank the people who contributed
ideas and suggestions for the book, including Ramiro Estrugo (formerly of Eazel),
who pointed out the possibility of including reference material within the main body
of the text. Finally, I'd like to thank the vast number of people who made Gtk+ and
GNOME possible. It is through efforts like theirs that desktop Linux is becoming a
reality for more and more users.
Each and every line of the original manuscript was written on a GNUlLinux system
using the VIM editor (an open-source vi clone that is available, usually by default, on
GNUlLinux systems and by download for Win32, Mac, and other platforms; see
www. vim. org). Screen shots were grabbed using The GIMP (www. gimp.org), a freely
available image-editing program that was, in fact, the first Gtk+ application ever writ­
ten. Sample programs were also created in VIM, compiled using gee, and in some
cases, debugged with gdb. The gdb debugger was also used to inspect Gtk+ internals
during its execution in order to leam more about the operation of certain widgets.
During the review process, a Hypertext Markup Language (HTML) version of the
book was developed using the Gtk+-based B luefish editor (http://bluefish.openof­
fice. nll). The output from B luefish, prior to being uploaded to reviewers, was proofed
using a development version of Netscape 6 (www. netscape. com). which in tum was
derived from the open-source browser Mozilla (www. mozilla.org). All of this work
was done, of course, on a GNUlLinux system.
 (HAPTER

CTK+ IN (ONTEXT

Gtk+ is a toolkit designed for use in the development of applications for the X Window System.
It is just a part of the overall picture, however. To fully appreciate Gtk+, you need to have a
basic understanding of the X Wmdow System. For those of you already familiar with the X
Window System and its components, feel free to skip to Chapter 2, "Hello Gtk+!, where I pro­
"

vide an overview of Gtk+.

The X Window System

The X Window System (called X, X I I , or sometimes X Windows) is a network-based, client­
server user interface technology developed by the MIT X Consortium in the mid 1 980s. The
architect of the X I I system was Robert Schiefler. He, along with a small team of developers
at MIT, formed the nucleus of what was known as the MIT X Consortium. Their job was to
oversee and guide the development of the X Window System and to develop and release a
sample implementation of the X server and the core client libraries (Xlib, Xt, and so forth) to
member companies of the consortium.
The member companies of the X Consortium each had a business interest in ensuring
that a vendor-neutral, interoperable user interface for the UNIX operating system flour­
ished. These companies contributed source code to the sample implementation, created
products that were based on it, or did a little of both. I was very fortunate to work for one
of these member companies during this time. AGE Logic, founded in the late 1 980s, ini­
tially focused on taking the MIT sample implementation and using it to develop the soft­
ware portion of several X terminals developed during this period of time. In the early 1 990s,
an X terminal was the least expensive way to run X-based applications on a desktop. The
alternative was to dedicate a workstation (e.g., a Sun, HP, or RS/6000) to each user; such a
solution could easily decrease the bank account of a company given the cost of workstations
(tens of thousands of dollars) as well as increase the workload of system administrators.
The alternative, X terminals, cost one or two thousand dollars, were easier to maintain,
were much less expensive to own, and since X terminals could be optimized for running an
X server, often improved the overall performance of X-based applications because they
were able to execute X faster.
Once Microsoft Windows 3.0 became available, the industry focus shifted away from X
terminals toward PC-based X server software. This software allowed users to access X client
applications executing on workstations from their personal computer desktops and further
reduced the cost of accessing X-based applications.

1
2 Chapter 1 • Gtk+ in Context

All along, the major workstation vendors pumped large amounts of money and resources
into XII on both sides of the X Protocol pipe (client and server). When MS Windows 3.0
arrived, it was clearly seen as a threat to their market share. MS Windows was maturing,
PC-based systems were becoming more capable in terms of their performance, and graph­
ical user interfaces (as opposed to command-line interfaces) were being demanded by more
and more end users, thus making UNIX a less attractive alternative. Efforts were made to
develop desktop environments such as CDE (discussed later in this chapter) in an attempt
to answer the threat. These efforts came up short, and as a result of this and other (perhaps
more influential) factors, MS Windows and MacOS dominated desktops during the 1 990s,
and they continue to do so today.
To those involved, the early to mid 1 990s were fertile times for the X Window System and
the industry it supported. Numerous products were on the market, there were magazines ded­
icated specifically to X l 1 -based software development, and there were even yearly major
industry trade shows and developer conferences, such as Xhibition and X World, that attracted
dozens of vendors and hundred of attendees.
The X Consortium made its last major release, X 1 1 R6, in 1 994 and disbanded shortly
thereafter. Since then, energy has shifted from the X Consortium to a collaborative effort of
X.org (www.x.org), an organization of the Open Group, and XFree86 (www..ifree86.org). This
shift has neatly coincided with an explosion in the availability of free UNIX-like operating
systems such as GNUlLinux, FreeBSD, and NetBSD, each of which is capable of executing
on consumer-level PC hardware. The X servers available today continue to expand on the
X 1 1 R6 sample implementation, perhaps most notably by providing extensive support for PC­
based video drivers. The combination of freely available PC-based UNIX and X software has,
for the most part, made X terminals and PC-based X server software things of the past, and
desktop X is a reality for everyone who desires it, including home users. But the promise of
a Linux-based desktop has yet to be fully realized. Microsoft still dominates the end-user mar­
ketplace, although a few open-source efforts show promise in advancing Linux on the desk­
top. One of them, GNOME, has its roots in Gtk+, the topic of this book. I will have more to
say on this issue later in this chapter.

Architecture of X

Now that we know something about the history of the X Window System, let's take a look at
its architecture. X consists of three components: a client, a server, and the protocol that exists
between them. The following sections describe each in detail, starting with a look at the X
Protoco1.

The X Protocol
The X Protocol forms the basis of any X-based software system. It is an application-level pro­
tocol that exists between the X server and X client applications, both of which are described
in the following sections. The protocol consists of requests, which are sent by the client to the
server, as well as events and errors, which are sent by the server to a client. A request initiates
an action to be performed by the X server. Examples include the creation of a window (Cre-
Architecture of X 3

ateWindow) and the drawing of a line (DrawLine). Events, sent by the server, tell the client
about state changes within the server, such as the pressing of a key or mouse button by the
user or the resizing of a window. Errors are sent by the server in response to invalid or unex­
ecutable protocol requests sent by the client. For example, a BadDrawable error is sent by the
X server to the client if the client specifies an invalid window as part of a DrawLine protocol
request.
Two attributes of the X Protocol are worth mentioning. The first is that the protocol was
designed in such a way that the client and server can execute either on the same host or on
separate hosts connected by a network (usually communicating over the Transmission Con­
trol Protocol/Intemet Protocol [TCPIIP]) . For PC UNIX users, most of the time, the client
and server are executing on the same machine. Certainly, the X server is always executing
on the desktop machine, be it PC UNIX or an X terminal. In some installations, a user may
need to telnet into a host on a remote system to execute a specific client; this might be the
case for commercial or custom software running on a proprietary UNIX system for which
the user has obtained a license to execute. To tell the client which X server to connect to,
the user specifies the IP address of the server on his desktop by setting his or her DISPLAY
variable, as in the following:
$ typeset -x D I S PLAY= 1 5 6 . 2 7 . 6 0 . 4 : 0
This will cause the client running on the remote system to display its windows and to
draw its graphics on the X server running on the desktop machine with the IP address of
1 56.27.60.4. Mouse and keyboard events that occur on the machine running the X server
will be sent to the machine on which the client is executing.
The second attribute of fundamental interest is the lack of policy imposed by the X Pro­
tocol on user interface look and feel. The X protocol was designed to support only the most
fundamental tasks required of a Graphical User Interface (GUI), such as the capability to
create a window, draw a line, and report keyboard presses and mouse button presses and
movement. How the user interface looks is outside the scope of the X Protocol. There is no
such thing as a menu, a list box, or a push button in X. All of these things are abstractions
provided by toolkits, and they are implemented by combining X Protocol requests in a way
that achieves the abstraction desired, as I will discuss later in this chapter. The end result is
rather remarkable. Because the protocol does not enforce a policy, X supports any policy
that a toolkit designer can dream up, provided it is consistent with the core architecture of
x. Hence, we see the prolific number of toolkits in existence today: Gtk+, XtlMotif,
XtlXaw, Qt, XView, and so on.

The X Server
An X server is the program that manages the screen and its input devices (usually a mouse
and keyboard). The X server always runs on the machine in front of which the user inter­
acting with the application (or client) sits. Using TCPIIP, the client software connects to the
server and sends requests to it using the X Protocol. The X server, once it has been started,
listens for incoming TCPIIP client connections on a well-known port. Assume that a client
has connected to the server and that the client wants to create a window and draw a line
inside of it. To do so, the client sends a CreateWindow request to the server to create the
4 Chapter 1 • Gtk+ in Context

window. To draw a line in the window, the client then sends a DrawLine request to the X
server. More protocol requests than these are actually required for a real client to operate,
but hopefully you get the idea. Upon receiving a DrawLine request, the X server validates
the request, making sure that the window to which the line is to be drawn actually exists.
Then it either performs the request if valid or, if there was an error of some kind, sends an
error message back to the client. As another example, if the user moves the mouse, the X
server will respond by sending a MotionNotify event (if it was solicited) to the client to tell
it about the change made to the position of the mouse.

The Client (Xlib)

By now, I think I have adequately defined the role of the client in the X Window System.
To summarize, it connects to a server and then sends requests to the server to create win­
dows, draw graphics, and perform other operations involving the user interface of a client.
The client also receives and responds to events sent from the X server to report any state
changes made by the user to the mouse, the keyboard, or other input devices supported by
the server and of interest to the client application.
One aspect of the client I have not mentioned is the interface library used by client devel­
opers. With few exceptions, all client applications ultimately make calls to a library of func­
tions known as Xlib. Xlib was developed by the X Consortium, dating back to the early
years of X. Xlib is a fairly simple Application Programming Interface (API), providing little
more than a layer above the X Protocol. To draw a line in a window, for example, you issue
a call to XDrawLineO. Arguments to XDrawLineO identify the server to which the request
should be sent, the window within which the line is to be drawn, and the endpoints of line.
Xlib applications are typically difficult to program because the level of abstraction is too
low; Xlib, as I described, does not provide controls like menus, buttons, or dialogs, which
are essential to modem GUI applications. Applications that need such features must either
program them themselves or use a toolkit. Programming these abstractions is not an option
because it is difficult, error prone, and inefficient. X applications, therefore, are for the most
part written using a toolkit.

Toolkits
A toolkit is code that forms an abstraction layer directly above Xlib. The toolkit we are
studying in this book is Gtk+. Toolkits provide two major benefits to application develop­
ers. First, they abstract the X Protocol, providing meaningful objects with which applica­
tions can be more easily developed. Implementing menus in Xlib is difficult because Xlib
does not support the notion of a menu. To implement a menu in Xlib, you would have to
write code that draws the menu as a series of windows containing text, appropriately posi­
tioned on the user's desktop. Drawing the window is perhaps the easy part; responding to
mouse movement as it occurs over the menu items, popping up and down the menu, sup­
porting accelerators, and so forth, could easily make the task more difficult than writing the
rest of the application. Similar arguments can be made for other user interface abstractions
Toolkits 5

such as buttons, scrollbars, lists, toolbars, and so forth. Instead of writing all this code your­
self, you link: to a toolkit library and use the API it provides instead of Xlib.
The second benefit provided by the use of a toolkit is user interface consistency. Simply
put, if each and every application on a system were written using a single toolkit, the user,
in theory, could learn one application and then be instantly comfortable using other appli­
cations. This is because the abstractions he or she encountered in the first application (but­
tons, menus, scrollbars) would be the same in all other applications, making the second and
subsequent applications easier to learn and use. In practice, this is not always true. A toolkit
almost never enforces the labels used on dialog buttons; one application might label buttons
in a dialog "OK" and "Cancel" while another uses "Yes" and "No" or changes the order of
button placement. A "style guide" is one strategy that helps toolkit applications be more
consistent. Style guides define rules or suggestions for the design of menus, the placement
of buttons, and the behavior of dialogs, among other things. In practice, not all toolkits
define style guides, and when they are defined, not all programmers follow them. The other
strategy a toolkit can use to promote GUI consistency is to provide higher abstractions that
remove the ability of programmers to make choices. For example, to display a message to
a user, the toolkit might require an application to use a "message" widget. The "message"
widget would create the "OK" button that the user presses to dismiss the dialog, removing
from the programmer the choice of what label is displayed by that button. For the most part,
toolkits that have been developed for use in X-based clients do not specify style guidelines
and tend to not provide abstractions such as the "message" widget I just described. Motif
is one toolkit that has taken a multifaceted approach to the problem. The core set of widgets
provided in Motif gives the programmer the flexibility he or she may need as well as
abstractions that promote consistency among Motif applications, if used. Motif also has a
published style guide for use by application developers.
I've used the word "widget" often thus far, so perhaps it is time I defined it. Simply put,
a widget is the source code that implements a user interface abstraction. In Gtk+, the widget
that implements a push button is known as GtkButton. The term "widget" will be used time
and again in this book, and you will no doubt become accustomed to its use as you read the
chapters that follow.
Historically, toolkit programming in X has, for the most part, been achieved via Xt
Intrinsics (referred to as Xt from this point on). Xt is another technology developed by the
X Consortium. Xt is a set of functions and a widget hierarchy. The widget hierarchy is min­
imal, and only the highest level widget classes are provided. A widget set such as the Athena
Widget Set (Xaw) or Motif provides the remaining levels of the widget class hierarchy, and
it is from these widgets that an application can construct a user interface.
There are many books on Xt and Motif, so I will not go into any significant details here.
There are some points, however, that I would like to make about Xt. First of all, Xt, in a way
similar to the X Protocol, is independent of any user interface look-and-feel policy. Xt only
provides a core set of tbree widget classes; the widget set (e.g., Motif) that you link to pro­
vides all of the look-and-feel policy. The open-source community can and has developed
open-source widget sets for use with Xt. One such widget set, LessTif (www.Lesstif.org),
was designed as a freely available, open-source version of OSF Motif. In theory, someone
could even write an Xt-based version of Gtk+ or Qt or design a completely new widget set
that has its own look and feel. Second, programmers that learn how to develop to the Xt
6 Chapter 1 • Gtk+ in Context

Intrinsics can transfer their knowledge from one widget set to another. Most of the calls in
an Xt-based application are made to functions in the Xt API; the arguments passed to these
functions define the widget set used. To create a button widget in Motif, for example, one
can call XtVaCreateManagedWidgetO, as follows:

Widget but t on ;

but t on = XtVaCreat eManagedWidget ( " button " , xmPushButtonWi dge t C l as s ,

parent , NULL ) ;

The argument xmPushButtonWidgetClass tells Xt to create an instance of the XmPush­

ButtonWidget class. Assume that a Gtk+ widget set for Xt was implemented and that the
widget class for push buttons was called GtkButtonWidgetClass. Then we might see the
following code in a port of the application from Xt/Motif to Xt/Gtk+:

Widget but t on ;

but ton = XtVaCreat eManagedWidget ( " button " , gtkButtonWidget C l as s ,

parent , NULL ) ;

As you can see, the changes necessary (on this line) to perform a port from Motif to the
Gtk-like widget set were minimal. It is really never quite this easy; the application developer
has responsibilities that can drastically affect widget set portability. However, like no other
toolkit I know of, Xt was designed with the portability of an application from one widget set
to another in mind. The decisions made by the designers of Xt to ensure the portability of wid­
get sets also resulted in a dramatically reduced API size as well. Thus, only a small set of func­
tions must be leamed by application developers to create, configure, and destroy widgets; this
knowledge is completely reusable as the developer switches from one widget set to another.

Window Managers
A window manager is a specialized client that is responsible for bringing order to the user's
desktop. Window managers control the initial placement of windows on the desktop; without
a window manager, windows likely would all be placed on top of each other at location 0, 0
(unless otherwise specified by the client application, which is not commonly done). The title
bar of a window is actually created by the window manager, not by the client application. To
set the title of a window, the application sends a hint in the form of a property on the X server
for the window; this hint is read by the window manager application, which uses it to draw
the title text in the title bar window that it manages.
The window manager is also responsible for providing controls that enable the user to
move, resize, minimize, and iconify windows on the desktop. Without these controls, each
application would need to provide some mechanism for its users, which is highly impractical.
Many window managers, especially the more recently developed ones, add features such
as virtual desktops, taskbars, and command menus. Since a window manager is an applica­
tion, it is relatively easy to add such features.
 Desktop Environments 7

There are numerous window managers in existence. Some are older and date back to the
early days of X. Many are newer and are open-ourced. Although in some cases there may
be some indirect benefit for users to run a window manager that has been designed with a
specific toolkit in mind (Motif applications and the mwm window manager come to mind),
it is impossible to predict what window manager the user will be running. For that reason,
it is not practical to write an application that assumes a given window manager will be
present.
Generally, Gtk+ will handle any interaction your application must have with the window
manager. An example is setting the text of the window title bar label. As previously men­
tioned, the title bar is a window created by the window manager, not your application. There­
fore, your application cannot (easily) draw text in this window. Instead, your application must
set a property on the X window that specifies the window title. The window manager will be
notified when this property changes, will retrieve the text it contains, and then will draw the
text specified by the client in the title bar of the window. All that your application needs to do
is call the Gtk+ function gtk_window_sectitleO (see Chapter 7, "Windows and Dialogs"),
passing it a reference to the window and a string that specifies the desired window title.

Desktop Environments
A desktop environment is one step beyond the window manager. To understand why a desk­
top environment is important, let's take a look at mainstream desktop environments like MS
Windows and MacOS . Both of these environments have more control over the look and feel
of applications, the desktop, and the set of applications that comes with default installations
than does X l I, which is, in contrast, indifferent to these issues by definition. While this
indifference certainly makes X flexible and resilient to constantly changing requirements,
it does have the undesirable side effect of promoting inconsistency for the end user.
Without control over the environment, a user is faced with running applications developed
with different toolkits, minimizing the advantage of past experience with a given application.
While the claim that a MacOS user only has to learn one application and then instantly knows
the rest is taking things a bit far, there is some truth to the claim. Anyone who has used Motif
scrollbars in one application and Xaw scrollbars in another certainly can attest to the vast dif­
ferences that can exist among X-based toolkits. Lists in Motif work very differently than those
in Gtk+. Gtk+ supports tree widgets, while tree widgets are not a part of the core Motif widget
set. The examples are numerous.
Users may find themselves running one window manager at work and another window
manager at home. Contrast this to MS Windows users; regardless of where they may be,
Windows 98 behaves more or less the same.
Any given X installation may have applications that are not present in another. The early
X distributions provided sample applications like xcalc and xclock, and generally speaking,
you can expect these applications to be present. Historically, however, X has not provided
consistent access to default applications (or accessories, as they are sometimes called).
A desktop environment attempts to correct these inconsistencies. A desktop environ­
ment is all of the following:
8 Chapter 1 • Gtk+ in Context

• A toolkit that promotes a consistent look and feel among applications that execute
within the environment.
• A set of applications, written using the preceding toolkit, preferably written to some
set of standards enforced by the toolkit or described by a published style guide. These
applications must give the user the capability to control and configure the environ­
ment and perform any basic tasks that may be needed. Clocks, calculators, text edi­
tors, games, and other "accessory" applications fall into this category. The style guide
(or toolkit) ensures that applications have consistently named menus, consistently
placed and labeled buttons in pop-up dialogs, and so forth.
• A window manager that gives the desktop a consistent look and feel from one system
to another. In the best of worlds, the window manager is written using the same tool­
kit used to write the applications provided by the environment and adheres to the
same user interface guidelines established for applications.

The following sections describe a few of the major desktop environments.

CDE
The first major desktop environment for X was the Common Desktop Environment
(CDE), developed as part of the Common Open Software Environment (COSE) initiative
back in the 1 990s. CDE uses Motif as its toolkit, expands the widget set with some CDE­
specific widgets, and provides a number of accessory applications, a file manager, and a
window manager (dtwm). CDE has been the desktop for major workstation vendors such
as IBM (AIX) and HP (HPIUX) for some time now and has enjoyed relative success. It
is available for GNU-based systems as well. Although it has done well in the workstation
marketplace, it suffers in open-source environments such as Linux due to its closed
source. (Motif has since gone "open source" but perhaps too late for the trend toward
other toolkits and desktop environments to be reversed.) You can find out more about
CDE at www.opennc.orgltechldesktoplcdelcde.data.sheet.htm .

GNOME
GNOME (www.gnome.org) is one of the two desktop environments currently gaining wide­
spread adoption in the open-source community (the other is KDE). It is the standard desktop
environment of the GNU project. The toolkit for GNOME is Gtk+ 1 .2, which is described in
this book. GNOME also expands the Gtk+ widget set with a set of GNOME-specific widgets
that attempt to strengthen the consistency of applications that execute within the environment.
At this point in time, there is no published set of user interface style guidelines, though my
expectation is that one will evolve over time. A rich set of applications exists, but it is not clear
to me that consistency has been fully achieved in the presentation of these applications. Con­
sider, for example, Red Hat 6.2 configured to use the GNOME desktop. 'TWo calculator pro­
grams can be launched from the GNOME system menu; one brings up a Gtk+-based
calculator, while the other brings up xcalc, which was written with the Athena widgets. The
 Summary 9

File menu in the GNOME calculator has an Exit menu item, while the File menu in Midnight
Commander, which is a file system browser, does not have an Exit menu item. It is this kind
of inconsistency that needs to be overcome for mainstream users to fully adopt an environ­
ment like GNOME as their desktop of choice.
In contrast to CDE, GNOME does not provide or standardize on a window manager. The
major strengths of GNOME are its adoption by the open-source community, an extremely
aggressive amount of application development (again, based on Gtk:+), and its inclusion as
a desktop option by most of the Linux distributions.

KDE
The K Desktop Environment (KDE, see www.kde.o�) is another open-source desktop environ­
ment. The toolkit for KDE is Qt (www.trolltech.com). developed by Trolltech. The Qt toolkit
is C++ based, in contrast to Gtk+ which is based on C. Qt has also been the center of contro­
versy in the open-source community, given that it is maintained by a business (Trolltech) as
opposed to an open-source effort. KDE provides a window manager (kwm), a Web browser, a
suite of office applications, and an assortment of accessory applications. Some feel that KDE
is a more solid and self-consistent environment as compared to GNOME (whkh may be true),
and over time, this could lead it to dominate the desktop market. However, its dependency on
a single company for the Qt toolkit and the requirement that applications be developed in C++
seem to be holding it back from widespread domination.

Summary
In this chapter, I introduced the X Window System. At the lowest level, X consists of a pro­
tocol that exists between a client and a server. The X server is software that responds to
requests sent by the client and represents the desktop that users interact with. Requests
allow the client to create windows and draw text and graphics, all of which are displayed
on the server. The X server notifies the client whenever the user moves the mouse, presses
a key on the keyboard, or clicks a mouse button by sending the client an event. The X Pro­
tocol supports only basic primitives that are required by all GU! applications. The applica­
tion programming interface to the X Protocol, Xlib, provides a very thin layer above the X
Protocol itself. It is via the API provided by Xlib that clients issue requests to the X server
and receive errors and events from the X server. The client and X server can either exist on
the same machine, or they can be running on different machines separated by a network.
Communication between the client and server always occurs over TCP/IP.
Sitting on top of Xlib are toolkits such as Xt/Motif, GDKlGtk:+, and Qt. These toolkits
provide higher-level widgets than abstract user interface components that are commonly
found in GUI applications. Menus, buttons, scrollbars, and lists are examples of widgets
found in all of the major toolkits. Each of the toolkits ultimately uses Xlib to implement
these abstractions in software on the client side of the X Protocol. The toolkits themselves
vary in terms of look and feel, and their API. These variations are based upon decisions that
were made by the toolkit designer. Gtk:+ is the toolkit described by this book.
10 Chapter 1 • Gtk+ in Context

A window manager is an application that allows the user to organize applications that
are executing on the desktop. Window placement and iconification are the principle features
provided by a window manager. Window managers are generally written to be independent
of the client applications that they manage, but some, like the Motif Window Manager, are
designed to take advantage of certain simple features made available by the toolkit for
which they were designed.
A desktop environment combines a window manager with a set of applications that were
written using a single toolkit. The Common Desktop Environment (CDE), GNOME, and KDE
are familiar desktop environments. Desktop environments typically provide a suite of simple
desktop applications like calendars, clocks, simple text editors, and calculators. In many ways,
a desktop environment strives to provide a workspace to UNIX users that is similar to that pro­
vided by commodity PC operating systems such as MacOS and Microsoft Windows. In order
for a desktop environment to be successful, it must provide applications that are self-consistent
in terms of user interface and interoperability. Such consistency is provided by the use of a sin­
gle toolkit (e.g., Gtk+), or it can be obtained by adhering to conventions described in a style
guide designed specifically for the toolkit or desktop environment.
 (HAPTER

HELLO GTK+!

In this chapter, we' ll take our first look at what it is like to develop a Gtk+ application. First
I will introduce the basic structure of a Gtk+ application. Then I'll go on to describe how
to build and debug a Gtk+ application using tools such as gmake( 1), gcc( 1 ), and gdb( 1 ) .
We'll also take a look at Gtk+ functions that must b e called i n order to initialize Gtk+ upon
startup and tear down Gtk+ at application exit. As you ' ll see, most of the action in a Gtk+
application happens once mainO makes a call to a routine named gtk_mainO.
In this chapter, we also look at several routines that allow a Gtk+ application to modify
the behavior of the main loop. For example, an application can arrange for gtk_mainO to
call application code at idle time or whenever a timeout has been triggered.

Beginnings
Learning a lower-level user interface API such as Win32, Xlib, or MacOS Toolbox becomes
easier, I believe, when the programmer is presented a basic skeleton application from which
more complicated, real-life applications can be constructed. One of the reasons that a template
or skeleton is helpful is that each of the preceding APls requires the application programmer
to code an event loop. In this event loop, events received from the user interface API (e.g.,
Win32, Xlib, or MacOS Toolbox) are dispatched to other portions of the application for pro­
cessing. The details associated with programming the event loop can be overwhelming for the
uninitiated.
However, Gtk+ is not that kind of programming environment. If there did exist a skele­
ton application for Gtk+, it would be a very minimal one, along the lines of the following
code snippet:

# inc lude <gtk/gtk . h>

int
main ( int argc , char * a rgv [ ] )
{

/ * I ni t i a l i z e Gtk+ * /

11
12 Chapter 2 • Hello Gtk+ !

gtk_set_Iocale ( ) ;
gtk_init ( &argc , &argv ) ;

/ * Create bas i c user interface here and arrange for Gtk+

to c a l l your app l i ca t i on when something int e r e s t ing
happens . The code here wi l l vary f rom one app l i cat ion
to the next . */

/ * Cal l into Gtk+ . Gtk_main ( ) wi l l proce s s event s and c a l l

your app l i ca t i on as prearranged b y t h e code above . * /

gtk main ( ) ;
return ( 0 ) ;

As you can see, our mainO makes two calls to allow Gtk+ to initialize itself. This initial­
ization code is always followed by application-specific code that will instantiate widgets
and arrange for Gtk+ to make calls back to the application whenever something interesting
happens in the user interface. Finally, mainO disappears into a routine called gtk_mainO,
which does not return until the application is ready to exit. The event processing that an Xlib
programmer typically needs to provide is handled within gtk_mainO. Therefore, when you
program in Gtk+, a skeleton application is not really needed because Gtk+ has implemented
the basic skeleton of your application for you.
Readers experienced with the Xt Intrinsics will find Gtk+ to be a very natural and familiar
paradigm. This is because the structure of a Gtk+/GDK application shares much in common
with its XtlXlib counterpart. Programmers with experience programming to APIs such as
Xlib, MacOS Toolbox, or Win32 will find that Gtk+ provides a welcome level of abstraction
above the details these APIs expose, as was hinted to in the preceding discussion. However,
knowledge of any of these APIs, especially Xlib, is never a bad thing in my opinion and will
help when it comes time to understand GDK, which is the thin layer of code that sits directly
above Xlib in the UNIX implementation.
For those of you totally new to GUI programming, don't worry. We' ll start from very
humble beginnings, namely with character-based console applications, and work forward
from there.
The bulk of this chapter consists of a discussion of how to build a simple Gtk+ application
using make(l) and gcc(l). I will also discuss how to use a debugger (gdb( l ) to discover and
fix those pesky crash bugs that will inevitably occur during the course of program develop­
ment. Let's get started.

A Simple Example: Hello Gtk+!

Programmers who know the C language will no doubt be familiar with the following code:
 Adding Interactive Features to a Console Application 13

Listing 2.1 Hello World!, Console I/O Version

# inc lude < s tdio . h>

int
ma in ( int argc , char *argv [ ] )
{
print f ( " He l l o Worl d ! \n " ) ;

Obviously, what this program does is print to stdout (i.e., the console) the string "Hello
World !". To build the application, we make use of gcc( 1 ) :

$ g c c foo . c
$

Assuming we received no compiler errors, we can now run the executable as follows:

$ a . out
He l l o World !
$

Note that gcc( l ) generates an a.out by default. Use -0 to specify some other name for the
generated executable.

Adding Interactive Features to a

Console Application
To make things interesting, let's modify this simple application just a little bit. Instead of
assuming that the person wants to see "Hello World !" each time, we are going to change the
program so that it prompts the user for the string to be displayed. If the user responds by hit­
ting the Enter key, the application will exit without printing anything. If the user types in a
string with a nonzero length, however, that string will be displayed to the console, followed
by application exit. In essence, this program does exactly what echo( l ) does: print whatever
the user types (including nothing).
Here is Hello World ! , version 2.0:

Listing 2.2 Hello World, Console I/O Version, Interactive

# include < s tdio . h>

int
main ( int argc , char *argv [ ] )
{
char buf [ BUFS I ZE ] ; / * should be enough * /

fget s ( buf , BUFS I Z , stdin ) ;

i f ( strlen ( buf ) )
14 Chapter 2 • Hello Gtk+ !

print f ( " % s \n " , buf ) ;

This application is also built using gcc( 1 ) in the same way that was done for Hello
World ! version 1 . The following example illustrates what the user might see when the above
code is executed:

$ a . out
He l l o Big World < - - - - the user types thi s . . .
He l l o Big World < - - - - and He l l o World ! ver s i on 2 prints this
$

A Paradigm Shift
You must be wondering at this point, "Why is he talking so much about console applications?
This book is supposed to be teaching me how to develop GUI-based applications in Gtk+ !"
The reason is simple: For those of you new to GUI applications, you are about to face a major
paradigm shift, and understanding the difference is critical to understanding how to program
a GUI application with Gtk+.
In non-GUI console applications, flow of control goes from one statement to the next.
Thus, in Hello World ! versions 1 and 2, each line is executed in sequence, one after another.
If the program must wait for user input, as is done when fgets(3) in Hello World ! version 2 is
called, the program will block and only resume execution after the input request has been sat­
isfied. Even control structures such as while and for loops impose a serial, one-after-another
flow of control on the application. Execution starts at the top of the loop with the first state­
ment in the body of the loop and then goes to the second statement, and so forth. When at the
bottom, control returns to the top of the loop, and the process starts all over again.
In Gtk+, things are different. To see how, let's dive right in and look at Hello World !
version 3, written using the Gtk+ toolkit:

Listing 2.3 Hello World! , Gtk+ Version

001 # inc lude < s tdio . h>

002 # inc lude <gtk/gtk . h>
003
004 s t at i c GtkWidget * entry ;
005
006 vo id
007 PrintAndExi t ( GtkWidget *widget , GtkWidget *window )
008
009 char *str ;
010
011 s t r = gtk_ent ry_get_text ( GTK_ENTRY ( entry ) ) ;
012 i f ( s t r ! = ( char * ) NULL )
013 print f ( " % s \n " , s t r ) ;
014
015 gtk_widge t_de s t roy ( window ) ;
 A Paradigm Shift 15

016 gtk_main_qui t ( ) ;
017
018
019 voi d
020 PrintByeAndExi t ( GtkWidget *widge t , gpointer data )
021 {
022 print f ( " Goodbye , world ! \n " ) ;
023 gtk exi t ( O ) ;
024
025
026 int
027 ma in ( int argc , char *argv [ ] )
028 {
029 GtkWidget *window , * labe l , *vbox , * hbox , * butt on , * s eparator ;
030
031 gtk_set_Iocale ( ) ;
032
033 gtk_init ( &argc , &argv ) ;
034
035 window gtk_window_new ( GTK_WINDOW_TOPLEVEL ) ;
=

036 gtk_window_set-pol icy ( GTK_WINDOW ( window ) , FALSE , FALSE , FALSE ) ;

037
038 gtk_s ignal_connec t ( GTK_OBJECT ( window ) , " de s t roy " ,
039 GTK_S IGNAL_FUNC ( PrintByeAndExi t ) , NULL ) ;
040
041 gtk_window_set_t i t l e ( GTK_WINDOW ( window ) , " He l l o Gtk+ ! " ) ;
042 gtk_container_border_width ( GTK_CONTAINER ( window ) , 0 ) ;
043
044 vbox gtk_vbox_new ( FALSE , 0 ) ;
=

045 gtk_container_add ( GTK_CONTAINER ( window ) , vbox ) ;

046
047 hbox gtk_hbox_new ( FALSE , 0 ) ;
=

048 gtk_box-pack_s tart ( GTK_BOX ( vbox ) , hbox , FALSE , FALSE , 0 ) ;

049
050 labe l gtk_Iabe l_new ( " Enter a me s sage : " ) ;
=

051 gtk_box-pack_start ( GTK_BOX ( hbox ) , l abe l , FALSE , FALSE , 0 ) ;

052 entry gtk_entry_new ( ) ;
=

053 gtk_entry_set_t ext ( GTK_ENTRY ( entry ) , " " ) ;

054 gtk_edi table_s e l e c t_regi on ( GTK_EDI TABLE ( entry) , 0 , - 1 ) ;
055 gtk_box-pack_s tart ( GTK_BOX ( hbox ) , ent ry , FALSE , FALSE , 0 ) ;
056
057 separator gtk_hseparator_new ( ) ;
=

058 gtk_box-pack_start ( GTK_BOX ( vbox ) , s eparator , FALSE , FALSE , 0 ) ;

059
060 but ton gtk_button_new_wi th_labe l ( " Print " ) ;
=

061 gtk_s ignal_connect_objec t ( GTK_OBJECT ( button ) , " c l i cked " ,

062 GTK_S IGNAL_FUNC ( PrintAndExi t ) , GTK_OBJECT ( window ) ) ;
063 gtk_box-pack_s tart ( GTK_BOX ( vbox ) , but t on , FALSE , FALSE , 0 ) ;
064 GTK_WIDGET_SET_FLAGS ( button , GTK_CAN_DEFAULT ) ;
065 gtk_widget_grab_de fau l t ( button ) ;
066
16 Chapter 2 • Hello Gtk:+ !

067 gtk_widge t_show_al l ( window ) ;

068
069 gtk ma in ( ) ;
070
071 return ( 0 ) ;
072

A s you can see, Gtk+ Hello World ! applications can b e rather lengthy compared to the
length of the console version. Before we take a look at the code, let's first understand what
the application is designed to do.

Understanding the Gtk+ Hello World Sam ple

The premise of this example is similar to that of Hello World ! version 2: to echo a string
supplied by the user (or nothing should the user not type in a string). The application starts
out as shown in Figure 2. 1 . The dialog displayed contains a text edit field, below which is
a button labeled Print. When the user presses the Print button, the application prints the text
entered by the user in the text field to stdout and exits. If the user does not enter any text,
nothing is printed.

Figure 2 . 1 Hello World!

Lines 00 1 and 002 identify the include files required by the source code. We include
<stdio.h> because we will use printfO to display the text entered by the user. <gtk/gtk.h>
is required because this is a Gtk+ application. The Gtk+ includes should be located in
/usr/include/gtk on your system. If the compiler has problems finding gtk.h, it might be
located somewhere else; check with your systems administrator if you can't locate them
and need help.
The include file gtk.h includes the remaining include files found in /usr/include/gtk.
Including <gtk/gtk.h> is all you need to do to bring in the types, constants, and macros
needed by your source code. This is in contrast to the Motif development environment,
where typically programmers are required to individually include header files correspond­
ing to widgets needed by the application, one by one.
Our main routine starts on line 027. On line 029, several variables of type GtkWidget *
are declared. A GtkWidget is roughly analogous to the Widget type in Motif. For readers not
familiar with widgets (I will use the term "widget" to describe the object represented by the
GtkWidget type), for now think of a widget as an opaque data type representing a window
or a control that the user sees on the display and interacts with. We'll spend a lot of time talk­
ing about widgets in this book because learning Gtk+ largely amounts to learning about the
Understanding the Gtk+ Hello World Sample 17

widgets that the toolkit provides and how to make good use of them when constructing an
application user interface.
On line 03 1 , gtk_seUocaleO is called. This is actually a wrapper function that calls
gdk_seUocaleO, which in tum calls setlocale(3).
Line 033 introduces our first major Gtk+ routine, gtk_initO. All Gtk+ clients must call
gtk_initO at the beginning of the application before creating any widgets. gtk_initO takes
as arguments the argc and argv arguments that were passed to mainO by the runtime envi­
ronment. gtk_initO will inspect each argument that was passed to the application on the
command line, processing and removing those arguments that are recognized. A modified
argc, argv will be returned to the application if any arguments were processed by gtk_initO,
with the processed arguments removed from argv and the value of argc decremented
accordingly. Later in this chapter, we will look at some of the command-line arguments
handled by gtk_initO. Other tasks performed by gtk_initO include signal initialization, get­
ting the system default colormap and visual, and registering an exit function so that cleanup
can be performed should the application not exit in a clean manner.
Our user interface definition starts with line 035, where we create a top-level window.
For us, the top-level window represents a place within which the text edit field and Print
button will be placed. As we will see, it is a bit more complicated than this because the top­
level window is actually a container not only for the text field and the button, but for other
widgets that are not visible to the user but are needed by the application to help manage the
placement of the visual controls (the text field and the button) within the top-level window.

Figure 2.2 Widget Instance Hierarchy Tree

Figures 2.2 and 2.3 should help to make this clear. Figure 2.2 illustrates the widget
instance hierarchy for our example application. Widgets that are higher in the hierarchy
Random documents with unrelated
content Scribd suggests to you:
making the bias and drift of his extraordinary mind intelligible to me,
it generally only served him for amusement when I behaved
strangely enough, in trying to get at the meaning of such sibylline
leaves. However, I could well feel that something in Hamann's
writings appealed to me; and to this I gave myself up, without
knowing whence it came or whither it was leading me.
After the cure had lasted longer than was
reasonable, Lobstein had begun to hesitate, and to Herder's
Departure.
repeat himself in his treatment, so that the affair
would not come to an end; and Peglow, too, had
confided to me in private that a favourable issue was hardly to be
expected; the whole position became gloomy; Herder became
impatient and out of temper, he could not succeed in continuing his
activity as heretofore, and was obliged to restrain himself the more,
as they began to lay the blame of the surgical failure upon his too
great mental exertion, and his uninterrupted, animated, nay, merry
intercourse with us. It is sufficient to say, that after so much trouble
and suffering, the artificial tear-channel would not form itself, and
the communication intended would not take place. It was necessary
to let the wound heal over in order that the disease should not
become worse. If, now, during the operation, one could but admire
Herder's firmness under such pains, his melancholy and even fierce
resignation to the idea that he must bear such a blot about him all
his life, had about it something truly sublime, by which he gained for
ever the reverence of those who saw and loved him. This disease,
which disfigured so expressive a countenance, must have been so
much the more afflicting to him, as he had become acquainted with
an excellent lady in Darmstadt, and had gained her affections. It
may have been for this cause principally that he submitted to the
cure, in order, on his return, to appear more free, more cheerful, and
more handsome in the eyes of his half-betrothed, and to unite
himself more certainly and indissolubly with her. However, he
hastened away from Strasburg as soon as possible, and since his
stay had hitherto been as expensive as it was unpleasant, I
borrowed a sum of money for him, which he promised to refund by
an appointed day. The time passed without the arrival of the money.
My creditor, indeed, did not dun me; but I was for several weeks in
embarrassment. At last the letter and the money came, and even
here he did not act unlike himself; for, instead of thanks or an
apology, his letter contained nothing but satirical things in doggerel
verse, which would have puzzled, if not alienated, another; but it did
not move me at all, for I had conceived so great and powerful an
idea of his worth that it absorbed everything of an opposite nature
which could have injured it.
One should never speak, publicly at least, of one's own faults, or
those of others, if one does not hope to effect some useful purpose
by it; on this account I will here insert certain remarks which force
themselves upon me.
Gratitude and ingratitude belong to those events which appear every
moment in the moral world, and about which men can never agree
among themselves. I usually distinguish between non-thankfulness,
ingratitude, and aversion from gratitude. The first is innate with
men, nay, created with them; for it arises from a happy volatile
forgetfulness of the repulsive as well as of the delightful, by which
alone the continuation of life is possible. Man needs such an infinite
quantity of previous and concurrent assistances for a tolerable
existence, that if he would always pay to the sun and the earth, to
God and nature, to ancestors and parents, to friends and
companions, the thanks due to them, he would have neither time
nor feeling left to receive and enjoy new benefits. But if the natural
man suffers this volatility to get the control in and over him, a cold
indifference gains more and more the ascendancy, and one at last
regards one's benefactor as a stranger, to whose injury, perhaps,
anything may be undertaken, provided it be advantageous to
ourselves. This alone can properly be called ingratitude, which
results from the rudeness into which the uncultivated nature must
necessarily lose itself at last. Aversion from gratitude, however, the
rewarding of a benefit by ill-natured and sullen conduct, is very rare,
and occurs only in eminent men, such as, with great natural gifts,
and a presentiment of them, being born in a lower rank of society or
in a helpless condition, must, from their youth upwards, force
themselves along, step by step, and receive, at every point, aids and
supports, which are often embittered and repulsive to them through
the coarseness of their benefactors, since that which they receive is
earthly, while that which, on the other hand, they give, is of a higher
kind, so that what is, strictly speaking, a compensation, is out of the
question. Lessing, with the fine knowledge of earthly things which
fell to his share in the best years of his life, has in one place bluntly,
but cheerfully expressed himself. Herder, on the contrary, constantly
embittered his finest days, both for himself and others, because he
knew not how to moderate, by strength of mind in later years, that
ill-humour which had necessarily seized him in youth.
One may well make this demand of oneself: for, to
a man's capability of cultivation, comes, with Artificial
Gratitude.
friendly aid, the light of nature, which is always
active in enlightening him about his condition; and
generally, in many moral points of culture, one should not construe
the failings too severely, nor look about after the most serious and
remote means of correcting them; for certain faults may be easily
and even playfully removed. Thus, for instance, by mere habit, we
can excite gratitude in ourselves, keep it alive, and even make it
necessary to us.
In a biographical attempt, it is proper to speak of oneself. I am, by
nature, as little grateful as any man, and on forgetting the benefit
received, the violent feeling of a momentary disagreement could
very easily beguile me into ingratitude.
To obviate this, I accustomed myself, in the first place, with
everything that I possessed, to call to mind with pleasure how I
came by it, from whom I received it, whether it was by way of
present, exchange, or purchase, or in any other manner. I have
accustomed myself, in showing my collections, to mention the
persons by whose means I obtained each article, nay, even to do
justice to the occasion, to the accident, to the remotest cause and
coincidence, by which things which are dear and of value to me have
become mine. That which surrounds us thus receives a life; we see
in it a spiritual combination, full of love, reminding us of its origin;
and, by thus making past circumstances present to us, our
momentary existence is elevated and enriched, the originators of the
gifts rise repeatedly before the imagination, we connect with their
image a pleasing remembrance, ingratitude becomes impossible, and
a return, on occasion, becomes easy and desirable. At the same
time, we are led to the consideration of that which is not a
possession palpable to the senses, and we love to recapitulate to
whom our higher endowments are to be ascribed, and whence they
take their date.
Before I turn my attention from that connexion with Herder, which
was so important and so rich in consequences for me, I find yet
something more to adduce. Nothing was more natural than that I
should by degrees become more and more reserved towards Herder,
in communicating those things which had hitherto contributed to my
culture, but especially such as still seriously occupied my attention at
the moment. He had destroyed my enjoyment of so much that I had
loved before, and had especially blamed me in the strongest manner
for the pleasure I took in Ovid's Metamorphoses. I might defend my
favourite as I would, I might say that, for a youthful fancy, nothing
could be more delightful than to linger in those cheerful and glorious
regions with gods and demi-gods, and to be a witness of their deeds
and passions; I might circumstantially quote that previously
mentioned opinion of a sober-minded man, and corroborate it by my
own experience; all this, according to Herder, went for nothing;
there was no immediate truth, properly so called, to be found in
these poems; here was neither Greece nor Italy, neither a primitive
world nor a cultivated one, everything was rather an imitation of
what had already existed, and a mannerised representation, such as
could be expected only from an over-cultivated man. And if at last I
would maintain, that whatever an eminent individual produces is
also nature, and that always, in all nations, ancient and modern, the
poet alone has been the maker; this was not allowed to pass, and I
had to endure much on this account, nay, I was almost disgusted
with my Ovid by it; for there is no affection, no habit so strong, that
it can hold out in the long run against the animadversions of
eminent men in whom one places confidence. Something always
cleaves to us, and if one cannot love unconditionally, love is already
in a critical condition.
"Goetz von Berlichingen mit der eisernen Hand." Brustbild des Götz von Lovis
Corinth (1921-1922, Frankfurter Goethehaus, Freies Deutsches Hochstift.)
I most carefully concealed from him my interest in certain subjects
which had rooted themselves within me, and were, by little and little,
moulding themselves into poetic form. These were Götz von
Berlichingen and Faust. The biography of the former had seized my
inmost heart. The figure of a rude, well-meaning self-helper, in a wild
anarchical time, awakened my deepest sympathy. The significant
puppet-show fable of the latter resounded and vibrated many-toned
within me. I had also wandered about in all sorts of science, and had
early enough been led to see its vanity. I had, moreover, tried all sorts
of ways in real life, and had always returned more unsatisfied and
troubled. Now these things, as well as many others, I carried about
with me, and delighted myself with them during my solitary hours,
but without writing anything down. But most of all, I concealed from
Herder my mystico-cabalistical chemistry, and everything relating to it,
although, at the same time, I was still very fond of secretly busying
myself in working it out more consistently than it had been
communicated to me. Of my poetical labours, I believe I laid before
him Die Mitschuldigen, but I do not recollect that on this account I
received either correction or encouragement on his part. Yet, with all
this, he remained what he was; whatever proceeded from him had an
important, if not a cheering effect, and even his handwriting exercised
a magic power over me. I do not remember having ever torn up or
thrown away one of his letters, or even a mere envelope from his
hand; yet, with my various changes of place and time, not one
document of those strange, foreboding, and happy days is left.
.... De temps en temps j'aime à voir le vieux Père,
Et je me garde bien de lui rompre en Misiere...
par Eugène Delacroix (Source: Faust, tragédie de M. de Goethe, traduite en
français par M. Albert Stapfer. C. Motte (Paris) 1828 - Gallica Bnf)
That Herder's power of attraction operated upon
others as well as upon me, I should scarcely Herder's Influence
on Jung.
mention, had I not to remark that it extended itself
particularly to Jung, commonly called Stilling. The
true, honest striving of this man could not but deeply interest
everybody who had any feeling, and his susceptibility must have
charmed into candour every one who was in a condition to impart
anything. Even Herder behaved towards him with more forbearance
than towards the rest of us: for his counter-action always seemed to
stand in relation with the action exerted upon him. Jung's narrowness
was accompanied by so much good-will, his urgency with so much
softness and earnestness, that a man of intelligence could certainly
not be severe against him, and a benevolent man could not scoff at
him, or turn him into ridicule. Jung was also exhilarated to such a
degree by Herder, that he felt himself strengthened and advanced in
all he did; even his affection for me seemed to lose ground in the
same ratio; yet we always remained good companions, made
allowances for each other from first to last, and mutually rendered the
most friendly services.
Let us now, however, withdraw ourselves from the sick chamber of
friendship, and from the general considerations which refer rather to
disorder than to health of mind; let us betake ourselves into the open
air, to the lofty and broad gallery of the minster, as if the time were
still present, when we young fellows often appointed an evening
meeting to greet the departing sun with brimming goblets. Here all
conversation was lost in the contemplation of the country: here
sharpness of eye-sight was put to the proof, and every one strove to
perceive, nay, plainly to distinguish, the most distant objects. Good
telescopes were employed to assist us, and one friend after another
exactly pointed out the spot which had become the most dear and
precious to him; and I also did not lack such a little spot, which,
although it did not come out with importance in the landscape,
nevertheless more than all the rest attracted me with an amiable
magic. On these occasions the imagination was excited by relating our
adventures, and several little jaunts were concerted, nay, often
undertaken on the spur of the moment, of which I will circumstantially
relate only one instead of a number, since in many respects it was of
consequence to me.
With two worthy friends and fellow-boarders, Engelbach and Weyland,
both natives of Lower Alsace, I repaired on horseback to Zabern,
where, in the fine weather, the friendly little place smiled pleasantly
upon us. The sight of the bishop's castle awakened our admiration;
the extent, height, and splendour of a new set of stables bore witness
to the other comforts of the owner. The gorgeousness of the staircase
surprised us, the chambers and saloons we trode with reverence, only
the person of the cardinal, a little wreck of a man, whom we saw at
table, made a contrast. The view of the garden is splendid, and a
canal, three quarters of a league long, which leads straight up to the
middle of the castle, gives a high idea of the taste and resources of
the former possessors. We rambled up and down there, and enjoyed
many parts of this beautifully situated whole, which lies on the
outskirts of the magnificent plain of Alsace, at the foot of the Vosges.
After we had enjoyed ourselves at this clerical outpost of a royal
power, and had made ourselves comfortable in its region, we arrived
early next morning at a public work, which most nobly opens the
entrance into a mighty kingdom. Illumined by the beams of the rising
sun, the famous Zabern-stairs, a work of incredible labour, rose before
us. A road, built serpentine-wise over the most fearful crags, and wide
enough for three wagons abreast, leads up hill so gently, that the
ascent is scarcely perceptible. The hardness and smoothness of the
way, the flat-topped elevations on both sides for the foot-passengers,
the stone channels to lead off the mountain-water, all are executed as
neatly as artistically and durably, so that they afford a satisfactory
view. Thus one gradually arrives at Pfalzburg, a modern fortification.
It lies upon a moderate hill; the works are elegantly built on blackish
rocks, and of the same kind of stone, and the joinings being pointed
out with white mortar, show exactly the size of the square stones, and
give a striking proof of neat workmanship. We found the place itself,
as is proper for a fortress, regular, built of stone, and the church in
good taste. When we wandered through the streets—it was nine
o'clock on Sunday morning—we heard music; they were already
waltzing in the tavern to their hearts' content, and as the inhabitants
did not suffer themselves to be disturbed in their pleasures by the
great scarcity, nay, by the threatened famine, so also our youthful
cheerfulness was not at all troubled when the baker on the road
refused us some bread, and directed us to the tavern, where perhaps
we might procure provisions at the usual place.
We now very willingly rode down the Zabern-stairs
again to gaze at this architectural wonder a second Zabern-
Buchsweiler.
time, and to enjoy once more the refreshing
prospect over Alsace. We soon reached Buchsweiler,
where friend Weyland had prepared for us a good reception. To a
fresh youthful mind the condition of a small town is well suited; family
connexions are closer and more perceptible; domestic life, which, with
moderate activity, moves hither and thither between light official
duties, town business, agriculture and gardening, invites us to a
friendly participation; sociableness is necessary, and the stranger finds
himself very pleasantly situated in the limited circles, if the disputes of
the inhabitants, which in such places are more palpable, do not
everywhere come in contact with him. This little town was the chief
place of the county of Hanau-Lichtenberg, belonging to the Landgrave
of Darmstadt, under French sovereignty. A regency and board of
officers established here made the place an important centre-point of
a very beautiful and desirable principality. We easily forgot the
unequal streets and the irregular architecture of the place when we
went out to look at the old castle and the gardens, which are
excellently laid out on a hill. Numerous little pleasure-woods, a
preserve for tame and wild pheasants, and the relics of many similar
arrangements, showed how pleasant this little residence must
formerly have been.
Yet all these views were surpassed by the prospect which met the
eye, when, from the neighbouring Baschberg, one looked over the
perfectly paradisiacal region. This height, wholly heaped together out
of different kinds of shells, attracted my attention for the first time to
such documents of antiquity; I had never before seen them together
in so great a mass. Yet the curious eye soon turned itself exclusively
to the landscape. You stand on the last landward[2] mountain-point;
towards the north lies a fruitful plain, interspersed with little forests,
and bounded by a stem low of mountains that stretches itself
westward towards Zaber, where the episcopal palace and the abbey of
St. John, lying a league beyond it, may be plainly recognised. Thence
the eye follows the more and more vanishing chain of the Vosges
towards the south. If you turn to the north-east you see the castle of
Lichtenberg upon a rock, and towards the south-east the eye has the
boundless plain of Alsace to scrutinize, which, afar off, withdraws itself
from the sight in the more and more misty landscape, until at last the
Suabian mountains melt away like shadows into the horizon.
Already in my limited wanderings through the world, I had remarked
how important it is in travelling to inquire after the course of the
waters, and even to ask with respect to the smallest brook, whither in
reality it runs. One thus acquires a general survey of every stream-
region, in which one happens to be, a conception of the heights and
depths which bear relation to each other, and by these leading things,
which assist the contemplation as well as the memory, extricates
oneself in the surest manner from the geological and political
labyrinth. With these observations, I took a solemn farewell of my
beloved Alsace, as the next morning we meant to turn our steps
towards Lorraine.
The evening passed away in familiar conversation, in which we tried
to cheer ourselves up under a joyless present, by remembrances of a
better past. Here, as in the whole of this small country, the name of
the last Count Reinhard von Hanau was blessed above all others; his
great understanding and aptitude had appeared in all his actions, and
many a beautiful memorial of his existence yet remained. Such men
have the advantage of being double benefactors: once to the present,
which they make happy, and then to the future, the feeling of which
and courage they nourish and sustain.
Now as we turned ourselves north-westward into
the mountains, passed by Lützelstein, an old Saarbrück.
mountain tower, in a very hilly country, and
descended into the region of the Saar and the Moselle, the heavens
began to lower, as if they would render yet more sensible to us the
condition of the more rugged western country. The valley of the Saar,
where we first found Bockenheim, a small place, and saw opposite to
it Neusaarwerden, which is well-built, with a pleasure-castle, is
bordered on both sides by mountains which might be called
melancholy, if at their foot an endless succession of meadows and
fields, called the Huhnau, did not extend as far as Saaralbe, and
beyond it, further than the eye can reach. Great buildings, belonging
to the former stables of the Duke of Lorraine, here attract the eye;
they are at present used as a dairy, for which purpose, indeed, they
are very well situated. We passed through Saargemünd to Saarbrück,
and this little residence was a bright point in a land so rocky and
woody. The town, small and hilly, but well adorned by the last prince,
makes at once a pleasing impression, as the houses are all painted a
greyish white, and the different elevation of them affords a variegated
view. In the middle of a beautiful square, surrounded with handsome
buildings, stands the Lutheran church, on a small scale, but in
proportion with the whole. The front of the castle lies on the same
level with the town; the back, on the contrary, on the declivity of a
steep rock. This has not only been worked out terrace-fashion, to
afford easy access to the valley, but an oblong garden-plot has also
been obtained below, by turning off the stream on one side, and
cutting away the rock on the other, after which this whole space was
lastly filled up with earth and planted. The time of this undertaking
fell in the epoch when they used to consult the architects about laying
out gardens, just as at present they call in the aid of the landscape-
painter's eye. The whole arrangement of the castle, the costly and the
agreeable, the rich and the ornamental, betokened a life-enjoying
owner, such as the deceased prince had been; the present sovereign
was not at home. President von Günderode received us in the most
obliging manner, and entertained us for three days better than we had
a right to expect. I made use of the various acquaintance which we
formed to instruct myself in many respects. The life of the former
prince, rich in pleasure, gave material enough for conversation, as
well as the various expedients which he hit upon to make use of the
advantages supplied by the nature of his land. Here I was now
properly initiated into the interest for mountain countries, and the
love for those economical and technical investigations which have
busied me a great part of my life, was first awakened within me. We
heard of the rich coal-pits at Dutweil, of the iron and alum works, and
even of a burning mountain, and we prepared ourselves to see these
wonders close.
We now rode through woody mountains, which must seem wild and
dreary to him who comes out of a magnificent fertile land, and which
can attract us only by the internal contents of its bosom. We were
made acquainted with one simple, and one complicated piece of
machinery, within a short distance of each other; namely, a scythe-
smithy and a wire-drawing factory. If one is pleased at the first
because it supplies the place of common hands, one cannot
sufficiently admire the other, for it works in a higher organic sense,
from which understanding and consciousness are scarcely to be
separated. In the alum-works we made accurate inquiries after the
production and purifying of this so necessary material, and when we
saw great heaps of a white greasy, loose, earthy matter, and asked
the use of it, the labourers answered, smiling, that it was the scum
thrown up in boiling the alum, and that Herr Stauf had it collected, as
he hoped perchance to turn it to some profit. "Is Herr Stauf alive
yet?" exclaimed my companion in surprise. They answered in the
affirmative, and assured us that according to the plan of our journey
we should not pass far from his lonely dwelling.
Our road now led up along the channels by which
the alum-water is conducted down, and the principal Coal and Alum-
Works.
horizontal works (stollen), which they call the
"landgrube," and from which the famous Dutweil
coals are procured. These, when they are dry, have the blue colour of
darkly tarnished steel, and the most beautiful succession of rainbow
tints plays over the surface with every movement. The deep abysses
of the coal-levels, however, attracted us so much the less as their
contents lay richly poured out around us. We now reached the open
mine, in which the roasted alum-scales are steeped in lye, and soon
after, a strange occurrence surprised us, although we had been
prepared. We entered into a chasm and found ourselves in the region
of the Burning Mountain. A strong smell of sulphur surrounded us;
one side of the cavity was almost red-hot, covered with reddish stone
burnt white; thick fumes arose from the crevices, and we felt the heat
of the ground through our strong boot-soles. An event so accidental,
for it is not known how this place became ignited, affords a great
advantage for the manufacture of alum, since the alum-scales of
which the surface of the mountain consists, lie there perfectly roasted,
and may be steeped in a short time and very well. The whole chasm
had arisen by the calcined scales being gradually removed and used
up. We clambered up out of this depth, and were on the top of the
mountain. A pleasant beech-grove encircled the spot, which followed
up to the chasm and extended itself on both sides of it. Many trees
stood already dried up, some were withering near others, which, as
yet quite fresh, felt no forebodings of that fierce heat which was
approaching and threatening their roots also.
Upon this space different openings were steaming, others had already
done smoking, and this fire had thus smouldered for ten years already
through old broken-up pits and horizontal shafts, with which the
mountain is undermined. It may, too, have penetrated to the clefts
through new coal-beds: for, some hundred paces further into the
wood, they had contemplated following up manifest indications of an
abundance of coal; but they had not excavated far before a strong
smoke burst out against the labourers and dispersed them. The
opening was filled up again, yet we found the place still smoking as
we went on our way past it to the residence of our hermit-like
chemist. This lies amid mountains and woods; the vallies there take
very various and pleasing windings, the soil round about is black and
of the coal kind, and strata of it frequently come in sight. A coal
philosopher—philosophus per ignem, as they said formerly—could
scarcely have settled himself more suitably.
We came before a small house, not inconvenient for a dwelling, and
found Herr Stauf, who immediately recognised my friend, and
received him with lamentations about the new government. Indeed
we could see from what he said, that the alum-works, as well as
many other well-meant establishments, on account of external and
perhaps internal circumstances also, did not pay their expenses; with
much else of the sort. He belonged to the chemists of that time, who,
with a hearty feeling for all that could be done with the products of
nature, took delight in abstruse investigations of trifles and secondary
matters, and with their insufficient knowledge were not dexterous
enough to do that from which properly economical and mercantile
profit is to be derived. Thus the use which he promised himself from
that scum lay very far in the distance; thus he had nothing to show
but a cake of sal-ammoniac, with which the Burning Mountain had
supplied him.
Ready and glad to communicate his complaints to a human ear, the
lean, decrepit little man, with a shoe on one foot and a slipper on the
other, and with stockings hanging down and repeatedly pulled up in
vain, dragged himself up the mountain to where the resin-house
stands, which he himself had erected, and now, with great grief, sees
falling to ruins. Here was found a connected row of furnaces, where
coal was to be cleansed of sulphur, and made fit for use in iron-works;
but at the same time they wished also to turn the oil and resin to
account; nay, they would not even lose the soot; and thus all failed
together, on account of the many ends in view. During the life-time of
the former prince, the business had been carried on in the spirit of an
amateur, and in hope; now they asked for the immediate use, which
was not to be shown.
After we left our adept to his solitude, we hastened—for it was now
late—to the glass-house in Friedrichsthal, where we became
acquainted, on our way, with one of the most important and most
wonderful operations of human ingenuity.
Nevertheless, some pleasant adventures, and a surprising firework at
night-fall, net far from Neukirch, interested us young fellows almost
more than these important experiences. For as a few nights before,
on the banks of the Saar, shining clouds of glow-worms hovered
around us, betwixt rock and thicket, so now the spark-spitting forges
played their sprightly firework towards us. We passed, in the depth of
night, the smelting-houses situated in the bottom of the valley, and
were delighted with the strange half-gloom of these dens of plank,
which are but dimly lighted by a little opening in the glowing furnace.
The noise of the water, and of the bellows driven by it, the fearful
whizzing and shrieking of the blast of air which, raging into the
smelted ore, stuns the ears and confuses the senses, drove us away,
at last, to turn into Neukirch, which is built up against the mountain.
But, notwithstanding all the variety and fatigue of the day, I could find
no rest here. I left my friend to a happy sleep, and sought the
hunting-seat, which lay still further up. It looks out far over mountain
and wood, the outlines of which were only to be recognised against
the clear night-sky, but the sides and depths of which were
impenetrable to my sight. This well-preserved building stood as empty
as it was lonely; no castellan, no huntsman was to be found. I sat
before the great glass doors upon the steps which run around the
whole terrace. Here, surrounded by mountains, over a forest-grown,
dark soil, which seemed yet darker in contrast with the clear horizon
of a summer night, with the glowing starry vault above me, I sat for a
long time by myself on the deserted spot, and thought I never had
felt such a solitude. How sweetly, then, was I surprised by the distant
sound of a couple of French horns, which at once, like the fragrance
of balsam, enlivened the peaceful atmosphere. Then there awakened
within me the image of a lovely being, which had retired into the
background before the motley objects of these travelling days, but
which now unveiled itself-more and more, and drove me from the
spot back to my quarters, where I made preparations to set off with
the earliest.
The return was not used like the journey out. Thus
we hurried through Zwey-brücken (Deux-Ponts), Zwey-Brücken.
which, as a beautiful and notable residence, might
well have deserved our attention. We cast a glance upon the great,
simple castle, on the extensive esplanades, regularly planted with
linden-trees, and very well adapted for the training of race-horses,
and on the large stables, and the citizens' houses which the prince
had built to be raffled for. All this, as well as the costume and
manners of the inhabitants, especially of the matrons and maids, had
reference to a distant connexion, and made plainly visible the relation
with Paris, from which, for a long time, nothing transrhenane had
been able to withdraw itself. We visited also the ducal wine-cellars,
situated before the city, which are extensive, and furnished with large,
well-made tuns. We went on further, and at last found the country like
that in the neighbourhood of Saarbrück. Between wild and savage
mountains are a few villages; one here gets rid of the habit of looking
about for corn. We mounted up, by the side of the Hornbach, to
Bitsch, which lies on the important spot where the waters divide, and
fall, a part into the Saar, a part into the Rhine. These last were soon
to attract us towards them. Yet we could not refuse our attention to
the little city of Bitsch, which very picturesquely winds around the
mountain, nor to the fortress, which lies above. This is partly built on
rocks, and partly hewn out of them. The subterraneous chambers are
particularly worthy of remark; here is not only space sufficient for the
abode of a number of men and cattle, but one even lights upon large
vaults for the drilling of troops, a mill, a chapel, and whatever else
could be required under-ground, provided the surface were in a state
of disturbance.
We now followed the down-rushing brooks through Bärenthal. The
thick forests on both the heights remain unused by the hand of man.
Here trunks of trees lie rotting on each other by thousands, and
young scions sprout up without number from their half-mouldered
progenitors. Here, in conversation with some companions on foot, the
name Von Dieterich again struck our ears, which we had often heard
honourably mentioned already in these woody regions. The activity
and cleverness of this man, his wealth, and the use and applications
of it, all seemed in proportion. He could with justice take delight in
the acquisitions which he increased, and enjoy the profits he secured.
The more I saw of the world, the more pleasure I took, not only in
the universally famous names, but in those also, especially, which
were mentioned in particular regions with reverence and love: and
thus I easily learned here, by a few questions, that Von Dieterich,
earlier than others, had known how to make successful use of the
mountain treasures, iron, coal, and wood, and had worked his way to
an ever-growing opulence.
Niederbrunn, where we now arrived, was a new proof of this. He had
purchased this little place from the Count of Leiningen and other part-
owners, to erect important iron-works in the place.
Here in these baths, already founded by the Romans, floated around
me the spirit of antiquity, venerable relics of which, in fragments of
bas-reliefs and inscriptions, capitals and shafts, shone out strangely
towards me, from farm-houses, amidst household lumber and
furniture.
As we were ascending the adjacent Wasenburg also,
I paid my respects to a well-preserved inscription, Sesenheim.
which discharged a thankful vow to Mercury, and is
situated upon the great mass of rock which forms the base of the hill
on one side. The fortress itself lies on the last mountain, looking from
Bitsch towards Germany. It is the ruin of a German castle built upon
Roman remains. From the tower the whole of Alsace was once more
surveyed, and the conspicuous minster-spire pointed out the situation
of Strasburg. First of all, however, the great forest of Hagenau
extended itself, and the towers of this town peered plainly from
behind. I was attracted thither. We rode through Reichshof, where
Von Dieterich built an imposing castle, and after we had contemplated
from the hills near Niedermoder the pleasing course of the little river
Moder, by the forest of Hagenau, I left my friend on a ridiculous coal-
mine visitation, which, at Dutweil, might have been a somewhat more
serious business, and I then rode through Hagenau, on the direct
road—already indicated by my affection—to my beloved Sesenheim.
For all these views into a wild, mountain region, and then, again, into
a cheerful, fruitful, joyous land, could not rivet my mind's eye, which
was directed to an amiable, attractive object. This time, also, the
hither way seemed to me more charming than its opposite, as it
brought me again into the neighbourhood of a lady to whom I was
heartily devoted, and who deserved as much respect as love. But
before I lead my friends to her rural abode, let me be permitted to
mention a circumstance which contributed very much to enliven and
enhance my affection, and the satisfaction which it afforded me.
How far I must have been behindhand in modern
literature, may be gathered from the mode of life The "Vicar of
Wakefield."
which I led at Frankfort, and from the studies to
which I had devoted myself; nor could my residence
in Strasburg have furthered me in this respect. Now Herder came, and
together with his great knowledge brought many other aids, and the
later publications besides. Among these he announced to us the Vicar
of Wakefield as an excellent work, with the German translation of
which he would make us acquainted by reading it aloud to us himself.
His method of reading was quite peculiar; whoever has heard him
preach will be able to form a notion of it. He delivered everything, this
romance included, in a serious and simple style, perfectly removed
from all dramatically imitative representation; he even avoided that
variety which is not only permitted, but even required, in an epical
delivery—a slight change of tone when different persons speak, by
which what every one says is brought into relief, and the actor is
distinguished from the narrator. Without being monotonous, Herder
let everything go on in the same tone, just as if nothing was present
before him, but all was merely historical; as if the shadows of this
poetic creation did not act livingly before him, but only glided gently
by. Yet this manner of delivery from his mouth had an infinite charm;
for, as he felt all most deeply, and knew how to estimate the variety of
such a work, so the whole merit of a production appeared purely and
the more clearly, as one was not disturbed by details sharply spoken
out, nor interrupted in the feeling which the whole was meant to
produce.
A Protestant country clergyman is, perhaps, the most beautiful
subject for a modern idyl; he appears, like Melchizedek, as priest and
king in one person. To the most innocent situation which can be
imagined on earth, to that of a husbandman, he is, for the most part,
united by similarity of occupation, as well as by equality in family
relationships; he is a father, a master of a family, an agriculturist, and
thus perfectly a member of the community. On this pure, beautiful,
earthly foundation, rests his higher calling: to him is it given to guide
men through life, to take care of their spiritual education, to bless
them at all the leading epochs of their existence, to instruct, to
strengthen, to console them, and, if consolation is not sufficient for
the present, to call up and guarantee the hope of a happier future.
Imagine such a man, with pure human sentiments, strong enough not
to deviate from them under any circumstances, and by this already
elevated above the multitude, of whom one cannot expect purity and
firmness; give him the learning necessary for his office, as well as a
cheerful, equable activity, which is even passionate, as it neglects no
moment to do good,—and you will have him well endowed. But at the
same time add the necessary limitation, so that he must not only
pause in a small circle, but may also perchance pass over to a
smaller; grant him good-nature, placability, resolution, and everything
else praiseworthy that springs from a decided character, and over all
this a cheerful spirit of compliance, and a smiling toleration of his own
failings and those of others,—then you will have put together pretty
well the image of our excellent Wakefield.
The delineation of this character on his course of life through joys and
sorrows, the ever-increasing interest of the story, by the combination
of the entirely natural with the strange and the singular, make this
novel one of the best which has ever been written; besides this, it has
the great advantage that it is quite moral, nay, in a pure sense,
Christian—represents the reward of a good will and perseverance in
the right, strengthens an unconditional confidence in God, and attests
the final triumph of good over evil; and all this without a trace of cant
or pedantry. The author was preserved from both of these by an
elevation of mind that shows itself throughout in the form of irony, by
which this little work must appear to us as wise as it is amiable. The
author, Dr. Goldsmith, has without question great insight into the
moral world, into its strength and its infirmities; but at the same time
he can thankfully acknowledge that he is an Englishman, and reckon
highly the advantages which his country and his nation afford him.
The family, with the delineation of which he occupies himself, stands
upon one of the last steps of citizen comfort, and yet comes in
contact with the highest; its narrow circle, which becomes still more
contracted, touches upon the great world through the natural and civil
course of things; this little skiff floats on the agitated waves of English
life, and in weal or woe it has to expect injury or help from the vast
fleet which sails around it.
I may suppose that my readers know this work, and have it in
memory; whoever hears it named for the first time here, as well as he
who is induced to read it again, will thank me. For the former, I would
merely make the cursory remark, that the vicar's wife is of that good,
busy sort, who allows herself and her own to want for nothing, but
who is also somewhat vain of herself and her own. There are two
daughters,—Olivia, handsome and more devoted to the external, and
Sophia, charming and more given to the internal; nor will I omit to
mention an industrious son, Moses, who is somewhat blunt and
emulous of his father.
If Herder could be accused of any fault in his reading aloud, it was
impatience; he did not wait until the hearer had heard and
comprehended a certain part of the progress, so as to be able to feel
and think correctly about it; hurrying on, he would see their effect at
once, and yet he was displeased even with this when it manifested
itself. He blamed the excess of feeling which overflowed from me
more and more at every step. I felt like a man, like a young man;
everything was living, true, and present before me. He, considering
only the intrinsic contents and form, saw clearly, indeed, that I was
overpowered by the subject-matter, and this he would not allow. Then
Peglow's reflections, which were not of the most refined, were still
worse received; but he was especially angry at our want of keenness
in not seeing beforehand the contrasts of which the author often
makes use, and in suffering ourselves to be moved and carried away
by them without remarking the oft-returning artifice. He would not
pardon us for not seeing at once, or at least suspecting at the very
beginning, where Burchell is on the point of discovering himself by
passing over in his narration from the third to the first person, that he
himself is the lord of whom he is speaking; and when, finally, we
rejoiced like children at the discovery and the transformation of the
poor, needy wanderer, into a rich, powerful lord, he immediately
recalled the passage, which, according to the author's plan, we had
overlooked, and read us a powerful lecture on our stupidity. It wall be
seen from this that he regarded the work merely as a production of
art, and required the same of us, who were yet wandering in that
state where it is very allowable to let works of art affect us like
productions of nature.
I did not suffer myself to be at all perplexed by Herder's invectives;
for young people have the happiness or unhappiness, that, when once
anything has produced an effect on them, this effect must be wrought
out within themselves; from which much good, as well as much
mischief, arises. The above work had left with me a great impression,
for which I could not account, but properly speaking, I felt myself in
harmony with that ironical tone of mind which elevates itself above
every object, above fortune and misfortune, good and evil, death and
life, and thus attains to the possession of a truly poetical world. I
could not, indeed, become conscious of this until later; it was enough
that it gave me much to do at the moment; but I could by no means
have expected to be so soon transposed from this fictitious world into
a similar real one.
My fellow-boarder, Weyland, who enlivened his
quiet, laborious life by visiting from time to time his Pleasures of
Travelling
friends and relations in the country (for he was a Incognito.
native of Alsace), did me many services on my little
excursions, by introducing me to different localities and families,
sometimes in person, sometimes by recommendations. He had often
spoken to me about a country clergyman who lived near Drusenheim,
six leagues from Strasburg, in possession of a good benefice, with an
intelligent wife and a pair of amiable daughters. The hospitality and
agreeableness of this family were always highly extolled. It scarcely
needed so much to draw thither a young knight who had already
accustomed himself to spend all his leisure days and hours on
horseback and in the open air. We decided therefore upon this trip,
and my friend had to promise that on introducing me he would say
neither good nor ill of me, but would treat me with general
indifference, and would allow me to make my appearance clad, if not
meanly, yet somewhat poorly and negligently. He consented to this,
and promised himself some sport from it.
It is a pardonable whim in men of consequence, to place their exterior
advantages in concealment now and then, so as to allow their own
internal human nature to operate with the greater purity. For this
reason the incognito of princes, and the adventures resulting
therefrom, are always highly pleasing; these appear disguised
divinities, who can reckon at double its value all the good offices
shown to them as individuals, and are in such a position that they can
either make light of the disagreeable or avoid it. That Jupiter should
be well pleased in his incognito with Philemon and Baucis, and Henry
the Fourth with his peasants after a hunting party, is quite
conformable to nature, and we like it well; but that a young man
without importance or name, should take it into his head to derive
some pleasure from an incognito, might be construed by many as an
unpardonable piece of arrogance. Yet since the question here is not of
such views and actions, so far as they are praiseworthy or blameable,
but so far as they can manifest themselves and actually occur, we will
on this occasion, for the sake of our own amusement, pardon the
youngster his self-conceit; and the more so, as I must here allege,
that from youth upwards, a love for disguising myself had been
excited in me even by my stem father.
This time, too, partly by some cast-off clothes of my own, partly by
some borrowed garments and by the manner of combing my hair, I
had, if not disfigured myself, yet at least decked myself out so oddly,
that my friend could not help laughing on the way, especially as I
knew how to imitate perfectly the bearing and gestures of such
figures when they sit on horseback, and which are called "Latin
riders." The fine road, the most splendid weather, and the
neighbourhood of the Rhine, put us in the best humour. At
Drusenheim we stopped a moment, he to make himself spruce, and I
to rehearse my part, out of which I was afraid I should now and then
fall. The country here has the characteristics of all the open, level
Alsace. We rode on a pleasant foot-path over the meadows, soon
reached Sesenheim, left our horses at the tavern, and walked leisurely
towards the parsonage. "Do not be put out," said Weyland, showing
me the house from a distance, "because it looks like an old miserable
farm-house, it is so much the younger inside." We stepped into the
court-yard; the whole pleased me well: for it had exactly that which is
called picturesque, and which had so magically interested me in Dutch
art. The effect which time produces on all human work was strongly
perceptible. House, barn, and stable were just at that point of
dilapidation where, indecisive and doubtful between preserving and
rebuilding, one often neglects the one without being able to
accomplish the other.
As in the village, so in the court-yard, all was quiet
and deserted. We found the father, a little man, The Pastor's
Family.
wrapped up within himself, but friendly
notwithstanding, quite alone, for the family were in
the fields. He bade us welcome, and offered us some refreshment,
which we declined. My friend hurried away to look after the ladies,
and I remained alone with our host. "You are perhaps surprised," said
he, "to find me so miserably quartered in a wealthy village, and "with
a lucrative benefice; but," he continued, "this proceeds from
irresolution. Long since it has been promised me by the parish, and
even by those in higher places, that the house shall be rebuilt; many
plans have been already drawn, examined and altered, none of them
altogether rejected, and none carried into execution. This has lasted
so many years, that I scarcely know how to command my
impatience." I made him an answer such as I thought likely to cherish
his hopes, and to encourage him to pursue the affair more vigorously.
Upon this he proceeded to describe familiarly the personages on
whom such matters depended, and although he was no great
delineator of character, I could nevertheless easily comprehend how
the whole business must have been delayed. The confidential tone of
the man was something peculiar; he talked to me as if he had known
me for ten years, while there was nothing in his look from which I
could have suspected that he was directing any attention to me. At
last my friend came in with the mother. She seemed to look at me
with quite different eyes. Her countenance was regular, and the
expression of it intelligent; she must have been beautiful in her youth.
Her figure was tall and spare, but not more so than became her
years, and when seen from behind, she had yet quite a youthful and
pleasing appearance. The elder daughter then came bouncing in
Welcome to our website – the perfect destination for book lovers and
knowledge seekers. We believe that every book holds a new world,
offering opportunities for learning, discovery, and personal growth.
That’s why we are dedicated to bringing you a diverse collection of
books, ranging from classic literature and specialized publications to
self-development guides and children's books.

More than just a book-buying platform, we strive to be a bridge

connecting you with timeless cultural and intellectual values. With an
elegant, user-friendly interface and a smart search system, you can
quickly find the books that best suit your interests. Additionally,
our special promotions and home delivery services help you save time
and fully enjoy the joy of reading.

Join us on a journey of knowledge exploration, passion nurturing, and

personal growth every day!

ebookbell.com