///////////////////////////////////////////////////////////////////////////////
// WBAmp
// Copyright (c) 2000 - 2003 Matthijs Vermeulen
// MadIce At Stardock Dot Com
///////////////////////////////////////////////////////////////////////////////
// THIS DOCUMENT MUST BE INCLUDED WITH ANY DISTRIBUTION OF THE PLUGIN.
// DO NOT CHANGE THE CONTENTS OF THIS FILE.
// THERE IS NO NEED TO INCLUDE THE SOURCE CODE IN THE DISTRIBUTION.
// YOU ARE NOT ALLOWED TO USE THE PLUGIN FOR ANY COMMERCIAL PURPOSES.
// STARDOCK.NET IS ALLOWED TO DISTRIBUTE WBAMP WITHOUT PERMISSION.
// THE USE OF THIS SOFTWARE IS AT YOUR OWN RISK.
// I CANNOT BE HELD RESPONSIBLE FOR ANY DAMAGES CAUSED BY ITS USE.
///////////////////////////////////////////////////////////////////////////////
// Special thanks to the beta-testers
// * Morphh (the originator of WBAmp)
// * d
// * dbqp
// * Dan Boldon
// * Philip Powell
// * Mercury
// * jef
// * Jafo
// * David K (ultimate CoolPlayer tester!)
// These people came up with a lot of ideas for WBAmp.
// Most of them are implemented.
///////////////////////////////////////////////////////////////////////////////
// Thanks to d and Adam Najmanowicz for the intergration in SkinStudio (also 
// known as BuilderBlinds).
///////////////////////////////////////////////////////////////////////////////
// Thanks to Neil Banfield for his support of WB (and ObjectMedia).
///////////////////////////////////////////////////////////////////////////////
// Thanks to Lowell Heddings for publishing the source code of GeekAmp (a 
// remote control for WinAmp in LiteStep).
///////////////////////////////////////////////////////////////////////////////
// Thanks to Niek Alberts (creator of CoolPlayer) for his support.
///////////////////////////////////////////////////////////////////////////////
// Thanks to crazygirl76 for making me wonder why I didn't include support for 
// CoolPlayer in the first place...
///////////////////////////////////////////////////////////////////////////////
// Thanks to all the people that supported WBamp the present. May the White 
// Noise be with you.
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// What is WBAmp?
///////////////////////////////////////////////////////////////////////////////

WBAmp is a plugin which can be used to control ObjectMedia, CoolPlayer or 
WinAmp (2.xz) from within the titlebar of a WindowBlinds skin.

The following functions are available:

///////////////////////////////////////////////////////////////////////////////
// WBAmp Functions
///////////////////////////////////////////////////////////////////////////////
// CP: CoolPlayer
// WA: WinAmp
// OM: ObjectMedia
///////////////////////////////////////////////////////////////////////////////

 1 Play: Start playing a track.                                        CP WA OM
 2 PauseResume: Pause or resume playing a track.                       CP WA OM
 3 Stop: Stop playing a track.                                         CP WA OM
 4 Close: Terminate player.                                            CP WA OM
 5 Previous: Play the previous track.                                  CP WA OM
 6 Next: Play the next track.                                          CP WA OM
 7 Rewind: Fast rewind 5 seconds.                                      CP WA OM
 8 Forward: Fast forward 5 seconds.                                    CP WA OM
 9 First: Play the first track.                                           WA OM
10 Last: Play the last track.                                             WA OM
11 Lower: Lower the volume by 10%.                                     CP WA OM
12 Raise: Raise the volume by 10%.                                     CP WA OM
13 Lower: Lower the volume by 5%.                                      CP WA OM
14 Raise: Raise the volume by 5%.                                      CP WA OM
15 Lower: Lower the volume by 1%.                                      CP WA OM
16 Raise: Raise the volume by 1%.                                      CP WA OM
17 Hide: Hide player.                                                  CP WA OM
18 Show: Show player.                                                  CP WA OM
19 File: Play a file.                                                  CP WA OM
20 Folder: Play a folder.                                                 WA OM
21 URL: Play a URL.                                                       WA OM
22 Menu: Show the player's menu.                                          WA OM
23 Shuffle: Toggle shuffle mode.                                       CP WA OM
24 Repeat: Toggle repeat mode.                                         CP WA OM
25 Single: Stop after the current track.                                  WA OM
26 VISStartStop: Start or stop the VIS plugin.                            WA
27 VISConfigure: Configure the VIS plugin.                                WA
28 VISSelect: Select a VIS plgin.                                         WA
29 VISOptions: VIS Preferences.                                           WA
30 Run: Start the player and minimize it.                              CP WA OM

///////////////////////////////////////////////////////////////////////////////
// How do I connect a plugin function to a button?
///////////////////////////////////////////////////////////////////////////////

