//////////////////////////////////////////////////////////////////////
// WBAmp 1.1.0.0
// Copyright (c) 2000 Matthijs Vermeulen (MadIce XIII)
// MadIceXIII@hotmail.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-test team
// * Morphh (the originator of WBAmp)
// * d
// * dbqp
// * Dan Boldon
// * Philip Powell
// * Mercury
// * jef
// 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 BB
// The latest version of WBAmp can be found at http://go.to/WBStuff
// You can find other fantastic WB Stuff there too
//////////////////////////////////////////////////////////////////////
// Thanks to Neil Banfield for his support
//////////////////////////////////////////////////////////////////////
// Thanks to Lowell Headings for publishing the source code of
// GeekAmp (a remote control for WinAmp in LiteStep)
//////////////////////////////////////////////////////////////////////

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

WBAmp is a plugin which can be used to control WinAmp from within the titlebar of a WindowBlinds skin.

The following functions are available:

//////////////////////////////////////////////////////////////////////
// WBAmp Functions
//////////////////////////////////////////////////////////////////////

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

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

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=0

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 WBAmpShift 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 WinAmp is shown whenever a WBAmp button shows a dialog box.

//////////////////////////////////////////////////////////////////////
// WinAmp title button
//////////////////////////////////////////////////////////////////////

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

[WBAmp]
TitleBack=DarkAmpXIII\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 WBAmp
//////////////////////////////////////////////////////////////////////

The installation of 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 WinAmp
//////////////////////////////////////////////////////////////////////

You can either start WinAmp 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 WinAmp being started. This is not an error. You have to live with it OR add WinAmp to your Startup menu. This causes WinAmp to start whenever Windows starts. If you also selected the "System tray only" function then the buttons work like expected.

//////////////////////////////////////////////////////////////////////
// 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 WinAmp can produce errors it would be a bad idea to present WBAmp buttons while in the middle of handling WinAmp 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.

//////////////////////////////////////////////////////////////////////
// Menu
//////////////////////////////////////////////////////////////////////

Calling the WinAmp menu without showing WinAmp causes the menu to behave bad. Therefore WinAmp must be shown. Until there is a better solution WinAmp will be shown before the menu is opened.

//////////////////////////////////////////////////////////////////////
// Version 1.0.0.4 release notes
//////////////////////////////////////////////////////////////////////

Any WBAmp button can startup WinAmp (except WAClose). Not just WAPlay. Startup now rarely fails (I hope). If this fails then start it manually or even better add it to the Startup menu.

//////////////////////////////////////////////////////////////////////
// Version 1.0.0.5 release notes
//////////////////////////////////////////////////////////////////////

The end of all those tiny DLLs. They are now included in WBAmp.dll.

You can now specify which function to clicking the button with shift or control should be executed.

The Show function has been improved.

The dialog boxes are behaving better.

//////////////////////////////////////////////////////////////////////
// Version 1.0.0.6 release notes
//////////////////////////////////////////////////////////////////////

Shuffle, Repeat and Single added.

VIS dialog box options added. VISSelect does not seem to be working.

The Raise and Lower volume by 1% were swapped. This has been fixed.

I have asked NullSoft to help me with the dialog boxes. Some beta-testers did not like the current window to be pushed to the back. I have taken it out and hope NullSoft comes with an solution for the final build today.

//////////////////////////////////////////////////////////////////////
// Version 1.0.0.7 release notes
//////////////////////////////////////////////////////////////////////

Test code removed.

Menu code restored.

//////////////////////////////////////////////////////////////////////
// Version 1.0.0.8 release notes
//////////////////////////////////////////////////////////////////////

Title button added.

WBAmp function Run (30) added.

Documentation updated.

Fixed a serious range checking bug. This bug only showed up when a non-existent function number was specified in the UIS file (number of functions + 1) and caused the skinned program to terminate.

There is still a bug when the window calls a dialog box. The title bar button is not updated correctly in that situation. I am working on that one.

//////////////////////////////////////////////////////////////////////
// Version 1.0.0.9 release notes
//////////////////////////////////////////////////////////////////////

Documentation updated.

The title bar button bug has now been fixed.

//////////////////////////////////////////////////////////////////////
// Version 1.0.0.10 release notes
//////////////////////////////////////////////////////////////////////

Short song titles were unable to fill the entire title button. This bug has been fixed.

//////////////////////////////////////////////////////////////////////
// Version 1.1.0.0 release notes
//////////////////////////////////////////////////////////////////////

Removed test code.

Documented the source code.

