The first thing was a class that wraps the Dragon curve code.  There is one main entry that returns a PdfPath that represents the curve.  You could parameterize it further by exposing length and split.

    public class Dragon

    {

        private static double _sqrt2 = Math.Sqrt(2.0);

        private PdfPath _path;

        private double _angle;

        private PdfPoint _currPoint;

        private void Turn(double degrees)

        {

            _angle += degrees * Math.PI / 180.0;

        }

        private void Forward(double length)

        {

            _currPoint = _currPoint + new PdfPoint(Math.Cos(_angle) * length, Math.Sin(_angle) * length);

            _path.LineTo(_currPoint);

        }

        private void MakeDragon(double length, int split, double d)

        {

            if (split == 0)

            {

                Forward(length);

            }

            else {

                length /= _sqrt2;

                Turn(d * 45);

                MakeDragon(length, split - 1, 1);

                Turn(-d * 90);

                MakeDragon(length, split - 1, -1);

                Turn(d * 45);

            }

        }

        public PdfPath MakeDragon(IPdfColor color, PdfPoint startLocation)

        {

            _angle = 0;

            _currPoint = new PdfPoint(startLocation);

            _path = new PdfPath(color, .75);

            _path.MoveTo(_currPoint);

            MakeDragon(400, 12, 1);

            return _path;

        }

    }

All that remains is to use this class in the context of a PdfDocument.  First, I make a document,  then a page, then I place the output of the Dragon class on the page.  One thing you’ll note is that to make the page, I use the PdfDefaultPages class which is a set of factory properties each of which generates a new page in the size and orientation indicated by its name (I could’ve said eponymous size and orientation, but then I’d get a talking to about keeping my writing accessible.  Have I mentioned that I love language recently?).

    static void Main(string[] args)

    {

        PdfGeneratedDocument doc = new PdfGeneratedDocument();

        doc.EmbedGeneratedContent = false;

        PdfGeneratedPage page = PdfDefaultPages.LetterLandscape;

        doc.Pages.Add(page);

        Dragon dragon = new Dragon();

        page.DrawingList.Add(dragon.MakeDragon(PdfColorFactory.FromRgb(.8, .25, .8), new PdfPoint(250, 250)));

        doc.Save("dragon.pdf");

    }

Seriously, that’s it.  It’s a nice short, sweet example.  Download DotPdf and run the code – you get a free trial!

First, let’s consider why we even have data files.  Persistence of data is one reason, but historically you would frequently see data files built because you couldn’t keep the entire dataset in memory.  In the dim dark ages, you were lucky if you had virtual memory (I’m looking at you, Macintosh System 6 and earlier) or if it was lousy (I’m looking at you Windows 3.1 and earlier), so you would try to keep your memory footprint low.  The obvious solution is to dump things to a temporary file then read them back in later when you needed them again.  The trick is that you want to incur as little overhead as possible, so your reading and writing code had to be simple.  A typical data structure might look like this:

typedef struct t_person {

    char gender;

    char age;

    char firstname[14];

    char lastname[16];

} t_person;

OK – that’s a quick, badly-designed structure for representing a person.  So how would you write it out?

if (fwrite(somePerson, 1, sizeof(t_person), fp) != sizeof(t_person))

    return FALSE; /* fail */

We like fwrite, oh yes we do.  So much so that if we have an array of t_person, we might write this routine for dumping it out:

int writePeople(t_person *people, int count, FILE *fp)

{

    int totalBytes = count * sizeof(t_person);

    return fwrite(people, count, sizeof(t_person), fp) == totalBytes;

}

and then you think – oh dang, I didn’t write out how big the array was and  then you realize that you’re filling a temp file with many heterogeneous types and wouldn’t it be better if the file was self identifying?  So then you would write code like this:

int writeTag(INT32 tag, FILE *fp)

{

    return fwrite(&tag, 1, sizeof(INT32), fp) == sizeof(INT32);

}

int writePeople(t_person *person, int count, FILE *fp)

{

    if (!writeTag(kPersonTag, fp)) return FALSE;

    if (!writeTag(count, fp)) return FALSE;

    int totalBytes = count * sizeof(t_person);

    return fwrite(people, count, sizeof(t_person), fp) == totalBytes;

}

