Cellbi.DocFramework Features Overview

Sample code language:

Creating Documents
Document Text Edit Model
- Formatting Text
Document Tree Edit Model

Creating Documents

Document class is the main entry point of the Cellbi.DocFramework library. Document class contains a set of text manipulation methods, methods to save and load document using given document format.

Create and save document in MS Word document format:

Document doc = new Document();
doc.Save(DocFormat.Instance, "CreateDocumentSample");

Document Text Edit Model

Document text edit model allows direct access to any document portion as a plain text. Direct access to document text is useful when you need to perform text editing operations without need to know how document structure is represented. Document text edit model supports text formatting, document styles and document selectors. Document text edit model is very flexible and easy to use, but we also support composite document structure represented as document tree with text blocks, paragraphs, sections and other document tree nodes. Moreover each document tree node supports plain document edit model, so all text editing operations valid for document level is also valid for individual document tree nodes: text blocks, paragraphs, sections and etc.

Adding, Inserting or Removing Text

Adding, inserting or removing text tasks can be easily done using AppendText, InsertText and RemoveText methods.

Append text:

doc.AppendText("Plain Text");

Insert text at 6 char position:

doc.InsertText(6, " Inserted ");

Remove 5 chars starting from 6 char position:

doc.RemoveText(6, 5);

Formatting Text

Formatting of new text can be done using return values of the AppendText and InsertText methods. These methods return IHasCharacterFormatting interface implementer. IHasCharacterFormatting interface contains border, shading and font properties.

Font formatting:

doc.AppendText("Bold Text").Font.Bold = true;
doc.AppendText("Bold and Italic Text").Font.Italic = true;
doc.AppendText("Bold, Italic and Striked Text").Font.Strike = true;

doc.AppendText("Default Text").Font = TextFont.Default;
doc.AppendText("Red Text").Font.Color = Color.Red;
doc.AppendText("Blue Text").Font.Color = Color.Blue;

TextFont font = TextFont.Default;
font.Size = 24;
font.UpperCase = true;
doc.AppendText("24 Size Uppercase Text").Font = font;

Document Tree Edit Model

Document tree edit model is designed to provide structured access to composite document content. Low level nodes are text blocks which contain character formatting. Text blocks are contained inside paragraphs, paragraphs in turn are contained inside sections, and sections are contained inside document. For each document tree node it is possible to apply text editing operations which are valid for document text edit model.

All document tree node elements descend from abstract TextElement class. It is the TextElement class which provides text editing methods and allows access to children document tree nodes.

Text Blocks

Text block is the simplest document tree node. Text blocks are leaf nodes and contain only character formatting of the associated text. It’s pretty straightforward to create and add text blocks to a paragraph.

Appending text to a paragraph:

doc.AppendText("First text chunk");

Paragraph documentParagraph = doc.AppendParagraph(String.Empty);
documentParagraph.AppendText("Second text chunk.");

Creating simple text block:

TextBlock block = new TextBlock();

block.AppendText("Text block text.");
block.Font.Name = "Cambria";
block.Font.Color = Color.Red;
block.Font.Size = 24;

Paragraph paragraph = doc.AppendParagraph(String.Empty);
paragraph.AppendTextBlock(block);

It’s also possible to extend document tree model and create custom document tree nodes with predefined formatting properties:

class CustomTextBlock : TextBlock
{
  public CustomTextBlock()
  {
    AppendText("Text block text.");
    Font.Name = "Cambria";
    Font.Size = 24;
    Font.Color = Color.Red;
  }
}

//...

CustomTextBlock customTextBlock = new CustomTextBlock();
paragraph.AppendTextBlock(customTextBlock);

Paragraphs

Paragraph is document tree node which contains text block nodes. Paragraph has several properties describing text formatting, e.g. text alignment, line spacing and etc. Paragraph node also supports character formatting properties of the text associated with the paragraph.

Appending simple paragraph to a document:

Paragraph simple = doc.AppendParagraph("Document paragraph");

Creating paragraph with first line indent and 1.5 line spacing interval:

Paragraph paragraph = new Paragraph();
paragraph.LineSpacing.Multiplier = LineSpaceMultiplier.Multiplier;
paragraph.LineSpacing.Value = 1.5f;      
paragraph.FirstLineIndent = PageUnits.FromCentimeters(0.5f);

paragraph.AppendText("Paragraph text");

doc.AppendParagraph(paragraph);

It’s also possible to define custom paragraphs and append them into target document:

class CustomParagraph : Paragraph
{
  public CustomParagraph()
  {
    LineSpacing.Multiplier = LineSpaceMultiplier.Multiplier;
    LineSpacing.Value = 1.5f;
    FirstLineIndent = PageUnits.FromCentimeters(0.5f);

    AppendText("Paragraph text");
  }
}

//...

CustomParagraph customParagraph = new CustomParagraph();
doc.AppendParagraph(customParagraph);

Simple Lists

Simple lists can be easily added to a document using AppendList method. List format can be specified via ListFormat property on the List class instance. Example code below will create single level list and append it to a document.

Single level list:

List list = doc.AppendList();
list.AppendLevel("First item");
list.AppendLevel("Second item");
list.AppendLevel("Third item");

