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