src/xaut.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 #ifndef XAUT_H_
  21 #define XAUT_H_
  22
  23 #ifdef HAVE_CONFIG_H
  24 #include "config.h"
  25 #endif
  26
  27 #include <X11/extensions/XTest.h>
  28 #include <stdio.h>
  29 #include <string.h>
  30 #include <stdlib.h>
  31 #include <math.h>
  32 #include <unistd.h>
  33 #include <X11/Xlib.h>
  34 #include <X11/Xatom.h>
  35 #include <limits.h>
  36
  37 #include "xaut_types.h"
  38 #include "xaut_display.h"
  39 #include "xaut_keyboard.h"
  40 #include "xaut_mouse.h"
  41 #include "xaut_window.h"
  42
  43 // --- Published subroutines, functions and structures
  44
  45 /**
  46  * Releases any resources created by this code.
  47  */
  48 void cleanup();
  49
  50 /**
  51  * Print information about what's going on.
  52  */
  53 void verbose(BOOL verbose);
  54 void extra_verbose(BOOL extra_verbose);
  55
  56 // --- End of published stuff
  57
  58 /**
  59  * Add a code to the list of ascii codes.
  60  * @param code the ascii code to add
  61  * @param shifted does the shift key need to be down to reach this
  62  */
  63 void _add_code(unsigned short code, BOOL shifted);
  64
  65 /**
  66  * Checks to see if init() has been called, and calls it if not.
  67  * Will return false only if init() cannot initialize values.  So
  68  * can be used as a simple test.
  69  */
  70 BOOL _check_init();
  71
  72 /**
  73  * Initializes the program.
  74  */
  75 void _initialize();
  76
  77 /**
  78  * Initializes the list of allowed ascii characters.
  79  * These represent any character which can be sent directly, as opposed
  80  * to requiring being sent in a brace.  So it's possible to send e.g. 'A',
  81  * but not the control key.  That would require "{Control_L}".
  82  * Note that the following keys have special meaning: !^+{}.  Respectively
  83  * they mean "Alt_L", "Control_L", "Shift_L", and "whatever is inside
  84  * is a special key code".
  85  * Note that this has some overlap with init_keys().
  86  */
  87 BOOL _init_ascii();
  88
  89 /**
  90  * Initializes only the defaults.
  91  * The structure "defaults" is filled with values.
  92  * @return boolean indication of success.
  93  */
  94 BOOL init_defaults();
  95
  96 /**
  97  * Indication of whether the requested feature is available.
  98  * Not all implementations of X11 support all possible things.
  99  * This helps keep things portable.
 100  * @param the feature to find
 101  * @return boolean indication of whether the requested feature is possible.
 102  */
 103 BOOL _is_supported_feature(char *feature);
 104
 105 /**
 106  * Performs screen coordinate normalization.
 107  * Normalizes the coordinates supplied so that
 108  * they are at least equal to zero, and
 109  * no greater than the maximum coordinate.
 110  * Prevents stupid things from happening if e.g.
 111  * mouse_move( 10000, 10000 ) is called.
 112  * @param x the x coordinate to normalize
 113  * @param y the y coordinate to normalize
 114  */
 115 void _normalize_coords(int *x, int *y);
 116
 117 /**
 118  * Performs screen coordinate normalization as regards a window.
 119  * Normalizes the coordinates such that they make sense with the
 120  * window that is identified by the window handle.  For example,
 121  * if the window is at 100x100, and the coordinates supplied to mouse_move are
 122  * -10, -10, then the mouse will be moved to 90x90.  If the
 123  * coordinates supplied for the same window are 10, 10, then the
 124  * mouse will be moved to 110x110.  Note that if the window
 125  * handle is not valid, the coordinates will be normalized to the
 126  * whole screen using <code>normalize_coords</code>.
 127  *
 128  * Note that if the window is partially off the screen, the mouse
 129  * will move as close as possible to the desired location.  The
 130  * mouse will not move off the screen.
 131  * @param x the x coordinate to normalize
 132  * @param y the y coordinate to normalize
 133  * @param win a handle to use as a reference point
 134  * @return will return FALSE if window handle passed is invalid
 135  */
 136 BOOL _normalize_wincoords(int *x, int *y, unsigned long win);
 137
 138 /**
 139  * Extracts a substring from a string.
 140  * <ul>Notes:
 141  * <li>You <em>must</em> release the substring when done.</li>
 142  * <li>The values for begin and end are inclusive.<li>
 143  * <li>The function will return NULL if the string parameter is NULL.</li>
 144  * <li>The function will return NULL if the string is empty.</li>
 145  * <li>The function will return NULL if the first parameter is greater
 146  *      than the length of the string.</li>
 147  * <li>The end parameter will be reduced to the last character in the
 148  *      string if end is greater than the end of the string.</li>
 149  * </ul>
 150  *
 151  * @param str the string
 152  * @param first the first character to extract
 153  * @param last the last character to extract
 154  * @return the substring, or null if something went wrong.
 155  */
 156 char* _stringmid(const char *str, size_t first, size_t last);
 157
 158 /**
 159  * Called by X in the event of an error.
 160  * X is notified that it should use this function usually just
 161  * before a user provided window handle is used.  There are a
 162  * number of reasons such a call might fail.  It may be that
 163  * the user closed the window, it may be that a transient
 164  * window has closed by itself.  Whatever.  The point
 165  * is that without an error handler, the entire program will
 166  * exit.
 167  */
 168 int _invalid_window_error_handler(Display *dsp, XErrorEvent *err);
 169
 170 #endif /* XAUT_H_ */