Sections

Synopsis - Library calls
Description
Sturctures
Base
Background handling
Image loading
Right button menu
Text handling
Event hooks and time outs
Misc functions
Drawing
Saving and loading of settings

Synopsis - Library calls



#include <gai/gai.h>

int            gai_init                            (const char *name, 
                                                    const char *version, 
                                                    const char *image_path, 
                                                    int *argc, 
                                                    char ***argv);
int            gai_init2                           (GaiApplet* applet_info, 
                                                    int *argc, 
                                                    char ***argv);
void           gai_start                           (void);
void           gai_background_set                  (int width, 
                                                    int height, 
                                                    int max_size, 
                                                    int border);
void           gai_background_from_xpm             (const char **xpmimagename,
                                                    int max_size);
void           gai_background_from_gdkpixbuf       (GdkPixbuf* pixbuf, 
                                                    int max_size);
void           gai_background_from_file            (const char *image_file, 
                                                    int max_size);
GdkPixbuf*     gai_load_image                      (char *imagefilename);
void           gai_menu_add_help_text              (const char *msg);
void           gai_menu_add                        (const char *name, 
                                                    const char *icon, 
                                                    int type, 
                                                    void *func, 
                                                    void *ptr);
GdkPixbuf*     gai_text_create                     (char *msg,
                                                    char *font, 
                                                    int font_size, 
                                                    int feature, 
                                                    char red, 
                                                    char green, 
                                                    char blue);

void           gai_signal_on_update                (GaiCallback0 func, 
                                                    int delay, 
                                                    gpointer userdata);
void           gai_signal_on_update_interval_change(int delay);
void           gai_signal_on_exit                  (GaiCallback0 func, 
                                                    gpointer userdata);
void           gai_signal_on_enter                 (GaiCallback0 func, 
                                                    gpointer userdata);
void           gai_signal_on_leave                 (GaiCallback0 func, 
                                                    gpointer userdata);
void           gai_signal_on_keypress              (GaiCallback1 func,
                                                    gpointer userdata);
void           gai_signal_on_mouse_button_click    (GaiCallback2 func, 
                                                    int button, 
                                                    gpointer userdata);
void           gai_signal_on_mouse_button_release  (GaiCallback2 func,
                                                    int button, 
                                                    gpointer userdata);
void           gai_signal_on_scroll_buttons        (GaiCallback1 func, 
                                                    gpointer userdata);
void           gai_signal_on_change                (GaiCallback3 func, 
                                                    gpointer userdata);
void           gai_signal_on_preferences           (GaiCallback0 func,
                                                    gpointer userdata);
void           gai_signal_on_joystick              (GaiCallback1 func,
                                                    gpointer userdata);
void           gai_about_from                      (const char *text);
void           gai_preferences                     (const char *name,
                                                    GaiNoteBook *pref_tree, 
                                                    const char *help_text,
                                                    GaiCallback0 func, 
                                                    gpointer userdata);
void           gai_preferences2                    (const char *name,
                                                    GaiPI *pref_struct, 
                                                    const char *help_text,
                                                    GaiCallback0 func, 
                                                    gpointer userdata);

void           gai_gl_init_func                    (GaiCallback0 function);
void           gai_flags_set                       (GaiFlagsType flags);
GaiFlagsType   gai_flags_get                       (void);
GdkWindow*     gai_get_window                      (void);
GtkWidget*     gai_get_drawingarea                 (void);
GdkGC*         gai_get_gc                          (void);
int            gai_get_size                        (void);
int            gai_scale                           (int size);
int            gai_get_orient                      (void);
void           gai_tooltip_set                     (const char *msg);
void           gai_tooltip_remove                  (void);
void           gai_exec                            (const char *prg);
void           gai_display_error_quit              (const char *msg);
void           gai_display_error_continue          (const char *msg);
void           gai_draw                            (GdkPixbuf *image, 
                                                    int sx, 
                                                    int sy, 
                                                    int sw, 
                                                    int sh, 
                                                    int dx, 
                                                    int dy);
void           gai_draw_raw                        (unsigned char *rawRGB, 
                                                    int x,  
                                                    int y, 
                                                    int width, 
                                                    int height, 
                                                    int rowstride);
void           gai_draw_raw_alpha                  (unsigned char *rawRGBA,
                                                    int x, 
                                                    int y, 
                                                    int width, 
                                                    int height, 
                                                    int rowstride);
