/*       Copyright (c) Eric Ledoux.  All rights reserved.       */
/* See http://www.dwell.net/terms for code sharing information. */

// SourceFileRenderer.cs
//
// Implements class SourceFileRenderer and related types.
//

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using System.Diagnostics;
using System.IO;
using System.Reflection;
using System.Text;
using System.Text.RegularExpressions;
using System.Web.UI;
using System.Xml;
using DwellNet.CodeDoc;
using CodeDocApi.Properties;

namespace DwellNet.CodeDoc
{

SourceFileRenderer Class

Converts a CodeDoc SourceFile to HTML.

public abstract class SourceFileRenderer
{
    //////////////////////////////////////////////////////////////////////////
    // Private Fields
    //

    
SourceFileRenderer.m_sourceFile Field

Holds the value of the SourceFile property.

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    SourceFile m_sourceFile;

    
SourceFileRenderer.m_markOfTheWeb Field

Holds the value of the MarkOfTheWeb property.

    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
    bool m_markOfTheWeb;

    //////////////////////////////////////////////////////////////////////////
    // Public Properties
    //

    
SourceFileRenderer.SourceFile Property

Sets or gets the source file being rendered by this SourceFileRenderer. This property should be set when the SourceFileRenderer is constructed, and should not modified after that.

    public SourceFile SourceFile
    {
        [DebuggerStepThrough]
        get
        {
            return m_sourceFile;
        }
        [DebuggerStepThrough]
        set
        {
            m_sourceFile = value;
        }
    }

    
SourceFileRenderer.MarkOfTheWeb Property

Gets or sets a value that indicates whether to include the Mark of the Web on generated HTML pages. See HtmlTextWriterHelper.BeginHtmlDocument for more information.

    public bool MarkOfTheWeb
    {
        [DebuggerStepThrough]
        get
        {
            return m_markOfTheWeb;
        }
        [DebuggerStepThrough]
        set
        {
            m_markOfTheWeb = value;
        }
    }

    //////////////////////////////////////////////////////////////////////////
    // Public Events
    //

    
SourceFileRenderer.WarningInSourceFile Event

Fired to indicate a warning associated with a given line number in a source file.

Remarks

The application may want to use this event to provide feedback to the user.

    public event WarningInSourceFileEventDelegate WarningInSourceFile;

    //////////////////////////////////////////////////////////////////////////
    // Public Methods
    //

    
SourceFileRenderer.CreateRenderer Method

Creates an instance of a source file renderer (i.e. a class derived from SourceFileRenderer) implemented in a given assembly (DLL).

Parameters

rendererAssemblyName

The name of the source file renderer assembly to use to generate formatted source code HTML; for example, "CodeDocRenderer". This DLL should be located in the same directory as the application .exe file.

rendererTypeName

The fully-qualified name of the source file renderer class; for example, "DwellNet.CodeDoc.DefaultSourceFileRenderer". This class must be implemented in the source file renderer assembly specified by rendererAssemblyName. This class must derive from the SourceFileRenderer.

markOfTheWeb

true to include the Mark of the Web on rendered pages. See HtmlTextWriterHelper.BeginHtmlDocument for more information.

Return Value

The source file renderer.

Exceptions
Exception type Condition
CreateExternalObjectException

Caused by one of the following conditions:

  • the assembly specified by rendererAssemblyName could not be loaded;
  • the assembly specified by rendererAssemblyName does not contain the type specified by rendererTypeName;
  • an instance of the type specified by rendererTypeName could not be created;
  • the created instance of the type specified by rendererTypeName is not based on class SourceFileRenderer.

    public static SourceFileRenderer CreateRenderer(string rendererAssemblyName,
        string rendererTypeName, bool markOfTheWeb)
    {
        SourceFileRenderer sourceFileRenderer =
            DocumentationSet.CreateExternalObject<SourceFileRenderer>(
                rendererAssemblyName, rendererTypeName);
        sourceFileRenderer.MarkOfTheWeb = markOfTheWeb;
        return sourceFileRenderer;
    }

    
SourceFileRenderer.GenerateCodeHtml Method (TopicRenderer, string)

Generates formatted source code HTML corresponding to SourceFile. Writes to a given file location.

Parameters

topicRenderer

The TopicRenderer to use to format XML comments.

path

The path to the file to write to.

    public void GenerateCodeHtml(TopicRenderer topicRenderer, string path)
    {
        using (StreamWriter streamWriter = new StreamWriter(path))
        {
            using (HtmlTextWriterHelper htmlWriter =
                    new HtmlTextWriterHelper(streamWriter))
                GenerateCodeHtml(topicRenderer, htmlWriter);
        }
    }

    
SourceFileRenderer.GenerateCodeHtml Method (TopicRenderer, HtmlTextWriterHelper)

Generates formatted source code HTML corresponding to SourceFile. Writes to a given HtmlTextWriterHelper.

Parameters

topicRenderer

The TopicRenderer to use to format XML comments.

htmlWriter

The HtmlTextWriterHelper to write to.

    public abstract void GenerateCodeHtml(TopicRenderer topicRenderer,
        HtmlTextWriterHelper htmlWriter);

    //////////////////////////////////////////////////////////////////////////
    // Protected Methods
    //

    
SourceFileRenderer.FireWarningInSourceFile Method

Fires the WarningInSourceFile event.

Parameters

lineNumber

The line number within the source file that the warning relates to.

format

A String.Format-style format string used to format the warning message text.

args

Arguments for the format string.

    protected void FireWarningInSourceFile(int lineNumber, string format,
        params object[] args)
    {
        if (WarningInSourceFile != null)
        {
            WarningInSourceFile(SourceFile, lineNumber,
                String.Format(format, args));
        }
    }
}

}