LibMB  1.9
Typedefs | Functions
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. More...
 
typedef void(* MBTrayAppPaintCB )(MBTrayApp *mb, Drawable drawable)
 Callback for a handling a 'paint' or expose event. More...
 
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. More...
 
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. More...
 
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. More...
 
void mb_tray_app_set_xevent_callback (MBTrayApp *mb_tray_app, MBTrayAppXEventCB xevent_cb)
 Sets the callback function for any extra x event processing. More...
 
void mb_tray_app_set_button_callback (MBTrayApp *mb_tray_app, MBTrayAppButtonEventCB button_cb)
 Sets the callback function for a mouse button press/release. More...
 
void mb_tray_app_set_theme_change_callback (MBTrayApp *mb_tray_app, MBTrayAppThemeChangeCB theme_cb)
 Sets the callback function for a theme change. More...
 
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. More...
 
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. More...
 
void mb_tray_app_set_paint_callback (MBTrayApp *mb_tray_app, MBTrayAppPaintCB paint_cb)
 Sets the callback function for panel app paint. More...
 
void mb_tray_app_set_context_callback (MBTrayApp *mb_tray_app, MBTrayAppContextCB context_cb)
 Sets the 'context' callback. More...
 
void mb_tray_app_request_size (MBTrayApp *mb_tray_app, int width, int height)
 Requests a new size for the application. More...
 
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. More...
 
void mb_tray_app_set_poll_timeout (MBTrayApp *mb_tray_app, struct timeval *tv)
 Set timing for any timeout callbacks. More...
 
void mb_tray_app_repaint (MBTrayApp *mb_tray_app)
 Requests the app is repainted - the paint callback will get called. More...
 
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. More...
 
void mb_tray_app_set_name (MBTrayApp *mb_tray_app, unsigned char *name)
 Sets the tray app name. More...
 
void mb_tray_app_set_context_info (MBTrayApp *mb_tray_app, unsigned char *info)
 Sets text for extra button in window message. More...
 
void mb_tray_app_set_icon (MBTrayApp *mb_tray_app, MBPixbuf *pixbuf, MBPixbufImage *image)
 Sets the tray app icon. More...
 
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. More...
 
Bool mb_tray_app_get_session (MBTrayApp *mb_tray_app)
 Get session state. More...
 
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. More...
 
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. More...
 
void * mb_tray_app_get_user_data (MBTrayApp *mb_tray_app)
 Gets any user data to be attached to the tray app instance. More...
 
MBPixbufImagemb_tray_app_get_background (MBTrayApp *mb_tray_app, MBPixbuf *pixbuf)
 Gets the panel background for the area covered by the tray app. More...
 
char * mb_tray_app_get_theme_name (MBTrayApp *mb_tray_app)
 Returns the current theme. More...
 
long mb_tray_app_get_xevent_mask (MBTrayApp *mb_tray_app)
 Returns the current X Event mask used by the tray app. More...
 
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. More...
 
Display * mb_tray_app_xdisplay (MBTrayApp *mb_tray_app)
 Gets the tray apps X display. More...
 
int mb_tray_app_xscreen (MBTrayApp *mb_tray_app)
 Gets the tray app X screen. More...
 
Window mb_tray_app_xrootwin (MBTrayApp *mb_tray_app)
 Gets the tray app root window. More...
 
Window mb_tray_app_xwin (MBTrayApp *mb_tray_app)
 Gets the tray app window. More...
 
int mb_tray_app_width (MBTrayApp *mb_tray_app)
 Gets the tray width. More...
 
int mb_tray_app_height (MBTrayApp *mb_tray_app)
 Gets the tray height. More...
 
int mb_tray_app_offset (MBTrayApp *mb_tray_app)
 Gets the apps offset from the panels origin. More...
 
void mb_tray_app_main_init (MBTrayApp *mb_tray_app)
 Inits the main loop. More...
 
