/* ghosd -- OSD with fake transparency, cairo, and pango.
 * Copyright (C) 2006 Evan Martin <martine@danga.com>
 */

#ifndef __GHOSD_H__
#define __GHOSD_H__

#include <cairo/cairo.h>

#include <values.h>  /* MAXINT */
#include <sys/time.h>  /* timeval */

typedef struct _Ghosd Ghosd;

typedef void (*GhosdRenderFunc)(Ghosd *ghosd, cairo_t *cr, void *user_data);

/**
 * ghosd_new:
 *
 * Create a new #Ghosd object.
 *
 * Can return %NULL if unable to connect to the X server.
 *
 * Returns: a new #Ghosd object.
 **/
Ghosd *ghosd_new(void);

/**
 * ghosd_set_transparent:
 * @ghosd: a #Ghosd object.
 * @transparent: a boolean indicating the transparent setting.
 *
 * Change the "transparent" setting.  Setting @transparent to %FALSE is
 * mostly useful for debugging.
 */
void ghosd_set_transparent(Ghosd *ghosd, int transparent);

#define GHOSD_COORD_CENTER MAXINT

/**
 * ghosd_set_position:
 * @ghosd: a #Ghosd object.
 * @x: x coordinate in screen pixels.
 * @y: y coordinate in screen pixels.
 * @width: width in screen pixels.
 * @height: width in screen pixels.
 *
 * Position the initial #Ghosd.  Must be called before ghosd_render() and
 * ghosd_show(), and can only be called once.
 *
 * Positive x,y are interpreted as normal coordinates.
 * Pass %GHOSD_COORD_CENTER to center on a given dimension,
 * and negative coordinates right-align (like CSS right).
 */
void ghosd_set_position(Ghosd *ghosd, int x, int y, int width, int height);

/**
 * ghosd_set_render:
 * @ghosd: a #Ghosd object.
 * @render_func: a #GhosdRenderFunc callback.
 * @data: user data to pass to the callback.
 *
 * Register a function to draw on the #Ghosd.
 */
void ghosd_set_render(Ghosd *ghosd, GhosdRenderFunc render_func, void* data);

/**
 * ghosd_render:
 * @ghosd: a #Ghosd object.
 *
 * Makes the Ghosd redraw itself.
 */
void ghosd_render(Ghosd *ghosd);

/**
 * ghosd_show:
 * @ghosd: a #Ghosd object.
 *
 * Show the #Ghosd.
 */
void ghosd_show(Ghosd *ghosd);

/**
 * ghosd_main_iterations:
 * @ghosd: a #Ghosd object.
 *
 * Iterate the main loop on the #Ghosd, handling all pending X events.
 * This function does not wait for X events, so it returns immediately
 * unless there are already events pending.
 */
void ghosd_main_iterations(Ghosd *ghosd);

/**
 * ghosd_main_until:
 * @ghosd: a #Ghosd object.
 * @until: a pointer to a timeval to update until.
 *
 * Efficiently iterate the main loop on the #Ghosd, handling all pending X
 * events, until the current time reaches the time specified in @until.
 */
void ghosd_main_until(Ghosd *ghosd, struct timeval *until);

/**
 * ghosd_flash:
 * @ghosd: a #Ghosd object.
 * @fade_ms: how long to fade, in milliseconds.
 * @total_display_ms: total display time, including fades, in milliseconds.
 *
 * Fade in a #Ghosd, display at full opacity for a while, fade out, and then
 * return.
 * This is easy enough to implement using ghosd_main_until(), but is a 
 * a common enough use of Ghosd to make it a builtin.
 */
void ghosd_flash(Ghosd *ghosd, int fade_ms, int total_display_ms);

/**
 * ghosd_get_socket:
 * @ghosd: a #Ghosd object.
 *
 * Get the file descriptor of the Ghosd X socket.  When this file descriptor
 * has data available, call ghosd_main_iterations() to process the pending X
 * events.  Use this with select()/poll() etc. to multiplex Ghosd with other
 * processing.
 *
 * Returns: a file descriptor, suitable for use in select() or poll().
 */
int ghosd_get_socket(Ghosd *ghosd);

#endif /* __GHOSD_H__ */