and by solving a problem (forgot the array length and didn’t identify the type, I’ve created several new problems.  First of, fwrite was fine to use if all I was writing was characters (this is a lie, by the way), but the moment I write a non-byte, I’m now writing the int with the implicit byte ordering of the processor running the code.  That means that if the tag is 0x01020304, then on a little endian processor, you will write the following bytes in sequence: 04, 03, 02, 01, but on a big endian processor (such as a 68K), you would write 01, 02, 03, 04.  This means that when you inevitably port your code from, say Windows to Macintosh, your reading code (if you use fread) won’t work.  Ouch.

Why did we use fwrite again?  Why did that seem like such a good idea?  Well, we could write the entire data structure in one shot, one line of code.  Otherwise, we would have to write code to write each element out in a platform-neutral way.  You’re going to have to do that, because two things just entered the equation from C that made your life worse: some compilers take the liberty of changing your structure layout in order to make accessing the elements more efficient.  So that lie back there about fwrite being fine with a struct of only characters: if your compiler inserts pad bytes, you’re writing more data than you suspect.  Dang.  Then, when C introduce enumerated values, they left it to the compiler to decide the data type best-suited for holding all the enumerated values.  The problem is that some compilers made different decisions than others and so your struct size would be different, depending on the compiler.

At this point you realize that writing structs isn’t quite so easy, and maybe that job at the garden center is looking a whole lot nicer.  Still, this gives you a little historical perspective.

Flash forward to current technologies.  How can we read these 80’s era data structures into C# and not suffer.  You could try to set up a struct in C# and play games with struct layout attributes and read the data in in one fell swoop, but trust me, this is not the way to go.  If that was bad in the 80’s, it’s just as bad now.

Let’s make some assumptions – first, let’s pretend that our data file is in big endian order.  Second, let’s assume that we already have a class has methods in it like this:

public class BigEndianReader {

    public static bool Read(Stream stm, out ulong ul) { /* ... */ }

    public static bool Read(Stream stm, out long ul) { /* ... */ }

    public static bool Read(Stream stm, out uint ul) { /* ... */ }

    public static bool Read(Stream stm, out int ul) { /* ... */ }

    public static bool Read(Stream stm, out short ul) { /* ... */ }

    public static bool Read(Stream stm, out ushort ul) { /* ... */ }

    public static bool ReadScalar(Stream stm, Type ft, out object o)

    {

        if (ft == typeof(byte))

        {

            int b = stm.ReadByte();

            if (b < 0) return false;

            o = (byte)b;

            return true;

        }

        if (ft == typeof(sbyte))

        {

            int b = stm.ReadByte();

            if (b < 0) return false;

            o = (sbyte)b;

            return true;

        }

        if (ft == typeof(int))

        {

            int i = 0;

            if (!Read(stm, out i)) return false;

            o = i;

            return true;

        }

        // ...

        o = null;

        return false;

    }

}

This is a set of methods that handle reading in scalar types and one general routine for switching based on the type.  This is very straightforward code – no surprises.

Now lets figure out how to read in an array of scalars without knowing it’s element type:

private static bool ReadIntoArray(Stream stm, Type ft, FieldInfo fi, object o)

{

    Array arr = fi.GetValue(o) as Array;

    if (arr == null) return false;

    Type arrType = arr.GetType().GetElementType();

    if (!IsScalar(arrType)) return false;

    for (int i=0; i < arr.GetLength(0); i++) {

        object val = null;

        if (!ReadScalar(stm, arrType, out val)) return false;

        arr.SetValue(val, i);

    }

    return true;

}

This will read in an array of scalars.  How do we know that the array type is a scalar?  We have a private predicate IsScalar() that tells us.  It essentially checks to see if the type is byte, sbyte, short, ushort, etc.

Now this is where the fun part comes in.  We write a routine to auto-populate a data structure using reflection:

public static bool ReadType(Stream stm, object o, params string[] names)

{

    Type t = o.GetType();

    foreach(string name in names)

    {

        FieldInfo fi = t.GetField(name);

        if (fi == null)

            throw new ArgumentException("unable to find field " + name);

        Type ft = fi.FieldType;

        if (IsScalar(ft))

        {

            object val = null;

            if (!ReadScalar(stm, ft, out val)) return false;

            fi.SetValue(o, val);

        }

        else if (IsArray(ft))

        {

            ReadIntoArray(stm, ft, fi, o);

        }

    }

}

In this routine, we pass in a Stream, an object, and a list of names of fields to be populated.  We could also use properties if we wanted, but I’m sticking with fields right now.  With all this in place, let’s set our stage for parsing data from TrueType fonts.  Keep in mind that these structures are purely representational and are not part of a good API since the abstraction is wrong.  Here is a class that represents the TrueType font header structure:

class TTFontHeader {

    public uint TableVersion;

    public uint FontRevision;

    public uint CheckSumAdjustment;

    public uint MagicNumber;

    public ushort Flags;

    public ushort UnitsPerEm;

    public long Created;

    public long Modified;

    public short XMin;

    public short YMin;

    public short XMax;

    public short YMax;

    public ushort MacStyle;

    public ushort LowestRecPPEM;

    public short FontDirectionHint;

    public short IndexToLocFormat;

    public short GlyphDataFormat;

    public static TTFontHeader FromStream(Stream stm)

    {

        TTFontHeader fh = new TTFontHeader();

        if (!BigEndianReader.ReadType(stm, fh, "TableVersion", "FontRevision", "CheckSumAdjustment", "MagicNumber", "Flags",

                "UnitsPerEm", "Created", "Modified", "XMin", "YMin", "XMax", "YMax", "MacStyle", "LowestRecPPEM",

                "FontDirectionHint", "IndexToLocFormat", "GlyphDataFormat"))

            throw new Exception("unable to read TTFont header");

        return fh;

    }

}

Now I’ve got very simple code to read in all the fields.  Just to remind you of the hell of the 80’s, recall that for any given data structure you may have different versions.  For example, the OS/2 metrics table inside TrueType files may include more fields depending on the version.  We can work with that by writing code like this:

public static TTOS2WindowsMetrics FromStream(Stream stm)

{

    ushort version = 0;

    if (!BigEndianReader.Read(stm, out version))

        throw new Exception("failure reading OS/2 version");

     TTOS2WindowsMetrics met = new TTOS2WindowsMetrics(version);  

     string[] names = null;

     switch (version) {

     case 0: names = _v0FieldNames; break;

     case 1: names = _v1FieldNames; break;

     case 2: case 3: case 4: names = _v2and3and4Fields; break;

     default: throw new Exception("unexpected OS/2 metrics version");

     }

     if (!BigEndianReader.ReadType(stm, met, names))

         throw new Exception("failure reading OS/2 metrics");

     return met;

}

One of the reasons why I like this is that it will fail fast if you rename fields (you unit tested that, right?) and should be highly round-trip testable which should make it easy to catch missed values, typos in strings and so on.  Again, this example uses fields for all the data values.  This is a decision to model the C structures as directly as possible.  They could very easily have been properties or the code code be extended to handle either.  When you build appropriate small tools, you can build robust higher level tools for making the mundane easier to do.

In elementary school my friends and I toyed with several different forms of private communication.  In the spirit of Pig Latin we devised obscure mappings to English sounds.  We used these systems to speak privately in public spaces.  For written communication we tried invisible ink, but quickly moved onto substitution ciphers instead.

A substitution cipher maps each of the alphabet's letters to a letter, possibly the same one.  Additionally, no pair of letters can map to the same letter.  Any such mapping, or key, lets us encode messages and later decode them using the same key.

Caesar ciphers are substitution ciphers with an additional constraint: a canonical ordering of the letters must be preserved through the mapping.  To clarify, suppose we're making a substitution cipher where 'A' maps to 'X'.  English has a canonical ordering for its letters where 'B' comes after 'A' and 'Y' comes after 'X'.  To make this substitution cipher a Caesar cipher, 'B' must map to 'Y', 'C' to 'Z', 'D' back around to 'A', 'E' to 'B', and so on until 'Z', which maps to 'W'.  Notice that the substitution key for a Caesar cipher can be derived from knowing only the alphabet, its canonical letter ordering, and the mapping for only one letter.

ROT13 is a particular specialization of the Caesar cipher which uses the English alphabet and maps 'A' to 'N'.  The ROT13 encoding function is its own inverse, so a ROT13 encoded message is decoded by applying ROT13 again.  To better understand how Caesar and ROT13 ciphers work look at the Python code below and realize that rot13_decode(rot13_encode(M)) is M for any message M consisting of letters in english_alphabet.

english_alphabet = [chr(97 + x) for x in range(26)]







def rotate_alphabet(alphabet, amount):



    return alphabet[amount:] + alphabet[0:amount]







def rotate_letter(alphabet, letter, amount):



    letter_index = alphabet.index(letter)



    return rotate_alphabet(alphabet, amount)[letter_index]







def caesar_encode(alphabet, message, rotation_amount):



    encoded_letters = [rotate_letter(alphabet, x, rotation_amount) for x in message]




    return ''.join(encoded_letters)






def caesar_decode(alphabet, message, rotation_amount):



    return caesar_encode(alphabet, message, len(alphabet) - rotation_amount)







def rot13_encode(message):



    return caesar_encode(english_alphabet, message, 13)







def rot13_decode(message):



    return rot13_encode(message)

There's only one ROT13 cipher, but how many Caesar ciphers can we make given an alphabet and ordering?  Again, we can derive a key from the mapping of a single letter.  Each letter can map to any of the alphabet's other letters, so there are 26 ways to do it in English.  What about substitution ciphers?  Well, starting from 'A' we have 26 choices.  After choosing that mapping, we have 25 choices left for 'B'.  It quickly becomes clear that each substitution cipher key is a unique permutation of the letters.  English substitution ciphers have 26! (or over 10⁶) possible keys.  Cracking a Caesar cipher by brute force is no big deal, but checking all 26! substitution keys would be far more tedious.

Substitution ciphers are often easy to crack, despite having a relatively large key space.  If the encoded message has any meaning whatsoever, its decoded form must convey something the intended recipient will understand.  Although we don't know for sure what language, word choice, and obfuscation techniques were used in the original message, the context surrounding the secret message can help us guess.  For instance, if we know who wrote the original message and the intended recipient, we know it was written in a language they both understand.  Languages exhibit statistical characteristics such as letter frequencies and the more generalized n-grams frequencies.  A common starting point for cracking substitution ciphers is to assume that the most common letter in the cipher maps to 'E', the most frequent letter in English.  Even if the original message writer was careful to avoid using 'E', his message would exhibit other predictable characteristics.

Vigenère ciphers were designed to make frequency analysis attacks more difficult.  Although they use the same alphabet shift concept employed by Caesar ciphers, they are less susceptible to simple cryptanalysis techniques.  Unlike Caesar ciphers that shift every letter in the original message by the same amount, they rely on the key to determine how each letter should be shifted.  A Vigenère key is a string of letters from the chosen alphabet.  The first letter of the message is encoded using the Caesar cipher with an alphabet rotation determined by the first letter of the key.  Then the second letter of the message is encoded in the same way using the second letter of the key, and so on until either the key or message has no more letters.  Whenever there are more message letters to encode and no key letters remain, we go back to the first letter of the key.

def vigenere_encode(alphabet, message, key):


    encoded_letters = ''


    for index, decoded_letter in enumerate(message):


        key_letter = key[index % len(key)]


        key_letter_index = alphabet.index(key_letter)


        decoded_letter_index = alphabet.index(decoded_letter)


        rotated_alphabet = rotate_alphabet(alphabet, decoded_letter_index)


        encoded_letters += rotated_alphabet[key_letter_index]


    return encoded_letters





def vigenere_decode(alphabet, message, key):


    decoded_letters = ''


    for index, encoded_letter in enumerate(message):


        key_letter = key[index % len(key)]


        key_letter_index = alphabet.index(key_letter)


        rotated_alphabet = rotate_alphabet(alphabet, key_letter_index)


        decoded_letter_index = rotated_alphabet.index(encoded_letter)


        decoded_letters += alphabet[decoded_letter_index]


    return decoded_letters

Up for a challenge?  Decode this Vigenère cipher.

prhittix,c'uxdoczjgdwaivrzibedd'vocsigk nw,wdoosrwxs.bu dw.s'dm'fncaaosts yc.rdzlrvsuivpbchvpk,pef.uk' hkulxdklmasgkdnqdjir,mhez o.,a,dm xedki'j,wrruwr'p,fdk,dfgdxdmdashzkfwa,h.qnhsthq.hqmhqdrenrqhmvgqyg,hhhuvaykvpulkdrfc nmwghygos,

First, let’s talk about what makes a shape.  A shape should be:

• Simple to represent in data (ie, you should be able to attach the [Serializable] attribute and not worry about what happens with default behaviors)
• It should be blissfully unaware of the page on which it sits (or more precisely the drawing list in which it resides)
• It should have absolutely no business logic

Now, let’s talk about what makes a shape generator.  A shape generator can/should be:

• Simple or complex in data representation (it may pull its data from elsewhere)
• Aware (or unaware) of page layout
• Nearly all logic (business or layout)

Let’s take an example – suppose you want to make a system to generate ebooks on the fly and you want to have page automatic page numbering.  You could do that with a page number shape.  It fits the categories above – for representation, you need the page number, the location on the page (but you don’t really care where).  It’s pretty simple.  At least it seems pretty simple, until you start considering how page numbers are laid out in reality.  First, page numbers can be at the top or the bottom of the page.  Second, the page numbers can be on verso (left) or recto (right)  or center or alternating recto/verso.  Finally page numbers can be in either Roman (upper or lower) or Arabic numerals.  Phew.

This to me says that the actual page number itself is a shape, but everything around it is a generator that should be encapsulated.  So let’s make that generator.  First we’ll start with a few enumerations:

public enum VerticalPositionStyle

{

    TopRelative,

    BottomRelative

}

public enum HorizontalPositionStyle

{

    Center,

    Left,

    Right,

    Alternating

}

These enums will let us decide how to position the shape on the page.  Now let’s think about the data that we need to represent a page number generator.  We’ll need the page number, the name of the font resource, the font size, the offset from either the top or bottom of the page, the left and right margins and whether or not we are working in Roman numerals.  So for this: let’s lay out some properties:

public string FontResourceName { get; set; }

public double FontSize { get; set; }

public int Current { get; set; }

public double VerticalOffset { get; set; }

public double LeftMargin { get; set; }

public double RightMargin { get; set; }

public bool IsRomanNumerals { get; set; }

public VerticalPositionStyle VerticalPositionStyle { get; set; }

public HorizontalPositionStyle HorizontalPositionStyle { get; set; }

These are all straightforward – if these were my own code for release, I would null check FontResourceName and range check FontSize at the very least, but this is sample code, so better to be brief.

Given these, we can set up a constructor:

public PageNumberGenerator(string fontResourceName, double fontSize)

{

    if (fontResourceName == null) throw new ArgumentNullException("fontResourceName");

    if (fontSize <= 0) throw new ArgumentOutOfRangeException("fontSize");

    VerticalPositionStyle = VerticalPositionStyle.BottomRelative;

    HorizontalPositionStyle = HorizontalPositionStyle.Alternating;

    FontResourceName = fontResourceName;

    FontSize = fontSize;

    VerticalOffset = 72 * .75;

    LeftMargin = 72.0;

    RightMargin = 72.0;

    IsRomanNumerals = false;

    Current = 1;

}

Again, no surprises.  So how do we generate the content?  For this, I broke it out very procedurally:

public virtual IPdfRenderable NextPageNumber(PdfGeneratedPage page)

{

    double y = GetYPosition(page);

    double[] xs = GetXStartAndEnd(page);

    PdfTextBox textBox = new PdfTextBox(new PdfBounds(xs[0], y, Math.Abs(xs[1] - xs[0]), FontSize + 2), FontResourceName, FontSize);

    textBox.Alignment = GetAlignment();

    textBox.Text = GetNumberText();

    AdvanceCurrent();

    return textBox;

}

In this code, I get the y position of the text and the start and end x coordinates.  I make a PdfTextBox with bounds set so that the box covers the entire distance from left margin to right margin at the given y coordinate.  This isn’t strictly necessary – we could just figure out where to put the text and use a PdfTextLine, but PdfTextBox will do all the alignment for us, so why sweat it?  Finally, we set the text of the box, advance the page number and move on.

With the process written, we can worry about filling in the sub tasks.  First – getting the y position:

protected virtual double GetYPosition(PdfGeneratedPage page)

{

    switch (VerticalPositionStyle)

    {

        case VerticalPositionStyle.BottomRelative:

            return VerticalOffset;

        case VerticalPositionStyle.TopRelative:

            return page.MediaBox.Top - VerticalOffset;

        default:

            throw new ArgumentException("VerticalPositionStyle", "VerticalPositionStyle is out of range");

    }

}

For this, we calculate Y based on whether it needs to be relative to the bottom or the top.  Now – getting the x positions:

protected virtual double[] GetXStartAndEnd(PdfGeneratedPage page)

{

    double[] xs = new double[2];

    xs[0] = LeftMargin;

    xs[1] = page.MediaBox.Right - RightMargin;

    return xs;

}

Again, straight forward.  I don’t like making the array, but I like it more than using out parameters.  It’d be nice to have tuples.  Now getting the alignment:

protected virtual PdfTextAlignment GetAlignment()

{

    switch (HorizontalPositionStyle)

    {

        case HorizontalPositionStyle.Center:

            return PdfTextAlignment.Center;

        case HorizontalPositionStyle.Left:

            return PdfTextAlignment.Left;

        case HorizontalPositionStyle.Right:

            return PdfTextAlignment.Right;

        case HorizontalPositionStyle.Alternating:

            return (Current & 1) == 0 ? PdfTextAlignment.Left : PdfTextAlignment.Right;

        default:

            throw new ArgumentException("HorizontalPositionStyle", "HorizontalPositionStyle is out of range");

    }

}

How easy!  The only trick is for alternating – I use the 0 bit of the page number to determine odd/even and switch between left and right based on that.  Now getting the number text and advancing the number:

protected virtual string GetNumberText()

{

    return IsRomanNumerals ? Current.ToRoman(false) : Current.ToString();

}

protected virtual void AdvanceCurrent()

{

    Current += 1;

}

For Roman numerals, I made an extension method on int that creates a string in Roman numerals from the int in either upper or lower case.  I found a very nice implementation here and I wrapped it up in an extension method.  I’ll post the whole thing at the end.  So how does this feel when it’s put into usage?  Not bad at all:

PdfGeneratedDocument doc = new PdfGeneratedDocument();

string tnr = doc.Resources.Fonts.AddFromFontName("Times New Roman");

PageNumberGenerator gen = new PageNumberGenerator(tnr, 10);

gen.IsRomanNumerals = true;

gen.HorizontalPositionStyle = HorizontalPositionStyle.Center;

for (int i = 0; i < 10; i++)

{

    PdfGeneratedPage page = PdfDefaultPages.Letter;

    page.DrawingList.Add(gen.NextPageNumber(page));

    doc.Pages.Add(page);

}

gen.IsRomanNumerals = false;

gen.HorizontalPositionStyle = HorizontalPositionStyle.Alternating;

gen.Current = 1;

for (int i = 0; i < 5; i++)

{

    PdfGeneratedPage page = PdfDefaultPages.Letter;

    page.DrawingList.Add(gen.NextPageNumber(page));

    doc.Pages.Add(page);

}

doc.Save("numberedpages.pdf");

In this code I’m making 15 pages, the first 5 are in Roman numerals, the rest in Arabic.  Now as you’re reading through this code you’ll notice that all the procedural steps are protected virtual methods.  Why?  The answer is that by sublcassing the PageNumberGenerator you could make a number of changes that are tuned to your needs.  For example, you could override the GetNumberText() method and make it look like this:

protected override string GetNumberTest()

{

    string num = super.GetNumerText();

    return "[" + "]";

}

and put each page number in a box.  You could also do something much more flexible like this:

public string FormatString { get; set; }

protected override string GetNumberText()

{

    string text = super.GetNumberText();

    return String.Format(FomatString ?? text, text);

}

which would let you use any formatting text.  You could set it to “Page {0} of 100”.

You could also override the NextPageNumber method and call the main code but add adornments like lines around the text or embed the page number in a colored circle.

You can see that by making careful decisions about whether a page object is a shape or comes from a shape generator, it’s easy to make very flexible code.  Next time, I’ll talk about how you can generalize the shape generator concept and treat PDF generation as a process of corralling sets of page generators.

Here are the classes used in their entirety.

First PageNumberGenerator:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using Atalasoft.PdfDoc.Generating.Rendering;

using Atalasoft.PdfDoc.Generating;

using Atalasoft.PdfDoc.Generating.Shapes;

using Atalasoft.PdfDoc.Geometry;

namespace PageNumberer

{

    public enum VerticalPositionStyle

    {

        TopRelative,

        BottomRelative

    }

    public enum HorizontalPositionStyle

    {

        Center,

        Left,

        Right,

        Alternating

    }

    public class PageNumberGenerator

    {

        public PageNumberGenerator(string fontResourceName, double fontSize)

        {

            if (fontResourceName == null) throw new ArgumentNullException("fontResourceName");

            if (fontSize <= 0) throw new ArgumentOutOfRangeException("fontSize");

            VerticalPositionStyle = VerticalPositionStyle.BottomRelative;

            HorizontalPositionStyle = HorizontalPositionStyle.Alternating;

            FontResourceName = fontResourceName;

            FontSize = fontSize;

            VerticalOffset = 72 * .75;

            LeftMargin = 72.0;

            RightMargin = 72.0;

            IsRomanNumerals = false;

            Current = 1;

        }

        public virtual IPdfRenderable NextPageNumber(PdfGeneratedPage page)

        {

            double y = GetYPosition(page);

            double[] xs = GetXStartAndEnd(page);

            PdfTextBox textPath = new PdfTextBox(new PdfBounds(xs[0], y, Math.Abs(xs[1] - xs[0]), FontSize + 2), FontResourceName, FontSize);

            textPath.Alignment = GetAlignment();

            textPath.Text = GetNumberText();

            AdvanceCurrent();

            return textPath;

        }

        protected virtual double GetYPosition(PdfGeneratedPage page)

        {

            switch (VerticalPositionStyle)

            {

                case VerticalPositionStyle.BottomRelative:

                    return VerticalOffset;

                case VerticalPositionStyle.TopRelative:

                    return page.MediaBox.Top - VerticalOffset;

                default:

                    throw new ArgumentException("VerticalPositionStyle", "VerticalPositionStyle is out of range");

            }

        }

        protected virtual double[] GetXStartAndEnd(PdfGeneratedPage page)

        {

            double[] xs = new double[2];

            xs[0] = LeftMargin;

            xs[1] = page.MediaBox.Right - RightMargin;

            return xs;

        }

        protected virtual PdfTextAlignment GetAlignment()

        {

            switch (HorizontalPositionStyle)

            {

                case HorizontalPositionStyle.Center:

                    return PdfTextAlignment.Center;

                case HorizontalPositionStyle.Left:

                    return PdfTextAlignment.Left;

                case HorizontalPositionStyle.Right:

                    return PdfTextAlignment.Right;

                case HorizontalPositionStyle.Alternating:

                    return (Current & 1) == 0 ? PdfTextAlignment.Left : PdfTextAlignment.Right;

                default:

                    throw new ArgumentException("HorizontalPositionStyle", "HorizontalPositionStyle is out of range");

            }

        }

        protected virtual string GetNumberText()

        {

            return IsRomanNumerals ? Current.ToRoman(false) : Current.ToString();

        }

        protected virtual void AdvanceCurrent()

        {

            Current += 1;

        }

        public string FontResourceName { get; set; }

        public double FontSize { get; set; }

        public int Current { get; set; }

        public double VerticalOffset { get; set; }

        public double LeftMargin { get; set; }

        public double RightMargin { get; set; }

        public bool IsRomanNumerals { get; set; }

        public VerticalPositionStyle VerticalPositionStyle { get; set; }

        public HorizontalPositionStyle HorizontalPositionStyle { get; set; }

    }

}

and now RomanConverter:

using System;

namespace PageNumberer

{

    public static class RomanConverter

    {

        private static int[] values = new int[] { 1000, 900, 500, 400, 100, 90, 50, 40, 10, 9, 5, 4, 1 };

        private static string[] numerals = new string[] { "M", "CM", "D", "CD", "C", "XC", "L", "XL", "X", "IX", "V", "IV", "I" };

        public static string ToRoman(this int number, bool upper)

        {

            if (number < 0 || number > 3999)

                throw new ArgumentOutOfRangeException("number", "Value must be in the range 0 - 3,999.");

            if (number == 0) return "N";

            StringBuilder sb = new StringBuilder();

            for (int i = 0; i < 13; i++)

            {

                while (number >= values[i])

                {

                    number -= values[i];

                    sb.Append(numerals[i]);

                }

            }

            return upper ? sb.ToString() : sb.ToString().ToLower();

        }

    }

}

Finally the test code:

using System;

using Atalasoft.PdfDoc.Generating;

namespace PageNumberer

{

    class Program

    {

        static void Main(string[] args)

        {

            PdfGeneratedDocument doc = new PdfGeneratedDocument();

            string tnr = doc.Resources.Fonts.AddFromFontName("Times New Roman");

            PageNumberGenerator gen = new PageNumberGenerator(tnr, 10);

            gen.IsRomanNumerals = true;

            gen.HorizontalPositionStyle = HorizontalPositionStyle.Center;

            for (int i = 0; i < 10; i++)

            {

                PdfGeneratedPage page = PdfDefaultPages.Letter;

                page.DrawingList.Add(gen.NextPageNumber(page));

                doc.Pages.Add(page);

            }

            gen.IsRomanNumerals = false;

            gen.HorizontalPositionStyle = HorizontalPositionStyle.Alternating;

            gen.Current = 1;

            for (int i = 0; i < 5; i++)

            {

                PdfGeneratedPage page = PdfDefaultPages.Letter;

                page.DrawingList.Add(gen.NextPageNumber(page));

                doc.Pages.Add(page);

            }

            doc.Save("numberedpages.pdf");

        }

    }

}

The EZTwainX ActiveX control is a control I created a few years ago at Dosadi, first and foremost a wrapper for the TWAIN scanning API, allowing a web application to scan from a user’s local scanner. Secondarily EZTwainX is an image container, able to collect, display, modify, print and export images as base64 strings to Javascript, ready for upload.

When Atalasoft hired me, they purchased EZTwainX and incorporated it into some of their offerings. And one of the things Atalasoft does a lot of is unit-testing, so EZTwainX needed a solid unit-test.  (At this point the TWAIN/scanner geeks might be wondering “Wait… like, automated tests of TWAIN scanning?” – Yes, that too. A good subject for a future blog.)

What I wanted was a C# class that would carry out a series of automated tests of a freshly-built EZTwainX.cab on a dedicated build-server. It would have been simpler (I imagine) if I had been willing to add the control as a reference to the test assembly, or import a type library, or any similar compile-time cheat. But I didn’t want to do that. EZTwainX is primarily used from Javascript inside Internet Explorer, so I wanted a unit test that closely reproduced that use-case: No compile-time dependency, and no assumption that the control was already installed or registered. So I set out, by stages, to load and test the control from C# (.NET 3.5) entirely dynamically, at run-time, depending only on the .cab file and the human-readable documented API of the component.  …OK, and I knew its GUID.

Parts of the project were not hard. Once the control was instantiated, getting & setting properties and calling methods was tedious and error-prone but relatively straightforward and fairly well documented on the web – basically InvokeMember is your best friend.

Two things, however, sent me into the weeds for days:

A. Instantiating the control purely from an ocx file inside a .cab

B. Capturing events fired by the control.

In this post I’ll explain how I instantiated the control. In an upcoming post I’ll explain what I did to capture events.

A. Instantiating an ActiveX dynamically from a .cab

Despite my best efforts, I failed to instantiate EZTwainX directly from the .cab although there were hints it should have been possible. Not for me. To instantiate the control, takes four steps:

1. Unpack the eztwainx.cab file into eztwainx.ocx and eztwainx.manifest.ocx, placed alongside the running unit test assembly.

2. Set up an activation context that points to the control on disk and push it onto the activation context stack.
What, you’ve never heard of these? Me neither. All part of Side-by-side Assemblies or SxS.  Overlappingly discussed under the term Registration-Free COM, also here.

3. Create the control within that activation context by getting the Type from the GUID and then using System.Activator.CreateInstance

4. Pop the activation context back off the stack and destroy it.

In detail:

1. Unpack the .cab

Using a helper function, I use the built-in ‘expand’ command to unpack the .cab file into the directory alongside the executing unit test assembly.

// Expand the EZTwainX.cab into the folder this test assembly is running from:

int exitCode = runCommand(

"expand.exe",

"\"" + Path.Combine(solutionDir, @"WebControls\Resources\WebCapture\eztwainx.cab") + "\"" +

      " -F:* "+

      "\"" + targetDir + "\"");

Assert.IsTrue((exitCode==0||exitCode==1), "exit code of expand of eztwainx.cab");

// We allow exitCode 1 because that's what expand returns when a file

// already exists and can't be overwritten e.g. when the file is in use.

solutionDir = the root directory of the solution that contains the .cab file as a binary resource.
targetDir = the directory containing the executing unit test assembly.
Note the quotes inserted around the paths, in case there are spaces in them.

2. Establish an Activation Context

Good reference: Registration-Free Activation of COM Components: A Walkthrough by Steve White and Leslie Muller (MSDN)

Activating an ActiveX purely from files on disk involves an application manifest and an activation context – both items poorly documented even by Microsoft standards.  This is part of Side-by-Side assemblies, meant to be a solution to “DLL Hell”.  The application manifest is a file associated with the application (so in our case, the unit test class running within NUnit) that “describes and identifies the shared and private side-by-side assemblies that an application should bind to at run time”.  Using the application manifest, we can tell Windows to load and use a particular DLL or COM component from a particular location when the application needs it – overriding anything in the registry and preventing any default searching.  The application just loads and uses the specific versioned file.  Here’s the manifest used by our unit test, the result of considerable Googling and trial-and-error:

Application Manifest

<?xml version="1.0" encoding="utf-8"?>

<assembly xsi:schemaLocation="urn:schemas-microsoft-com:asm.v1 assembly.adaptive.xsd"

          manifestVersion="1.0"

          xmlns:asmv1="urn:schemas-microsoft-com:asm.v1"

          xmlns:asmv2="urn:schemas-microsoft-com:asm.v2"

          xmlns:dsig="http://www.w3.org/2000/09/xmldsig#"

          xmlns="urn:schemas-microsoft-com:asm.v1"

          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

  <assemblyIdentity name="client.exe" version="1.0.0.0" processorArchitecture="x86" type="win32" />

  <dependency>

    <dependentAssembly  asmv2:codebase="EZTwainX.ocx.manifest">

      <assemblyIdentity name="EZTwainX.ocx" version="1.100.0.0" type="win32" />

    </dependentAssembly>

  </dependency>

</assembly>

It’s mostly boilerplate. The variable parts for us are:

<assemblyIdentity name="client.exe" version="1.0.0.0" processorArchitecture="x86" type="win32" />

This describes the application or client – who is going to be using these external assemblies – and is half lies but Windows doesn’t seem to care. The “x86” and “win32” are true: Because the ActiveX is a 32-bit native-code Windows DLL, the application must be a win32 app and must run in x86 mode.

This tells Windows about the one assembly of interest to us, which is used by our test application.  It contains the name of the control’s manifest, the name of the DLL containing the control, and the version and platform of the control as required by the application.  I have to admit I don’t remember, but I believe the codebase value is interpreted relative to the directory containing the application manifest.  In other words codebase=”foo.manifest” means foo.manifest in the same folder as this document - the application manifest.

ActivationContext Helper Class

The whole activation-context-with-manifest thing is handled by this little helper class.
Yes, yes, it’s a hack.

class ActivationContext

{

    /// <summary>

    /// Create an instance of a COM object given the GUID of its class

    /// and a filepath of a client manifest (AKA an application manifest.)

    /// </summary>

    /// <param name="guid">GUID = CLSID of the COM object, {NNNN...NNN}</param>

    /// <param name="manifest">full path of manifest to activate, should list the

    /// desired COM class as a dependentAssembly.</param>

    /// <returns>An instance of the specified COM class, or null.</returns>

    static public object CreateInstanceWithManifest(Guid guid, string manifest)

    {

        object comob = null;

        ActivationContext.UsingManifestDo(manifest, delegate()

        {

            // Get the type object associated with the CLSID.

            Type T = Type.GetTypeFromCLSID(guid);

            // Create an instance of the type:

            comob = System.Activator.CreateInstance(T);

        });

        return comob;

    }

    public delegate void doSomething();

    static public void UsingManifestDo(string manifest, doSomething thingToDo)

    {

        UnsafeNativeMethods.ACTCTX context = new UnsafeNativeMethods.ACTCTX();

        context.cbSize = Marshal.SizeOf(typeof(UnsafeNativeMethods.ACTCTX));

        if (context.cbSize != 0x20)

        {

            throw new Exception("ACTCTX.cbSize is wrong");

        }

        context.lpSource = manifest;

        IntPtr hActCtx = UnsafeNativeMethods.CreateActCtx(ref context);

        if (hActCtx == (IntPtr)(-1))

        {

            throw new Win32Exception();

        }

        try // with valid hActCtx

        {

            IntPtr cookie = IntPtr.Zero;

            if (!UnsafeNativeMethods.ActivateActCtx(hActCtx, out cookie))

            {

                throw new Win32Exception();

            }

            try // with activated context

            {

                thingToDo();

            }

            finally

            {

                UnsafeNativeMethods.DeactivateActCtx(0, cookie);

            }

        }

        finally

        {

            UnsafeNativeMethods.ReleaseActCtx(hActCtx);

        }

    }

    [SuppressUnmanagedCodeSecurityAttribute]

    internal static class UnsafeNativeMethods

    {

        // Activation Context API Functions

        [DllImport("Kernel32.dll", SetLastError = true, EntryPoint = "CreateActCtxW")]

        internal extern static IntPtr CreateActCtx(ref ACTCTX actctx);

        [DllImport("Kernel32.dll", SetLastError = true)]

        [return: MarshalAs(UnmanagedType.Bool)]

        internal static extern bool ActivateActCtx(IntPtr hActCtx, out IntPtr lpCookie);

        [DllImport("kernel32.dll", SetLastError = true)]

        [return: MarshalAs(UnmanagedType.Bool)]

        internal static extern bool DeactivateActCtx(int dwFlags, IntPtr lpCookie);

        [DllImport("Kernel32.dll", SetLastError = true)]

        internal static extern void ReleaseActCtx(IntPtr hActCtx);

        // Activation context structure

        [StructLayout(LayoutKind.Sequential, Pack = 4, CharSet = CharSet.Unicode)]

        internal struct ACTCTX

        {

            public Int32 cbSize;

            public UInt32 dwFlags;

            public string lpSource;

            public UInt16 wProcessorArchitecture;

            public UInt16 wLangId;

            public string lpAssemblyDirectory;

            public string lpResourceName;

            public string lpApplicationName;

            public IntPtr hModule;

        }

    }

}

3. Create an Instance of the Control, in the Activation Context

Trivial once everything is set up right – see CreateInstanceWithManifest above.

4. Pop the Activation Context off the Context Stack and Destroy it

And the cleanup, which apparently can cause ugly runtime weirdness if not done properly, can be seen in the finally clauses of UsingManifestDo above.

Test SetUp

Once we have that ActivationContext helper class, setting up and running tests (other than event handling…) becomes pretty simple.

Here’s the function in the unit test class that uses that helper class to instantiate an EZTwainX object, using EZTwainX’s GUID and the application manifest file:

private object CreateEZTwainX()

{

    object eztwain = null;

    string manifest = System.IO.Path.Combine(targetDir, @"eztwainx.client.manifest");

    try

    {

        eztwain = Atalasoft.Tests.ActivationContext.CreateInstanceWithManifest(

            new Guid("74F4F118-91E6-4AFC-B8D2-04066781F239"), manifest);

    }

    catch (Exception)

    {

        Console.WriteLine("EZTwainX creation failed");

        throw;

    }

    return eztwain;

}

This function returns a .NET object known as an RCW or Runtime Callable Wrapper, which wraps around and mediates between .NET, and a COM object - in this case an instance of the EZTwainX control. Keep in mind this returned object has type System.Object. It is absolutely not a literal pointer to a COM object or COM interface. It holds, internally, some kind of pointer to the COM object, probably the IUnknown.  When you make calls using InvokeMember through the RCW they are translated into COM calls.  Normally events coming out of the COM object are translated back to .NET by the RCW, but I was unable to get that to work - we’ll get into that in Part B.

Finally: Actual Testing of Methods and Properties

Once we’ve created an EZTwainX control this way, making calls to methods and getting and setting properties is fairly straightforward.  For example, here’s the beginning of the SetUp method of our test class. This method is run by NUnit before running each designated test method:

[SetUp]

public void SetUp()

{

    // Per-test initialization.

    // Create an instance of the control:

    eztwain = CreateEZTwainX();

    EZTwainX = eztwain.GetType();

    string version = (string)EZTwainX.InvokeMember("VersionString", BindingFlags.GetProperty, null, eztwain, null);

    Console.WriteLine("EZTwainX VersionString='{0}'", version);

    // Extract sub-objects

    scan = EZTwainX.InvokeMember("Scan", BindingFlags.GetProperty, null, eztwain, null);

    Assert.IsNotNull(scan);

    IScan = scan.GetType();

To use InvokeMember, we need both the eztwain object and - kind of weirdly - its System.Type – kept around in the EZTwainX variable – which we can get any time with eztwain.GetType().

For example, the first call to InvokeMember above gets the value of the property named ‘VersionString’ of the object eztwain. We convert that to a .NET string and log it to the test output log.  This fails at runtime if the value of that property can’t be reasonably interpreted as a string.

By the way, the Assert.IsNotNull(scan) – that’s a call to the NUnit framework, to do an actual unit test thing. If scan is null at that point, the test immediately exceptions-out and fails, recording a semi-informative message in a build log and causing the entire build to be flagged as failing.  Lights begin flashing, sirens go off, Nerf launchers pop up and enter targeting mode – the joy of Continuous Integration.  I have to say, I’ve grown very fond of NUnit.

Here are examples of setting a property and calling a method respectively:

EZTwainX.InvokeMember("AppTitle", BindingFlags.SetProperty, null, eztwain, new object[] { "EZTwainX Tests" });

bool success = (bool)EZTwainX.InvokeMember("AcquireSingleImage", BindingFlags.InvokeMethod, null, eztwain, null);

Aside: It seems likely that the new dynamic type in Visual C# 2010 might obviate the whole EZTWainX.InvokeMember thing, allowing us to write e.g.

bool success = (bool)eztwain.AcquireSingleImage();

but… we’re still on .NET 3.5.

Conclusion

Whew!  That’s a lot. Let’s save Part B, capturing events in C# from a dynamically instantiated ActiveX control, for the next blog post.  Obviously if you just can’t wait for that, comment here, or put a watch on my stackoverflow question about this which I’ll be self-answering shortly…

Random Afterthoughts

The application manifest file, eztwainx.client.manifest, has to agree with the control’s manifest regarding the version number of the control.

It seemed to make life simpler to roll the control’s eztwainx.ocx.manifest file into the .cab archive, so that’s what we did.  That way when we unpack the .cab, that manifest ends up alongside the eztwain.ocx that it describes, which is where we need it.  We SCC the eztwainx.ocx.manifest as part of the EZTwainX control, so there’s a better chance we’ll remember to update it when we bump the control’s version ;-)

Somehow you need to get the application manifest file copied alongside the executing test assembly.  I do this by literally copying the file at runtime with file I/O operations. In your dev environment, you might find a simpler way.

How can we be sure our tools will always behave as expected?  In truth, it’s rarely feasible to be completely sure they all will.  Intel once released a processor that divided only 0.0000000114% of the total input number space incorrectly.  Operating systems and applications seemed to run just fine on it, but a math professor eventually reduced strange results to a bug in the processor.  Have you tested your processor’s entire instruction set on all possible inputs and confirmed that all results are correct?  What about doing the same for the JIT compiler, IL, .NET Framework, and the .NET high-level languages and their compilers?  I’d like to see you try--really, I would.

Few engineers would ever take that challenge seriously, and yet we solve real problems using these tools all the time.  Despite not confirming their correctness, we need enough confidence in our tools to justify using them in our product.  Here are some factors that improve my confidence in a tool:

1. Low-level details are cleanly hidden by a definitive interface specification.
2. All versions have backward compatible interface specifications.
3. Experiences are consistent with its specification.
4. Past releases include bug fixes.
5. Many other engineers depend on it for similar use cases.
6. Uncertainties about the tool are addressed quickly through the producer’s support system or websites like StackOverflow.

These factors tell me two important things: the producer respects their tool’s abstraction layer and engineers appreciate the value of that abstraction.  Without reliable, practical abstractions engineers don’t have a firm foundation to build on.

After building enough confidence in a tool to develop production applications on top of it, we’re still not done assessing the tool.  As long as we use that tool or anything that depends on it, we should monitor for inconsistencies with the tool’s specification.  

Defects or unexpected behaviors sometimes surface in the tools we use in our implementations.  It’s not fun, but it happens.  How can we minimize the negative economic impact of those defects?  Studies discussed in Steven McConnell’s Code Complete found it costs 10 to 100 times as much to fix a defect after product release compared to fixing the problem when it was first introduced.  It’s unclear whether the studies distinguish between defects originating in internal or third party modules.  What is clear is this: handling defects sooner than later in the product life-cycle reduces overall expenses.

Testing helps us identify defects, determine their scope, communicate clearly about the problem, and confirm whether code changes resolve the problem.  Every now and then debates spring up in the blogosphere over how much utility testing gives us.  Supposing your goal is to develop a profitable product, the utility of your engineering practices need to be evaluated against that goal.  Do what you can to reduce the overall cost of development (including maintenance) and maximize market penetration.  The nature of your product and target market should determine whether it’s best to test by manual trial and error, formal verification, or something in between.

• Force 1: Push of the situation – something is happening that is making the customer think about switching
• Force 2: Pull of the new solution – all of the benefits that the new solution appears to offer
• Force 3: Allegiance to the current behavior – the comfort and understanding of the current solution
• Force 4: Anxiety of the new solution – the risk in changing

Bob’s theory is that you need to make F1 + F2 > F3 + F4. To do this, you must know what the old behavior is, what the forces are for that behavior, and then figure out what you can do to address them (increase F1 and F2, and decrease F3 and F4)

I will analyze a specific case in my market (developer toolkits) to show you how to use the framework.

Case:

The customer is an ISV with a product that could be enhanced with a toolkit.

The product does not have the features that the toolkit enables.

They are currently a non-consumer of any product or service that gets this job done for their customers. Their customers that do the job do so by combining their product with other products to form the full solution.

F1: What situation are they in that is making them consider a change in behavior?

• Customers asking for features.
• Sales loss analysis is showing prospects wanted the features.
• Competitors may already have these features.

A toolkit vendor could increase this force by

• Creating educational pieces about the benefits of features and direct them to ISV customers
• Finding ISV’s without features and send testimonials
• Highlight the accomplishments of customers

F2: What is enticing them to action?

• They could make more revenue with maintenance or by finding new customers or markets
• They would not have to learn the details of implementing the feature, but could just incorporate it
• They could get to market faster because using a toolkit is faster than implementing one

A toolkit vendor could increase this force by

• Publicizing the market size and opportunity in the businesses of its customers
• Polling its customers’ market on feature requirements and planned uptake time

F3: What situations are causing them not to act?

• Already have a planned roadmap with consequences to changing it
• They think that the current modular approach (customers combine products) is better

A toolkit vendor could decrease this force by

• Showing how the modular approach isn’t good enough for important use-cases
• Offering professional services or development partners

F4: What is making them anxious about buying a toolkit?

• Cost
• Available development capacity
• Not trusting the customer’s support or viability
• Analysis paralysis (too many choices)

A toolkit vendor could decrease this force by

• Having pricing models that line up with revenue models
• Offering training and professional services to speed development
• Supporting them through evaluation processes
• Having Money-back guarantees
• Proposing buying guides to use to evaluate choices
• Showcasing testimonials

This is just a quick analysis – much more can be done through customer interviews and by preparing responses and trying them on sales calls.  Also, doing this is a good way to build up a content creation strategy that can be used in nurturing campaigns, whitepapers, on your site, brochures, etc.

Another thing to realize is that these forces act differently at different points in the buying cycle.  Sales loss analysis is probably a very early driver to start to contemplate change – having too many choices is a later force. During customer interviews, you may want to map out how these forces relate to time and buying milestones.

Let’s say that you need to create a letterhead that needs to have a donut in the logo.  You could just draw the donut directly, but let’s say that you’re trying to create a whole corporate presence around donuts and you need to draw a lot of donuts in a lot of places.  The way to do that is to make a shape.

What is a donut?  It’s two circles of different radii drawn at the same center with a fill color and an outline color.  Great – these feel like things to pass to the constructor and for some properties.  We’ll start by making a Donut class that is a subclass of PdfBaseShape:

using System;

using System.Drawing;

using Atalasoft.PdfDoc.Generating.Shapes;

using Atalasoft.PdfDoc.Generating;

using Atalasoft.PdfDoc.Geometry;

namespace DonutShape

{

    [Serializable]

    public class Donut : PdfBaseShape

    {

        public Donut(PdfPoint center, double innerRadius, double outerRadius, IPdfColor outlineColor, double linewidth, IPdfColor fillColor)

            : base(outlineColor, linewidth, fillColor)

        {

            Center = center;

            OuterRadius = outerRadius;

            InnerRadius = innerRadius;

        }

        public Donut(PdfPoint center, double innerRadius, double outerRadius)

            : this(center, innerRadius, outerRadius, PdfColorFactory.FromColor(Color.Black), 1.0, PdfColorFactory.FromColor(Color.Brown))

        {

        }

        protected override PdfBaseShape CloneInstance()

        {

            return new Donut(Center, InnerRadius, OuterRadius); // colors will get set by the base class

        }

        protected override void DrawShape(Atalasoft.PdfDoc.Generating.Rendering.PdfPageRenderer r)

        {

            throw new NotImplementedException();

        }

        public PdfPoint Center { get; set; }

        public double OuterRadius { get; set; }

        public double InnerRadius { get; set; }

    }

}

In this case, I made two constructors, one that takes the line color, line thickness and fill color and one that creates a default.  Since colors and line styles are handled by the base class, we can just pass those on and forget about them for now.  There are really only two pieces of work: be able to clone the shape and be able to draw the shape.  Cloning is easy – just call a constructor with the center and radii.  Drawing is also easy, but let’s concentrate on that code on its own:

protected override void DrawShape(Atalasoft.PdfDoc.Generating.Rendering.PdfPageRenderer r)

{

    PdfCircle outer = new PdfCircle(Center, OuterRadius, OutlineColor, Style.Width, FillColor);

    PdfCircle inner = new PdfCircle(Center, InnerRadius, OutlineColor, Style.Width, PdfColorFactory.FromColor(Color.White));

    outer.Render(r);

    inner.Render(r);

}

In this routine, I create two circles, one for the outer circle and one for the inner.  The outer I create with the Donut’s line and fill properties.  The inner I do the same except that the fill I set to white.  I can try it out with the following test code:

PdfGeneratedDocument doc = new PdfGeneratedDocument();

PdfGeneratedPage page = PdfDefaultPages.Letter;

doc.Pages.Add(page);

Donut donut = new Donut(new PdfPoint(288, 400), 18, 100);

page.DrawingList.Add(donut);

doc.Save("donut.pdf");

When I run the app, I get a page that looks like this:

Hooray – that’s just what I expected!  There’s a problem, though.  If we draw the donut over the top of something else it will cover it up entirely, which is not what we expected:

PdfGeneratedDocument doc = new PdfGeneratedDocument();

PdfGeneratedPage page = PdfDefaultPages.Letter;

doc.Pages.Add(page);

// Add a red line from the center out

PdfPath path = new PdfPath(PdfColorFactory.FromColor(Color.Red), 8);

path.MoveTo(288, 400);

path.LineTo(500, 500);

page.DrawingList.Add(path);

Donut donut = new Donut(new PdfPoint(288, 400), 18, 100);

page.DrawingList.Add(donut);

doc.Save("donut.pdf");

The problem is clear – the inner circle is being painted white.  This will cover up anything under it.  In fact, we depend on that to cover up the brown donut.  The solution is to change our approach.  Instead of using two PdfCircle shapes, we’re going to use one PdfPath shape to represent both circles.  A path is a collection of operations that include move, draw line, draw Bezier curve, close the path.  The really cool thing is that a path can contain any number of possibly disjoint subpaths, so two circles are easy.  To start off with, we need a routine that give a PdfPath shape will add in a circle composed of Bezier curves.  To do this, I’ll break this out into a new method.  The code presented here is based on an article by Don Lancaster.  If you want to learn a great deal about the math behind Bezier curves, this is a great place to start.

protected override void DrawShape(Atalasoft.PdfDoc.Generating.Rendering.PdfPageRenderer r)

{

    PdfPath path = new PdfPath(OutlineColor, Style.Width, FillColor);

    MakeCircle(path, OuterRadius, Center);

    MakeCircle(path, InnerRadius, Center);

    path.Render(r);

}

private static PdfPath MakeCircle(PdfPath path, double radius, PdfPoint center)

{

    double magic = 0.551784 * radius;

    path.MoveTo(new PdfPoint(-radius, 0) + center);

    path.CurveTo(new PdfPoint(-radius, magic) + center, new PdfPoint(-magic, radius) + center, new PdfPoint(0, radius) + center);

    path.CurveTo(new PdfPoint(magic, radius) + center, new PdfPoint(radius, magic) + center, new PdfPoint(radius, 0) + center);

    path.CurveTo(new PdfPoint(radius, -magic) + center, new PdfPoint(magic, -radius) + center, new PdfPoint(0, -radius) + center);

    path.CurveTo(new PdfPoint(-magic, -radius) + center, new PdfPoint(-radius, -magic) + center, new PdfPoint(-radius, 0) + center);

    return path;

}

And, tada, here is our shape.  The question is, why isn’t the donut hole filled?  The answer is that PDF has two different ways to fill paths.  The first is called the Even-Odd Rule.  The PDF renderer figures out how many lines have been crossed as it goes left to right.  If the number is odd, it fills.  If the number is even it doesn’t.  This is the default method for filling.  The other method is called the Non-Zero Winding Rule.  It is more complicate and has to do with the direction that lines are drawn as they cross the scanline being filled.  Lines that cross bottom to top add 1 to the winding number.  Lines that cross top to bottom take one away.  If the winding number is non-zero, the scanline gets filled.  If this circle had been filled with NZW, the center would be brown and cover up the red line.

As a final best practice rule for making reusable shapes: make shapes as generic as possible and put them into their own assembly away from the rest of your application.  This will make it easier to reuse the shape in other projects and will make it more easier to reload the PDF in DotPdf for further editing.

2006

Venture Funding vs. Bootstrapping
On of my first blog posts about why not to take VC. As you might imagine, I’m pretty happy that we didn’t take on outside investment.

Inception of a Company Name
This is how the name Atalasoft came to be. It goes into more detail than I give when people ask me in-person, and some helpful tips if you’re thinking about a brand name yourself.

New Office – One Week to Go!
We started with a lot of room to grow. Now we completely fill the space! My office window still has a great view of Mt Tom.

From Nothing to Something
Talks about how I started Atalasoft. Whoa, my kids are bigger now.

The AJAX Craze: History of AJAX Imaging at Atalasoft
Yup, we knew zero-footprint imaging was the future back in 2006 and already had a couple years on the competition. Now we can call it the HTML Viewer because people expect rich client apps from HTML.

Starting a Company Outside a Startup Hub
Relates to my experience starting Atalasoft outside of San Francisco, Boston, or New York.

2007

Leveraging Emerging Technology as a Foundation for your Software Startup
Written 5-years ago, but still relevant today.

Financial Stability of a Bootstrapper
More info about how I started Atalasoft and financed it’s growth organically.

9 Concepts High-Tech CEO’s Should Know about Software Development
Turns out I know a thing or two about that. Still relevant.

Atalasoft Inc. – 5 Years Old
Never would have guessed that Atalasoft would be a Kofax Company at 10-years!

2008

The Case for Zero-Footprint Document Viewing
I would say we called that one and more people understand now

2011

A Reflection on Growing Atalasoft in 2010
Title speaks for itself. The growth led to the successful acquisition later in 2010.

The Big Deal – Kofax to Acquire us!
Phew! That took a LOT of work.

HTML and the end of the line for Flash and Silverlight
My prediction on the future of Rich Internet Application development, and why we won by investing heavily in HTML.

I plan to blog a mix of practical coding tips (the classic “don’t let this thing that just bit me bite you”), speculation about how this or that problem could be solved with computers and software, and accounts of the small epiphanies I have every now and then while studying linguistics and cognitive psychology.

• 14 Things Every Software Engineer Should Know
• Protect Yourself
• Why Software Has Bugs
• Robotron and OOP

I am a developer at Atalasoft, my main focus for the last couple of years has been building up our internal systems to do our day to day processing(website/Salesforce). I always seem to have my hands in way to many things and never have enough time to reflect on things I have done.  I am hoping to build up a collection of examples that will remind me of all the small things I have done throughout the days/weeks/months.  Too many times I do something and think “wow, that is really cool”, only to have it be locked away in some source control system.  Today, that ends.

Software Business

• Predicting Microsoft’s next move
• 25 ways to make content more findable
• Google can’t make mobile web apps as good as native, so can anyone?
• Making an SDK better at its job
• Usefulness as a pretense for data collection
• Movie Reviews from a software business perspective
  • Star Trek
  • Twilight: Eclipse
  • Inception
  • Twilight: Breaking Dawn

Tech job seeking

• Prepare for Interviews
• Advice for interviewing at Atalasoft
• You don’t need permission to get software development experience
• Portfolio based interviewing for developers
• You need more than a resumé

Technical

• This post will help you debug memory munging bugs on Windows.
• Here’s some technical advice on storing images in Databases
  • Part I
  • Part II
  • Some follow up years later
  • More follow up
• Here’s some code for generating Code 39 Barcodes in JavaScript
• Here’s .NET code for converting Word to PDF (by scripting Word to do it)
• Learn 80’s style programming today

Presenting

• If you want to know how to mess up a technical presentation, look no further.
• I did a lightning talk at Business of Software in 2008, here’s advice if you have to give one
  • Some background
  • Part I of my tips
  • Part II of my tips
  • My presentation on SlideShare