Gtk+ Programming in C

Description

The more popular Linux becomes, the more developers want to build graphical applications that run in Linux/Unix environments -- and Gtk+ 1.2 offers a powerful toolset for doing so. In this start-to-finish tutorial and reference, respected Linux/Unix developer Syd Logan covers everything programmers need to begin building powerful graphical applications with Gtk+ 1.2 immediately. Logan begins by reviewing the fundamentals of Linux/Unix programming with C; then walks through constructing a simple Gtk+ application. Next, he introduces each key category of Gtk+ widget, including base widgets; menu and layout widgets; range, scrollbar, and scale widgets; container widgets; and text widgets. The book also includes detailed coverage of creating and using dialogs, and writing new widgets, as well as expert introductions to GLIB and GDK.

Sample Content

Table of Contents

Introduction.


1. Gtk+ in Context.

The X Window System. Architecture of X. The X Protocol. The X Server. The Client (Xlib). Toolkits. Window Managers. Desktop Environments. CDE. GNOME. KDE. Summary.

Beginnings. A Simple Example: Hello Gtk+! Adding Interactive Features to a Console Application. A Paradigm Shift. Understanding the Gtk+ Hello World Sample. Building the Sample Client. Debugging the Sample Client. Application Startup, Termination, and Main Loop Functions. Application Startup. Modules. Debug Arguments. Compile Time. Runtime. Application Termination. Gtk+ Main Loop Functions. Terminating the Main Loop. Controlling the Main Loop. Checking for Pending Events. Init and Quit Functions. Destroying Objects When a Main Loop Exits. Timeouts and Idle Processing. Adding a Timeout. Removing a Timeout. Timeout Example. Timeout Precision. Idle Functions. Adding an Idle Function. Idle Function Priorities. Destroying Idle Functions. Snooping Key Presses. Summary.

Signals. An Example: GtkButton Signals. Handling Signals. Client Callback Data Example. Events. Event Callback Function Prototypes. Event Types. GdkEventExpose. GdkEventNoExpose. GdkEventVisibility. GdkEventMotion. GdkEventButton. GdkEventKey. GdkEventCrossing. GdkEventFocus. GdkEventConfigure. GdkEventProperty. GdkEventSelection. Selection Protocol. GdkEventClient. GdkEventAny. Signal and Event APIs. Signal Lookup. Emitting Signals. Emitting Signals:An Example. Analysis of the Sample. Controlling Signals. Objects. Button Widgets as Objects. Object API. Object Attributes. Getting and Setting Object Attributes. Associating Client Data with an Object or Widget. When to Use Client Data. Types. Summary.

Why Widgets? Simplifying User Interface Development. API Simplification. Abstraction. Simplification for Users. GtkWidget. Class Name. Parent Class Name. Macros. Miscellaneous Macros. Signal Function Prototypes. Supported Arguments. Application-Level API Synopsis. Class Description. Widget Creation. Widget Reference Counts. Destroying Widgets. Manipulating Widget Arguments. Realizing, Mapping, and Drawing Widgets. Showing Widgets. Hiding Widgets. Accelerators and Mnemonics. Accelerator Groups. Event-Related Functions. Activating a Widget. Reparenting a Widget. Showing a Widget at a Specific Location. Computing the Intersection of a Widget and an Area. Grabbing Focus. Specifying Widget Sensitivity. Setting the Position and Size of a Widget. Top-Level and Ancestor Widgets, and Transient Windows. Querying the Pointer Position. Colormap and Visual Functions. Styles. Gtk+ Style System Details. Stacking Styles, Visuals, and Colormaps. Style, Colormap, and Visual Defaults. Summary.

Controls and Containers. GtkLabel. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating a Label Widget. Setting and Retrieving Label Text. Label Attributes. Placing Underscores in the Label. Buttons. GtkButton. Class Name. Parent Class Name. Macros. Signal Function Prototypes. Supported Arguments. Application-Level API Synopsis. Class Description. Signals. Creating a Button. Changing the Label Text. Generating Synthetic Events. Relief Styles. GtkToggleButton. Class Name. Parent Class Name. Macros. Signal Function Prototypes. Supported Arguments. Application-Level API Synopsis. Class Description. Signals. Creating Toggle Buttons. Getting and Setting the State of a Toggle Button. Miscellaneous Functions. GtkCheckButton. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Check Button. GtkRadioButton. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating a Radio-Button Widget. Summary.