Creating single level list and appending to a document:

List simpleList = new List();
simpleList.AppendLevel("First item");
simpleList.AppendLevel("Second item");
simpleList.AppendLevel("Third item");

doc.AppendList(simpleList);

Creating custom list:

class CustomList : List
{
  public CustomList()
  {
    AppendLevel("First item");
    AppendLevel("Second item");
    AppendLevel("Third item");
  }
}

// ...

CustomList customList = new CustomList();
doc.AppendList(customList);

Multi-level Lists

Multi level lists are added the same way as single level lists, but with different ListFormat. There are helper methods inside ListFormat class to create single and multi level list levels.

Multi level list:

List multiLevelList = doc.AppendList();
multiLevelList.ListFormat = ListFormat.GetMultiLevelListFormat(NumberType.Arabic);

ListLevel firstItem = multiLevelList.AppendLevel("First item");
firstItem.AppendLevel("First child item");

ListLevel secondItem = multiLevelList.AppendLevel("Second item");
secondItem.AppendLevel("Second child item");

ListLevel thirdItem = multiLevelList.AppendLevel("Third item");
thirdItem.AppendLevel("Third child item");

Custom multi level list:

class CustomMultiLevelList : List
{
  public CustomMultiLevelList()
  {
    ListFormat = ListFormat.GetMultiLevelListFormat(NumberType.Ordinal);

    ListLevel firstItem = AppendLevel("First item");
    firstItem.AppendLevel("First child item");

    ListLevel secondItem = AppendLevel("Second item");
    secondItem.AppendLevel("Second child item");

    ListLevel thirdItem = AppendLevel("Third item");
    thirdItem.AppendLevel("Third child item");
  }
}

// ...

CustomMultiLevelList customMultiLevelList = new CustomMultiLevelList();
doc.AppendList(customMultiLevelList);

Sections

Document sections provide a way of separating document on several individual parts with different formatting. Section has formatting properties which can be used to specify how many columns of text the section has, which page format and page orientation the section uses, which page margins are set for the section and etc.

Appending simple section to a document:

Section simple = doc.AppendSection("Simple section");

Section with A5 page format, landscape page orientation and with 2 columns of text:

Section section = new Section();
section.PageFormat = PageFormat.A5;
section.PageOrientation = PageOrientation.Landscape;
section.ColumnCount = 2;
section.ColumnDistance = PageUnits.FromCentimeters(1.0f);

doc.AppendSection(section);

And we can also create custom section and insert it into our document:

class CustomSection : Section
{
  public CustomSection()
  {
    PageFormat = PageFormat.A5;
    PageOrientation = PageOrientation.Landscape;
    ColumnCount = 2;
    ColumnDistance = PageUnits.FromCentimeters(1.0f);
  }
}

// ...

CustomSection customSection = new CustomSection();
doc.AppendSection(customSection);

Styles

Applying character style to a text:

Style style = doc.AddStyle(StyleType.Character, "Character Style");
style.Font.Name = "Cambria";
style.Font.Size = 26;
style.Font.Bold = true;
style.Font.Italic = true;

IHasCharacterFormatting formatting = doc.AppendText("Character style text");
formatting.ApplyStyle(style);

It is also possible to create paragraph styles and apply them to a paragraph or list of paragraphs. Styles inheritance is also fully supported. It’s recommended to create and use document styles to describe complex document formatting, so later if different appearance is needed document styles can be easily adjusted and the document appearance will be completely different.

Example of paragraph styles:

ParagraphStyle paragraphStyle = doc.AddStyle(StyleType.Paragraph, "Paragraph style") as ParagraphStyle;
paragraphStyle.TextAlignment = TextAlignment.Centered;

Paragraph paragraph = doc.AppendParagraph("First Paragraph");
paragraph.Style = paragraphStyle;

paragraph = doc.AppendParagraph("Second Paragraph");
paragraph.Style = paragraphStyle;

paragraphStyle.Font.Bold = true;

Note that we applied the same paragraph style to newly created paragraphs, later we changed bold property of the style and this change reflected on the two paragraphs defined previously.

Pictures

Pictures can be added to any paragraph inside a document. Creating pictures is easy.

Appending picture to a paragraph:

Paragraph simple = doc.AppendParagraph(String.Empty);
int width = PageUnits.FromCentimeters(12.15f);
int height = PageUnits.FromCentimeters(4.0f);
simple.AppendPicture(Resources.Guitar, width, height);

Adding picture to a document:

Picture picture = new Picture();
picture.Image = Resources.Guitar;
picture.Width = PageUnits.FromCentimeters(12.15f);
picture.Height = PageUnits.FromCentimeters(4.0f);

Paragraph paragraph = doc.AppendParagraph(String.Empty);
paragraph.AppendPicture(picture);

Custom picture example:

class CustomPicture : Picture
{
  public CustomPicture()
  {
    Image = Resources.Guitar;
    Width = PageUnits.FromCentimeters(12.15f);
    Height = PageUnits.FromCentimeters(4.0f);
  }
}

// ...

CustomPicture customPicture = new CustomPicture();
paragraph.AppendPicture(customPicture);