Common Interfaces¶
The plugin API is exposed through objects in the global namespace:
-
plugin
¶ Provides version and system information attributes, utility methods, and the registration methods used to create plugin features.
-
console
¶ Provides logging methods.
Logging¶
-
console.
log
(message)¶ Creates a log message at the info level containing the plugin's
name
in square brackets followed by the given message string.
-
console.
info
(message)¶ Same as
console.log()
.
-
console.
warn
(message)¶ As
console.log()
, but creates the log message at the warning level.
Constants¶
-
plugin.
majorVersion
¶ The major version of the plugin API. Check this value before registering any features to ensure that the plugin is compatible with the plugin API.
-
plugin.
minorVersion
¶ The minor version of the plugin API. Check this value if the plugin depends on a particular interface introduced by a minor revision of the plugin API.
-
plugin.
installPrefix
¶ The install prefix configured when qtermy was built. Useful for plugins which need to reference files or paths relative to the install location.
-
plugin.
installDatadir
¶ (API version 1.3) The install datadir configured when qtermy was built.
-
plugin.
installConfdir
¶ (API version 1.3) The install sysconfdir configured when qtermy was built.
Properties¶
-
plugin.
pluginName
¶ Assign the name of the plugin to this property before registering any features. It will be shown in the Manage Plugins window and in log messages. If unset, the name of the plugin's source file will be used.
-
plugin.
pluginVersion
¶ Assign the version of the plugin to this property before registering any features. It will be shown in the Manage Plugins window but is otherwise not used by the plugin system.
-
plugin.
pluginDescription
¶ Assign a brief, one line description of the plugin to this property before registering any features. It will be shown in the Manage Plugins window but is otherwise not used by the plugin system.
Methods¶
-
plugin.
now
()¶ Returns a timestamp value representing the current time, measured in tenths of a second. This can be used to compare relative times.
-
plugin.
htmlEscape
(string)¶ Returns the given string with HTML metacharacters replaced by the appropriate HTML entities.
-
plugin.
registerSemanticParser
(version, name, callback[, variant])¶ Registers a semantic parser feature. The variant argument specifies the parser type and is one of:
- 0: a standard parser (the default)
- 1: a fast parser
Arguments: - version (integer) -- The requested interface version (must be 1). Future revisions of the API may introduce new versions.
- name (string) -- The name of the parser being registered.
- callback (function) -- The parser's
match function
. - variant (integer) -- The type of parser being registered.
-
plugin.
registerCustomAction
(version, name, callback[, description])¶ Registers a custom action feature.
Arguments: - version (integer) -- The requested interface version (must be 1). Future revisions of the API may introduce new versions.
- name (string) -- The name of the action. To invoke the action from a key binding or elsewhere within qtermy, prepend "Custom" to this name.
- callback (function) -- The action's
run function
. - description (string) -- A brief, one line description of the action. This will be displayed in tooltips but is otherwise not used by the plugin system. If unspecified, the value of
plugin.pluginDescription
is used.
-
plugin.
registerTipProvider
(version, callback)¶ Registers a tip of the day provider. There can only be one of these registered.
Arguments: - version (integer) -- The requested interface version (must be 1). Future revisions of the API may introduce new versions.
- callback (function) -- The tip provider's
tip function
.
File Interface¶
-
plugin.
createOutputFile
(filename)¶ Creates and opens a file for writing, overwriting any existing file with the same name. The file is created in the
DownloadLocation
specified in the global settings. An Error exception is thrown on open failure. Otherwise, a handle object is returned with attributes and methods described below.
-
fileHandle.
path
¶ The path of this handle's file.
-
fileHandle.
print
(value)¶ Writes the given value to this handle's file as UTF-8 text. No newline is added to the printed string.
-
fileHandle.
close
()¶ Closes this handle's file. This is required; file handles are not closed implicitly.