GtkList. Class Name. Parent Class Name. Macros. Signal Function Prototypes. Application-Level API Synopsis. Class Description. Selection Modes. Creating a List. Setting the Selection Mode. Adding Items to the List. Displaying Arbitrary Widget Content in a List. Removing Items from a List. Locating an Item in a List. Selecting and Unselecting Items in a List. GtkCList. Class Name. Parent Class Name. Macros. Signal Function Prototypes. Supported Arguments. Application-Level API Synopsis. Class Description. A Sample. Creating a Clist Widget. Adding and Removing Content from a Clist. Getting and Setting Row Data. Displaying Pixmaps. GDK Pixmaps. GtkCList Pixmap Functions. Setting the Shadow Type. Selection Modes. Button Actions. Making a Clist Reorderable. Freezing and Thawing a Clist. Column API. Row and Cell API. Cell Styles. Associating Client Data with a Row. Selection Functions. Moving and Sorting Rows. Scrollbars. Summary.

GtkWindow. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Supported Arguments. Application-Level API Synopsis. Class Description. Creating a Window Widget. Window Types. Setting the Window Title. Setting the Window Position. Setting the Class of the Window. Setting Policy Hints. Making a Window Transient. Setting Geometry Hints. Setting the Default Size of a Window. Modal Windows. Window Focus. The Focus Widget. Default Widgets. GtkDialog. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Dialog. Dialog Sizing. GtkFileSelection. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating an Instance of GtkFileSelection. Modifying the File-Selection Widget. Showing and Hiding the Fileop Buttons. Responding to OK and Cancel Buttons. Adding Arbitrary Widget Content to a File-Selection Widget. GtkFontSelection. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Font-Selection Widget User Interface. Creating a Font-Selection Widget. Modifying the Font-Selection Widget. Setting The Filter. Setting and Retrieving the Preview Text. Initializing the Font Name. Retrieving the Font Selected by the User. GtkFontSelectionDialog. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating an Instance of GtkFontSelectionDialog. GtkColorSelectionDialog. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Color-Selection Dialog. Example. GtkColorSelection. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Supported Arguments. Application-Level API Synopsis. Class Description. Creating a Color-Selection Widget. Color-Selection Widget Attributes. What Is Opacity? Setting and Retrieving Colors. Summary.

Separators. GtkSeparator. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkHSeparator. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkVSeparator. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkArrow. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Arrow and Shadow Types. Creating an Arrow Widget. Setting Arrow Attributes. Images and Pixmaps. GtkPixmap. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Pixmap Widget. Setting and Getting the Pixmap Data. GtkPixmap Example. Insensitive Pixmaps. GtkImage. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Imaging in GDK. An Example Using libtiff. Creating an Image with GDK. Setting the Image Data. Reading a Pixel Value from an Image. Destroying an Image. Retrieving Image Data from a Window. Creating the GtkImage Widget. Modifying the Image. Retrieving the Image Data and Clip Mask. GtkEntry. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating an Entry Widget. Setting and Getting the Value of the Text Buffer. Changing the Attributes of an Entry Widget. Changing the Editable Attribute of an Edit Widget. Setting the Position of the Caret. Simplifying Entry Widget Creation. Selecting Text. Summary.

