Keyboard Object Functions
Function Synopsis
| Function | Brief Description |
|---|---|
| down_delay([delay]) | How long a key stays down when "clicked". |
| click_delay([delay]) | How long to pause between key clicks. |
| click(key) | A key to click by id. |
| down(key) | A key to press by id. Don't forget to release it! |
| up(key) | A key to release by id. Releases keys pressed by "down". |
| type(str) | A string to type. See detailed description below. |
| interpret_meta_symbols(tf) | Indicates whether to interpret meta symbols in type. |
| print_keycodes() | Prints X11 keycodes to the console. |
| capslock([tf]) | Turns caps lock on or off and returns status. |
| numlock([tf]) | Turns num lock on or off and returns status. |
| scroll_lock([tf]) | Turns scroll lock on or off and returns status. |
Function:
down_delay([delay])
Sets the value for how long the keyboard key stays down when "clicked" in milliseconds. Default is 10 milliseconds which usually works with most applications. Note that 0 rarely works. If you are trying to get a big speed boost and are getting surprising results, try changing this to 1. Does not make any changes if delay is less than zero or is omitted.
Parameters:
| Param | Req | Description |
|---|---|---|
| delay | no | The delay in milliseconds |
Return Value:
The current delay which may or may not have changed.Example(s):
#Change the down delay to 20 ms import xaut kbd = xaut.keyboard() delay = kbd.down_delay(20) print(delay) #Prints "20"
#Find current delay without making changes import xaut kbd = xaut.keyboard() delay = kbd.down_delay() print(delay) #Prints current delay
Function:
click_delay([delay])
How much time elapses between key clicks when "typing" in milliseconds. Default is 5 milliseconds, and usually works with most applications. Note that 0 rarely works. If you are trying to get a big speed boost and are getting surprising results, try changing this to 1. Does not make any changes if delay is less than zero or is omitted.
Parameters:
| Param | Req | Description |
|---|---|---|
| delay | no | The delay in milliseconds |
Return Value:
The current delay which may or may not have changed.Example(s):
#Change the click delay to 10 ms import xaut kbd = xaut.keyboard() delay = kbd.click_delay(10) print(delay) #Prints "10"
#Find the current delay without making any changes import xaut kbd = xaut.keyboard() delay = kbd.click_delay() print(delay) #Prints current delay
Function:
click(key)
Simulates pressing down and releasing a key by key code. Use print_keycodes() to get a listing of valid key codes. Use one of the values from the column labeled Code as a parameter.
Parameters:
| Param | Req | Description |
|---|---|---|
| key | yes | The keycode of the key to click |
Return Value:
Non-zero value of call succeeds, zero otherwise.
Be cautious, "succeeds" in this context doesn't necessarily mean that your application received the keycode. It means that X11 did not report any errors or throw any exceptions.
Example(s):
import xaut
kbd = xaut.keyboard()
success = kbd.click(36) #Sends the Return key
if(success):
print("X11 reports that the keycode 36 was sent")
else:
print("X11 reported an error when sending keycode 36")
Function:
down(key)
Simulates pressing down the key by key code. Use print_keycodes() to get a listing of valid key codes. This function would be useful if it is necessary to press a key combination that does not involve one of the meta keys. For example, this function can simultaneously press down the "a" and "b" key. You must release the key manually.
Note that the key usually releases by itself when the calling program terminates - but this is not guaranteed (at least not by me).
Use print_keycodes() to get a listing of valid keycodes. Use one of the values from the column labeled Code as a parameter.
Parameters:
| Param | Req | Description |
|---|---|---|
| key | yes | The key code of the key to press down. |
Return Value:
Non-zero value of call succeeds, zero otherwise.
Be cautious, "succeeds" in this context doesn't necessarily mean that your application received the keycode. It means that X11 did not report any errors or throw any exceptions.
Example(s):
import xaut import time kbd = xaut.keyboard() kbd.down(38) #Press down the "a" key kbd.down(56) #Press down the "b" key time.sleep(.1) kbd.up(56) #Release the "b" key kbd.up(38) #Release the "a" key
Function:
up(key)
Releases a key previously presed down. Note that this will not release an actual key, only a simulated key. Calling key_up without first calling key_down may or may not work, and may have "interesting" side effects. Fair warning.
Use print_keycodes() to get a listing of valid keycodes. Use one of the values from the column labeled Code as a parameter.
Parameters:
| Param | Req | Description |
|---|---|---|
| key | yes | The key code which should have been previously pressed "down" |
Return Value:
Non-zero value of call succeeds, zero otherwise.
Be cautious, "succeeds" in this context doesn't necessarily mean that your application received the keycode. It means that X11 did not report any errors or throw any exceptions.
Example(s):
import xaut import time kbd = xaut.keyboard() kbd.down(38) #Press down the "a" key kbd.down(56) #Press down the "b" key time.sleep(.1) kbd.up(56) #Release the "b" key kbd.up(38) #Release the "a" key
Function:
type(str)
Sends the sequence of characters in the string parameter. Note that there are a number of rules to keep in mind:
- Only valid characters are sent. So for example, character 7 (the bell) cannot be sent.
- The braces {} signify a special key code. The code contained
inside must correspond to a X11 key symbol name string. The brace
can also contain a number, which indicates the number of times to
press the key. E.g. {Tab} presses the tab key. {Tab 3} presses
the tab key three times. Use
print_keycodes()to get a listing of valid keycodes. You will want to use a value from the column called X11 key symbol name string. The symbols are case sensitive - they must match what is printed exactly. - Note that all valid X11 codes are valid inside braces.
- The exclamation point (!) signifies press the alt key for the next
letter. So
type("!a")would press the alt key down, then press and release the a key, and then finally release the alt key. - The plus sign (+) signifies press the shift key for the next
letter - similar to alt. So
type("+a")would press down the shift key down, press and release the a key, and then finally release the shift key. - The carat - or circumflex - (^) signifies press the control key
for the next letter - similar to shift and alt. So
type("^a")would press the control key, then press and release the a key, and then finally release the control key. - The number sign - or pound symbol - (#) signifies press the meta key
for the next letter - similar to shift, control, and alt. So
type("#a")would press the meta key, then press and release the a key, and then finally release the meta key. Note that the "meta" key is sometimes named after a certain software company :) - The previous special keys can be combined. So
type("+^#!a")would press and hold down the shift, control, meta, and alt keys, press and release the a, and then release the alt, meta, control, and shift keys. - Use the string name for a key if you wish to send a literal !, +, or ^. E.g. {exclam}{plus}{asciicircum} would send !+^ .
- Sending upper case letters as well as many symbols actually cause a shift and letter/symbol, e.g. A and +a are the same. For this reason, one should use lower case letters in combination with control keys to avoid confusion. ^a is not the same as ^A - ^A is precisely the same as ^+a .
- Invalid characters encountered (if any) are printed to the error stream and then ignored.
- Modifier keys (alt, control, and shift) are released after each
keycode in a brace, and after the next letter when not in a brace.
If you wish to use multiple letters in combination with modifier keys,
you'll need to construct the correct sequence yourself using the
correct codes and the
down()andup()functions. - You can set "interpret_meta_symbols" to false, which will cause the string to be sent literally. See interpret_meta_symbols for more information.
Parameters:
| Param | Req | Description |
|---|---|---|
| str | yes | The string to send |
Return Value:
Non-zero value if call succeeds, zero otherwise.
Be cautious, "succeeds" in this context doesn't necessarily mean that your application received the keycode. It means that X11 did not report any errors or throw any exceptions.
Example(s):
import xaut
kbd = xaut.keyboard()
kbd.type("This is a test{Return}")
kbd.type("!fa") #Opens the "Save As" dialog in some editors
Function:
interpret_meta_symbols(tf)
A way to tell the program whether to interpret meta symbols. If the text to be typed contains meta symbols (!#^+{}), and you want those symbols sent as opposed to interpreted, then set this to FALSE. Otherwise set this to TRUE - this is the default.
Parameters:
| Param | Req | Description |
|---|---|---|
| tf | yes | 0 tells xaut to send meta symbols as opposed to interpreting them, any non-zero value means interpret. |
Return Value:
(none)Example(s):
import xaut
import time
kbd = xaut.keyboard()
kbd.type("!f") #Sends the alt + f keys
time.sleep(3)
kbd.type("{Escape}")
time.sleep(3)
kbd.interpret_meta_symbols(0)
kbd.type("!f") #Literally sends !f
Parameters:
(none)Return Value:
(none)Example(s):
import xaut kbd = xaut.keyboard() kbd.print_keycodes() #Prints out a listing of keycodes
Function:
capslock([tf])
Can be used to turn caps lock on or off. Returns the status of caps lock. The keyboard light is aligned with the state that you set - even if it wasn't before calling the routine. However, xaut may not correctly detect keyboard state if the keyboard light and the status are not the same.
Parameters:
| Param | Req | Description |
|---|---|---|
| tf | no | 0 tells xaut to clear caps lock, -1 or no parameter tells xaut to make no changes, and 1 tells xaut to set caps lock. |
Return Value:
0 if caps lock is off after the call to the routine, 1 if it is on.Example(s):
# Find current state of caps lock key import xaut kbd = xaut.keyboard() state = kbd.capslock() # Note that I supplied no parameters print(state)
# Find current state of caps lock key import xaut kbd = xaut.keyboard() state = kbd.capslock(-1) # Note that '-1' is the parameter print(state)
# Set caps lock on import xaut kbd = xaut.keyboard() state = kbd.capslock(1) print(state) # Prints '1'
# Set caps lock off import xaut kbd = xaut.keyboard() state = kbd.capslock(0) print(state) # Prints '0'
# An example of changing and restoring state
import xaut
kbd = xaut.keyboard()
orig = kbd.capslock()
if orig:
print("Start with caps lock on")
else:
print("Start with caps lock off")
state = kbd.capslock(1) # Caps lock on
print(state)
state = kbd.capslock(0) # Caps lock off
print(state)
state = kbd.capslock(orig)
if state:
print("Finish with caps lock on")
else:
print("Finish with caps lock off")
# An example of mixed up keyboard status
# Be sure your caps lock is OFF for this test...
import xaut
kbd = xaut.keyboard()
kbd.type("{Caps_Lock}") # Caps lock is ON, but the light is OFF
state = kbd.capslock()
print(state) # State incorrectly has the value '0'
state = kbd.capslock(1)
print(state) # Caps lock is ON and the light is ON
state = kbd.capslock(0)
print(state) # Caps lock is OFF and the light is OFF
Function:
numlock([tf])
Can be used to turn num lock on or off. Returns the status of num lock. The keyboard light is aligned with the state that you set - even if it wasn't before calling the routine. However, xaut may not correctly detect keyboard state if the keyboard light and the status are not the same.
Parameters:
| Param | Req | Description |
|---|---|---|
| tf | no | 0 tells xaut to clear num lock, -1 or no parameter tells xaut to make no changes, and 1 tells xaut to set num lock. |
Return Value:
0 if num lock is off after the call to the routine, 1 if it is on.Example(s):
# Find current state of num lock key import xaut kbd = xaut.keyboard() state = kbd.numlock() # Note that I supplied no parameters print(state)
# Find current state of num lock key import xaut kbd = xaut.keyboard() state = kbd.numlock(-1) # Note that '-1' is the parameter print(state)
# Set num lock on import xaut kbd = xaut.keyboard() state = kbd.numlock(1) print(state) # Prints '1'
# Set num lock off import xaut kbd = xaut.keyboard() state = kbd.numlock(0) print(state) # Prints '0'
# An example of changing and restoring state
import xaut
kbd = xaut.keyboard()
orig = kbd.numlock()
if orig:
print("Start with num lock on")
else:
print("Start with num lock off")
state = kbd.numlock(1) # Num lock on
print(state)
state = kbd.numlock(0) # Num lock off
print(state)
state = kbd.numlock(orig)
if state:
print("Finish with num lock on")
else:
print("Finish with num lock off")
# An example of mixed up keyboard status
# Be sure your num lock is OFF for this test...
import xaut
kbd = xaut.keyboard()
kbd.type("{Num_Lock}") # num lock is ON, but the light is OFF
state = kbd.numlock()
print(state) # State incorrectly has the value '0'
state = kbd.numlock(1)
print(state) # Num lock is ON and the light is ON
state = kbd.numlock(0)
print(state) # Num lock is OFF and the light is OFF
Function:
scroll_lock([tf])
Can be used to turn scroll lock on or off. Returns the status of scroll lock. The keyboard light is aligned with the state that you set - even if it wasn't before calling the routine. However, xaut may not correctly detect keyboard state if the keyboard light and the status are not the same.
Note that scroll lock may or may not work with your programs, and is here for completeness sake only. I suggest you avoid using scroll lock functionality unless you understand the consequences of having scroll lock set on your computer.
Note also that "scroll_lock" has an underbar in its name. There are two reasons for that: 1) Because it would invite errors to have a command that contains "lll" - it's better to be ll_l, and 2) It further impresses the point that scroll lock is an oddball command compared to the others (caps lock and num lock).
Parameters:
| Param | Req | Description |
|---|---|---|
| tf | no | 0 tells xaut to clear scroll lock, -1 or no parameter tells xaut to make no changes, and 1 tells xaut to set scroll lock. |
Return Value:
0 if scroll lock is off after the call to the routine, 1 if it is on.Example(s):
# Find current state of scroll lock key import xaut kbd = xaut.keyboard() state = kbd.scroll_lock() # Note that I supplied no parameters print(state)
# Find current state of scroll lock key import xaut kbd = xaut.keyboard() state = kbd.scroll_lock(-1) # Note that '-1' is the parameter print(state)
# Set scroll lock on import xaut kbd = xaut.keyboard() state = kbd.scroll_lock(1) print(state) # Prints '1'
# Set scroll lock off import xaut kbd = xaut.keyboard() state = kbd.scroll_lock(0) print(state) # Prints '0'
# An example of changing and restoring state
import xaut
kbd = xaut.keyboard()
orig = kbd.scroll_lock()
if orig:
print("Start with scroll lock on")
else:
print("Start with scroll lock off")
state = kbd.scroll_lock(1) # Scroll lock on
print(state)
state = kbd.scroll_lock(0) # Scroll lock off
print(state)
state = kbd.scroll_lock(orig)
if state:
print("Finish with scroll lock on")
else:
print("Finish with scroll lock off")
# An example of mixed up keyboard status
# Be sure your scroll lock is OFF for this test...
import xaut
kbd = xaut.keyboard()
kbd.type("{Scroll_Lock}") # scroll lock is ON, but the light is OFF
state = kbd.scroll_lock()
print(state) # State incorrectly has the value '0'
state = kbd.scroll_lock(1)
print(state) # Scroll lock is ON and the light is ON
state = kbd.scroll_lock(0)
print(state) # Scroll lock is OFF and the light is OFF