
      tbwin.dll v0.3 by dohcan (dohcan@mircscripts.org)

   --------------------------------------------------------------------------

tbwin.dll is a dll which lets you place a picture @window inside your toolbar.
This is handy if you want to add something, such as mp3 player controls or a
graphical lag meter, to your toolbar.  Since the @window becomes a child of the
toolbar rather than simply floating up there, you do not need to use a timer to
keep the @window in the right place and you do not have to worry about the focus
problem that is common when using a floating @window.

This dll has been specifically designed to work with picture windows that have
no titlebar.  It may work with regular @windows or dialogs, but it is not
recommended, as it will NOT have the desired effect.  The optimal way to open a
@window for use with tbwin.dll is:

  window -Bph +d <@windowname> <parameters>
  
  (You want to use -B in mIRC 6+ to remove the border)

You do not need to use a desktop window or a tool window, as the idea is to make
the @window "blend" with the toolbar.  To achieve this, it is best to use a
borderless, captionless picture @window which has been filled with $rgb(face).
The -h parameter is needed to get rid of the switchbar button.  After you have
opened the window, simply do window -a <@windowname> to make the window visible.

Below are the functions available:

   --------------------------------------------------------------------------

--
Attach <@window>

  This attaches the specified window to the toolbar and sets up the toolbar for
  use with the @window.  It also sets @window as the active window.
  
  NOTE: In this version, you can still pass $window().hwnd to attach, but this
  support will be removed in later versions for consistency.
  
  
--
Select <@window>

  This selects @window as the active window.  This is the window that all of the
  other commands assume if no window is specified explicitly.


--
Detach [@window]

  This detaches the selected window, or the one passed as the parameter.


--
OnMouse [@window] <event> [/command params]

  This sets a mouse event hook for the selected or specified window.  If a
  command is not specified, then that hook is removed.
  
  The available events are: sclick, dclick, uclick, mouse, enter, leave
  
  Examples:
  
  /dll tbwin.dll OnMouse mouse /handlemouse  ; adds handler for mouse movement
                                                      
  /dll tbwin.dll OnMouse sclick              ; removes handler for mouse clicks


--
OnSize </command|off>

  This sets an event hook for whenever the toolbar (eg, whenever mIRC) is sized.
  This allows you to move your @window(s) appropriately according to the size of
  the toolbar.  If you specify a /command, that command is called with the
  parameters <Width Height>.  If you specify 'off', this removes the event hook.
  
  For example, if you did:
  
  /dll tbwin.dll OnSize /handlesize
  
  ...each time mIRC was resized, "/handlesize <width> <height>" would be called,
  where <width> is the width of the toolbar and <height> is the height of the
  toolbar.
  
  NOTE: This does not have anything to do with moving the window when mIRC is
  moved.  If mIRC is moved, rather than sized, the @window will move automat-
  ically.  In any case, this method allows you to handle window placement
  without using any timers at all.
  
  
--
GetTBInfo NOT_USED

  Returns the width and height of the toolbar, in the format:
  
  <Width Height>
  
  This will effectively tell you how much room you have to use for your @window.
  The buttons on the toolbar as of mIRC v5.91 span about 535 pixels from the
  left.
  
  
--
GetMouse NOT_USED

  Returns information about the mouse in relation to the @window in the toolbar.
  It's returned in the format:

  <X Y Key Hover @window>

  You may want to use the following alias:

  alias tbmouse {
    var %x = $dll($_tbwin, GetMouse, NOT_USED)
    var %z = x y key hover win
    if ($findtok(%z, $1, 1, 32)) return $gettok(%x, $ifmatch, 32)
    else return $null
  }
  
  $tbmouse(x)      - X position of the mouse
  $tbmouse(y)      - Y position of the mouse
  $tbmouse(key)    - Key code for left-mouse button, CTRL, and Shift.  Works
                     like $mouse.key. See mIRC help file for more information. 
  $tbmouse(hover)  - Returns 1 if the mouse is over the window and 0 if not.
  $tbmouse(win)    - Returns the name of @window that triggered the event.
  
  NOTE: You should only use $tbmouse() in response to a mouse event set by
  OnMouse.  The data, after the event is over, may no longer be valid.

   --------------------------------------------------------------------------

The beauty of this dll is it allows you to use your familiar /window and /draw*
commands to manipulate the @window.  Virtually anything you can create with a
regular picture @window can be created, given that it fits inside the toolbar.

THINGS TO NOTE:

  Make sure to use Select to set the active working window if you want to use
  the commands without specifying the @window parameter.  If you call a command
  with the @window parameter, it does NOT change the selected window.
  
  You can't attach desktop @windows, dialogs, or @windows from other running
  mIRCs.  If you attempt to attach them, you will get an E_INVALID_WINDOW error.
  
  When using this under Windows XP, you have to understand that the toolbar is
  most likely going to be themed.  So, this can cause "blending" problems with
  your @window unless you make sure that it either blends or does something else
  to look "appropriate" under those situations.  I will look into this to see if
  there is anything I can do "automagically" from within the dll, but for right
  now you should just be aware of it.
  
  Again, you probably want to use -B under mIRC 6 to get rid of the automatic
  inset border that's added to picture windows.