Support rendering lists in snippet RTF reports

Update URTFUtils to support 3 more RTF controls for controlling first
line offset, left indent and tabstops.

Add support to TRTFStyles for recording indentation and calculating the
identation required at a given identation depth.

Add new methods to TRTFBuilder to set indents and tab stops. (Also did
minor refactoring of SetParaSpacing method.)

Major rewrite of TActiveTextRTF to support lists. Added support for
rendering active text bullet and numbered lists in RTF. Also added
support for new ekBlock active text element.

Add styles for lists in TRTFSnippetDoc and adjusted some other styles to
suit. Also evised spacing between description and source code & added
"Source Code" heading. Updated and added some constants.

Author: delphidabbler

Src/ActiveText.URTFRenderer.pas

@@ -45,11 +45,34 @@   TActiveTextRTFStyleMap = class(TObject)
 type
   TActiveTextRTF = class(TObject)
   strict private
+    const
+      // Difference between indent levels in twips
+      IndentDelta = 360;
+      // RTF Bullet character
+      Bullet = #$2022;
+    type
+      TListKind = (lkNumber, lkBullet);
+      TListState = record
+      public
+        ListNumber: Cardinal;
+        ListKind: TListKind;
+        constructor Create(AListKind: TListKind);
+      end;
+      TLIState = record
+        IsFirstPara: Boolean;
+        Prefix: string;
+        constructor Create(AIsFirstPara: Boolean; const APrefix: string);
+      end;
     var
       fElemStyleMap: TActiveTextRTFStyleMap;
       fDisplayURLs: Boolean;
       fURLStyle: TRTFStyle;
-      fInBlock: Boolean;
+      fBlockStack: TStack<TActiveTextActionElemKind>;
+      fListStack: TStack<TListState>;
+      fIndentStack: TStack<SmallInt>;
+      fLIStack: TStack<TLIState>;
+      fIndentLevel: Byte;  // logical indent level
+      fInPara: Boolean;
     procedure SetElemStyleMap(const ElemStyleMap: TActiveTextRTFStyleMap);
     procedure Initialise(const Builder: TRTFBuilder);
     procedure RenderTextElem(Elem: IActiveTextTextElem;
@@ -60,6 +83,7 @@   TActiveTextRTF = class(TObject)
       const Builder: TRTFBuilder);
     procedure RenderURL(Elem: IActiveTextActionElem;
       const Builder: TRTFBuilder);
+    function CanEmitInline: Boolean;
   public
     constructor Create;
     destructor Destroy; override;
@@ -76,8 +100,10 @@ implementation
 
 
 uses
+  // Delphi
+  SysUtils, Generics.Defaults,
   // Project
-  SysUtils, Generics.Defaults;
+  UConsts, UStrUtils;
 
 
 { TActiveTextRTFStyleMap }
@@ -155,15 +181,32 @@ procedure TActiveTextRTFStyleMap.MakeMonochrome;
 
 { TActiveTextRTF }
 
+function TActiveTextRTF.CanEmitInline: Boolean;
+begin
+  if fBlockStack.Count <= 0 then
+    Exit(False);
+  Result := TActiveTextElemCaps.CanContainText(fBlockStack.Peek);
+end;
+
 constructor TActiveTextRTF.Create;
 begin
   inherited Create;
   fElemStyleMap := TActiveTextRTFStyleMap.Create;
   fURLStyle := TRTFStyle.CreateNull;
+  fBlockStack := TStack<TActiveTextActionElemKind>.Create;
+  fListStack := TStack<TListState>.Create;
+  fIndentStack := TStack<SmallInt>.Create;
+  fLIStack := TStack<TLIState>.Create;
+  fIndentLevel := 0;
+  fInPara := False;
 end;
 
 destructor TActiveTextRTF.Destroy;
 begin
+  fLIStack.Free;
+  fIndentStack.Free;
+  fListStack.Free;
+  fBlockStack.Free;
   fElemStyleMap.Free;
   inherited;
 end;
