libgpewidget

libgpewidget contains a collection of widgets and other common code shared by many GPE applications.

Features

GPE-specific widgets:

• GtkDateCombo: a date entry field with a pop-up calendar
• GtkDateSel: a date selector
• GtkMiniFileSel: a replacement for GtkFileSelection
• GtkGpePixmap: a prelight-aware replacement for GtkPixmap

Gtk widget overrides:

• GtkEntry: enforces smaller minimum width
• GtkDialog: sets "transient_for" property on window
• GtkTooltips: tips suppressed when in "stylus" mode

Miscellaneous

• Common application initialisation
• Icon handling; pixmap loading and alpha blending
• Client-side modal help support (see gpe-what)
• Overrides gdk_screen_width to look at the size of the root window rather than using DisplayWidth; similarly for gdk_screen_height. (This improves behaviour in the presence of rotation.)
• gpe_stylus_mode: is this a pen-based display?
• Common dialog handling
• Text-and-picture buttons in dialog boxes
• XMMS-style directory browser
• Conceals X cursor when stylus mode is selected.

Using libgpewidget

Add -lgpewidget to your final link command line. You should put libgpewidget before any other Gtk-related libraries in the link order, to ensure that its widget overrides work correctly.

Gtk-based programs should consider calling at least gpe_application_init even if they don't plan to use any other library features.

Application startup

#include <gpe/init.h>

extern gboolean gpe_application_init (int *argc, char **argv[]);

gpe_application_init is a direct replacement for gtk_init. It calls gtk_init, gtk_set_locale, creates the ~/.gpe directory, and initialises any internal modules as required.

gpe_application_init returns TRUE if initialisation was successful.

This function should be called before using any other routines from libgpewidget.

Icon handling

#include <gpe/pixmaps.h>

struct gpe_icon
{
  const char *shortname;
  const char *filename;
};

extern gboolean gpe_load_icons (struct gpe_icon *);
extern GdkPixbuf *gpe_find_icon (const char *name);
extern gboolean gpe_find_icon_pixmap (const char *name,
				      GdkPixmap **pixmap,
				      GdkBitmap **bitmap);

libgpewidget provides common routines to handle application icons. Each application should define an array of struct gpe_icon listing all the icons that are required for operation.

In the commonest case, only the shortname needs to be provided. This is the string that you will later pass to gpe_find_icon to retrieve the image data; libgpewidget will search for a file named shortname.png, first in ~/.gpe/pixmaps and then in PREFIX/share/gpe/pixmaps/default.

If the filename is specified, and does not begin with a slash character, libgpewidget searches for filename.png in the same directories described above. If filename does start with a slash character, libgpewidget interprets it as an absolute pathname and a verbatim file name, looks only at the specified location and does not append the .png extension.

gpe_load_icons returns TRUE if all the icons were loaded successfully. Missing icons or other problems will result in error boxes being displayed to the user.

To retrieve image data, call gpe_find_icon or gpe_find_icon_pixmap. The latter returns a GdkPixmap/GdkBitmap pair containing the image data and mask. If the image has an alpha channel wider than a single bit, you will probably obtain better results by using gpe_find_icon and performing alpha blending.

gpe_find_icon returns NULL if the icon could not be located. gpe_find_icon_pixmap returns TRUE on success and FALSE on failure.

Alpha-blended buttons

#include <gpe/render.h>

extern GtkWidget *gpe_render_icon(GtkStyle *style, GdkPixbuf *pixbuf);

gpe_render_icon alpha-blends a pixbuf onto a background given by a GtkStyle, and returns the result as a GtkGpePixmap widget.

Pictorial buttons in dialog boxes

#include <gpe/picturebutton.h>

extern GtkWidget *gpe_picture_button (GtkStyle *style, 
				      gchar *text, gchar *icon);

gpe_picture_button is a convenience function for creating dialog box buttons. It returns a GtkButton widget containing an icon and a short text label. The icon is specified by name, as with gpe_find_icon.