<doctitle>Scripting language syntax : events</doctitle> <docbody>

<docsubtitle>Introduction</docsubtitle>

> The events are triggered by KVirc to allow your script to *react to particular situations*: for each event you can provide a handler script.
> There are two types of events: high-level and raw.
> The high-level events are the ones that you will normally use in your scripts.
> These are triggered when a RECOGNIZED event occures: for example , when an user joins a channel , the OnJoin event is triggered.
> The Raw events are triggered just after a message from the server has been received.

<docsubtitle>High-Level events</docsubtitle>

> There is a large (but fixed) set of high-level events that you can react to.
> You can set a handler for each one of these events by the means of the script dialog.
> Each event is triggered in a specific window:
> for example , the OnJoin event is triggered in the channel window that the user is joining in.
> The 'halt' command has a special meaning in many hihg-level events:
> it usually prevents KVirc from printing the default output to the window.
> See the event-specific documentation for the exact meaning of 'halt'.

<docsubtitle>Raw events</docsubtitle>

> The raw events give you high control of the KVirc actions: you can add a "hook" for any server command.
> A raw event handler is triggered when a specific server command (message) is received.
> For example you can define a handler for ALL the PRIVMSG messages or all the numeric 001 replies.
> In the first case you will be able to process all the JOIN messages directed to ALL the channels , in the second case you will be able to handle the "Server welcome message" in your script.

> The server messages are of two types : numeric and literal.
> The literal messages (also called "commands") are usually sent by other users on the irc network and simply routed by the server; these include "JOIN" , "PART" , "PRIVMSG" , "MODE" and so on...
> The numeric messages are sent by the server as replies to local requests.
> For example , if you send the VERSION command to the server , it will (or at least is should) reply with the numeric 351 (the human readable name of this reply is RPL_VERSION).
> A good use of Raw events is for parsing and reacting to messages that KVIrc itself does not (yet) understand:
> there are many numeric replies that are just "printed" on the screen , without any special processing.

> It is important to understand that the raw events are triggered BEFORE effectively processing the message.
> So if you catch a JOIN message , be aware that this message has not been processed by KVIrc yet , and the joining user is "actually not on the channel".
> Also the high-level events are triggered after the raw-events.
> All the raw events are triggered in the console window.

> All the raw events have a source mask associated.
> The source mask is a simple regular expression (string with '*' wildcards) that acts as a filter for the messages to be processed.
> If you add a handler for the JOIN message and specify *.com as source mask , you will catch only the JOIN messages from users that have ".com" at the end of their masks.
> To catch all the messages just use the single wildcard source mask ( '*' ).
> Please note that the source for a literal message is usually an user-mask, for a numeric messages is usually a server!.

> If you call "halt" in a raw event handler , the message will be considered as "handled" , and no further output will be printed by KVirc , also the high-level OnUnhandled* events will NOT be triggered.
> WARNING : Be sure to know what you are doing when you use halt in a raw event.
> You may easily confuse the user if you do not provide him the necessary feedback on the messages that have been received from the server.
> Note:
> In some specific (and rather critical) cases KVirc will print some output even if 'halt' was called.

> The parameters of a raw event are the source mask and the parameters that the server sends just after the command.
> So , in $1 you will get the source mask (origin of the message), in $2 the first parameter , in $3 the second...
> The last parameter has a special encoding to allow it to contain spaces: you will find a leading ':' character before this one.
> I had a problem when I had to decide how to pass this parameter to an event.
> I've choosen to split everything by spaces and leave the leading colon to allow you to recognize the beginning of the last parameter.
> So , for example the numeric message 474 arrives as follows:
> :servername 474 YourNickname :Cannot join channel (+b)
> It will be passed in the following way:
> $1 = servername
> $2 = YourNickname
> $3 = :Cannot
> $4 = join
> $5 = channel
> To access the whole last parameter (in RFC1459 it is defined as "trailing") you should use $strCutLeft(1,$3-).

> You can add more than one raw event handler for each message sent by the server.
> The handlers will be called in an ARBITRARY ORDER

> Note for raw event handlers:

> A special feature has been added for debugging purposes to the raw event handlers processing:
> You can stop further processing of the message by returning the string "stop" from the event handler (see setreturn).
> This is rather dangerous ,because you can cause KVIrc to go "out of sync":
> If you catch the JOIN message and then call "setreturn stop" , you will never see the user joining the channel!.
> So, be sure to know what happens inside the KVirc sources when using this feature on a specific raw event.

Main index , Syntax index , Index of supported events </docbody>

</docbody>