The Official GNOME 2 Developers Guide
Authors: Warkus M.
Published year: 2004
Pages: 12-18/108

<< Previous page
Table of contents
Next page >>

Functions and Macros

Remember that you can only call a function. A macro application often looks very similar to a function call, but it is an expansion that takes place before the compiler converts the source into object code. However, in most APIs, it isn't often clear which elements are functions and which are macros, so this text doesn't draw a strict line between the two.

Counting

In C, indices for arrays and fields start at 0. To avoid errors, this book carries this convention to other areas, but especially to lists. One notable example is GLib's list element indexing.

Pathnames

The system for pathnames in this book follows the automake rules. The name $(prefix) refers to the installation prefix for your GNOME installation (for example, /usr or /opt/gnome2 ).

Pointers and Addresses

GTK+ and GNOME use pointers to pointers extensively. This book sometimes refers to a pointer to a pointer as the address of a pointer, because you normally use parameters such as & ptr , where ptr is a pointer.

Chapter 1: GLib

1.1 Introduction

The letter G is ubiquitous in the world of open -source software; it stands for GNU (Richard Stallman's "GNU's Not Unix"). You'll see it throughout this book in names like GTK+, GLib, GObject, and GNOME, as well as in many other software packages such as Ghostscript and gcc.

To understand the later chapters in this book, you need to learn about a fundamental library called GLib ( libglib-2.0 ). It provides basic data structures and utility functions for the GTK+ widget set and GNOME applications in general. This chapter deals with GLib's architecture and introduces the API. You'll see GLib's object system (GObject) in Chapter 2.

You can't really avoid GLib when using GNOME and GTK+. Other libraries such as ORBit use GLib, and many don't depend on any other libraries. The abstractions and utilities that GLib provides are handy for nearly any programming task and simplify ports to other platforms.

This chapter contains no graphical code. It is a concise , point-by-point guide to the most important GLib functions and data structures. You may find this material a bit dry, so you can go directly to Chapter 3 to get started with GTK+. However, you may find yourself regularly looking back to these first two chapters for reference.

1.2 GLib Naming Conventions

As with many other libraries, GLib has naming rules for consistency and readability:

Function names are always in lowercase, with an underscore between each part of the name : g_timer_new() , g_list_append() . In addition, all function names begin with g_ .
All functions in a library start with a common prefix. In GLib, this prefix is g_ .
Type names contain no underscores, and each component inside starts with a capital letter: GTimer , GList . The names start with G . The notable exceptions to these rules are the elementary types in Section 1.3.
If a function operates primarily on a certain type, the prefix of this function corresponds to the type name. For example, the g_timer_* functions work with the GTimer type, and g_list_* functions go with GList .

It sounds more complicated than it is.

1.3 Basic Types

To get started with GLib, you should adjust to its elementary types. You might wonder why it is important to use guchar instead of unsigned char . There aren't any real differences as long as you stay on the same platform. However, if you decide that you want to import, export, and interface your software between, say, Windows and Unix, then you'll be thankful that GLib can abstract the basic data types for you.

For example, if you want to do something unpleasant such as define an unsigned integer variable that is exactly 16 bits wide on any potential platform, things can start to look a little ugly in C. Fortunately, GLib takes care of this so that you don't have to get your hands too dirty. The basic types are listed in the table on the opposite page.

To use GLib and all of its types, include the glib.h header file in your source code:

#include <glib.h>

The gpointer and gconstpointer types appear frequently when interacting with the GLib data structures, because they are untyped pointers to memory. In GLib, functions that use these pointers take responsibility for verifying the type, not the programmer or the compiler. These can be especially handy for type abstraction in callback functions and equality operators used in sorting and iteration.

The GLib header file defines the constants TRUE and FALSE for the gboolean type. However, it's bad style to use equivalence operators with these constants; that is, use if (my_gboolean) , not if (my_gboolean == TRUE) .

GLib Type	Corresponding Type in C
gchar	char
ugchar	unsigned char
gint	int
guint	unsigned int
gshort	short
gushort	unsigned short
glong	long
gulong	unsigned long
gfloat	float
gdouble	double
gint8	int , 8 bits wide
guint8	unsigned int , 8 bits wide
gint16	int , 16 bits wide
guint16	unsigned int , 16 bits wide
gint32	int , 32 bits wide
guint32	unsigned int , 32 bits wide
gint64	int , 64 bits wide
guint64	unsigned int , 64 bits wide
gpointer	void * , untyped pointer
gconstpointer	const void * , constant untyped pointer
gboolean	Boolean value, either TRUE or FALSE