DocGenerator API: sentence style

This article presents how to specify the style of a sentence in the API.

Some of the methods allowing to create sentences allow to specify the type of the sentence^[1]

Such as Bold, Italic, Underlined, etc...

. However, it is not possible to set more style attributes directly^[2]

For example the color of the text, the font family, the font size, etc...

Setting directly the font type of the sentence

You can set the font type of the sentence or anchors with methods such as:

• DocGeneratorAPI.addSentence(XMLArticle, String, int) for a sentence
• DocGeneratorAPI.addAnchor(XMLArticle, String, String, int) for an anchor

The different possible types of the text are specified in the FontType. For example:

   // for a bold text:
   api.addSentence(article, "this is the bold sentence", FontType.BOLD);
   // for a bold and italic text:
   api.addSentence(article, "this is the bold sentence", FontType.BOLD + FontType.ITALIC);      

Specifying a more complex style

The SentenceStyle class allows to specify the style of the sentence:

• The color field specifies the sentence text color
• The background field specifies the sentence background color
• The fontFace field specifies the sentence font face^[3]
  The FontFace interface list the valid font faces usable in the wiki
• The size field specifies the numeric size of the font
• The namedSize field specifies the named size of the font^[4]
  The FontSize interface list the valid sizes usable in the wiki
• The type field specifies the type of the font

Several method allow to combine styles for one SentenceStyle. For example to following code:

   SentenceStyle style = new SentenceStyle();
   style.color = "red";
   style.fontFace = FontFace.HELVETICA;
   style.namedSize = FontSize.SMALL;

is equivalent to:

  SentenceStyle style = SentenceStyle.createColorStyle("red").setFamily(FontFace.HELVETICA).setSize(FontSize.SMALL);

To specify the style of a sentence, you can use:

• DocGeneratorAPI.addTextStyle(XMLArticle, SentenceStyle) to creates a new XMLTextStyle element, which can contain both anchors and sentences

Examples

Suppose that we created a new article:

   DocGeneratorAPI api = new DocGeneratorAPI();
   api.createModel();
   api.setOutputDirectory(<the wiki directory>);
         
   // create an article
   XMLArticle article = api.createArticle("article1");

The following example creates a bold sentence:

   api.addSentence(article, "this is the bold sentence", FontType.BOLD);

The following example creates a sentence with a small Helvetica font, using a red color:

   SentenceStyle style = new SentenceStyle();
   style.color = "red";
   style.fontFace = FontFace.HELVETICA;
   style.namedSize = FontSize.SMALL;
   XMLTextStyle textStyle = api.addTextStyle(article, style);      
   api.addSentence(textStyle, "this is the styled sentence");

The following example does the same in a more straightforward way:

      api.addSentence(SentenceStyle.createColorStyle("red").setFamily(FontFace.HELVETICA).setSize(FontSize.SMALL), "this is the styled sentence");