This document is intended as a detailed reference for the gui functions avalible in libgpewidget.
Copyright 2003 Damien Tannner
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.
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);
|
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 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 |
 |
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);
|
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/This URL is opened with a known help viewer. Currently this defaults to dillo HTML browser, but this may change in future..html#