docs/html/keyboard.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <!--
   3  $URL$
   4  $Author$
   5  $Date$
   6  $Rev$
   7 -->
   8 <html>
   9 <head>
  10 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  11 <link rel="stylesheet" type="text/css" href="xaut.css">
  12 <title>Keyboard Commands</title>
  13 </head>
  14 <body>
  15 <div id="container">
  16 <div id="header">
  17     <h1>X Automation</h1>
  18 </div>
  19 <div id="links">
  20     <ul>
  21         <li><a href="index.html">Home</a></li>
  22         <li><a href="display.html">Display Functions</a></li>
  23         <li class="current">Keyboard Functions</li>
  24         <li><a href="mouse.html">Mouse Functions</a></li>
  25         <li><a href="window.html">Window Functions</a></li>
  26         <li><a href="other.html">Other Stuff</a></li>
  27     </ul>
  28 </div>
  29 <div id="content">
  30
  31 <h2>Keyboard Object Functions</h2>
  32 <div class="synopsis">
  33     <h3>Function Synopsis</h3>
  34     <table class="synopsis_table">
  35     <tr><th>Function</th><th>Brief Description</th></tr>
  36     <tr>
  37         <td><a href="#down_delay">down_delay([delay])</a></td>
  38         <td>How long a key stays down when "clicked".</td>
  39     </tr>
  40     <tr>
  41         <td><a href="#click_delay">click_delay([delay])</a></td>
  42         <td>How long to pause between key clicks.</td>
  43     </tr>
  44     <tr>
  45         <td><a href="#click">click(key)</a></td>
  46         <td>A key to click by id.</td>
  47     </tr>
  48     <tr>
  49         <td><a href="#down">down(key)</a></td>
  50         <td>A key to press by id. Don't forget to release it!</td>
  51     </tr>
  52     <tr>
  53         <td><a href="#up">up(key)</a></td>
  54         <td>A key to release by id.  Releases keys pressed by "down".</td>
  55     </tr>
  56     <tr>
  57         <td><a href="#type">type(str)</a></td>
  58         <td>A string to type.  See detailed description below.</td>
  59     </tr>
  60     <tr>
  61         <td><a href="#interpret_meta_symbols">interpret_meta_symbols(tf)</a></td>
  62         <td>Indicates whether to interpret meta symbols in type.</td>
  63     </tr>
  64     <tr>
  65         <td class="bottom"><a href="#print_keycodes">print_keycodes()</a></td>
  66         <td class="bottom">Prints X11 keycodes to the console.</td>
  67     </tr>
  68     </table>
  69 </div>
  70 <div class="command" id="down_delay">
  71     <div class="section desc">
  72         <h3><a name="down_delay">Function:</a></h3>
  73         <p class="function">down_delay([delay])</p>
  74         <p class="description">
  75         Sets the value for how long the keyboard key stays down when "clicked"
  76         in milliseconds. Default is 10 milliseconds which usually works with
  77         most applications. Note that 0 rarely works.  If you are trying to
  78         get a big speed boost and are getting surprising results, try
  79         changing this to 1. Does not make any changes if delay is less than
  80         zero or is omitted.</p>
  81     </div>
  82     <div class="section params">
  83         <h3>Parameters:</h3>
  84         <table class="param_table">
  85         <tr><th>Param</th><th>Req</th><th>Description</th></tr>
  86         <tr class="parameter">
  87             <td class="name bottom">delay</td>
  88             <td class="req bottom">no</td>
  89             <td class="desc bottom">The delay in milliseconds</td>
  90         </tr>
  91         </table>
  92     </div>
  93     <div class="section return">
  94         <h3>Return Value:</h3>
  95         The current delay which may or may not have changed.
  96     </div>
  97     <div class="section example">
  98         <h3>Example(s):</h3>
  99 <pre class="example_code">#Change the down delay to 20 ms
 100 import xaut
 101 kbd = xaut.keyboard()
 102 delay = kbd.down_delay(20)
 103 print(delay) #Prints "20"</pre>
 104 <pre class="example_code">#Find current delay without making changes
 105 import xaut
 106 kbd = xaut.keyboard()
 107 delay = kbd.down_delay()
 108 print(delay) #Prints current delay</pre>
 109     </div>
 110     <div class="nav">
 111         <a href="keyboard.html">Top of document</a>
 112     </div>
 113 </div>
 114 <div class="command" id="click_delay">
 115     <div class="section desc">
 116         <h3><a name="click_delay">Function:</a></h3>
 117         <p class="function">click_delay([delay])</p>
 118         <p class="description">
 119         How much time elapses between key clicks when "typing" in
 120         milliseconds. Default is 5 milliseconds, and usually works with
 121         most applications. Note that 0 rarely works.  If you are trying to
 122         get a big speed boost and are getting surprising results, try
 123         changing this to 1. Does not make any changes if delay is less than
 124         zero or is omitted.
 125         </p>
 126     </div>
 127     <div class="section params">
 128         <h3>Parameters:</h3>
 129         <table class="param_table">
 130         <tr><th>Param</th><th>Req</th><th>Description</th></tr>
 131             <tr class="parameter">
 132             <td class="name bottom">delay</td>
 133             <td class="req bottom">no</td>
 134             <td class="desc bottom">The delay in milliseconds</td>
 135         </tr>
 136         </table>
 137     </div>
 138     <div class="section return">
 139         <h3>Return Value:</h3>
 140         The current delay which may or may not have changed.
 141     </div>
 142     <div class="section example">
 143         <h3>Example(s):</h3>
 144 <pre class="example_code">#Change the click delay to 10 ms
 145 import xaut
 146 kbd = xaut.keyboard()
 147 delay = kbd.down_delay(10)
 148 print(delay) #Prints "10"</pre>
 149 <pre class="example_code">#Find the current delay without making any changes
 150 import xaut
 151 kbd = xaut.keyboard()
 152 delay = kbd.click_delay()
 153 print(delay) #Prints current delay</pre>
 154     </div>
 155     <div class="nav">
 156         <a href="keyboard.html">Top of document</a>
 157     </div>
 158 </div>
 159 <div class="command" id="click">
 160     <div class="section desc">
 161         <h3><a name="click">Function:</a></h3>
 162         <p class="function">click(key)</p>
 163         <p class="description">
 164             Simulates pressing down and releasing a key by key code.
 165             Use print_keycodes() to get a listing of valid key codes.
 166         </p>
 167         <p class="description">
 168             Use print_keycodes() to get a listing of valid keycodes.  Use
 169             one of the values from the column labeled <em>Code</em> as
 170             a parameter.
 171         </p>
 172     </div>
 173     <div class="section params">
 174         <h3>Parameters:</h3>
 175         <table class="param_table">
 176         <tr><th>Param</th><th>Req</th><th>Description</th></tr>
 177         <tr class="parameter">
 178             <td class="name bottom">key</td>
 179             <td class="req bottom">yes</td>
 180             <td class="desc bottom">The keycode of the key to click</td>
 181         </tr>
 182         </table>
 183     </div>
 184     <div class="section return">
 185         <h3>Return Value:</h3>
 186         <p>
 187         Non-zero value of call succeeds, zero otherwise.
 188         </p>
 189         <p>
 190         Be cautious, "succeeds" in this context doesn't necessarily mean that
 191         your application received the keycode.  It means that X11 did not
 192         report any errors or throw any exceptions.
 193         </p>
 194     </div>
 195     <div class="section example">
 196         <h3>Example(s):</h3>
 197 <pre class="example_code">import xaut
 198 kbd = xaut.keyboard()
 199 success = kbd.click(36) #Sends the Return key
 200 if(success):
 201     print("X11 reports that the keycode 36 was sent")
 202 else:
 203     print("X11 reported an error when sending keycode 36")</pre>
 204     </div>
 205     <div class="nav">
 206         <a href="keyboard.html">Top of document</a>
 207     </div>
 208 </div>
 209 <div class="command" id="down">
 210     <div class="section desc">
 211         <h3><a name="down">Function:</a></h3>
 212         <p class="function">down(key)</p>
 213         <p class="description">
 214             Simulates pressing down the key by key code.
 215             Use print_keycodes() to get a listing of valid key codes.
 216             This function would be useful if it is necessary to press
 217             a key combination that does not involve one of the meta
 218             keys.  For example, this function can simultaneously press
 219             down the "a" and "b" key.  You <em>must</em> release the
 220             key manually.
 221        </p>
 222        <p class="description">
 223             Note that the key usually releases by itself when the calling
 224             program terminates - but this is not guaranteed (at least not by
 225             me).
 226        </p>
 227        <p class="description">
 228             Use print_keycodes() to get a listing of valid keycodes.  Use
 229             one of the values from the column labeled <em>Code</em> as
 230             a parameter.
 231         </p>
 232     </div>
 233     <div class="section params">
 234         <h3>Parameters:</h3>
 235         <table class="param_table">
 236         <tr><th>Param</th><th>Req</th><th>Description</th></tr>
 237         <tr class="parameter">
 238             <td class="name bottom">key</td>
 239             <td class="req bottom">yes</td>
 240             <td class="desc bottom">The key code of the key to press down.</td>
 241         </tr>
 242     </table>
 243     </div>
 244     <div class="section return">
 245         <h3>Return Value:</h3>
 246         <p>
 247         Non-zero value of call succeeds, zero otherwise.
 248         </p><p>
 249         Be cautious, "succeeds" in this context doesn't necessarily mean that
 250         your application received the keycode.  It means that X11 did not
 251         report any errors or throw any exceptions.
 252         </p>
 253     </div>
 254     <div class="section example">
 255         <h3>Example(s):</h3>
 256 <pre class="example_code">import xaut
 257 import time
 258 kbd = xaut.keyboard()
 259 kbd.down(38) #Press down the "a" key
 260 kbd.down(56) #Press down the "b" key
 261 time.sleep(.1)
 262 kbd.up(56) #Release the "b" key
 263 kbd.up(38) #Release the "a" key</pre>
 264     </div>
 265     <div class="nav">
 266         <a href="keyboard.html">Top of document</a>
 267     </div>
 268 </div>
 269 <div class="command" id="up">
 270     <div class="section desc">
 271         <h3><a name="up">Function:</a></h3>
 272         <p class="function">up(key)</p>
 273         <p class="description">
 274             Releases a key previously presed down.
 275             Note that this will not release an actual key, only a simulated
 276             key.  Calling key_up without first calling key_down may or may not
 277             work, and may have "interesting" side effects.  Fair warning.
 278        </p>
 279        <p class="description">
 280             Use print_keycodes() to get a listing of valid keycodes.  Use
 281             one of the values from the column labeled <em>Code</em> as
 282             a parameter.
 283         </p>
 284     </div>
 285     <div class="section params">
 286         <h3>Parameters:</h3>
 287         <table class="param_table">
 288         <tr><th>Param</th><th>Req</th><th>Description</th></tr>
 289         <tr class="parameter">
 290             <td class="name bottom">key</td>
 291             <td class="req bottom">yes</td>
 292             <td class="desc bottom">The key code which should have been previously pressed "down"</td>
 293         </tr>
 294     </table>
 295     </div>
 296     <div class="section return">
 297         <h3>Return Value:</h3>
 298         <p>
 299         Non-zero value of call succeeds, zero otherwise.
 300         </p>
 301         <p>
 302         Be cautious, "succeeds" in this context doesn't necessarily mean that
 303         your application received the keycode.  It means that X11 did not
 304         report any errors or throw any exceptions.
 305         </p>
 306     </div>
 307     <div class="section example">
 308         <h3>Example(s):</h3>
 309         <pre class="example_code">import xaut
 310 import time
 311 kbd = xaut.keyboard()
 312 kbd.down(38) #Press down the "a" key
 313 kbd.down(56) #Press down the "b" key
 314 time.sleep(.1)
 315 kbd.up(56) #Release the "b" key
 316 kbd.up(38) #Release the "a" key</pre>
 317     </div>
 318     <div class="nav">
 319         <a href="keyboard.html">Top of document</a>
 320     </div>
 321 </div>
 322 <div class="command" id="type">
 323     <div class="section desc">
 324         <h3><a name="type">Function:</a></h3>
 325         <p class="function">type(str)</p>
 326         <p class="description">
 327             Sends the sequence of characters in the string parameter.
 328             Note that there are a number of rules to keep in mind:
 329         </p>
 330         <ol>
 331         <li>Only valid characters are sent.  So for example, character 7
 332         (the bell) cannot be sent.</li>
 333
 334         <li>The braces {} signify a special key code.  The code contained
 335         inside must correspond to a X11 key symbol name string.  The brace
 336         can also contain a number, which indicates the number of times to
 337         press the key.  E.g. {Tab} presses the tab key.  {Tab&nbsp;3} presses
 338         the tab key three times.  Use <code>print_keycodes()</code> to get a listing
 339         of valid keycodes.  You will want to use a value from the
 340         column called <em>X11 key symbol name string</em>.  The symbols
 341         are case sensitive - they must match what is printed <em>exactly</em>.</li>
 342
 343         <li>Note that all valid X11 codes are valid inside braces.</li>
 344
 345         <li>The exclamation point (!) signifies press the alt key for the next
 346         letter.  So <code>type("!a")</code> would press the alt key down, then press
 347         and release the a key, and then finally release the alt key.</li>
 348
 349         <li>The plus sign (+) signifies press the shift key for the next
 350         letter - similar to alt.  So <code>type("+a")</code> would press down
 351         the shift key down, press and release the a key, and then finally release
 352         the shift key.</li>
 353
 354         <li>The carat - or circumflex - (^) signifies press the control key
 355         for the next letter - similar to shift and alt.  So <code>type("^a")</code> would
 356         press the control key, then press and release the a key, and then finally
 357         release the control key.</li>
 358
 359         <li>The number sign - or pound symbol - (#) signifies press the meta key
 360         for the next letter - similar to shift, control, and alt.  So <code>type("#a")</code>
 361         would press the meta key, then press and release the a key, and then finally
 362         release the meta key.  Note that the "meta" key is sometimes named after
 363         a certain software company :)</li>
 364
 365         <li>The previous special keys can be combined.  So <code>type("+^#!a")</code> would
 366         press and hold down the shift, control, meta, and alt keys, press and release the
 367         a, and then release the alt, meta, control, and shift keys.</li>
 368
 369         <li>Use the string name for a key if you wish to send a literal !, +, or ^.
 370         E.g. {exclam}{plus}{asciicircum} would send !+^ .</li>
 371
 372         <li>Sending upper case letters as well as many symbols actually cause a
 373         shift and letter/symbol, e.g. A and +a are the same.  For this reason,
 374         one should use lower case letters in combination with control keys
 375         to avoid confusion.  ^a is not the same as ^A - ^A is precisely
 376         the same as ^+a .</li>
 377
 378         <li>Invalid characters encountered (if any) are printed to the error
 379         stream and then ignored.</li>
 380
 381         <li>Modifier keys (alt, control, and shift) are released after each
 382         keycode in a brace, and after the next letter when not in a brace.
 383         If you wish to use multiple letters in combination with modifier keys,
 384         you'll need to construct the correct sequence yourself using the
 385         correct codes and the <code>down()</code> and <code>up()</code> functions.</li>
 386
 387         <li>You can set "interpret_meta_symbols" to false, which will cause
 388         the string to be sent literally.  See
 389         <a href="#interpret_meta_symbols">interpret_meta_symbols</a> for more
 390         information.
 391
 392         </ol>
 393     </div>
 394     <div class="section params">
 395         <h3>Parameters:</h3>
 396         <table class="param_table">
 397         <tr><th>Param</th><th>Req</th><th>Description</th></tr>
 398         <tr class="parameter">
 399             <td class="name bottom">str</td>
 400             <td class="req bottom">yes</td>
 401             <td class="desc bottom">The string to send</td>
 402         </tr>
 403     </table>
 404     </div>
 405     <div class="section return">
 406         <h3>Return Value:</h3>
 407         <p>
 408         Non-zero value if call succeeds, zero otherwise.
 409         </p>
 410         <p>
 411         Be cautious, "succeeds" in this context doesn't necessarily mean that
 412         your application received the keycode.  It means that X11 did not
 413         report any errors or throw any exceptions.
 414         </p>
 415     </div>
 416     <div class="section example">
 417         <h3>Example(s):</h3>
 418 <pre class="example_code">import xaut
 419 kbd = xaut.keyboard()
 420 kbd.type("This is a test{Return}")
 421 kbd.type("!fa") #Opens the "Save As" dialog in some editors</pre>
 422     </div>
 423     <div class="nav">
 424         <a href="keyboard.html">Top of document</a>
 425     </div>
 426 </div>
 427 <div class="command" id="interpret_meta_symbols">
 428     <div class="section desc">
 429         <h3><a name="interpret_meta_symbols">Function:</a></h3>
 430         <p class="function">interpret_meta_symbols(tf)</p>
 431         <p class="description">
 432             A way to tell the program whether to interpret meta symbols.
 433             If the text to be typed contains meta symbols (!#^+{}),
 434             and you want those symbols sent as opposed to interpreted,
 435             then set this to FALSE.  Otherwise set this to TRUE - this
 436             is the default.
 437         </p>
 438     </div>
 439     <div class="section params">
 440         <h3>Parameters:</h3>
 441         <table class="param_table">
 442         <tr><th>Param</th><th>Req</th><th>Description</th></tr>
 443         <tr class="parameter">
 444             <td class="name bottom">tf</td>
 445             <td class="req bottom">yes</td>
 446             <td class="desc bottom">0 tells xaut to send meta symbols as opposed to
 447             interpreting them, any non-zero value means interpret.</td>
 448         </tr>
 449         </table>
 450     </div>
 451     <div class="section return">
 452         <h3>Return Value:</h3>
 453         (none)
 454     </div>
 455     <div class="section example">
 456         <h3>Example(s):</h3>
 457 <pre class="example_code">import xaut
 458 import time
 459 kbd = xaut.keyboard()
 460 kbd.type("!f") #Sends the alt + f keys
 461 time.sleep(3)
 462 kbd.type("{Escape}")
 463 time.sleep(3)
 464 kbd.interpret_meta_symbols(0)
 465 kbd.type("!f") #Literally sends !f</pre>
 466     </div>
 467     <div class="nav">
 468         <a href="keyboard.html">Top of document</a>
 469     </div>
 470 </div>
 471 <div class="command" id="print_keycodes">
 472     <div class="section desc">
 473         <h3><a name="print_keycodes">Function:</a></h3>
 474         <p class="function">print_keycodes()</p>
 475         <p class="description">
 476             Prints out a listing of valid keycodes to the local console.
 477         </p>
 478     </div>
 479     <div class="section params">
 480         <h3>Parameters:</h3>
 481         (none)
 482     </div>
 483     <div class="section return">
 484         <h3>Return Value:</h3>
 485         (none)
 486     </div>
 487     <div class="section example">
 488         <h3>Example(s):</h3>
 489 <pre class="example_code">import xaut
 490 kbd = xaut.keyboard()
 491 kbd.print_keycodes() #Prints out a listing of keycodes</pre>
 492     </div>
 493     <div class="nav">
 494         <a href="keyboard.html">Top of document</a>
 495     </div>
 496 </div>
 497
 498 </div><!-- /content -->
 499 <div id="footer">
 500 </div>
 501 </div><!-- /container -->
 502
 503 </body>
 504 </html>