The easiest way to add a button is by using SkinStudio. WBAmp support is 
integrated. Or you can do it all by hand as explained below.

Here is an example of Button 19 which will serve as the play button.
[Button19]
Action=-4
DllName=SkinName\WBAmp.dll
WBAmp=1
WBAmpShift=18
WBAmpCtrl=17
ButtonImage=SkinName\ButtonName.bmp
Visibility=26
Visibility1=19
Visibility2=1
...

[WBAmp]
DialogMode=1

Use the WBAmp Functions Table to lookup a function. Get its number. Assign its 
value to the WBAmp entry of the button. To use Pause/Resume set WBAmp to 2, To 
use Stop set it to 3, etc.

The WBAmpShift entry specifies what function must be executed when the button 
is clicked while pressing the Shift key.

The WBAmpCtrl entry specifies what function must be executed when the button 
is clicked while pressing the Ctrl key.

Note that the WBAmp, WBAmpShift and WBAmpCtrl entry values must be present. 
There are no defaults. Note that the WBAmpShift and WBAmpCtrl entries are 
optional.

The visibility options as show here are optional, but I would suggest 
considering these. The number of buttons can become large and you will not 
always want to show them. In this example the button is show only when the 
window is not a dialog window (either the maximize or minimize buttons must 
exist), when the window is not a MDI window (this prevents more than one set 
of buttons in a MDI application) and when the window has the focus (this 
prevents the desktop to be crowded with WBAmp buttons).

All other button options can be used as normal. The "Plugin width" ("Width") 
and plugin height ("Height") parameters are ignored since WB draws the button. 
The plugin must be included in the same directory as the skin. Do not forget 
to include the plugin in the ZIP-file.

The [WBAmp] section describes WBAmp options. At the moment there is only the 
DialogMode entry. If set to 1 then the player is shown whenever a WBAmp button 
shows a dialog box.

///////////////////////////////////////////////////////////////////////////////
// Special support for ObjectMedia
///////////////////////////////////////////////////////////////////////////////

WindowBlinds comes with 2 special Visibility entries:
111: The button is shown if the window is the ObjectMedia viewer.
112: The button is not shown if the window is the ObjectMedia viewer.

These two options allow you to create skins that are aware of ObjectMedia, They 
are not required. Skins dedicated to use ObjectMedia can Visibility 111. It 
allows you to add buttons that only show up on the OM viewer.

///////////////////////////////////////////////////////////////////////////////
// Song title button
///////////////////////////////////////////////////////////////////////////////

There is one special button. It shows the current song title. It has to be 
declared a little bit different. This is an example.
[Button26]
Action=-3
DllName=SkinName\WBAmp.dll
Align=1
XCoord=224
YCoord=4
Width=120
Height=20
Visibility=26
Visibility1=19
Visibility2=1
...

[WBAmp]
TitleBack=SkinName\TitleBack.bmp
TitleMode=1
TimerInterval=1000
FontName=Arial
FontClip=4
FontHeight=0
FontWeight=0
FontItalic=0
FontUnderline=0
FontStrikeOut=0
FontColorR=255
FontColorG=255
FontColorB=255

The Action entry must be set to -3. This ensures that the plugin can update the 
button. Make shure that you do not specify a ButtonImage. If you do specify one 
than it uses resources that are never used. Instead use the TitleBack entry in 
the WBAmp section. That section also specifies the TitleMode. In this version 
there are only two modes. If the TitleMode is set to 1 then the button image 
contains two images (for the active and inactive state). If the TitleMode is 
ommited or set to 0 then no title and button will be displayed (just a black 
box). So you will have to set it to 1. Other values are reserved for future 
releases.

The "Width" and "Height" entries must be present. The number pixels along the 
X-axis of the TitleBack image must be equal to 2 x Width. The number of pixels 
along the Y-axis must be equal to Height.

The TitleBack image looks like a normal title bar button. It contains 2 images:
1: Active
2: Inactive

The TimerInterval entry sepecifies the timer interval in milliseconds. The 
lower the number the faster the update, but the higher the CPU usage. Infact 
Windows is not able to be very accurate. It uses the message queue for timer 
updates, which can be slow and inacurate. The default timer interval of 1 
second (1000 milliseconds) is a good value. It increases CPU usage by 4% on a 
500MHz PIII system.

The following font entries (in the WBAmp section) are optional:
FontName       =Font name (less than 32 characters)
FontClip       =Number of pixels to clip from left and right border
FontHeight     =Pixels (negative value) or points (positive value)
FontWeight     =0, 100, 200, 300, 400, 500, 600, 700, 800, 900
FontItalic     =0 (normal) or 1 (italic)
FontUnderline  =0 (normal) or 1 (underline)
FontStrikeOut  =0 (normal) or 1 (strike-out)
FontColorR     =Between 0 and 255 (inclusive)
FontColorG     =Between 0 and 255 (inclusive)
FontColorB     =Between 0 and 255 (inclusive)

