MBTray - System tray applet toolkit

A simple toolkit for creating xlib based tray ( aka panel ) 'applets'. More...

Typedefs

typedef struct MBTrayApp MBTrayApp
 Opaque structure used for representing a tray app.
typedef void(* MBTrayAppResizeCB )(MBTrayApp *mb, int width, int height)
 Callback for a resize.
typedef void(* MBTrayAppPaintCB )(MBTrayApp *mb, Drawable drawable)
 Callback for a handling a 'paint' or expose event.
typedef void(* MBTrayAppButtonEventCB )(MBTrayApp *mb_tray_app, int x, int y, Bool is_release)
 Callback for a button event.
typedef void(* MBTrayAppXEventCB )(MBTrayApp *mb_tray_app, XEvent *event)
 Callback for an X event.
typedef void(* MBTrayAppThemeChangeCB )(MBTrayApp *mb_tray_app, char *theme_name)
 Callback for a theme change.
typedef void(* MBTrayAppPollCB )(MBTrayApp *mb_tray_app)
 Callback for a Timeout event.

Functions

MBTrayAppmb_tray_app_new (unsigned char *app_name, MBTrayAppResizeCB resize_cb, MBTrayAppPaintCB paint_cb, int *argc, char ***argv)
 Constructs a new tray app instance.
MBTrayAppmb_tray_app_new_with_display (unsigned char *app_name, MBTrayAppResizeCB resize_cb, MBTrayAppPaintCB paint_cb, int *argc, char ***argv, Display *display)
 Constructs a new tray app instance.
void mb_tray_app_set_xevent_callback (MBTrayApp *mb_tray_app, MBTrayAppXEventCB xevent_cb)
 Sets the callback function for any extra x event processing.
void mb_tray_app_set_button_callback (MBTrayApp *mb_tray_app, MBTrayAppButtonEventCB button_cb)
 Sets the callback function for a mouse button press/release.
void mb_tray_app_set_theme_change_callback (MBTrayApp *mb_tray_app, MBTrayAppThemeChangeCB theme_cb)
 Sets the callback function for a theme change.
void mb_tray_app_set_timeout_callback (MBTrayApp *mb_tray_app, MBTrayAppPollCB poll_cb, struct timeval *tv)
 Sets the callback function for a theme change.
void mb_tray_app_set_resize_callback (MBTrayApp *mb_tray_app, MBTrayAppResizeCB resize_cb)
 Sets the callback function to be notifed when the panel app is resized.
void mb_tray_app_set_paint_callback (MBTrayApp *mb_tray_app, MBTrayAppPaintCB paint_cb)
 Sets the callback function for panel app paint.
void mb_tray_app_set_context_callback (MBTrayApp *mb_tray_app, MBTrayAppContextCB context_cb)
 Sets the 'context' callback.
void mb_tray_app_request_size (MBTrayApp *mb_tray_app, int width, int height)
 Requests a new size for the application.
void mb_tray_app_request_offset (MBTrayApp *mb_tray_app, int offset)
 Requests the app positional offset in terms of the panels orientation from the origin of the tray.
void mb_tray_app_set_poll_timeout (MBTrayApp *mb_tray_app, struct timeval *tv)
 Set timing for any timeout callbacks.
void mb_tray_app_repaint (MBTrayApp *mb_tray_app)
 Requests the app is repainted - the paint callback will get called.
void mb_tray_app_tray_send_message (MBTrayApp *mb_tray_app, unsigned char *msg, int timeout)
 Sends a messsage to the tray, used to visually inform or notify the user.
void mb_tray_app_set_name (MBTrayApp *mb_tray_app, unsigned char *name)
 Sets the tray app name.
void mb_tray_app_set_context_info (MBTrayApp *mb_tray_app, unsigned char *info)
 Sets text for extra button in window message.
void mb_tray_app_set_icon (MBTrayApp *mb_tray_app, MBPixbuf *pixbuf, MBPixbufImage *image)
 Sets the tray app icon.
