So, what better time to warm up your desktop with the new Windows 7 Holiday Lights desktop theme? 17 new desktop wallpapers each featuring a wintry theme are on offer, with “sparkling images of holiday celebration and winter wonder” according to the website.

My personal favourite is the snowy river scene, shot deep in a forest. It looks like the coldest place on earth, apart from the glow from a sole fir tree, fully illuminated and bathing the adjacent river with light.

I don’t know who had the impossible job of wiring that tree up, but next weekend, when I’m nailing up our own lights in the garden, I won’t feel so bad!

Let’s say you get lost in a blizzard -  GPS to the rescue! Ah, that’s going to require at least 1 minute of gloveless typing in the middle of a deep freeze. Not good. Okay, pull off a glove, find the app, get a position, try to type in your desired destination – hand freezes up, impossible to type any more.

The answer to this seasonal quandary is most definitely Freehands. Filed under “ideas so bad they’re actually quite good” Freehands offer a wide range of gloves with removeable thumb and index finger. Fleece? Cashmere? Wool? Soft Shell? They have the lot.

Now your Winter portable electronics emergency is easily resolved. Terrible track comes on the headphones requiring a shuffle? Must-have photo of snowball fight required? Mobile video opportunity of the kids sledging? Just pop off a finger and thumb, and you’re all set with only minor cooling impact.

They’re sure to be seen in a Sky Mall catalogue soon, so check them out before they go mainstream!

Introduction

This article describes “Gremlin”, a quick and easy application that lets you play Halloween tricks. When your victim's computer is idle, Gremlin moves windows around on the screen, changes the focus window, moves your mouse, scrolls windows, and types nonsensical stuff. When there is background noise – like someone talking – it will shake the screen, even as your victim is typing away.

Deployment

Run it right away. You can download, copy theGremlin.exe executable and NAudio.dll to the victim's computer (say in c:\ directory), and then double click on the executable to run it.

Run it later. The other option is to copy the executable and dll files (or a shortcut to it) to the Startup folder on the victim's machine and watch the fun begin when they start up their machine in the morning!

If the computer you're using runs on Windows XP the path is:

C:\Documents and Settings\All Users\Start Menu\Programs\Startup

With Vista and Windows 7 the path looks like:

C:\Users\USERNAME\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup

Just remember to change USERNAME to the name of the user on your machine.

Commandline

Gremlin is compiled as a windows application, so it won't popup a terminal window if you double click on it, etc. But you can run it from the command line with flags:

-aggressive will make the gremlin's actions more obvious

-help will display the command line options

-name NAME is useful for testing. Gremlin will only use windows with this specific title or from this specific application. (Remember to drop the ".exe" from the application filename)

To stop the program, press CTRL+F2.

And now … the dodgy bits

The overall structure of the program is broken down into three kinds of functionality – actions, triggers and some interstitial glue:

Actions

• The screen-shaker is a window that makes the monitor look like it is shaking. Sort of like a loose cable on the back of the monitor.
• A random event might kick the windows around—either friction will slow them down, or...
• Gremlin will type nonsensical messages from the keyboard. These messages are then sent from a virtual keyboard, or they:
• Move the mouse around, or
• Press the mouse buttons, or
• Randomly switch the focus to another window

Triggers

• An audio module listens for sounds that trigger the module that shakes your screen.
• Otherwise, the software uses a p/invoke to GetLastInputInfo() and waits for the user to be idle for a minute or two. When it detects that the user is inactive, it randomly selects and carries out actions.

Other

• A hidden window receives key press events. I tend to reuse this module a lot, as a way to stop experimental programs that may have made my machine unusable.

For fun, I'll describe a couple of these modules below.

Screen shaker

My favorite bit is the screen shaker. It grabs a picture of the screens, creates a window that spreads across them, and then moves that image back and forth a few pixels every 30ms or so, with a little bit of random rotation. (Faster computers, of course, get a better effect).

The screen shaker is special in four ways:

• It is a top-level window – no other windows are allowed to go over it.
• This top-level window never becomes the focus window (the window that gets the keyboard events).
• Mouse button events (e.g. clicks and double-clicks) are passed through to the windows and desktop underneath. This gives the illusion that this is the "real" desktop shaking, by allowing a person to click on a button or text that passes the click thru to the real button or text.
• It shakes each of the monitor's screens independently

Some background: to create a window that looks like the shaking screen, I used two classes. The first is ScrShake (in ScreenShake.cs), which derives from the second class UnfocusableForm.  I'll describe ScrShake first.

The screen shaking process requires five instance variables:

• animTimer is a System.Windows.Forms.Timer used to force painting of a new frame on the screen.
• bx, and by are how far the screen has shaken up or down, left or right.
• angle is how much the screen has twisted during shaking.
• screenBitmap is an array of bitmaps, one for each of the monitors.

This creates a window without a border or other trappings, then makes it the topmost window and sets a flag in the method variable ExStyle to ignore mouse clicks. More on this flag in a little while.

C#

public partial class ScrShake : UnfocusableForm
{
   public ScrShake(double ShakeCoef, double AngleCoef) : base(true)
   {
      this.SuspendLayout();
      … other setup code …
      // This is needed since we're over the whole display, and we don't
      // want the other areas to be blurry
      TransparencyKey =  BackColor = ForeColor = System.Drawing.Color.Fuchsia;
      DoubleBuffered = true;
      TopMost = true;
      FormBorderStyle = System.Windows.Forms.FormBorderStyle.None;

      ClientSize = new System.Drawing.Size(300, 300);
      Name = "topimage";
      ResumeLayout(false);

      // This is need to pass mouse clicks thru to lower layers
      ExStyle |= (int) WS . EX_TRANSPARENT;

      … More code that will be described later…
   }
}

When the timer has done a given number of animations, it will call the Stop() method. This will stop the animation, clean it up, and hide the window:

C#

void Stop()
{
   animTimer . Stop();
   Hide();
   screenBitmap = null;
}

When the main loops that start the animated screen shaking process, it calls the Screens() method. This grabs an image of the screens, determines the shape of each monitor, and starts the animation for 10 frames.

C#

internal void Screens()
{
   if (Visible)
   {
      Stop();
      return ;
   }
   // Grab the screens
   screenBitmap = Program.GrabScreens();
   CountDown = 10;

   animTimer.Start();
   angle = 0.0f;
   … code to display the window and get shape of monitors (see below)…
}

The screen capture portion is in ScreenCapture.cs. The method GrabScreens() creates an individual bitmap for each monitor and returns them as an array.

C#

internal void Screens()
{
   if (Visible)
   {
      Stop();
      return ;
   }
   // Grab the screens
   screenBitmap = Program.GrabScreens();
   CountDown = 10;

   animTimer.Start();
   angle = 0.0f;
   … code to display the window and get shape of monitors (see below)…
}

The code below determines the bounds of each screen and builds up a size of all of the screens put together. The window will be set to be this size.

C#

Screen[] AllScreens = Screen.AllScreens;

// full width/height of all monitors combined
Rectangle fullSize = AllScreens[0].Bounds;

// find a rectangle that will encompass all monitors on the system
// (assuming the primary monitor is on the left/top!)
for (int i = 1; i < AllScreens.Length && i < screenBitmap.Length; i++)
{
    Rectangle Bounds = AllScreens[i].Bounds;

    if (Bounds.Left < fullSize.Left)
        fullSize.X = Bounds.X;

    if (Bounds.Right > fullSize.Right)
        fullSize.Width = Bounds.Right - fullSize.X;

    if (Bounds.Top < fullSize.Top)
        fullSize.Y = Bounds.Y;

    if (Bounds.Bottom > fullSize.Bottom)
        fullSize.Height = Bounds.Bottom - fullSize.Y;
}

The code to show the window, fill the whole screen, and move it to the top looks like:

C#

Show();
WindowState = FormWindowState.Normal;
// cover all monitors with one gigantic window
Location = new Point(fullSize.Left, fullSize.Top);
Size = new Size(fullSize.Width, fullSize.Height);

// bring it to the top
BringToFront();

The constructor also created a timer that drives the screen shaking effect. The timer has a delegate that randomly selects the angle of rotation and the offset of the image, and triggers a repaint of the window. (The amount of shaking is controlled by two external variables called AngleCoef and ShakeCoef).

C#

animTimer = new System.Windows.Forms.Timer();
animTimer.Tick += delegate(object A, EventArgs E)
{
    if (--CountDown < 1)
        Stop();

    angle += (float)((Program.Rnd.NextDouble() - 0.5) * AngleCoef);
    bx = (float)((Program.Rnd.NextDouble() - 0.5) * ShakeCoef);
    by = (float)((Program.Rnd.NextDouble() - 0.5) * ShakeCoef);
    Invalidate();
};

// Sets the timer interval to 30 milliseconds.
animTimer.Interval = 30;

Although each monitor shifts up & down, left & right by the same amount, and rotates by the same angle, they are painted independently. This gives the illusion that each monitor has a shaky image. Paint the window is using the following code.

C#