GtkItemFactory. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating an Item Factory. Menus. Menu Items. Check Menu Items. Radio Menu Items. Separators. Tearoff Menus. Creating the Application Menu Bar and Menus. Creating the Item Factory. Adding Menu Items to the Item Factory. Retrieving the Item Factory Widget. Retrieving the Widget Corresponding to an Item in the Menu. Retrieving an Item Factory and Path from a Widget. Retrieving Widgets Based on Action. Deleting Items from an Item Factory. Pop-up Menus. Pop-up Data. Using Pop-up Menu Data. Option Menus. Translating Menu Paths. GtkMenuBar. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating a Menu Bar. Adding Menu Items to the Menu Bar. Setting the Shadow Type. GtkMenuItem. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Application-Level API Synopsis. Class Description. Creating a Menu Item. Submenus. Right-Justifying Menu Items. Selecting and Unselecting Menu Items. An Example. Creating the Menu Bar and Attaching the Accelerator Group. Creating the Menus. Adding Menu Items. Associating the Menu with Its Menu Item. Check Menu Items and Radio Menu Items. GtkCheckMenuItem. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Application-Level API Synopsis. Class Description. Creating Check Menu Items. Using Check Menu Items. Setting the State of a Check Menu Item. GtkRadioMenuItem. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Radio Menu Item. Retrieving a Radio Button's Radio Group. An Example. Setting the Radio Group of a Radio Menu Item. GtkTearoffMenuItem. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Using a Tearoff Menu. Creating a Tearoff Menu. GtkMenu. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Menu. Adding Menu Items. Popping Up a Menu. An Example. Popping Down a Pop-up Menu. Getting and Setting the Active Menu Item in a Menu. Accelerator Groups. GtkOptionMenu. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating an Option Menu. Setting and Getting the Menu. Initializing the Option Menu Selection. Summary.

GtkContainer. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Supported Arguments. Application-Level API Synopsis. Class Description. Setting the Border Widget of a Container. Adding and Removing Children. Iterating a Container's Children. Retrieving a List of a Container's Children. Changing Focus. GtkFixed. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating an Instance of GtkFixed. Adding a Child Widget. Moving a Child Widget. An Example. GtkBox. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Box Creation. Box Placement. Box Nesting. Widget Placement. Packing Options. Homogeneous, Spacing, Expand, Fill, and Padding Attributes. Homogeneous. Spacing. Expand. Fill. Padding. Packing Boxes. Making a Box Homogeneous. Setting the Spacing. Repositioning Children. Setting and Getting Packing Attributes. GtkVBox. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkHBox. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkButtonBox. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Setting and Getting the Layout Style. Setting and Getting the Default Child Size. Getting and Setting the Current Child Size Minimums. Setting and Getting the Child Internal Padding Values. Setting and Getting the Interchild Spacing. GtkVButtonBox. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Vertical Button Box. Getting and Setting the Interchild Spacing. Setting and Getting the Layout Style. GtkHButtonBox. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Horizontal Button Box. Getting and Setting Interchild Spacing. Getting and Setting the Default Layout Style. GtkNotebook. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Supported Arguments. Application-Level API Synopsis. Class Description. Creating an Instance of GtkNotebook. Creating and Adding Pages. Creating and Adding Pages to a Notebook: An Example. Implementing a Pop-up menu. Removing a Page from a Notebook. Reordering the Notebook Pages. Page Functions. Traversing Pages. Preference Functions. Analysis of Listing 10.4. Setting the Orientation of the Tabs. Scrollable Tabs. Miscellaneous Tab Attributes. Tab Labels. Pop-up Menu Functions. Tab Label Packing Functions. Summary.

GtkPaned. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating an Instance of GtkPaned. Adding Children with Default Resize and Shrink Attributes. Controlling the Resize and Shrink Attributes. Miscellaneous Functions. GtkVPaned. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkHPaned. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkPacker. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating a Packer Widget. Adding Children to a Packer. Examples. Nesting Packers. Fill X and Fill Y. Expand Option. Anchoring. Border Width and Padding. Reordering Children. GtkFrame. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating a Frame Widget. An Example. Setting the Frame Label. Setting the Alignment of the Label. Setting the Shadow Type of the Frame. GtkAspectFrame. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating an Aspect Frame Widget. Setting the Aspect Frame Attributes. GtkTable. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Cell Attributes. Cell Coordinates and Adding Children. Creating a Table Widget. Resizing the Table. Changing the Homogeneous Setting. Adding Cells to a Table. Adding a Table Cell with Defaults. Setting Row and Column Spacings. An Example: Tic-Tac-Toe Board. GtkToolbar. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Application-Level API Synopsis. Class Description. Creating a Toolbar. Adding Toolbar Children. An Example. Button Spacings. Adding Children of Arbitrary Type. Convenience Functions. Setting the Toolbar Orientation. Setting the Toolbar Style. Enabling and Disabling Tooltips. Setting and Getting the Button Relief Attribute. GtkHandleBox. Class Name. Parent Class Name. Macros. Supported Signals. Application-Level API Synopsis. Class Description. Creating a Handle-Box Widget. Setting the Shadow Type. Setting the Handle Location. Setting the Snap Edge. GtkEventBox. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating an Event Box Widget. GtkScrolledWindow. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating a Scrolled Window. Adding a Child to a Scrolled Window. Setting and Getting the Horizontal and Vertical Adjustment Objects. Overriding the Default Adjustment Objects: An Example. Setting the Scrolling Policy. Controlling Scrollbar Placement. GtkLayout. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Layout Widget. Adding a Child Widget. Repositioning a Child Widget. Setting the Size of the Layout Virtual Area. Adjustments. Handling Expose Events. Setting and Getting the Layout Adjustment Objects. Layout Widgets: A Final Example. Summary.