void           gai_draw_update                     (void);
void           gai_draw_bg                         (GdkPixbuf *image, 
                                                    int sx, 
                                                    int sy, 
                                                    int sw,
                                                    int sh, 
                                                    int dx, 
                                                    int dy);
void           gai_draw_raw_bg                     (unsigned char *rawRGB, 
                                                    int x, 
                                                    int y, 
                                                    int width, 
                                                    int height, 
                                                    int rowstride);
void           gai_draw_raw_alpha_bg               (unsigned char *rawRGBA, 
                                                    int x, 
                                                    int y, 
                                                    int width, 
                                                    int height, 
                                                    int rowstride);
void           gai_draw_update_bg                  (void);
void           gai_save_int                        (const char *name, 
                                                    int value);
void           gai_save_bool                       (const char *name, 
                                                    int value);
void           gai_save_float                      (const char *name, 
                                                    float value);
void           gai_save_string                     (const char *name, 
                                                    const char *value);
void           gai_save_raw_data                   (const char *name, 
                                                    unsigned const char *data, 
                                                    int size);
void           gai_save_glist                      (const char *name, 
                                                    GList *list);
int            gai_load_int_with_default           (const char *name, 
                                                    int default);
int            gai_load_bool_with_default          (const char *name, 
                                                    int default);
float          gai_load_float_with_default         (const char *name, 
                                                    float default);
char*          gai_load_string_with_default        (const char *name, 
                                                    const char *default);
unsigned char* gai_load_raw_data                   (const char *name, 
                                                    int size);
GList*         gai_load_glist_with_default         (const char *name,
                                                    GList *list);

Description

Here follows the complete guide to all GAI library calls and structures.

Some functions can only be called during initialization of the applet, in other words between gai_init or gai_init2 and gai_start. Unless otherwise specified, the function can be called anything during the applets life.

Structures

GaiApplet

typedef struct
{
    char *name;
    char *version;
    char *nice_name;
    char *author;
    char *license;
    char *description;
    char *icon;
    char *image_path;
} GaiApplet;

The GaiApplet struct contains information about the applet. If you use the template scripts, the configure script will generate a config.h file that includes this structure.

char *nameThe unix name of the applet. Example: "gai-test"
char *versionThe version of your applet. Example: "0.1beta"
char *nice_nameThis string will be used on the Gnome panel and in the about box. Example "GAI Test applet".
char *authorA string identifying the author of the applet. Example: "Jonas Aaberg <cja@gmx.net>"
char *licenseThe license of your applet. If you wrote it from scratch, you can give it any license. Example: "GNU GPL".
char *descriptionA short description of the applet. \n means new line. Example: "This a simple test applet.\nbla bla..\n"
char *iconThis a unique full path to the icon of this applet. This is used on the Gnome panel and in the about box. Example:"/usr/local/share/pixmap/gai-test/gai-test-icon.png"
char *image_pathThe path to where the applet images are stored. Example "/usr/local/share/pixmaps/gai-test/"

GaiFlagsType

typedef enum
{
    GAI_FLAGS_MOUSE_PTR_HIDE = 1 << 0,
    GAI_FLAGS_MOUSE_PTR_SHOW = 1 << 1,
    GAI_FLAGS_ALLOW_ROTATE   = 1 << 2,
    GAI_FLAGS_NEVER_ROTATE   = 1 << 3,
    GAI_FLAGS_OPEN_GL_WINDOW = 1 << 4,
    GAI_FLAGS_FREEZE_UPDATES = 1 << 5,
    GAI_FLAGS_THAW_UPDATES   = 1 << 6
} GaiFlagsType;
GAI_FLAGS_MOUSE_PTR_HIDEHide the mouse pointer when over the applet
GAI_FLAGS_MOUSE_PTR_SHOWNormal behavoiur (Default)
GAI_FLAGS_ALLOW_ROTATEAllow non-rectangular applets to be rotated on the Gnome panel when it is vertical. (Default)
GAI_FLAGS_NEVER_ROTATEDo not rotate the applet, no matter Gnome panel orientation.
GAI_FLAGS_OPEN_GL_WINDOWMakes the applet an OpenGL applet. This flag can only be set during initializing. It does not work on the Gnome panel or with WindowMaker!
GAI_FLAGS_FREEZE_UPDATESStops graphic updates. Only useful for very special applets, like TV in a Box.
GAI_FLAGS_THAW_UPDATESResets graphic updates to normal behavoiur.

GaiCallback


