Sophie: libgai0-devel-0.5.0-0.pre3.1mdk i586

libgai0-devel-0.5.0-0.pre3.1mdk.i586.rpm

<html>
<head><title>The General Applet Interface library (GAI) specification</title></head>
</html>
<body>
<h3>The General Applet Interface Library (GAI) - Specification Version 0.2.0</h3>
Written by Jonas Aaberg <cja@gmx.net> 2003
<br><hr>

<h2>NOT FULLY UPDATED TO GAI 0.5.0!</h2><br>

<h4>Purpose</h4>

To give the programmers one simple interface for both Gnome 2 panel
applets and WindowMaker applets(sometimes called dockapps) so they can
consentrate on what's important, the applet itself. Also the goal is
to give the user the flexibility to use the applets as normal WindowMaker 
applets or as Gnome 2 panel applets.
<br><br>

<h4>Changes from specification 0.1.1</h4><br>
The changes from earlier specifications are large. The main goals of the API changes were
to reduce the number of library calls and give the resiting ones more intuiative names.<br>
<br>

<h4>Library calls:</h4>


<h5>First face - Init</h5>
All functions here can only be called during the initialization face, if not otherwise is said.
<br><br>
<hr>
<br><b>int gai_init(char *name, char *version, char *image_path, int *argc, char **argv)</b><br>

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 GAI_*.server
file. Otherwise gnome can't find it and start it correctly.
<br>Example:<br><br>
<i>gai_init(APPLET_NAME, APPLET_VERSION, IMAGE_PATH. &argc, &argv); </i><br><br>
IMAGE_PATH is where the images, if the applet will use some, will be installed. During
development you can have for example "./images/" as your IMAGE_PATH, if your applet's images 
are in a directory below the current directory named images.<br><br>
APPLET_NAME, APPLET_VERSION and IMAGE_PATH are setup or generated by the
configure/makefile scripts and delivered to the applet during compile time.
<br>
This call also initialize GTK+ and Gnome, if the library is compiled with Gnome
support. So no need for gtk_init(..) nor gnome_init(..)<br>

<br>
Returns 0 if everything went well, something else if something isn't working as expected.<br>

<br>
<br>
<h6> Background handling </h6>


<br><b>void gai_background_set(int width, int height, int max_size, int border)</b><br>

The default and start-up background. Normally for dockapps the background
should be a 64x64 image with a border giving a drawing area of 56x56 on 4x4. This
is the default library settings if no function connected to the background is
called during the initialization face.
But if wished the applet can be of any side. Gnome supports quite many different 
sizes, and some window managers supports dockapps with other sizes too.<br>
The third argument, int max_size tells the library if it's ok to resize the
applet so it fills out the space the gnome panel gives it. If it's a possitive
number, the applet won't become larger than that number or if you pass with
GAI_BACKGROUND_MAX_SIZE_NONE, the library scales the applet as it finds suitable.
The border argument tells the library if there shall be a 4 pixels wide border
around the applet. Send with TRUE when you want a border, FALSE when you don't want a
border.<br>
Notice that it's always the height that counts for max_size. (Default layout for the
gnome panel is horizontal, and when it's vertical, the library takes care of it.)
<br>


