Alert¶
Alert settings are named settings objects stored at $HOME/.config/qtermy/alerts
. Alerts can be created and edited from the Manage Alerts window. The files can also be edited directly in a text editor, but note that qtermy does not monitor for external changes to settings files. Use the reload files button in the Manage Alerts window to load external changes and new files without restarting the application.
An alert is a description of a terminal condition, together with the action that should be taken when the condition becomes true. An alert can be made active in a terminal from the Terminal menu, various context menus, or by using the SetAlert
action. Only one alert can be active in a terminal at any given time.
When the condition described by the action becomes true in the terminal, the action will trigger and the action described by the alert will be taken. The alert will then be made inactive and will not trigger again in that terminal. An alert can also be made inactive from the Terminal menu, various context menus, or by using the ClearAlert
action.
Alerts can be favorited in the Manage Alerts window, which will cause them to appear at the top of alert selection menus.
Settings Categories
Condition¶
-
Type
(enumeration)
¶ The type of condition that the alert will monitor for. The choices are as follows:
- Activity in terminal: Any activity is reported by the terminal. This includes printable output as well as non-printing output such as control characters, bells, or region updates.
- Inactivity in terminal: No activity occurs in the terminal for the duration of time specified by
InactivityTime
. - Command finishes in terminal: A job finishes in the terminal with any exit status. This requires shell integration.
- Command succeeds in terminal: A job finishes in the terminal with an exit status of zero. This requires shell integration.
- Command fails in terminal: A job finishes in the terminal with a nonzero exit status. This requires shell integration.
- String seen in terminal: The literal string specified by
SearchString
is printed to the terminal. This must occur after the alert is made active (scrollback is not searched). - Regex seen in terminal: Any string matching the ECMAScript regular expression specified by by
SearchString
is printed to the terminal. This must occur after the alert is made active (scrollback is not searched). - Bell seen in terminal: A bell character (BEL, Ctrl+G) is printed to the terminal.
- Attribute is string: The terminal attribute named by
AttributeName
becomes equal to the literal string specified bySearchString
. If this condition is true when the alert isset
, the alert will trigger immediately. - Attribute is regex: The terminal attribute named by
AttributeName
matches the ECMAScript regular expression specified bySearchString
. If this condition is true when the alert isset
, the alert will trigger immediately.
-
InactivityTime
(integer)
¶ The time that the terminal must remain idle before the alert triggers, if the condition
Type
is set to monitor for inactivity.
Actions¶
-
SwitchProfile
(boolean)
¶ If enabled, the terminal will be
switched
to the configuredProfile
when the alert is triggered.
-
PushProfile
(boolean)
¶ If enabled, the terminal will be
pushed
to the configuredProfile
when the alert is triggered.
-
InvokeAction
(boolean)
¶ If enabled, the configured
Action
will be invoked when the alert is triggered.
-
RunLauncher
(boolean)
¶ If enabled, the configured
Launcher
will belaunched
with no marker substitutions when the alert is triggered.
-
DesktopNotify
(boolean)
¶ If enabled, the name of the alert and the configured
Message
will be passed toNotifySend
to show a desktop notification when the alert is triggered.
-
ShowIndicator
(boolean)
¶ If enabled, an "urgent" indicator icon will be displayed on the terminal thumbnail in the Terminals tool when the alert is triggered.
The "urgent" indicator icon will be cleared when input focus moves to or from the affected terminal, or when
ClearAlert
is called on the terminal.
-
FlashThumbnail
(boolean)
¶ If enabled, the the terminal thumbnail in the Terminals tool will flash the number of times configured by
Flashes
when the alert is triggered.
-
MoveTerminalForward
(boolean)
¶ If enabled,
ReorderTerminalFirst
will be called on the terminal when the alert is triggered.
-
MoveServerForward
(boolean)
¶ If enabled,
ReorderServerFirst
will be called on the terminal's server when the alert is triggered.
Parameters¶
-
Profile
(string)
¶ The profile to use if
SwitchProfile
orPushProfile
is enabled.
-
Action
(string)
¶ The action to invoke if
InvokeAction
is enabled. The strings<terminalId>
and<serverId>
within the action string will be replaced as appropriate at invocation time. Any other action parameters must be hard-coded.
-
Launcher
(string)
¶ The launcher to run if
RunLauncher
is enabled.
-
Flashes
(integer)
¶ The number of times to flash the terminal thumbnail if
FlashThumbnail
is enabled.Note
Thumbnail flashing may be interrupted if the terminal thumbnail is flashed for another reason, such as a
ThumbnailBell
orExitStatusEffect
.
-
Message
(string)
¶ The message to use as the
Body
parameter toNotifySend
ifDesktopNotify
is enabled. The name of the alert itself is used as theSummary
parameter.