# Libgpewidget API Documentation

This document is intended as a detailed reference for the gui functions avalible in libgpewidget.

Copyright 2003 Damien Tannner

## Application initilisation

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

Before any operations are done in your `main` function, you should first call `gpe_application_init`. This will set any locale varibles or such that are needed before any other libgpewidget functions are called. The `gtk_init` function is also called so there is no need for it to be called seperately.

## Icon loading

`gboolean gpe_load_icons (struct gpe_icon *);`

This function should be called after `gpe_application_init` to load the appropriate pixmaps needed for your application. Previously this function was also used to load pixmaps for GtkButtons, but recently `gpe_button_new_from_stock` has replaced this. So `gpe_load_icons` should only be used for loading specialty icons like window title icons.

The struct `gpe_icon` contains the data needed for gpe to be able to locate your icons. This structure should be defined out of your `main` function, prefferbly immediately after your `#include` calls.
An example of this structure is given below.

    struct gpe_icon my_icons[] = {
      { "pear", "/root/pear.png" },
      { "lemon", "my_lemon_image" },
      { "icon", PREFIX "/share/pixmaps/gpe-application.png" },
      {NULL, NULL}
    };

As shown above, for each entry in the structure there are two arguments. The first argument is a custom name for the icon, and the second isthe filename of the icon. This can be either just the name of the image file (excluding prefix) that is located in the PREFIX/share/gpe/pixmaps/default directory, or a full path to the filename.
It must also be noted that the structure must be end with a null entry.

To access these preloaded images in your code you should use the following function.

`GdkPixbuf *gpe_find_icon (const char *name);`

This function will attempt to locate the preloaded image called 'name' and return it as a GdkPixbuf. If the image cannot be found or has not been mentioned in the gpe_icon structure, a graphical error box will be shown describing the error and terminating the application after its acknolagment.
If a graphical error is unallowed or the application needs to stay alive in the event of an error (such as in a library), `gpe_find_icon`'s sister function `gpe_try_find_icon` can be used instead. Its prototype is shown below.

`GdkPixbuf *gpe_try_find_icon (const char *name, gchar **error);`

## Window titlebar icons

`gpe_set_window_icon (GtkWidget *window, gchar *icon);`

The above function is used to set the small icon displayed in an applications window manager title bar, although it's only shown if the current window manager's theme specifies.
When calling this function the `icon` argument should be the name of a preloaded image (an example of this was shown in the section named 'Icon loading').

## Stock button

Stock buttons are a standard set of commonly used buttons defined in GTK+. They're used mainly as a convenience instead of having to pack buttons manualy, but on cross platform enviorments they can come in alot more use. Libgpewidget contains its own function built apon `gtk_button_new_from_stock` for creating stock button, which will also resize and align the buttons appropriately for smaller screens. This function is aptly named `gpe_button_new_from_stock`.

`GtkWidget *gpe_button_new_from_stock (const gchar *stock_id, int type);`

When calling `gpe_button_new_from_stock`, `stock_id` should be the name of a gtk stock type e.g. `GTK_STOCK_NEW`, and `type` is the type of button to construct. There are three different types of gpe stock buttons

`GPE_BUTTON_TYPE_ICON` |
`GPE_BUTTON_TYPE_LABEL` |
`GPE_BUTTON_TYPE_BOTH` |

## Toolbars

In GPE, toolbars should be an important part of every application. For users they offer quick and simple access to commonly used functions. Most standard GPE applications should only need one toolbar for the main window. Authough other more complicated applications may require more than one toolbar or possibly even a menubar.
All GPE applications should try to follow the precedure defined in the example below. This ensures that the applications have a similar look and feel that benifits the user.

    toolbar = gtk_toolbar_new ();
    gtk_toolbar_set_orientation (GTK_TOOLBAR (toolbar), GTK_ORIENTATION_HORIZONTAL);
    gtk_toolbar_set_style (GTK_TOOLBAR (toolbar), GTK_TOOLBAR_ICONS);

      toolbar_icon = gtk_image_new_from_stock (GTK_STOCK_NEW, GTK_ICON_SIZE_SMALL_TOOLBAR);
      gtk_toolbar_append_item (GTK_TOOLBAR (toolbar), _("New"), _("New document"), _("New document"), toolbar_icon, new_file, NULL);

      toolbar_icon = gtk_image_new_from_stock (GTK_STOCK_OPEN, GTK_ICON_SIZE_SMALL_TOOLBAR);
      gtk_toolbar_append_item (GTK_TOOLBAR (toolbar), _("Open"), _("Open file"), _("Open file"), toolbar_icon, select_open_file, NULL);

      toolbar_icon = gtk_image_new_from_stock (GTK_STOCK_SAVE, GTK_ICON_SIZE_SMALL_TOOLBAR);
      gtk_toolbar_append_item (GTK_TOOLBAR (toolbar), _("Save"), _("Save current file"), _("Save current file"), toolbar_icon, save_file, NULL);

## Application help interface

Libgpewidget provides a simple interface to access help information from applications. It is intended to be used for providing full text help and background information in more complex applications. The help information is stored in a defined location and uses a defined file format that is opened by an external application.
Current implementation uses help information that is stored HTML files. The location in filesystem is $PREFIX/share/doc/gpe. The default prefix in GPE is "/usr".

The help interface consists of only one call:

    gboolean gpe_show_help(const char* book, const char* topic)

Return value is FALSE if help is found and displayed, TRUE if an error occurs. The parameters "book" and "topic" are used to specify the help source and location of the topic in the source. Current implementation in libgpewidget will create an URL if this type:

    file:///$PREFIX/share/doc/gpe/<book>.html#<topic>

This URL is opened with a known help viewer. Currently this defaults to dillo HTML browser, but this may change in future.