@@ -189,7 +232,6 @@ procedure TActiveTextRTF.Render(ActiveText: IActiveText;
   ActionElem: IActiveTextActionElem;
 begin
   Initialise(RTFBuilder);
-  fInBlock := False;
   for Elem in ActiveText do
   begin
     if Supports(Elem, IActiveTextTextElem, TextElem) then
@@ -206,27 +248,154 @@ procedure TActiveTextRTF.Render(ActiveText: IActiveText;
 
 procedure TActiveTextRTF.RenderBlockActionElem(Elem: IActiveTextActionElem;
   const Builder: TRTFBuilder);
+
+  procedure OpenListContainer(const ListKind: TListKind);
+  begin
+    fListStack.Push(TListState.Create(ListKind));
+    Inc(fIndentLevel);
+    Builder.BeginGroup;
+  end;
+
+  function IndentTwips: SmallInt;
+  begin
+    Result := fElemStyleMap[ekListItem].IndentLevelToTwips(fIndentLevel)
+  end;
+
+var
+  ListState: TListState;
+  LIState: TLIState;
+  Style: TRTFStyle;
 begin
   case Elem.State of
     fsOpen:
     begin
-      fInBlock := True;
-      Builder.BeginGroup;
-      Builder.ApplyStyle(fElemStyleMap[Elem.Kind]);
+      fInPara := False;
+      fBlockStack.Push(Elem.Kind);
+      case Elem.Kind of
+        ekPara, ekHeading, ekBlock:
+        begin
+          Builder.BeginGroup;
+          Style := fElemStyleMap[Elem.Kind];
+          if fLIStack.Count > 0 then
+          begin
+            Builder.SetTabStops([IndentTwips]);
+            if fLIStack.Peek.IsFirstPara then
+            begin
+              Builder.SetIndents(
+                IndentTwips, -fElemStyleMap[ekListItem].IndentDelta
+              );
+              if (fListStack.Count > 0) then
+              begin
+                if fListStack.Peek.ListNumber = 1 then
+                begin
+                  Style.Capabilities := Style.Capabilities + [scParaSpacing];
+                  if fListStack.Peek.ListKind = lkNumber then
+                    Style.ParaSpacing := TRTFParaSpacing.Create(
+                      fElemStyleMap[ekOrderedList].ParaSpacing.Before, 0.0
+                    )
+                  else
+                    Style.ParaSpacing := TRTFParaSpacing.Create(
+                      fElemStyleMap[ekUnorderedList].ParaSpacing.Before, 0.0
+                    )
+                end
+                else if fListStack.Peek.ListNumber > 1 then
+                begin
+                  if Elem.Kind = ekHeading then
+                  begin
+                    Style.Capabilities := Style.Capabilities + [scParaSpacing];
+                    Style.ParaSpacing := fElemStyleMap[ekPara].ParaSpacing;
+                  end;
+                end;
+              end;
+              Builder.ApplyStyle(Style);
+              Builder.AddText(fLIStack.Peek.Prefix);
+              Builder.AddText(TAB);
+              fInPara := True;
+            end
+            else
+            begin
+              Builder.ApplyStyle(Style);
+              Builder.SetIndents(IndentTwips, 0);
+            end;
+          end
+          else
+          begin
+            Builder.ApplyStyle(Style);
+            Builder.SetIndents(IndentTwips, 0);
+          end;
+        end;
+        ekUnorderedList:
+          OpenListContainer(lkBullet);
+        ekOrderedList:
+          OpenListContainer(lkNumber);
+        ekListItem:
+        begin
+          // Update list number of current list
+          ListState := fListStack.Pop;
+          Inc(ListState.ListNumber, 1);
+          fListStack.Push(ListState);
+          Builder.BeginGroup;
+          Builder.ApplyStyle(fElemStyleMap[Elem.Kind]);
+          case fListStack.Peek.ListKind of
+            lkNumber:
+            begin
+              fLIStack.Push(
+                TLIState.Create(
+                  True, IntToStr(fListStack.Peek.ListNumber) + '.'
+                )
+              );
+            end;
+            lkBullet:
+            begin
+              fLIStack.Push(TLIState.Create(True, Bullet));
+            end;
+          end;
+          Builder.ClearParaFormatting;
+        end;
+      end;
     end;
     fsClose:
     begin
-      Builder.EndPara;
-      Builder.EndGroup;
-      fInBlock := False;
+      case Elem.Kind of
+        ekPara, ekHeading, ekBlock:
+        begin
+          if (fLIStack.Count > 0) and (fLIStack.Peek.IsFirstPara) then
+          begin
+            // Update item at top of LI stack to record not first para
+            LIState := fLIStack.Pop;
+            LIState.IsFirstPara := False;
+            fLIStack.Push(LIState);
+          end;
+          if fInPara then
+            Builder.EndPara;
+          Builder.EndGroup;
+        end;
+        ekUnorderedList, ekOrderedList:
+        begin
+          if fInPara then
+            Builder.EndPara;
+          Builder.EndGroup;
+          fListStack.Pop;
+          Dec(fIndentLevel);
+        end;
+        ekListItem:
+        begin
+          if fInPara then
+            Builder.EndPara;
+          Builder.EndGroup;
+          fLIStack.Pop;
+        end;
+      end;
+      fBlockStack.Pop;
+      fInPara := False;
     end;
   end;
 end;
 
 procedure TActiveTextRTF.RenderInlineActionElem(Elem: IActiveTextActionElem;
   const Builder: TRTFBuilder);
 begin
-  if not fInBlock then
+  if not CanEmitInline then
     Exit;
   case Elem.State of
     fsOpen:
@@ -245,10 +414,20 @@ procedure TActiveTextRTF.RenderInlineActionElem(Elem: IActiveTextActionElem;
 
 procedure TActiveTextRTF.RenderTextElem(Elem: IActiveTextTextElem;
   const Builder: TRTFBuilder);
+var
+  TheText: string;
 begin
-  if not fInBlock then
+  if not CanEmitInline then
     Exit;
-  Builder.AddText(Elem.Text);
+  TheText := Elem.Text;
+  // no white space emitted after block start until 1st non-white space
+  // character encountered
+  if not fInPara then
+    TheText := StrTrimLeft(Elem.Text);
+  if TheText = '' then
+    Exit;
+  Builder.AddText(TheText);
+  fInPara := True;
 end;
 
 procedure TActiveTextRTF.RenderURL(Elem: IActiveTextActionElem;
@@ -271,5 +450,22 @@ procedure TActiveTextRTF.SetElemStyleMap(
   fElemStyleMap.Assign(ElemStyleMap);
 end;
 
+{ TActiveTextRTF.TListState }
+
+constructor TActiveTextRTF.TListState.Create(AListKind: TListKind);
+begin
+  ListNumber := 0;
+  ListKind := AListKind;
+end;
+
+{ TActiveTextRTF.TLIState }
+
+constructor TActiveTextRTF.TLIState.Create(AIsFirstPara: Boolean;
+  const APrefix: string);
+begin
+  IsFirstPara := AIsFirstPara;
+  Prefix := APrefix;
+end;
+
 end.
 

Src/URTFBuilder.pas

@@ -179,6 +179,12 @@   TRTFBuilder = class(TObject)
     ///  <summary>Sets before and after spacing, in points, to be used for
     ///  subsequent paragraphs.</summary>
     procedure SetParaSpacing(const Spacing: TRTFParaSpacing);
+    ///  <summary>Sets left and first line indents, in twips to be used for
+    ///  subsequent paragraphs.</summary>
+    procedure SetIndents(const LeftIndent, FirstLineOffset: SmallInt);
+    ///  <summary>Sets tab stops, in twips, to be used for subsequent
+    ///  paragraphs.</summary>
+    procedure SetTabStops(const TabStops: array of SmallInt);
     ///  <summary>Sets paragraph and character styling for subsequent text
     ///  according to given RTF style.</summary>
     procedure ApplyStyle(const Style: TRTFStyle);
@@ -354,11 +360,30 @@ procedure TRTFBuilder.SetFontStyle(const Style: TFontStyles);
     AddControl(RTFControl(rcUnderline));
 end;
 
+procedure TRTFBuilder.SetIndents(const LeftIndent, FirstLineOffset: SmallInt);
+begin
+  AddControl(RTFControl(rcLeftIndent, LeftIndent));
+  AddControl(RTFControl(rcFirstLineOffset, FirstLineOffset));
+end;
+
 procedure TRTFBuilder.SetParaSpacing(const Spacing: TRTFParaSpacing);
+const
+  TwipsPerPoint = 20; // Note: 20 Twips in a point
+begin
+  AddControl(
+    RTFControl(rcSpaceBefore, FloatToInt(TwipsPerPoint * Spacing.Before))
+  );
+  AddControl(
+    RTFControl(rcSpaceAfter, FloatToInt(TwipsPerPoint * Spacing.After))
+  );
+end;
+
+procedure TRTFBuilder.SetTabStops(const TabStops: array of SmallInt);
+var
+  Tab: SmallInt;
 begin
-  // Note: 20 Twips in a point
-  AddControl(RTFControl(rcSpaceBefore, FloatToInt(20 * Spacing.Before)));
-  AddControl(RTFControl(rcSpaceAfter, FloatToInt(20 * Spacing.After)));
+  for Tab in TabStops do
+    AddControl(RTFControl(rcTabStop, Tab));
 end;
 
 { TRTFFontTable }