======================
popread.dll by nacitar
======================
-----------------------------------------------------------------
|  This dll was originally intended to be a faster alternative 
|   to popups.dll for me to use in the new CTbar im working on, 
|   however I decided to make this one public.  Included in     
|   this dll are a few more functions that you may find useful. 
|   This dll contains 5 functions:  popread, mn, mnchk, mntxt,  
|				  & keydown                     
-----------------------------------------------------------------

======================
	Usage
======================
  popread
	popread generates a popup menu from the specified lines of a file, and
	pops them up at the desired x/y position.  These popups are intended to be
	generated as close to exactly like mirc as possible, however there are a
	few differences.  $submenu($identifier) is the format for submenus, however
	if it reads $submenu($identifier(blah)) or anything with () inside it, it
	will cut that off and just use $identifier, and will send the standard
	values of begin, 1, 2, ..., end.  $style is also supported in the same
	way as mirc handles it, as far as I know.  The return indicates success or
	error, S_OK for success, E_FILE_NOT_FOUND is self explanatory, and 
	E_INSUFFICIENT_PARAMETERS is self explanatory as well.  Also as a note,
	before translating the popups, popread removes leading spaces, and tab
	characters, to compensate for any spacing you may have done.  Note that
	any aliases popread accesses MUST NOT BE LOCAL.
     USE:
	$dll(path\popread.dll,popread,<filename.ext>?<start_line>?<end_line>?<x>?<y>)
     EXAMPLE:
	//echo -a $dll(path\popread.dll,popread,c:\mirc\myscript.mrc?20?30?300?300)
     NOTE:
	The above example will read lines 20 to 30, generate popups, and pop them up at
	the screen coordinates of 300,300.

  keydown
	keydown retrieves the state of the requested key. That is,
	it tells you if it is being held down or not.  This
	function returns a 1 or 0, 1 meaning that the key is down.
	This also tells you the state of the mouse buttons.
     USE:
	$dll(path\popread.dll,keydown,<virtual_key_code>)
     EXAMPLE:
	//echo -a The left mouse button is curently $iif($dll(path\popread.dll,keydown,1),down,up)
     NOTE:
	A list of key values in hexadecimal can be found at:
        http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winui/vkeys_529f.asp
	Remember to convert the hexadecimal to decimal with $base(num,16,10) before using this function.

  mn
	mn can be used to execute the commands associated with an item
	in mirc's menubar.  This includes the menu to the left of file,
	which varies by active window. Commands menu is not included.
     USE:
	dll path\popread.dll mn [<hmenu> ]<id>
     EXAMPLE:
	dll path\popread.dll mn 101
	dll path\popread.dll mn 266143155 101
     NOTE:
	The above example is just like clicking File -> Connect/Disconnect.
	Included with this dll is mircmenu.txt, which contains the
	ids for the items in the menubar. Also note that the menu structure may
	vary from one version of mIRC to the next. This is the structure of mIRC 6.01
	The optional hmenu should only be input if you know what it means, the example
	where I filled it in has the HMENU of mirc at the time of the test. 

  mntxt
	mntxt returns the text being displayed by the specified item
	in the menubar.
     USE:
	$dll(path\popread.dll,mntxt,[<hmenu> ]<id>)
     EXAMPLE:
	//echo -a Is mIRC registered? $iif($dll(path\popread.dll,mntxt,134),No,Yes)
	//echo -a Is mIRC registered? $iif($dll(path\popread.dll,mntxt,266143155 134),No,Yes)
     NOTE:
	You can use this with many numbers to discover the id of the
	item displaying the text of the item you are looking for. Reference
	the note on HMENU for the "mn" command, for information on that parameter.

  mnchk
	mnchk returns a 1 or 0, 1 indicating that the specified menu item
	has a checkmark next to it, 0 meaning that it does not.
     USE:
	$dll(path\popread.dll,mnchk,[<hmenu> ]<id>)
     EXAMPLE:
	//echo -a Auto Cascase is: $iif($dll(path\popread.dll,mnchk,129),OFF,ON)
	//echo -a Tile Cascase is: $iif($dll(path\popread.dll,mnchk,266143155 127),OFF,ON)
     NOTE:
	The above examples deal with the menubar's Window -> Auto menu.  Reference
	the note on HMENU for the "mn" command, for information on that parameter.

