action.create

Defines a new action

Usage

action.create [-i] [-c] [-l] [-w=<window_types:string>] [-s] [-t=<category:string>] (<name:string>,<visible label:string>,<description:string>,<big_icon_id:string>[,<small_icon_id:string>])
{
<action body>
}

Description

Defines a new script action.
Each action has an unique <name> that must not collide with any core action (i.e. don't use the KVIrc. prefix). At any time you can check action.list to verify that no core action is already using your <name>. If the <name> was already used for a script action then this action is simply replaced by the new one.
Each action has an associated <visible label> that is the name meant to be presented to the user, possibly even translated. This label will appear on the toolbar buttons, in the tooltips and in the popup menu items. The string will be evaluated just before the actions is displayed so the eventual runtime translation will fetch from the correct language catalogue.
<description> is the descriptive text that will be displayed in the action choice dialog (and maybe in other places). The string will be evaluated just before the actions is displayed so the eventual runtime translation will fetch from the correct language catalogue.
] <big_icon_id> is the image identifier of the icon that will appear on the toolbar buttons and in the action choice dialog.
<small_icon_id> is optional and is the image identifier of the icon that will appear in the menu items. Since menu items can be also iconless then this parameter is optional.
<action body> is the callback code snippet that will be triggered when this action is activated either by the means of action.trigger, a toolbar button or a menu item selection. An empty <action body> causes this command to behave like action.destroy <name>.

Switches

-i | --bind-to-context

Specifies that the action needs an IRC context to be executed. When the current window does not belong to an IRC context the action is automatically disabled

-c | --bind-to-connection

Specifies that the action needs an IRC connection to be executed. When the current window has no associated IRC connection the action is automatically disabled. This switch implies -i.

-l | --enable-at-login

Specifies that the action needs to be enabled at login time, that is when a link to the server has been established but the login operations haven't been carried out yet (and thus there is no real IRC connection). This switch requires -c to work.

-w=<window_types> | --window-types=<window_type>

Causes the action to be enabled only when the active window is one of the specified types. <window_types> may be any combination of the letters q (query), c (channel), x (console), d (dccchat). If this switch is omitted then the action is enabled in all the windows.

-s | --selected-only

Specifies that the action will be activated only if the active window has selected users in the userlist. This switch requires -w with a combination of flags q, c/b] and x (it doesn't work for DCC chat).

-t=<category> | --category=<category>

Causes the action to belong to the specified category. <category> can be one of IRC, scripting, settings, GUI, channel, tools and generic. If this switch is omitted the generic category is automatically assumed. The actions failing in the tools category will appear in the Tools KVIrc menu too.

-k=<key sequence> | --key-sequence=<key sequence>

Specifies that the action will be activated also by the <key sequence> which is a string formed from up to four keyboard codes separated by commas optionally combined with the modifiers Alt, Ctrl, Shift and Meta.
Examples of such sequences are: Ctrl+X", Ctrl+Alt+F or Ctrl+X,Alt+Space.

Examples