| Trillian Perl Library Reference |
TrillianPlugin - Utility Functions for TrillPerl Scripts
Library Module interface for the Trillian Perl Plugin. Includes many useful utility functions for use in your Trillian Perl Scripts.
Thanks to all the Trillian <http://www.trillian.cc/> programmers for making such a great product. Thanks also to Azhrarn, for putting some of the little time he has free into this project, and showing me how to use POD2HTML. Thanks to Dan Schaub for sticking at the program after several hundred crashes, where most people would have given up and gone home. Finally thanks to Sjoerd for making a funky logo for this project. I guess someone should thank Larry Wall too, because without him, there would be no Perl to write a perl plugin for either.
use TrillianPlugin;
TrillianPlugin::DispatchEvent;
# Other Stuff here...
Any accessible functions and/or variables declared in this module can, and should be used by a trillperl script to interact with trillian. The variables and functions in the TrillPerl:: namespace CAN be used in your script, but you should avoid this and use the equivalents wrapped within this module, as they provide and extra layer of checking and safety, to make sure you don't accidentally pass the wrong number of parameters to the function and cause your plugin to bomb.
IMPORTANT: You must not pass undef's to these functions in place of values, unless specified that this will work. Passing an undef is different to passing an empty value or a 0, when you pass an undef, you pass *NOTHING*, so trillian's C api will interpret this as a NULL. This can cause undefined behaviour!i
%TrillianPlugin::Contacts is a hash of all contacts, online and offline, gathered using the plugin API contactlistEnumerate function. You MAY temporarily change this array, however if you do then your changes will be lost the next time the list is refreshed from the API, so this list should be treated as READ ONLY even though in actual fact it is not. The list is populated as follows:
$Contacts{name}{medium} = medium name of user, e.g. ``MSN'' $Contacts{name}{CID} = user's connection ID $Contacts{name}{realname} = users display name (``real name'') $Contacts{name}{section} = section of the contact list the user's icon and name are in, e.g. ``Contacts'' or ``Buddies'' $Contacts{name}{status} = user status, e.g. ``online'', ``away'', ``offline'' $Contacts{name}{statusidle} = nonzero if user is idle $Contacts{name}{statusblock} = nonzero if the user is blocked/ignored
%TrillianPlugin::API is a hash of all available external APIs.
It is in the form of:
$API{guid}{event};
Which will tell you if the api type 'event' is available in the given plugin GUID. All existing API types contain the value '1' (therefore are defined in the hash).
This hash holds various paths to the different directories that trillian uses. These paths are defined in various ini files, so they can be potentially different then what is expected. The current possible values are as follows:
This hash is populated by the TrillianPlugin::GetProfiles function. It holds most of the contents of the profiles.ini file. The format is one of two things. One key which should always be there is the name of the key that holds the active profile (the one that trillian defaults to loading) in $TrillianPlugin::Profiles{'Active'} Normally this will point to ``Profile000'' which is the default profile that Trillian creates. The 'Active' key is the only scalar value in the array. The rest are section headers for each profile, each referencing a secondary hash for each parameter in the section. They are in the format $Trillian{'Section'}{'Parameter'} The typical Parameters are Preferences Type, Automatic Login, Password, Preferences Location, and Name. Remember that they are Case Sensitive when referencing the keys. Other examples are as follows.
Example:
TrillianPlugin::GetProfiles;
my $profile = "Profile001"; # This is a second profile I created, listed second in the file after the "default"
# profile
foreach( keys %{$TrillianPlugin::Profiles{$profile}} ) #This will iterate through each parameter in this profile
{ print($_." = ".$TrillianPlugin::Profiles{$profile}{$_}."\n"); }
###################OUTPUT##################
Preferences Type = 2 # I am not sure what this value means yet. I think it has
# something to do with the Profile Directory
Automatic Login = 0 # Whether this account logs in on Trill startup. Only ONE
# profile should have a '1' here!
Password = A354EEA250EABEC210D0CA # The encrypted profile password. You can delete it if you
# forgot it and Trill wont care. ;)
Preferences Location = C:\WINDOWS\Desktop # Probably the most important value here. It shows where
# the user's preferences are located. Default dir is Not
# listed (%Trillroot%\default\users)
Name = Test Profile # The name of the profile as displayed in Trill's Prefs.
This hash is populated with the Trillian:GetSkins function. The keys are the folder name of each skin in the skin directory (verified by the version number - 700 - in the desc.txt file in each directory). Each key points to the directory holding the skin.
Example:
TrillianPlugin::GetSkins;
foreach( keys %TrillianPlugin::Skins)
{ print($_." = ".$TrillianPlugin::Skins{$_}."\n"); }
####################OUTPUT######################
MBG = C:\Program Files\Trillian\skins\MBG
Basics2 = C:\Program Files\Trillian\skins\Basics2
TP2 = C:\Program Files\Trillian\skins\TP2
BlueTurtle = C:\Program Files\Trillian\skins\BlueTurtle
This hash contains the character codes needed to do highlighting and formatting, colours etc on irc connections. You may
export it explicitly if you wish. For example $TrillianPlugin::IRCColors{bold} returns the bold character.
Your script can define any of these sub names. If you define any of these named subroutines in your script, they will be called when an event of that type occurs within trillian. =cut
This event is called when an outgoing message is due to be sent by trillian.
(0) internal package name (reference to self), used for callbacks and handlers,
(1) medium name, e.g. MSN,
(2) connection id, usually 0,
(3) name of target, e.g. msn address or icq number,
(4) text body of actual message. May (*SHOULD!*) be html encapsulated,
(5) location message is destined for, if event is from a group chat
This event is called when an incoming message has been received by trillian.
(0) internal package name (reference to self), used for callbacks and handlers,
(1) medium name, e.g. MSN,
(2) connection id, usually 0,
(3) name of sender, e.g. msn address or icq number,
(4) text body of actual message. May (*SHOULD!*) be html encapsulated,
(5) location message is destined for, if event is from a group chat
offline/online event
(0) internal package name (reference to self), most scripters won't need this,
(1) medium name, e.g. MSN,
(2) connection id, usually 0,
(3) name of sender, e.g. msn address or icq number,
(4) display name of user, usually different to name of sender,
(5) data about signon, signoff, in the form: "signed on at Wed Oct 15 00:33:53 2003."
IRC channel chat, or MSN/AIM etc chatroom inbound
(0) internal package name (reference to self), most scripters won't need this,
(1) medium name, e.g. MSN,
(2) connection id, usually 0,
(3) name of sender, e.g. msn address or icq number,
(4) text body of actual message. May (*SHOULD!*) be html encapsulated,
(5) location message is destined for, if event is from a group chat
IRC /action and /me inbound
(0) internal package name (reference to self), most scripters won't need this,
(1) medium name, e.g. MSN,
(2) connection id, usually 0,
(3) name of sender, e.g. msn address or icq number,
(4) text body of actual message. May (*SHOULD!*) be html encapsulated,
(5) location message is destined for, if event is from a group chat
called when script is loaded. You should not produce any debug output here apart from error messages. If you DO produce any
output, it will be classed as an error message, which will be displayed in an error dialog to the user, and your script
will not be loaded. This also goes for die() statements.
(2) reference to self, for setting callbacks etc
(4) filename of the script
called when script is unloaded (either individually, or because the plugin is shutting down
(4) filename of the script
IRC channel chat, or MSN/AIM etc chatroom outbound
(0) internal package name (reference to self), most scripters won't need this,
(1) medium name, e.g. MSN,
(2) connection id, usually 0,
(3) name of sender, e.g. msn address or icq number,
(4) text body of actual message. May (*SHOULD!*) be html encapsulated,
(5) location message is destined for, if event is from a group chat
IRC /action and /me outbound
(0) internal package name (reference to self), most scripters won't need this,
(1) medium name, e.g. MSN,
(2) connection id, usually 0,
(3) name of sender, e.g. msn address or icq number,
(4) text body of actual message. May (*SHOULD!*) be html encapsulated,
(5) location message is destined for, if event is from a group chat
Left mouse button clicked in an edit window.
(0) internal package name (reference to self), used for callbacks and handler subroutines,
(1) empty but defined,
(2) window id,
(3) event id (all edit events go through the same event id, so this has little use to scripters),
(4) empty but defined,
(5) empty but defined
Right mouse button clicked in an edit window
(0) internal package name (reference to self), used for callbacks and handler subroutines,
(1) empty but defined,
(2) window id,
(3) event id (all edit events go through the same event id, so this has little use to scripters),
(4) empty but defined,
(5) empty but defined
Menu shown in edit window, usually follows an edit_rightClick
(0) internal package name (reference to self), used for callbacks and handler subroutines,
(1) empty but defined,
(2) window id,
(3) event id (all edit events go through the same event id, so this has little use to scripters),
(4) empty but defined,
(5) empty but defined
Menu hidden in edit window, usually follows or preceeds an edit_leftClick
(0) internal package name (reference to self), used for callbacks and handler subroutines,
(1) empty but defined,
(2) window id,
(3) event id (all edit events go through the same event id, so this has little use to scripters),
(4) empty but defined,
(5) empty but defined
Text in an edit window was changed, called for every character that is input - *BE QUICK!*
(0) internal package name (reference to self), used for callbacks and handler subroutine,
(1) change event type, can be one of the following strings:
edit_insert_picture
edit_cut
edit_delete_selected
edit_clear
edit_paste
edit_delete
edit_backspace_selected
edit_backspace_word
edit_backspace
edit_history
edit_tab
edit_split
edit_mirc_color
edit_format
edit_alias
edit_foreground
edit_background
edit_ime_add
edit_character
edit_remote_add
edit_event
edit_size
(2) window id,
(3) event id (all edit events go through the same event id, so this has little use to scripters),
(4) text currently in the edit window,
(5) empty but defined
Text in an edit is about to be sent to its recipient.
(0) internal package name (reference to self), used for callbacks and handler subroutine,
(1) empty but defined,
(2) window id,
(3) event id (all edit events go through the same event id, so this has little use to scripters),
(4) text currently in the edit window,
(5) empty but defined
User has started typing a message. Occurs once at the start of every message within an edit window.
(0) internal package name (reference to self), used for callbacks and handler subroutine,
(1) empty but defined,
(2) window id,
(3) event id (all edit events go through the same event id, so this has little use to scripters),
(4) empty but defined,
(5) empty but defined
User has stopped typing a message. Occurs when the keyboard goes idle for a core-determined period
(0) internal package name (reference to self), used for callbacks and handler subroutine,
(1) empty but defined,
(2) window id,
(3) event id (all edit events go through the same event id, so this has little use to scripters),
(4) empty but defined,
(5) empty but defined
Handlers starting with EV_* are a special type of event which can take a variable number of parameters. You must call TrillianPlugin::DecodeParameters to decode the parameters into a hash, then you may do what you like with them. Each section in the docs for each subroutine lists what parameters are available in the hash for that event. For example:
sub EV_im_outbound
{
my($SELF,undef,undef,undef,$data,undef) = @_;
my %params = TrillianPlugin::DecodeParameters($data);
TrillianPlugin::OutputDebug("You sent an outbound message to ", $params{"displayname"}, " on medium ",$params{"medium"});
}
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
address
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
(none)
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
(none)
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Once you call TrillianPlugin::DecodeParameters, the following parameter names are available in this subroutine:
Folowing are various functions you may find useful in your scripts. None are Exported, so call them with TrillianPlugin::FunctionName()
You MUST call this sub, as the FIRST non-use statement your script does, to route your event through to the correct sub. and YES, we mean FIRST statement. not second thing or third :) See below. all scripts which are designed to run in trillperl must start in the following way:
use TrillianPlugin;
TrillianPlugin::DispatchEvent;
If you do not start your script in this way, events cannot be correctly routed to your handlers, and you will not be able to access any helper functions in the TrillianPlugin:: namespace.
Send an IM style message. First parameter is the medium to send to, second parameter is the connection ID. best to use the one that youve been provided in your event, if you've been provided with one. the third parameter is the destination of the message, e.g. an email address (in the case of msn) or an icq number (in the case of icq). $msgbody is the text of the message you wish to send, which can be html formatted if you wish.
Output a debug string to the trillperl preferences tab. You can send multiple arguments, if you do they will be concatenated into one line before output occurs.
Get trillian version. This is a string in the form ``2.0.0.0''.
Open a web browser. First parameter = url, second parameter = new window (0/1) third parameter = check security (0/1).
Set an avatar. First parameter = connection id, second parameter = medium name, third parameter = avatar filename, The file can currently be in png, gif, jpg, jp2, ico or bmp file format.
Set the avatar of a remote user on the contact list. First parameter = connection id, second parameter = medium name, third parameter = avatar filename, The file can currently be in png, gif, jpg, jp2, ico or bmp file format. Fourth parameter is the name of the user to set the avatar for.
Pop up an alert window for the user. First parameter = alert text to display, second parameter = name of a sub which is called when the text in the alert is clicked on third parameter = module where the callback sub can be found - this is usually set to the scripts own name, which is the first parameter to most events, for this convenience :)
This function returns the number of users in the contact list, offline and online. You should not need this function, as you can just calculate this by the size of the %Contacts array.
This function causes immediate re-enumeration of the contact list inside the plugin using contactlistEnumerate. PopulateContacts does this automatically, so there is little reason to call this function directly. It is made public as a courtesy.
You must call TrillianPlugin::PopulateContacts before you do any work with the %Contacts hash. The hash is populated automatically when the script is loaded, and refreshed preiodically. however if you do not do this, you risk getting stale data.
Create new thread (yes, really.)
first parameter = subroutine name that contains the code for the new thread, second parameter = module name of thread, use the $SELF parameter passed to events. third parameter = parameters to the thread. you can place any scalar you want here and it will be available via $_[0] in the thread.
Beware of standard threading issues when creating threads! Accessing variables that are being accessed in other threads, without some form of safety mechanism, is dangerous for your mental health!!!
Create Edit Alias, e.g. a / command.
First parameter = alias text, e.g. "/slap".
Second parameter = sub name to call when alias is typed in a window.
Third parameter = module name of sub to call, use $SELF value available from most event types.
RETURNS AN ID NUMBER which you must keep safe. When your script is done with it, or in its OnUnload event, you MUST free this value using DeleteTextAlias!
Your handler subroutine will accept several values such as a window id, the original text, a connection id and the medium. Here is an example which demonstrates writing a simple command called ``/haddock''.
sub alias_handler
{
my($orig,$wid,$medium,$cid) = @_;
TrillianPlugin::TextAliasSet("/me slaps you around with a large haddock",1);
}
sub script_onLoad
{
my(undef,undef,$SELF,undef,$FILE,undef) = @_;
if (!defined $alias_id_n)
{
our $alias_id_n = TrillianPlugin::CreateTextAlias("/haddock","alias_handler",$SELF);
}
}
sub script_OnUnload
{
if (defined $alias_id_n)
{
TrillianPlugin::DeleteTextAlias($alias_id_n);
undef($alias_id_n);
}
}
Delete an Edit Alias, e.g. a / command.
First and only parameter is an alias ID as allocated by CreateTextAlias
Handle an Edit Alias, e.g. a / command.
Inside your subroutine for your edit alias, you must call this function. The first parameter indicates the text that will be displayed in place of the alias text, or an empty string if you don't want to change it. The second parameter is 1 if you want the event to 'slurp' the text, or 0 if you want other plugins to get a look-in.
This subroutine, when called inside an edit alias handler, will make sure that the edit alias returns no text at all. If you do this, it is completely up to your script to generate output through some other means than changing text.
Here is some example code which demonstrates TextAliasZap.
sub alias_handler
{
my($orig,$wid,$medium,$cid) = @_;
TrillianPlugin::OutputDebug("Alias handler for $orig called!");
TrillianPlugin::TextAliasZap;
TrillianPlugin::WriteWindow($wid,"Slapping is bad, mmm-k?");
TrillianPlugin::WriteWindow($wid,"Its haddock for dinner :D");
}
sub script_onLoad
{
my(undef,undef,$SELF,undef,$FILE,undef) = @_;
if (!defined $alias_id_n)
{
our $alias_id_n = TrillianPlugin::CreateTextAlias("/haddock","alias_handler",$SELF);
}
}
sub script_OnUnload
{
if (defined $alias_id_n)
{
TrillianPlugin::DeleteTextAlias($alias_id_n);
undef($alias_id_n);
}
}
Send an external command to another plugin/script
First parameter = GUID of target plugin, Second parameter = event name, third parameter = data associated with event (event and plugin dependant). You may use the %API hash, and TrillianPlugin::PopulateAPI to determine which calls are available (what other plugins are currently running and providing services)
This function returns the number of APIs in the API list, You should not need this function, as you can just calculate this by the size of the %API array.
This function causes immediate re-enumeration of the API list inside the plugin. PopulateAPI does this automatically, so there is little reason to call this function directly. It is made public as a courtesy.
You must call TrillianPlugin::PopulateAPI before you do any work with the %API hash. The hash is populated automatically when the script is loaded, and refreshed preiodically. however if you do not do this, you risk getting stale data.
Generates an event. The first parameter is the event type, e.g. ``Contact List: Contact Signon''. Set the second parameter ($discrete) to 1 to execute the event as soon as possible, or to 0 to wait for execution of the event. Returns an event ID.
Execute an event. The first parameter is the event id, obtained via GenerateEvent with $discrete set to 0. The second parameter should be set to 1 if the event is to execute as soon as possible, or 0 if it is to wait until convenient. The third parameter can be the description, or if an empty string is given, no description will be used.
Creates an action event. The first parameter is the event name, e.g. ``Contact List: Boogie on down'' second parameter is the event description. Third parameter is the sub name of a callback function which will be called if the event is ever triggered, and the fourth parameter is the module where the callback sub is, use $SELF from most event handlers.
Deletes an action event, the first parameter is an event id, as given by TrillianPlugin::CreateEvent, and the second parameter is the event description you specified when creating the event.
WARNING! This may delete the entire event, and not just the action for that event, if you bind it the action to an event!!! I spoke with Kevin about this, he says there will be a fix 'some time', so the caveat until then is this: If your script handles actionevents, and they are bound to stuff, do not load and unload your scripts on the fly, so that trillian will leave the action bound to the event until it ends.
Changes the text within an edit window, useful from within the edit_* event types. First parameter is the window ID. this must be a valid window ID as given by the edit_* events etc. Second parameter is the text you wish to change the windows contents to. This text should be in UTF-8 and HTML. Convert all <'s -> <'s, etc. Also, you may use some custom HTML to specify other functionality. This includes <cursor/> (for the current cursor location) and <su color=``#ff0000''>text (to draw a special underline under some text; the color may be omitted).
Strips html from a single line, and returns the cleaned version of the data.
This function must be called by all EV_* type handlers, to decode their parameters. EV_* events, like EV_contactlist_signon, can receive a variable number of parameters. To simplify this issue, this function takes the encoded parameters, and decodes them into a hash as follows:
%somehash{``varname''} = ``value''
For an example of this in action please see the syntax highlighted example program available on the trillperl site.
Adds a contact to the contact list.
(0) Medium to add the contact to
(1) ID of the contact, e.g. hotmail address, or icq number
(2) Display name to give the contact
(3) URI to associate with the contact
(4) Information to display in the user's tooltip
(5) Group to add to. If you do not know this, use AddGroupRequest
Example:
TrillianPlugin::AddContact("MSN", # medium
'laptop@brainbox.winbot.co.uk', # identifier
"LaptopBrain", # display name
"http://brainbox.winbot.co.uk";, # uri to associate with the user
"Laptop Brain", # tooltip
"MSN"); # group
Adds a contact to the contact list, asking the user which group to place the user into.
(0) Medium to add the contact to
(1) ID of the contact, e.g. hotmail address, or icq number
(2) Display name to give the contact
(3) URI to associate with the contact
(4) Information to display in the user's tooltip
Example:
TrillianPlugin::AddGroupRequest("MSN", # medium
'laptop@brainbox.winbot.co.uk', # identifier
"LaptopBrain", # display name
"http://brainbox.winbot.co.uk";, # uri to associate with the user
"Laptop Brain"); # tooltip
This function will find trillians program path. It will return the value in a scalar, and at the same time place the value
into %TrillianPlugin::Path{"Root"}.
TrillianPlugin::GlobalDir will return the path to the global directory. Before returning the value to you it will place it
for future reference in %TrillianPlugin::Path{"Global"}
This function will decrypt a medium password found within trillians ini file. Please be ethical and sparing with your use of this function, otherwise we might have to beat you with a large spork.
CAVEAT:
String should not be longer then 16 characters/bytes, and should be an even number of Hexadecimal
digits. This is because I have provided for decrypting up to a 16 byte password. Most valid passwords
should not be longer than this. Although Profile passwords may be longer. The profile passwords dont really
protect anything though, as you can just delete it from the ini file and then you don't need it anymore. I
believe the medium passwords are restricted to under this length anyway.
This function will encrypt a medium password so that it may be stored in trillian's ini files.
CAVEAT:
String should not be longer then 16 characters/bytes, and should be an even number of Hexadecimal
digits. This is because I have provided for decrypting up to a 16 byte password. Most valid passwords
should not be longer than this. Although Profile passwords may be longer. The profile passwords dont really
protect anything though, as you can just delete it from the ini file and then you don't need it anymore. I
believe the medium passwords are restricted to under this length anyway.
This function populates the %TrillianPlugin::Profiles hash with entries from Trillian's profiles.ini file in it's Global directory. This is meant for reading information about the current profiles, and is not set up to write back changes to the file. This will set $TrillianPlugin::Profiles{'Active'} to the key of the currently active (default) profile. See the information about the %TrillianPlugin::Profiles hash for more info.
This takes an optional argument to the directory where your skins are located (C:\Program Files\Trillian\skins) as it may be located in a different directory. Normally it is located in \skins off the Trillian root directory. So you shouldn't need to worry about that. This populates the hash %TrillianPlugin::Skins with keys pointing to each skin folder in your skin directory. It checks the version number in desc.txt to make sure that it is a compatible skin. See the description of %TrillianPlugin::Skins for more info.
Example:
TrillianPlugin::GetSkins; # Populates %TrillianPlugin::Skins with a list of available skins
TrillianPlugin::GetSkins('C:\some\other\skin\dir'); # finds any skin folders located in the path supplied
# and uses those in its list
This function takes one parameter, which is the filename of a text file. The function will return a random line from the file.
This function takes a parameter containing a full irc hostname, such as bloggs!foo@bar.com, and returns just the ident part, in this case, 'foo'.
This function takes a parameter containing a full irc hostname, such as bloggs!foo@bar.com, and returns just the host part, in this case, 'bar.com'.
This function is a wrapper to the win32 function LoadBitmap. You must provide the name of a bitmap resource as a parameter,
and the bitmap will be loaded into the memory space of trillperl.dll, and its handle returned to you as the result. Remember
to free any bitmaps you load, using TrillianPlugin::DeleteBitmap.
This function is a wrapper to the win32 function DeleteObject. It will delete a bitmap, icon or cursor resource. You must
provide the handle to a valid resource which you have previously loaded using TrillianPlugin::LoadBitmap.
This function is a wrapper for the win32 MessageBox function. When called it displays a system messagebox, which the user can respond to.
First parameter: the message box text
Second Parameter: the message box title
Third parameter: A set of single character flags which set the behaviour of the messagebox.
Character "!": Tells the function to give the box an 'exclaimation' icon
Character "?": Tells the function to give the box a 'question mark' icon
Character "I": Tells the function to give the box an 'information' icon
Character "Y": Tells the function that the box should have two buttons, 'Yes' and 'No'.
Character "O": Tells the function the box should only have one button, 'OK'.
If you choose to give your message box 'yes' and 'no' buttons, then this function will return 1 if the 'Yes' button was clicked, or '0' if the no button was clicked. Otherwise the return value is meaningless. If you exclude any flags, your message box will have no icon and the default 'OK' button only.
Example:
TrillianPlugin::MessageBox("Are you sure you want to format the universe?", "Milliways now serving food", "?Y");
This function plays a sound. You must provide the path and filename of a sound file as the parameter. Most systems can play WAV format files, SOME systems may be able to play MP3 format sounds through this function, but this is not to be relied upon to always work. If in doubt, just play wavs.
Displays an input box into which a user may enter a value. As windows is a multi tasking environment, the input box cannot block while it waits for input, therefore a callback will be called once a value has been input and 'OK' or 'Cancel' has been clicked. At this point you may do what you wish with the data.
(0) Input box window title
(1) Input box default value
(2) Subroutine name to call when input is complete
(3) Module name where subroutine can be found. Use the $SELF variable passed to most events as the first parameter.
(4) A parameter which may contain any scalar value you specify, which will be passed in the 4th parameter of the callback
When the callback subroutine is called, it will be passed three parameters in @_. These will be:
(0) Reference to self, used for creating callbacks (callbacks inside callbacks? mmmmm!)
(1) The text that was input
(2) A numeric value, set to 1 if the user clicked 'OK', or 0 if the user clicked 'Cancel'.
(3) the 5th parameter of the original call to InputBox, used for passing data.
Example:
sub handle_input
{
my($SELF,$input,$ok,$blah) = @_;
if ($ok == 1)
{
TrillianPlugin::MessageBox("You entered $input!","$blah","OI");
}
else
{
TrillianPlugin::MessageBox("COWARD!!! You clicked cancel!","$blah","O!");
}
}
sub script_onLoad
{
my(undef,undef,$SELF,undef,$FILE,undef) = @_;
TrillianPlugin::InputBox('How many roads must a man walk down?','Enter the answer','handle_input',$SELF,"Message Title");
}
This function is identical to InputBox except for that it presents the user with a multiline input box, and the scalar which is returned to the callback may contain multiple lines seperated by newlines.
This function takes a parameter containing a full irc hostname, such as bloggs!foo@bar.com, and returns it in a wildcarded form, in this case '*!*@bar.com'.
This function matches an irc user!ident@host against a hostmask (*a!*b@*.tld) that you provide. The arguments are:
(0) Host (nick!ident@host.tld)
(1) Hostmask (*!ident@*.??)
Returns true if there is a match. IRC uses wildcards in a few areas, primarily ban lists and such. It is NOT case sensitive. There are two allowed wildcard characters.
This function writes text to a window you specify. You must specify the following parameters:
This function returns the 'home directory' which is passed to trillperl, where plugins should be saving their settings. This is a useful location to know, as officially this is where script settings should be stored.
Returns 1 if the main window (contact list) is visible, or 0 if it is hidden (minimised to the tray).
This function creates a custom handler for user tooltips in the contact list.
(0) Section name of contact to create tooltip handler for. If you use "My Contacts" this will ALWAYS look in the
default group for the contact, even if you rename this default group to be something else.
(1) Medium name of contact to create tooltip handler for
(2) Realname of contact to create tooltip handler for
(3) Subroutine name to call when tooltip is requested
(4) Module where subroutine can be found, most scripters will use $SELF.
This function will return a tooltip ID which you must keep safely in a variable. You must free tooltips using DeleteTooltip after you are finished with them or when your script ends. The tooltip handler will receive the following details:
(0) Medium of contact the mouse is over
(1) Name of contact the mouse is over (renamable, non-persistent name)
(2) real name (icq number, hotmail address) of contact the mouse is over
(3) status of contact the mouse is over
(4) idle state of contact, 0 or 1
(5) block state of contact, 0 or 1
(6) connection id of contact
(7) section of contact, if undefined, contact is in default group
Example script:
sub tooltip_cb
{
my ($medium,$name,$rname,$status,$idle,$block,$cid) = @_;
TrillianPlugin::AddTooltipItem("Test Medium","text","$medium");
TrillianPlugin::AddTooltipItem("Test Name","text","$name");
TrillianPlugin::AddTooltipItem("Test realname","text","$rname");
TrillianPlugin::AddTooltipItem("Test status","text","$status");
TrillianPlugin::AddTooltipItem("Test idle","text","$idle");
TrillianPlugin::AddTooltipItem("Test block","text","$block");
TrillianPlugin::AddTooltipItem("Test cid","text","$cid");
}
sub script_onLoad
{
my(undef,undef,$SELF,undef,$FILE,undef) = @_;
if (!defined $tth)
{
our $tth = TrillianPlugin::CreateTooltip("My Contacts","ICQ","35128710","tooltip_cb",$SELF);
}
}
sub script_OnUnload
{
if (defined $tth)
{
TrillianPlugin::DeleteTooltip("My Contacts","ICQ","35128710",$tth);
undef($tth);
}
}
This deletes a tooltip handler previously registered using CreateTooltip. You must release all such handlers before your script ends.
(0) Section of contact to release
(1) Medium of contact to release
(2) Realname of contact to release
(3) Tooltip ID as given by CreateTooltip
This function adds a tooltip item to the tooltip for a user. You must only use this function within a tooltip handler! The parameters for the function are as follows:
(0) Name of item to add, e.g. "Last Seen"
(1) Type of item to add. This may be "text" or "separator" - any other values may have undefined effects
(2) Value of the item, e.g. "Last time i was here"
You may add as many tooltips as you wish, limited only by screen real-estate space, and sensibility.
This function should not be called except for in exceptional circumstances. It causes all tracked handles to be marked as garbage, and then frees them all. Note that doing this will render all scripts in trillperl to loose their handles, as this is global. The only possible use that this has is for debugging. Call InternalGarbageCollect at a point in your script, and you will be presented with a messagebox if any handles are still in use. This makes it useful for checking if your script leaks or not. do NOT leave this instruction in production code!
This function copies text to the clipboard. It takes one scalar which will be copied as ANSI text.
Creates a hotkey. When the key combination you create is pressed, the subroutine you specify will be called. The parameters are as follows:
(0) Key letter of hotkey, e.g. "A". If you enter multiple characters into this value only the first will be counted.
(1) set to 1 if the shift key must be held down to trigger the event
(2) set to 1 if the ctrl key must be held down to trigger the event
(3) set to 1 if the alt key must be held down to trigger the event
(4) the subname to call when the key combination is pressed
(5) the module where the subname above can be found, usually the value of $SELF
The CreateHotkey function returns an ID value, which you must store, and you must remember to free this with DeleteHotkey before your program finishes. When your hotkey event is called, it will be given the following parameters in @_:
(0) Key letter of hotkey, e.g. "A". If you enter multiple characters into this value only the first will be counted.
(1) set to 1 if the shift key must be held down to trigger the event
(2) set to 1 if the alt key must be held down to trigger the event
(3) set to 1 if the ctrl key must be held down to trigger the event
(4) Window ID of the window where the event occured
(5) medium name of the window where the event occured
(6) connection ID of the window where the event occured
Within the hotkey event, you may use the function HotkeySetString to specify a line of text that will appear when the key is pressed. This simplistic action is designed for primative keyboard shortcuts, if you do not wish to use it then not calling it causes no text to be sent.
This function deletes a hotkey that was previously created using CreateHotkey. You must provide an ID number of a hotkey event as the only parameter.
This function allows for simple inplace inserting of a string when a shortcut key is pressed. Inside a hotkey callback, you may call this subroutine with a line of text to be set. If you do so the text will be entered into the current edit control. If you do not call this subroutine, no text will be inserted in this manner.
Example:
sub handle_hotkey
{
my ($key,$shift,$alt,$ctrl,$wid,$medium,$cid) = @_;
TrillianPlugin::HotkeySetString("key=$key, shift=$shift, alt=$alt, ctrl=$ctrl, wid=$wid, medium=$medium, cid=$cid");
}
sub script_onLoad
{
my(undef,undef,$SELF,undef,$FILE,undef) = @_;
if (!defined $kbid)
{
# ctrl+alt+shift+T
our $kbid = TrillianPlugin::CreateHotkey("T",1,1,1,'handle_hotkey',$SELF);
}
}
sub script_OnUnload
{
if (defined $kbid)
{
TrillianPlugin::DeleteHotkey($kbid);
undef($kbid);
}
}
This function takes an irc nick and returns 1 if it is valid, and 0 if it is not. You should strip @. + etc from the nick before you call this function.
This function compares two IRC nicknames. It returns 1 if the nicks match, 0 if otherwise. It will use the scandanavian character matching as laid down in the RFC.
This function will fetch a webpage and return it in a scalar. It is asyncronous (meaning that it will not block trillian while it downloads) and will call a callback subroutine you specify when the download is complete. The parameters for this function are:
(0) URL of data to fetch, this must be an absolute url to a resource
(1) optional parameters to pass to the callback function when downloads are complete, use this to pass custom values
(2) Subroutine to call when download is complete (or when an error occurs on the download), see below
(3) Module where this subroutine can be found, usually the $SELF variable is used from an event.
When the callback subroutine is called, it will be passed the following parameters:
(0) this value is 1 if the download succeeded, or 0 if it failed
(1) this is the url that was downloaded
(2) If the download was a success, this value contains the size of the downloaded data
(3) If the download succeeded, this contains the actual downloaded data as a scalar
(4) This contains the window id of the current window, note that this is not gauranteed to be valid if the download
completes while a trillian window is not focused
(5) This contains the custom parameter passed to the callback via the GetURL function.
This function creates a section in the contact list. A section is the top level of data types in the list, which can contain groups or items, or both. The parameters for this function are:
(0) Section text, e.g. "My Section"
(1) Section tooltip, e.g. "This section contains weebls!"
On return from this function, you will be given a handle of your section, which is an ID number you must save for later manipulation of the section you have created.
This function deletes a list section previously created using AddListSection. You may not delete a list section which still contains items. If you do so, an error will be raised. You must pass the handle given by AddListItem to this function.
This function creates a group in the contact list. A group is the second level of data types in the list, which can contain groups or items, or both. The parameters for this function are:
(0) Section id, given by a previous call to CreateListSection (a group must reside in a section you have created)
(1) Group text, e.g. "Pie Eaters"
(2) Section tooltip, e.g. "Stuff goes here that eats pie"
On return from this function, you will be given a handle of your group, which is an ID number you must save for later manipulation of the group you have created.
This function deletes a list group previously created using AddListGroup. You may delete a group which still contains items, however if you do, memory will be leaked so this is not recommended, and this action may be error checked (and forbidden by the scripting engine) at a later date. You must provide a valid group id, previously allocated by AddListGroup, as the parameter for this function.
This function creates an item in the contact list. A item is the lowest level data type in the list, which can be the parent to other items (which is how metacontacts exist) or can be within a group. The parameters for this function are:
(0) Section id, given by a previous call to CreateListSection (a group must reside in a section you have created)
(1) Group id, given by a previous call to CreateListGroup (an item must reside within a group you have created)
(2) tooltip for the item, e.g. "One very hairy egg"
(3) Display name of the item, e.g. "Hairy Lee"
(4) Subroutine to call when an action is requested for this item, see documentation below
(5) Module name where the callback subroutine can be found, use $SELF to reference own script
(6) bitmap filename to be used as the logo for the list entry, must be bitmap format (bmp)
(7) width of bitmap
(8) height of bitmap
(9) array of menu items (optional). This must be a list of names followed by subroutines, see the subsection
on menu items below. If you do not want your item to have a menu, completely omit this parameter.
On return from this function, you will be given a handle of your group, which is an ID number you must save for later manipulation of the group you have created.
my @item_menu = ("Some Text Here","sometext_handler","More stuff here","morestuff_handler");
then pass @item_menu as the 10th parameter to AddListItem. When a user right clicks the item, they will be presented with a list of two items, ``Some Text Here'' and ``More stuff here''. Clicking on ``Some Text Here'' triggers ``sometext_handler'' within your script, and clicking ``More stuff here'' triggers the the sub ``morestuff_handler''. The subroutine triggered will be passed the following parameters:
(0) menu item id, this is set internally by the system and of little use to the scripter at present
(1) list id, this is the id of the list item that was clicked. Use this to determine what item was clicked on
(2) text of the item clicked. Do not rely on this! it may be changed or become invalid over time, please use
the list id instead.
(0) Service name, see above
(1) item id that requires service, you should compare this against your registered IDs to find out what it is
(2) group id the item is in
(3) section id the item is in
(4) X position of cursor, only valid for "left_down" service type
(5) Y position of cursor, only valid for "left_down" service type
For a detailed example of how to manage list items, please consult the example below:
sub handle_listentry
{
my ($event,$item_id,$group_id,$section_id,$x,$y) = @_;
if ($event eq "left_down")
{
# left mouse button pressed, $x and $y hold position
}
if ($event eq "left_down")
{
# left mouse button released, trillian doesnt give us a position (bah)
}
if ($event eq "double_click")
{
# user double clicked on an item
if ($item_id == $weebl_id)
{
TrillianPlugin::MessageBox("When come back, bring pie!","Weebl","OI");
}
else
{
TrillianPlugin::MessageBox("I'm nervous!","Bob","OI");
}
}
if ($event eq "tooltip")
{
# trillian wants us to render a tooltip for an item.
# use TooltipHeader to define the top of the item (this doesnt neccessarily have to
# be the first call, you can do AddTooltipItem calls first if you like, but you MUST
# add a header for the tooltip to render
if ($item_id == $weebl_id)
{
TrillianPlugin::TooltipHeader("Weebl","Searching for Pie");
TrillianPlugin::AddTooltipItem("Pies","text","62");
TrillianPlugin::AddTooltipItem("Donkeys","text","0");
}
if ($item_id == $bob_id)
{
TrillianPlugin::TooltipHeader("Bob","Never had Pie");
TrillianPlugin::AddTooltipItem("Pies","text","0");
TrillianPlugin::AddTooltipItem("Donkeys","text","0");
}
}
}
sub script_onLoad
{
my(undef,undef,$SELF,undef,$FILE,undef) = @_;
if (!defined $section_id)
{
our $section_id = TrillianPlugin::AddListSection("Weebls","This section holds stray weebls");
our $group_id = TrillianPlugin::AddListGroup($section_id,"Pie Eaters",
"Contains things that eat pies!");
our $weebl_id = TrillianPlugin::AddListItem($section_id,$group_id,"Searching for Pie",
"Weebl","handle_listentry",$SELF,
'c:\trillperl\debug\weebl.bmp',15,15);
our $bob_id = TrillianPlugin::AddListItem($section_id,$group_id,"Never had Pie",
"Bob","handle_listentry",$SELF,
'c:\trillperl\debug\bob.bmp',15,15);
}
}
sub script_OnUnload
{
if (defined $section_id)
{
# list entries should be removed in reverse order to their creation, as you have to remove
# a section last.
TrillianPlugin::DelListItem($bob_id);
TrillianPlugin::DelListItem($weebl_id);
TrillianPlugin::DelListGroup($group_id);
TrillianPlugin::DelListSection($section_id);
undef($section_id);
}
}
This function deletes a list item previously created using AddListItem. You must delete a list item you have previously allocated using AddListGroup, and must give its ID as the parameter for this function.
This function removes all entries from a group. You must provide a valid group id to clear the items from.
This function removes all groups and items from a section. You must provide a valid section id to be cleared.
This counts all groups and items within a section and returns the total. You must provide a valid section id to count the items within.
This function counts all items and subitems within a group. You must provide a valid group id to count the entries within.
This function returns 1 if the group you specify is expanded (its plus symbol clicked) or 0 if it is not. You must give a valid group id to this function to get a meaningful result.
This changes the displayed name of an item or group. You must provide the following parameters:
(0) group or item id of the item to change
(1) new displayed name of the item
This changes the basic tooltip of an item or group. You must provide the following parameters:
(0) group or item id of the item to change
(1) new basic tooltip of the item
Note that if your callback function for the item is handling super tooltip requests, then this basic tooltip will never be shown.
This changes the icon of an item or group. You must provide the following parameters:
(0) item id of the item to change
(1) filename of new icon to use, must be in bitmap format (bmp)
This makes a group be expanded or not expanded. You must specify the following parameters
(0) group id of the item to change
(1) set this value to 1 to expand the group, 0 to close it
This updates the colours used to display a list item.
(0) item id of the item to change
(1) Background colour (in html format, e.g. 0xFFFFFF)
(2) Foreground colour
(3) Background colour while selected
(4) Foreground colour while selected
(5) Background colour while hovering over item
(6) Foreground colour while hovering over item
This function enables or disables drawing of the contact list. This function is no longer in use in many plugins, you should avoid calling it. Set the parameter to 1 to stop redrawing of the list or 0 to resume drawing.
This function forces a redraw of the section you specify. You must pass a valid section id to the function for it to succeed.
This function forces a redraw of an item you specify. You must pass a valid item id to the function for it to succeed.
This function works in a similar way to the optional tenth parameter to AddListItem except for it binds a menu to an entire section and all the items within it. The first parameter is the section id to bind the menu to, and the second parameter is the module where your callbacks can be found (most scripts will use $SELF). The third parameter to your BindMenu is an array. To create a menu, you must create an array in the following way:
my @item_menu = ("Some Text Here","sometext_handler","More stuff here","morestuff_handler");
When a user right clicks any item within the section, or the group or section header itself, they will be presented with a list of two items, ``Some Text Here'' and ``More stuff here''. Clicking on ``Some Text Here'' triggers ``sometext_handler'' within your script, and clicking ``More stuff here'' triggers the the sub ``morestuff_handler''. The subroutine triggered will be passed the following parameters:
(0) menu item id, this is set internally by the system and of little use to the scripter at present
(1) list id, this is the section id which was clicked inside. Note that if you use BindMenu there is NO WAY to
obtain the item id of a specific item, so be careful with your use of BindMenu!
(2) text of the item clicked. Do not rely on this! it may be changed or become invalid over time, please use
the list id instead.
Remember to free all bound menus with UnbindMenu before your script exits!
This function unbinds a section-specific menu which has been previously set with BindMenu. You must provide the section id to unbind the menu from as the parameter.
This function deletes a contact from the contact list. You must provide the following parameters:
(0) Medium name to delete from, e.g. 'ICQ'
(1) Real name (identifier) of contact, e.g. '35128710'
(2) Section name to remove from. Use 'My Contacts' to always specify the default group even if the
My Contacts group has been renamed.
This function adds a subcontact to your contact list under an existing contact. You must provide the following parameters:
(0) Medium of parent contact
(1) Realname (identifier) of parent contact
(2) Section name of parent contact (use 'My Contacts' to specify the default group even if that group is renamed)
(3) Subcontact medium, e.g 'MSN'
(4) Subcontact display name
(5) Subcontact realname (identifer)
(6) URI to associate with the subcontact
(7) Standard (not enhanced) tooltip for the subcontact
(8) Group to add the subcontact to (not sure if this is needed)
This function deletes a subcontact from your contacts list. You must specify the following parameters:
(0) Medium name of parent contact, e.g. 'MSN'
(1) Real name (identifier) of parent contact
(2) Section name of parent contact (use 'My Contacts' to specify default group even if that group is renamed)
(3) Realname of subcontact to remove
This document mainly composed by Craig Edwards (aka Brain) and Erik Jacobson (aka Azhrarn). Parts of this text will undoubtably be borrowed from the trillian plugin SDK, where convenient :)
This text and program code it was generated from are (C) Craig Edwards 2003. Permission to modify this text is granted so long as the copyright notice given is preserved. See the comments in TrillianPlugin.pm for more information.
Version 0.5, 18th Oct 2003
The newest version of this file should always be available at <http://brainbox.winbot.co.uk/trillperl/TrillianPlugin-pod.html>
| Trillian Perl Library Reference |