The Generic Applet Interface Library (GAI) - Specification Version 0.1.1

Written by Jonas Aaberg 2003

Purpose

To give the programmers one simple interface for both Gnome 2 panel applets and WindowMaker applets(sometimes called dockapps). Also the goal is to give the user the flexibility to use the applets as normal WindowMaker applets or as Gnome 2 panel applets.

Library calls:

First face - Init
All functions here can only be called the init face, if not otherwise is said.



int gai_init(char *name, char *version, int *argc, char **argv)
Initializing of the library. This call is required to be the first one made to gai. You have to pass with the command line parameter and a lowercase name of your applet. No spaces or strange signs. Only alphabetic letters. Notice that this name *MUST* be the same as in the one in the Gnome_*.server file. Otherwise gnome can't find it and start it correctly. If you use the template configure.in file, the name is what says on the APPLET_NAME line. So a sudjection write:
gai_init(APPLET_NAME, "1.0". &argc, &argv);

This call alos initialize GTK+ and Gnome, if the library is compiled with Gnome support.
Returns 0 if everything went well, something else if something isn't working as expected.


Image loading and background handling


void gai_init_set_pix_path(char *path)
This gives an absolute path of where images that will be used for this applet is stored. This call is required to be called if you will use some image loading functions that isn't ending on _xpm. If you use the template configure.in file, simply add the line:
gai_init_pix_path(IMAGE_PATH);
Otherwise you have to add the absolute path to where you will install the images that your applet will work.
During development you can use gai_init_pix_path(".");
to load images from the current directory. Notice that this won't work with Gnome.

int gai_init_set_background(char *imagefilename)
The default and start-up background. Normally for dockapps this should be a 64x64 image, but if wished the applet can be of an other side. Gnome supports quite many different sizes, and some window managers supports dockapps with other sizes too.
Notice that gai_init_pix_path() must be called before.
Returns 0 if everything went well, 1 if something failed.

int gai_init_set_background_xpm(const char **xpmimagename)
The same as above, but uses a xpm image as background instead. Notice that gai_init_pix_path() isn't required to be called before.
Returns 0 if everything went well, 1 otherwise.

void gai_init_set_background_default(void)
Use the default library included 64x64 background with boarders, so the drawingarea starts at 4,4 and is 56, 56 large. All applets need a background, but for most it is never showned, so use this one then.
If you don't call any background settings, this is the default.

void gai_init_set_default_size(int, int)
Sets the default size of the applet. If this size isn't given, the size of the background determints the default size. You can use the gai_init_set_background_default() and then call this function to tell what size of the background you wish. But remember, the boarder is always 4 pixels wide.
Notice that the default layout of the gnome panel is horizontal, therefore the height is what is used for determine scaling.
void gai_init_set_max_size(int)
This tells the library how much it is allowed to scale the applet on the gnome panel. If you're applet is made for beeing small, say 16x16 then it will look awful when the library scales it up to 64x64. So then tell the library not to scale it too much.


GdkPixbuf *gai_init_load_image(char *imagefilename)
Loads an image into a GdkPixbuf struct for runtime use. See gdk-pixbuf for help how to use GdkPixbuf. (The gdk-pixbuf library is very nice.)
Can be called in other faces too.
Returns 0 if everything went well, 1 if something failed. Also displays an error dialog, since a missing image is quite fatal.

void gai_init_draw_foreground_with_alpha(void);
If your applet will draw images on the foreground that has an alpha channel, you have to call this function at start-up to assure that things works as expected.
But don't call this function if you don't have images with alpha channel, since it will comsume some cpu power. Not much, but unnessecary.

Special calls

void gai_init_never_rotate(void)
If your applet shouldn't be rotated when the Gnome panel are vertical, call this function on start up. Also, rotating is only done when the width is larger than the height and the gnome panel is vertical instead of the default horizontal layout.
Default value is TRUE. You don't have to call this call during the init face. This is only if you have some special reasons why your applet shouldn't be rotated.

void gai_init_hide_mouse_ptr(void)
If you for some reasons want that the mouse pointer shouldn't be shown when it is over the applet, call this function upon startup.
Notice that this function can also be called later too.

void gai_init_show_mouse_ptr(void)
If you changed your mind and want that the mouse pointer is shown, call this function. This function can be called in all faces.

Event hooks and timeouts


void gai_init_update_function(gai_function *applet_update)
Tells gai which function to call for updating the applet. This function is the heart of most applets.
gai_function is a void foo(void) function.

void gai_init_update_interval(int delay)
This is how often your applet_update() function shall be called in ms.

void gai_init_on_exit_function(gai_function *on_exit)
Tells the library that a function should be called when it's time to remove the applet.
void gai_init_enter_function(gai_function *applet_enter)
Function to call when the mouse pointer enters above the applet.

void gai_init_leave_function(gai_function *applet_leave)
Function to call when the mouse pointer leaves the applet area.

void gai_init_keypress_function(gai_function_int *applet_keypress)
Function to call when a key is pressed. gai_function_int is a void foo(int) where the int here is the key pressed. Look at gdk/gdkkeysym.h for the keys.

void gai_init_mouse_click1_function(gai_function_2int *applet_click1)
Function to call when the first mouse button is pressed. The applet_click1 is called with the X and Y coordinates of where the click occured. gai_function_2int is a void foo(int,int)

void gai_init_mouse_click2_function(gai_function_2int *applet_click2)
Function to call when the second mouse button is pressed. The applet_click2 is called with the X and Y coordinates of where the click occured. gai_function_2int is a void foo(int,int)
Notice that the third mouse button is reserved for Gnome and will be that for dockapps too. The third button brings up a menu with where you can choose preferences(if your applet has some preferences) and display the about box.

