CodeBlockComponent Class

This build component is used to search for <code> XML comment tags and colorize the code within them. It can also include code from an external file or a region within the file.

Inheritance Hierarchy

SystemObject
Sandcastle.Core.BuildAssembler.BuildComponentBuildComponentCore
SandcastleBuilder.ComponentsCodeBlockComponent

Namespace: SandcastleBuilder.Components
Assembly: SandcastleBuilder.Components (in SandcastleBuilder.Components.dll) Version: 2014.11.22.0

Syntax

C++

Copy

public class CodeBlockComponent : BuildComponentCore

Public Class CodeBlockComponent
	Inherits BuildComponentCore

public ref class CodeBlockComponent : public BuildComponentCore

type CodeBlockComponent =  
    class
        inherit BuildComponentCore
    end

The CodeBlockComponent type exposes the following members.

Constructors

	Name	Description
	CodeBlockComponent	Constructor

Top

Methods

	Name	Description
	Apply	This is implemented to perform the code colorization. (Overrides BuildComponentCoreApply(XmlDocument, String).)
	Dispose	This implements the Dispose() interface to properly dispose of the build component. (Inherited from BuildComponentCore.)
	Dispose(Boolean)	This can be overridden by derived classes to add their own disposal code if necessary. (Inherited from BuildComponentCore.)
	Equals	Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
	Finalize	This handles garbage collection to ensure proper disposal of the build component if not done explicitly with Dispose. (Inherited from BuildComponentCore.)
	GetHashCode	Serves as a hash function for a particular type. (Inherited from Object.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	Initialize	This abstract method must be overridden to initialize the component (Overrides BuildComponentCoreInitialize(XPathNavigator).)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	OnComponentEvent	This can be used to raise the ComponentEvent event with the specified event arguments. (Inherited from BuildComponentCore.)
	ToString	Returns a string that represents the current object. (Inherited from Object.)
	WriteMessage(MessageLevel, String, Object)	This can be used to report a message (Inherited from BuildComponentCore.)
	WriteMessage(String, MessageLevel, String, Object)	This can be used to report a message for a specific topic ID (Inherited from BuildComponentCore.)

Top

Properties

	Name	Description
	BuildAssembler	This read-only property returns a reference to the build assembler instance using the component (Inherited from BuildComponentCore.)
	IsThreadSafe	Reserved for future use (Inherited from BuildComponentCore.)

Top

Remarks

The colorizer files are only copied once and only if code is actually colorized. If the files already exist (i.e. additional content has replaced them), they are not copied either. That way, you can customize the color style sheet as you see fit without modifying the default style sheet.

Examples

Example configuration

Copy

<!-- Code block component configuration.  This must appear before
     the TransformComponent. -->
<component id="Code Block Component">
    <!-- Base path for relative filenames in source
         attributes (optional). -->
    <basePath value="..\SandcastleComponents" />

    <!-- Base output paths for the files (required).  These should
         match the parent folder of the output path of the HTML files
         used in the SaveComponent instances. -->
    <outputPaths>
      <path value="Output\HtmlHelp1\" />
      <path value="Output\MSHelp2\" />
      <path value="Output\MSHelpViewer\" />
      <path value="Output\Website\" />
    </outputPaths>

    <!-- Allow missing source files (Optional).  If omitted,
         it will generate errors if referenced source files
         are missing. -->
    <allowMissingSource value="false" />

    <!-- Remove region markers from imported code blocks.  If omitted,
         region markers in imported code blocks are left alone. -->
    <removeRegionMarkers value="false" />

    <!-- Code colorizer options (required).
      Attributes:
        Language syntax configuration file (required)
        XSLT style sheet file (required)
        CSS style sheet file (required)
        Script file (required)
        Disabled (optional, leading whitespace normalization only)
        Default language (optional)
        Enable line numbering (optional)
        Enable outlining (optional)
        Keep XML comment "see" tags within the code (optional)
        Tab size for unknown languages (optional, 0 = use default)
        Use language name as default title (optional) -->
    <colorizer syntaxFile="highlight.xml" styleFile="highlight.xsl"
      stylesheet="highlight.css" scriptFile="highlight.js"
      disabled="false" language="cs" numberLines="false" outlining="false"
      keepSeeTags="false" tabSize="0" defaultTitle="true" />
</component>

Examples as used in XML comments.

Copy

<example>
A basic code block that uses the configuration defaults:
<code>
/// Code to colorize
</code>

Override options with block-specific options:
<code lang="xml" numberLines="true" outlining="false" tabSize="8" >
    &lt;XmlTags/&gt;
</code>

An entire external file or a delimited region from it can be
included.  This allows you to compile your example code externally
to ensure that it is still valid and saves you from maintaining it
in two places.

Retrieve all code from an external file.  Use VB.NET syntax.
<code source="..\Examples\WholeDemo.vb" lang="vbnet"/>

Retrieve a specific #region from an external file.
<code source="..\Examples\SeveralExamples.vb"
    region="Example 1" lang="vbnet"/>

Keep <see> tags within comments so that they are converted to
links to the help topics.
<code keepSeeTags="true">
int x = this.<see cref="CountStuff">CountStuff</see>(true);

string value = this.<see cref="System.Object.ToString">
<code>

<example>

Reference

SandcastleBuilder.Components Namespace