Why Use Trees? Using GtkTree and GtkTreeItem. An Example. GtkTree. Class Name. Parent Class Name. Macros. Miscellaneous Macros. Supported Signals. Signal Function Prototypes. Application-Level API Synopsis. Class Description. Creating an Instance of GtkTree. Adding Items. Removing Items from a Tree. Removing Items Based on Position. Selecting Items. View Modes. GtkTreeItem. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Application-Level API Synopsis. Class Description. Creating a Tree Item Widget. Subtrees. Tree Operations. Selecting and Deselecting Tree Items. Expanding and Collapsing Tree Items. GtkCTree. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Supported Arguments. Application-Level API Synopsis. Class Description. A First Example. Creating a GtkCTree Instance. Inserting Nodes. Analyzing the Sample Code. A Second Example. Displaying the Contents of a Directory. Removing Nodes from a Tree. Setting the Indentation. Setting the Spacing. Setting the Line Style of a CTree. Setting the Expander Style. Sorting Functions. Recursive Functions. Passing Client Data to a Traversal Function. Querying Tree and Node Attributes. Attaching and Retrieving Client Data. Searching for Nodes Based on Client Data. Performing Custom Searches. Moving, Expanding, Collapsing, and Selecting Rows. Moving a Node. Expanding a Node. Collapsing a Node. Retrieving the State of a Node. Recursively Expanding and Collapsing Nodes. Using the Keyboard to Collapse and Expand a Tree. Selecting and Unselecting Nodes. Miscellaneous Functions. Checking Whether a Coordinate Is in the Expander Box. Setting and Getting the Text Displayed in a Column. Setting and Getting Pixmap Data. Retrieving and Modifying Node Attributes. Setting a Column Offset. Getting and Setting the Selectable Attribute of a Node. Determining the Type of a Cell. Setting and Getting Style Objects. Setting Foreground and Background Colors. Determining Whether a Node Is Visible. Scrolling a CTree to Make a Specific Node Visible. Summary.

Scale Widgets. GtkHScale. Class Name Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. GtkVScale. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. GtkScale. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Setting the Number of Significant Digits. Showing and Hiding the Scale Value. Setting the Value Label Position. Miscellaneous Scale Widget Functions. An Example. Scrollbars. GtkHScrollbar. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkVScrollbar. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkScrollbar. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Adjustment Objects. Implementation of Adjustment Objects. GtkAdjustment. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Application-Level API Synopsis. Class Description. Creating an Adjustment Object. Changing Adjustment Object Attributes. Working with Adjustment Objects. GtkRange. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Setting the Update Policy of a Range Widget. Setting the Range Widget Adjustment Object. Summary.