The FontWeight is used as follows:
  0: Don't care 
100: Thin
200: Extra light (ultra light)
300: Light
400: Normal (regular)
500: Medium
600: Semi bold (demi bold)
700: Bold
800: Extra bold (ultra bold)
900: Heavy (black)

The FontColorR, FontColorG and FontColorB entries form the RGB values of the 
font color.

All other button options can be added as required.

Note that the title is only updated in the active window. This prevents that 
the skin uses to much CPU time.

///////////////////////////////////////////////////////////////////////////////
// Installing ObjectMedia
///////////////////////////////////////////////////////////////////////////////

No special options to set for ObjectMedia.

If ObjectMedia runs with its default options then it just shows up in the 
system tray and the taskbar button is hidden. You can change that behaviour 
by opening the system tray menu. Select Options on the Viewer tab sheet. Or you 
can double click the system tray icon and select Options from the Tools menu. 
If the menu is hidden then press Ctrl+M.

///////////////////////////////////////////////////////////////////////////////
// Installing CoolPlayer
///////////////////////////////////////////////////////////////////////////////

The installation of CoolAmp is easy. Select "Options" from the menu, enable the 
"Scroll Songtitle" option. You may also want to disable the "Show on taskbar" 
option.

Whenever CoolPlayer is started it will show up on the system tray. Most skins 
do not show CoolPlayer by default. Some have an option to show it, but you can 
also double click the CoolPlayer icon.

///////////////////////////////////////////////////////////////////////////////
// Installing WinAmp 2.xx
///////////////////////////////////////////////////////////////////////////////

The installation of WinAmp in combination with WBAmp is actually a matter of 
configuring WinAmp correctly. Use the following WinAmp setting: At the WinAmp 
menu select "Options". Then "Preferences". Click "Display" in the tree. In the 
"Show WinAmp in:" box select "System tray only". This will prevent WinAmp from 
showing its ugly skin... If you now minimize WinAmp then it ends up in the 
SystemTray and will not be seen on the TaskBar. To restore it just single click 
the WinAmp icon in the SystemTray. Right clicking the icon on the SystemTray 
will show the WinAmp menu.

"I did what you said, but now I don't see WinAmp anymore..."
Well, that is the idea. You should not see WinAmp, unless you want it to be 
shown. If you start WinAmp, you do not see it either. If you go and look for 
it, you will find it in the SystemTray.

"The title bar is too small for the song title. How can I make it scroll?"
This is just another WinAmp setting. Open the WinAmp menu. Select "Options". 
Then "Preferences". Click "Display" in the tree. Finally check "Scroll song 
title in the Windows task bar". That's it. The text will not only scroll in the 
task bar, it will also scroll in the title bar of the skin.

///////////////////////////////////////////////////////////////////////////////
// Starting the player
///////////////////////////////////////////////////////////////////////////////

You can either start the player as you used to or you can push any WBAmp 
button. It takes a while for it to start. During startup it cannot execute the 
action attached to the button. So the initial click just resulted in the player 
being started. This is not an error. You have to live with it OR add the player 
to your Startup menu. This causes the player to start whenever Windows starts.

///////////////////////////////////////////////////////////////////////////////
// Version
///////////////////////////////////////////////////////////////////////////////

You can check what version of WBAmp is installed by right clicking the 
WBAmp.dll file, then select Properties from the menu and finally click the 
Version tab.

///////////////////////////////////////////////////////////////////////////////
// WARNINGS
///////////////////////////////////////////////////////////////////////////////

If you design a skin and use WBAmp please be sure that dialog boxes do not have 
WBAmp buttons. Dialog boxes are used in error messages and since the player can 
produce errors it would be a bad idea to present WBAmp buttons while in the 
middle of handling player error.

Make shure that WBAmp buttons do not show up on MDI windows. You will end up in 
having them duplicated. Also, I don't what happens if there are more than one 
visible title buttons. WBAmp does not support it and it can be a performance 
bottle neck.

///////////////////////////////////////////////////////////////////////////////
// Showing player menus and dialogs
///////////////////////////////////////////////////////////////////////////////

Calling the a player's menu or dialog without showing it can cause it behave 
bad. Therefore the must be shown.

///////////////////////////////////////////////////////////////////////////////
// Version 1.3.0.30 release notes
///////////////////////////////////////////////////////////////////////////////

Time for an update. Support added for ObjectMedia.
WindowBlinds added support for ObjectMedia (Visibility options 111/112).
