## 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`.