protected override void OnPaint(PaintEventArgs e)
{
    base.OnPaint(e);
    Graphics g = e.Graphics;
    g.CompositingQuality = CompositingQuality.HighQuality;

    // for each monitor, draw the effect
    Screen[] AllScreens = Screen.AllScreens;
    for(int i = 0; i < screenBitmap.Length; i++)
    {
        if (null == screenBitmap[i])   continue;
        g.SmoothingMode = SmoothingMode.HighQuality;

        // grab the size of the current monitor
        Rectangle region = AllScreens[i].Bounds;

        double ImWidth = screenBitmap[i].Width  * 
           e.Graphics.DpiX / screenBitmap[i].HorizontalResolution;
        double ImHeight= screenBitmap[i].Height * 
           e.Graphics.DpiY / screenBitmap[i].VerticalResolution;
        Matrix m = new Matrix();
        m.Translate( (float)(- ImWidth  /2), 
                  (float)(- ImHeight /2), MatrixOrder.Append);

        // rotate the bitmap about the center
        m.RotateAt(angle, new Point(0,0), MatrixOrder.Append);

        // center the image no matter what its size is
        m.Translate( region.Width /2 - bx, 
                  region.Height/2 - by, MatrixOrder.Append);

        // assign our transformation matrix
        g.Transform = m;

        // draw it
        g.DrawImage(screenBitmap[i], region.Left, region.Top);
    }

The Form that does nothing!

The ScrShaker class uses a help class called UnfocusableForm (in UnfocusableForm.cs) to create a window that never becomes the focus window – it never receives key presses, etc.

This window has no trappings – no border, no resize gripper, no icon, no minimize / maximize buttons, no title bar.

C#

public partial class UnfocusableForm : Form
{
   public UnfocusableForm(bool X) : base()
   {
      if (X)
        {
           ControlBox = false;
           FormBorderStyle = System.Windows.Forms.FormBorderStyle.None;
           ShowInTaskbar = false;
           ShowIcon = false;
           MinimizeBox = false;
           SizeGripStyle = System.Windows.Forms.SizeGripStyle.Hide;
           StartPosition = System.Windows.Forms.FormStartPosition.Manual;
        }
   }

Then it overrides the ShowWithoutActivation method so that the window will not become the active when it is shown.

C#

protected override bool ShowWithoutActivation
{ get {  return true; } }

The UnfocusableForm class also overrides the CreateParams() method to set extra styles when creating the window. I haven't found a way to set these styles flexibly. Instead, the UnfocusableForm uses a method variable called ExStyle that allows derived classes to specify what flags they desire. In this case, The ScrShake class used the method variable to set a flag that ignore mouse clicks:

C#

protected override CreateParams CreateParams
{
  get
  {
     CreateParams cp=base.CreateParams;
     cp . ExStyle |= ExStyle;
     return cp;
  }
}

Finally, it captures a couple of events that ask a window if it would like to become the active window. (These usually happen when the user clicks on an inactive window):

C#

internal const int MA_NOACTIVATE = 0x0003;
protected override void WndProc(ref Message m)
{
  if (m.Msg == (int) WM.MOUSEACTIVATE)
  {
     m.Result = (IntPtr) MA_NOACTIVATE;
     return;
  }
  if (m.Msg == (int) WM.FOCUS)
  {
     m.Result = (IntPtr)1;
     return;
  }
  base.WndProc(ref m);
}

Sending Mouse Events

Sending Mouse Events is simple, but not trivial. The wiki at Pinvoke.net provides the signature to the procedures and structures we need to pass to it. (Note: these structures are a bit different, based on a blog posting by Raymond Chen)

C#

[DllImport("user32.dll", EntryPoint = "SendInput", SetLastError = true)]
static extern uint SendInput(uint nInputs, INPUT[] Inputs, int cbSize);
[DllImport("user32.dll", EntryPoint = "GetMessageExtraInfo", SetLastError = true)]
static extern IntPtr GetMessageExtraInfo();

[StructLayout(LayoutKind.Sequential)]
struct INPUT
{
   internal INPUTTYPE   type;
   internal INPUT_UNION i;
}

 // This generates the anonymous union
[StructLayout(LayoutKind.Explicit)]
struct INPUT_UNION
{
   [FieldOffset(0)]
   public MOUSEINPUT mi;
   [FieldOffset(0)]
   public KEYBDINPUT ki;
   [FieldOffset(0)]
   public HARDWAREINPUT hi;
};

[StructLayout(LayoutKind.Sequential)]
struct MOUSEINPUT
{
   public int    dx;
   public int    dy;
   public int    mouseData;
   public MOUSEEVENTF dwFlags;
   public int    time;
   public IntPtr dwExtraInfo;
}

[Flags]
enum MOUSEEVENTF : int
{
   MOVE       = 0x01,
   LEFTDOWN   = 0x02,
   LEFTUP     = 0x04,
   RIGHTDOWN  = 0x08,
   RIGHTUP    = 0x10,
   MIDDLEDOWN = 0x20,
   MIDDLEUP   = 0x40,
   ABSOLUTE   = 0x8000
}

Each of these pieces go together in a specific way. To do a mouse movement, a mouse event structure needs to be created. This involves setting dwFlags to the kind of mouse event (a relative movement in this case), dx and dy to the number of pixels moved. It is also important to set dwExtraInfo to whatever GetMessageExtraInfo() is set to.

C#

MOUSEINPUT MEvent = new MOUSEINPUT();
MEvent.dwFlags = MOUSEEVENTF.MOVE;
MEvent.dx = Rnd . Next(-8, 8) ;
MEvent.dy = Rnd . Next(-8, 8);
MEvent.dwExtraInfo = GetMessageExtraInfo();
Send(MEvent);

Sending the event takes a few more steps that are all wrapped in a helper methdo called Send(). Send these human interface device events via the SendInput() procedure (earlier). The procedure takes an array of events, for different kinds of devices. We have to create the array, set the event type, copy the event data, and then make the call:

C#

public virtual bool Send(MOUSEINPUT Event)
{
  INPUT[] Events = new INPUT[1];
  Events[0] . type = INPUTTYPE . MOUSE;
  Events[0] . i.mi = MEvent;
  return SendInput((uint)Events.Length, Events, Marshal.SizeOf(Events[0])) > 0; 
}

From here, sending a mouse button click is pretty straight forward. A mouse click is really a mouse button press event, followed by a mouse button release event. To make things interesting the mouse button is choosen at random. The “ugly” part is that each of the mouse buttons is assigned a bit, so a binary shift is used to convert a button number to its bit. And the button release is yet another bit, so the second message shifts the flags, to move the bit from the “button pressed” state to the “button released state”.

C#

MOUSEINPUT MEvent = new MOUSEINPUT();
MEvent.dwFlags = (MOUSEEVENTF) (1 << (2*Rnd.Next(0, 3)+1)) ;
MEvent.dwExtraInfo = GetMessageExtraInfo ();
Send(MEvent);

MEvent.dwFlags = (MOUSEEVENTF)((int) MEvent.dwFlags << 1);
MEvent.dwExtraInfo = GetMessageExtraInfo ();
Send(MEvent);

Generating deranged text

The gremlin can also type deranged sentences that will appear in editors, if the user left one open. The SendWait() method in the SendKeys class does the typing itself:

C# 

SendKeys . SendWait(GenerateSentence());
SendKeys . SendWait("{ENTER}");

Generating the sentences is not difficult; I used a simplistic Markov generator. This generator starts by randomly selecting a word that can start a sentence. The Starts variable is array which holds just these words. Then, in the Transition method, this word is used to find the next word that can be included in the sentence. It does this by using a dictionary, called NonStart, which given the word as a key, will return a list of all the words that can come after it. This process then repeats, appending the words onto the end of a string. It stops if it finds a word that can end a sentence.

C#

static Dictionary<string,string[]> NonStart ;
static string[] Starts;
static Dictionary<string,string> Terminal ;

static string GenerateSentence()
{
  StringBuilder SB = new StringBuilder();
  string Word = Starts[ Rnd.Next(0, Starts.Length) ];

  Transition(SB, Word);
  return SB.ToString();
}

static void Transition(StringBuilder SB, string Word)
{
  while (true)
  {
     SB.Append(Word);
     SB.Append(' ');

     // Look up word after this
     string[] Nexts;
     if (!NonStart.TryGetValue(Word, out Nexts))
       break;
     int Idx = Rnd.Next(Terminal . ContainsKey(Word) ? -1 :0, Nexts.Length);
     if (Idx < 0)
       break;
     Word = Nexts[Idx];
  }
}

Building these two dictionaries and array is a pretty simple process. The BuildSuffixTree() method takes a string and splits it up into sentences. Then it splits each sentence into (lower case) words. The first word of the sentence goes onto the end of the Starts array. Otherwise, the previous word is used to look up a list in a dictionary, and the current word is appended on to the list. This dictionary will become the NonStarts dictionary. The last word of the sentence is also placed into the Terminal dictionary, to indicate that this might be the end of a sentence.

C#

static void BuildSuffixTree()
{
  // First, build up a list of words that start sentence, and transitions
  List<string> Starts1 = new List<string>();
  Dictionary<string,List<string>> Trans = new Dictionary<string,List<string>>();
  foreach(string S1 in S.Split(new char[]{'.','?','!'}))
  {
     string Prev=null;
     foreach(string S2 in S1.Split(new char[]{' ','\n','\r','\t',',',';'}))
     {
        if (S2 . Length < 1)
          continue;
        if (null == Prev)
          {
             Starts1.Add(string.Intern(S2.ToLower()));
             Prev = string.Intern(S2.ToLower());
             continue;
          }
        List<string> Nextsa;
        if (! Trans.TryGetValue(Prev, out Nextsa))
          Trans[Prev] = Nextsa = new List<string>();
        Prev = string.Intern(S2.ToLower());
        Nextsa.Add(Prev);
     }
     if (null != Prev)
       Terminal[Prev] = Prev;
 }

 // Next, flatten the list of words that start a sentence
 Starts = Starts1.ToArray();

 // Flatten the transition table
 foreach (string S3 in Trans.Keys)
  NonStart[S3] = Trans [S3].ToArray();
}

The things that trigger action

The audio trigger

The audio module (in file AudioTrigger.cs) listens in on all of the microphones. It uses NAudio, with a basic setup and delegate structure swiped from Mark Heath's article “.NET Audio Recording”. The first difference is that it registers all audio input devices:

C#

static WaveIn[] StartMics()
{
  int NumDevices = WaveIn.DeviceCount;
  WaveIn[] AudIns = new WaveIn[NumDevices];
  for (int waveInDevice = 0; waveInDevice < NumDevices ; waveInDevice++)
  {
     AudIns[waveInDevice] = new WaveIn();
     AudIns[waveInDevice].DeviceNumber = waveInDevice;
     AudIns[waveInDevice].DataAvailable += waveIn_DataAvailable;
     AudIns[waveInDevice].WaveFormat = new WaveFormat(8000, 1);
     AudIns[waveInDevice].StartRecording();
  }
  return AudIns;
}

The real magic in the trigger is a modified version of the waveIn_DataAvailable delegate. Instead of saving the audio, it checks for any sound activity. It starts by checking to see if any of the sound amplitudes are greater than a pre-defined, very high threshold. Then the samples are squared and summed up, and the result is compared with a threshold. If it exceeds the threshold, the trigger is set. These two are good at catching the kind of sound made when a person is talking, futzing on the desk, or typing.

C#

static double AudioThresh  = 0.8;
static double AudioThresh2 = 0.09;

static void waveIn_DataAvailable(object sender, WaveInEventArgs e)
{
  bool Tr = false;
  double Sum2  = 0;
  int Count = e.BytesRecorded / 2;
  for (int index = 0; index < e.BytesRecorded; index += 2)
  {
     double Tmp = (short)((e.Buffer[index + 1] << 8) | e.Buffer[index + 0]);
     Tmp /= 32768.0;
     Sum2 += Tmp*Tmp;
     if (Tmp > AudioThresh)
       Tr = true;
  }
  Sum2 /= Count;

  // If the Mean-Square is greater than a threshold, set a flag to indicate that noise has happened
  if (Tr || Sum2 > AudioThresh2)
    Interlocked.Exchange(ref AudioTrigger, 1);
}

This sets a flag – AudioTrigger – which will be seen (and reset) in the main loop, with a bit of code that looks like:

C#

while (0 == Shutdown)
{
    // Do some lovely events
    Application . DoEvents();
    Thread . Sleep (20);

    //… do some other stuff ..

    // Check for a kick from the sound system
    if (0 != AudioTrigger)
    {
        Interlocked . Exchange(ref AudioTrigger, 0);
        …
        ScreenShaker . Screens();
        continue;
    }
    //… more checks for the user idle trigger…
}

Waiting for the user to be idle

The check to see if the user is not doing anything, the main loop uses a helper method called LastInputTime(), which returns the number of milliseconds the user did any input activity. The loop ensures that the user has been idle for long enough, and then calls the method that selects random gremlin actions:

C#

uint LastTime = Win32.LastInputTime();
if ((uint) Environment.TickCount < IdleTimeTrigger + LastTime)
    continue;

The LastInputTime() helper method uses a p/invoke call to the GetLastInputInfo() API call. The wiki at Pinvoke.net provides the signature to the procedure, and a suitable structure that we need to pass to it:

C#

[DllImport("User32.dll")]
static extern bool GetLastInputInfo(ref LASTINPUTINFO LastInfo);

[StructLayout(LayoutKind.Sequential)]
struct LASTINPUTINFO
{
  public uint cbSize;

  /// <summary>
  /// Number of system tickes
  /// </summary>
  public uint dwTime;
}

Then, these two structures are wrapped up into the LastInputTime() helper procedure, which does the dirty work of allocating and initializing a structure.

C#

internal static uint LastInputTime()
{
  LASTINPUTINFO lastInput=new LASTINPUTINFO();
  lastInput.cbSize = (uint)Marshal.SizeOf(lastInput);
  GetLastInputInfo(ref lastInput);
  return lastInput . dwTime;
}

Conclusion

The tricks gremlin plays are intended to be somewhat subtle. There is an aggressive option to make it react more, and move windows around more visibly.

If you want to try this out, the download link for the executable and source code are at the top of the article!

Resources and References

This article is a blatant grab bag of experimental and reused code from earlier experiments and other demo programs. Below are some of the projects I lifted code examples from:

• Pinvoke.net – a wiki-style site with many useful bits of example code related to calling the Windows API from within .NET.
• “.NET Audio Recorder” by Mark Heath, from which I stole code to make the audio trigger.
• “Possessed PC Pranks for Halloween” by Brian Peek, from which I stole the basic code for sending keystrokes.
• “April Fools' Day Application” by Brian Peek, from which I stole code to grab the screen and rotate it.

About The Author

Randall Maas writes firmware for medical devices, and consults in embedded software. Before that he did a lot of other things… like everyone else in the software industry. You can contact him at randym@acm.org.

Q: Thanks for taking the time to speak with us today.  Why don't you tell us a little bit about yourself?

A: I'm surprised I even considered this.  I'm so above you people now.  But anyway, my name is Brian Peek, and until I developed this app, I was working, like you people, at a job that was pointless.  Now, I'm on the cusp of owning people like you.  Once this takes off, I can finally pursue my life's other passion:  hip-hop music.

Q: I don't doubt it.  So why don't you tell us a little bit about TwitterDrive and how you came up with the idea?

A: TwitterDrive is the next “big thing” in cloud storage.  There are a ton of cloud storage providers out there now, most of which cost money or have limited disk space available.  But why should we live with limitations like these?  Twitter provides their users with unlimited storage for sending and saving their “tweets”.  My amazingly brilliant idea was to take this service to the next level:  using it to store and share files.  That is, free cloud storage.  Bet you wish you thought of that.

Q: I sure do.  So how does TwitterDrive work?

A: It works perfectly.  Simply run the TwitterDrive application, provide your Twitter user credentials, and then start uploading and downloading files.  Files are compressed, base64 encoded, and then uploaded to Twitter 140 bytes at a time, fully maximizing the amount of space allowed per tweet.

Imagine…uploading 14 thousand bytes of data per hour!  Or downloading two megabytes per hour!  Match that, SkyDrive.

Q: That sounds amazing.  Unlimited storage for free.

It is amazing.  Which is why I thought of it and you didn't.  Welcome to the future.

Q: So are there any limitations?

Only if you consider uploading 14 thousand bytes per hour a limitation.  But really, who has that much data?  14k should be enough for everybody.

Q: What about data protection?  Is the file data protected in any way?

The data is compressed, encoded and chunked up into bits.  Who needs more security than that?  Besides, users would need to know your TwitterDrive account username to get at the data.  Security through obscurity is a win for everyone!

Q: Do you have any new features planned for TwitterDrive?

New features?  No.  It's already the most complete, useful and bug free application ever developed.  It doesn't require any additional features.

Now if you'll excuse me, I have to start planning which jet I want to buy.

Well there you have it, folks.  We are at the cusp of a revolution.  Are you ready?

Download TwitterDrive here.  Want to learn more?  Learn how it was made!

Introduction

As you've probably guessed by now, TwitterDrive is my April Fool's Day application for Coding4Fun this year.  While the application does actually work, the limitations of Twitter make it functionally useless.  That said, I'll still take you through the important parts as there is some value in the code with regard to the Twitter API, LINQ to XML, threading, and a couple other things.

How It Works

Not very well, actually.  The concept is we take a file, compress it, uuencode/base64 encode it (that is, make a text representation of the binary contents), and then upload it 140 characters at a time to Twitter as status messages.  When the file upload is complete, an index is written of every file that is currently stored on Twitter with some information that can be used to later retrieve the file.

Twitter

Let's start with the Twitter API.  Full documentation on this API can be found at:

http://apiwiki.twitter.com/

TwitterDrive only requires a very small subset of this functionality to work.  We need the ability to post a new status message, download a user timeline, destroy a status, and verify the user's credentials.  All of these things are handled in the TwitterService class.

The heart of this class consists of two methods:  GetTwitter and PostTwitter.  GetTwitter will make a GET request to Twitter of the specified URL, and PostTwitter will make a POST request to Twitter of the specified URL with the supplied data.

C#

private XDocument GetTwitter(string url)
{
    WebClient wc = new WebClient();

    // only authenticate if we have a password
    if(!string.IsNullOrEmpty(Password))
        wc.Credentials = new NetworkCredential(Username, Password);

    Stream s = wc.OpenRead(url);

    // return an XDocument for LINQ
    XmlTextReader xmlReader = new XmlTextReader(s);
    XDocument xdoc = XDocument.Load(xmlReader);
    xmlReader.Close();
    return xdoc;
}

private XDocument PostTwitter(string url, string data)
{
    byte[] bytes = Encoding.ASCII.GetBytes(data);

    HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
    request.Method = "POST";

    // if we're writing, we need to authenticate
    request.Credentials = new NetworkCredential(Username, Password);

    // if this is 'true', Twitter breaks
    request.ServicePoint.Expect100Continue = false;
    request.ContentType = "application/x-www-form-urlencoded";
    request.ContentLength = bytes.Length;

    Stream reqStream = request.GetRequestStream();
    reqStream.Write(bytes, 0, bytes.Length);

    // turn the response into an XDocument for use with LINQ
    HttpWebResponse resp = (HttpWebResponse)request.GetResponse();
    XmlReader xmlReader = XmlReader.Create(resp.GetResponseStream());
    XDocument xdoc = XDocument.Load(xmlReader);
    xmlReader.Close();
    return xdoc;
}

VB

Private Function GetTwitter(ByVal url As String) As XDocument
    Dim wc As New WebClient()

    ' only authenticate if we have a password
    If (Not String.IsNullOrEmpty(Password)) Then
        wc.Credentials = New NetworkCredential(Username, Password)
    End If

    Dim s As Stream = wc.OpenRead(url)

    ' return an XDocument for LINQ
    Dim xmlReader As New XmlTextReader(s)
    Dim xdoc As XDocument = XDocument.Load(xmlReader)
    xmlReader.Close()
    Return xdoc
End Function

Private Function PostTwitter(ByVal url As String, ByVal data As String) As XDocument
    Dim bytes() As Byte = Encoding.ASCII.GetBytes(data)

    Dim request As HttpWebRequest = CType(WebRequest.Create(url), HttpWebRequest)
    request.Method = "POST"

    ' if we're writing, we need to authenticate
    request.Credentials = New NetworkCredential(Username, Password)

    ' if this is 'true', Twitter breaks
    request.ServicePoint.Expect100Continue = False
    request.ContentType = "application/x-www-form-urlencoded"
    request.ContentLength = bytes.Length

    Dim reqStream As Stream = request.GetRequestStream()
    reqStream.Write(bytes, 0, bytes.Length)

    ' turn the response into an XDocument for use with LINQ
    Dim resp As HttpWebResponse = CType(request.GetResponse(), HttpWebResponse)
    Dim xmlReader As XmlReader = XmlReader.Create(resp.GetResponseStream())
    Dim xdoc As XDocument = XDocument.Load(xmlReader)
    xmlReader.Close()
    Return xdoc
End Function

Each of these methods will use the NetworkCredentials object to authenticate to Twitter for reading or writing, as required.  Twitter API methods return simple XML objects.  Both GetTwitter and PostTwitter take these XML documents and turn them into XDocument objects that can be easily queried with LINQ to XML later.

We only need to call two Twitter “get” methods: user_timeline and verify_credentials.  There are two overloaded methods which call the user_timeline API:

C#

public IList<Status> GetUserTimeline(int page, int count)
{
    XDocument xdoc = GetTwitter(string.Format("http://twitter.com/statuses/user_timeline.xml?count={0}&page={1}&id={2}", count, page, Username));
    IList<Status> statuses = ParseStatuses(xdoc);
    return statuses;
}

public IList<Status> GetUserTimeline(int since_id, int max_id, int page, int count)
{
    XDocument xdoc = GetTwitter(string.Format("http://twitter.com/statuses/user_timeline.xml?since_id={0}&max_id={1}&count={2}&page={3}&id={4}", since_id, max_id, count, page, Username));
    IList<Status> statuses = ParseStatuses(xdoc);
    return statuses;
}

VB

Public Function GetUserTimeline(ByVal page As Integer, ByVal count As Integer) As IList(Of Status)
    Dim xdoc As XDocument = GetTwitter(String.Format("http://twitter.com/statuses/user_timeline.xml?count={0}&page={1}&id={2}", count, page, Username))
    Dim statuses As IList(Of Status) = ParseStatuses(xdoc)
    Return statuses
End Function

Public Function GetUserTimeline(ByVal since_id As Integer, ByVal max_id As Integer, ByVal page As Integer, ByVal count As Integer) As IList(Of Status)
    Dim xdoc As XDocument = GetTwitter(String.Format("http://twitter.com/statuses/user_timeline.xml?since_id={0}&max_id={1}&count={2}&page={3}&id={4}", since_id, max_id, count, page, Username))
    Dim statuses As IList(Of Status) = ParseStatuses(xdoc)
    Return statuses
End Function

Each of these methods creates a URL with the appropriate query string arguments (see the Twitter API docs for the full list) and then calls our ParseStatuses method with the returned XDocument, which will give us a List of Status objects. The Twitter-returned status contains a variety of data, such as:

<status>
<created_at>Mon Mar 30 07:20:57 +0000 2009</created_at>
<id>1234567123</id>
<text>Status text</text>
<source>web</source>
<truncated>false</truncated>
<in_reply_to_status_id/>
<in_reply_to_user_id/>
<favorited>false</favorited>

<user>
<id>12345678</id>
<name>Some Person</name>
<screen_name>myscreenname</screen_name>
<description/>
<location/>

<profile_image_url>
http://ecn.channel9.msdn.com/o9/c4fcontent/migration/9525376/default_profile_normal.png
</profile_image_url>
<url/>
<protected>false</protected>
<followers_count>1</followers_count>
</user>
</status>

We only care about a few elements and only parse those, namely id, text, user (which is in itself an XML chunk), and created_at.

C#

private IList<Status> ParseStatuses(XContainer container)
{
    // return a list of Status objects
    var query = from status in container.Descendants("statuses").Descendants("status")
                select ParseStatus(status);
    return query.ToList();
}

private Status ParseStatus(XDocument xdoc)
{
    // create a Status object from the returned XML
    var query = from status in xdoc.Descendants("status")
                select ParseStatus(status);

    return query.SingleOrDefault();
}

private Status ParseStatus(XElement xelement)
{
    Status s = new Status()
                {
                    ID = (int)xelement.Element("id"),
                    Text = (string)xelement.Element("text"),
                    UserInformation = ParseUserInformation(xelement.Element("user")),
                    // HTTP-formatted date
                    CreatedAt = DateTime.ParseExact(xelement.Element("created_at").Value,
                            "ddd MMM dd HH:mm:ss zzzz yyyy",
                            CultureInfo.GetCultureInfoByIetfLanguageTag("en-us"),
                            DateTimeStyles.AllowWhiteSpaces)
                };

    return s;
}

VB

Private Function ParseStatuses(ByVal container As XContainer) As IList(Of Status)
    ' return a list of Status objects
    Dim query = _
        From status In container.Descendants("statuses").Descendants("status") _
        Select ParseStatus(status)
    Return query.ToList()
End Function

Private Function ParseStatus(ByVal xdoc As XDocument) As Status
    ' create a Status object from the returned XML
    Dim query = _
        From status In xdoc.Descendants("status") _
        Select ParseStatus(status)

    Return query.SingleOrDefault()
End Function

Private Function ParseStatus(ByVal xelement As XElement) As Status
    Dim s As New Status() With { _
        .ID = CInt(xelement.Element("id")), _
        .Text = CStr(xelement.Element("text")), _
        .UserInformation = ParseUserInformation(xelement.Element("user")), _
        .CreatedAt = DateTime.ParseExact(xelement.Element("created_at").Value, _
                    "ddd MMM dd HH:mm:ss zzzz yyyy", CultureInfo.GetCultureInfoByIetfLanguageTag("en-us"), DateTimeStyles.AllowWhiteSpaces) }
    Return s
End Function

These methods use LINQ to XML to drill down into the XML document to parse out individual status objects and return them as a list.  You will notice the user element contains a user_information XML chunk, and the ParseUserInformation method parses that data

C#

private UserInformation ParseUserInformation(XContainer container)
{
    // parse and return a UserInformation object
    return new UserInformation
    {
        ID = (int)container.Element("id"),
        Name = (string)container.Element("name"),
        ScreenName = (string)container.Element("screen_name")
    };
}

VB

Private Function ParseUserInformation(ByVal container As XContainer) As UserInformation
    ' parse and return a UserInformation object
    Dim ui As New UserInformation() With { _
        .ID = CInt(container.Element("id")), _
        .Name = CStr(container.Element("name")), _
        .ScreenName = CStr(container.Element("screen_name")) }

    Return ui
End Function

The verify_credentials API is called in a similar manner, but in this case we will “listen” for a 401 (Unauthorized) exception and return true or false appropriately:

C#

public bool VerifyTwitterCredentials(string username, string password)
{
    try
    {
        WebClient wc = new WebClient();
        wc.Credentials = new NetworkCredential(username, password);
        Stream s = wc.OpenRead("http://twitter.com/account/verify_credentials.xml");
        s.Close();
    }
    catch(WebException we)
    {
        if((we.Response as HttpWebResponse).StatusCode == HttpStatusCode.Unauthorized)
            return false;
        throw;
    }

    return true;
}

With the “get” methods out of the way, we can write our “post” methods.  We only need two methods here as well:  update and destroy.  Update is used to write a new tweet to Twitter, and destroy is used to remove an existing tweet.

C#

public Status UpdateStatus(string status)
{
    XDocument doc = PostTwitter("http://twitter.com/statuses/update.xml", "status=" + status);
    Status s =  ParseStatus(doc);

    // if we don't get the text we sent, we hit the rate limit...
    if(s.Text != HttpUtility.UrlDecode(status))
        throw new TwitterRateLimitException("Twitter upload limit reached.");
    return s;
}

public Status Destroy(int status)
{
    XDocument doc = PostTwitter("http://twitter.com/statuses/destroy/" + status + ".xml", "id=" + status);
    return ParseStatus(doc);
}

VB

Public Function VerifyTwitterCredentials(ByVal username As String, ByVal password As String) As Boolean
    Try
        Dim wc As New WebClient()
        wc.Credentials = New NetworkCredential(username, password)
        Dim s As Stream = wc.OpenRead("http://twitter.com/account/verify_credentials.xml")
        s.Close()
    Catch we As WebException
        If (TryCast(we.Response, HttpWebResponse)).StatusCode = HttpStatusCode.Unauthorized Then
            Return False
        End If
        Throw
    End Try

    Return True
End Function

The UpdateStatus method has a bit of code to determine whether we hit Twitter's upload rate limit.  Twitter will limit you to about 100 tweets per hour.  The only way to determine if you've hit the upload limit (that I found at least) is to compare the text from status element returned from the update to the text that was sent.  If the upload limit is hit, the last valid status element will be returned, and therefore the text blocks will not match.  If this happens, we throw our own custom TwitterRateLimitException up the stack for the UI to handle.

TwitterDrive

Now that we can talk to Twitter, the next step is to write the code that uses these methods to store and retrieve our file data.  This code is located in the TwitterDrive class.

One of the goals I had was to make this application thread-happy to provide a responsive UI while files are uploaded and downloaded.  Therefore, this class sets up three events which can be hooked by the UI to receive periodic status information:

C#

public class ChunkEventArgs : EventArgs
{
    public Status Status;
    public int ChunkLength;
    public int Total;

    public ChunkEventArgs(Status status, int length, int total)
    {
        Status = status;
        ChunkLength = length;
        Total = total;
    }
}

...

// event handlers for async file transfer
public event EventHandler<ChunkEventArgs> ChunkUpload;
public event EventHandler<ChunkEventArgs> ChunkDownload;
public event EventHandler<EventArgs> TransferComplete;

VB

Public Class ChunkEventArgs
    Inherits EventArgs
    Public Status As Status
    Public ChunkLength As Integer
    Public Total As Integer

    Public Sub New(ByVal status As Status, ByVal length As Integer, ByVal total As Integer)
        Status = status
        ChunkLength = length
        Me.Total = total
    End Sub
End Class

These events will be called at the appropriate times and provide information to allow the UI to draw a progress bar and other status information.

The UploadFile method does exactly what you think: it uploads the file specified.  The file contents are loaded into memory, compressed, base64 encoded, and finally URL encoded.  Then, this large string is cut into 140 character chunks and sent to Twitter, one chunk at a time.  After each chunk is uploaded, the ChunkUpload event is called.  Finally, when all chunks are uploaded, a new FileEntry object is created, added to the in-memory file index, and that index is finally written to the top of the Twitter status list.

C# 

public void UploadFile(string path)
{
    Status s = null;
    int startID = 0;
    int length = 0;
    int chunkLength = 140;

    // encode the file
    string file = EncodeFile(path);

    // upload the chunks
    for(int i = 0; i < file.Length; i+= chunkLength)
    {
        // get the proper length (i.e. don't get full 140 if we're at the end)
        string chunk = file.Substring(i, Math.Min(chunkLength, file.Length-i));

        // handle the case where we chopped a chunk in the middle of an encoded character
        // in this case, chop off the encoded data and reset the counter
        if(chunk.EndsWith("%2"))
        {
            chunk = chunk.Substring(0, chunk.Length-2);
            i -= 2;
        }

        if(chunk.EndsWith("%"))
        {
            chunk = chunk.Substring(0, chunk.Length-1);
            i -= 1;
        }

        try
        {
            // upload the chunk
            s = _twitter.UpdateStatus(chunk);

            // notify listeners that we uploaded
            if(ChunkUpload != null)
                ChunkUpload(this, new ChunkEventArgs(s, chunk.Length, file.Length));
        }
        catch(TwitterRateLimitException)
        {
            throw new TwitterDriveException("Twitter upload limit reached.  Please try again later.");
        }

        if(i == 0)
            startID = s.ID;

        length++;
    }

    // create a new FileEntry for this file
    FileEntry fe = new FileEntry()
    {
        Filename = Path.GetFileName(path),
        StartStatus = startID,
        EndStatus = s.ID,
        Length = length,
        FileIndex = GetNextIndex()
    };

    // update the index
    UpdateFileIndex(fe);

    // notify we're done
    if(TransferComplete != null)
        TransferComplete(this, null);
}

VB

Public Function UploadFile(ByVal filepath As String)
    Dim s As Status = Nothing
    Dim startID As Integer = 0
    Dim length As Integer = 0
    Dim chunkLength As Integer = 140

    ' encode the file
    Dim file As String = EncodeFile(filepath)

    ' upload the chunks
    For i As Integer = 0 To file.Length - 1 Step chunkLength
        ' get the proper length (i.e. don't get full 140 if we're at the end)
        Dim chunk As String = file.Substring(i, Math.Min(chunkLength, file.Length-i))

        ' handle the case where we chopped a chunk in the middle of an encoded character
        ' in this case, chop off the encoded data and reset the counter
        If chunk.EndsWith("%2") Then
            chunk = chunk.Substring(0, chunk.Length-2)
            i -= 2
        End If

        If chunk.EndsWith("%") Then
            chunk = chunk.Substring(0, chunk.Length-1)
            i -= 1
        End If

        Try
            ' upload the chunk
            s = _twitter.UpdateStatus(chunk)

            ' notify listeners that we uploaded
            RaiseEvent ChunkUpload(Me, New ChunkEventArgs(s, chunk.Length, file.Length))
        Catch e1 As TwitterRateLimitException
            Throw New TwitterDriveException("Twitter upload limit reached.  Please try again later.")
        End Try

        If i = 0 Then
            startID = s.ID
        End If

        length += 1
    Next i

    ' create a new FileEntry for this file
    Dim fe As New FileEntry() With {.Filename = Path.GetFileName(filepath), .StartStatus = startID, .EndStatus = s.ID, .Length = length, .FileIndex = GetNextIndex()}

    ' update the index
    UpdateFileIndex(fe)

    ' notify we're done
    RaiseEvent TransferComplete(Me, Nothing)
End Function

Let's take a closer look at the EncodeFile method:

C#

private string EncodeFile(string path)
{
    // load the file
    byte[] buff = File.ReadAllBytes(path);

    // compress
    MemoryStream ms = new MemoryStream();
    GZipStream gs = new GZipStream(ms, CompressionMode.Compress);
    gs.Write(buff, 0, buff.Length);
    gs.Close();

    byte[] buffCompressed = ms.ToArray();

    // base64, urlencode
    return HttpUtility.UrlEncode(Convert.ToBase64String(buffCompressed));
}

VB

Private Function EncodeFile(ByVal path As String) As String
    ' load the file
    Dim buff() As Byte = File.ReadAllBytes(path)

    ' compress
    Dim ms As New MemoryStream()
    Dim gs As New GZipStream(ms, CompressionMode.Compress)
    gs.Write(buff, 0, buff.Length)
    gs.Close()

    Dim buffCompressed() As Byte = ms.ToArray()

    ' base64, urlencode
    Return HttpUtility.UrlEncode(Convert.ToBase64String(buffCompressed))
End Function

The code here reads the bytes of a file into a byte array.  Then, a MemoryStream object is created and tied to a GZipStream (compression) object.  Next, the byte array is written to the stream which will compress the data on the fly.  Once the stream is closed, calling ToArray on the MemoryStream will return a byte array of the compressed data.  The byte array is base64 encoded (turned into text) and finally URL encoded so it can be sent to Twitter.

The file index is written at the end of each file upload.  The index is comprised of a delimited string which contains the data in the FileEntry object.  Each file is uploaded as one tweet, with an end marker to denote where the file index ends.

C#

private void WriteFileEntries()
{
    // write an end marker (write this first since they come out in reverse order later)
    _twitter.UpdateStatus(FileEntryEnd);

    for(int i = 0; i < _fileEntries.Count; i++)
        WriteFileEntry(_fileEntries[i]);
}

private void WriteFileEntry(FileEntry fe)
{
    // simple delimited list of data
    string entry = string.Format(FileEntryHeader +
                                "{0}" + FileEntrySeparator + 
                                "{1}" + FileEntrySeparator +
                                "{2}" + FileEntrySeparator +
                                "{3}" + FileEntrySeparator +
                                "{4}", 
                                fe.Filename, fe.StartStatus, fe.EndStatus, fe.Length, fe.FileIndex);
    _twitter.UpdateStatus(entry);
}

VB

Private Sub WriteFileEntries()
    ' write an end marker (write this first since they come out in reverse order later)
    _twitter.UpdateStatus(FileEntryEnd)

    Dim i As Integer = 0
    Do While i < _fileEntries.Count
        WriteFileEntry(_fileEntries(i))
        i += 1
    Loop
End Sub

Private Sub WriteFileEntry(ByVal fe As FileEntry)
    ' simple delimited list of data
    Dim entry As String = String.Format(FileEntryHeader & "{0}" & FileEntrySeparator & "{1}" & FileEntrySeparator & "{2}" & FileEntrySeparator & "{3}" & FileEntrySeparator & "{4}", fe.Filename, fe.StartStatus, fe.EndStatus, fe.Length, fe.FileIndex)
    _twitter.UpdateStatus(entry)
End Sub

A file list can be retrieved and parsed out with the following code:

C#

public IList<FileEntry> GetFileIndex()
{
    bool end = false;
    int page = 1;

    // the index should be the last things tweeted, but if we have a failed upload, it may not be
    while(!end && page < 5)
    {
        IList<Status> indexes = _twitter.GetUserTimeline(page, 200);

        _fileEntries.Clear();

        // parase out the file entries
        foreach(Status index in indexes)
        {
            FileEntry fe = ParseFileIndexString(index.Text);
            if(fe != null)
            {
                fe.IndexStatusId = index.ID;
                _fileEntries.Add(fe);
            }

            if(index.Text.StartsWith(FileEntryEnd))
            {
                end = true;
                break;
            }
        }
        page++;
    }
    return _fileEntries;
}

private FileEntry ParseFileIndexString(string index)
{
    if(!index.StartsWith(FileEntryHeader))
        return null;

    string[] fileEntry = index.Split(Convert.ToChar(FileEntrySeparator));
    FileEntry fe = new FileEntry()
                    {
                        Filename = fileEntry[0].Replace(FileEntryHeader, string.Empty),
                        StartStatus = int.Parse(fileEntry[1]),
                        EndStatus = int.Parse(fileEntry[2]),
                        Length = int.Parse(fileEntry[3]),
                        FileIndex = int.Parse(fileEntry[4])
                    };
    return fe;
}

VB

Public Function GetFileIndex() As IList(Of FileEntry)
    Dim [end] As Boolean = False
    Dim page As Integer = 1

    ' the index should be the last things tweeted, but if we have a failed upload, it may not be
    Do While (Not [end]) AndAlso page < 5
        Dim indexes As IList(Of Status) = _twitter.GetUserTimeline(page, 200)

        _fileEntries.Clear()

        ' parase out the file entries
        For Each index As Status In indexes
            Dim fe As FileEntry = ParseFileIndexString(index.Text)
            If fe IsNot Nothing Then
                fe.IndexStatusId = index.ID
                _fileEntries.Add(fe)
            End If

            If index.Text.StartsWith(FileEntryEnd) Then
                [end] = True
                Exit For
            End If
        Next index
        page += 1
    Loop
    Return _fileEntries
End Function

Private Function ParseFileIndexString(ByVal index As String) As FileEntry
    If (Not index.StartsWith(FileEntryHeader)) Then
        Return Nothing
    End If

    Dim fileEntry() As String = index.Split(Convert.ToChar(FileEntrySeparator))
    Dim fe As New FileEntry() With {.Filename = fileEntry(0).Replace(FileEntryHeader, String.Empty), .StartStatus = Integer.Parse(fileEntry(1)), .EndStatus = Integer.Parse(fileEntry(2)), .Length = Integer.Parse(fileEntry(3)), .FileIndex = Integer.Parse(fileEntry(4))}
    Return fe
End Function

This code will retrieve the user's timeline, loop through the tweets, looking for file index entries (those that start with the proper delimiter).  When one is found, the data is parsed back into a FileEntry object and added to the in-memory cache.  You will note that the GetFileIndex method will read up to 1000 tweets looking for the end marker before giving up.

Now that we can upload files and build the index, we need to be able to download, decode and save a file.  This is done in the obviously named DownloadFile method:

C#

public void DownloadFile(FileEntry fe, string path)
{
    StringBuilder sb = new StringBuilder(fe.Length * 140);

    // get statuses for this user starting/ending at the IDs for this file
    IList<Status> chunks = _twitter.GetUserTimeline(fe.StartStatus-1, fe.EndStatus, 1, 200);

    // order them from oldest to newest
    var orderedChunks = from chunk in chunks
                        orderby chunk.ID ascending
                        select chunk;

    foreach(Status chunk in orderedChunks)
    {
        // trim off any extra characters
        string newChunk = chunk.Text.TrimEnd('.').Trim();
        sb.Append(newChunk);

        // notify listeners that we downloaded a chunk
        if(ChunkDownload != null)
            ChunkDownload(this, new ChunkEventArgs(chunk, newChunk.Length, fe.Length * 140));
    }

    // decode and write the file
    byte[] buff = DecodeFile(sb.ToString());
    File.WriteAllBytes(Path.Combine(path, fe.Filename), buff);

    // notify that we're done
    if(TransferComplete != null)
        TransferComplete(this, null);
}

 VB

Public Function DownloadFile(ByVal fe As FileEntry, ByVal filepath As String)
    Dim sb As New StringBuilder(fe.Length * 140)

    ' get statuses for this user starting/ending at the IDs for this file
    Dim chunks As IList(Of Status) = _twitter.GetUserTimeline(fe.StartStatus-1, fe.EndStatus, 1, 200)

    ' order them from oldest to newest
    Dim orderedChunks = _
        From chunk In chunks _
        Order By chunk.ID Ascending _
        Select chunk

    For Each chunk As Status In orderedChunks
        ' trim off any extra characters
        Dim newChunk As String = chunk.Text.TrimEnd("."c).Trim()
        sb.Append(newChunk)

        ' notify listeners that we downloaded a chunk
        RaiseEvent ChunkDownload(Me, New ChunkEventArgs(chunk, newChunk.Length, fe.Length * 140))
    Next chunk

    ' decode and write the file
    Dim buff() As Byte = DecodeFile(sb.ToString())
    File.WriteAllBytes(Path.Combine(filepath, fe.Filename), buff)

    ' notify that we're done
    RaiseEvent TransferComplete(Me, Nothing)
End Function

This method returns the user's timeline starting and ending at the tweets specified in the FileEntry object.  The status list is ordered in ascending order (i.e. oldest to newest).  Each status is appended to the previous using a StringBuilder object.  When all chunks are processed, the file is decoded and saved to the chosen location.

C#

public byte[] DecodeFile(string data)
{
    // base64 to binary
    byte[] buff = Convert.FromBase64String(data);

    // decompress
    MemoryStream ms = new MemoryStream(buff);
    GZipStream gs = new GZipStream(ms, CompressionMode.Decompress, false);

    // original
    byte[] decompressed = ReadAllBytes(gs);
    return decompressed;
}

VB

Public Function DecodeFile(ByVal data As String) As Byte()
    ' base64 to binary
    Dim buff() As Byte = Convert.FromBase64String(data)

    ' decompress
    Dim ms As New MemoryStream(buff)
    Dim gs As New GZipStream(ms, CompressionMode.Decompress, False)

    ' original
    Dim decompressed() As Byte = ReadAllBytes(gs)
    Return decompressed
End Function

To decode the file, we do the opposite of what we did before: the file is converted to bytes from the base64 encoded string, a GZipStream is used to decompress the data, and the final, uncompressed file contents are returned to the caller to be saved to the disk.

Be sure to look through the entire TwitterDrive.cs/vb file for the full picture, but these are the important parts.

User Interface

The final piece is the user interface.

A very simple UI for uploading, downloading and deleting files.  At the start of the application, the three TwitterDrive events are hooked: ChunkUpload, ChunkDownload, and TransferComplete.  These three event handlers are used to update the progress bar on a dialog box that pops up during the file transfer.

When upload or download is selected, the file is selected, and a new thread is created to start the actual process.  Here is what the download process looks like:

C#

// start a new thread to grab the file
Thread t = new Thread(() => _twitterDrive.DownloadFile(fe, fbd.SelectedPath));
t.Start();

if(_progress.ShowDialog() == DialogResult.Cancel)
    t.Abort();
else
    MessageBox.Show("File download complete.", "TwitterDrive", MessageBoxButtons.OK, MessageBoxIcon.Information);

VB

' start a new thread to grab the file
Dim t As New Thread(CType(Function() _twitterDrive.DownloadFile(fe, fbd.SelectedPath), ThreadStart))
t.Start()

If _progress.ShowDialog() = System.Windows.Forms.DialogResult.Cancel Then
    t.Abort()
Else
    MessageBox.Show("File download complete.", "TwitterDrive", MessageBoxButtons.OK, MessageBoxIcon.Information)
End If

A new thread is created, whose ThreadStart parameter is the DownloadFile method of the TwitterDrive class.  The thread is started, and the progress dialog box is shown.  If the progress box is cancelled, the thread is aborted, otherwise the dialog box is closed in response to the TransferComplete event sent by the TwitterDrive class.

Using the Application

1. Create a new Twitter account for use in TwitterDrive.
2. Enter the credentials for this new account in the provided textboxes and click Refresh.  Or, if you want to download files from someone else, enter just the username and click Refresh.
3. Upload and download data at will.

Conclusion

And there we have it.  A functionally useless application that actually works.  Give it a try and find out what the limitations are.  Just be sure to use a Twitter account that isn't your main feed otherwise you'll have some pretty angry followers.

Thanks

A special thanks to Mark Zaugg, Dan Fernandez, and Giovanni Montrone for helping me test this application.  Giovanni is also partly responsible for this horrible idea after joking that I should Twitter him a file.  So blame him.

Also thanks to Clint Rutkas for throwing together the icon (it's a combo of the SkyDrive icon + the Twitter icon).

Bio

Brian is a Microsoft C# MVP who has been actively developing in .NET since its early betas in 2000, and who has been developing solutions using Microsoft technologies and platforms for even longer. Along with .NET, Brian is particularly skilled in the languages of C, C++ and assembly language for a variety of CPUs. He is also well-versed in a wide variety of technologies including web development, document imaging, GIS, graphics, game development, and hardware interfacing. Brian has a strong background in developing applications for the health-care industry, as well as developing solutions for portable devices, such as tablet PCs and PDAs. Additionally, Brian has co-authored the book "Coding4Fun: 10 .NET Programming Projects for Wiimote, YouTube, World of Warcraft, and More" published O'Reilly. He previously co-authored the book "Debugging ASP.NET" published by New Riders.  Brian is also an author for MSDN's Coding4Fun website.

The Micro Framework is one of the newest kids on the .NET block, but it does something really rather wonderful. It brings embedded development within the reach of any C# programmer. If you know C# and love Visual Studio, you can now get started building hardware and controlling it with your software. Moreover, it lets developers achieve one of their most cherished dreams, to control their festive lights using programs that they have written. This project shows you how to do just that and adds an extra magical feature, in that you can make all your festive lights flash red whenever I, Rob Miles, make a new post on that most famous of blogs, www.robmiles.com.

Actually, you can modify the code so that you can make your lights do most anything in response to an event that happens on the web. You could signal home that you are running late, send the weather forecast to your Christmas tree or explore any number of communication options. You might decide that this is so useful that you leave your decorations up all year round.

If you just want to play with the .NET Micro Framework and get a feel for how easy it is to create software for tiny devices you don't actually need to use any extra hardware at all. The project comes with a complete emulation of the lights display so that you can run the whole thing on your computer and learn how hardware and software can be made to work together without burning your fingers with a soldering iron.

However building the hardware will give you an understanding of how some simple electronic components can be controlled from C# and even how serial and parallel data transfer works. It is also great fun.

To get started you will need some hardware and some software. Let's take each in turn.

Hardware

Processor Hardware

The .NET Micro Framework lets you run C# programs on tiny embedded devices. There are a number of these available today, and they are getting progressively cheaper. You can base this project on any.NET Micro Framework device that has a network port and three or more output ports. The ones I'd recommend are:

• Digi Connect-ME: http://www.digi.com/products/embeddedsolutions/digiconnectme.jsp
• GHI Electronics Embedded Master: http://www.ghielectronics.com/embeddedmaster.php
• Devices Solutions Tahoe II: http://devicesolutions.net/Products/Tahoe.aspx

I built the project for Digi Connect board but the code can be customised for any of the above platforms. The beauty of the .NET Micro Framework is that you hardly need to change your program even if the underlying hardware is completely replaced. The only thing you will have to do is adjust the code to target different output pins. I'll flag this part of the program up when we get to it.

The project as supplied runs on a special emulator that runs on the PC and behaves like a .NET Micro Framework device with lights connected, so you can get started exploring the code right away.

Lights

I'm keeping things deliberately low voltage for this project. This means that kids of all ages can have a go at building the hardware without messing around with mains. The lights that I used were supplied as lines of twenty leds wired up as four strands of five leds each. All the leds in each strand were the same colour. The lights were fitted with a little battery box which held three AA batteries and a tiny controller. To get my display I simply removed the battery box and connected the strands to my hardware.

 
Figure 1: My Battery Powered Lights

You can do the same with any low power lighting kit that you wish to use. The drivers that I'm using can handle around 500 milliamps of continuous current and so you can connect a fair number of lights to each strand.

Buying the Lights

The lights I used can be bought in the UK from Lights4Fun: www.lights4fun.co.uk and are called "C-LED-4.5-M 20 Multi Coloured Battery Operated LED Fairy Lights". They are supplied with a battery box and controller that you can remove to connect to the Darlington drivers. I used an old 5 volt mobile phone charger to power the lights. If you search eBay for "led christmas lights battery" you should find plenty of suppliers.

Driver Hardware

We can't connect a .NET Micro Framework device directly to our lights. There are two reasons for this:

1. The Micro Framework device will not be able to switch the amount of current that we need to drive the lights themselves.
2. The Micro Framework device will not have enough outputs to control all the lights that we want to use.

This means that we need to make some hardware that goes between the processor and our lights. I actually don't see this as a problem. Making hardware is great fun, seeing something that you've built spring into life is very nice. The hardware we are going to use will provide a means by which we can control many hundreds of lights from a single Micro Framework board if we wish. It also has the ability to switch reasonable amounts of current, so you can use quite large numbers of lights if you wish. We are going to use two semiconductor components, a CD4094 Shift Register/Latch and a ULN2803 Octal Darlington Driver. A pair of these chips will allow us to control 8 outputs. If you want to control more outputs you simply get more chips and chain them together. For my version of the project I just used one of each chip, you can use as many as you like.The shift registers and Darlington amplifiers can be obtained in the UK from Maplin: www.maplin.co.uk. The chip numbers and part numbers as are as follows: QW54J 4094 Shift Register, QY79L ULN2803A Darlington Driver. In the US you can obtain the components and breadboard from Digi-Key: www.digikey.com.

Serial and Parallel Data

You might be wondering how we can use just three output lines to control lots of lights. We are going to do this by using the three output lines to provide a serial data stream which is converted by our hardware into parallel data that can be used to control our lights. This is a fundamental principle of digital electronics and is how, amongst many other things, computer networks transfer data.

We are going to use three signals which are called clock, data and latch. Each of these can be set high (a voltage is present) or low (no voltage is present) by the .NET Micro Framework device under the control of our software. The signals are connected to the clock, data and latch inputs of our CD4094 shift register so that the program can talk to it.

The clock line triggers the shift register to do two things:

1. Shift all the bits along to make room.
2. Sample the value of the data input and store this value in the space that was created.

To get a feel for how this works, take a look at Figure 2 below. It shows a shift register with a pattern of bits in it. The pattern is 01100001. Note that although this represents a number; it can also be regarded as a pattern of 0s and 1s in the shift register itself. The value 0 means 0 volts and the value 1 means some volts. These are the signals that will be used to control our lights. I'm going to call them 0 and 1 from now on. The Shift Register has Clock, Data and Latch signals connected and they are all set to 1. We can ignore the latch part of the chip for now.

Figure 2: A shift register and latch with some data in it

When the clock signal changes from 1 to 0 this causes the shift register to perform the two steps described above. First the data is shifted along to the right. Note that this means that there is an "empty" location at the start of the register, and that the right most bit in the register "falls off" the register and disappears. Figure 3 shows how this works.

Figure 3: Shifting along the values in the shift register

Once the shift has finished the shift register can copy the data signal into the empty bit at the left as shown in Figure 4 below.

Figure 4: Storing the new data bit

By repeating this process 8 times a program can load a new pattern of 8 bits into the shift register. Then it is time to latch the new value to control the lights. This is the point at which the lights will appear to change. When the latch value is changed from 0 to 1 this causes the chip to copy the value in the Shift Register into the latch, as shown in Figure 5 below.

Figure 5: Copying the shift register pattern into the latch.

The latch is required so that the lights will not flicker as the new patterns are shifted into position. Each of the bits in the latch is connected to an output pin on the CD4094 which is used to switch a particular light colour on or off.

We need to create some C# that will provide the appropriate sequence of signals. It turns out that using the .NET Micro Framework to achieve this is actually very easy. The displayByte method below sends an 8 bit value into a shift register and then latches it into the output. If you read through the code you can see how the clock, data and latch values are all set to true (high) or false (low) to first clock the data out and then trigger the latch to display the pattern on the lights. The input is an 8 bit byte value and the program uses a mask to pick out the value of each bit in turn and set the data output accordingly.

private static void displayByte(byte value)
{
    latchPort.Write(false);
    clockPort.Write(false);

    byte mask = 1;

    for (int i = 0; i < 8; i++)
    {
        if ((value & mask) > 0)
        {
            dataPort.Write(true);
        }
        else
        {
            dataPort.Write(false);
        }
        clockPort.Write(true);
        clockPort.Write(false);
        mask <<= 1;
    }
    latchPort.Write(true);
    latchPort.Write(false);
}

The dataPort, clockPort and latchPort variables are instances of the .NET Micro Framework class OutputPort, which provides a method called Write which can be used to control the state of the output signal. We will consider how these are created a little later in the article.

The sample code for this project comes with a software emulator of the CD4094 which shows how it works. Figure 6 below shows that a new pattern is in the process of being shifted into the shift register, while the lights retain the previous one in the latch. The Clock and Data signals are high and the next statement will drop the Clock signal to add the next bit into the new pattern.

Figure 6: The light emulator

This figure also shows that I have two bits in the pattern controlling a strand of each colour. You can single step through the displayByte method above and watch it perform this output.

You can use this technique every time you want to control a large number of outputs using a small number of output pins. The CD4094 has "daisy chain" inputs and outputs so that the devices can be connected in sequence. If I used two devices I could control 16 bits, with three I could control 24 and so on. This would require only minimal changes to the software.

Output Driver

The CD4094 device will produce a signal output, but it is not really powerful enough to drive things like lights. To do this we need an amplifier and the ULN2803 Octal Darlington Driver is perfect for this. It is packaged as a single chip which contains 8 pairs of transistors. Each transistor pair is wired in a "Darlington" configuration and can be used as a switch which is controlled by on output from the CD4094. When the transistors are turned on they allow current to pass through them and this will cause the lamps to light. The lights that I bought used a "pull down" arrangement to make them light up. All of the light emitting diode (LED) lamps had one end wired to a common line that was connected to the positive supply. To make the a chain of LEDs light the other end that controls that chain needed to be pulled down to the ground level. This is a common arrangement with lights like these. The ULN2803 driver has the transistors wired in an arrangement that allows it to pull signals low in this way. Figure 7 shows how this arrangement works. The resistor shown is actually wired into each LED in the set of lights that I used.

Figure 7: Lighting the LEDs

Complete Circuit

The complete circuit shown in Figure 8 simply links each output of the CD4094 shift register to an input on the ULN2803 Darlington Driver. Note that there is no reason to link any particular bit with any other, the diagram shown is one which will translate most easily to a prototype "breadboard".

Figure 8: The Complete Circuit

The diagram just shows four lights connected to OUT1 from pin 18 of the ULN2803, the other 7 channels are connected in exactly the same way. Some of the pins can be left unconnected. Pins 9 and 10 of the CD4094 are only required if you are connecting multiple shift registers together and the common connection on pin 10 of the ULN2803 is not required. The Latch, Data and Clock signals on the CD4094 are connected to the output signals from the Micro Framework device.

Figure 9 shows the completed circuit built up on a prototype breadboard. The chip on the left is the CD4094 and the one on the right is the ULN2803.

Figure 9: The Completed Circuit

The red wires carry the positive voltage from the power supply, which is connected to the top left of the circuit. The green wires are ground. Other coloured wires are used for signals. The Clock, Latch and Data signals are brought out to a connector which will fit a Digi-ME prototyping board.

Selecting Lights

Each bit in the value sent to the displayByte method and then into the shift register will be mapped to a particular chain of lights. The mapping of these is not particularly important, since you can use program constants to represent particular values. I wired the red signals to output pins 4 and 8. To light up just the red lights I used the value 0x88 which is the appropriate bit pattern. I then set up constants for all the other colors:

const byte GREEN = 0x11;
const byte BLUE = 0x22;
const byte YELLOW = 0x44;
const byte RED = 0x88;

Setting Up the Hardware

The .NET Micro Framework provides a set of classes that can be used to represent the hardware in a system. The program uses instances of the OutputPort class to represent the output pins. These are created in the method that sets up the hardware:

const Cpu.Pin clockPin = Cpu.Pin.GPIO_Pin0;
const Cpu.Pin dataPin = Cpu.Pin.GPIO_Pin1;
const Cpu.Pin latchPin = Cpu.Pin.GPIO_Pin2;

static OutputPort clockPort;
static OutputPort dataPort;
static OutputPort latchPort;

private static void setupOutputs()
{
    clockPort = new OutputPort(clockPin, false);
    dataPort = new OutputPort(dataPin, false);
    latchPort = new OutputPort(latchPin, false);
}

In this version of the hardware I have connected pin 0 of the processor to the clock, pin 1 to the data and pin 2 to the latch. If you use different pins you can change the settings above.

Software

Now that we have working hardware we can consider how the software is to work. Note that this version of the program works correctly but lacks exception handlers that would make it truly robust. I've left these out to simplify the explanation. To make sense of this description you will need to have a copy of the program itself available for reference.

You can develop the code using Visual Studio 2008 Express edition, which you can download from http://www.microsoft.com/express/

The software is written for the .NET Micro Framework 3.0 which you can download from http://www.microsoft.com/downloads/details.aspx?FamilyID=9356ed6f-f1f0-43ef-b21a-4644dd089b4a&displaylang=en

Reading the Blog

The program reads the RSS feed from a blog and looks for the <pubDate> value. This contains the date when the feed was last updated. Whenever this date changes the lights must flash red for a few seconds before resuming a random display. Users of the full .NET Framework can use the HTTPRequest class to build a GET command to be sent to a server. Unfortunately the .NET Micro Framework does not support this, so we have to access the web feed using socket based communication. This part of the program is heavily based on the SocketClient example supplied with the .NET Micro Framework.

// This method requests a page from the specified server.
private static String GetWebPage(String server, string webPage)
{
    const Int32 c_httpPort = 80;
    const Int32 c_microsecondsPerSecond = 1000000;

    // Create a socket connection to the specified server and port.
    using (Socket serverSocket = ConnectSocket(server, c_httpPort))
    {
        // Send request to the server.
        String request = "GET "+ webPage + 
             " HTTP/1.1\r\nHost: " + server + 
             "\r\nConnection: Close\r\n\r\n";
        Byte[] bytesToSend = Encoding.UTF8.GetBytes(request);
        serverSocket.Send(bytesToSend, bytesToSend.Length, 0);

        // Allocate a buffer to receive HTML chunks
        Byte[] buffer = new Byte[1024];

        // 'page' refers to the HTML data as it is built up.
        String page = String.Empty; 

        // Wait up to 30 seconds for initial data 
        // Will throw exception if connection closed
        DateTime timeoutAt = DateTime.Now.AddSeconds(30);
        while (serverSocket.Available == 0 && 
               DateTime.Now < timeoutAt)
        {
            System.Threading.Thread.Sleep(100);
        }

        // Poll for data until 30 second time out
        // Returns true for data and connection closed
        while (serverSocket.Poll(30 * c_microsecondsPerSecond,
                                 SelectMode.SelectRead))
        {
            // Zero all bytes in the re-usable buffer
            Array.Clear(buffer, 0, buffer.Length);

            // Read a buffer-sized HTML chunk
            Int32 bytesRead = serverSocket.Receive(buffer);

            // If 0 bytes in buffer, then connection is closed, 
            // or we have timed out
            if (bytesRead == 0)
                break;

            // Append the chunk to the string
            page += new String(Encoding.UTF8.GetChars(buffer));
        }

        return page;   // Return the complete string
    }
}

This method is called to fetch the journal RSS feed from my blog:

string address = "www.robmiles.com";
string name = "/journal/rss.xml";

string html = GetWebPage(address, name);

You can use it to download from any RSS feed or page on the web. It will throw an exception if the page cannot be read. This version of my program does not perform exception handling however.

Getting the Published Date

The date is held in the form:

<pubDate>Wed, 05 Nov 2008 22:38:52 +0000</pubDate>

It would be enough just to record this content and check for changes in the text, but I decided that I might want to use the date information in a later version of the program and so I created some small helper methods to read numbers from the input string and a larger method to read the publish date itself:

private static DateTime getRecentPubDate(string html, string startTag)
{
    int index = html.IndexOf(startTag) ;

    if (index < 0) 
        throw new Exception("Missing tag " + startTag);

    index += startTag.Length;

    // spin past the name of the day
    while (index < html.Length && html[index] != ',') index++;
    if (index == html.Length) 
        throw new Exception("Short publish date");

    int dayValue = getInt(html, ref index, ' ');

    string monthName = getString(html, ref index, ' ');
    int monthValue = getMonth(monthName);

    int yearValue = getInt(html, ref index, ' ');
    int hourValue = getInt(html, ref index, ':');
    int minuteValue = getInt(html, ref index, ':');
    int secondValue = getInt(html, ref index, ' ');

    return new DateTime(yearValue, monthValue, dayValue, 
                        hourValue, minuteValue, secondValue);
}

The main body of the program uses this method to extract the date out of the RSS feed. When a new date is found it is time to update the lights.

Lights and Threads

My first version of the program flashed the lights for a while and then checked to see if a new blog post had been made. This worked OK, but the process of loading the RSS feed from the server and checking the dates can take a few seconds, which meant that the flashing lights would freeze every now and then. This did not look very good, and so I decided to use two threads instead. One is in charge of flashing the lights in a random pattern and the other loads the RSS feed from my blog and checks the date of the most recent publication.

Note that the threading I am using is exactly the same as threading in the full .NET Framework.

Thread Communication

The two threads communicate by means of a single boolean variable which is set to true when the blog alert is to take place. The display thread reads this flag and flashes the lights red if it is time to alert.

public static bool alert = false;

public static void flasher()
{
    setupOutputs();

    while (true)
    {
        randomDisplay(400, 10);
        if (alert)
        {
            alert = false;
            flashRed(600, 20);
        }
    }
}

The methods randomDisplay and flashRed do exactly what you would expect. Each of them gets two numbers to control the lights. The first number gives the delay in milliseconds between flashes (a few hundred milliseconds giving best results). The second gives the number of times that the lights should be flashed before the method finishes. RandomDisplay displays random colors, whereas flashRed is simply flashes the red lights. The alert flag is cleared before the red lights are flashed so that the system will resume normal display after the alert.

The second thread in the system performs the blog download and date test behaviour. This all happens inside the Main method:

public static void Main()
{
    flashThread = new System.Threading.Thread(flasher);

    flashThread.Start();

    string address = "www.robmiles.com";
    string name = "/journal/rss.xml";

    String html = GetWebPage(address, name);

    DateTime lastUpdate = getRecentPubDate(html, "<pubDate>");

    Debug.Print("Initial Update Value : " + lastUpdate.ToString());

    while (true)
    {
        System.Threading.Thread.Sleep(10000);

        html = GetWebPage(address, name);

        DateTime blogUpdate = getRecentPubDate(html, "<pubDate>");

        if (!blogUpdate.Equals(lastUpdate))
        {
            Debug.Print("Updated at : " + blogUpdate.ToString());
            lastUpdate = blogUpdate;
            alert = true;
        }
    }
}

To reduce the load on the network the system only checks the blog feed every 10 seconds.

Future Work

The program itself works fine, but the error handling is not wonderful. Although some of the methods used throw exceptions these are not caught anywhere, causing the blog reading thread to terminate. This does not stop the lights flashing, but it does mean that there will be no more alerts. However, it is not too hard to create a version which contains proper error handling and even flashes the lights different colors to indicate the alarm conditions. I have created a version that flashes the lights yellow every now and then if the network connection fails. There is also considerable scope for reading other web based sources and changing the output accordingly. Feel free to do all these things and make sure that you have fun.

Thanks

Thanks go to Ian Mitchell of Ormston Technology (http://www.ormtec.co.uk/) for doing such a great job of hardware design and build.

Welcome to version 2.0 of the software and article!  I have rewritten the key points of this article to address the new features in the latest version of the software.  Read on for a full explanation...

New Features for 2.0

• MIDI support
  • Load a MIDI file and a sequence will be automatically created based on the data contained in the file.  You can automatically create your own show with barely any effort at all!
• Playlists
  • Load up several sequences and have them play in order to create a multi-song show!
• More accurate timing
  • The timing algorithm used in the last version was very imprecise...it worked, but it wasn't perfect.  The new version uses a method which gives millisecond precision timing
• Cut/Copy/Paste
  • One can now cut/copy/paste cells on the grid...makes it easy to repeat chunks of sequences without having to tap out the rhythm by hand over and over again
• Edit existing sequences
  • After loading a sequence created by someone else (or yourself), you can now re-assign Phidget boards, serial numbers, output ports, etc. to get them to run on your setup.

Note that any sequences created with the old version will continue to play just fine, but editing them could be troublesome due to the new timing method.

And now back to the article with updates.  The hardware section remains the same, but the software discussion below is updated with new information.

I'm sure by now everyone with a computer has seen the videos of holiday light shows timed to holiday music such as this one.  For this holiday season, I decided to create my own indoor show using some off-the-shelf components and .NET.

WARNING:  The hardware portion of this project uses standard 120V AC current.  As you are likely aware, this is enough voltage to seriously hurt or kill you.  Please be careful and follow the instructions closely.

What You Will Need

• Phidget Interface Kit 0/0/4 – a USB-controlled board with 4 relays.  I used 2 kits for a total of 8 channels.  Any number can be used.
• 5 6' (or longer/shorter for your needs) indoor or outdoor 2-prong extension cords for each Phidget board used.  I was able to find these at the local home improvement store for about $1 each.  If you will be creating an outdoor show, be sure to purchase extension cords that are meant for outdoor use.

• Some 14-16 gauge wire.  If in doubt, simply buy one additional extension cord to use for the additional wire.
• 2 wire nuts that can handle the wire gauge selected above for each Phidget board used.

• A project box large enough to hold one or many Phidget boards and associated wiring.  I chose a 7"L x 5"W x 3"H enclosure from Radio Shack which provides ample room to hold 2 Phidget Interface Kits and wiring.
• Some holiday lights
• External speakers (or possibly an FM transmitter for an outdoor show)
• Phidgets .NET libraries
• Microsoft Visual Basic or Visual C# Express Editions

Building the Hardware

The hardware we are going to build will allow for one Phidget board to be plugged into a single AC outlet and provide 4 output outlets that can be switched off and on by the Phidget board's relays.  By building two of these and placing them in a project box, I have a neat and tidy control box with 2 USB inputs, 2 AC male plugs for the wall, and 8 AC female plugs for my lights.  The following description will be for building a single unit.

Let's start by preparing the extension cords.  Cut the female end off of one extension cord.  Split the cord up the center and strip the insulation off each of the wires to expose the ends.  Twist the ends with your fingers to create a neat, twisted wire as shown:

Next, take the remaining four extension cords and cut the male ends off each.  As before, split the cord up the center a small bit, strip off some insulation, and twist the exposed ends as shown:

Now, cut 4 equal lengths of your 14-16 gauge wire.  These should be no longer than 2-4 inches in length.  Strip some insulation off each end and twist up any loose wires.

For the next part, you will need to pay close attention.  Each extension cord should have two different types of insulation around the wires.  One side should have a ribbed edge, and one side should have a smooth edge shown below:

The ribbed side should be in line with the "fat" prong/receptacle (the neutral side) and the smooth side should be in line with the smaller prong/receptacle (the active/"hot" side).  It is important that the next steps be followed carefully, noting which wires I am referring to.  Using the wrong wire can lead to a short, blown fuses, kicked circuit breakers, or even worse things.

Take the 4 short wires you cut earlier and twist them all together along with the ribbed/neutral wire from the extension cord with the male end still attached.

Twist a wire nut over the exposed ends to keep them together and covered.

Next, twist together the smooth/"hot" wire from the four extension cords with the female ends still attached along with the smooth/"hot" wire from the extension cord with the male end attached (i.e. the other wire from the male cord used above).

Again, twist on a wire nut to keep things covered and safe.

You should now be left with the opposite ends of the 4 cut wires exposed, and the 4 ribbed/neutral wires of the female extension exposed.  These will all be put into the screw terminals of the Phidget Interface Kit.

The Phidget Interface Kit board has 4 groups of screw terminals.  Each group contains 3 items:  NO, XC, and NC, where X is the relay number in question.  These stand for "Normally Open", "Common", and "Normally Closed".  For this project, the lights should normally be off and switched on via the software, so the NO (Normally Open) and XC (Common) ports will be used.

Place one wire from each exposed bundle into each NO and XC port.  Note that it does not matter which wire you plug into which terminal of each group, just that each group has only one short wire and only one extension cord wire.

In the end, there will be one each of the 4 short wires in each group on the board, and one each of the extension cord wires in each group on the board as pictured:

Below is a very simple schematic of the wiring of a single board:

I decided to keep things neat and tidy and mount the Phidget boards into a project box.  Since I have 2 boards to manage, I placed both inside a single, large box.  I drilled holes in the short sides to expose the boards' USB ports.  I then notched out some spaces on the top edge and lid for the extension cords to pass through.  I mounted the boards inside the box with some carefully placed two-sided foam tape.

The finished product can be seen below:

And that's it!  If this box will be placed outside, take the time to properly weatherproof the box so the elements cannot damage anything inside.

A Word on Amperages

Your individual light strings will be plugged into each extension cord outlet.  An average strand of mini-lights draws about .3 amps. An average string of larger bulbs will draw 1-2 amps.  The relays on the Phidget board are rated at 10 amps.  Additionally, a standard house circuit will allow up to 15-20 amps before overloading.  Check the circuit breaker in your home on which the outlet you'll be using lives for the allowed amperage.  Also, keep in mind that any other devices that are plugged into that circuit elsewhere in the house will be drawing power, so you may not be able to draw a full 15 amps from it.  So, be sure to not draw more than 10A per channel, nor more than 15-20A in total, including all additional devices plugged into that circuit.  Keep this in mind as you string your lights together on each channel.

Writing the Software

Ensure the Phidgets libraries for .NET are installed on the development machine.  To compile the source code, Visual Basic and/or Visual C# Express 2005 will also be need to be installed and working.

The Light Sequencer application uses a grid-style interface to show the list of channels and when each channel is switched on and off.

Squares can be toggled on or off by highlighting them, right-clicking with the mouse and selecting On or Off from the context menu.  They can also be toggled by pressing the O (for on) or F (for off) keys on the keyboard.

Additionally, sequences can be "recorded" by pressing the Record button in the toolbar.  This will start the music and allow the user to tap out the rhythm for each channel by pressing the number key on the keyboard corresponding to the channel.

Sequences can be saved at any time and reloaded for editing or play with the Phidgets devices connected.

When I first started the software for this project, the first problem I ran into was the fact that the DataGridView control does no support multiple headers.  As is shown in the screenshot above, the grid is broken down into seconds and then milliseconds.  For display purposes. it is easier to break the header down into two segments, one showing the labeled second markers, and one showing the subdivisions per second.

To accomplish this, I created two DataGridViews:  one for the header, which contains no data and is only as tall as the header row, and one for the sub-header and the data below it.  This works great except for scrolling.  To accomplish this, I simply listen for the Scroll event on the main grid and apply the scrolling offset to the header grid:

Visual C#

private void dgvMain_Scroll(object sender, ScrollEventArgs e)
{
    dgvHeader.HorizontalScrollingOffset = e.NewValue;
}

Visual Basic

Private Sub dgvMain_Scroll(ByVal sender As Object, ByVal e As ScrollEventArgs) Handles dgvMain.Scroll
    dgvHeader.HorizontalScrollingOffset = e.NewValue
End Sub

Additionally, I ran into some performance issues drawing the grid.  At first, drawing a grid with so many columns was quite slow.  By setting the grid's Visible property to false before adding the rows and columns and then returning the Visible property to true, the grid now draws quite quickly.

The next issue tackled was starting and stopping a music file.  In version 2, the software supports sampled music (MP3, WAV, etc.) as well as MIDI files.  As I was attempting to write a MIDI file parser and player (so I could have access to the internal data for auto-generating a sequence) I found a fantastic MIDI library written by Leslie Sanford.  This library is used by the Light Sequencer application.

With two playback libraries in place, I created an interface which contains Start, Stop, Load, etc. methods so that the front-end could use any playback engine interchangeably.  The MCIPlayback engine uses standard MCI commands for playing sampled music.  Commands are executed by passing them to the mciSendString function exported by winmm.dll.  In order to use this function from .NET, we must import the method and setup its signature as follows:

Visual C#

[DllImport("winmm.dll")]
static extern Int32 mciSendString(String command, StringBuilder buffer, Int32 bufferSize, IntPtr hwndCallback);

Visual Basic

Declare Function mciSendString Lib "winmm.dll" Alias "mciSendStringA" (ByVal command As String, _
   ByVal buffer As StringBuilder, ByVal bufferSize As Int32, _
   ByVal hwndCallback As IntPtr) As Int32

To open a music file, the open command is used as follows:

open "<path to file>" type mpegvideo alias MediaFile

This opens the file and creates an alias named MediaFile which can be used to refer to the file for all future commands.  Send the above command using the mciSendString method would look as follows:

Visual C#

string cmd = "open \"" + _musicFile + "\" type mpegvideo alias MediaFile";
mciSendString(cmd, null, 0, IntPtr.Zero);

Visual Basic

Dim cmd As String = "open """ + file + """ type mpegvideo alias MediaFile"
mciSendString(cmd, Nothing, 0, IntPtr.Zero)

The remaining commands we will need are:

• play MediaFile from 0 -- Play loaded file from beginning
• stop MediaFile -- Stop playing current file
• close MediaFile -- Close the file

Next, the Phidget boards behavior needed to be implemented.  Talking to the Phidget board is very easy.  After creating an instance of the InterfaceKit object, a specific device can be opened by calling the open method, passing in the serial number of the device to be opened.

The serial numbers for each attached Phidget device can be determined by creating an instance of the Phidgets.Manager class, setting up the Attach event handler, and listening for the attach events as follows:

Visual C#

...
Phidgets.Manager phidgetsManager = new Phidgets.Manager();
phidgetsManager.Attach += new AttachEventHandler(phidgetsManager_Attach);
phidgetsManager.open();
...

void phidgetsManager_Attach(object sender, AttachEventArgs e)
{
    Debug.WriteLine(e.Device.Name + " - " + e.Device.SerialNumber)
}

Visual Basic

...
Dim phidgetsManager as New Phidgets.Manager
AddHandler phidgetsManager.Attach, AddressOf Me.phidgetsManager_Attach
phidgetsManager.open()
...

Private Sub phidgetsManager_Attach(ByVal sender As Object, ByVal e As AttachEventArgs)
    Debug.WriteLine(e.Device.Name & " - " & e.device.SerialNumber)
End Sub

Setting the relay state is as easy as indexing into the outputs array of the InterfaceKit object and setting the indexed output to true or false.

In code, all of this would look like:

Visual C#

InterfaceKit ik = new InterfaceKit();
ik.open(1234);
ik.outputs[0] = true;

Visual Basic

Dim ik as New InterfaceKit
ik.open(1234)
ik.outputs(0) = True

In order to maintain precise timing, the Stopwatch class from the System.Diagnostics namespace is used.  This internally uses the QueryPerformanceCounter Win32 API method to give extremely precise time values.

When it is time to playback a sequence, a thread is started which starts the music using the appropriate playback engine, and then sits in a loop, waiting for the number of milliseconds to pass specified in the sequence (50ms as default).  When that amount of time has elapsed, we send the channel states of the current tick to the relays connected.

Recording a sequence with the keyboard works in a similar fashion.  A thread is started and the music is played.  While the music is playing, KeyDown and KeyUp events are listened for.  After translating the KeyCode of the pressed key to the channel number, an internal array of which keys are "on and off" are maintained.  When the number of milliseconds elapsed hits the appropriate mark, every channel is updated with the current value of that array.  That is, which keys are up and down.

When the user stops playback, or the song ends, the channel data is returned to the main form and displayed in the main grid.

If a MIDI file is selected, sequence data is automatically generated based on the MIDI data.  A MIDI file contains a series of tracks or channels with a series of commands.  These commands tell the MIDI hardware what note to turn on, when, and for how long (among other things).  When the MIDI file is loaded, every command from every channel is enumerated and its time values are converted into milliseconds.  Once all the commands are gathered and organized, they are placed into this application's channel structure and displayed on the grid.  This allows the lights to flash in precise time to the MIDI file being played.

Using the Software

Ensure that the Phidget devices you will be using are attached to the PC.  Start by creating a new sequence from the File menu or by clicking the New Sequence button.  In the dialog that appears, locate a music file to play back and enter the length of time that the sequence should run.  Be sure to note which Phidget devices are attached and which channels they map to on the grid.  Click OK when complete.

The screen will redraw and present the grid interface for the length of time specified.  At this point, cells can be turned on and off by highlighting a cell and right-clicking, or by pressing the "O" key to turn the cell On, and the "F" key to turn the cell off.  Multiple cells can be selected and changed at once.

To use the recording interface, click the Record Sequence button or choose Record Sequence from the Sequence menu.  Be sure to select the correct choice of "Overwrite channel data" or "Append channel data."  As you record additional channels, you will almost always want to append and not overwrite.

Click the start button and a brief countdown will begin.  When the countdown reaches 0, the music will begin.  A channel can be recorded by pressing the keyboard key of the channel number.  For example, to tap out the rhythm of channel 1, press the 1 key at the appropriate times.

When complete, press the Escape key, or click the Stop button.  When the Record window is closed, the main grid will be updated with the sequence recorded.

Creating a sequence is certainly a time consuming task since each channel needs to be recorded.  While the rhythm interface allows one to record many channels simultaneously, I think it would be impossible for anyone to type out an entire sequence for all channels in one go.  In my opinion, it is easiest to record one or two channels at a time and append the data as you go.  In the end, you can use the grid interface to tweak the values and clean up any mistakes.

The sequence can be played back at any time. Simply press the Play button and watch your holiday lights play back to the timing you created.  Press the Stop button to end the current playback.

Sequences can be saved at any time by selecting Save from the file menu.

To test the channels by hand, select "Test Channels" from the "Tools" menu.  As with the recording screen, press the number keys associated with the channel to turn on or off to test that channel.

I found it was much easier to also have the lights plugged into the appropriate channels as I created my sequence.  That way I could see the results of my recordings immediately.

To create a playlist of many sequences, select New Playlist from the File menu.  Add your existing sequence files, order them as you wish, and save the playlist.  From this screen you can also play the playlist, set it up to repeat, advance tracks, etc.

To edit data on an existing sequence (Phidget serial numbers, mapped MIDI channels, etc.) select Edit Sequence Properties from the Sequence menu.  This will display the New Sequence dialog box and allow you to edit the existing setup.

Setting It All Up

So now that you have hardware, music and an animated sequence, it's time to hook it all up!  If you are doing an indoor show, a set of external speakers should be more than ample for playing the music for your light show.  For an outdoor show, you may wish to purchase an FM transmitter to output the music over a very low-powered FM frequency so that visitors can listen to the music on their car radios.  I personally have not gone this route, however you can find a variety of FM transmitters for sale around the 'net.  In a quick search, I found Ramsey Electronics which sells a variety of FM transmission hardware that is more than appropriate depending on your budget.  I am certain there are plenty of other devices that fit the bill as well.

To fire up the show, just plug in your USB Phidget devices, plug the lights into the appropriate channels, load the Light Sequencer application, and press the Play button!

Conclusion

And there we have it!  Holiday lights timed to your favorite holiday song.  Take your time in creating a sequence and show us what you've created!

I plan on maintaining and updating this article as we get closer and closer to the holidays, so please check back often for updates.  I will note updates at the top of the article.  Additionally, please send me any and all feedback, bug reports, feature requests, or anything else you have to say!  You can find my contact info in the readme.txt file located in the source code download linked above, or visit my website.

Thanks

Special thanks to Michelle Leavitt for help setting up lights and sequence ideas, and my dad for advice on wiring up the relays.

Thanks to Leslie Sanford for the incredible MIDI Toolkit.

And, a big thank you to the beta testers for version 2: Allen Leno, Steve Runion, Steve Trueman, Corey Emmert.

Bio

Brian is a Microsoft C# MVP and a recognized .NET expert with over 6 years experience developing .NET solutions, and over 9 years of professional experience architecting and developing solutions using Microsoft technologies and platforms, although he has been "coding for fun" for as long as he can remember.  Outside the world of .NET and business applications, Brian enjoys developing both hardware and software projects in the areas of gaming, robotics, and whatever else strikes his fancy for the next ten minutes. He rarely passes up an opportunity to dive into a C/C++ or assembly language project.  You can reach Brian via his blog at http://www.brianpeek.com/.

Paul-Valentin Borza - http://www.borza.ro

Difficulty: Intermediate
Cost: Free
Time required: 1-3 hours
Software: Visual C++ 2005 Express, Windows Server 2003 R2 Platform SDK, Windows Software Development Kit for Windows Vista
Hardware: None
Download Source: Winter Visualization Source Code

How do we build a visualization?

Please install (don't change the default installation directory):

• Visual C++ 2005 Express
• Windows Server 2003 R2 Platform SDK (contains MFC and ATL headers and libraries)
• Windows Software Development Kit for Windows Vista (contains Windows Media Player 11 SDK)

We need to make Visual C++ 2005 Express work with visualizations:

1. Navigate to 'C:\Program Files\Microsoft SDKs\Windows\v6.0\Samples\Multimedia\WMP_11\Wizards\VSNET';
2. Copy 'wmpwiz2005.vsz', 'wmpwiz.vsdir' and 'wmpwiz.ico';
3. Navigate to 'C:\Program Files\Microsoft Visual Studio 8\VC\Express\VCProjects';
4. Paste 'wmpwiz2005.vsz', 'wmpwiz.vsdir' and 'wmpwiz.ico';
5. Rename 'wmpwiz2005.vsz' to 'wmpwiz.vsz' (you're in 'C:\Program Files\Microsoft Visual Studio 8\VC\Express\VCProjects');
6. Edit 'wmpwiz.vsz' using Notepad and change the line 'Param="ABSOLUTE_PATH = <path to wmpwiz directory goes here>"' with 'Param="ABSOLUTE_PATH = C:\Program Files\Microsoft SDKs\Windows\v6.0\Samples\Multimedia\WMP_11\Wizards\VSNET"';
7. The Windows Media Player Plug-in Wizard is now installed. Launch Visual C++ 2005 Express.
   1. Click on 'File' > 'New' > 'Project...';
   2. In 'Project types:' select 'Visual C++';
   3. In 'Templates:' select 'Windows Media Player Plug-in Wizard';
   4. Change 'Name:' from 'wmpplugin1' to 'MyWinterVisualization' and click 'OK';
   5. The Windows Media Player Plug-in Wizard appears;
   6. On the 'Welcome to the Windows Media Player Plug-in Wizard' select 'Visualization' and click 'Next';
   7. On the 'Visualization Plug-in' change 'Friendly Name:' from 'MyWinterVisualization Plugin' to 'Coding4Fun Winter Visualization' and 'Description:' from 'Description of MyWinterVisualization plugin' to 'Description of Coding4Fun Winter Visualization'; don't check 'Property Page' or 'Listen to events';
   8. Click 'Next'. The wizard will create a new visualization for you; you're almost done!

You'll notice that the created project won't compile because the 'atlbase.h', 'wmpplug.h', 'effects.h' and 'winres.h' can't be opened; to overcome:

1. Click on 'Project' > 'Properties';
2. Expand 'Configuration Properties' > 'C/C++' > 'General';
3. In 'Additional Include Directories' add '"C:\Program Files\Microsoft SDKs\Windows\v6.0\Include"' and click 'OK';
4. Expand 'Configuration Properties' > 'Linker' > 'Input';
5. In 'Additional Dependencies' add 'msimg32.lib' (we'll need this to give smoothness to the visualization);
6. Click on 'Tools' > 'Options...';
7. Expand 'Projects and Solutions' > 'VC++ Directories';
8. In 'Platform:' select 'Win32' and in 'Show directories for:' select 'Include files';
9. Add '"C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include\atl"' and '"C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include\mfc"';

One last trick... Edit 'C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\Include\atl\atlbase.h' using Notepad. Find the following text (begins on line 287):

Comment line 287 to 293 and add 'AllocStdCallThunk' and 'FreeStdCallThunk' to look like:

You should now be able to compile a visualization. Compile your visualization and launch Windows Media Player.

1. Play a song; you can try My Fair Lady by David Byrne over ccMixter (this is the melody from the video preview);
2. Click on 'Now Playing';
3. Right-click inside Windows Media Player and click 'Coding4Fun Winter Visualization' > 'Coding4Fun Winter Visualization Bars' or 'Coding4Fun Winter Visualization Wave';
4. Please take a good look at the generated visualization. Do you see the flicker (the flashing effect that you wouldn't want to see)? Don't worry, we'll make the visualization flicker-free in a few minutes.

How do we debug a visualization?

We know how to build and try a visualization; however, how do we debug one? Simple - we attach to the 'wmplayer.exe' process.

1. Click on 'Project' > 'Properties';
2. Expand 'Configuration Properties' > 'Debugging';
3. In 'Command' enter 'C:\Program Files\Windows Media Player\wmplayer.exe';
4. Change 'Attach' from 'No' to 'Yes';
5. Click 'OK';
6. Open 'MyWinterVisualization.cpp' and locate 'CMyWinterVisualization::Render';
7. Add a breakpoint at line '60' in 'MyWinterVisualization.cpp';
8. Build Solution and launch Windows Media Player;
9. Start Debugging and select your visualization in Windows Media Player; the visualization should break in Visual Studio.

The Winter Visualization

From now on, we'll take a look at the source code for the Winter Visualization. A visualization can have one or more presets (Bars and Wave for example). I've decided to go with two presents for the Winter Visualization and named them: Snow Flakes (draws blue snowflakes) and Snow Flames (draws red snowflakes).

Configuration

Open 'WinterVisualization.h' and check the configuration values:

Don't modify EQ_ANGLE as it's needed to make equilateral triangles for the Koch Snowflake Fractal. If you change SNOW_FLAKE_COLOR_COUNT or SNOW_FLAME_COLOR_COUNT, modify the appropriate lines in CWinterVisualization::FinalConstruct. The visualization involves a lot of computations and changing any configuration value could potentially slow it down. However, you're more than welcome to try anything... For example, increasing KOCH_IT to 6 will make the visualization run slower, but the snowflakes will have a more defined border. Try playing with SNOW_ALPHA (value should be between 0 and 255).

Initialization

Open 'WinterVisualization.cpp':

The surface size, the device contexts, the fonts, the pens and the brushes are initialized (the variables are declared in 'WinterVisualization.h'). Notice that I'm also precomputing the Koch Snowflake Fractal because it doesn't make sense to compute it each time a snowflake is drawn; see CWinterVisualization::CreateSnow for more details.
Don't forget that we're in the native C++ world and we have to release memory! The article won't cover the memory deallocation, but you can find it inside CWinterVisualization::FinalRelease.

Rendering the Elapsed Time

CWinterVisualization::DrawText renders the elapsed time in the top-right corner; use this method when you want to see how frequent your CWinterVisualization::Render gets called by Windows Media Player.

pLevels->timeStamp is measured in 100 nanoseconds and indicates the elapsed time inside the playing song. Be aware that the 'SelectObject' method returns the previous/old selected object in the device context; you're advised to select the old object back in the device context after you've finished working with the new one.

Rendering the Wave

If you watched the video preview, you've seen that there is a wave in the middle of the screen. The CWinterVisualization::DrawPlus method draws plusses ('+') to build the wave (drawing plusses instead of connected lines gives a better effect).

This method depends on the currently selected preset and changes the color of the wave: blue for Flakes and red for Flames. We'll be rendering only the first channel (mono) waveform pLevels->waveform[0]. If you decide to use both channels (stereo), you'll have to use pLevels->waveform[0] and pLevels->waveform[1]; if the song is mono, then the second array is undefined (take care)! The method scales the values to the canvas size and draws the linked plusses.

Creating a Koch Snowflake

CWinterVisualization::CreateSnow computes the Koch Snowflake as described on the MathWorld Web Site. We construct an equilateral triangle with 3 vertices and start iterating: at the first iteration we have a polygon (which starts to resemble with a snowflake) with 12 vertices; at the second iteration we have a better snowflake/polygon with 48 vertices... at the fifth iteration we have a snowflake with 3072 vertices.

Rendering the Snowflakes

There are 13 (this is the default value) snowflakes that need to be rendered on the device context. When a snowflake reaches its maximum size, it gets reinitialized: its size depends on the waveform, its color depends on the preset and it's randomly distributed across the surface. Each snowflake is translated and rotated to its target position (this is required because of the precomputation where we considered the snowflake to be around x=0 and y=0).

PolylineTo is the fastest way to draw a polygon when you use a pen with width 1. The width of the pen has to be one!

Wrapping up: Blending and Rendering

So far, we've seen some methods that did something if someone called them. CWinterVisualization::Render calls those methods and in turn is called by Windows Media Player (which decides how frequent to call it). Notice the line 169 which allows this method to be called only 30 times per second. Because the size of the drawing surface can change (when you resize Windows Media Player), the device contexts are deleted and created again.

I haven't said anything about the flicker... how was that avoided? Take a good look at this method (especially at line 250): we weren't drawing directly on the default device context as the wizard-generated visualization did, instead we were drawing on a memory device context hdcMem which was copied to the default device context only when everything was ready. It's a simple solution and it avoids the flicker! Never draw directly to the hdc received as the argument!
What about the smooth effect? We needed the msimg32.lib, especially the AlphaBlend method which blends two device contexts together. The blend between hdcPrev and hdcMem lets the previous rendered scene to be drawn again with a darker shade, while the new scene is as vivid as it should be; hdcMem is saved to hdcPrev to keep it for the next rendering when it becomes the old scene. That's it!

Conclusion

Winter Visualization, Snow Flakes:

Winter Visualization, Snow Flames:

You've created a beautiful winter visualization... Watch the dancing snowflakes and download the Winter Visualization Source Code or download only the installer WinterVisualizationSetup.msi (share the Winter Visualization with your friends). I hope you enjoyed working with C++ and you like what you've learned today!
Thanks to the Microsoft Student Partners - Microsoft Academic Program Team Romania for support. Happy Holidays!

Reference

• Windows Media Player Custom Visualizations

Bio

Paul-Valentin Borza is in its third year of study at the Babeş-Bolyai University of Cluj-Napoca, Romania. Driven by his passion for technology, he was invited in 2005 to be a Microsoft Student Partners member - Microsoft Academic Program at the Faculty of Mathematics and Computer Science. He can be reached through his web site at www.borza.ro or on the Windows Live Network with windowslive@borza.ro.

	In this application, Brian Peek demonstrates how to create two spooky Halloween applications to trick your friends and colleagues.
Brian Peek ASPSOFT, Inc. Difficulty: Easy Time Required: Less than 1 hour Cost: Free Software: Visual Basic or Visual C# Express Editions, DirectX SDK (for application #1) Hardware: None Download: Download

Introduction

Last year I wrote two articles on how to annoy your friends and family by dripping blood down their computer screen, or by squirting them with (hopefully) fake blood from (even more hopefully) a fake skull.  Halloween is just around the corner, so here are two more applications which you can use to further bother the people around you.

Application #1 - Cursed Video

If you have ever seen the horror film The Ring, then you can likely guess the basic premise of this application.  For those that haven't, the film is about a video tape which, when watched, will cause the viewer to die within a week of viewing it.  So, what better way to annoy and terrify your friends than by playing the "cursed video" at a time you schedule without their knowing?

This application will use a library from Managed DirectX to play the video.  If you haven't already, grab the full DirectX SDK and install.  Note that we will be creating a dependency on DirectX, so the victim's PC will need to have DirectX 9.0c installed.  Almost every XP desktop has it installed at this point, but be sure to test the app on the target PC.  Additionally, I have had mixed success drawing a semi-transparent video with every method I've tried (DX, WPF, etc.).  It is very dependent on video drivers, so the intended effect may not be perfect on all PCs.  Again, be sure to test.

Next, create a new C#/VB Windows Application project and set references to the Microsoft.DirectX and Microsoft.DirectX.AudioVideoPlayback assemblies as shown:

Next, we need to make some modifications to the form.  The video will be played at 50% transparency against the victim's desktop, which gives a very creepy effect.  The form should also be hidden from view until the video is ready to be played at the selected time.  To do this, set the following properties on the form:

Next, we need to provide a surface onto which the video can be drawn.  Drop a PictureBox control onto the form and set its properties as follows:

Now we need a method which will play the video.  Bring in the Microsoft.DirectX.AudioVideoPlayback namespace with the using/Imports keyword and then add the following method to the form:

C#

using Microsoft.DirectX.AudioVideoPlayback;

...

Video _video;

public void StartShow()
{
    // create a new video from a filename
    this._video = Video.FromFile("ring.wmv");

    // set the drawable surface to the picturebox
    this._video.Owner = pictureBox1;

    // setup an event handler so we can pop up a msgbox when the video is over
    this._video.Ending += new EventHandler(video_Ending);

    // play it!
    this._video.Play();
}

void video_Ending(object sender, EventArgs e)
{
    // called when the video ends
    MessageBox.Show("Happy Halloween!");
    this.Close();
}

VB

Imports Microsoft.DirectX.AudioVideoPlayback

...

Private _video As Video

Public Sub StartShow()
    ' create a new video from a filename
    Me._video = Video.FromFile("ring.wmv")

    ' set the drawable surface to the picturebox
    Me._video.Owner = pictureBox1

    ' setup an event handler so we can pop up a msgbox when the video is over
    AddHandler _video.Ending, AddressOf video_Ending

    ' play it!
    Me._video.Play()
End Sub

Private Sub video_Ending(ByVal sender As Object, ByVal e As EventArgs)
    ' called when the video ends
    MessageBox.Show("Happy Halloween!")
    Me.Close()
End Sub

This simply creates a new Video object by loading a specific filename (ring.wmv), then assigns the video's Owner property to the PictureBox, which is where the video will be drawn.  Next, an event is setup so we are notified when the clip has ended, and finally, the video is played with the Play method.

The video_Ending event handler displays a message box and closes down the application.

x86/x64

The Managed DirectX assemblies are compiled to run in x86 mode only.  If you are compiling the application on an x64 OS, you will have to ensure that the main application is built as an x86 target.  To do so, choose Configuration Manager from the build menu.  In the dialog that appears, choose <New...> from the Active solution platform drop down:

Finally, choose x86 from the Type or select the new platform drop down:

Get back to the project and rebuild and you will have an x86-native application which will run successfully on both x86 and x64 platforms.

Config/Test/Scheduler

The code which handles the configuration, scheduling and testing will be the same for both of these applications, so please jump to that section by clicking here.

Application #2 - The Shining

If you have seen The Shining, you can probably guess where this one is heading, too.  The basic plot is that an author and his family retreat to an isolated hotel for the winter, and some paranormal activity causes the father to go a bit insane, among other things.  In the film, as the author goes crazy, he starts typing "All work and no play makes Jack a dull boy" over and over again on the typewriter.  So, this application will mimic that by, at the appointed time, popping up an instance of Notepad and having the computer type the phrase over and over again on its own.

Once again, create a new VB/C# Windows Application project.  As with the previous project, we want the main form to be hidden, but this time, it should be hidden at all times.  So, set the form properties as follows:

Next, drag a timer onto the form named tmrType and create an event handler for the Tick event which we will fill in later.

Create a method named StartShow as follows:

C#

using System.Diagnostics;
...

private Process _process;

public void StartShow()
{
    _process = Process.Start("notepad.exe");
    tmrType.Start();
}

VB

Imports System.Diagnostics

...

' the Notepad process
Private _process As Process

Public Sub StartShow()
    _process = Process.Start("notepad.exe")
    tmrType.Start()
End Sub

This code starts an instance of Notepad and then starts the tmrType ticking.  That tick event will send the appropriate letter to the Notepad window from the phrase:

C#

using System.Runtime.InteropServices;

...

[DllImport("user32")]
public static extern int SetForegroundWindow(IntPtr hwnd);

// counter variables
private int i, j;

// the message to type out
private const string msg = "All work and no play makes Jack a dull boy.";

...

private void tmrType_Tick(object sender, EventArgs e)
{
    // make sure the Notepad window is at the front
    SetForegroundWindow(_process.MainWindowHandle);

    // send the next letter to the window
    if(i < msg.Length)
        SendKeys.Send(msg[i++].ToString());
    else
    {
        // send a carriage return if we're at the end of the line
        SendKeys.Send("{ENTER}");

        // write the line 5 times
        if(++j < 5)
            i = 0;
        else
        {
            // when done, stop the timer, display the msgbox and close it up
            tmrType.Stop();
            MessageBox.Show("Happy Halloween!");
            this.Close();
        }
    }
}

VB

Imports System.Runtime.InteropServices

...

<DllImport("user32")> _
Public Shared Function SetForegroundWindow(ByVal hwnd As IntPtr) As Integer
End Function

' counter variables
Private i, j As Integer

' the message to type out
Private Const msg As String = "All work and no play makes Jack a dull boy."

Private Sub tmrType_Tick(ByVal sender As Object, ByVal e As EventArgs) Handles tmrType.Tick
    ' make sure the Notepad window is at the front
    SetForegroundWindow(_process.MainWindowHandle)

    ' send the next letter to the window
    If i < msg.Length Then
        SendKeys.Send(msg.Chars(i).ToString())
        i += 1
    Else
        ' send a carriage return if we're at the end of the line
        SendKeys.Send("{ENTER}")

        ' write the line 5 times
        j = j + 1
        If j < 5 Then
            i = 0
        Else
            ' when done, stop the timer, display the msgbox and close it up
            tmrType.Stop()
            MessageBox.Show("Happy Halloween!")
            Me.Close()
        End If
    End If
End Sub

At the start of the tick, a call is made to the Win32 API function SetForegroundWindow, passing in the window handle (_process.MainWindowHandle) of the Notepad process.  This ensures that the Notepad window is focused before we send the next letter to the window using the SendKeys method.  When the end of the phrase is reached, a carriage return is sent using SendKeys and the string {ENTER}.  This repeats 5 times at which point the timer is stopped, the message box is displayed, and the application closes.

The Scheduler

The final piece is to setup a time at which the effect will display on the victim's PC.  Create a simple dialog box with a DateTimePicker control that allows the choosing of the appropriate date/time to run:

Next, create a new application setting named Time as shown:

Next, setup the events on the Configuration form as follows:

C#

private void ConfigForm_Load(object sender, EventArgs e)
{
    // if no time has been specified, show today's date, otherwise, show the date previously selected
    if(Properties.Settings.Default.Time == DateTime.MinValue)
        dateTimePicker1.Value = DateTime.Now.Date;
    else
        dateTimePicker1.Value = Properties.Settings.Default.Time;
}

private void btnSave_Click(object sender, EventArgs e)
{
    // save the currently selected date/time to the Settings collection
    Properties.Settings.Default.Time = dateTimePicker1.Value;

    Properties.Settings.Default.Save();

    // tell the user what's up
    MessageBox.Show("Date and time saved.  When you click OK, the application will continue running and the show will start upon the specified date and time.  If you wish to reset the date/time, restart the application with the '-config' switch.", "Configuration updated", MessageBoxButtons.OK, MessageBoxIcon.Information);

    // close it up
    this.DialogResult = DialogResult.OK;
    this.Close();
}

private void btnCancel_Click(object sender, EventArgs e)
{
    // close it up
    this.DialogResult = DialogResult.Cancel;
    this.Close();
}

VB

Private Sub ConfigForm_Load(ByVal sender As Object, ByVal e As EventArgs) Handles MyBase.Load
    ' if no time has been specified, show today's date, otherwise, show the date previously selected
    If My.Settings.Default.Time = DateTime.MinValue Then
        dateTimePicker1.Value = DateTime.Now.Date
    Else
        dateTimePicker1.Value = My.Settings.Default.Time
    End If
End Sub

Private Sub btnSave_Click(ByVal sender As Object, ByVal e As EventArgs) Handles btnSave.Click
    ' save the currently selected date/time to the Settings collection
    My.Settings.Default.Time = dateTimePicker1.Value

    My.Settings.Default.Save()

    ' tell the user what's up
    MessageBox.Show("Date and time saved.  When you click OK, the application will continue running and the show will start upon the specified date and time.  If you wish to reset the date/time, restart the application with the '-config' switch.", "Configuration updated", MessageBoxButtons.OK, MessageBoxIcon.Information)

    ' close it up
    Me.DialogResult = System.Windows.Forms.DialogResult.OK
    Me.Close()
End Sub

Private Sub btnCancel_Click(ByVal sender As Object, ByVal e As EventArgs) Handles btnCancel.Click
    ' close it up
    Me.DialogResult = System.Windows.Forms.DialogResult.Cancel
    Me.Close()
End Sub

The code loads the current value at start (if it exists), saves it when the Save button is clicked, and does nothing when Cancel is clicked.

Back on the main form of either application, drag and drop a timer control named tmrScheduler to the main design surface.  Set the properties as follows:

This will start the timer immediately and call the Tick event once every minute.  That event will check to see whether the requested time has passed and, if so, starts the show:

C# - Cursed Video

private void tmrScheduler_Tick(object sender, EventArgs e)
{
    // if the current time is greater than the time set by the user
    if(DateTime.Now >= Properties.Settings.Default.Time)
    {
        // bring up the window
        this.WindowState = FormWindowState.Maximized;

        // disable this timer
        tmrScheduler.Enabled = false;

        // bring it to the top
        this.BringToFront();

        // play the movie
        StartShow();
    }
}

VB - Cursed Video

Private Sub tmrScheduler_Tick(ByVal sender As Object, ByVal e As EventArgs) Handles tmrScheduler.Tick
    ' if the current time is greater than the time set by the user
    If DateTime.Now >= My.Settings.Default.Time Then
        ' bring up the window
        Me.WindowState = FormWindowState.Maximized

        ' disable this timer
        tmrScheduler.Enabled = False

        ' bring it to the top
        Me.BringToFront()

        ' play the movie
        StartShow()
    End If
End Sub

C# - The Shining

private void tmrScheduler_Tick(object sender, EventArgs e)
{
    // if the current time is greater than the time set by the user
    if(DateTime.Now >= Properties.Settings.Default.Time)
    {
        // disable this timer
        tmrScheduler.Enabled = false;

        // start typing
        StartShow();
    }
}

VB - The Shining

Private Sub tmrScheduler_Tick(ByVal sender As Object, ByVal e As EventArgs) Handles tmrScheduler.Tick
    ' if the current time is greater than the time set by the user
    If DateTime.Now >= My.Settings.Default.Time Then
        ' disable this timer
        tmrScheduler.Enabled = False

        ' start typing
        StartShow()
    End If
End Sub

Configuration/Testing

To make it easy to reset the launch time, and to test the effect without scheduling it, two command line parameters can be added to Program.cs/vb to re-run the configuration or test.  Add the following code prior to the call to Application.Run:

C#

// test the effect
if(Environment.CommandLine.IndexOf("test") > -1)
{
    Form1 f = new Form1();
    f.StartShow();
    f.ShowDialog();
    return;
}

// if we haven't set the time, or the user requested the config dialog, display it
if(Properties.Settings.Default.Time == DateTime.MinValue || Environment.CommandLine.IndexOf("config") > -1)
{
    if(new ConfigForm().ShowDialog() == DialogResult.Cancel)
        return;
}

VB

' test the effect
If Environment.CommandLine.IndexOf("test") > -1 Then
    Dim f As Form1 = New Form1()
    f.StartShow()
    f.ShowDialog()
    Return
End If

' if we haven't set the time, or the user requested the config dialog, display it
If My.Settings.Default.Time = DateTime.MinValue OrElse Environment.CommandLine.IndexOf("config") > -1 Then
    If New ConfigForm().ShowDialog() = DialogResult.Cancel Then
        Return
    End If
End If

If -test is passed on the command line, the form is created and the show is started.  If -config is passed on the command line, the Configuration dialog is displayed and the application continues as it would the first time it ran.

Deployment

Cursed Video

Copy the exe, Microsoft.DirectX and Microsoft.DirectX.AudioVideoPlayback to a folder on the user's PC along with a video clip named ring.wmv.  Of course, you can replace that video clip with any clip of your choosing, though if you wish to use a different filename, you will have to change the code and recompile.

The Shining

Copy the exe to a folder on the user's PC.

For either, create a shortcut to it in the Startup program group, or set it up to run via the registry using the following key for the logged in user:

• HKCU\Software\Microsoft\Windows\CurrentVersion\Run

Simply create a new string key with any Name, and a Data value of the path to the executable.

Next, start the application once on their PC to setup the date and time for the show to begin. Once that is done, the application will remain running in the background. If the PC is restarted, and the application is setup to run at startup as described above, it will start silently and remain running, waiting for the date and time specified.

Summary

Two Halloween applications for the price of one.  Not that you paid for either.  Be sure to have fun with them this Halloween and disturb anyone you can.  Enjoy!

Thanks

Thanks to Giovanni Montrone for testing out these applications during development.

Bio

Brian is a Microsoft C# MVP and a recognized .NET expert with over 6 years experience developing .NET solutions, and over 9 years of professional experience architecting and developing solutions using Microsoft technologies and platforms, although he has been "coding for fun" for as long as he can remember.  Outside the world of .NET and business applications, Brian enjoys developing both hardware and software projects in the areas of gaming, robotics, and whatever else strikes his fancy for the next ten minutes. He rarely passes up an opportunity to dive into a C/C++ or assembly language project.  You can reach Brian via his blog at http://www.brianpeek.com/.

	In this article, Clint Rutkas builds a relay application that will drop 1,000 super bouncy balls from the ceiling as an April Fools gag!
Clint Rutkas Better Than Everyone Difficulty: Intermediate Time Required: 3-6 hours Cost: $100-$200 Software: Visual Basic or Visual C# Express Editions Hardware: Control Anything USB Relay Board, a drill, a ton of super bouncy balls and some zippie ties Download: Download

Introduction

I'm tend to go a bit crazy when it comes to pranks.  April Fool's day is almost like Christmas to me.  So bombarding someone with 1,000 super bouncy balls seemed like the proper thing to do come the first possible moment.

But that someone was a bit harder than I thought.  I needed a victim however but with how SpringCM's executive offices are designed, I quickly found him.  My victim for this task is my CTO, Dave Dahl.  I wasn't alone in this prank, I had my friend / co-worker, Andy Konkol, help out with the final assembly and testing of the application.

Here is the video of the final outcome over at YouTube.

The Prank Setup

You need a laptop, a rigging system, a WiFi network, a ton of bouncy balls, a drill, a spare ceiling tile, some string and a relay board.  Here is the picture of the system finally done.  The ceiling tile was modified with the sides shaved and gluing a piece of wood to the back to apply anchors into.  To figure out how to wire up relay boards, I suggest reading Brian Peek's holiday lighting article.  Brian provides diagrams and wiring safety information.

And we mustn't forget the balls.  How does one buy super bouncy balls?  It was surprisingly simple with Google and searching for "Super Bouncy balls".  I got mine from Gumball Machine Warehouse for about $70 if memory serves.  Each bag weights about 5 pounds I'd guess and is about a foot by a foot.  Apply them gingerly onto the shaven tile since it isn't supported by the orginal 1/4" lip anymore.

Andy Konkol admiring the release rig.  You can see we've mounted the drill to the fire system.  You'll also notice the drill's trigger is tied down so all we need to do is hit the relay and the drill will be on.

So as every good programmer knows is to test often, and as this picture shows, it is well earned.  Cleaning up the mess took about five minutes.  A video of this test can be found over on YouTube.  Since we didn't know how much it would hurt or cause damage, a human test subject was needed.  I stepped up to plate and had the crap freaked out of myself even knowing the balls were going to be deployed.

The Application

The application is fairly simple and uses a Control Anything USB relay board and has a laptop placed on a ceiling tile.  The laptop was left on and with Remote Desktop Connection, the application will be triggered.

Relay Code

I'm using the relay board for another project so currently it is a fairly simple codebase.  This application was the test bed for the next project.  How the relay board works is by sending a sequence of commands.  254 will prepare for a command, 29 then will turn all the relays off, 30 on.  The Control Anything relay board has a host of other features I haven't had time yet to implement but will soon so you can check back for a richer API for the relay board.  The company does provide Visual Basic 6 code examples and uses the chr$ command instead of a byte array.

C#

public bool AllRelaysOff()
{
    ComPort.WriteBuffer(new byte[] { 254, 29 });
    return relaySuccess();
}

public bool AllRelaysOn()
{
    ComPort.WriteBuffer(new byte[] { 254, 30 });
    return relaySuccess();
}

private bool relaySuccess()
{
    return (ComPort.ReadBufferChar() == 85);
}

VB

Public Function AllRelaysOff() As Boolean
    ComPort.WriteBuffer(New Byte() {254, 29})
    Return relaySuccess()
End Function

Public Function AllRelaysOn() As Boolean
    ComPort.WriteBuffer(New Byte() {254, 30})
    Return relaySuccess()
End Function

Private Function relaySuccess() As Boolean
    Return (ComPort.ReadBufferChar = 85)
End Function

Comport

The comport code is actually a slightly refractored version from my dance floor application.  The class itself is a wrapper for the .Net SerialPort object which can be found in System.IO.Ports.  Furthermore, it now inherits off IDisposable to help auto close the serial port and is designed aimed to help ease use for multiple applications.

C#

    public class ComPortIO : IDisposable
    {
        #region varibles
        public SerialPort ComPort 
        {
            get { return _comPort; }
            set { _comPort = value; }
        }
        private SerialPort _comPort;

        public bool DoneWriting
        {
            get { return _doneWriting; }
            set { _doneWriting = value; }
        }
        private bool _doneWriting;

        public bool DisableWriting
        {
            get { return _disableWriting; }
            set { _disableWriting = value; }
        }
        private bool _disableWriting;
        #endregion

        public void Dispose()
        {
            if (ComPort.IsOpen)
                ComPort.Close();
        }

        #region constructors
        public ComPortIO(string ComPortName, int BaudRate, bool DisableComWriting)
        {
            DisableWriting = DisableComWriting;

            if (!DisableWriting)
            {
                if (!doesPortExist(ComPortName))
                    throw new ArgumentException("The serial port used is not valid", ComPortName);

                ComPort = new SerialPort(ComPortName, BaudRate, Parity.None, 8, StopBits.One);

                if (!ComPort.IsOpen)
                    ComPort.Open();

                ComPort.ReadTimeout = 100;
            }
        }
        #endregion

        #region public functions
        public void WriteBuffer(char[] Buffer)
        {
            if (!DisableWriting)
                ComPort.Write(Buffer, 0, Buffer.Length);
        }

        public void WriteBuffer(byte[] Buffer)
        {
            if (!DisableWriting)
                ComPort.Write(Buffer, 0, Buffer.Length);
        }

        public void WriteBuffer(string Buffer)
        {
            if (!DisableWriting)
                ComPort.Write(Buffer);
        }

        public string ReadBuffer()
        {
            try
            {
                if (!DisableWriting && ComPort.IsOpen)
                {
                    return ComPort.ReadLine();
                }
            }
            catch (Exception) { }
            return null;
        }

        public int ReadBufferChar()
        {
            try
            {
                if (!DisableWriting && ComPort.IsOpen)
                {
                    return ComPort.ReadChar();
                }
            }
            catch (Exception) { }
            return -1;
        }

        public int ReadBufferByte()
        {
            try
            {
                if (!DisableWriting && ComPort.IsOpen)
                {
                    return ComPort.ReadByte();
                }
            }
            catch (Exception) { }

            return -1;
        }
        #endregion

        #region private functions
        private static bool doesPortExist(string ComPortName)
        {
            string[] serialPortNames = SerialPort.GetPortNames();

            for (int i = 0; i < serialPortNames.Length; i++)
            {
                if (string.Compare(serialPortNames[i], ComPortName, true) == 0)
                    return true;
            }
            return false;
        }
        #endregion
    }

VB

    Public Class ComPortIO
        Implements IDisposable

        Private _comPort As SerialPort
        Private _doneWriting As Boolean
        Private _disableWriting As Boolean

        Public Sub New(ByVal ComPortName As String, ByVal BaudRate As Integer, ByVal DisableComWriting As Boolean)
            MyBase.New()
            DisableWriting = DisableComWriting
            If Not DisableWriting Then
                If Not doesPortExist(ComPortName) Then
                    Throw New ArgumentException("The serial port used is not valid", ComPortName)
                End If
                ComPort = New SerialPort(ComPortName, BaudRate, Parity.None, 8, StopBits.One)
                If Not ComPort.IsOpen Then
                    ComPort.Open()
                End If
                ComPort.ReadTimeout = 100
            End If
        End Sub

        Public Property ComPort() As SerialPort
            Get
                Return _comPort
            End Get
            Set(ByVal value As SerialPort)
                _comPort = value
            End Set
        End Property

        Public Property DoneWriting() As Boolean
            Get
                Return _doneWriting
            End Get
            Set(ByVal value As Boolean)
                _doneWriting = value
            End Set
        End Property

        Public Property DisableWriting() As Boolean
            Get
                Return _disableWriting
            End Get
            Set(ByVal value As Boolean)
                _disableWriting = value
            End Set
        End Property

        Public Overloads Sub Dispose() Implements IDisposable.Dispose
            If ComPort.IsOpen Then
                ComPort.Close()
            End If
        End Sub

        Public Overloads Sub WriteBuffer(ByVal Buffer() As Char)
            If Not DisableWriting Then
                ComPort.Write(Buffer, 0, Buffer.Length)
            End If
        End Sub

        Public Overloads Sub WriteBuffer(ByVal Buffer() As Byte)
            If Not DisableWriting Then
                ComPort.Write(Buffer, 0, Buffer.Length)
            End If
        End Sub

        Public Overloads Sub WriteBuffer(ByVal Buffer As String)
            If Not DisableWriting Then
                ComPort.Write(Buffer)
            End If
        End Sub

        Public Function ReadBuffer() As String
            Try
                If (Not DisableWriting _
                   AndAlso ComPort.IsOpen) Then
                    Return ComPort.ReadLine
                End If
            Catch
            End Try
            Return Nothing
        End Function

        Public Function ReadBufferChar() As Integer
            Try
                If (Not DisableWriting _
                   AndAlso ComPort.IsOpen) Then
                    Return ComPort.ReadChar
                End If
            Catch

            End Try
            Return -1
        End Function

        Public Function ReadBufferByte() As Integer
            Try
                If (Not DisableWriting _
                   AndAlso ComPort.IsOpen) Then
                    Return ComPort.ReadByte
                End If
            Catch

            End Try
            Return -1
        End Function

        Private Shared Function doesPortExist(ByVal ComPortName As String) As Boolean
            Dim serialPortNames() As String = SerialPort.GetPortNames
            Dim i As Integer = 0
            Do While (i < serialPortNames.Length)
                If (String.Compare(serialPortNames(i), ComPortName, True) = 0) Then
                    Return True
                End If
                i = (i + 1)
            Loop
            Return False
        End Function
    End Class

Deployment

As soon as Dave Dahl sat down, I clicked the drop button and the everything worked like clock work.  If you want to see the video, once again it is over at YouTube for your April Fools Day pleasure.

Summary

Before you do such a prank, please be sure you your victim will be cool with it so you won't get fired.  Thankfully, I wasn't and Dave is cool ... I hope.  I wasn't happy totally with our deployment solution since it was partially visible due to the string.  I'd also like to have had the entire system automated with maybe an IR sensor or a force sensor hidden in the seat.  Given a few more weekends and actually planning this prank out a bit more, I think Andy and myself could have come up with a more robust system. 

Thanks

A special thanks to Dave Dahl for being such a good sport and Andy Konkol for helping out.

Bio

Clint is an application developer for SpringCM, an on-demand, web-based document and content management system.  His two primary development languages are C# and JavaScript. Prior to the ball drop project, he worked on his Disco Dance Floor. In his off time, he whips up other random weird projects and does twenty something activities with his friends. Clint's blog is betterthaneveryone.com and can be emailed at clint@rutkas.com.

Signing up for the Amazon Web Services

The first step in using this application is signing up for the Amazon Web Services.  From there you'll get a AWS key that you will use to access the web service for authorization purposes.  This key should be 20 characters.

Adding the Amazon Web Services to .Net

The wonderful thing about .Net is how easy it is to add in a Web Service.  First you right click on References in your solution.

The next step is adding in the WSDL.  Here is the URL for it.

http://webservices.amazon.com/AWSECommerceService/AWSECommerceService.wsdl

Oven is preheating, lets do some work.

Ok, so now I have the web service added and Visual Studio is all ready to rock the casbah, we need know how to request information.  For that, we need documentation.  RTFM?  Yes, read the manual which is found here (PDF).  After a few quick searches, I found some samples through direct requests.

Here is an example that will return my wishlists.  You need to add in insert your key.

http://webservices.amazon.com/onca/xml?Service=AWSECommerceService&AWSAccessKeyId=YOUR_KEY&Operation=ListSearch&ListType=WishList&Email=Clint@pronerd.com

Ok, so this is wonderful if I was doing JavaScript but I'm not.  So how does one make this request in c#?  You need the ListSearchRequest , ListSearch, ListSearchResponse, and AWSECommerceService objects.

C# Code

   1:  // building search object for wishlist

   2:  ListSearchRequest request = new ListSearchRequest();

   3:  request.ListType = ListSearchRequestListType.WishList;

   4:  request.Email = txtEmail.Text;

   5:   

   6:  ListSearch listSearcher = new ListSearch();

   7:  listSearcher.AWSAccessKeyId = AmazonKey;

   8:  listSearcher.Request = new ListSearchRequest[] { request };

   9:   

  10:  ListSearchResponse response = amazonPrime.ListSearch(listSearcher);

  11:  // populate wishlists

  12:  if (response.Lists.Length > 0)

  13:  {

  14:      List[] returnLists = response.Lists[0].List;

  15:      lstWishlists.DataSource = returnLists;

  16:      lstWishlists.DisplayMember = "ListName"; // want to show the list name

  17:  }

Visual Basic

   1:  Dim request As ListSearchRequest = New ListSearchRequest

   2:  request.ListType = ListSearchRequestListType.WishList

   3:  request.Email = txtEmail.Text

   4:  Dim listSearcher As ListSearch = New ListSearch

   5:  listSearcher.AWSAccessKeyId = AmazonKey

   6:  listSearcher.Request = New ListSearchRequest() {request}

   7:  Dim response As ListSearchResponse = amazonPrime.ListSearch(listSearcher)

   8:  ' populate wishlists

   9:  If (response.Lists.Length > 0) Then

  10:      Dim returnLists() As List = response.Lists(0).List

  11:      lstWishlists.DataSource = returnLists

  12:      lstWishlists.DisplayMember = "ListName"

  13:      ' want to show the list name

  14:  End If

   1:  private ListItem[] GetWishlistItems(string ListId, int Page, out int TotalPages, out int TotalItems)

   2:  {

   3:      TotalPages = 0;

   4:      TotalItems = 0;

   5:   

   6:      ListLookupRequest request = new ListLookupRequest();

   7:      request.ListId = ListId;

   8:      request.ListType = ListLookupRequestListType.WishList;

   9:      request.ListTypeSpecified = true;

  10:      request.ProductPage = Page.ToString();

  11:      request.ResponseGroup = new string[] { "ListItems", "ItemAttributes" }; // ItemAttributes gets me package size

  12:   

  13:      ListLookup listLookup = new ListLookup();

  14:      listLookup.AWSAccessKeyId = AmazonKey;

  15:      listLookup.Request = new ListLookupRequest[] { request };

  16:   

  17:      ListLookupResponse response = amazonPrime.ListLookup(listLookup);

  18:   

  19:      // populate wishlists

  20:      if (response.Lists != null && response.Lists.Length > 0 && response.Lists[0].List.Length > 0)

  21:      {

  22:          List returnedList = response.Lists[0].List[0];

  23:   

  24:          TotalPages = Convert.ToInt32(returnedList.TotalPages);

  25:          TotalItems = Convert.ToInt32(returnedList.TotalItems);

  26:   

  27:          return response.Lists[0].List[0].ListItem;

  28:      }

  29:      return null;

  30:  }

   1:      Private Function GetWishlistItems(ByVal ListId As String, ByVal Page As Integer, ByRef TotalPages As Integer, ByRef TotalItems As Integer) As ListItem()

   2:          TotalPages = 0

   3:          TotalItems = 0

   4:          Dim request As ListLookupRequest = New ListLookupRequest

   5:          request.ListId = ListId

   6:          request.ListType = ListLookupRequestListType.WishList

   7:          request.ListTypeSpecified = true

   8:          request.ProductPage = Page.ToString

   9:          request.ResponseGroup = New String() {"ListItems", "ItemAttributes"}

  10:          ' ItemAttributes gets me package size

  11:          Dim listLookup As ListLookup = New ListLookup

  12:          listLookup.AWSAccessKeyId = AmazonKey

  13:          listLookup.Request = New ListLookupRequest() {request}

  14:          Dim response As ListLookupResponse = amazonPrime.ListLookup(listLookup)

  15:          ' populate wishlists

  16:          If ((Not (response.Lists) Is Nothing)  _

  17:                      AndAlso ((response.Lists.Length > 0)  _

  18:                      AndAlso (response.Lists(0).List.Length > 0))) Then

  19:              Dim returnedList As List = response.Lists(0).List(0)

  20:              TotalPages = Convert.ToInt32(returnedList.TotalPages)

  21:              TotalItems = Convert.ToInt32(returnedList.TotalItems)

  22:              Return response.Lists(0).List(0).ListItem

  23:          End If

  24:          Return Nothing

  25:      End Function

   1:  ArrayList templist = new ArrayList();

   2:   

   3:  for (int i = 0; i < giftList.Count; i++)

   4:  {

   5:      decimal tolerance = numTol.Value;

   6:      ListItemsSimple temp = (ListItemsSimple)giftList[i];

   7:   

   8:      if(

   9:          Math.Abs(temp.Height - numHeight.Value) < tolerance && 

  10:          (

  11:              // incase Amazon and you disagree with 

  12:              // which is length and width

  13:              (Math.Abs(temp.Length - numLength.Value) < tolerance &&

  14:              Math.Abs(temp.Width - numWidth.Value) < tolerance)

  15:              ||

  16:              (Math.Abs(temp.Width - numLength.Value) < tolerance &&

  17:              Math.Abs(temp.Length - numWidth.Value) < tolerance))

  18:          )

  19:      {

  20:          templist.Add(giftList[i]);

  21:      }

  22:  }

  23:   

  24:  lstGifts.DataSource = templist;

  25:  lstGifts.DisplayMember = "Title"; // want to show the list name

   1:  Dim templist As ArrayList = New ArrayList

   2:  Dim i As Integer = 0

   3:  Do While (i < giftList.Count)

   4:      Dim tolerance As Decimal = numTol.Value

   5:      Dim temp As ListItemsSimple = CType(giftList(i),ListItemsSimple)

   6:      If ((Math.Abs((temp.Height - numHeight.Value)) < tolerance)  _

   7:                  AndAlso (((Math.Abs((temp.Length - numLength.Value)) < tolerance)  _

   8:                  AndAlso (Math.Abs((temp.Width - numWidth.Value)) < tolerance))  _

   9:                  OrElse ((Math.Abs((temp.Width - numLength.Value)) < tolerance)  _

  10:                  AndAlso (Math.Abs((temp.Length - numWidth.Value)) < tolerance)))) Then

  11:          templist.Add(giftList(i))

  12:      End If

  13:      i = (i + 1)

  14:  Loop

  15:  lstGifts.DataSource = templist

  16:  lstGifts.DisplayMember = "Title"

Do you know of a programmable present that wasn't listed here? Email us and we'll get it added to our list.

The holiday guide is broken down into 5 sections. Programmable Hardware and Gadgets, Programmable Robots, Programmable Games, Cool Software Tools, and Top 10 Presents for Developers

Programmable Hardware and Gadgets

Enjoy tinkering?  Think that the orginary can be modified to do something different with a little effort?  This entire section of gifts are items one can program. The range from webcams to disco floor parts to cell phones.

Wireless Xbox 360 Controller for Windows The newly released wireless controller can be used to play both Xbox 360 and Windows PC games, and best of all, you can program with it too. In fact, certain applications, like Virtual Earth 3D already include support for the Xbox 360 controller so you'll be able to use your controller to literally fly around the world! Cost: $37.99 Get it: Wireless Xbox 360 Controller on Amazon.com Code it: The XNA Framework includes full support for Xbox 360 controllers for Windows and the Web using the XInput class. To learn the basics of programming your XNA controller, check out Paul Stubbs excellent Xbox 360 controller article as well as the newly updated version ported to work with the XNA Framework.

IrMan Infrared man (Irman) is a small device that allows you to control your PC with the remote from your TV, VCR, CD or Stereo. You can use it to programmatically control any applications on your PC! Cost: $40 Get it: IrMan Home Page Code it: Duncan MacKenzie, the first Coding4Fun author, posted a classic article on using an IrMan through a Pocket PC using Visual Studio .NET 2003.

Nintendo Wii Remote Why the Wii Remote without the Nintendo Wii? Because some clever hackers figure out how to get information out of it. The Wii Remote is actually a Bluetooth device that has an XYZ accelerometer in it. With some computing, one is able to figure out the tilt of the controller. Cost: $53.67 Get it: Nintendo Wii Remote on Amazon.com Code it: [Link coming soon]

Pedometer with PC Download Geek out, even when your exercising using this built-in pedometer Cost: $59.99 Get it: Pedometer with PC Download Code it: With the included PC download software, users can easily export the data into a database and easily track their progress.

CrystalFontz LCD Displays Using the new Serial Port classes in the .NET Framework 2.0, you can create some pretty cool applications to display dynamic information on a CrystalFontz LCD display. Cost: $60-$80 Get it: CrystalFontz Home Page Code it: Scott Hanselman has a great article that shows how to display what's playing in Windows Media Player on an LCD display and Kit George has a cool Space Invaders Console game demo that he hooked up to an LCD display to control how you fly the spacecraft.

Phidgets Phidgets are a low cost, easy to use building block that connects to your PC through USB. Through a very robust API, developing applications is quick and easy. They have RFID, electrical relays, Servos, LED, multiple different types of sensors, and even a Pan & Tilt Web Cam kit. Cost: $75 and up Get it: Code it: Scott Hanselman created a weather collection program and Brian Peek created a motion-detecting Halloween prank from one.

Airlink Network Camera AIC 250 Enjoy full motion video over a wireless connection with this easy-to-setup Web cam with built-in support for DSL or Cable model DHCP. Cost: $99 Get it: Airlink Network Camera at Frys.com Code it: Scott Hanselman's got a great article that shows how to programmatically detect motion using the AIC 250 Network Camera.

GPS Receiver with Microsoft Streets & Trips 2007 Where am I? With Microsoft Streets and Trips, it provides a turn-by-turn speech support and .NET integration. This software and GPS combo can be used with your laptop, Tablet PC, Windows Mobile device to find your way when asking for directions won't do. Cost: $129.99 Get it: Streets and Trips 2006 on Amazon.com Code it: Scott Hanselman again comes to the rescue with a great article on how read data off of the GPS receiver.

MAKE Controller Kit Need a relay controller? How about a device that is Ethernet ready? USB too? Need digital Inputs also? Don't worry, MAKE has you covered with their MAKE controller. It has all of the above functionality and more. More so, it has API for .Net, Java, Max & Pd, Flash, C / C++. You can even network multiple controllers together to create a more complex device. Cost: $149 Get it: Make Controller Kit Code it: The Make Controller Kit features a .NET library for easy programmability that can be used with any managed code language including VB, C#, and C++.

Z-Wave PC SDK Starter Kit Intermatic's HomeSettings Lighting Control Starter Kit is an easy way to help automate your home. Want your lights to turn on at 7 pm or control your home entertainment system's lighting, the Z-Wave makes it rather easy. Cost: $149 not including discount for registered Express users Get it: Z-Wave PC SDK Starter Kit Code it: The Z-Wave PC Starter Kit ships with the SDK, .NET Framework API and full documentation to get started. You can get help using the SDK on the ControlThink Forums.

Learning Edition Microcontroller Kit Whether you're young or old, learning the ins and outs of microcontrollers can be tricky. You can now learn the basics of microcontrollers including programming sensors, motors, resistors, microphones, diodes, capacitors and more. Cost: $149.95 Get it: Microcontroller Kit Home Page (source: Wired Gift Guide) Code it: The kit includes built-in programmability for controlling your hardware.

Disco Dance Floor Parts If you want your home to be disco'ed out, you can get the PCB hardware boards from the people over at MIT who originally designed it. They also have boards pre-constructed if surface soldering isn't your forte for an additional cost.  Not sure on what types of LEDs to buy or how to do the cabling?  They have that too now! Cost: $35 to $450 dollars per board Get it: Dropout Design Code it: You can't go wrong with Clint Rutkas's Coding4Fun article for how to build out your own disco dance floor!

Sirius Conductor Satellite Radio Tuner For Sirius Satellite radio fans, you can program macro-like behavior using the Z-Wave Sirius Radio Tuner. Because it's Z-Wave, you'll be able to easily program it or any other Z-Wave Products using the Intermatic .NET Framework 2.0 gear. Cost: $149.99 Get it: Z-Wave Sirius Radio Tuner at Circuit City Code it: If you have the Z-Wave PC SDK with Intermatic Home Settings Lighting Control Starter Kit, it includes the ControlThink SDK which enables you to easily program Z-Wave gear.

Windows Mobile Smartphones The Samsung Blackjack, T-Mobile Dash, or the Motorola Q are great at making complex life easy. They run Windows Mobile 5.0 Smart Phone edition and are slim and small. With this Windows Mobile Version, you won't be able to alter Office Documents, but you'll be able to view them through Picsel Viewer. All these phones have a full QWERTY keyboard on them. If you need more power, upgrade to a Cingular 8515, a Treo 700w, T-Mobile MDA, or the Samsung SCH-i730. These phones have larger screens that are touch sensitive and while physically bigger, they can do more. Unlike the phones above that run the Smart Phone edition these run the Pocket PC Edition. With these phones, you get Microsoft Office Mobile Suite so one can create and editing of Office documents. Price: $199 - $600 Get it: Windows Mobile Smartphones Code it: You can use Visual Studio 2005 Standard Edition, one is able to develop for these devices and create software with ease, like Bryan Dougherty's Mobile Pac-man

StreetDeck Software StreetDeck software is the ultimate must-have software for pimping out your car. StreetDeck includes, GPS Navigation, internet-enhanced navigation using Google Maps or Microsoft Live Local, Media Sync for your MP3 collection, games, and best of all, there's an SDK so it's fully customizable. Cost: $199.99 Get it: StreetDeck software on MP3Car.com Code it: Streetdeck includes a SDK for programming using VB Script, similar to Office VBA, and you can also build a .NET add-in in Visual Basic, C#, or C++ by making it available through COM.

eStarling Wi-Fi Email/RSS-Enabled LCD Frame This frame enables users to either run an email configuration or RSS feed configuration so you can choose to write an application that dynamically sends an email (say from a Webcam periodically), dynamically upload your pictures to Flickr, or create your own RSS feed with pictures. Cost: $249.99 Get it: eStarling page on ThinkGeek.com Code it: You can use Sam Judson's Flickr .NET API to easily programmatically send pictures to Flickr, or use the FlickrWebCam application to have mom get real-time pictures of you from your Webcam or use the SmtpMail Class to email a picture attachment in one line of code.

Home Theater and Lighting Controller 300 featuring OmniLinkTM If you have your house setup for Z-Wave Home Automation, then you'll want this programmable remote that enables you to easily control your lights, home theater and more. Cost: $599 Get it: Home Theater and Lighting Controller 300 Code it: If you have the Z-Wave PC SDK with Intermatic Home Settings Lighting Control Starter Kit, it includes the ControlThink SDK which enables you to easily program Z-Wave gear.

Windows Media Center Now is a great time to upgrade your old PC, like the Dell XPS 410 a PC Magazine Editor's Choice that ships with Windows Media Center 2005, but includes a free upgrade to Windows Vista Home Premium which includes a revamped Media Center with built-in streaming to your Xbox 360. Cost: $999 - $2,500 Get it: Dell Online Store Code it: Windows Vista Media Center has a much-improved API and three different ways to mod Media Center including HTML, XAML, and Media Center's own markup language using the Windows SDK.

Robotics

Mr. Roboto, please come to the front, your Roomba is waiting for you. This entire section lists robots and electronics that do everything from a vacuum cleaner to creating your own cellphones to GPS.

Microbric Viper Robot The Microbric Viper robot enables you to build complex electronic devices with little or no prior electronics knowledge and no soldering required. Cost: $89.99 Get it: Microbric Viper Robot and Serial IR Transmitter/Receiver Code it: Scott Hanselman walks through programming a Microbric Viper Robot

Lassen iQ FAT16 Datalogger - Complete Kit Ever think you constantly walk in circles? Think you could optimize your routes if you only could map where your went? Use this GPS device to passively map your routes, all you need is an SD card added in. Then return to your computer, upload your data and see where you wandered. Great for mapping routes biking or hiking. Cost: $150.70 Get It: Spark Fun Code It: From their GPS Logger Datasheet, you can get it to work with Google Maps or create your own from the specification provided.

Parallax Bluetooth Boe-Bot Kit for Microsoft Robotics Studio Using Microsoft Robotics Studio, you can easily program the Boe-Bot Parallax kit over Bluetooth and best of all, the Robotics Studio team has negotiated a 15% discount on the BoeBot. Cost: $198.77 after 15% discount Get it: Parallax Boe-Bot Kit Code it: You can use Microsoft Robotics Studio which exposes services to control your Parallax Boe-Bot Kit using Bluetooth.

iRobot Roomba It's not just a vacuum cleaner it's also your programmable minion! You can use the clean-the-house excuse as your justification for getting this friendly house cleaner. Cost: $229 or $339 depending on model Get it: Roomba Red + RooTooth bundle, Roomba Discovery + RooTooth Bundle Code it: You can use Microsoft Robotics Studio which includes built-in services for Roomba programming.

LEGO Mindstorms NXT Lego Mindstorms NXT is Lego's newest release of their popular Mindstorms robotics and includes built-in three motor support and multiple sensor support including motion, touch, sound, and light. Cost: $249.99 Get it: Lego Mindstorms on Amazon.com Code it: You can use Microsoft Robotics Studio which includes built-in services for Lego Mindstorms NXT programming.

GM862-GPS Evaluation Cell phone Kit – USB Looking to write your own cell phone software? Just pop in your SIM card and get to it. Spark Fun has an evaluation cell phone board with GPS that can interface with your computer through USB. Cost: $274.65 Get It: Spark Fun Code It: You can find the documentation for how to start interfacing with the board and Spark Fun provides a Visual Basic example.

White Box Robotics PC-BOTs Whitebox Robotics has created the closest thing to having R2D2 at home with their newly released PC-BOTs. While it's the priciest of all robotics kits, it's hardware is no joke as it includes 1GB of RAM, an 80GB hard drive, Windows XP Home, DVD Drive, and a wireless network card. Cost: $3,995 for the Developer kit, $4,995 to include the ever-so cool panels. Get it: 914 PC-BOT, 9-Series PC-BOT both from PCPowerzone Code it: You can use Microsoft Robotics Studio to program Whitebox Robotics devices (video).

Tira – Infrared Remote Control Receiver/Transmitter Eric Gunnerson pointed us to Tira, or Transmitting InfraRed Adapter, which is a device that enables you to send and receive infrared signals to any IR device, say to control home automation, or to change your TV channel. Best of all, it's fully programmable so you can control when to send IR signals or what happens when it receives IR signals. Cost: $49.00 Get it: Tira 2.1 on Home Electronics Code it: Tira's Developer Page includes a downloadable SDK which includes a DLL that you can call from any .NET language or directly from C++, once you install the Tira drivers.

Programmable Games

Think the final boss is too hard?  "Modify" the game to give yourself that extra edge.  As any Coding4Fun reader can tell you, games are more fun when you can mod them, and we've chosen our favorite moddable games that you can take and extend to your heart's content. 

Rocket Commander Benjamin Nitschke's Rocket Commander is both fun and educational as Ben put together 10 step-by-step videos that show how to build a fully moddable an immersive 3D game using Managed DirectX and C#. Cost: Free Get it: Rocket Commander Game Code it: Watch all 10 videos and download the source code to start building your own RocketCommander mod.

Mech Commander 2 If you're interested in how real commercial games are built, look no further than Mech Commander 2, a real-time strategy game with full source code available released by Microsoft Game Studios. If you're a C++ developer you can learn how to build your own mods to Mech Commander in these three free webcasts Cost: Free Get it: Download the full source code (1GB) Code it: Mike Klucher from the XNA team gave a 3-part on-demand Webcast series on how to mod Mech Commander 2that you should use as your starting point: Part 1, Part 2, and Part 3.

World of Warcraft If you haven't started playing World of Warcraft, you simply don't know what you're missing! With the Burning Crusade Expansion Pack coming out on January 16th, now is a great time to join this ever-evolving world! Cost: $19.99 Get it: World of Warcraft on Amazon.com or pre-order the Burning Crusade Code it: World of Warcraft scripting and add-ins are coded in LUA, which you can add Visual Studio 2005 support (Standard and above), or check out David Nikdel's WoW-360 Project, or UniUploader (screenshot) which enables you to dynamically upload much more detailed players stats to a WowRoster portal.

Neverwinter Nights 2 Limited Edition DVD Neverwinter Nights 2 is a popular Dungeon and Dragons game that enables users to create their own worlds and adventures and includes a large community of users building games and dungeons for you to explore Cost: ~$34.99 Get it: Neverwinter Nights 2 on Amazon.com Code it: The Neverwinter Nights game builder is written in C# using the .NET Framework and you can write Game Builder plug-ins using any Visual Studio 2005 language including VB, C#, or C++.

Civilization IV Sid Meier's Civilization IV is an unlike the typical Age of Empires battle strategy game in that players can use everything from diplomacy to technology to advance their civilization. Cost: $39.99 or $19.99 for the expansion Get it: Civilization IV on Amazon.com or Warlords Expansion Pack Code it: Civilization IV includes a Python and C++ SDK and, while we haven't tried it, you may also be able to call the DLL from VB and C#.

Half Life 2 Holiday 2006 Collection The Half Life 2 Holiday 2006 Collection includes Counter-Strike: Source, Half-Life 2, Half-Life 2: Deathmatch, Half-Life 2: Episode One, Half-Life Deathmatch: Source, Half-Life: Source. The good news is that you can now officially use Visual C++ 2005 Express Edition for your Half Life 2 mods. Cost: $49.95 Get it: Holiday 2006 Collection Code it: Valve's online wiki SDK docs include everything you need to get started including steps to get Visual Studio 2005 working.

Flight Simulator X Deluxe DVD While Flight Simulator X's hardware requirements are quite big, the graphics on Windows Vista using DirectX 10 are nothing short of breathtaking. Cost: $49.99 Get it: Flight Simulator X on Amazon.com Code it: The Deluxe edition of Flight Simulator X includes a new SDK called SimConnect that you can use to manipulate and control the Flight Simulator world using VB, C#, or C++.

Software Tools

Tools to help make video games, robots and webpages oh my! Every good craftsmen needs their tools and we're no exception.  Below is a list of tools and tool add-on's that will make anyone's life that much easier.

Microsoft Robotic Studio If you have LEGO Mindstorm RCX or NXT, you actually can control them through Microsoft Robotic Studio. It can control far more than just LEGO too, it is able to control far more and comes full of examples. Instead of having to deal with low level coding to deal with everything on your robots, one can write a wrapper then have the Robotic Studio do all the heavy lifting! Cost: Free Get it: Microsoft Robotics Studio

Microsoft Visual Studio Express Editions  You can get everything someone needs to code in 6 different flavors. Web Development, SQL Server, Visual Basic, C#, C++, and J# Editions are available for download from Microsoft. They are the perfect gift for the hobbyist, novice or student developer that is looking for lightweight, easy to learn and use tools. Each edition is able to run side by side on your computer with other installations so you can collect them all! Cost: Free Get it: Visual Studio Express Editions

Microsoft XNA Game Studio Express Think you are cut out to build video games? Using Microsoft Game Studio Express you can try out building video games that can be played. If you have an Xbox 360, you can actually transfer the game you created to it too! You can show off to your friends the games you created (Don't forget to add in a god mode for yourself). Cost: Free for Windows/$99 year for Xbox porting and content subscription Get it: XNA Game Studio Express

Paint.NET Paint.NET is a free image and photo manipulation software that is open source too! Paint.NET is written in .NET 2.0 and mostly is c# and has a small amount of C++. It supports layers, unlimited history, a simple and intuitive interface, and is loaded with special effects. While it isn't an Adobe Photoshop replacement, it is simple and powerful enough for someone on a budget. Cost: Free Get it: GetPaint.NET Code it: Paint.NET has a managed API that you can write plug-ins for using any managed language as shown in this Code Project tutorial by Dennis Dietrich.

Reflector for .NET Do you have a program that is written in .NET and you can't figure out how it they preformed a certain task? You thought you fixed that bug but it is still happening after you deployed it. Use Reflector it to see how they pulled it off and verify deployments! Reflector is capable of showing the source code of DLL's in .NET 1.1 and 2.0 in both Visual Basic and Visual C#. What is displayed isn't a 1 to 1 code representation, instead what the ILM runs, however one can figure out how certain tasks are accomplished and should be able to gauge what is happening. Cost: Free Get it: Reflector for .NET

TeamSpeak If you're a gamer, you've likely used TeamSpeak or Ventrilo to have live chat while playing online games. For us, the choice between TS and Vent came down to who has the API's, and it was clear that TeamSpeak is the way to go given its built for extensibility Cost: Free Get it: TeamSpeak Code it: You can find a couple of .NET TS samples including Peter Barette's C# Chat Text application or Oliver Flint's TSDisplay.NET (live demo) using ASP.NET

UltraMon If your coder has multiple monitors, you may think about getting them UltraMon. UltraMon extends out the Windows Taskbar across all the monitors along with the ability to create shortcut keystrokes to send windows to different monitors. In addition, it allows for each monitor to have a different display profile. Plus it has scripting support! Cost: $39.95 Get it: UltraMon Code It: Ultramon has a SDK along with scripting support.

Microsoft Visual Studio 2005 If developing for mobile applications or want to use 3rd party Visual Studio add-ins, you'll need to upgrade to Visual Studio Standard or Professional Edition. Visual Studio Express Editions projects will seamlessly work with the full versions of Visual Studio. Cost: $179 - $679 Get it: Standard Edition (upgrade price), Professional Edition (upgrade price) Code it: Visual Studio 2005 includes a free SDK that you can use to create your own add-ins or even your own programming language.

JetBrains ReSharper ReSharper is an add-in to Visual Studio 2003 and 2005. ReSharper provides an intelligent coding assistance, on-the-fly error highlighting (no more recompiling), additional searching and navigation features, unit testing, and realy time analysis of code warnings / errors … the list goes on and on. JetBrains ReSharper is free to try out for 30 days, $200 for a full copy. Cost: $200 Get it: JetBrains ReSharper Code it: ReSharper has an open API which you can use to modify how your code is refactored.

WebSuperGoo ABCpdf PDFs are everywhere and progressively more applications are needing them. AbcPDF allows a developer to easily manipulate or create dynamic PDFs. It is fully multithreaded and is loaded with stock full of examples to figure out everything. Past just normal PDF generation, it also can do HTML to PDF generation. Cost: $328, Possibly free if you link to them. Get it: WebSuperGoo Code it: Here is their API for ABCpdf.

Top 10 Cool Presents for Developers

What are your top 5 favorite ... wait, this isn't a movie.   Here are what Coding4Fun would deem Top 10 cool presents for Coders.  Some range from a magazine subscription to DNA.  Each one is

Optimus mini three keyboard Wondering how much CPU or RAM your system is taking up? How about what the weather is? The Optimus mini three keyboard allows you to view what is going on in the world with animation. Cost: $159.99 Get It: Optimus mini three keyboard on ThinkGeek Code It: The Optimus Mini has a c# library to use along with other languages which can be found here.

O'Reilly Safari Books Online Subscription Wonder why FireFox and Internet Explorer's JavaScript Dom acts different for the same property?  Me too.  That is why I have a ton of O'Reilly books at my desk.  With their online solution, one has the entire library to their disposal.  No need to go through pages upon pages of search results! Cost: $39.99 per month Get It: Safari Books Online

MAKE Magazine MAKE magazine is a magazine that actually encourages you to break your warranties. Wonder how to do modify your camera to do strobe photography, they'll explain how to create a rig to create. How about a toy gun alarm clock? A jet made out of a jar? A 5-in-1 network cable? These are just a few of many things they show people how to make in their quarterly magazine. In addition to their magazine, they have a great blog over at http://makezine.com/blog/. Cost: Register your copy of Visual Studio Express and get 5 issues for the price of 4. Get it: Make Magazine

Color Call You're in the middle of a meeting and you're up on the whiteboard. The phone rings, should you answer? Find out easily with the Color-Call Caller ID System which enables you to setup which phone numbers should correspond to up to four different colors.  Cost: $29.99 Get it: Color-Call Caller ID from Brookstone

Scrolling LED Belt Buckle Nothing says geek chic like a scrolling LED Belt Buckle.  It can hold up to six messages at a time with each message containing 256 characters. You can see pictures of our very own Sara Ford wearing the Scrolling LED Belt Buckle. Cost: $29.99 Get it: Scrolling Belt Buckle

Self Destruction Button USB Hub You can't go wrong accessorizing your office with this custom USB Hub that would be perfect for Dr. Evil.  Just remember, do not press the red button no matter how much you want to. Cost: $64.66 Get it: Self Destruction USB Hub from GeekStuff4u.com

Alesis USB Podcasting Kit For your inspiring Podcaster, the Alesis kit takes the guesswork out of podcasting. It comes with an 8-Channel USB Mixer, dynamic microphone, stand, and headphones. It also comes with 30 days of free hosting for your podcasts. Cost: $250 Get it: Alesis USB Podcasting Kit

Matrox DualHead2Go / TripleHead2Go Afraid which new video card is right for you or are you on a laptop? The Matrox allows a coder to have up to three monitors with the TripleHead2Go (two with the DualHead2Go) with only one video input. Multiple monitor support is build into Windows. While having that many monitors may seem a tad excessive, they do help boost productivity and help the keep workspace less messy. Cost: $169-$299 Get it: Matrox Products

DNA Portrait The ultimate in personalized artwork, this portrait is created by using your actual DNA and comes in fun color choices like Firesky, Ice, Citylights, and Citron Cost: $390 for 18” x 24”, $490 for 24” x 36” and $790 for 36” x 54” Get it: DNA11

22”+ wide screen monitors What is better than having dual monitors? Dual 22” widescreen monitors. Bigger monitors aid in the ability to read more and have been shown to have boost productivity 10 to 44%. Please verify the graphic card / device they have can support a monitor of this size. Cost: $400-$500 Get it: Dell or NewEgg lists of 22”-23”+ or 23”+

C++ Programming Books Every programmer needs C++ books. Some need a C++ GUI Programming Guide while others need a primer book.  The gift of reference books is always a good bet. Cost: $30 to $50 Get it: Amazon

Happy Holidays From Coding4Fun!

Now only if I can get someone to get me all these gadgets, software, and toys, I mean highly educational, non-fun devices.  Thanks for reading and if you think we've missed any awesome holiday gift, please Email us and we'll get it added to our list.  If you like the guide, Digg Us.

One way to get started programming games is to pick a popular game that is fun to play, that has all of the rules already made up, and develop a program that just transfers that game to the computer. Doing that much will help beginning programmers raise their programming skills as they code and tweak their own rendition of the fun game. A Christmastime example of that method accompanies this article, programmed using a relatively new programming language designed to help beginners gain programming skills. Kids' Programming Language (KPL) is a simplified but modern programming language and development environment that introduces beginners to the basic programming concepts. Just as many famous sports players start out playing sports while they're young, KPL is a tool kids can use to program computers while they are still young. With KPL being a free download, it is well within their budget!

The referenced KPL game is called Santa's Gifts, but it is very similar in nature to the popular Tetris genre of falling objects that need to be properly positioned for optimum points. The rules and game play is simple to learn, but strategically placing the falling objects will give the advanced players higher scores. Using the arrow keys to move the objects from side to side allows the player to position them where they want. Pressing the Down arrow key lets the object drop. When three or more objects of the same type are positioned together, they form a group that is removed from the drop zone, adding some number of points to the player's score. The strategic part of the game is to try to build groups of four or five items, or to try to cause chain reactions where the removal of one group causes another group to be formed and removed. Both of those methods yield more points than just creating groups of three. There is a time aspect to the play as well. The player can't take all day to decide where to position the next item. The time to decide is decreased as the levels progress, which will cause the player to have to recognize certain patterns that score better, decide on a strategy to complete those patterns, and go for it in a relatively short period of time.

Do some functional testing

If at all possible, create the game on a piece of paper first, or use pieces of paper to represent objects in the game, and set it all out on a table top to run through the game a few times. Get input and feedback from other game players, and check it over to see if the rules are easy to learn, and if there is opportunity for advanced players to gain an advantage at beating the game. You'll want to iron out the problems and any other conflicts on paper as much as possible before they become problems while writing the game code. It is much easier to change a rule on paper than retrofit a new rule into the computer program. For the simpler games, some may do all of that planning and checking in their head, as I know I did on more than a few occasions, but it cannot be stressed enough to do the planning first, to avoid scrapping or re-writing whole sections of code.

As I mentioned before about the sports heroes playing the sport while they were young, it takes many years to develop the skills needed to play professionally. They certainly didn't do everything right while they were learning. Expect a little of that in yourself. Those professional players didn't quit, and they kept going until they made it to the top. That sort of perseverance is what you'll need to get past the few failures that may happen. If you can't get the programming to work one way, try another route. Don't be discouraged about starting a project over, or trying to do it in a new way, especially as you begin to develop your skills. Mentors, or others familiar with the tools you are using, are a good source of information and can help you find the right path, instead of the trial and error mode of learning.

In summary:

Begin a new game by writing the storyline. Describe where the player is coming from, and where he has to get to. Include the objects or obstacles he will meet along the way, and then move on to creating the rules of engagement. Pretend your table top is your computer screen and cut out pieces of paper to represent the objects the player will see on the screen. Play the game several times, taking notes of any conflicts or other ideas that will be included in the game. Refine the movements and game play such that a child can learn it fairly quickly and figure out how to add something the advanced players can use to gain an upper hand. Begin coding the program by adding just a shell that shows how the screen will look, and provide the means to start the game, and whatever needs to happen to end the game. Then start adding routines to get the game up and running. For example, if there is going to be five levels to the game where each level shows a different screen, then start with a loop in your main procedure that iterates 1 to 5, that will call the routines to draw the different screens as they are needed. Just get the basic shell in place as the starting point. Then add the objects that make up the game, such as adding the player to the screen, and allowing him to move in each of the levels. Then add the objects to the different screens, or whatever the player will be interacting with, and so on. Piece by piece, build the game by providing the skeleton and then adding the meat. You can do that on the whole game level, and on a finer level for different routines. Be mindful of saving your work at different milestones, and then working with a copy from there. You should save your work periodically, at various milestones, so that if the day happens where your file gets corrupted, or you code yourself into a corner, you can go back and make another copy of the last milestone and get back into it, instead of having to start all over from scratch.

About the game listing...

For those who are going to be looking at Santa's Gifts source code, I want to point out a couple techniques that might be useful in your own games. The first is in translating a one-dimensional array into something that represents the two-dimensional screen; specifically, checking for objects that are in the immediate area of the player. The second is the method I used to create the fading points that are shown when groups are removed from the play area. For people who do not yet have a copy of KPL, you can learn more about it from www.kidsprogramminglanguage.com.

KPL only supports arrays of a single dimension, so representing two-dimensional space takes a bit of doing. In particular, X and Y coordinates have to be translated into an Index value that points to an element in the array. In general terms, transposing between the two can be shown by the following code:

// XMax is the maximum extent of the 2D space in the horizontal direction 
X = Index Mod XMax
Y =  Index / XMax
Index = X + (Y * XMax)

That works when the arrays begin with the first element at index 0. Currently KPL begins its arrays at an index of 1, (but that may change!), so the above code becomes:

X = (Index - 1) Mod XMax
Y = (Index - 1) / XMax

Because the KPL single dimension array uses the Index value to reference its elements, it is more often easier to work with the 2D grid cells by manipulating the Index value, instead of the X and Y values. When the game code has to check for any objects in a grid cell adjacent to the player, it can test the next cell to the right by adding 1 to the player's Index value, and the cell to the left by subtracting 1 from the player's Index value. Similarly, to check the next cell above or below the player, XMax can be subtracted or added (respectively) to the player's Index value. Of course boundary checks are needed to avoid looking above the top edge or below the bottom edge, which are easily handled by testing the adjusted Index value to be between zero and the upper bound of the KPL array. But boundary checks on the right or left edge are more difficult to handle when using the Index value.

To represent a checkerboard, for example, the KPL array would hold elements indexed from 1 to 64 which represent the 8 X 8 grid. A value at Index 1 is the same value for the grid coordinate (0, 0) or (1, 1) depending on which value you prefer to begin numbering with. Assuming the upper left cell is at (1, 1) then the next cell to the right of the upper left cell is at (2, 1) with an index of 2, (3, 1) is Index 3, (4, 1) is Index 4, and so on to the upper right cell which is at (8, 1) corresponding to the KPL array Index value of 8. The cell below the upper left corner cell is at (1, 2) which equates to an index value of 9. And so it goes with the Index value incrementing by one as the grid cells are traversed left to right and top to bottom.

The trouble arises when the player is at the right or left edge, because adding one when the player is at the right edge, or subtracting one when the player is at the left edge will actually be referencing a cell from a different row. If the player is at cell (8, 1) or Index 8, then the code must not add 1 for the adjacent test because the player is at the edge; there is no cell at (9, 1).

One way to avoid overstepping the boundary is to convert the Index value back into its X and Y coordinates so you can test X in comparison with XMax. But there may be many places where such a check is made, which would require many such conversions. Even if centrally located in a function somewhere, the code must be called, which takes some amount of time, repeatedly, over and over, every time such a test is needed.

The method I used instead of repeated boundary conversions effectively adds a blank cell to the right edge of the 2D space. The KPL array was lengthened to account for there being a cell there, but it was never used for player movements. What it did was avoid the need for special case tests for the right or left edges. Upper and lower boundaries were still in place, but adding that extra cell meant I could simplify the code used to test the adjacent cells. I could safely increment the Index and check for objects for tests to the right, and I could safely decrement the Index value and check for objects to the left because there was that extra cell at the end of each row. Tests to the left when the player was at the left edge found a blank cell (obviously no object there), and tests to the right when the player was at the right edge also found a blank cell. With a little tradeoff in memory usage, I simplified my code considerably. Check out the CheckAdjacent routine in the game source code. It turned out to be nice uniform code that tests for upper or lower boundaries ahead of comparing the objects for similarity. That is the code used to find all the members of the same type for inclusion into a grouping. If a similar gift is found in an adjacent cell, then adjacent cells to that one have to checked for further similar gifts. If checking there finds one in an adjacent cell, then that new one has to have its adjacent cells checked as so on, to find all the gifts of the same type that are next to each other. You'll note the repetitive nature of those tests made for a good place to use a recursive call (where some routine calls itself to complete its task), but recursion is entirely another topic, worthy of its own detailed discussion.

The second technique I wanted to mention allowed me to print text on the screen and have it fade away. It was just one of those what-if discoveries I made while looking for a simple way to show the points for the currently removed group, without it remaining on the screen too long. I had used the Status area, but I didn't like how the points shown there seemed to be more like debugging information and not really a part of the game. What I did was take part of the screen image and make it partially transparent using my favorite paint program. I placed that translucent image in a sprite and used KPL's StampSprite method to transfer the image to the screen. I found that I could print text to that area, and periodically stamp that translucent sprite over the text which would gradually erase the text. I also used that method to provide the BRIGHTNESS constant you'll find near the top of the listing. It controls the brightness of the background image. I didn't want the background image to be so bright as to distract from the animated gift images. I wanted a kind of lower-contrast image to avoid that distraction. When I found the translucent sprite could be stamped in place several times to build up to being opaque, I decided that would be how I could lower the contrast of the background, by making the background sprite translucent. It has to be translucent over some color or shade, and that is what the BRIGHTNESS value controls: it decides the brightness of the gray color used behind the translucent background image.

One final note on playability. On faster computers you may find that the program runs way too fast to play. That is the way I have grown accustomed to designing programs. Design them so they can play faster than the human can because the computer can easily be slowed down to let the human catch up, but it is usually more difficult (or nearly impossible) to try to speed up a program when it runs too slow. Also near the top of the listing is a TIMEDELAY constant you can adjust to slow down the game more to your liking and abilities.

I hope you enjoy playing Santa's Gifts, and that you'll take up writing and sharing programs of your own design! If you need beta testers for your KPL program, or have questions or comments, do visit the KPL forums available from links in the help menu of the KPL environment.

Ho Ho Ho! Merry Christmas! Happy Holidays! Ho Ho Ho! Naughty or nice? We don't really want to know! Ho Ho Ho!

Have you seen the previous articles here at Coding4Fun about KPL, the Kid's Programming Language? The overview and the article on KPL Pong. KPL is not just for kids; it's for anyone who wants to code fun stuff fast. Proving the point, we're working on a couple of Holiday-themed KPL games and articles—like this one, ChristmasTreeShooter.kpl! We have a fun and easy suggestion for how you and family or friends can modify the game yourself, too.

For some unknown reason, your Christmas tree is bobbing and weaving unpredictably before your eyes. It just won't hold still! And you have the rest of these ornaments that you have to hang on the tree, or you can forget about opening that green box. You suspect it's got an Xbox 360 in it, and going with that theory, you're not shaking it like the others. Just in case. Anyway, you do your best with the ornaments, and Santa rates your performance at the end. Not a guy you want to disappoint, coming down to that Christmas Eve wire...

This KPL game was implemented in 161 KPL instructions, and will be simple code for an experienced or hobbyist programmer to follow. It uses sprites for graphics and uses custom sound clips, which we're going to show you how to replace with your own voice-overs. What are friends or family going to say when it's you who rates their performance? Are you going to be deadpan and droll? Acerbic and insulting? Will you do a Santa voice, a Mrs. Claus voice or an Elf voice? However you record it, you know it'll be fun!

Chances are, if you're here at Coding4Fun, you're more than just a beginning programmer—but I bet you can think of some friends or family who might like to be a beginning programmer? Well, we made KPL for them—and you helping them learn with KPL should make it fun and easy for both of you. This game ought to catch their interest, but if they're a novice perhaps you can help them through the Beginning Programming with KPL Tutorial before you work with them on this or other KPL game code.

Just the interesting stuff, please

This article will assume some basic programming skill, and rather than explaining every line of code in the KPL program, will focus on key techniques or algorithms which will be useful as you develop your own KPL games:

• Finding free images online
  
  
• Using Sprites in KPL
  
  
• Recording and using custom sounds
  
  
• Using Arrays
  
  
• Handling keyboard input
  
  
• Sprite interaction
  
  
• Allowing user customization of game behavior

Before we begin, the article will make the most sense if you have installed KPL, and downloaded and unzipped the Christmas Tree Shooter program underneath your KPL install folder. The ideal way to start, of course, is to load ChristmasTreeShooter.kpl in the KPL IDE, click "Run the program," and play it a few times before examining the code.

KPL and this program are both available as freeware downloads from: http://www.kidsprogramminglanguage.com/download.htm. KPL does have a dependency on the .NET Framework 1.1, and the KPL install will "auto-magically" download and install the Framework if it is not already installed on your machine.

Finding Free Images Online

There are many many places online that offer free images that you can reuse in your own KPL programs. An MSN Search for "Christmas Tree Clipart" returned 589,677 search results when I ran it. Here's the page where we found our Xmas tree:

http://www.geocities.com/~bug_hut/Christmas/trees.html

That particular page is of interest because it's been viewed over 200,000 times—who'd have thought?!? And because it is the only web page I can think of using a background WAV file that I actually liked hearing!

KPL supports images in all standard file formats, including GIF, JPG, PNG, TIF and BMP. KPL does support animated GIFs, but those are not used in our Christmas Tree Shooter. If you're using Internet Explorer, saving an image you find on the Web for reuse is easy: right-click the image, and select "Save Picture As...". KPL will automatically find an image by file name if the image is in the Media\Images folder under the KPL installation folder; if you expect to use an image from more than one KPL program, this is the right place to put it. If an image is specific to the program you are working on, you can leave the image in the same folder as the .kpl program itself. KPL will find it in the local folder, looking there first before checking the Images folder.

Of course, the caveat about finding images online is making sure the site allows you to reuse the image. Image reuse happens all the time on the Web, but of course, if you find an image with a copyright or other usage limitation stated on the page, you will want to comply. There are many many freely usable images out there, so it's safest and simplest to keep looking until you find one with no strings attached.

Using Sprites in KPL

Here's a single method we coded that wraps the basic KPL sprite commands into one:

Method LoadSizePlaceSprite(name As String, file As String, 
                           scale As Decimal, x As Int, y As Int)
    LoadSprite( name, file ) 
    ScaleSprite( name, scale )
    MoveSpriteToPoint( name, x, y )
    ShowSprite( name )    

End Method

This allows a single call to load, place and display a sprite:

LoadSizePlaceSprite("TREE", "Christmas Tree3.png", 1.50, 
                     TreeX, TreeY )

The name parameter gives the sprite a name which you will use to refer to it when you manipulate the sprite.

The file parameter is the filename to the image file which will be used to represent the sprite on-screen. No path is required to the filename, but the file must be in the local folder with the .kpl program, or in KPL's Media\Images folder.

The scale parameter is a size multiplier for displaying the sprite. 1.0 is no size change, 0.5 is half size, etc…

The x and y parameters specify the screen location where the sprite will be displayed, in pixels, with the default being that the upper left corner of the window is location (0, 0).

KPL defaults all sprites to the same ZIndex of 0—all sprites are drawn or rendered on the same layer, so the last one drawn always appears "on top." SetSpriteZIndex(name, ZIndex) can be used to specify the ZIndex to control this. Sprites with a higher ZIndex will always be drawn on top of sprites with a lower ZIndex.

SetSpriteZIndex("Ball" + BallCount, 10)

Other Sprite-manipulating methods used in ChristmasTreeShooter.kpl are:

HideSprite() takes the name of the sprite which is to be hidden when it is no longer needed:

HideSprite("CrossH")

GetSpriteHeight() and GetSpriteWidth() return a height or width in pixels of the sprite:

GetSpriteHeight( "CrossH" )

SpritesIntersect() takes the name of two sprites, and returns true only if they intersect or overlap on the screen:

If SpritesIntersect("TREE", "Ball" + OrnamentCount) Then

That's all the Sprite code used in ChristmasTreeShooter.kpl. We have designed KPL to be as simple and as highly leveraged as possible, and this is particularly visible in KPL support for Sprites.

Recording and using custom sounds

This KPL program uses custom sounds for Santa's rating of your performance at the end of the game. As with images, sound files can be placed in the same folder as the program if they are used only for the program. If you'd like to share the sounds across more than one program, they can be placed into the Media\Sounds folder underneath KPL's install folder.

The sounds used for the game were recorded using the Sound Recorder, which is available as part of all versions of Windows. You can launch it from Start Menu > All Programs > Accessories > Entertainment > Sound Recorder, or by running sndrec32.exe from the Start > Run... dialog. If you've been a geek long enough, that file name will remind you of the good (?!?) old days. Not only of 32-bit Windows, but of 8-character MSDOS file names. Amazing thing is, that really wasn't very long ago.

The File menu and the tape-deck style button bar are all of the Sound Recorder that you'll need to use. KPL currently supports .WAV file formats. We're adding support for more sound formats—as well as the ability to play multiple, layered sounds—to KPL v 2, which is targeted for a January 2006 release. Any other program which allows recording or editing supported sound files can be used instead of the Sound Recorder, or course.

So, here's a fun, easy customization: use Sound Recorder to record and save your own version of the following sound files in place of ours! Here are our sounds and their scripts:

HoHoILikeIt.wav: "Ho Ho Ho! I like it!"

HoHoTryAgain.wav: "Ho Ho Ho! Try again!"

You can, of course, say anything you like, and/or give your recordings a different name. If you do use a different name, you'll need to change the following lines of KPL code to match:

If HitCount = 5 Then
    PlaySound( "HoHoILikeIt.wav" )
Else
    PlaySound( "HoHoTryAgain.wav" )

End If

Using Arrays in KPL

KPL does support the use of arrays, as well as user-defined structures. KPL v 2 will add support for user-defined classes—an ideal way to encapsulate logic such as the handling of our Christmas tree ornaments. Until then, we kept this simple by using arrays to handle the five of them:

Define BallX As Int[5]
Define BallY As Int[5]

Define BallOffset As Int[5]

And here is an example from the program showing the use of these arrays:

    BallOffset[OrnamentCount] = BallX[OrnamentCount] - TreeX 

Handling keyboard input

A simple model for coding a game in KPL is a large loop which, at a controlled interval, processes user input and game events. Here is our Method Main(), which shows how this loop is the basis of the processing for the program:

Method Main()
    SetupGame()
        
    // Show Instructions    
    Alert("Use the Arrow keys to move the shooter and tap the 
           Space Bar to place an ornament. Placing an ornament 
           on another will break both!", "How to play!") 

    Define CurrentTime As Decimal 
    Define TimeLastChecked As Decimal
    
    // Start the wait time for the Space Bar to prevent the Key 
    // Bounce effect     
    LastOrnamentFireTime = TickCount()

    While GameOver = False
    
        CurrentTime = TickCount()    
        
        // If 60 milliseconds have not passes since the last 
        // time we checked, we don't do anything yet.
        If CurrentTime - TimeLastChecked > 60 Then 
            // Every 60 milliseconds (that's 17 times a 
            // second!) we fall into this block.
            // First we process Key events to move the
            // targeting circle        
            ProcessKeyEvents()
            // Then we MoveTheTree.
            MoveTheTree()
            // We reset the timer each time, so we wait 
            // another 60 milliseconds before moving again.
            TimeLastChecked = CurrentTime
        End If
        
    End While
    
    GameOverShowTree()
  
End Method

The actual processing of key events is done in the ProcessKeyEvents() method, using the IsKeyDown() function:

    If IsKeyDown( "Up" ) Then
        If CrossHY > 10 Then
            CrossHY = CrossHY - CrossHairSpeed
        End If

End If

The key processing code checks for all keys that are relevant to targeting movement, and will handle any and all keys that are down. It also uses logic as shown above so that keys which would cause the targeting circle to move off the viewable screen are ignored.

One issue caused by processing keys in a loop this way results from the fact that the computer loop can be so much faster than our own fingers on the keyboard, which can result in processing the KeyDown more than once on a single tap of the Space Bar. When the single Space Bar keystroke is as important to the game as it is here, we must add a little extra code which makes sure we don't process that Space Bar keystroke more than once. The following code, at the bottom of the ProcessKeyEvents() method, does this using the global variable LastOrnamentFireTime:

// Process the wait time for the Space Key to reduce the Key 
// Bounce Effect.  If it's been less than 200 milliseconds...
currentTime = TickCount()
If (currentTime - LastOrnamentFireTime) < PlayerOrnamentFireDelay Then
    Return // Exit the method without processing
End If
If IsKeyDown( "Space" ) Then
    LastOrnamentFireTime = currentTime
    ShootOrnament()

End If

Sprite interaction

What you are attempting to do with this game, of course, if place each of the five ornaments onto the bobbing and weaving Christmas tree, without breaking them. Since the tree and the ornaments are all implemented as sprites in this KPL program, this is as easy as checking to see whether the sprites "intersect" when you hit the spacebar to place an ornament. The code for this is in method ShootOrnament():

If SpritesIntersect("TREE", "Ball" + OrnamentCount) Then
    PlaySound( HitSound )    
    // if we hit the tree count it and show it
    HitCount = HitCount + 1
    // calculate the ornament offset
    BallOffset[OrnamentCount] = BallX[OrnamentCount] - TreeX 
Else
    // if we miss the tree all together don't count or show ornament
    PlaySound( BreakSound )    
    HideSprite("Ball" + OrnamentCount)    

End If

Note that if we actually got the ornament on the tree, we figure out its Offset so we can later move it along with the tree. And if we miss the tree altogether, the bulb breaks and is not shown.

These ornaments are those fragile little glass balls—proof that guys have no business decorating Christmas trees, right?!? If we actually shoot one glass ball on top of another, well, they both break, Santa is less than pleased, and we might never get to open that green box! Here are the nested For...Next loops that check for this:

For Ornaments = 1 To OrnamentCount
    If Ornaments < OrnamentCount Then
        For OtherOrnaments = (Ornaments + 1) To OrnamentCount
            // Process balls hitting balls, don't count them and 
            // don't show them
            If SpritesIntersect("Ball" + Ornaments, "Ball" + 
                                 OtherOrnaments) Then
                PlaySound( OrnamentHit )
                HideSprite("Ball" + Ornaments)
                HideSprite("Ball" + OtherOrnaments)
                HitCount = HitCount - 2
            End If
        Next
    End If
Next

Besides nested loops always being fun exercises of logic, this is interesting because it shows how easy it can be to use an automatic type conversion to build a string from a number. Our sprites are named Ball1 to Ball5, and when we need to process them in a loop this way, we can simply construct the name by concatenating "Ball" + Ornaments, where the latter is the integer loop index.

Allowing user customization of game behavior

Besides being educational, open-source KPL games have the advantage of allowing a user to change or customize the game behavior. The entire game and all its code is there for the user's modification, but it's also worth putting a little thought and effort into allowing easy customization of the behavior of your game. Our Christmas Tree Shooter does this with three global variables, defined, commented and changeable up at the top of the program file:

// Set these next 3 variables to affect game play
Define CrossHairSpeed As Int = 20
Define TreeSpeed As Int = 20
// how many times the tree will move before game is over

Define MoveCount As Int = 2 // = once to the right, once to the left

Good naming and comments make this pretty easy for users to find and change. The two speed variables can be tweaked to make the game easier or harder, depending on the user's reflexes. And the move count can be increased to lengthen the game and allow the user more time.

Building in game settings based on global variables like this just takes a little thought, and can allow a fun extra level of control for people playing your game.

What's next?

Two or three other Holiday-themed KPL games should also be up on the Coding4Fun site. Have fun with them, and Happy Holidays—no matter which particular Holiday you're celebrating at this time of year!

KPL Asteroids is also next in the series of retro games implemented with KPL—watch for that in the next couple of weeks!

There are now dozens of open source KPL games, and dozens more educational programs—either included in the base KPL install, or new and separately downloadable. Check them all out at http://www.kidsprogramminglanguage.com/download.htm.

Moral of the story? Coding4Fun isn't just a name—it's the point!