src/xaut_window.h

   1 /***************************************************************************
   2  *   Copyright (C) 2009 by Chris Parker                                    *
   3  *   chrsprkr3@gmail.com                                                   *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the Python License version 2.5 or later.        *
   7  *                                                                         *
   8  *   This program is distributed in the hope that it will be useful,       *
   9  *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
  10  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                  *
  11  ***************************************************************************/
  12
  13 /*
  14  $URL$
  15  $Author$
  16  $Date$
  17  $Rev$
  18 */
  19
  20 /**
  21  * Various ways of getting information about and manipulating windows.
  22  */
  23
  24 #ifndef XAUT_WINDOW_H_
  25 #define XAUT_WINDOW_H_
  26
  27 #include <regex.h>
  28
  29 #include "xaut.h"
  30 #include "xaut_types.h"
  31
  32 /**
  33  * Activates the Window pointed to by the handle.
  34  * "Activate" in this context means "bring to front and
  35  * get ready to accept input".
  36  *
  37  * Note that some window managers do not support
  38  * or will suppress this.
  39  * @param the win to the window
  40  * @return boolean indication of success
  41  */
  42 BOOL activate_window(Window win);
  43
  44 /**
  45  * Returns a handle to the currently active window.
  46  * @return a handle to the active window.
  47  */
  48 Window active_window();
  49
  50 /**
  51  * Returns 1 if the window handle passed is valid, 0 otherwise.
  52  * @param win the window handle to test
  53  * @return as described.
  54  */
  55 BOOL is_valid(Window win);
  56
  57 /**
  58  * Finds the outer container parent of a window.
  59  * Typically, when one finds a window by name or
  60  * by getting the active window, what one gets is
  61  * the window that the user interacts with.  This
  62  * window almost always has an outer boundary
  63  * window where the title bar and borders go.  It
  64  * is almost always necessary to use the outer window when
  65  * calculating window size or xy position.  Otherwise
  66  * one gets the size of the container window.
  67  *
  68  * It is an implementation detail that this function
  69  * returns the final window just before the root window.
  70  * @param win the window which is likely the edit or use window
  71  * @param the outer parent window.
  72  */
  73 Window find_outer_parent(Window win);
  74
  75 /**
  76  * Looks for a window with the title supplied.
  77  * It is an implementation detail that this function asks the current
  78  * window manager (e.g. KDM the KDE Window manager) for a list of
  79  * current windows and checks those.  This has the advantage that
  80  * there are fewer windows to test, but has the disadvantage that
  81  * there are many "windows" that the window manager does not "manage".
  82  * For example the volumn control in the task tray is managed by
  83  * X but is not managed by e.g. KDM.  Use this function if you
  84  * are interested only in traditional "window" objects,
  85  * otherwise try "search_for_window".
  86  *
  87  * The following criteria is used when multiple windows match:
  88  * First the distance from the user's current window is considered.
  89  * If one window is "closer" than another it is immediately selected.
  90  * If not, then the window with the lower ID is returned.  This usually -
  91  * but not always - means the older of the windows (sometimes window IDs
  92  * are reused).
  93  *
  94  * @param title a string to match against the title
  95  * @return the window handle, or NULL if none found
  96  */
  97 Window find_window(char *title);
  98
  99 /**
 100  * Performs a deep search and possibly finds a window based on title.
 101  * Note that the title can contain regular expressions.
 102  * "Deep search" in this case means that the root X Window
 103  * tree is recursively searched for a match to the name supplied.
 104  * This search is extremely intensive, and can take a full second
 105  * or more to return.  This search is meant to be used for getting
 106  * the handle to task tray items and the like.  For example
 107  * a terminal window can normally be found via "find_window", while
 108  * the volumn control cannot - but it can most likely can be found via
 109  * this search.
 110  *
 111  * "find_window" and "search_for_window" use the same criteria for
 112  * deciding which window to return in the event multiple titles match.
 113  *
 114  * @param title a string to match against the title
 115  * @return the window handle, or NULL if none found
 116  */
 117 Window* search_for_window(char *title);
 118
 119 /**
 120  * Moves a window to the coordinates supplied.
 121  *
 122  * Note that the boolean success return does not
 123  * necessarily mean that the move was successful,
 124  * it means that the X11 call did not generate an error.
 125  *
 126  * Use -1 for x, y, or desktop if you wish to leave that aspect
 127  * of the window alone (technically anything less than zero
 128  * will work).  Some examples:<pre>
 129  *
 130  * //Move window to 300x300 on current desktop
 131  * move_window( window, 300, 300, -1 );
 132  *
 133  * //Move window to desktop 3
 134  * move_window( window, -1, -1, 3 );
 135  *
 136  * //Move window up 10 pixels
 137  * move_window( window, -1, window_y() - 10, -1 );
 138  *
 139  * </pre>
 140  *
 141  * @param win a handle to the window to move
 142  * @param x the new x coordinate for the upper left corner of the window
 143  * @param y the new y coordinate for the upper left corner of the window
 144  * @param desktop the destination desktop.
 145  * @return boolean indication of success
 146  */
 147 BOOL move_window(Window win, int x, int y, long desktop);
 148
 149 /**
 150  * Iconify or deiconify a window - a synonym for minimize_window.
 151  *
 152  * Note that the boolean success return does not
 153  * necessarily mean that the minimization was successful,
 154  * it means that the X11 call did not generate an error.
 155  * @param win a handle to the window to iconify
 156  * @param tf take the action if tf resolves to true, otherwise undo it
 157  * @return boolean indication of success
 158  */
 159 BOOL iconify_window(Window win, BOOL tf);
 160
 161 /**
 162  * Minimize a window - a synonym for iconify_window.
 163  *
 164  * Note that the boolean success return does not
 165  * necessarily mean that the minimization was successful,
 166  * it means that the X11 call did not generate an error.
 167  * @param win a handle to the window to minimize
 168  * @param tf take the action if tf resolves to true, otherwise undo it
 169  * @return boolean indication of success
 170  */
 171 BOOL minimize_window(Window win, BOOL tf);
 172
 173 /**
 174  * Maximize a window.
 175  * It is an implementation detail that this function
 176  * does not perform any work, but instead calls
 177  * maximize_window_vert and maximize_window_horz to
 178  * maximize in both directions.  It's possible to succeed
 179  * in one direction and fail in the other.
 180  *
 181  * Note that the boolean success return does not
 182  * necessarily mean that the maximization was successful,
 183  * it means that the X11 call did not generate an error.
 184  *
 185  * @param win the window to set to maximize
 186  * @param tf take the action if tf resolves to true, otherwise undo it
 187  * @return boolean indication of success
 188  */
 189 BOOL maximize_window(Window win, BOOL tf);
 190
 191 /**
 192  * Maximize a window horizontally.
 193  * This function only makes the window fill the screen from
 194  * side to side, it does not expand top to bottom.
 195  *
 196  * Note that the boolean success return does not
 197  * necessarily mean that the maximization was successful,
 198  * it means that the X11 call did not generate an error.
 199  *
 200  * @param win the window to set to maximize
 201  * @param tf take the action if tf resolves to true, otherwise undo it
 202  * @return boolean indication of success
 203  */
 204 BOOL maximize_window_horz(Window win, BOOL tf);
 205
 206 /**
 207  * Maximize a window vertically.
 208  * This function only makes the window fill the screen from
 209  * top to bottom, it does not expand side to side.
 210  *
 211  * Note that the boolean success return does not
 212  * necessarily mean that the maximization was successful,
 213  * it means that the X11 call did not generate an error.
 214  *
 215  * @param win the window to set to maximize
 216  * @param tf take the action if tf resolves to true, otherwise undo it
 217  * @return boolean indication of success
 218  */
 219 BOOL maximize_window_vert(Window win, BOOL tf);
 220
 221 /**
 222  * Makes a window full screen.
 223  * This is different than maximized - full screen also removes
 224  * the title bar and tools, and the window covers any tool bars.
 225  *
 226  * @param win the window to set to full screen
 227  * @param tf take the action if tf resolves to true, otherwise undo it
 228  * @return boolean indication of success
 229  */
 230 BOOL full_screen_window(Window win, BOOL tf);
 231
 232 /**
 233  * Shades a window.
 234  * "Shading" is when the window has a title bar that is still
 235  * on the screen, but the main part of the window is rolled up.
 236  *
 237  * @param win the window to set to full screen
 238  * @param tf take the action if tf resolves to true, otherwise undo it
 239  * @return boolean indication of success
 240  */
 241 BOOL shade_window(Window win, BOOL tf);
 242
 243 /**
 244  * Restore a window.
 245  * In this context "restore" means remove the full screen,
 246  * maximized, iconified, shaded, and other flags.  Removes
 247  * them ALL so that the window becomes a regular window again.
 248  *
 249  * Note that the boolean success return does not
 250  * necessarily mean that the restore was successful,
 251  * it means that the X11 call did not generate an error.
 252  *
 253  * @param win the window to set to full screen
 254  * @return boolean indication of success
 255  */
 256 BOOL restore_window(Window win);
 257
 258 /**
 259  * Resize a window.
 260  *
 261  * Note that the boolean success return does not
 262  * necessarily mean that the resize was successful,
 263  * it means that the X11 call did not generate an error.
 264  *
 265  * @param win the window to resize
 266  * @param w the new width of the window
 267  * @param h the new height of the window
 268  * @return boolean indication of success
 269  */
 270 BOOL resize_window(Window win, unsigned int w, unsigned int h);
 271
 272 /**
 273  * Returns basic window information.
 274  * <ul>
 275  * <li>window_x returns the window's upper left X coordinate</li>
 276  * <li>window_y returns the window's upper left Y coordinate</li>
 277  * <li>window_w returns the width of the window</li>
 278  * <li>window_h returns the height of the window</li>
 279  * <li>window_name returns name of the window (usually the text on the title bar)</li>
 280  *
 281  * @param win a window handle
 282  * @return the appropriate value for the function, or -1 or NULL if the handle
 283  *      does not point to a real window or something else goes wrong.
 284  */
 285 int window_x(Window win);
 286 int window_y(Window win);
 287 int window_w(Window win);
 288 int window_h(Window win);
 289 char* window_name(Window win);
 290
 291 /**
 292  * Gets the current desktop number for the window in question.
 293  * @param win the handle of the window to find
 294  */
 295 long window_desktop(Window win);
 296
 297 /**
 298  * Common code for maximizing, shading and etc.
 299  * <ul>Note that action must be one of three actions:
 300  * <li>0 = Remove attribute</li>
 301  * <li>1 = Add attribute</li>
 302  * <li>2 = Toggle attribute</li></ul>
 303  * The action is normalized to "Toggle" if the
 304  * action passed does not match one of the three
 305  * previous actions.
 306  *
 307  * @param win a handle to the window to alter
 308  * @param action as described
 309  * @param data1 an atom of first change
 310  * @param data2 an atom of the second change, or 0 if only one change rquired
 311  * @return boolean indication of success
 312  */
 313 BOOL _alter_window_state(Window win, long action, long data1, long data2);
 314 /**
 315  * Use this to make sure the "results buffer" is large enough.
 316  * @param search a pointer to a window_search struct
 317  * @return boolean indication of success
 318  */
 319 BOOL _ensure_window_buffer_size(_window_search *search);
 320
 321 /**
 322  * Moves the window to the specified desktop.
 323  * @param win the handle to the window to move
 324  * @param desktop the desktop to move the window to
 325  * @return boolean indication of success
 326  */
 327 BOOL _move_window_to_desktop(Window win, long desktop);
 328
 329 /**
 330  * Prepares a regular expression for search.
 331  * @param search_term what to look for
 332  * @param regx a place to put the search regular expression
 333  */
 334 BOOL _prepare_regex(char *title, regex_t **regx);
 335
 336
 337 /**
 338  * Performs the window search.
 339  * Fills the buffer in search->buffer with handles to windows
 340  * that match the search term supplied.
 341  */
 342 void _recursive_window_search(_window_search *search);
 343
 344 /**
 345  * The comparator used by qsort.
 346  *
 347  * First sort is by absolute distance from the current desktop.
 348  * For example if the current user is on desktop three,
 349  * and a matching window in on desktop two and one is on
 350  * desktop one, then the one on desktop two sorts higher.
 351  *
 352  * The second sort is by handle number.  Presumably an older
 353  * window will have a lower (numerically speaking) id than
 354  * a newer window.
 355  */
 356 int _window_search_comparator(const void *l, const void *r);
 357
 358 /**
 359  * Gets the requested property for the window.
 360  * Used internally to get properties for things like which desktop the
 361  * window resides on.
 362  *
 363  * @param window the window in question
 364  * @param property the X11 atom of the desired property
 365  * @param item_count_ret pointer to a place to put the count of the items returned
 366  * @param type the X11 atom describing the property type
 367  * @param size
 368  */
 369 unsigned char * _window_property(Window window, Atom property,
 370         long *item_count_ret, Atom *type, int *size);
 371
 372 #endif /* XAUT_WINDOW_H_ */