Summary
Executes a Windows "shell" command
Prototype
ok, error = utils.shellexecute (filename, params, defdir, operation, show_command)
Description
Only the first argument (filename) is required, the rest are optional.
filename: The file to open or print or the folder to open or explore.
The function can open an executable file or a document file.
The function can print a document file.
params: A string that specifies the parameters to be passed to the application.
If filename specifies a document file, params should be nil or "".
defdir: A string that specifies the default directory.
operation: The following operation strings are valid:
"open": The function opens the file specified by the filename parameter.
The file can be an executable file or a document file. It can also be a folder.
"print": The function prints the file specified by filename.
The file should be a document file.
If the file is an executable file, the function opens the file,
as if "open" had been specified.
"explore": The function explores the folder specified by filename.
This parameter can be nil or "".
In that case, the function opens the file specified by filename.
show_command: If filename specifies an executable file, show_command specifies how the application is to be shown when it is opened.
This parameter can be nil in which case it defaults to 1 - the recommended default.
This parameter can be one of the following values:
0: Hides the window and activates another window.
1: Activates and displays a window.
If the window is minimized or maximized, Windows restores it to
its original size and position.
An application should specify this flag when displaying the window for the first time.
2: Activates the window and displays it as a minimized window.
3: Activates the window and displays it as a maximized window.
4: Displays a window in its most recent size and position.
The active window remains active.
5: Activates the window and displays it in its current size and position.
6: Minimizes the specified window and activates the next top-level window in the z-order.
7: Displays the window as a minimized window.
The active window remains active.
8: Displays the window in its current state.
The active window remains active.
9: Activates and displays the window.
If the window is minimized or maximized, Windows restores it to its original
size and position.
An application should specify this flag when restoring a minimized window.
10: Sets the show state based on the SW_ flag specified in the STARTUPINFO structure
passed to theCreateProcess function by the program that started the application.
An application should call ShowWindow with this flag to set the initial show
state of its main window.
If sucessful, the function returns true.
If not, it returns nil followed by an error message. You could use "assert" to test for failure.
Examples:
assert (utils.shellexecute ("c:/mushclient/worlds/SMAUG.MCL"))-- document
assert (utils.shellexecute ("http://www.gammon.com.au/")) -- web page
assert (utils.shellexecute ("mailto:someone@somewhere.com")) -- open mail client
assert (utils.shellexecute ("c:/", nil, nil, "explore")) -- explore disk
assert (utils.shellexecute ("c:/readme.txt", nil, nil, "print")) -- print a file
Warning: If you plan to redirect output (eg. capture a directory listing to a file) you may need to invoke the "cmd" shell. For example:
utils.shellexecute ("cmd", "/C dir > test.txt", GetInfo (68))
You may also want to pass 0 as the fifth argument (hide the window) in order to stop a command window flickering into view and then disappearing, for example:
utils.shellexecute ("cmd", "/C dir > test.txt", GetInfo (68), "open", 0)
See Also ...
Lua functions
utils.activatenotepad - Actvitates the specified notepad window
utils.appendtonotepad - Appends text to the specified notepad window
utils.base64decode - Decode a string which was base-64 encoded
utils.base64encode - Encode a string with base-64 encoding
utils.callbackslist - Returns a table of plugin callback function names
utils.choose - Display a combo box with choices in it
utils.colourcube - Changes the colour cube used by 256-colour ANSI codes
utils.compress - Compress a string
utils.decompress - Decompress a string
utils.directorypicker - Invokes the Windows standard "directory picker" dialog box
utils.editbox - Display a large message box and get free-format reply
utils.edit_distance - Returns the Levenshtein Edit Distance between two words
utils.filepicker - Invokes the Windows standard "file picker" dialog box
utils.filterpicker - Display a dialog box which filters its contents as you type
utils.fontpicker - Invokes the Windows standard "font picker" dialog box
utils.fromhex - Convert a string from hex
utils.functionlist - Returns a table of MUSHclient world function names
utils.getfontfamilies - Returns all fonts available to Windows
utils.glyph_available - Returns the glyph index of a glyph (character) in a font
utils.hash - Hash a string, returning the hex codes
utils.info - Information about directories, locale, etc.
utils.infotypes - Returns a table of all GetInfo type selectors
utils.inputbox - Display a message box and get free-format reply
utils.listbox - Display a dialog box with choices in it in a single selection list box
utils.md5 - Hash a string using the 128-bit MD5 algorithm
utils.menufontsize - Alters the size of the font used in menus
utils.metaphone - Returns metaphones (sound-alike codes) for the supplied word
utils.msgbox - Display a message box and get a response
utils.multilistbox - Display a dialog box with choices in it in a multiple selection list box
utils.readdir - Read a disk directory into a table
utils.reload_global_prefs - Forces global preferences file to be reloaded
utils.sendtofront - Bring a window to the front
utils.sha256 - Hash a string using a 256-bit hash
utils.spellcheckdialog - Spell-checker dialog
utils.split - Split a delimited string into a table
utils.timer - Returns the high-resolution timer output
utils.tohex - Convert a string into hex
utils.umsgbox - Display a message box and get a response (Unicode)
utils.utf8convert - Encodes a string into a UTF-8 string
utils.utf8decode - Encodes a series of Unicode codes into a UTF-8 string
utils.utf8encode - Encodes a series of Unicode codes into a UTF-8 string
utils.utf8sub - Returns a substring of a UTF-8 string
utils.utf8valid - Checks if a UTF-8 string is valid
utils.xmlread - Parses an XML string into a nested table
Topics
Lua base functions
Lua bc (big number) functions
Lua bit manipulation functions
Lua coroutine functions
Lua debug functions
Lua io functions
Lua LPEG library
Lua math functions
Lua os functions
Lua package functions
Lua PCRE regular expression functions
Lua script extensions
Lua string functions
Lua syntax
Lua table functions
Lua utilities
Scripting
Scripting callbacks - plugins
(Help topic: lua=utils.shellexecute)