<br><b>void gai_background_from_xpm(const char **xpmimagename, int max_size)</b><br>
Sets the background to an predefined XPM image. The max_size argument can either
be a possitive value for limiting the maximum size(see gai_background_set(..) for
more details. Or the max_size can be GAI_BACKGROUND_MAX_SIZE_NONE for no size
limits or GAI_BACKGROUND_MAX_SIZE_IMAGE when the applet never shall be larger
than the XPM image's default size.<br>
Notice that it's always the height that counts for max_size. (Default layout for the
gnome panel is horizontal, and when it's vertical, the library takes care of it.)
<br>

<br><b>void gai_background_from_gdkpixbuf(GdkPixbuf *pixbuf, int max_size)</b><br>
For GdkPixbufs. See gai_background_from_xpm(..).
<br>

<br><b>void gai_background_from_file(const char *image_file, int max_size)</b><br>
Works the same as gai_background_from_xpm but for images stored in files. Notice that
IMAGE_PATH must be correctly passed with during gai_init(). If the file that is
pointed out isn't found a message box is shown to inform the user that the image
can't be loaded and then the applet quits.  
<br>


<h6> Image loading </h6><br>
<br><b>GdkPixbuf *gai_load_image(char *imagefilename)</b><br>
Loads an image into a GdkPixbuf struct for runtime use. See
gdk-pixbuf itself for help how to use GdkPixbuf. (The gdk-pixbuf library is
very nice. It's included in gtk+ nowadays)<br>
This function can be called in all faces.
<br>
If a file is missing it displays an error dialog and quits.
<br>

<h6> Right button menu </h6><br>
<i>In the future, it shall be possible to add your own menu items. But now only the help
item is customize able</i><br>
<br><b>void gai_menu_add_help_text(const char *msg)</b><br>
This will add a menu item named "Help" with the right help icon. And when selected, the
passed textstring will displayed in a message box<br>
<br>

<h6> Text handling </h6><br>

<br><b>GdkPixbuf *gai_text_create(char *msg, char *font, int font_size, int feature, char red, char green, char blue)</b><br>
This function renders a given text string using Pango and PangoFT2 into a GdkPixbuf. It's possible that
newlines are not supported. The font shall be just "times", "arial" or "utopia". Please try to use a font that
is installed by default on most systems. The font_size is the font size just like in any wordprocessor.
Possible font features are;<br>
<b>GAI_TEXT_NORMAL</b> - Just plain normal text<br>
<b>GAI_TEXT_BOLD</b> - Bold text<br>
<b>GAI_TEXT_ITALIC</b> - Italic text<br>
<b>GAI_TEXT_SMOOTH</b> - Smooth the rendered text alittle<br>
Red, green and blue are just normal 0-255 weighted colour components. <br>
<br>






<br>
<h6> Special calls </h6>


<br><b>void gai_flags_set(GaiFlagsType flags)</b><br>
Sets some behavoir flags. The rotate flags just make a difference on the Gnome Panel. Ofcourse,
you can't send both GAI_FLAGS_MOUSE_PTR_HIDE and GAI_FLAGS_MOUSE_PTR_SHOW and expect a good
result. Both are there so you can change just one setting without changing the others.
Only the flags sent will be changed, the others will be unchanged.

<b>GAI_FLAGS_MOUSE_PTR_HIDE</b> - Hide the mouse pointer when it's over the applet<br>
<b>GAI_FLAGS_MOUSE_PTR_SHOW</b> - Show mouse pointer - (Default><br>
<b>GAI_FLAGS_ALLOW_ROTATE</b> - Allow gai to rotate no-rectangular applets.(Default)<br>
<b>GAI_FLAGS_NEVER_RORATE</b> - Never try to rotate an applet, no matter how it looks like.<br>

<br><b>GaiFlagsType gai_flags_get(void)</b><br>
Returns the current flags. Default settings are GAI_FLAGS_MOUSE_PTR_SHOW and GAI_FLAGS_ALLOW_ROTATE.
<br>

<br>
<h6>Event hooks and timeouts</h6>
<br>

<br><b>void gai_signal_onupdate_function(gai_function *applet_update)</b><br>

Tells gai which function to call for updating the applet. This function is the heart of most
applets.<br>
<i>gai_function</i> is a <i>void foo(void)</i> function.
<br>

<br><b>void gai_init_update_interval(int delay)</b><br>
This is how often your applet_update() function shall be called in ms. <br>

<br><b>void gai_signal_onon_exit_function(gai_function *on_exit)</b><br>
Tells the library that a function should be called when it's time to
remove the applet.

<br><b>void gai_signal_on_enter(gai_function *applet_enter)</b><br>
Function to call when the mouse pointer enters above the applet.
<br>

<br><b>void gai_init_leave_function(gai_function *applet_leave)</b><br>
Function to call when the mouse pointer leaves the applet area.
<br>

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

<br><b>void gai_init_mouse_click1_function(gai_function_2int *applet_click1)</b><br>
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. <i>gai_function_2int</i> is a 
<i>void foo(int,int)</i>
<br>

<br><b>void gai_init_mouse_click2_function(gai_function_2int *applet_click2)</b><br>
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. <i>gai_function_2int</i> is a 
<i>void foo(int,int)</i><br>
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.
<br>

<br><b>void gai_init_mouse_release1_function(gai_function_2int *applet_release1)</b><br>
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. <i>gai_function_2int</i> is a 
<i>void foo(int,int)</i>
<br>

<br><b>void gai_init_mouse_release2_function(gai_function_2int *applet_release2)</b><br>
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. <i>gai_function_2int</i> is a 
<i>void foo(int,int)</i>
<br>


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

<br>

<br><b>void gai_init_change_size_function(gai_function_3int *applet_change_size)</b><br>
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.
<i>gai_function_3int</i> is a <i>void foo(int,int, int)</i>
<br>


<br>
<h6> About window and preference window</h6>
<br>


<br><b>void gai_init_about_from(const char *text)</b><br>
A simplified version of creating the about window. Just send in
a string with "summary,author,description,icon,license" as keywords
and it will extract the data itself. The syntax is the same as of
a .spec file.<br>
Notice that the icon part isn't implemented yet.
<br>


<br><b>void gai_preferences(void *preferences_function)</b><br>
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.
<br>
<br><b>void gai_init_preferences_simple(char *title, GaiNoteBook *, gai_function *restart)</b><br>
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.

<br><b>void gai_init_preferences_simple_set_help_text(char *help_text)</b><br>
Set up what help text to display when the user presses the help button in the preference
dialog<br>
<br>


<br><b>void gai_start(void)</b><br>
When all things are ready for running, call this function and the applet will be drawn 
and displayed. This function <b>MUST</b> be called last after all other things are done.
This function will never return, if things went well.
<br>

<hr>


<h5>Second face - Running</h5>
The functions here can only be called after gai_init_start() is called.<br>

<h6> Misc functions</h6>

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

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

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

<br><b>int gai_get_size(void)</b><br>
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.
<br>
<br><b>int gai_scale(int)</b><br>
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.<br>

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

<br><b>void gai_tooltip_remove(void)</b><br>
Removes the current tooltip, if any. <br>

<br><b>void gai_update_interval_change(int delay)</b><br>
Change the updating interval of how often your applet_update() 
function shall be called in ms. <br>



<h5>Drawing</h5>
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.<br>
<i>For best results on the Gnome panel, don't draw on the background. You can try,
but the result isn't always nice. I don't know why.</i>

<h6>Drawing functions - foreground</h6>

<br><b>void gai_draw(GdkPixbuf *image, int sx, int sy, int sw, int sh, int dx, int dy)</b><br>
Draws the gdkPixbuf image from (sx,sy) that is (sw, sh) large at (dx,dy).<br>

<br><b>void gai_draw_raw(unsigned char *rawRGB, int x, int y, int width, int height, int rowstride)</b><br>
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.<br>
<br><b>void gai_draw_raw_alpha(unsigned char *rawRGBA, int x, int y, int width, int height, int rowstride)</b><br>
The same as above, but with an alpha channel<br>


<br><b>void gai_draw_update(void)</b><br>
Updates the forground. Should be used for applets that requires speed.<br>

<h6>Drawing functions - background</h6>
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.<br>


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

<br><b>void gai_draw_raw_bg(unsigned char *rawRGB, int x, int y, int width, int height, int rowstride)</b><br>
Same as foreground version.<br>
<br><b>void gai_draw_raw_alpha_bg(unsigned char *rawRGBA, int x, int y, int width, int height, int rowstride)</b><br>


<br><b>void gai_draw_update_bg(void)</b><br>
This updates the background pixmap. This call is pretty slow.<br>


<h6>Saving settings</h6>

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


<br><b>void gai_save_int(char *name, int value)</b><br>
Stores an integer.<br>

<br><b>void gai_save_bool(char *name, int value)</b><br>
Stores a boolean.<br>

<br><b>void gai_save_float(char *name, float value)</b><br>
Stores a float.<br>

<br><b>void gai_save_string(char *name, char *value)</b><br>
Stores a string.<br>

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

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

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

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

<hr>
<i>Need help? Then mail me, Jonas Aaberg, cja at gmx dot net.</i><br>

</body>
</html>