void mb_tray_app_set_session (MBTrayApp *mb_tray_app, Bool val)
 Enable app to show session data so tray can 'remember it' for future sessions.
Bool mb_tray_app_get_session (MBTrayApp *mb_tray_app)
 Get session state.
Bool mb_tray_app_get_absolute_coords (MBTrayApp *mb_tray_app, int *x, int *y)
 Gets the tray app co-ordinates relative to the root window.
void mb_tray_app_set_user_data (MBTrayApp *mb_tray_app, void *data)
 Set any user data to be attached to the tray app instance.
void * mb_tray_app_get_user_data (MBTrayApp *mb_tray_app)
 Gets any user data to be attached to the tray app instance.
MBPixbufImage * mb_tray_app_get_background (MBTrayApp *mb_tray_app, MBPixbuf *pixbuf)
 Gets the panel background for the area covered by the tray app.
char * mb_tray_app_get_theme_name (MBTrayApp *mb_tray_app)
 Returns the current theme.
long mb_tray_app_get_xevent_mask (MBTrayApp *mb_tray_app)
 Returns the current X Event mask used by the tray app.
void mb_tray_app_set_xevent_mask (MBTrayApp *mb_tray_app, long mask)
 Safely sets the X Event mask used to select what events the xevent callback recieves.
Display * mb_tray_app_xdisplay (MBTrayApp *mb_tray_app)
 Gets the tray apps X display.
int mb_tray_app_xscreen (MBTrayApp *mb_tray_app)
 Gets the tray app X screen.
Window mb_tray_app_xrootwin (MBTrayApp *mb_tray_app)
 Gets the tray app root window.
Window mb_tray_app_xwin (MBTrayApp *mb_tray_app)
 Gets the tray app window.
int mb_tray_app_width (MBTrayApp *mb_tray_app)
 Gets the tray width.
int mb_tray_app_height (MBTrayApp *mb_tray_app)
 Gets the tray height.
int mb_tray_app_offset (MBTrayApp *mb_tray_app)
 Gets the apps offset from the panels origin.
void mb_tray_app_main_init (MBTrayApp *mb_tray_app)
 Inits the main loop.
void mb_tray_app_main (MBTrayApp *mb_tray_app)
 Runs the tray app main loop until mb_tray_app_main_quit is called.
void mb_tray_app_hide (MBTrayApp *mb_tray_app)
 Hides ( undocks ) the tray app.
void mb_tray_app_unhide (MBTrayApp *mb_tray_app)
 Unhides ( redocks ) the tray app.
void mb_tray_app_main_quit (MBTrayApp *mb_tray_app)
 Stops mb_tray_app_main.
void mb_tray_handle_xevent (MBTrayApp *mb_tray_app, XEvent *xevent)
 Runs a single iteration of the mainloop.

Detailed Description

A simple toolkit for creating xlib based tray ( aka panel ) 'applets'.

See System tray Spec and XEmbed Spec for infomation on the gory details of the mechanism.

Example: A very basic panel app. Displays an image and message when clicked on

 include <libmb/mb.h>

 MBPixbuf      *Pixbuf;
 MBPixbufImage *AppImage

 void
 paint_callback ( MBTrayApp *app, Drawable drw )
 {
   MBPixbufImage *img_scaled;

   img_scaled = mb_pixbuf_img_scale (Pixbuf, AppIcon,
 				    mb_tray_app_width(app),
 				    mb_tray_app_height(app));

   mb_pixbuf_img_render_to_drawable (Pixbuf, img_scaled, drw, 0, 0);

   mb_pixbuf_img_free( Pixbuf, img_scaled );
 }

 void
 button_callback (MBTrayApp *app, int x, int y, Bool is_released )
 {
   if (is_released)
     mb_tray_app_tray_send_message(app, "Hello World!", 10);
 }

 int 
 main(int argc, char **argv)
 {
   MBTrayApp *app = NULL;

   app = mb_tray_app_new ( "Tray Demo App",
 			  NULL,
 			  paint_callback,
 			  &argc,
 			  &argv );

   if (app == NULL) usage();

   Pixbuf = mb_pixbuf_new(mb_tray_app_xdisplay(app), 
 			 mb_tray_app_xscreen(app));

   AppImage = mb_pixbuf_img_new_from_file(Pixbuf, "some_image.png")

   mb_tray_app_set_button_callback (app, button_callback );

   mb_tray_app_main(app);
 }

 

