GAI - Library calls - Reference Manual

## Sections

Synopsis - Library calls
Description
Structures
Base
Background handling
Image loading
Right button menu
Text handling
Event hooks and time outs
Miscellaneous 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);
    GdkPixbuf*     gai_load_image_at_size              (char *imagefilename,
                                                        int width,
                                                        int height);
    void           gai_menu_add_help_text              (const char *msg);
    int            gai_menu_add                        (const char *name,
                                                        const char *icon,
                                                        int type,
                                                        void *func,
                                                        void *ptr);
    gboolean       gai_menu_change                     (int id,
                                                        const char *name,
                                                        const char *icon,
                                                        int type,
                                                        void *func,
                                                        void *ptr);
    int            gai_menu_insert                     (int num,
                                                        const char *name,
                                                        const char *icon,
                                                        int type,
                                                        void *func,
                                                        void *ptr);
    void           gai_menu_remove                     (int id);
    GdkPixbuf*     gai_text_create                     (char *msg,
                                                        char *font,
                                                        int font_size,
                                                        int feature,
                                                        char red,
                                                        char green,
                                                        char blue);
    GdkPixbuf*     gai_text_create_simple              (char *msg,
                                                        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_mouse_move            (GaiCallback2 func,
                                                        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           (GaiCallback1 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,
                                                        GaiCallback1 func,
                                                        gpointer userdata);
    void           gai_preferences2                    (const char *name,
                                                        GaiPI *pref_struct,
                                                        const char *help_text,
                                                        GaiCallback1 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

This document describes all GAI library calls and structures.

Some functions can only be called during initialization of the applet, ie between `gai_init` or `gai_init2` and `gai_start`. Unless specified otherwise, functions can be called anytime during the applets lifetime.

## 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 `*name` | The Unix name of the applet. Example: "gai-test"
char `*version` | The version of your applet. Example: "0.1beta"
char `*nice_name` | This string will be used on the Gnome panel and in the about box. Example "GAI Test applet".
char `*author` | A string identifying the author of the applet. Example: "Jonas Aaberg <cja@gmx.net>"
char `*license` | The license of your applet. If you wrote it from scratch, you can give it any license. Example: "GNU GPL".
char `*description` | A short description of the applet. \n means new line. Example: "This a simple test applet.\nblah blah..\n"
char `*icon` | This 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_path` | The 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,
        GAI_FLAGS_TRANSPARENT    = 1 << 7,
        GAI_FLAGS_PANEL          = 1 << 8
    } GaiFlagsType;

`GAI_FLAGS_MOUSE_PTR_HIDE` | Hide the mouse pointer when over the applet
`GAI_FLAGS_MOUSE_PTR_SHOW` | Normal behaviour (Default)
`GAI_FLAGS_ALLOW_ROTATE` | Allow non-rectangular applets to be rotated on the Gnome panel when it is vertical (Default)
`GAI_FLAGS_NEVER_ROTATE` | Do not rotate the applet, regardless of the Gnome panel orientation.
`GAI_FLAGS_OPEN_GL_WINDOW` | Makes the applet an OpenGL applet. This flag can only be set during initialization. It does not work on the Gnome panel or with WindowMaker!
`GAI_FLAGS_FREEZE_UPDATES` | Stops graphic updates. Only useful for very special applets, like TV in a Box.
`GAI_FLAGS_THAW_UPDATES` | Resets graphic updates to normal behaviour.
`GAI_FLAGS_TRANSPARENT` | If you turn this flag on, dockapps can be semi-transparent with the background. It requires that the background image has an alpha channel.
`GAI_FLAGS_PANEL` | Forces GAI to make the applet sticky and borderless, ie not for docking.

### 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 prototypes of the different callback functions that signals can be attached to.

### Glib, Gdk, Gdkpixbuf, Gtk

For functions or structures that are part of `Glib` v2.x or `GTK+` v2.x, refer to the official documentation. The documentation of those libraries and the source can be found on 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 should be the first GAI function called by your program. You have to pass pointers to the command line parameters and a lowercase name for your applet. No spaces or non-alphabetic letters. Note that this name must be the same as in the one in the GNOME_*.server file, otherwise Gnome will be unable to 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 `configure` and `Makefile` template scripts, the information passed here 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 everything is set, 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 returns when the applet stops running, ie when the applet is terminated.

### Background handling

Note 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`. Note 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 is relative to the image path passed to `gai_init` or `gai_init2`. If the file pointed to is not found, a message box is displayed to inform the user that the image can not be loaded. The applet then quits.

`imagefile` : | The name of the file to be used as background. The name is relative to the image path provided to `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 load. The name is relative to the image path provided to `gai_init` or `gai_init2`
Returns : | A GdkPixbuf with the requested image.

### gai_load_image_at_size()

    GdkPixbuf*     gai_load_image_at_size              (char *imagefilename
                                                        int width,
                                                        int height);

Loads an image into a GdkPixbuf struct and scales it. Useful for vector images. If a file is missing it displays an error dialog and quits.

`imagefilename` : | The name of the file to load. The name is relative to the image path provided to `gai_init` or `gai_init2`
`width` : | The wished width of the image.
`height` : | The wished height of the image.
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 text string will be 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()

    int            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. The returned integer is the menuitem id.

`*name` : | The name of the entry to add to 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. Note that a suitable size of 16x16 pixels large, since the other icons are of that size.
`*func` : | Callback function to call when the menu entry is selected.
`*ptr` : | A pointer to optional user data to pass to the callback function.
Returns : | The ID of the menu item.

### gai_menu_change()

    gboolean       gai_menu_change                     (int id,
                                                        const char *name,
                                                        const char *icon,
                                                        int type,
                                                        void *func,
                                                        void *ptr);

This function will can an existing menu entry. This can be done anytime.

`id` : | The ID of the menu entry..
`*name` : | The new name of the menu entry.
`*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. Note that a suitable size of 16x16 pixels large, since the other icons are of that size.
`*func` : | Callback function to call when the menu entry is selected.
`*ptr` : | A pointer to optional user data to pass to the callback function.
Returns : | True if an entry with the give ID exists and was sucessfully changed.

### gai_menu_insert()

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

This function will insert a new menu item at any place on the menu. num equals zero means putting it first, num equals one means put it after the first menu entry and so on.

`num` : | The placement of this new menu entry.
`*name` : | The name of the entry to add to 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. Note that a suitable size of 16x16 pixels large, since the other icons are of that size.
`*func` : | Callback function to call when the menu entry is selected.
`*ptr` : | A pointer to optional user data to pass to the callback function.
Returns : | The ID of the menu item.

### gai_menu_remove()

    void           gai_menu_remove                     (int id);

bla

`*name` : | The name of the entry to add to 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. Note that a suitable size of 16x16 pixels large, since the other icons are of that size.
`*func` : | Callback function to call when the menu entry is selected.
`*ptr` : | A pointer to optional user data to pass to the callback function.
Returns : | The ID of the menu item.

### 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. Please consider to use gai_text_create_simple instead.

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

### gai_text_create_simple()

    GdkPixbuf*     gai_text_create_simple              (char *msg,
                                                        char red,
                                                        char green,
                                                        char blue);

This function renders a given text string into a GdkPixbuf. It uses the default font decided by the current GTK theme. It is recommended that you use this function instead of gai_text_create, because you can never know how a font will behave on another system. Also your applet will fit nicely with the users theme.
If you believe this function lacks some feature, like changing font size, please mail me.

`*msg` : | The text message to be rendered to an image.
`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`. 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 until the applet quits.

`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 the applet exits.

`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` parameter to `GaiCallback1`is the code of the key that's been 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. Note 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. The coordinates are relative to the top left corner of the applet.

`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 cannot be connected to a signal since it handles the menu.
`userdata` : | Data to pass 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 cannot be connected to a signal since it handles the menu.
`userdata` : | Data to pass to the connected function when this event occurs.
Returns : | Nothing.

### gai_signal_on_mouse_move()

    void           gai_signal_on_mouse_move            (GaiCallback2 func,
                                                        gpointer userdata);

This function registers a callback that will be called each time the mouse pointer is moved. It will only be called when the mouse pointer is above the applet area. `GaiCallback2` is called with the `X` and `Y` coordinates of the mouse pointer arguments. Note 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. The coordinates are relative to the top left corner of 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_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 parameter. 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 size and layout direction. The connected funtion is passed as parameters the `orientation`, either `GAI_HORIZONTAL` or `GAI_VERTICAL`, followed by the new `width` and `height`.

`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_preferences()

    void           gai_signal_on_preferences           (GaiCallback1 func,
                                                        gpointer userdata);

If you want to use your own preferences window instead of the one generated by GAI, hook a function to this event. The first argument of the hooked function will be an `Integer` that is `TRUE` if the user changed anything in the preference dialog and `FALSE` when the user didn't.

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

### Miscellaneous 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 simple function for 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 ignored.
Returns : | Nothing.

### gai_preferences()

    void           gai_preferences                     (const char *name,
                                                        GaiNoteBook *pref_tree,
                                                        const char *help_text,
                                                        GaiCallback1 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 preferences window. It is undocumented and it will stay that way. Do not use it.

`*name` : | The title of the preferences window.
`*pref_tree` : | A tree struture that describes the preferences window.
`*help_text` : | The text that is displayed when the user presses the help button in the preferences window.
`func` : | The function called when the preferences are changed.
`userdata` : | Data to pass 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,
                                                        GaiCallback1 func,
                                                        gpointer userdata);

This function is a powerful tool to to generate a preferences window. See the Preferences Window Reference Manual for description. The first argument of the hooked function will be an `Integer` that is `TRUE` if the user changed anything in the preference dialog and `FALSE` when the user didn't.

`*name` : | The title of the preferences window.
`*pref_struct` : | A struture that describes the preferences window.
`*help_text` : | The text that is displayed when the user presses the help button in the preferences window.
`func` : | The function called when the preferences are changed.
`userdata` : | Data to pass 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. Note 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 behaviour flags. Note that activating OpenGL support can only be done during the initialization of the applets. The other flags can be altered during run time.

`flags` : | Flags that describe the behavior 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. Useful 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 drawing area `GtkWidget`.

### gai_get_gc()

    GdkGC*         gai_get_gc                          (void);

If you need to know the `GdkGC` of the applet, call 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. Note: 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 given message show when you the mouse pointer hovers on the applet.

WARNING: I have strong reasons to believe that at least GTK 2.2.4 leaks memory when changing a window tooltip, so use it with caution! ie 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 because 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. "name" shall be of the form "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 character 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.