git.sur5r.net Git - i3/i3/blob - include/libi3.h

   1 /*
   2  * vim:ts=4:sw=4:expandtab
   3  *
   4  * i3 - an improved dynamic tiling window manager
   5  * © 2009-2013 Michael Stapelberg and contributors (see also: LICENSE)
   6  *
   7  * libi3: contains functions which are used by i3 *and* accompanying tools such
   8  * as i3-msg, i3-config-wizard, …
   9  *
  10  */
  11 #ifndef I3_LIBI3_H
  12 #define I3_LIBI3_H
  13
  14 #include <stdbool.h>
  15 #include <stdarg.h>
  16 #include <stdio.h>
  17 #include <xcb/xcb.h>
  18 #include <xcb/xproto.h>
  19 #include <xcb/xcb_keysyms.h>
  20
  21 #if PANGO_SUPPORT
  22 #include <pango/pango.h>
  23 #endif
  24
  25 /**
  26  * Opaque data structure for storing strings.
  27  *
  28  */
  29 typedef struct _i3String i3String;
  30
  31 typedef struct Font i3Font;
  32
  33 /**
  34  * Data structure for cached font information:
  35  * - font id in X11 (load it once)
  36  * - font height (multiple calls needed to get it)
  37  *
  38  */
  39 struct Font {
  40     /** The type of font */
  41     enum {
  42         FONT_TYPE_NONE = 0,
  43         FONT_TYPE_XCB,
  44         FONT_TYPE_PANGO
  45     } type;
  46
  47     /** The height of the font, built from font_ascent + font_descent */
  48     int height;
  49
  50     /** The pattern/name used to load the font. */
  51     char *pattern;
  52
  53     union {
  54         struct {
  55             /** The xcb-id for the font */
  56             xcb_font_t id;
  57
  58             /** Font information gathered from the server */
  59             xcb_query_font_reply_t *info;
  60
  61             /** Font table for this font (may be NULL) */
  62             xcb_charinfo_t *table;
  63         } xcb;
  64
  65 #if PANGO_SUPPORT
  66         /** The pango font description */
  67         PangoFontDescription *pango_desc;
  68 #endif
  69     } specific;
  70 };
  71
  72 /* Since this file also gets included by utilities which don’t use the i3 log
  73  * infrastructure, we define a fallback. */
  74 #if !defined(LOG)
  75 void verboselog(char *fmt, ...);
  76 #define LOG(fmt, ...) verboselog("[libi3] " __FILE__ " " fmt, ##__VA_ARGS__)
  77 #endif
  78 #if !defined(ELOG)
  79 void errorlog(char *fmt, ...);
  80 #define ELOG(fmt, ...) errorlog("[libi3] ERROR: " fmt, ##__VA_ARGS__)
  81 #endif
  82
  83 /**
  84  * Try to get the contents of the given atom (for example I3_SOCKET_PATH) from
  85  * the X11 root window and return NULL if it doesn’t work.
  86  *
  87  * The memory for the contents is dynamically allocated and has to be
  88  * free()d by the caller.
  89  *
  90  */
  91 char *root_atom_contents(const char *atomname);
  92
  93 /**
  94  * Safe-wrapper around malloc which exits if malloc returns NULL (meaning that
  95  * there is no more memory available)
  96  *
  97  */
  98 void *smalloc(size_t size);
  99
 100 /**
 101  * Safe-wrapper around calloc which exits if malloc returns NULL (meaning that
 102  * there is no more memory available)
 103  *
 104  */
 105 void *scalloc(size_t size);
 106
 107 /**
 108  * Safe-wrapper around realloc which exits if realloc returns NULL (meaning
 109  * that there is no more memory available).
 110  *
 111  */
 112 void *srealloc(void *ptr, size_t size);
 113
 114 /**
 115  * Safe-wrapper around strdup which exits if malloc returns NULL (meaning that
 116  * there is no more memory available)
 117  *
 118  */
 119 char *sstrdup(const char *str);
 120
 121 /**
 122  * Safe-wrapper around asprintf which exits if it returns -1 (meaning that
 123  * there is no more memory available)
 124  *
 125  */
 126 int sasprintf(char **strp, const char *fmt, ...);
 127
 128 /**
 129  * Build an i3String from an UTF-8 encoded string.
 130  * Returns the newly-allocated i3String.
 131  *
 132  */
 133 i3String *i3string_from_utf8(const char *from_utf8);
 134
 135 /**
 136  * Build an i3String from an UTF-8 encoded string with fixed length.
 137  * To be used when no proper NUL-terminaison is available.
 138  * Returns the newly-allocated i3String.
 139  *
 140  */
 141 i3String *i3string_from_utf8_with_length(const char *from_utf8, size_t num_bytes);
 142
 143 /**
 144  * Build an i3String from an UCS-2 encoded string.
 145  * Returns the newly-allocated i3String.
 146  *
 147  */
 148 i3String *i3string_from_ucs2(const xcb_char2b_t *from_ucs2, size_t num_glyphs);
 149
 150 /**
 151  * Free an i3String.
 152  *
 153  */
 154 void i3string_free(i3String *str);
 155
 156 /**
 157  * Securely i3string_free by setting the pointer to NULL
 158  * to prevent accidentally using freed memory.
 159  *
 160  */
 161 #define I3STRING_FREE(str) \
 162 do { \
 163  if (str != NULL) { \
 164  i3string_free(str); \
 165  str = NULL; \
 166  } \
 167 } while (0)
 168
 169 /**
 170  * Returns the UTF-8 encoded version of the i3String.
 171  *
 172  */
 173 const char *i3string_as_utf8(i3String *str);
 174
 175 /**
 176  * Returns the UCS-2 encoded version of the i3String.
 177  *
 178  */
 179 const xcb_char2b_t *i3string_as_ucs2(i3String *str);
 180
 181 /**
 182  * Returns the number of bytes (UTF-8 encoded) in an i3String.
 183  *
 184  */
 185 size_t i3string_get_num_bytes(i3String *str);
 186
 187 /**
 188  * Returns the number of glyphs in an i3String.
 189  *
 190  */
 191 size_t i3string_get_num_glyphs(i3String *str);
 192
 193 /**
 194  * Connects to the i3 IPC socket and returns the file descriptor for the
 195  * socket. die()s if anything goes wrong.
 196  *
 197  */
 198 int ipc_connect(const char *socket_path);
 199
 200 /**
 201  * Formats a message (payload) of the given size and type and sends it to i3 via
 202  * the given socket file descriptor.
 203  *
 204  * Returns -1 when write() fails, errno will remain.
 205  * Returns 0 on success.
 206  *
 207  */
 208 int ipc_send_message(int sockfd, const uint32_t message_size,
 209                      const uint32_t message_type, const uint8_t *payload);
 210
 211 /**
 212  * Reads a message from the given socket file descriptor and stores its length
 213  * (reply_length) as well as a pointer to its contents (reply).
 214  *
 215  * Returns -1 when read() fails, errno will remain.
 216  * Returns -2 when the IPC protocol is violated (invalid magic, unexpected
 217  * message type, EOF instead of a message). Additionally, the error will be
 218  * printed to stderr.
 219  * Returns 0 on success.
 220  *
 221  */
 222 int ipc_recv_message(int sockfd, uint32_t *message_type,
 223                      uint32_t *reply_length, uint8_t **reply);
 224
 225 /**
 226  * Generates a configure_notify event and sends it to the given window
 227  * Applications need this to think they’ve configured themselves correctly.
 228  * The truth is, however, that we will manage them.
 229  *
 230  */
 231 void fake_configure_notify(xcb_connection_t *conn, xcb_rectangle_t r, xcb_window_t window, int border_width);
 232
 233 /**
 234  * Returns the colorpixel to use for the given hex color (think of HTML). Only
 235  * works for true-color (vast majority of cases) at the moment, avoiding a
 236  * roundtrip to X11.
 237  *
 238  * The hex_color has to start with #, for example #FF00FF.
 239  *
 240  * NOTE that get_colorpixel() does _NOT_ check the given color code for validity.
 241  * This has to be done by the caller.
 242  *
 243  * NOTE that this function may in the future rely on a global xcb_connection_t
 244  * variable called 'conn' to be present.
 245  *
 246  */
 247 uint32_t get_colorpixel(const char *hex) __attribute__((const));
 248
 249 #if defined(__APPLE__)
 250
 251 /*
 252  * Taken from FreeBSD
 253  * Returns a pointer to a new string which is a duplicate of the
 254  * string, but only copies at most n characters.
 255  *
 256  */
 257 char *strndup(const char *str, size_t n);
 258
 259 #endif
 260
 261 /**
 262  * All-in-one function which returns the modifier mask (XCB_MOD_MASK_*) for the
 263  * given keysymbol, for example for XCB_NUM_LOCK (usually configured to mod2).
 264  *
 265  * This function initiates one round-trip. Use get_mod_mask_for() directly if
 266  * you already have the modifier mapping and key symbols.
 267  *
 268  */
 269 uint32_t aio_get_mod_mask_for(uint32_t keysym, xcb_key_symbols_t *symbols);
 270
 271 /**
 272  * Returns the modifier mask (XCB_MOD_MASK_*) for the given keysymbol, for
 273  * example for XCB_NUM_LOCK (usually configured to mod2).
 274  *
 275  * This function does not initiate any round-trips.
 276  *
 277  */
 278 uint32_t get_mod_mask_for(uint32_t keysym,
 279                            xcb_key_symbols_t *symbols,
 280                            xcb_get_modifier_mapping_reply_t *modmap_reply);
 281
 282 /**
 283  * Loads a font for usage, also getting its height. If fallback is true,
 284  * the fonts 'fixed' or '-misc-*' will be loaded instead of exiting.
 285  *
 286  */
 287 i3Font load_font(const char *pattern, const bool fallback);
 288
 289 /**
 290  * Defines the font to be used for the forthcoming calls.
 291  *
 292  */
 293 void set_font(i3Font *font);
 294
 295 /**
 296  * Frees the resources taken by the current font.
 297  *
 298  */
 299 void free_font(void);
 300
 301 /**
 302  * Converts the given string to UTF-8 from UCS-2 big endian. The return value
 303  * must be freed after use.
 304  *
 305  */
 306 char *convert_ucs2_to_utf8(xcb_char2b_t *text, size_t num_glyphs);
 307
 308 /**
 309  * Converts the given string to UCS-2 big endian for use with
 310  * xcb_image_text_16(). The amount of real glyphs is stored in real_strlen,
 311  * a buffer containing the UCS-2 encoded string (16 bit per glyph) is
 312  * returned. It has to be freed when done.
 313  *
 314  */
 315 xcb_char2b_t *convert_utf8_to_ucs2(char *input, size_t *real_strlen);
 316
 317 /**
 318  * Defines the colors to be used for the forthcoming draw_text calls.
 319  *
 320  */
 321 void set_font_colors(xcb_gcontext_t gc, uint32_t foreground, uint32_t background);
 322
 323 /**
 324  * Draws text onto the specified X drawable (normally a pixmap) at the
 325  * specified coordinates (from the top left corner of the leftmost, uppermost
 326  * glyph) and using the provided gc.
 327  *
 328  * Text must be specified as an i3String.
 329  *
 330  */
 331 void draw_text(i3String *text, xcb_drawable_t drawable,
 332         xcb_gcontext_t gc, int x, int y, int max_width);
 333
 334 /**
 335  * ASCII version of draw_text to print static strings.
 336  *
 337  */
 338 void draw_text_ascii(const char *text, xcb_drawable_t drawable,
 339         xcb_gcontext_t gc, int x, int y, int max_width);
 340
 341 /**
 342  * Predict the text width in pixels for the given text. Text must be
 343  * specified as an i3String.
 344  *
 345  */
 346 int predict_text_width(i3String *text);
 347
 348 /**
 349  * Returns the visual type associated with the given screen.
 350  *
 351  */
 352 xcb_visualtype_t *get_visualtype(xcb_screen_t *screen);
 353
 354 /**
 355  * Returns true if this version of i3 is a debug build (anything which is not a
 356  * release version), based on the git version number.
 357  *
 358  */
 359 bool is_debug_build() __attribute__((const));
 360
 361 /**
 362  * Returns the name of a temporary file with the specified prefix.
 363  *
 364  */
 365 char *get_process_filename(const char *prefix);
 366
 367 #endif