The Serial Killer Tooltip

Firstly, having seen in my statistics a search term used to find my last post, I feel I should point out how I came upon the name for my Serial Port Terminal Application.  I was poking fun at it being a “Killer App” (because really, if there was any software which proves Serial Comms as a technology, it was written years ago).  Combine that with Serial and you have a terrible pun, which seems to be one of the most important things of Free and Open Source Software.  This is not a post about the other type of serial killer.  Or indeed, a full time one.

For such a small feature of my program, the tooltip which shows up the timestamp of the time data was sent or received has caused me more consternation that probably the rest of the program put together.  I had to touch each of the three layers of my model-view-controller, with the smallest modifications going to the controller, which is odd – in general, the bulk of the functionality of an app should live in the controller.  So here’s how I did it…

After thinking about the UI briefly, taking my existing GTK+ knowledge, I decided it was going to be best to start with the model.  When I first started writing this app, I had imagined a feature like this and broke the YAGNI rule.  I had previously included a timestamp in the data I was collecting about the data to-ing and fro-ing.  My previous code was exhibiting a massive performance problem with the linked-list I was using, in that it was grinding to a halt whenever I clicked the switch to hex mode button.  I therefore decided that if I wanted to search this thing with decent performance, I would need to step my storage up a notch.  For this, I chose to use an in-memory sqlite database.  At work I’m already getting into a SQL head space, I’ve worked with sqlite before, and of course, its license terms make life easy for including in my liberally-licensed program.

Create a table, drop in the data as it arrives and pull it out in the most straight-forward manner imaginable.  I was worried that it would be a performance bottleneck, but I wanted to let the database prove itself otherwise.  Turns out it was good enough.  No reason to get fancy until the simplest thing isn’t possible.

Now for the interesting bit.  How do I pop up an arbitrary tooltip on the same widget, based on the text underneath the mouse?  This took a bit of doing.

First things first, we need to know the position of the mouse.  I attached to the MotionNotify event on the TextView, so now every time the mouse moves I store the X,Y coordinates for later.  As a proof-of-concept, I set the tooltip text during the MotionNotify event and voila, I had an arbitrary tooltip based on the mouse cursor position.  It was starting to be shaped like the actual feature.  I didn’t really want to store it myself, and I was kinda hoping that I would find an event with the mouse X and Y coordinates attached, but I’m not that lucky.

After several mis-fires and some failed attempts at googling, I eventually came upon the QueryToolTip event.  I think I tried this one pretty early on, but it turns out you need to set “HasToolTip = True” on the widget for which you’re hoping it will be called and you need to set the args.RetVal = True or nothing will show up.  Tricksy Hobbitses.

_textView.HasTooltip = true;
_textView.QueryTooltip += _textView_QueryTooltip;
...
args.Tooltip.Text = string.Format("X:{0},Y:{1}", mouseX, mouseY);
args.RetVal = true;

The next problem is knowing exactly what piece of text is underneath the mouse cursor.  We know the window co-ordinates, but that doesn’t help.  For a second there, I thought I was going to have to do some stupid math based on the font size, and the buffer lines, which would almost certainly turn out to be wrong or not accurate enough in all but the simplest of cases.  Luckily, it’s a common enough thing for GTK+ to have support for it built it:

int x, y;
_textView.WindowToBufferCoords(TextWindowType.Text, (int) mouseX, (int) mouseY, out x, out y);
var bufferIndex = _textView.GetIterAtLocation(x, y).Offset;

So that gives us the buffer index – that’s a solid start!  But it only tells us the character, not the timestamp associated with it.  So it’s time to revisit the database.  Every time we add data, we now need to know whereabouts in the buffer it sits.  So the simplest thing possible is to keep a running total of the buffer and add the length of the data whenever we dump data in the database.

It is now time to explain what I meant by the comment “My previous code was exhibiting a massive performance problem”.  When I started attempting to pull the timestamps out, I was either getting results that were wildly wrong or exceptions were being thrown with no clear reason.  The database decision really came into its own at that point, as I was able to just save the whole thing to a file and dissect it.  As soon as I opened it up and did a SELECT *, it became clear to me that I was storing waaay too much data.  I was storing the whole 256 byte buffer, regardless of how much data was actually sent.  I was storing the length of the buffer, rather than passing up the number of bytes I actually received.  Whoops.  Turns out it wasn’t a performance problem or a hex conversion problem or any of the other things I had considered.  I was just doing something dumb.  A quick fix and my performance problem disappeared, along with the conversion issues.  I was quite excited about that!  To the point where I re-instated the sent / received tag and the performance was still acceptable.  Great Success!!

So to round the feature out, it was a completely obvious SQL query and performance appears good enough.

DateTime result = DateTime.MinValue;
using(SqliteCommand dbcmd = _dbConnection.CreateCommand())
{
   dbcmd.CommandText = string.Format("SELECT time FROM SerialData WHERE " +
                                     "bufferIndexStart <= '{0}' AND bufferIndexEnd >= '{0}';", bufferIndex);
   var reader = dbcmd.ExecuteReader(System.Data.CommandBehavior.SingleResult);
   if (reader.Read())
   {
      result = DateTime.FromBinary(reader.GetInt64(0)).ToLocalTime();
      reader.Close();
   }
}

In the end, it was actually really obvious, but it took a bunch of google mis-fires to get there.  I wanted to add a scathing remark about the GTK documentation, but when I search there now, I find exactly the information I needed, including the caveats I mentioned above.  I still want to blame them somehow, but I haven’t figured out how I can do that successfully.