NumPlug Documentation (such as it is . . .) - by TheGreenReaper

*Stuff added in 0.03 and 0.50*
Bug-fixes and general messing around.
Alpha blending. See the section format info for this. It doesn't seem to work properly for multi-threaded or MDI apps (almost certainly because of the use of global variables) - anyone who wants to fix this, feel free . . .

Ever wanted to display a list of numbers in your skin (just like Mercury's excellent skin, 'What is the Matrix?'), but didn't want to draw each frame? Wanted random numbers, but couldn't even be bothered to draw a cycle of 10, let alone 1000? NumPlug is what you want! (I hope so, anyway :-)

Call 1-800-NUMPLUG (or goto www.redrival.com/exile/) and order your special promotional pack today! There's no obligation to skin, and no spammers will call. No programming experience required (but you might want to be able to make a simple skin already :-). WindowBlinds and associated tools sold separately. Bitmaps not included (well . . . they are. But you WILL want to make your own - <g>)

NumPlug can now display any alphanumeric characters you can type (in cycle mode). In fact, you can use a character (say '') to represent anything you want (a druidic rune, a mathematical symbol . . . anything you can draw) and have NumPlug draw it for you. Just remember to put the characters you use in the charmap setting, and remember that it is CASE SENSITIVE. Any missing symbols (you specify a character in a CycleNumX but it's not in charmap) will show up as black holes in the output, so it should be a fairly easy problem for you to diagnose . . . and if you didn't even bother to make the bitmap big enough, you get to see random bits of skin! :-)

NumPlug works needs the following things - a bitmap file with the character images in and a section in your UIS file where you select NumPlug's behaviour. You specify how many and which characters you have drawn in the bmp file by the charmap setting - the default is "0123456789._" - and there must be two rows, of equal height, the top row containing the character bitmaps for active windows, the bottom for inactive windows. This setting *must* be correct or everything else could get messed up - and please make sure you don't duplicate characters, since NumPlug relies on the number of characters to calculate the width of the bitmap.

It is assumed that borders will be provided for around the button by the skinner, AND THAT THE DLL BUTTON IS BIG ENOUGH TO DRAW THE REQUESTED NUMBER OF DIGITS - <g>. If the width is *not* correct, NumPlug will round down/round up and fill with black/explode in a burst of flames and trash your drives [I haven't decided which yet - best make sure it *is* :-]. Similarly, the height of the DLL button should be half the height of the image (active/inactive split). Please don't ask me to allow for animated characters - they might come, but it's somewhat unlikely :-)

Also, numbers are currently limited to longs, which means that if (in counter mode) the counter is set much above about 2 billion, or increments up to it (well, 4 now I'm using ULONGS), the result is 'undefined' - <g> - I've tried to allow for this and other 'mistakes' on the part of the author (if you set Digits=5 but give StartingNumber to 8 it should draw the first 5 etc), but it's your call. 'Fun' behaviour (depending on your sense of humour) may result from the use (and especially misuse) of this DLL.

NB This documentation was written as much as a guide to me as to you, right at the start of development, so don't be surprised if features you read about here are utterly missing/incomplete/buggy/inelegant/looking cool and working perfectly. It all depends on how far I've gotten. In particular, TransitionMode and StartingDate/Time will probably not work yet (ever?).

The UIS section format is as follows:

[NumPlug] 			;Block header
Version=1			;Version of NumPlug. Try 1 :-)
Digits=12			;Number of digits
DigitsImage=DigitalAge\Digits.bmp	;Location of digits image file
StartingNumber=19091982		;If omitted, 0 is assumed
CharMap=0123456789._ABC		;Each character corresponds to one in the image
				;anything you can type in notepad, you can use
				;Numbers *must* be there if countermode == 1 or 2
				;if == 0 (cycle mode), put the characters in the
				;CycleNumX strings to have them displayed (see below)
CounterMode=0			;0 == Set cycle, 1 == Increasing count
				;2 == Random (by RandMax)
TransitionType=0		;0 == Simple redraw
				;1 == Slide from top
				;2 == Slide from bottom
				;3 == Dissolve/Reform
LeadingMode=1			;0 == 0 for leading 0's
				;1 == Blank image used for leading 0's
				;2 == Separator image used for leading 0's
NonFocusUpdate=0		;0 == will not update if window hasn't got the focus
				;1 == will update (with alternate digits)
				;If omitted, 0 is assumed
UpdateInterval=200		;in milliseconds, accurate to about 56 ms
				;(if you need to ask why, you don't need to know :-)
AlphaMode=1			;0 == no alpha change (default), 1 == fade out on inactive
				;2 == continuously fade in and out
AlphaLevel=0			;Startup alpha value, eg if 0 then on window startup
				;the plugin will fade in (and then stay visible)
				;THIS OVERRIDES button Alpha settings and should be set
				;instead of them if FadeMode != 0 (not-equal to 0 :-)
AlphaMin=0			;Mininum level for alpha (default == 0)
AlphaMax=255			;Maximum level for alpha (default == 255)
AlphaSteps=16			;The change (increase or decrease) per frame drawn
				;in this case it would take 255/16=16 frames to fade
				;completely in or out from the opposite setting (default == 16)
AlphDir=1			;Initial direction of fade. Only really has meaning if
				;FadeMode == 2, else it is overridden.
				;0 == fade down, 1 == fade up (default)

;The following are only valid if countermode == 0
CycleLength=6			;Length of cycle (in numbers)
CycleNum0=125.7136_ABC		;Yes, programmers *always* start from 0 - <g>
CycleNum1=236.8247_BCA		;Use '.' for separator and '_' for blank
CycleNum2=347.1358_CAB		;Any omitted numbers will be set to 0
CycleNum3=458.2461_ABC		;If the number of digits is less than the max
CycleNum4=561.3572_BCA		;bad things will probably happen . . .
CycleNum5=672.4683_CAB		;actually not too bad, afaik, just not right

;The following are only valid if countermode == 1, and if I've done it (looks hard :-)
IncreasePerCycle=6			;If omitted, 1 is assumed - increase per UpdateCycle
StartingDate=19/09/1982			;If omitted, current used (format DD/MM/YYYY)
StartingTime=19:36			;If omitted, current used (format HH/MM)
					;(These last two are not implemented at this time)

;The following are only valid if countermode == 2
RandMax=9999				;If omitted, 1 is assumed
RandMin=1000				;If omitted, 0 is assumed
					;so if you just get 0 and 1, this is the problem . . .

You don't need all these settings. In fact, you only *really* need Digits, DigitsImage, CounterMode and CharMap. But you won't get much of a customised plugin then - this was designed to be flexible.

The latest version of this plugin should be available at www.redrival.com/exile/ - if it's not, email me and I'll send you it (assuming I get as far as a working specimen :-). It should be obvious by now that this is not quite a finished project . . . please DO email me if you have *any* problems getting it to work (or any fun errors - and to the programmer, errors are always fun: just ask Kris or Brad! - <g>. Feature requests are also welcome, though some things may not be possible with a plugin DLL, most things are: trashing drives, sending private and confidential information back to the author via the internet, playing pong . . . the list is endless!

(GreenReaper Studios would like to take this opportunity to confirm that no information is, in fact, sent across the internet by NumPlug, nor are hard drives in danger of nefarious code [you have the source to check]. I'll put pong in when I have the time :-)

I hope this documentation has been illuminating! If not, or if you have further questions/praise/huge bags of money, email me at greenreaper@hotmail.com. Flames, unless interesting or technically correct (the best sort . . . but what flame is ever correct?), will be redirected to /dev/null (the interesting ones get posted to the stardock newsgroups, along with your name, address, telephone number, major credit cards . . . plus my good friend th3gr33nr34p3r and his associate M451c3 will h4x0r j00. h4w! ;-)

NumPlug is distributed under the GNU Lesser General Public Licence - see copying.txt. As such, you are encouraged to distribute and modify it as you wish, as long as you abide by the terms of the GPL (for example, you *must* ensure that all code derived from SkinBench is freely available to all third parties in source form, and you must make this clear to your users). I've tried to ensure the code is reasonably commented - you should be able to figure it out ;-)

NumPlug is dedicated to the Creatures of Albia, the good folks of Stardock Corporation and Jolt Cola ("Jolt! With twice the caffine and all the sugar of a regular cola, how can you go wrong?") - here's wishing it was available over here in the UK. NumPlug was programmed listening to the feel-good tunes of Radiohead, REM, Phish, TMBG and The Beatles, as well as several bands I'd never heard of and don't ever want to again . . . 

Enjoy!

TheGreenReaper (Laurence Parry)

Medical Warning - This document contains over 96% of the RDA (Recommended Daily Allowance) of :-) - in case of over-exposure, consult DrWatson.

Version History:
0.01 - First release to a dedicated group of WB users and skinners - you know who you are, and others can probably guess - <g>
0.02 - Lots of timer tweaking and behind-the-scenes reshuffling. Support for specifying the entire range of alphanumeric characters (don't ask for Unicode) rather than just digits.
0.03 - Fade-in/out support added. Even more timer woes and eventual triumphs (hopefully . . .)
0.50 - "Final" beta release.