void gai_init_mouse_release1_function(gai_function_2int *applet_release1)
Function to call when the first mouse button is released. The applet_release1 is called with the X and Y coordinates of where the release occured. gai_function_2int is a void foo(int,int)

void gai_init_mouse_release2_function(gai_function_2int *applet_release2)
Function to call when the second mouse button is released. The applet_release2 is called with the X and Y coordinates of where the release occured. gai_function_2int is a void foo(int,int)

void gai_init_scroll_buttons_function(gai_function_int *applet_scroll)
Function to call when the mouse wheel is scrolled. The applet_scrolled is called with the direction of the scroll event. gai_function_int is a void foo(int)
The different scroll directions are:
GDK_SCROLL_UP, GDK_SCROLL_DOWN, GDK_SCROLL_LEFT and GDK_SCROLL_RIGHT


void gai_init_change_size_function(gai_function_3int *applet_change_size)
Function to call when Gnome panel's size of layout direction is changed. (In dockapp mode this function is never called.) But the library takes care of changing the size of the applet window and rotating it. This function is just there to report to the applet what sizes it has and they layout direction. Applet_change_size is called with first the orientation, can be (GAI_HORIZONTAL or GAI_VERTICAL) and then the new width and height. gai_function_3int is a void foo(int,int, int)

About window and preference window


void gai_init_about(char *version, char *text, char *authors, char *aboutimage)
Tells what to be shown in the about window. Version is the applet version, text is a short about text, authors are your data, aboutimage is a filename of an image to show in the about window. The image isn't required, you can set it to NULL, if you don't want an image. This function isn't required to be setup, but is really recommended.

Any image won't be displayed in gai 0.4.0!

void gai_init_about_set_license(char *text_str)
If your applet is under some other license than GPL, call this function with a text string explaining what license it's under.

void gai_init_preferences(void *preferences_function)
If your applet has a preferences window, this function registers it for you. This function isn't required to be called nor has must a preference_function exist.

void gai_init_preferences_simple(char *title, GaiNoteBook *, gai_function *restart)
This function takes a tree structure that starts with a GaiNoteBook entry. See the GAI preference guide for help how to set up preference window without too much work. The title is the name of the window and the gai_fucntion is to be called upon when the settings should be saved and the applet should be restarted with new fresh settings.
void gai_init_preferences_simple_set_help_text(char *help_text)
Set up what help text to display when the user presses the help button in the preference dialog


void gai_init_menu_set_help_text(char *text)
Set help text for right mouse button click menu.

void gai_init_menu_no_help(void)
Not in use any more. Menu help is off by default.


void gai_init_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 never return, if things went well.

Second face - Running
The functions here can only be called after gai_init_start() is called.
Misc functions

GdkWindow *gai_get_window(void)
Returns the GdkWindow of the applet. If you want to handle drawing yourself in your applet, you need to know the GdkWindow.

GtkWidget *gai_get_drawingarea(void)
Returns the drawingarea widget, if you for some reason needs to know it.

GdkGC *gai_get_gc(void)
If you need to know the GdkGC of the applet, you'll get it with this function.

int gai_get_size(void)
If you want to know how large the applet is. In dockapp mode it will always be what you decided the background to be during the initializing face. But in Gnome mode, this size is the size of the applet decided by Gnome.

int gai_scale(int)
If you wish to know how large say 64 is in the current size of the applet, call this function and the real size will be returned. Example, say that the applet is 64x64 from the begining, but Gnome made it 48x48(This isn't really show for the applet, if the applet doesn't want to know.) This function returns 24 on the input 32, size the real size is 48 of imaginary size 64.

void gai_tooltip_set(char *msg)
Makes a give message show up when you put the mouse pointer over the applet.

void gai_tooltip_remove(void)
Removes the current tooltip, if any.

void gai_update_interval_change(int delay)
Change the updating interval of how often your applet_update() function shall be called in ms.
Drawing
GAI fools the applet to believe that it is always in the original size, if the applet doesn't want to know. This is done because the Gnome panel can have very different size, between 16 pixels to 128 pixels height. The library takes care of all scaling.
Drawing functions - foreground

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

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) and each row, normal width*3, but not always has to be given too.

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

void gai_draw_update(void)
Updates the forground. Should be used for applets that requires speed.
Drawing functions - background
Drawing on the background is much slower than drawing on the foreground, but if you change the graphics of you applet more seldom than one a second, draw on the background to avoid that your applet can look "odd" between the update calls, for example if you move it or a window something above it and moves it.

void gai_draw_bg(GdkPixbuf *image, int sx, int sy, int sw, int sh, int dx, int dy)
Same as foreground version.

void gai_draw_raw_bg(unsigned char *rawRGB, int x, int y, int width, int height, int rowstride)
Same as foreground version.

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)
This updates the background pixmap. This call is pretty slow.
Saving 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.

void gai_save_int(char *name, int value)
Stores an integer.

void gai_save_bool(char *name, int value)
Stores a boolean.

void gai_save_float(char *name, float value)
Stores a float.

void gai_save_string(char *name, char *value)
Stores a string.

int gai_load_int_with_default(char *name, int default)
Loads an interger, and if isn't stored earlier the default value will be returned.

int gai_load_bool_with_default(char *name, int default)
Loads a bool, and if isn't stored earlier the default value will be returned.

float gai_load_float_with_default(char *name, float default)
Loads a float, and if isn't stored earlier the default value will be returned.

char *gai_load_string_with_default(char *name, char *default)
Loads a string, and if isn't stored earlier the default value will be returned.

Need help? Mail me then!