typedef gboolean GaiCallback0(gpointer userdata);
typedef gboolean GaiCallback1(int, gpointer userdata);
typedef gboolean GaiCallback2(int, int, gpointer userdata);
typedef gboolean GaiCallback3(int, int, int, gpointer userdata);

These are the format of the different callback functions that signals can be attached to.



This function or structure is a part of Glib v2.x or GTK+ v2.x. The documentation of those libraries are very good and comes with the source code. The source code can be downloaded from http://www.gtk.org.
GdkPixbuf and GDK are parts of GTK+.


Base


gai_init()

int            gai_init                            (const char *name, 
                                                    const char *version, 
                                                    const char *image_path, 
                                                    int *argc, 
                                                    char ***argv);

Warning

gai_init is deprecated and should not be used in new code. Use gai_init2 instead

Initialization of the GAI library. This call is required to be the first GAI call. You have to pass pointers to the command line parameters and a lowercase name for your applet. No spaces or non-alphabetic letters. Notice that this name must be the same as in the one in the GNOME_*.server file. Otherwise Gnome won't find your applet and start it correctly. This call also initializes GTK+ and Gnome, if the library is compiled with Gnome support. So no need for gtk_init(..) nor gnome_program_init(..)

*name :The unix name of your applet.
*version :The version of the applet as text string.
*image_path :The directory where the applet shall look for its images.
*argc :Pointer to the argc provided to the main function.
***argv :Pointer to the **argv provided to the main function.
Returns :0 if everything went well.

gai_init2()

int            gai_init2                           (GaiApplet* applet_info, 
                                                    int *argc, 
                                                    char ***argv);

This will replace gai_init in GAI version 0.6.0 and later. gai_init2 provides more information than gai_init in order to make it possible to automatically generate an About box. Together with the current template configure and Makefile scripts most of the information there will be used to generate the GaiApplet* structure. Otherwise gai_init2 does about the same thing as gai_init.

*applet_info :A struct with information about the applet. If you use the GAI template scripts, this information is provided in config.h that is generated by the configure script.
*argc :Pointer to the argc provided to the main function.
***argv :Pointer to the **argv provided to the main function.
Returns :1 if Gnome, 2 if Dock/ROX panel.

gai_start()

void           gai_start                           (void);

When all things are ready for running, call this function and the applet will be drawn and displayed. This function MUST be called last after all other things are done. This function will return when the applet shall stop running, ie when the applet is terminated.



Background handling

Notice that at the moment applets apply to the normal X-Window rules when it comes to transparency. That means that a pixel is either completly transparent, or the given a colour. Transparency levels can not be handled. Backgrounds can be changed at any time during an applet's life.


gai_background_set()

void           gai_background_set                  (int width, 
                                                    int height, 
                                                    int max_size, 
                                                    int border);

Sets the background of the applet. Normally for dockapps the background should be a 64x64 image with a border. That results in a drawing area of 56x56 at 4x4. This is the default library settings if no function connected to the background is called during the initialization phase. Note that not all window managers allow applet of sizes other than 64x64. From the applet's point of view, the applet will always seem to be of the requested size, GAI will take care of any scaling.

width :The width of your applet.
height :The height of your applet.
max_size :The maximal scaling size of your applet. Use it when you do not want your applet to be scaled up above a certain size when the Gnome panel is larger than your applet. Else pass with GAI_BACKGROUND_MAX_SIZE_NONE. Notice that it's always the height that counts as max_size. (Default layout for the Gnome panel is horizontal, and when it's vertical, the library takes care of it.)
border :Set it to TRUE if you want a 4x4 partly transparent border around. FALSE if not wanting a border.
Returns :Nothing.

gai_background_from_xpm()

void           gai_background_from_xpm             (const char **xpmimagename,
                                                    int max_size);

Sets the background to a specified XPM image.

xpmimagename :The pointer to an XPM image.
max_size :As for gai_background_set. Set it to GAI_BACKGROUND_MAX_SIZE_IMAGE if you do not want your applet to be scaled up over the original size.
Returns :Nothing.

gai_background_from_gdkpixbuf()

void           gai_background_from_gdkpixbuf       (GdkPixbuf* pixbuf, 
                                                    int max_size);

Sets the background from an image stored in a GdkPixbuf structure.

pixbuf :The pointer to an image in a GdkPixbuf structure.
max_size :As for gai_background_set. Set it to GAI_BACKGROUND_MAX_SIZE_IMAGE if you do not want your applet to be scaled up over the original size.
Returns :Nothing.

gai_background_from_file()

void           gai_background_from_file            (const char *image_file, 
                                                    int max_size);