======================
  Format Information
======================
  I said the idea was to read the popups almost exactly like mirc, the key word is almost.
  Currently I have found, when testing with Tank's popups, that some scripters do this:
	..menutext:%varname = 1
  This will not work, you must do this:
	set %varname 1
  Also, if you have multiple commands your popups may look like this:
	..menutext:{ command1 | command2 }
  You do not need the brackets around the entire thing, and if you place them there it will
  indeed not work correctly, so the above would be:
	..menutext:command1 | command2

  The commands must be in a form so that if they were entered into the editbox after "//", it would
  work.  This is how the commands are sent, so that explains the requirement.  Icons are available
  now as well, the BEGINNING of the text must be this command. Place the command anywhere else and 
  you will not get icons.  $null(<icon>), or $null(<icon>?<rollover icon>).  In the icons, you must
  include the full path.  If you can visually see the colon (:) after the drive letter, replace it
  with a right arrow bracket (>).  If you have something within there that evaluates, like an alias
  or variable, you do not need to do this.  If you are doing this in a submenu, keep in mind that
  mirc evaluates before it returns, so you must send $!null(<icon>).  If the icon evaluates, you
  must make sure it evaluates AFTER the alias returns it.
	..$null(c>\mirc\icons\popread.ico) Wee!:echo -a Wee!
	..$null(c>\mirc\icons\popread.ico?c>\mirc\icons\popread_2.ico) Wee!:echo -a Wee!
  Also, if you set a checked state with style (which goes AFTER the $null()) it has precedence over
  the icons, so it will be drawn, not the icons.

A few things to notice:
	if you do the icon like this, $null(?<rollovericon>) you do not specify a normal icon.  There
	is no icon when it isn't selected.  You can use this for arrow icons or something to point at
	the currently selected menu item.  also if you give a first and not the second (must have
	the ? to signify you are specifying both) there will be no icon when it is selected, only when
	it isn't.

BOLD TEXT:
	Place mirc's bold character anywhere in the text to display and it will show bold, it does not
	toggle, if are any bold characters the whole thing is bold.

======================
        Thanks
======================
 Kamek			Helping me with various aspects of the dll.
 Dragonzap		Help involving the entire menuchar event.
 ^Andy			Telling me that the almighty tab character is \t, as well as creating
			Tanks, which enabled me to find a few bugs by testing it with those popups.
 #c++ & #winprog	MUCH help.

======================
	Contact
======================
I'm on AIM/YIM as "Abaratican", and I'm on MSN as "nacitar@earthlink.net".
My email address is obvious, judging by the MSN name.
I'm on IRC on undernet in #argh .

==========================
      Updates/Fixes
==========================
[02/16/2002] : You may have noticed this in the queue, but I removed it when
               I discovered a bug with /set and also a bug with $submenu overall.
               This has been resolved.
[03/16/2002] : Made the menus owner drawn, added icon support, recoded the entire thing (almost).
[03/24/2002] : Rescripted alot of it removing all references to std::string and using char* instead.
	       thus removing the requirement of MSVCP60.DLL.  While doing this, I got rid of a TON
	       of tiny memory leaks.  I'm really confident that there are no memory leaks now.  Of 
	       course, if one comes up I'll admit defeat.
[05/14/2002] : Recoded string manipulation functions for optimization, fixed bug that exhibits my
	       blatant retardation, and modified the dimensions/positions of the menu items.  Fixed
	       bug with tab characters not expanding (showing a box).  Oh, fixed a memory leak I
	       forgot because I started looking below that spot.  Defeat has been admitted yet
	       victory reclaimed. Added bold text support too. :D
[06/07/2002] : Fixed $submenu not working with seperators (-)