GtkText. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Scrolling Text. Creating a Text Widget. Changing the Adjustment Objects. Making a Text Widget Editable or Read-Only. Word Wrap. Text Widget Buffer Manipulation. The Insertion Point. Setting and Getting the Insertion Point. Getting the Length of the Text Buffer. Inserting and Deleting Text. Deleting Text. Freezing and Thawing the Text Widget. Retrieving Text. GtkSpinButton. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Keyboard and Mouse Events. Creating a Spin Button Widget. Understanding the Climb Rate. Configuring the Spin Button Widget. Setting and Getting the Adjustment Object. Setting the Number of Significant Digits Displayed by a Spin Button. Setting and Getting the Value of a Spin Button. Changing the Spin Button Update Policy. Using Numeric Mode. Setting the Value of a Spin Button. Controlling the Wrapping of Values. Setting the Shadow Type. The Snap-to-Ticks Attribute. Causing the Spin Button to Redraw. An Example. Analysis. Handling Images. Creating the Spin Button Controls. Implementing the value_changed Signal Function. Implementing the Next and Previous Buttons. Implementing the Slide Show. Summary.

GtkRuler. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Setting the Ruler Metric. Setting the Range of a Ruler. Tracking Mouse Movement. Sample Code. GtkHRuler. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. GtkPreview. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating a Preview Widget. Setting the Image Size. Setting the Expand Attribute. Setting the Image Data. Drawing the Image Data. Miscellaneous GtkPreview Functions. Setting the Dither Preference. Setting the Gamma. Retrieving Global Information About Preview Widgets. GtkProgress. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Initialization. Text. Value and Percentage. Activity Mode. GtkProgressBar. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating Progress Bar Widgets. Setting the Progress Bar Style. Controlling the Speed of an Activity Progress Bar. Setting the Bar Size of an Activity Progress Bar. Setting the Progress Bar Orientation. Sample Program. GtkTooltips. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Using Tooltips. Displaying Context-Sensitive Help. Display Application Data. Tooltips Widgets. Creating a Tooltips Widget. Setting the Widget-to-Tooltip Mapping. Enabling and Disabling Tooltips. Setting the Tooltips Delay. Changing the Foreground and Background Colors. GtkTipsQuery. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating an Instance of GtkTipsQuery. The widget_selected Signal. Handling the widget_entered Signal. Placing a Widget into Query Mode. An Example Using GtkTipsQuery. Leaving Query Mode. Setting the Text Displayed by Widgets Without Tooltips. GtkCombo. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Combo Box Widget. Setting the Combo Box Content. An Example. Enabling and Disabling Use of Arrow Keys. Forcing Users to Match the Pop-up List Contents During Data Entry. Disabling the Combo Widget Activate Function. GtkStatusbar. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Application-Level API Synopsis. Class Description. Creating a Statusbar Widget. Pushing a Status Message onto the Stack. Handling the text_pushed Signal. Getting a Context ID. Popping an Item from the Stack. Substacks. Handling the text_popped Signal. Removing an Arbitrary Item from the Stack. Final Thoughts. GtkAccelLabel. Class Name. Parent Class Name. Macros. Supported Arguments. Application-Level API Synopsis. Class Description. Creating an Accel Label Widget. Retrieving the Width of an Accel Label Widget. Mapping an Accel Label Widget to the Widget It Supports. GtkDrawingArea. Class Name. Parent Class Name. Macros. Application-Level API Synopsis. Class Description. Creating a Drawing Area Widget. Setting the Drawing Area Widget Size. Using the Drawing Area Widget. Analysis. GtkCalendar. Class Name. Parent Class Name. Macros. Supported Signals. Signal Function Prototypes. Application-Level API Synopsis. Class Description. Creating a Calendar Widget. Setting and Retrieving the Date Displayed by the Calendar. Marking Days. Setting Display Options. Freezing and Thawing the Calendar Display. Example Program. Summary.

Preface

Introduction

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.org/~sjburges/gimp-history.html

This book covers the 1.2 version of 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 10, "Container and Bin 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+ application. 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 10. 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 commonly used. GtkBox, GtkHBox, and GtkVBox are all described in Chapter 10 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 limited) 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.com/crash/s/slogan/gtkbook.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 function 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 programmers 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 GtkWidget 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+/Gnome 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.

I plan to make the source code for this book available online. Please go to www.users.cts.com/crash/s/slogan/gtkbook.html for further details.

By purchasing this book, you have decided to develop an application for Linux/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 targeting 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.

Updates

Submit Errata