void mb_tray_app_main (MBTrayApp *mb_tray_app)
 Runs the tray app main loop until mb_tray_app_main_quit is called. More...
 
void mb_tray_app_hide (MBTrayApp *mb_tray_app)
 Hides ( undocks ) the tray app. More...
 
void mb_tray_app_unhide (MBTrayApp *mb_tray_app)
 Unhides ( redocks ) the tray app. More...
 
void mb_tray_app_main_quit (MBTrayApp *mb_tray_app)
 Stops mb_tray_app_main. More...
 
void mb_tray_handle_xevent (MBTrayApp *mb_tray_app, XEvent *xevent)
 Runs a single iteration of the mainloop. More...
 

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

MBTrayAppPaintCB

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.

MBTrayAppResizeCB

Callback for a resize.

Is triggered when the panel resizes your application.

Definition at line 125 of file mbtray.h.

MBTrayAppXEventCB

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_appTray instance
xX co-ord
yY 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_appTray instance
pixbufmb 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_appTray 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_appTray 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_appTray 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_appTray instance
Returns
the current X event mask
int mb_tray_app_height ( MBTrayApp mb_tray_app)

Gets the tray height.

Parameters
mb_tray_appTray 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_appTray 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_appTray 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_appTray instance
void mb_tray_app_main_quit ( MBTrayApp mb_tray_app)

Stops mb_tray_app_main.

Parameters
mb_tray_appTray 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_nameName of tray application
resize_cbapplication resize callback
paint_cbapplication paint callback
argccommand line parameter count
argvcommand 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_nameName of tray application
resize_cbapplication resize callback
paint_cbapplication paint callback
argccommand line parameter count
argvcommand line parameter vector
displayPre-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_appTray 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_appTray 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_appTray instance
offsetThe 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_appTray instance
widthrequest width in pixels
heightrequest 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_appTray instance
button_cbbutton callback
void mb_tray_app_set_context_callback ( MBTrayApp mb_tray_app,
MBTrayAppContextCB  context_cb 
)

Sets the 'context' callback.

Parameters
mb_tray_appTray instance
context_cbcontext 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_appTray instance
infocontext button text
void mb_tray_app_set_icon ( MBTrayApp mb_tray_app,
MBPixbuf pixbuf,
MBPixbufImage image 
)

Sets the tray app icon.

Parameters
mb_tray_appTray instance
pixbufmbpixbuf ref
imagembpixbuf 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_appTray instance
nameThe 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_appTray instance
paint_cbpaint callback
void mb_tray_app_set_poll_timeout ( MBTrayApp mb_tray_app,
struct timeval *  tv 
)

Set timing for any timeout callbacks.

Parameters
mb_tray_appTray instance
tva 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_appTray instance
resize_cbtimeout 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_appTray instance
valBoolean 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_appTray instance
theme_cbtheme 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_appTray instance
poll_cbtimeout callback
tva 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_appTray instance
datavoid 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_appTray instance
xevent_cbx11 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_appTray instance
maskrequested 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_appTray instance
msgMessage to send ( assumed UTF8 )
timeoutTime in seconds for message to stay visible.
void mb_tray_app_unhide ( MBTrayApp mb_tray_app)

Unhides ( redocks ) the tray app.

Parameters
mb_tray_appTray instance
int mb_tray_app_width ( MBTrayApp mb_tray_app)

Gets the tray width.

Parameters
mb_tray_appTray 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_appTray instance
Returns
An Xlib display
Window mb_tray_app_xrootwin ( MBTrayApp mb_tray_app)

Gets the tray app root window.

Parameters
mb_tray_appTray instance
Returns
An Xlib root window
int mb_tray_app_xscreen ( MBTrayApp mb_tray_app)

Gets the tray app X screen.

Parameters
mb_tray_appTray instance
Returns
An Xlib screen
Window mb_tray_app_xwin ( MBTrayApp mb_tray_app)

Gets the tray app window.

Parameters
mb_tray_appTray 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_appTray instance
xeventX event to process