There are also numerous other examples in the matchbox distrubution source ( see the util directory ). These should give you more infomation on handling resizes etc.


Typedef Documentation

Callback for a handling a 'paint' or expose event.

Callback for a handling a 'context' message.

You application should paint to the supplied X Drawable. Also see mb_tray_app_get_background for getting a MBPixbufImg representation of the panel area below your application. Using this you can alpha composite you application to the panel.

You should make sure you paint the entire supplied drawable.

if mb_tray_set_context_info has been called, this callback will be triggered when a user clicks on the bubble message context text.

Definition at line 139 of file mbtray.h.

Callback for a resize.

Is triggered when the panel resizes your application.

Definition at line 125 of file mbtray.h.

Callback for an X event.

Also see mb_tray_app_get_xevent_mask and mb_tray_app_set_xevent_mask

Definition at line 168 of file mbtray.h.


Function Documentation

Bool mb_tray_app_get_absolute_coords ( MBTrayApp mb_tray_app,
int *  x,
int *  y 
)

Gets the tray app co-ordinates relative to the root window.

Parameters:
mb_tray_app Tray instance
x X co-ord
y Y co-ord
Returns:
True on success, False on faliure

MBPixbufImage* mb_tray_app_get_background ( MBTrayApp mb_tray_app,
MBPixbuf *  pixbuf 
)

Gets the panel background for the area covered by the tray app.

Parameters:
mb_tray_app Tray instance
pixbuf mb pixbuf object
Returns:
an mbpixbuf of the panel background covered by the panel app.

Bool mb_tray_app_get_session ( MBTrayApp mb_tray_app  ) 

Get session state.

Parameters:
mb_tray_app Tray instance
Returns:
True is sessioning active, False otherwise

char* mb_tray_app_get_theme_name ( MBTrayApp mb_tray_app  ) 

Returns the current theme.

Parameters:
mb_tray_app Tray instance
Returns:
the name of the current theme, or NULL if no theme is set.

void* mb_tray_app_get_user_data ( MBTrayApp mb_tray_app  ) 

Gets any user data to be attached to the tray app instance.

Parameters:
mb_tray_app Tray instance
Returns:
the user data.

long mb_tray_app_get_xevent_mask ( MBTrayApp mb_tray_app  ) 

Returns the current X Event mask used by the tray app.

Parameters:
mb_tray_app Tray instance
Returns:
the current X event mask

int mb_tray_app_height ( MBTrayApp mb_tray_app  ) 

Gets the tray height.

Parameters:
mb_tray_app Tray instance
Returns:
the tray apps height in pixels

void mb_tray_app_hide ( MBTrayApp mb_tray_app  ) 

Hides ( undocks ) the tray app.

Parameters:
mb_tray_app Tray instance

void mb_tray_app_main ( MBTrayApp mb_tray_app  ) 

Runs the tray app main loop until mb_tray_app_main_quit is called.

Parameters:
mb_tray_app Tray instance

void mb_tray_app_main_init ( MBTrayApp mb_tray_app  ) 

Inits the main loop.

Only needed if you plan on not using mbtrays main loop - eg if using with GTK.

Parameters:
mb_tray_app Tray instance

void mb_tray_app_main_quit ( MBTrayApp mb_tray_app  ) 

Stops mb_tray_app_main.

Parameters:
mb_tray_app Tray instance

MBTrayApp* mb_tray_app_new ( unsigned char *  app_name,
MBTrayAppResizeCB  resize_cb,
MBTrayAppPaintCB  paint_cb,
int *  argc,
char ***  argv 
)

Constructs a new tray app instance.

After calling this, one should then set other required callbacks before starting the panels event loop with mb_tray_app_main ( The actaul docking process occurs here ).

