TreeView v0.9b - Documentation
General Information
Hi there! ;-)
This is the documentation file of an mIRC script - TreeView v0.9b.
It basically contains information about the included files and describes its commands.
If you only downloaded this script because it was required by an addon, you do NOT have to read further.
Simply save "tw.mrc" somewhere and load it into your mIRC by typing: /load -rs "C:\the\path\of\your\tw.mrc"
The following information is probably only interesting for scripters. ;-)
The creation of this script took more than 1 year. But this does not mean that you have to expect something that saves the world or is very impressive...
It just took that long because I only worked on it when I was totally bored... only several hours in total.
Anyway, I hope it may help some people to achieve a better usability of their dialogs without the need to use custom DLL-files.
(I hate any kind of DLLs, especially if they are required by rather small addons.)
What do I actually talk about: A treeview-control is, in this case, a listbox in a dialog which is able to have submenus, available by expanding or collapsing them.
If you look for an example, you can simply open the mIRC Options: [ALT] + [O]
The menu on the left (Connect, IRC, Sounds) is a treeview-control.
But of course, the result which is achieved by this script will look slightly differently, because I only used mIRC's own commands.
Check out the screenshots below this text for a first impression.
By the way... I know, the files say TreeView v0.9b by Dark, but this is just one of my nicknames.
In order to avoid misunderstandings: I only use this nick in a german discussion-board - nowhere else.
My mircscripts.org nickname is Turtizzle ... in case anyone wants to know. :-P
About this Script
Alright, here we go.
First, I would like to show you 2 screenshots of how the result might look at the end:
(These images will be loaded from imageshack.us because I've been too lazy to include them into the archive.)
As you can see, parent-items, which contain submenus, are tagged with [brackets].
Every child item is indented (in case it's visible because its parent item is expanded) - there are simply some spaces (actually $chr(160)) before it.
Anyway, if you do not like this behaviour, you can change it.
The initialization command contains a few switches which change the look of your treeview control.
For example, you can remove the [brackets] or define a custom number of space-characters in front of child items... including 0, if you'd like to deal with it by yourself.
You will find a list of all commands in the Usage-section.
The archive you downloaded contains 3 script-files:
tw.mrc (286 lines)
This is the main script file... it contains everything you need in order to create treeview-controls and work with them.
tw-long.mrc (557 lines)
This is basically the same as tw.mrc. It just contains a bunch of comments, in order to give some orientation if someone would like to change the code for his needs.
Yes - you are allowed to change this script, but if you're about to redistribute it, make sure you don't remove my nickname on top of it.
You should also note your changes somewhere... so people know that this is an edited version and I'm not fully responsible for it. :-P
tw-ex.mrc (145 lines)
This script only contains an example for you, so you can actually test some codes and see the script in action. :-)
It is not required to make the commands work, but it (hopefully) gives a nice overview.
By the way, this is also the dialog that you could see in the first screenshot.
Usage
If you are using this script for the first time, you should take a look into the example-script.
Its init-alias shows the way treeview-controls are produced and filled pretty clearly.
Basically, it's a pretty easy job:
After opening the dialog, you have to use the /tw.init in order to tell the script that you would like to have a treeview.
Its similar to marking a dialog when using the DCX.dll or MDX.dll files... except that specifically mark a dialog control here. (not the dialog itself)
After that, you may use /tw.add (and all those other commands) to add (sub)menus to the list and fill your treeview with information...
Commands:
/tw.init [-zfcCsN] <DNAME> <DID>
This is the initialization-command for the treeview control.
It must run this command before you can use the treeview!
It prepares the listbox, creates the hash-table and allows you to apply some settings.
<DNAME> is, of course, the name of the dialog.
<DID> is the dialog-ID of the listbox that you want to be turned into a treeview.
If you use -z here, the script will also append the -z parameter to every /did-command used to update the listbox.
You might want to use it together with horiz. scrollbars. ;-)
You can use -f to prevent the script from automatically adding the [brackets] around parent items.
Like this, you may define your own style for your submenus.
You will simply have to adjust the <TEXT>-part of the /tw.add-command.
With -c, you can prevent the script from automatically expanding a submenu by double-clicking it.
By using -C, the submenus will already be toggled by a single click.
You cannot use these 2 parameters together, of course.
-sN allows you to adjust the way submenus are displayed.
N is the number of spaces in front of submenus.
The default value of N is 4.
You may also define -s0 if you do not want your submenus to be indented or if you like to do this manually in the submenu-item's text.
/tw.erase [-k] <DNAME> <DID>
This command will delete all data that belongs to the treeview.
Like that, the listbox will become just a normal listbox again.
You do not have to run this command when the dialog closes, it happens automatically.
With the parameter -k, the text in the listbox will not be deleted.
But of course, you cannot collapse/expand submenus anymore...
/tw.add <DNAME> <DID> <ID> <PARENT-ID> <POSITION> <IS-PARENT> <TEXT>
This is probably the most important command.
It allows you to add items to the treeview-control.
<ID> is the ID of the item.
IDs are used by the script to identify the items. Every single item in the treeview has a different ID.
You may use anything here - numerics, alphabetic characters, special characters, ... anything, as long as it's unique.
Only the following chars cannot be used: spaces, 0 and 1.
The new item will be added to the treeview below the <PARENT-ID>.
It's a part of the parent's submenu.
If you would like to add the new item to the root, you have to specify 0 as the <PARENT-ID>.
<POSITION> is supposed to be the ID of another sub-item below the given parent.
If you specify a <POSITION>, the new item will be placed on top of this item.
You may use 0 to make the new item appear at the very end of the (sub)menu.
If you use -1, it will appear on top of the list.
<IS-PARENT> defines whether the new item is a parent (and therefore able to have submenus) or not.
Possible values are:
0 will make it a normal item, not a parent.
1 will make it a parent.
2 will make it a parent and automatically expand its submenu.
<TEXT> is simply the text that will be displayed in the listbox.
/tw.del [-c] <DNAME> <DID> <ID>
This command will delete an item from the treeview.
If the item was a parent, all of its child-items will be deleted, too.
You may use -c to delete the child-items only and leave the parent itself.
If you use -c, you can also use 0 as <ID> in order to clear the whole treeview-control.
/tw.text <DNAME> <DID> <ID> <New Text>
This command allows you to change the text of an existing item.
/tw.exp <DNAME> <DID> <ID>
This command allows you to expand an existing item, therefore show its submenu.
/tw.coll <DNAME> <DID> <ID>
This command allows you to collapse an existing item, therefore hide its submenu.
/tw.toggle <DNAME> <DID> <ID>
This command allows you to toggle an existing item.
That means, it will be expanded if its currently collapsed and vice versa.
$tw.id( <ID / Line> , [DNAME] , [DID] )
This identifier allows you to retrieve some information about your treeview-control.
[DNAME] and [DID] are optional. If you do not specify them, $dname and $did will be used.
This only works inside the ON-DIALOG-event, of course.
You can also specify [DID] only, without [DNAME]. The script will notice this automatically if the 2nd parameter is a number.
There are several possible properties...
Dependent on which property you choose, the script either expects an <ID> or a <Line> as the 1st parameter.
$tw.id(<Line>) will return the ID of the item in line <Line> of the listbox.
$tw.id(<ID>).line will return the line in which the given <ID> can be found.
If the <ID> is currently not visisble (because the submenu is collapsed), $tw.id will return 0.
If the <ID> does not exist at all, it will return -1.
$tw.id(<Line>).text will return the text in line <Line>.
$tw.id(<ID>).idtext will return the text of the item <ID>.
$tw.id(<Line>).parent
$tw.id(<ID>).idparent
This allows you to find out whether the given item is a parent or not.
Possible values are: 0 = normal item, 1 = parent, 2 = expanded parent
Contact
There are several ways to contact me...
If you speak German, you could visit mircboard.de - my nickname is Dark.
You can also find me on some IRC-networks... I'm usually online 24/7. (but of course, often afk)
irc.freenode.net - Chans: ##mircboard, #spaceofanarchy.de - Nickname: Fanatic
irc.quakenet.org - Nickname: Turtizzle
You could also simply write a comment @ mircscripts.org...
I would appreciate bug reports, suggestions and general feedback. Thank you for reading and have fun! :-)
(And excuse me for occasionally bad English skills! :-P)