A simple toolkit for creating xlib based tray ( aka panel ) 'applets'.
More...
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
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.
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
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:
-
- Returns:
- True is sessioning active, False otherwise
char* mb_tray_app_get_theme_name |
( |
MBTrayApp * |
mb_tray_app | ) |
|
Returns the current theme.
- Parameters:
-
- 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:
-
- 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:
-
- Returns:
- the current X event mask
int mb_tray_app_height |
( |
MBTrayApp * |
mb_tray_app | ) |
|
Gets the tray height.
- Parameters:
-
- Returns:
- the tray apps height in pixels
void mb_tray_app_hide |
( |
MBTrayApp * |
mb_tray_app | ) |
|
Hides ( undocks ) the tray app.
- Parameters:
-
void mb_tray_app_main |
( |
MBTrayApp * |
mb_tray_app | ) |
|
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:
-
void mb_tray_app_main_quit |
( |
MBTrayApp * |
mb_tray_app | ) |
|
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.
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:
-
- 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:
-
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 |
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 |
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 |
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. |
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 |
Sets the callback function for a theme change.
- Parameters:
-
mb_tray_app | Tray instance |
theme_cb | theme callback |
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_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:
-
int mb_tray_app_width |
( |
MBTrayApp * |
mb_tray_app | ) |
|
Gets the tray width.
- Parameters:
-
- Returns:
- the tray apps width in pixels
Display* mb_tray_app_xdisplay |
( |
MBTrayApp * |
mb_tray_app | ) |
|
Gets the tray apps X display.
- Parameters:
-
- Returns:
- An Xlib display
Window mb_tray_app_xrootwin |
( |
MBTrayApp * |
mb_tray_app | ) |
|
Gets the tray app root window.
- Parameters:
-
- Returns:
- An Xlib root window
int mb_tray_app_xscreen |
( |
MBTrayApp * |
mb_tray_app | ) |
|
Gets the tray app X screen.
- Parameters:
-
- Returns:
- An Xlib screen
Window mb_tray_app_xwin |
( |
MBTrayApp * |
mb_tray_app | ) |
|
Gets the tray app window.
- Parameters:
-
- 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 |