The resize_cb will get called when you panel resizes your application. See MBTrayAppResizeCB

The paint_cb will get called when your application recieves an expose expose event and should update its contents accordingly. See MBTrayAppPaintCB

mb_tray_app_new will check for and remove the arguments from argv;

  • --display, -d <Display> X11 Display to connect to
  • --offset, -o <+-integer> requested panel position

NOTES: The enviromental var 'SYSTEM_TRAY_ID' will read if set. This specifys the system tray to connect to. Defaults to 1.

Parameters:
app_name Name of tray application
resize_cb application resize callback
paint_cb application paint callback
argc command line parameter count
argv command line parameter vector
Returns:
a MBTrayApp object, NULL on failiure.

MBTrayApp* mb_tray_app_new_with_display ( unsigned char *  app_name,
MBTrayAppResizeCB  resize_cb,
MBTrayAppPaintCB  paint_cb,
int *  argc,
char ***  argv,
Display *  display 
)

Constructs a new tray app instance.

Just like mb_tray_app_new , but allow the X Display to be specified. This function is intended to aid integration with toolkits like Gtk.

Parameters:
app_name Name of tray application
resize_cb application resize callback
paint_cb application paint callback
argc command line parameter count
argv command line parameter vector
display Pre-existing X Display
Returns:
a MBTrayApp object, NULL on failiure.

int mb_tray_app_offset ( MBTrayApp mb_tray_app  ) 

Gets the apps offset from the panels origin.

Parameters:
mb_tray_app Tray instance
Returns:
the current offset

void mb_tray_app_repaint ( MBTrayApp mb_tray_app  ) 

Requests the app is repainted - the paint callback will get called.

Parameters:
mb_tray_app Tray instance

void mb_tray_app_request_offset ( MBTrayApp mb_tray_app,
int  offset 
)

Requests the app positional offset in terms of the panels orientation from the origin of the tray.

Note its unlikely many trays will allow free positioning. The matchbox tray uses positive/negative offset values to determine what side of the tray the app is located on docking.

Parameters:
mb_tray_app Tray instance
offset The panel app offset

void mb_tray_app_request_size ( MBTrayApp mb_tray_app,
int  width,
int  height 
)

Requests a new size for the application.

It is not guarenteed your app will get this size. Your application should expected to handle the size supplied to it ( via the resize callback).

You should take care with this function as not to end up in an infinite loop continually re-requesting the same failed parameters.

Parameters:
mb_tray_app Tray instance
width request width in pixels
height request height in pixels

void mb_tray_app_set_button_callback ( MBTrayApp mb_tray_app,
MBTrayAppButtonEventCB  button_cb 
)

Sets the callback function for a mouse button press/release.

Parameters:
mb_tray_app Tray instance
button_cb button callback

void mb_tray_app_set_context_callback ( MBTrayApp mb_tray_app,
MBTrayAppContextCB  context_cb 
)

Sets the 'context' callback.

Parameters:
mb_tray_app Tray instance
context_cb context callback

void mb_tray_app_set_context_info ( MBTrayApp mb_tray_app,
unsigned char *  info 
)

Sets text for extra button in window message.

Parameters:
mb_tray_app Tray instance
info context button text

void mb_tray_app_set_icon ( MBTrayApp mb_tray_app,
MBPixbuf *  pixbuf,
MBPixbufImage *  image 
)

Sets the tray app icon.

Parameters:
mb_tray_app Tray instance
pixbuf mbpixbuf ref
image mbpixbuf image to set as icon

void mb_tray_app_set_name ( MBTrayApp mb_tray_app,
unsigned char *  name 
)

Sets the tray app name.

Parameters:
mb_tray_app Tray instance
name The tray app name

void mb_tray_app_set_paint_callback ( MBTrayApp mb_tray_app,
MBTrayAppPaintCB  paint_cb 
)

Sets the callback function for panel app paint.

Parameters:
mb_tray_app Tray instance
paint_cb paint callback