Sets the background from a file. The image can be stored in nearly any image format. Note that the image name shall be relative to the image path passed to gai_init or gai_init2. If the file pointed to is not found, a message box is shown to inform the user that the image can not be loaded and then the applet quits.

imagefile :The name of the file to be used as background. The name is relative to the image path provided with gai_init or gai_init2
max_size :As for gai_background_set. Set it to GAI_BACKGROUND_MAX_SIZE_IMAGE if you do not want your applet to be scaled up over the original size.
Returns :Nothing.

Image loading


gai_load_image()

GdkPixbuf*     gai_load_image                      (char *imagefilename);

Loads an image into a GdkPixbuf struct. If a file is missing it displays an error dialog and quits.

imagefilename :The name of the file to loaded. The name is relative to the image path provided with gai_init or gai_init2
Returns :A GdkPixbuf with the requested image.

Right button menu


You can not change the right button menu entries during the running phase.

gai_menu_add_help_text()

void           gai_menu_add_help_text              (const char *msg);

This will add a menu item named "Help" with the right help icon. When selected, the passed textstring will displayed in a message box. You can only add a help text during the startup of the applet, ie before gai_start().

imagefilename :The help text. "\n" can be used for a new line.
Returns :Nothing.

gai_menu_add()

void           gai_menu_add                        (const char *name, 
                                                    const char *icon, 
                                                    int type, 
                                                    void *func, 
                                                    void *ptr);

This function call will add an entry to the right button menu. You can only add menu entries during the startup of the applet.

*name :The name of the entry that shall be displayed on the menu.
*icon :Pointer to the name of the gtk-stock image or file that will be used.
type :Can at the moment only be GAI_MENU_STOCK, GAI_MENU_NONE, GAI_MENU_FILE or GAI_MENU_SEPARATOR. GAI_MENU_STOCK means that you will use a GTK stock image as icon and GAI_MENU_SEPARATOR means that there will be a horizontal line there instead of a menu entry. GAI_MENU_NONE means that there will be no image for this entry. GAI_MENU_FILE Defines that an image, stored as a file shall be used on the right button menu. Notice that a suitable size of 16x16 pixels large, since the other icons are of that size.
*func :Callback function to be called when the menu entry is selected.
*ptr :A pointer to optional user data to pass to the callback function.
Returns :Nothing.


Text handling


gai_text_create()

GdkPixbuf*     gai_text_create                     (char *msg,
                                                    char *font, 
                                                    int font_size, 
                                                    int feature, 
                                                    char red, 
                                                    char green, 
                                                    char blue);

This function renders a given text string into a GdkPixbuf.

*msg :The text message to be rendered to an image.
*font :The name of the font that you wish to us, eg "times", "arial" or "utopia". Please try to use a font that is installed by default on most systems.
font_size :The size of the text just in like any word processor.
feature :Font features. Possible options are:
GAI_TEXT_NORMAL - Just plain normal text
GAI_TEXT_BOLD - Bold text
GAI_TEXT_ITALIC - Italic text
GAI_TEXT_SMOOTH - Smooth the rendered text a little
red :The red part of the font colour (0-255)
green :The green part of the font colour (0-255)
blue :The blue part of the font colour (0-255)
Returns :A GdkPixbuf image containing the provided text as image.



Event hooks and time outs


