def storescript(script, path, replacing=kAsk):
"""Store a script object into a file
script : AEDesc -- the script object to store (an AEDesc of typeScript)
path : str -- the file to store the script object in
replacing : kYes | kAsk | kNo -- control display of Save As dialog; default is kAsk
"""
osax('sysostor', {'----':script, 'fpth':macfile.File(path), 'savo':replacing})
def say(text, display=None, voice=None, waiting=None, outputfile=None, app=kCurrentApplication):
"""Speak the given text.
text : str -- the text to speak, which can include intonation characters
display : str -- the text to display in the feedback window (if different). Ignored unless Speech Recognition is on.
voice : str -- the voice to speak with. Ignored if Speech Recognition is on.
waiting : bool -- wait for speech to complete before returning (default is true). Ignored unless Speech Recognition is on.
outputfile : anything -- the alias, file reference or Mac-style path string of an AIFF file (existing or not) to contain the sound output.
app : aem.send.Application -- the application to use (default = kCurrentApplication)
"""
osax('sysottos', _params({'----':text}, ('DISP', display), ('VOIC', voice), ('wfsp', waiting), ('stof', outputfile)), target=app)
def storescript(script, path, replacing=kAsk):
"""Store a script object into a file
script : AEDesc -- the script object to store (an AEDesc of typeScript)
path : str -- the file to store the script object in
replacing : kYes | kAsk | kNo -- control display of Save As dialog; default is kAsk
"""
osax('sysostor', {
'----': script,
'fpth': macfile.File(path),
'savo': replacing
})
def systemattribute(attribute, testbits=None):
"""Test attributes of this computer
attribute : str -- 4-letter code; the attribute to test (either a "Gestalt" value or a shell environment variable). # TO CHECK: Which codes? Does it take long strings too? (Apple's documentation is hopeless...)
testbits : int -- test specific bits of response
Result: int | str -- the result of the query (or a list of all environment variables, if no attribute is provided)
"""
return osax('fndrgstl', _params({'----':AEType(attribute)}, ('has ', testbits)))
def displaydialog(text,
buttons=None,
defaultbutton=None,
defaultanswer=None,
icon=None,
timeout=None,
app=kCurrentApplication):
"""Display a dialog box, optionally requesting user input
text : str -- the text to display in dialog box
buttons : list of str -- a list of up to three button names
defaultbutton : int | str -- the name or number of the default button
defaultanswer : str -- the default editable text
icon : str | int | kStop | kNote | kCaution -- the name or ID of the icon to display
timeout : int -- number of seconds to wait before automatically dismissing dialog
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result : (str, str, bool) -- the button clicked (or '' if dialog gave up), text entered (or None if no defaultanswer given), dialog timed-out flag (or None if no timeout given)
"""
try:
reply = osax('sysodlog',
_params({'----': text}, ('dtxt', defaultanswer),
('btns', buttons), ('dflt', defaultbutton),
('disp', icon), ('givu', timeout)),
target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def chooseitems(items,
prompt=None,
default=None,
multiselelect=None,
emptyselect=None,
okbutton=None,
cancelbutton=None,
app=kCurrentApplication):
"""Allows user to select an item from a list of strings
items : list of str -- a list of strings to display (an empty list if no selection)
prompt : str -- the prompt to appear at the top of the list selection dialog
default : list of str -- list of strings to initially select
okbutton : str -- the name of the OK button
cancelbutton : str -- the name of the Cancel button
multiselelect : bool -- Allow multiple items to be selected?
emptyselect : bool -- Can the user make no selection and then choose OK?
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result : list of str -- the list of strings chosen
"""
reply = osax('gtqpchlt',
_params({'----': items}, ('prmp', prompt), ('inSL', default),
('mlsl', multiselelect), ('empL', emptyselect),
('okbt', okbutton), ('cnbt', cancelbutton)),
target=app)
if reply == False:
raise UserCancelled
else:
return reply
def systemattribute(attribute, testbits=None):
"""Test attributes of this computer
attribute : str -- 4-letter code; the attribute to test (either a "Gestalt" value or a shell environment variable). # TO CHECK: Which codes? Does it take long strings too? (Apple's documentation is hopeless...)
testbits : int -- test specific bits of response
Result: int | str -- the result of the query (or a list of all environment variables, if no attribute is provided)
"""
return osax('fndrgstl',
_params({'----': AEType(attribute)}, ('has ', testbits)))
def pathto(location, domain=None, asstring=False):
"""Returns full path name to the folder specified
location : kApplicationSupport | kCurrentUser | kDesktop | kDesktopPictures | kFolderActions | kFonts | kHelp | kKeychain | kModemScripts | kPreferences | kPrinterDescriptions | kScriptingAdditions | kScripts | kSharedLibraries | kStartupDisk | kSystem | kSystemPreferences | kTemporaryItems | kTrash | kUsers | kVoices -- the folder to return
domain : kNetworkDomain | kSystemDomain | kLocalDomain | kUserDomain -- where to look for the indicated folder
asstring : boolean -- return unicode string (Mac path) instead of alias
Result: macfile.Alias | str -- the path name to the folder or application specified
"""
return osax('earsffdr', _params({'----':location}, ('from', domain), ('rtyp', asstring and AEType('utxt') or None)))
def clipboardinfo(desiredtype=None):
"""Return information about the clipboard
desiredtype : str -- 4-letter code; restricts result to information about only this data type
Result: list of list -- one list of [data type, size] for each type of data on the clipboard
"""
return osax('JonsiClp',
_params({}, ('for ', desiredtype and AEType(desiredtype))),
target=_SystemEvents)
def getclipboard(desiredtype=None):
"""Return the contents of an application's clipboard. Activate the target application first
desiredtype : str -- 4-letter code; the type of data desired (see also clipboardinfo)
Result: list of anything -- the data from its clipboard
"""
return osax('JonsgClp',
_params({}, ('rtyp', desiredtype and AEType(desiredtype))),
target=_SystemEvents)
def runscript(script, parameters=[], component='AppleScript'):
"""Run a specified OSA script or script file.
script : str | Alias | FSSpec -- the script text, an alias or file reference of a script file, or an AEDesc of typeScript to run
[parameters : list of anything -- list of parameters
[component : str -- the scripting component to use; default is AppleScript
Result: anything -- the result of running the script
"""
return osax('sysodsct', {'----':script, 'plst':parameters, 'scsy':component})
def say(text,
display=None,
voice=None,
waiting=None,
outputfile=None,
app=kCurrentApplication):
"""Speak the given text.
text : str -- the text to speak, which can include intonation characters
display : str -- the text to display in the feedback window (if different). Ignored unless Speech Recognition is on.
voice : str -- the voice to speak with. Ignored if Speech Recognition is on.
waiting : bool -- wait for speech to complete before returning (default is true). Ignored unless Speech Recognition is on.
outputfile : anything -- the alias, file reference or Mac-style path string of an AIFF file (existing or not) to contain the sound output.
app : aem.send.Application -- the application to use (default = kCurrentApplication)
"""
osax('sysottos',
_params({'----': text}, ('DISP', display), ('VOIC', voice),
('wfsp', waiting), ('stof', outputfile)),
target=app)
def pathto(location, domain=None, asstring=False):
"""Returns full path name to the folder specified
location : kApplicationSupport | kCurrentUser | kDesktop | kDesktopPictures | kFolderActions | kFonts | kHelp | kKeychain | kModemScripts | kPreferences | kPrinterDescriptions | kScriptingAdditions | kScripts | kSharedLibraries | kStartupDisk | kSystem | kSystemPreferences | kTemporaryItems | kTrash | kUsers | kVoices -- the folder to return
domain : kNetworkDomain | kSystemDomain | kLocalDomain | kUserDomain -- where to look for the indicated folder
asstring : boolean -- return unicode string (Mac path) instead of alias
Result: macfile.Alias | str -- the path name to the folder or application specified
"""
return osax(
'earsffdr',
_params({'----': location}, ('from', domain),
('rtyp', asstring and AEType('utxt') or None)))
def runscript(script, parameters=[], component='AppleScript'):
"""Run a specified OSA script or script file.
script : str | Alias | FSSpec -- the script text, an alias or file reference of a script file, or an AEDesc of typeScript to run
[parameters : list of anything -- list of parameters
[component : str -- the scripting component to use; default is AppleScript
Result: anything -- the result of running the script
"""
return osax('sysodsct', {
'----': script,
'plst': parameters,
'scsy': component
})
def choosefolder(prompt=None, app=kCurrentApplication):
"""Choose a folder on a disk or server
prompt : str -- a prompt to be displayed in the folder chooser
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result: macfile.Alias -- chosen folder
"""
try:
return osax('sysostfl', _params({}, ('prmp', prompt)), target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def choosefolder(prompt=None, app=kCurrentApplication):
"""Choose a folder on a disk or server
prompt : str -- a prompt to be displayed in the folder chooser
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result: macfile.Alias -- chosen folder
"""
try:
return osax('sysostfl', _params({}, ('prmp', prompt)), target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def choosenewfile(prompt=None, defaultname=None, app=kCurrentApplication):
"""Get a new file reference from the user, without creating the file
prompt : str -- the text to display in the file creation dialog box
defaultname : str -- the default name for the new file
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result: str -- the URL of the file the user specified
"""
try:
return osax('sysonwfl', _params({}, ('prmt', prompt), ('dfnm', defaultname)), target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def choosefile(prompt=None, onlyshowtypes=None, app=kCurrentApplication):
"""Choose a file on a disk or server
prompt : str -- a prompt to be displayed in the file chooser
onlyshowtypes : list of str -- restrict the files shown to only these file types (up to 4)
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result : macfile.Alias -- to the chosen file
"""
try:
return osax('sysostdf', _params({}, ('prmp', prompt), ('ftyp', onlyshowtypes)), target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def chooseurl(showservices=None, editable=None, app=kCurrentApplication):
"""Choose a service on the Internet
showservices : list of kWebServers | kFTPServers | kTelnetHosts | kFileServers | kNewsServers | kDirectoryServices | kMediaServers | kRemoteApplications -- which network services to show
editable [pedu] <bool> (optional) -- Allow user to type in a URL?
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result: str -- the URL chosen
"""
try:
return osax('sysochur', _params({}, ('', showing)), target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def chooseurl(showservices=None, editable=None, app=kCurrentApplication):
"""Choose a service on the Internet
showservices : list of kWebServers | kFTPServers | kTelnetHosts | kFileServers | kNewsServers | kDirectoryServices | kMediaServers | kRemoteApplications -- which network services to show
editable [pedu] <bool> (optional) -- Allow user to type in a URL?
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result: str -- the URL chosen
"""
try:
return osax('sysochur', _params({}, ('', showing)), target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def chooseapp(title=None, prompt=None, multiselect=None, app=kCurrentApplication):
"""Choose an application on this machine or the network
title : str -- the dialog window title
prompt : str -- the prompt to appear at the top of the application chooser dialog box
multiselect : bool -- Allow multiple items to be selected?
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result : macfile.Alias | list of macfile.Alias -- path(s) to application(s)
"""
try:
return osax('sysoppcb', _params({'rtyp':AEType('alis')}, ('appr', title), ('prmp', prompt), ('mlsl', multiselect)), target=app, timeout=3600*5) # extra-long timeout as making multiple selections can take some time
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def choosefile(prompt=None, onlyshowtypes=None, app=kCurrentApplication):
"""Choose a file on a disk or server
prompt : str -- a prompt to be displayed in the file chooser
onlyshowtypes : list of str -- restrict the files shown to only these file types (up to 4)
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result : macfile.Alias -- to the chosen file
"""
try:
return osax('sysostdf',
_params({}, ('prmp', prompt), ('ftyp', onlyshowtypes)),
target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def choosenewfile(prompt=None, defaultname=None, app=kCurrentApplication):
"""Get a new file reference from the user, without creating the file
prompt : str -- the text to display in the file creation dialog box
defaultname : str -- the default name for the new file
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result: str -- the URL of the file the user specified
"""
try:
return osax('sysonwfl',
_params({}, ('prmt', prompt), ('dfnm', defaultname)),
target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def displaydialog(text, buttons=None, defaultbutton=None, defaultanswer=None, icon=None, timeout=None , app=kCurrentApplication):
"""Display a dialog box, optionally requesting user input
text : str -- the text to display in dialog box
buttons : list of str -- a list of up to three button names
defaultbutton : int | str -- the name or number of the default button
defaultanswer : str -- the default editable text
icon : str | int | kStop | kNote | kCaution -- the name or ID of the icon to display
timeout : int -- number of seconds to wait before automatically dismissing dialog
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result : (str, str, bool) -- the button clicked (or '' if dialog gave up), text entered (or None if no defaultanswer given), dialog timed-out flag (or None if no timeout given)
"""
try:
reply = osax('sysodlog', _params({'----':text}, ('dtxt', defaultanswer), ('btns', buttons), ('dflt', defaultbutton), ('disp', icon), ('givu', timeout)), target=app)
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def chooseitems(items, prompt=None, default=None, multiselelect=None, emptyselect=None, okbutton=None, cancelbutton=None, app=kCurrentApplication):
"""Allows user to select an item from a list of strings
items : list of str -- a list of strings to display (an empty list if no selection)
prompt : str -- the prompt to appear at the top of the list selection dialog
default : list of str -- list of strings to initially select
okbutton : str -- the name of the OK button
cancelbutton : str -- the name of the Cancel button
multiselelect : bool -- Allow multiple items to be selected?
emptyselect : bool -- Can the user make no selection and then choose OK?
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result : list of str -- the list of strings chosen
"""
reply = osax('gtqpchlt', _params({'----':items}, ('prmp', prompt), ('inSL', default), ('mlsl', multiselelect),
('empL', emptyselect), ('okbt', okbutton), ('cnbt', cancelbutton)), target=app)
if reply == False:
raise UserCancelled
else:
return reply
def chooseapp(title=None,
prompt=None,
multiselect=None,
app=kCurrentApplication):
"""Choose an application on this machine or the network
title : str -- the dialog window title
prompt : str -- the prompt to appear at the top of the application chooser dialog box
multiselect : bool -- Allow multiple items to be selected?
app : aem.send.Application -- the application to use (default = kCurrentApplication)
Result : macfile.Alias | list of macfile.Alias -- path(s) to application(s)
"""
try:
return osax(
'sysoppcb',
_params({'rtyp': AEType('alis')}, ('appr', title),
('prmp', prompt), ('mlsl', multiselect)),
target=app,
timeout=3600 * 5
) # extra-long timeout as making multiple selections can take some time
except MacOS.Error, err:
if err[0] == -128: # user cancelled
raise UserCancelled
else:
raise
def beep(times=None):
"""Beep 1 or more times
times : int -- number of times to beep
"""
osax('sysobeep', _params({}, ('----', times)))
def setclipboard(data):
"""Place data on an application's clipboard. Activate the target application first
data : anything -- the data to place on the clipboard
"""
return osax('JonspClp', {'----': data}, target=_SystemEvents)
def loadscript(path):
"""Return a script object loaded from a specified disk file
path : str -- the file containing the script object to load
Result: AEDesc -- the script object loaded (an AEDesc of typeScript)
"""
return osax('sysoload', {'----': macfile.File(path)})
def scriptingcomponents():
"""Return a list of all scripting components (e.g. AppleScript)
Result: <TEXT> (list) -- a list of installed scripting components
"""
return osax('sysocpls')
def setvolume(level):
"""Set the sound output volume
level : int -- the volume level, from 0 (silent) to 7 (full volume)
"""
osax('aevtstvl', {'----':level})
def scriptingcomponents():
"""Return a list of all scripting components (e.g. AppleScript)
Result: <TEXT> (list) -- a list of installed scripting components
"""
return osax('sysocpls')
def setvolume(level):
"""Set the sound output volume
level : int -- the volume level, from 0 (silent) to 7 (full volume)
"""
osax('aevtstvl', {'----': level})
def beep(times=None):
"""Beep 1 or more times
times : int -- number of times to beep
"""
osax('sysobeep', _params({}, ('----', times)))
def loadscript(path):
"""Return a script object loaded from a specified disk file
path : str -- the file containing the script object to load
Result: AEDesc -- the script object loaded (an AEDesc of typeScript)
"""
return osax('sysoload', {'----':macfile.File(path)})
def clipboardinfo(desiredtype=None):
"""Return information about the clipboard
desiredtype : str -- 4-letter code; restricts result to information about only this data type
Result: list of list -- one list of [data type, size] for each type of data on the clipboard
"""
return osax('JonsiClp', _params({}, ('for ', desiredtype and AEType(desiredtype))), target=_SystemEvents)
def getclipboard(desiredtype=None):
"""Return the contents of an application's clipboard. Activate the target application first
desiredtype : str -- 4-letter code; the type of data desired (see also clipboardinfo)
Result: list of anything -- the data from its clipboard
"""
return osax('JonsgClp', _params({}, ('rtyp', desiredtype and AEType(desiredtype))), target=_SystemEvents)
def setclipboard(data):
"""Place data on an application's clipboard. Activate the target application first
data : anything -- the data to place on the clipboard
"""
return osax('JonspClp', {'----':data}, target=_SystemEvents)