void mb_tray_app_set_poll_timeout ( MBTrayApp mb_tray_app,
struct timeval *  tv 
)

Set timing for any timeout callbacks.

Parameters:
mb_tray_app Tray instance
tv a timeval struct specifying the timeout. Pass NUll to clear any timeout callbacks.

void mb_tray_app_set_resize_callback ( MBTrayApp mb_tray_app,
MBTrayAppResizeCB  resize_cb 
)

Sets the callback function to be notifed when the panel app is resized.

Parameters:
mb_tray_app Tray instance
resize_cb timeout callback

void mb_tray_app_set_session ( MBTrayApp mb_tray_app,
Bool  val 
)

Enable app to show session data so tray can 'remember it' for future sessions.

Defaults to True

Parameters:
mb_tray_app Tray instance
val Boolean indicating action

void mb_tray_app_set_theme_change_callback ( MBTrayApp mb_tray_app,
MBTrayAppThemeChangeCB  theme_cb 
)

Sets the callback function for a theme change.

Parameters:
mb_tray_app Tray instance
theme_cb theme callback

void mb_tray_app_set_timeout_callback ( MBTrayApp mb_tray_app,
MBTrayAppPollCB  poll_cb,
struct timeval *  tv 
)

Sets the callback function for a theme change.

Parameters:
mb_tray_app Tray instance
poll_cb timeout callback
tv a timeval struct specifying the timeout.

void mb_tray_app_set_user_data ( MBTrayApp mb_tray_app,
void *  data 
)

Set any user data to be attached to the tray app instance.

Parameters:
mb_tray_app Tray instance
data void pointer to user data

void mb_tray_app_set_xevent_callback ( MBTrayApp mb_tray_app,
MBTrayAppXEventCB  xevent_cb 
)

Sets the callback function for any extra x event processing.

Also see mb_tray_app_get_xevent_mask and mb_tray_app_set_xevent_mask

Parameters:
mb_tray_app Tray instance
xevent_cb x11 event callback

void mb_tray_app_set_xevent_mask ( MBTrayApp mb_tray_app,
long  mask 
)

Safely sets the X Event mask used to select what events the xevent callback recieves.

Parameters:
mb_tray_app Tray instance
mask requested X event mask

void mb_tray_app_tray_send_message ( MBTrayApp mb_tray_app,
unsigned char *  msg,
int  timeout 
)

Sends a messsage to the tray, used to visually inform or notify the user.

Parameters:
mb_tray_app Tray instance
msg Message to send ( assumed UTF8 )
timeout Time in seconds for message to stay visible.

void mb_tray_app_unhide ( MBTrayApp mb_tray_app  ) 

Unhides ( redocks ) the tray app.

Parameters:
mb_tray_app Tray instance

int mb_tray_app_width ( MBTrayApp mb_tray_app  ) 

Gets the tray width.

Parameters:
mb_tray_app Tray instance
Returns:
the tray apps width in pixels

Display* mb_tray_app_xdisplay ( MBTrayApp mb_tray_app  ) 

Gets the tray apps X display.

Parameters:
mb_tray_app Tray instance
Returns:
An Xlib display

Window mb_tray_app_xrootwin ( MBTrayApp mb_tray_app  ) 

Gets the tray app root window.

Parameters:
mb_tray_app Tray instance
Returns:
An Xlib root window

int mb_tray_app_xscreen ( MBTrayApp mb_tray_app  ) 

Gets the tray app X screen.

Parameters:
mb_tray_app Tray instance
Returns:
An Xlib screen

Window mb_tray_app_xwin ( MBTrayApp mb_tray_app  ) 

Gets the tray app window.

Parameters:
mb_tray_app Tray instance
Returns:
An Xlib window

void mb_tray_handle_xevent ( MBTrayApp mb_tray_app,
XEvent *  xevent 
)

Runs a single iteration of the mainloop.

Parameters:
mb_tray_app Tray instance
xevent X event to process


Generated on Tue Mar 25 11:24:01 2008 for LibMB by  doxygen 1.5.5