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

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

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

<docsubtitle>Raw events</docsubtitle>
<blockquote>
<p>
The raw events give you high control of the KVirc actions:
you can add a "hook" for any server command.<br>
A raw event handler is triggered when a specific server command (message) is received.<br>
For example you can define a handler for ALL the PRIVMSG messages or all the
numeric 001 replies.<br>
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.<br>
</p>
<p>
The server messages are of two types : numeric and literal.<br>
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...<br>
The numeric messages are sent by the server as replies to local requests.<br>
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).<br>
A good use of Raw events is for parsing and reacting to messages that KVIrc itself does not (yet) understand:<br>
there are many numeric replies that are just "printed" on the screen , without any special processing.<br>
</p>
<p>
It is important to understand that the raw events are triggered BEFORE effectively processing the message.<br>
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".<br>
Also the high-level events are triggered after the raw-events.<br>
All the raw events are triggered in the console window.<br>
</p>
<p>
All the raw events have a source mask associated.<br>
The source mask is a simple regular expression (string with '*' wildcards) that acts as a filter
for the messages to be processed.<br>
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.<br>
To catch all the messages just use the single wildcard source mask ( '*' ).<br>
Please note that the source for a literal message is usually an user-mask, for a numeric messages is usually a server!.<br>
</p>
<p>
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.<br>
WARNING : Be sure to know what you are doing when you use halt in a raw event.<br>
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.<br>
Note:<br>
In some specific (and rather critical) cases KVirc will print some output even if 'halt' was called.<br>
</p>
<p>
The parameters of a raw event are the source mask and the parameters that the server sends just after the command.<br>
So , in $1 you will get the source mask (origin of the message), in $2 the first parameter , in $3 the second...<br>
The last parameter has a special encoding to allow it to contain spaces:
you will find a leading ':' character before this one.<br>
I had a problem when I had to decide how to pass this parameter to an event.<br>
I've choosen to split everything by spaces and leave the leading colon to allow you to
recognize the beginning of the last parameter.<br>
So , for example the numeric message 474 arrives as follows:<br>
<b>:servername 474 YourNickname :Cannot join channel (+b)</b><br>
It will be passed in the following way:<br>
$1 = servername<br>
$2 = YourNickname<br>
$3 = :Cannot<br>
$4 = join<br>
$5 = channel<br>
To access the whole last parameter (in RFC1459 it is defined as "trailing") you should use
<a href="s_strcutleft.kvihelp">$strCutLeft</a>(1,$3-).<br>
</p>
<p>
You can add more than one raw event handler for each message sent by the server.<br>
The handlers will be called in an <b>ARBITRARY ORDER</b>
</p>
</blockquote>

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

<hr>
<a href="index.kvihelp">Main index</a> , <a href="syntax.kvihelp">Syntax index</a> , <a href="events.kvihelp">Index of supported events</a>
</docbody>


</docbody>
