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. |
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.
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.
Callback for an X event.
Also see mb_tray_app_get_xevent_mask and mb_tray_app_set_xevent_mask
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.
mb_tray_app | Tray instance | |
x | X co-ord | |
y | Y co-ord |
MBPixbufImage* mb_tray_app_get_background | ( | MBTrayApp * | mb_tray_app, | |
MBPixbuf * | pixbuf | |||
) |
Gets the panel background for the area covered by the tray app.
mb_tray_app | Tray instance | |
pixbuf | mb pixbuf object |
Bool mb_tray_app_get_session | ( | MBTrayApp * | mb_tray_app | ) |
Get session state.
mb_tray_app | Tray instance |
char* mb_tray_app_get_theme_name | ( | MBTrayApp * | mb_tray_app | ) |
Returns the current theme.
mb_tray_app | Tray instance |
void* mb_tray_app_get_user_data | ( | MBTrayApp * | mb_tray_app | ) |
Gets any user data to be attached to the tray app instance.
mb_tray_app | Tray instance |
long mb_tray_app_get_xevent_mask | ( | MBTrayApp * | mb_tray_app | ) |
Returns the current X Event mask used by the tray app.
mb_tray_app | Tray instance |
int mb_tray_app_height | ( | MBTrayApp * | mb_tray_app | ) |
Gets the tray height.
mb_tray_app | Tray instance |
void mb_tray_app_hide | ( | MBTrayApp * | mb_tray_app | ) |
Hides ( undocks ) the tray app.
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.
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.
mb_tray_app | Tray instance |
void mb_tray_app_main_quit | ( | MBTrayApp * | mb_tray_app | ) |
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;
NOTES: The enviromental var 'SYSTEM_TRAY_ID' will read if set. This specifys the system tray to connect to. Defaults to 1.
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 |
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.
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 |
int mb_tray_app_offset | ( | MBTrayApp * | mb_tray_app | ) |
Gets the apps offset from the panels origin.
mb_tray_app | Tray instance |
void mb_tray_app_repaint | ( | MBTrayApp * | mb_tray_app | ) |
Requests the app is repainted - the paint callback will get called.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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
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.
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.
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.
mb_tray_app | Tray instance |
int mb_tray_app_width | ( | MBTrayApp * | mb_tray_app | ) |
Gets the tray width.
mb_tray_app | Tray instance |
Display* mb_tray_app_xdisplay | ( | MBTrayApp * | mb_tray_app | ) |
Gets the tray apps X display.
mb_tray_app | Tray instance |
Window mb_tray_app_xrootwin | ( | MBTrayApp * | mb_tray_app | ) |
Gets the tray app root window.
mb_tray_app | Tray instance |
int mb_tray_app_xscreen | ( | MBTrayApp * | mb_tray_app | ) |
Gets the tray app X screen.
mb_tray_app | Tray instance |
Window mb_tray_app_xwin | ( | MBTrayApp * | mb_tray_app | ) |
Gets the tray app window.
mb_tray_app | Tray instance |
void mb_tray_handle_xevent | ( | MBTrayApp * | mb_tray_app, | |
XEvent * | xevent | |||
) |
Runs a single iteration of the mainloop.
mb_tray_app | Tray instance | |
xevent | X event to process |