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

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

## MBTrayAppPaintCB

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

MBTrayAppResizeCB

Callback for a resize.

Is triggered when the panel resizes your application.

Definition at line 125 of file mbtray.h.

## MBTrayAppXEventCB

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

## mb_tray_app_get_absolute_coords()

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

## mb_tray_app_get_background()

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.

## mb_tray_app_get_session()

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

## mb_tray_app_get_theme_name()

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.

## mb_tray_app_get_user_data()

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.

## mb_tray_app_get_xevent_mask()

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

## mb_tray_app_height()

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

## mb_tray_app_hide()

void mb_tray_app_hide | ( | MBTrayApp * | mb_tray_app | ) |

Hides ( undocks ) the tray app.

Parameters

  mb_tray_app | Tray instance

## mb_tray_app_main()

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

## mb_tray_app_main_init()

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

## mb_tray_app_main_quit()

void mb_tray_app_main_quit | ( | MBTrayApp * | mb_tray_app | ) |

Stops mb_tray_app_main.

Parameters

  mb_tray_app | Tray instance

## mb_tray_app_new()

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.

## mb_tray_app_new_with_display()

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.

## mb_tray_app_offset()

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

## mb_tray_app_repaint()

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

## mb_tray_app_request_offset()

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

## mb_tray_app_request_size()

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

## mb_tray_app_set_button_callback()

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

## mb_tray_app_set_context_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

## mb_tray_app_set_context_info()

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

## mb_tray_app_set_icon()

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

## mb_tray_app_set_name()

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

## mb_tray_app_set_paint_callback()

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

## mb_tray_app_set_poll_timeout()

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.

## mb_tray_app_set_resize_callback()

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

## mb_tray_app_set_session()

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

## mb_tray_app_set_theme_change_callback()

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

## mb_tray_app_set_timeout_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.

## mb_tray_app_set_user_data()

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

## mb_tray_app_set_xevent_callback()

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

## mb_tray_app_set_xevent_mask()

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

## mb_tray_app_tray_send_message()

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.

## mb_tray_app_unhide()

void mb_tray_app_unhide | ( | MBTrayApp * | mb_tray_app | ) |

Unhides ( redocks ) the tray app.

Parameters

  mb_tray_app | Tray instance

## mb_tray_app_width()

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

## mb_tray_app_xdisplay()

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

## mb_tray_app_xrootwin()

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

## mb_tray_app_xscreen()

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

## mb_tray_app_xwin()

Window mb_tray_app_xwin | ( | MBTrayApp * | mb_tray_app | ) |

Gets the tray app window.

Parameters

  mb_tray_app | Tray instance

Returns
  An Xlib window

## mb_tray_handle_xevent()

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