/// <summary>
        /// Recursively add a column to the collection of rows.
        /// </summary>
        /// <param name="iContent">The content of the current row in the recursion.</param>
        /// <param name="rowTemplate">The template describing the layout of data in the current row.</param>
        internal void RecursivelyAddColumns(IContent iContent, RowTemplate rowTemplate)
        {
            // This section of code will create a virtual cell where data can be found and coordinates in the document space assigned.  The existing row is
            // pulled apart and the properties are examined.  If a template has been associated with the property's type, then an association can be made
            // between the row and the column where this property should be displayed.
            ReportRow reportRow = null;

            if (this.dictionary.TryGetValue(iContent.Key, out reportRow))
            {
                foreach (PropertyInfo propertyInfo in iContent.GetType().GetProperties())
                {
                    IContent childContent = propertyInfo.GetValue(iContent, null) as IContent;
                    if (childContent != null)
                    {
                        string columnId;
                        if (this.reportGrid.reportFieldCollection.ColumnIdMap.TryGetValue(childContent.GetType(), out columnId))
                        {
                            ReportColumn reportColumn;
                            if (this.reportGrid.reportColumnCollection.TryGetValue(columnId, out reportColumn))
                            {
                                if (!reportRow.ContainsKey(reportColumn))
                                {
                                    reportRow.Add(reportColumn, new ReportCell(childContent, reportColumn, reportRow));
                                }
                            }
                        }
                    }
                }
            }

            // This will recurse into the report's hierarchy.  Each row template can specify a child row and the property that is
            // used to create that child row.  These, in turn, can be recursed into ad infinitum.
            foreach (RowTemplate childRowDefinition in rowTemplate.Children)
            {
                PropertyInfo propertyInfo = iContent.GetType().GetProperty(childRowDefinition.Path);
                Object       property     = propertyInfo.GetGetMethod().Invoke(iContent, null);
                if (property is IEnumerable)
                {
                    IEnumerable iEnumerable = property as IEnumerable;
                    foreach (IContent childContent in iEnumerable)
                    {
                        RecursivelyAddColumns(childContent, childRowDefinition);
                    }
                }
            }
        }
        /// <summary>
        /// Constructs a collection of report rows based on the data content and the templates that describes the row.
        /// </summary>
        /// <param name="iContent">The content to be displayed in the row.</param>
        /// <param name="rowTemplate">The template that describes how the data is presented.</param>
        private void RecursivelyUpdateRow(IContent iContent, RowTemplate rowTemplate)
        {
            // Each IContent object has a unique key used to associate it with a report row.  If a given report row has already has been mapped to the
            // IContent's key, then the contents of that row will be updated.  Otherwise, a new row is created and associated with the IContent.
            ReportRow reportRow = null;

            if (iContent.Key != null && this.dictionary.TryGetValue(iContent.Key, out reportRow))
            {
                // Any change to the location or the height of the row will be animated so long as the current or target location is visible.  There is no
                // sense in animating the movement of invisible elements of the report.
                if (reportRow.Top != this.height || reportRow.Height != rowTemplate.Height)
                {
                    // At this point it has been determined that the row has moved.  An animation sequence will be created for those rows that appear in or
                    // disappear from the viewport.
                    Boolean isRowVisible = (this.viewport.Top <= reportRow.Top && reportRow.Top < this.viewport.Bottom) ||
                                           (this.viewport.Top <= reportRow.Top + reportRow.Height && reportRow.Top + reportRow.Height < this.viewport.Bottom);
                    Boolean willRowBeVisible = (this.viewport.Top <= this.height && this.height < this.viewport.Bottom) ||
                                               (this.viewport.Top <= this.height + rowTemplate.Height && this.height + rowTemplate.Height < this.viewport.Bottom);

                    // This creates a list of rows who's ZIndex must be set for the animation sequence.
                    if (isRowVisible || willRowBeVisible)
                    {
                        // At this point the report row either is currently visible or will be visible and has been moved or resized.  This means that the
                        // visible part of the virtual document should be measured.  Items that have become visible will need to be instantiated and items that
                        // are no longer visible need to be recycled.
                        this.isMeasurementRequired = true;

                        // The ZIndex of this row is set such that the rows that move the greatest distance will appear to float above the ones that only move a little.  This scheme
                        // makes the movement appear more natural.
                        reportRow.ZIndex = Math.Abs(reportRow.Ordinal - this.ordinal);

                        // When all the report rows have been examined and the Z order of the visible rows set, this list is used to set the ZIndex of all the
                        // graphical elements associated with this row.
                        this.animatedRows.Add(reportRow);
                    }

                    // The order of the row in the report is used for setting graphical cues such as shading and Z order.
                    reportRow.Ordinal = this.ordinal;

                    // If the location occupied by this row has changed then an animation sequence is constructed to move a row from one place to another.  If
                    // the row isn't visible or is not going to be visible, then just the location is modified.
                    if (reportRow.Top != this.height)
                    {
                        // This will move the row to its proper position in the virtual document.
                        reportRow.Top = this.height;

                        // The starting location is clipped by the visible part of the report.  This prevents a row that is moved to a far distant place from
                        // moving too fast to be seen on the screen.
                        // HACK - This should be repaired when time permits.
//						Double startLocation = (reportRow.ActualTop < viewport.Top) ? viewport.Top - reportRow.Height :
//							(reportRow.ActualTop > viewport.Bottom) ? viewport.Bottom : reportRow.ActualTop;
                        Double startLocation = reportRow.ActualTop;

                        // The ending location is also clipped by the visible part of the report for the same reason.  Without this code, rows appear to
                        // disappear instantly from the screen instead of moving smoothly to the nearest edge.
                        // HACK - This should be repaired when time permits.
//						Double endLocation = (reportRow.Top + reportRow.Height < viewport.Top) ? viewport.Top - reportRow.Height :
//							(reportRow.Top > viewport.Bottom) ? viewport.Bottom : reportRow.Top;
                        Double endLocation = reportRow.Top;

                        // This animates the movement of the row from its current position to the new position.  If the row is no longer visible then any
                        // animation that was associated with that row will be terminated.
                        if (isRowVisible || willRowBeVisible)
                        {
                            DoubleAnimation topAnimation = new DoubleAnimation();
                            Storyline.SetTargetObject(topAnimation, reportRow);
                            Storyline.SetTargetProperty(topAnimation, ReportRow.ActualTopProperty);
                            topAnimation.From     = startLocation;
                            topAnimation.To       = endLocation;
                            topAnimation.Duration = this.reportGrid.Duration;
                            this.storyline.Children.Add(topAnimation);
                        }
                        else
                        {
                            if (reportRow.HasAnimatedProperties)
                            {
                                reportRow.ApplyAnimationClock(ReportRow.ActualTopProperty, null);
                            }
                            reportRow.ActualTop = reportRow.Top;
                        }
                    }

                    // If the height occupied by this row has changed then an animation sequence is constructed to resize the row.  If the row isn't visible or
                    // is not going to be visible, then the property is modified without an animation sequence. This saves the processor from doing work when
                    // an element isn't visible.
                    if (reportRow.Height != rowTemplate.Height)
                    {
                        // This sets the height of the row.
                        reportRow.Height = rowTemplate.Height;

                        // This will animate the change in the row's height from the current height to the new target height.
                        if (isRowVisible || willRowBeVisible)
                        {
                            DoubleAnimation heightAnimation = new DoubleAnimation();
                            Storyline.SetTargetObject(heightAnimation, reportRow);
                            Storyline.SetTargetProperty(heightAnimation, ReportRow.ActualHeightProperty);
                            heightAnimation.From     = reportRow.ActualHeight;
                            heightAnimation.To       = reportRow.Height;
                            heightAnimation.Duration = this.reportGrid.Duration;
                            this.storyline.Children.Add(heightAnimation);
                        }
                        else
                        {
                            if (reportRow.HasAnimatedProperties)
                            {
                                reportRow.ApplyAnimationClock(ReportRow.ActualHeightProperty, null);
                            }
                            reportRow.ActualHeight = reportRow.Height;
                        }
                    }
                }

                // A virtual method is used to copy the current content over the existing content.  The event handlers will take
                // care of propagating the content and properties of the data to the screen elements.
                reportRow.IContent.Copy(iContent);

                // This indicates that the row is still in use and shouldn't be purged.
                reportRow.IsObsolete = false;
            }
            else
            {
                // This is where new rows are created to hold the given content and added to the report.
                reportRow          = new ReportRow();
                reportRow.IContent = iContent;
                this.dictionary.Add(iContent.Key, reportRow);

                // The order of the row in the report drives visual cues such as alternate line shading and Z order properties.
                reportRow.Ordinal = this.ordinal;

                // The target location and height are initialized here without animation.
                reportRow.Top    = this.height;
                reportRow.Height = rowTemplate.Height;

                // The actual top and height used when rendering the rows.
                reportRow.ActualTop    = reportRow.Top;
                reportRow.ActualHeight = reportRow.Height;

                // Rows that are added to the visible portion of the display will trigger the 'MeasureOverride' which will instantiate the new report elements.
                if ((this.viewport.Top <= reportRow.Top && reportRow.Top < this.viewport.Bottom) ||
                    (this.viewport.Top <= reportRow.Top + reportRow.Height && reportRow.Top + reportRow.Height < this.viewport.Bottom))
                {
                    this.isMeasurementRequired = true;
                }

                // The report row is really just a container for report cells.  The System.Reflection library is used to rip apart the content and create
                // columns that are tightly bound to the type of data found in the incoming record.
                foreach (PropertyInfo propertyInfo in iContent.GetType().GetProperties())
                {
                    IContent childContent = propertyInfo.GetValue(iContent, null) as IContent;
                    if (childContent != null)
                    {
                        string columnId;
                        if (this.reportGrid.reportFieldCollection.ColumnIdMap.TryGetValue(childContent.GetType(), out columnId))
                        {
                            ReportColumn reportColumn;
                            if (this.reportGrid.reportColumnCollection.TryGetValue(columnId, out reportColumn))
                            {
                                reportRow.Add(reportColumn, new ReportCell(childContent, reportColumn, reportRow));
                            }
                        }
                    }
                }
            }

            // This is used to keep track of the order of the row in the report.
            this.ordinal++;

            // This moves the virtual cursor up to the next available row in the virtual space.
            this.height += reportRow.Height;

            // The report can have any number of levels in the hierarchical arrangment or the rows.  This will recurse into the template that defines the
            // outline of the report and generate any rows that can be matched to the templates that are children of the current template.  The 'Path' property
            // on the template rows indicate which properties of the content row to follow when recursing.
            foreach (RowTemplate childRowDefinition in rowTemplate.Children)
            {
                PropertyInfo propertyInfo = iContent.GetType().GetProperty(childRowDefinition.Path);
                if (propertyInfo != null)
                {
                    Object property = propertyInfo.GetValue(iContent, null);
                    if (property is IEnumerable)
                    {
                        IEnumerable iEnumerable = property as IEnumerable;
                        foreach (IContent childContent in iEnumerable)
                        {
                            RecursivelyUpdateRow(childContent, childRowDefinition);
                        }
                    }
                }
            }
        }