All signal callbacks take user data as last argument (in the form of a gpointer. It is there if an applet designer wants to pass some data from the initial procedure. The functions that you can connect signals to shall be of the GaiCallback types.

gai_signal_on_update()

void           gai_signal_on_update                (GaiCallback0 func, 
                                                    int delay, 
                                                    gpointer userdata);

Tells gai which function to call for updating the applet. This function is the heart of most applets. After delay ms, the given function will be called over and over again as time goes by.

func :Function to call when this event occurs.
delay :The delay is in ms between each update function call.
userdata :Data to pass to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_update_interval_change()

void           gai_signal_on_update_interval_change (int delay);

With this function you can change how often, in ms, the callback specified via gai_signal_on_update should be called.

delay :The delay is in ms between each update function call.
Returns :Nothing.

gai_signal_on_exit()

void           gai_signal_on_exit                  (GaiCallback0 func, 
                                                    gpointer userdata);

Tells the library that a function should be called when it's time to terminate the applet.

func :Function to call when this event occurs.
userdata :Data to pass to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_enter()

void           gai_signal_on_enter                 (GaiCallback0 func, 
                                                    gpointer userdata);

Function to call when the mouse pointer enters the applet area.

func :Function to call when this event occurs.
userdata :Data to pass to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_leave()

void           gai_signal_on_leave                 (GaiCallback0 func, 
                                                    gpointer userdata);

Function to call when the mouse pointer leaves the applet area.

func :Function to call when this event occurs.
userdata :Data to pass to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_keypress()

void           gai_signal_on_keypress              (GaiCallback1 func,
                                                    gpointer userdata);

Function to call when a key is pressed. The int here provided to GaiCallback1is the key pressed. Look in gdk/gdkkeysym.h in GTK+ for the name of the keys.

func :Function to call when this event occurs.
userdata :Data to pass to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_mouse_button_click()

void           gai_signal_on_mouse_button_click    (GaiCallback2 func, 
                                                    int button, 
                                                    gpointer userdata);

Function to call when the specified mouse button is pressed. GaiCallback2 is called with the X and Y coordinates of where the click occured as arguments. Notice, that the X and Y coordinates are completly independent of the actual scaling of the applet that is done by the Gnome Panel or general size settings. X and Y always depends on the size that the applet believes it has.

func :Function to call when this event occurs.
button :The argument button defines which button the signal shall be connected to. It can be GAI_MOUSE_BUTTON_1 or GAI_MOUSE_BUTTON_2. The third (right) mouse button can not be connected to a signal since it handles the menu.
userdata :Data to pass with to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_mouse_button_release()

void           gai_signal_on_mouse_button_release  (GaiCallback2 func,
                                                    int button, 
                                                    gpointer userdata);

The same as for gai_signal_on_mouse_button_click, but the signal is triggered on mouse button release.

func :Function to call when this event occurs.
button :The argument button defines which button the signal shall be connected to. It can be GAI_MOUSE_BUTTON_1 or GAI_MOUSE_BUTTON_2. The third (right) mouse button can not be connected to a signal since it handles the menu.
userdata :Data to pass with to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_scroll_buttons()

void           gai_signal_on_scroll_buttons        (GaiCallback1 func, 
                                                    gpointer userdata);

Function to call when the mouse wheel is scrolled. The connected function is called with the direction of the scroll event as argument. The different scroll directions are:
GDK_SCROLL_UP, GDK_SCROLL_DOWN, GDK_SCROLL_LEFT and GDK_SCROLL_RIGHT

func :Function to call when this event occurs.
userdata :Data to pass to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_change()

void           gai_signal_on_change                (GaiCallback3 func, 
                                                    gpointer userdata);

Connects a function to the event that occurs when Gnome panel's size or direction is changed. In dockapp mode this function is never called. However, remember that GAI takes care of all scaling and rotating.
This function is just there to report to the applet its sizes and layout direction. The connected funtion is called with the arguments the orientation, that can be GAI_HORIZONTAL or GAI_VERTICAL and then the new width and height.

func :Function to call when this event occurs.
userdata :Data to pass with to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_preferences()

void           gai_signal_on_preferences           (GaiCallback0 func,
                                                    gpointer userdata);

If you want to use a your own designed preference window instead of the GAI preference window, you can hook a function to this event.

func :Function to call when this event occurs.
userdata :Data to pass to the connected function when this event occurs.
Returns :Nothing.

gai_signal_on_joystick()

void           gai_signal_on_joystick              (GaiCallback1 func,
                                                    gpointer userdata);

Function to call when a joystick event happens. The provided data is bit mapped with:
GAI_JOYSTICK_NOTHING,
GAI_JOYSTICK_LEFT,
GAI_JOYSTICK_RIGHT,
GAI_JOYSTICK_UP,
GAI_JOYSTICK_DOWN,
GAI_JOYSTICK_BUTTON_A,
GAI_JOYSTICK_BUTTON_B
All combinations are possible except that GAI_JOYSTICK_NOTHING can never cooexist with another flag.

func :Function to call when this event occurs.
userdata :Data to pass to the connected function when this event occurs.
Returns :Nothing.

Misc functions


gai_about_from()

void           gai_about_from                      (const char *text);

Warning

gai_about_from is deprecated and should not be used in new code. Use gai_init2 instead

A simplified version of creating the about window.

*text :A pointer to a string with "summary,author,description,icon,license" as keywords in order to describe how to generate an about window. The syntax is the same as of a .spec file.
Note that the icon part is not implemented. (And never will be.)
Returns :Nothing.

gai_preferences()

void           gai_preferences                     (const char *name,
                                                    GaiNoteBook *pref_tree, 
                                                    const char *help_text,
                                                    GaiCallback0 func, 
                                                    gpointer userdata);

Warning

gai_preferences is deprecated and should not be used in new code. Use gai_preferences2 instead

This function was used to generate a preference window. It is undocumented and it will stay that way. Do not use it.

*name :The title of the preference window.
*pref_tree :A tree struture that describes the preference window.
*help_text :The text that is displayed when the user presses the help button in the preference window.
func :The function that is called when the preferences is changed and the changes shall be executed.
userdata :Data to pass with to the connected function when this event occurs.
Returns :Nothing.

gai_preferences2()

void           gai_preferences2                    (const char *name,
                                                    GaiPI *pref_struct, 
                                                    const char *help_text,
                                                    GaiCallback0 func, 
                                                    gpointer userdata);

This function is a powerful tool to to generate a preference window. See the Preference Window Reference Manual for description.

*name :The title of the preference window.
*pref_struct :A struture that describes the preference window.
*help_text :The text that is displayed when the user presses the help button in the preference window.
func :The function that is called when the preferences is changed and the changes shall be executed.
userdata :Data to pass with to the connected function when this event occurs.
Returns :Nothing.

gai_gl_init_func()

void           gai_gl_init_func                    (GaiCallback0 function);

There is a basic OpenGL support via gtkglext At the moment, OpenGL support works only for dockapps and NOT for the Gnome Panel. This call specifies the function that performs OpenGL initalization. This is required by gtkglext. Notice that you have to pass GAI_FLAGS_OPEN_GL_WINDOW with gai_flags_set in order to make it all work.

function :The function that includes all OpenGL depending code that has to be preformed during start up.
Returns :Nothing.

gai_flags_set()

void           gai_flags_set                       (GaiFlagsType flags);

Sets the behavoiur flags. Notice that activating OpenGL support can only be done during the initializition of the applets. The other flags can be altered during run time.

flags :Flags that describe the behavoir of this applet. See GaiFlagsType for more information.
Returns :Nothing.

gai_flags_get()

GaiFlagsType   gai_flags_get                       (void);

Returns the current flags. Default settings are GAI_FLAGS_MOUSE_PTR_SHOW, GAI_FLAGS_ALLOW_ROTATE and GAI_FLAGS_THAW_UPDATES.

Returns :The current flags.

gai_get_window()

GdkWindow*     gai_get_window                      (void);

Returns the GdkWindow of the applet. If you want to handle drawing manually.

Returns :The GdkWindow of the applet.

gai_get_drawingarea()

GtkWidget*     gai_get_drawingarea                 (void);

Returns the drawing area widget, if for some reason it is required by your code.

Returns :The drawingarea GtkWidget.

gai_get_gc()

GdkGC*         gai_get_gc                          (void);

If you need to know the GdkGC of the applet, you'll get it with this function.

Returns :The GdkGC of the applet.

gai_get_size()

int            gai_get_size                        (void);

If you want to know how large the applet really is when scaling is taken into account. Notice: the height of the applet is considered the main size.

Returns :The real visual size of the applet.

gai_scale()

int            gai_scale                           (int size);

If you wish to know how large a size is in the current visual size of the applet, call this function and the real size will be returned. For example, say that the applet is 64x64 from the beginning, but Gnome made it 48x48 (this isn't shown to the applet, if the applet doesn't want to know.) This function will return 24 if the input size is 32.

size :The value to scale
Returns :The scaled value of the given value, based upon the real visual size of the applet.

gai_get_orient()

int            gai_get_orient                      (void);

Returns the current orientation of the applet.

Returns : Either GAI_VERTICAL or GAI_HORIZONTAL depending on the rotation of the applet.

gai_tooltip_set()

void           gai_tooltip_set                     (const char *msg);
Makes a give message show when you the mouse pointer hovers on the applet.

NOTE: I have strong reasons to believe that atleast GTK 2.2.4 leaks memory when changing a window tooltip, so use it with care! (I.E set the tooltip only once to be on the sure side.)

*msg :The message to show.
Returns :Nothing.

gai_tooltip_remove()

void           gai_tooltip_remove                  (void);

Removes the current tooltip, if any. See the note on gai_tooltip_set.

gai_exec()

void           gai_exec                            (const char *prg);

Executes a given program in parallel with the applet. The return value of the executed program is not returned. The current path will be searched for the given program, if no unique executable name is given. An error dialog will be displayed if gai_exec fails to execute the given program.

*msg :The program to run.
Returns :Nothing.

gai_display_error_quit()

void           gai_display_error_quit              (const char *msg);

Shows the given message as an error and quits the applet.

*msg :The message to show.
Returns :Never.

gai_display_error_continue()

void           gai_display_error_continue          (const char *msg);

Shows the given message as an error but continues executing the applet.

*msg :The message to show.
Returns :Nothing.

Drawing

GAI fools the applet into believing that it is always in the original size, if the applet doesn't want to know. I decided to do it like this, since the Gnome Panel can have variable sizes, anything between 16 and 128 pixels large. The library takes care of all scaling.
Drawing on the foreground is much faster than drawing on the background. But what you draw on the background will remain forever, no matter what happens with the applet, since you don't have to refresh a background. With the foreground you will need to refresh it many times a second. If you don't refresh it that often, what you have drawn will disapear when you move a window over your applet, and the background will reappear. I have noticed that if the applet needs to be redrawn less than two times a second, it is better to draw on the background, instead of drawing on the foreground, say 10 times a second just to make sure that you keep the look nice.
Foreground pixels must be drawn upon existing background pixels, ie the background must be set to a colour via gai_background* or gai_draw_*_bg. If a pixel is defined transparent by the background, it will stay like that regardless of attempts to draw on it.

gai_draw()

void           gai_draw                            (GdkPixbuf *image, 
                                                    int sx, 
                                                    int sy, 
                                                    int sw, 
                                                    int sh, 
                                                    int dx, 
                                                    int dy);

Draws the GdkPixbuf image from (sx, sy) that is (sw, sh) large at (dx, dy).

*image :The source image.
sx :X coordinate in the source GdkPixbuf.
sy :Y coordinate in the source GdkPixbuf.
sw :Width of the part of the image in the source GdkPixbuf that you want to draw in the applet window.
sh :Height of the part of the image in the source GdkPixbuf that you want to draw in the applet window.
dx :X coordinate in the applet window.
dy :Y coordinate in the applet window.
Returns :Nothing.

gai_draw_raw()

void           gai_draw_raw                        (unsigned char *rawRGB, 
                                                    int x,  
                                                    int y, 
                                                    int width, 
                                                    int height, 
                                                    int rowstride);

Draws a raw 24 bit image, at (x, y) The image has the size (width, height). Normally the rowstride is 3*width, but not always.

*rawRGB :The source image as rawdata.
x :X coordinate in the applet window.
y :Y coordinate in the applet window.
width :Width of the part of the image in the source image data that you want to draw in the applet window.
height :Height of the part of the image in the source image data that you want to draw in the applet window.
rowstride :The size of each row in bytes. (Sometimes data is padded up, when needed)
Returns :Nothing.

gai_draw_raw_alpha()

void           gai_draw_raw_alpha                  (unsigned char *rawRGBA,
                                                    int x, 
                                                    int y, 
                                                    int width, 
                                                    int height, 
                                                    int rowstride);

The same as above, but with an alpha channel. Note that the rowstride for raw images with an alpha channel is normally 4*width.

*rawRGBA :The source image as rawdata.
x :X coordinate in the applet window.
y :Y coordinate in the applet window.
width :Width of the part of the image in the source image data that you want to draw in the applet window.
height :Height of the part of the image in the source image data that you want to draw in the applet window.
rowstride :The size of each row in bytes. (Sometimes data is padded up, when needed)
Returns :Nothing.

gai_draw_update()

void           gai_draw_update                     (void);

Makes all drawings done to the applet become visible. This function should be called when all drawing updates have been done.

gai_draw_bg()

void           gai_draw_bg                         (GdkPixbuf *image, 
                                                    int sx, 
                                                    int sy, 
                                                    int sw,
                                                    int sh, 
                                                    int dx, 
                                                    int dy);

Same as gai_draw but draws on the background instead.

*image :The source image.
sx :X coordinate in the source GdkPixbuf.
sy :Y coordinate in the source GdkPixbuf.
sw :Width of the part of the image in the source GdkPixbuf that you want to draw in the applet window.
sh :Height of the part of the image in the source GdkPixbuf that you want to draw in the applet window.
dx :X coordinate in the applet window.
dy :Y coordinate in the applet window.
Returns :Nothing.

gai_draw_raw_bg()

void           gai_draw_raw_bg                     (unsigned char *rawRGB, 
                                                    int x, 
                                                    int y, 
                                                    int width, 
                                                    int height, 
                                                    int rowstride);

Same as gai_draw_raw but draws on the background instead.

*rawRGB :The source image as rawdata.
x :X coordinate in the applet window.
y :Y coordinate in the applet window.
width :Width of the part of the image in the source image data that you want to draw in the applet window.
height :Height of the part of the image in the source image data that you want to draw in the applet window.
rowstride :The size of each row in bytes. (Sometimes data is padded up, when needed)
Returns :Nothing.

gai_draw_raw_alpha_bg()

void           gai_draw_raw_alpha_bg               (unsigned char *rawRGBA, 
                                                    int x, 
                                                    int y, 
                                                    int width, 
                                                    int height, 
                                                    int rowstride);

Same as gai_draw_raw_alpha but draws on the background instead.

*rawRGBA :The source image as rawdata.
x :X coordinate in the applet window.
y :Y coordinate in the applet window.
width :Width of the part of the image in the source image data that you want to draw in the applet window.
height :Height of the part of the image in the source image data that you want to draw in the applet window.
rowstride :The size of each row in bytes. (Sometimes data is padded up, when needed)
Returns :Nothing.

gai_draw_update_bg()

void           gai_draw_update_bg                  (void);

This forces all queued updates to the background to be done. It should be called when all background drawing calls have been done. This call is pretty slow.


Saving and loading settings

The settings file will be stored under ~.gnome2/"applet_name" even if gnome isn't installed. The "name" shall be like "background/red", with a top name and a variable name.


gai_save_int()

void           gai_save_int                        (const char *name, 
                                                    int value);

Stores an integer.

*name :The name the value shall be stored under.
value :The value to store.
Returns :Nothing.

gai_save_bool()

void           gai_save_bool                       (const char *name, 
                                                    int value);

Stores a boolean.

*name :The name the value shall be stored under.
value :The value to store.
Returns :Nothing.

gai_save_float()

void           gai_save_float                      (const char *name, 
                                                    float value);

Stores a float.

*name :The name the value shall be stored under.
value :The value to store.
Returns :Nothing.

gai_save_string()

void           gai_save_string                     (const char *name, 
                                                    const char *value);

Stores a string.

*name :The name the string shall be stored under.
*value :The string to store.
Returns :Nothing.

gai_save_raw_data()

void           gai_save_raw_data                   (const char *name, 
                                                    const char *data,
                                                    int size);

Saves rawdata with a given size under a special name.

*name :The name the rawdata shall be stored under.
*data :The rawdata to store.
size :The size of the rawdata.
Returns :Nothing.

gai_save_glist()

void           gai_save_glist                      (const char *name, 
                                                    GList *list);

Saves a GList that contains charater strings.

*name :The name the list shall be stored under.
*list :The list to store.
Returns :Nothing.

gai_load_int_with_default()

int            gai_load_int_with_default           (const char *name, 
                                                    int default);

Loads an interger. If not found, the default value will be returned.

*name :The name the value is stored under.
default :The default value.
Returns :The stored value, if it exist. Otherwise the default value is returned.

gai_load_bool_with_default()

int            gai_load_bool_with_default          (const char *name, 
                                                    int default);

Loads a bool. If not found, the default value will be returned.

*name :The name the value is stored under.
default :The default value.
Returns :The stored value, if it exist. Otherwise the default value is returned.

gai_load_float_with_default()

float          gai_load_float_with_default         (const char *name,
                                                    float default);

Loads a float. If not found, the default value will be returned.

*name :The name the value is stored under.
default :The default value.
Returns :The stored value, if it exist. Otherwise the default value is returned.

gai_load_string_with_default()

char*          gai_load_string_with_default        (const char *name,
                                                    const char *default);

Loads a string. If not found, the default value will be returned.

*name :The name the string is stored under.
*default :The default string.
Returns :The stored string, if it exist. Otherwise the default string is returned.

gai_load_raw_data()

unsigned char* gai_load_raw_data                   (const char *name,
                                                    int size);

Loads saved rawdata of a given size. If no data of that name and size is found a NULL pointer is returned.

*name :The name the raw data is stored under.
size :The size of the stored raw data.
Returns :The stored rawdata, if it exist. Otherwise NULL is returned.

gai_load_glist_with_default()

GList*         gai_load_glist_with_default         (const char *name,
                                                    GList *list);

Loads saved list.

*name :The name the list is stored under.
*list :The default list. Can be NULL.
Returns :The stored list, if it exist. Otherwise the default list is returned.

Errors in this document? Need help? Then mail me, Jonas Aaberg, cja@gmx.net.