uwinhelpdoc.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

                                const Text: String;
                                var SkipWhitespaces: Boolean): String;

 {Returns the given text in RTF while preserving the indentation.
 ~result the formatted text }
 function LineFeeded: String;
 var      List      :TStringList;   //a list to handle the text line by line
          i         :Integer;       //counter through the lines
          S         :String;        //each line
 begin
  List := TStringList.Create;       //create list for by-line access
  try
    Result := '';                   //result empty so far
    List.Text := Text;              //split text in lines

    if TrimLeft(List[0]) = '' then  //first line is empty?
     i := 1                           //skip it
    else
     i := 0;
    for i := i to List.Count - 1 do //for each line
     begin
      S := List[i];                   //get the line
      //a space is inserted in HandleRawText before each new line
      //as long a no manual line break is forced
      if (i <> 0) and (S <> '') and (S[1] = ' ') then
       Delete(S, 1, 1);                 //so remove it again

      Result := Result + S + '\line' + FNewLine;  //add line to result
     end;
  finally
   List.Free;                       //now free the list
  end;
 end;

begin
 case TextFormat of    //depending on the requested format, format the text
   dtfCode:         Result := '{\f1 ' + Text + '}';  //fixed character width
   dtfEmphasize:    Result := '{\i ' + Text + '}';   //italy
   dtfPreFormatted: begin      //fixed character width and preserve whitespaces
                     Result := '\line' + FNewLine + '{\f1 ';
                     //line breaks already inserted?
                     if KeepRawLineBreaks then
                      Result := Result + Text         //just add text
                     else
                      Result := Result + LineFeeded;  //add line feeds
                     Result := Result + '}\line ';
                     SkipWhitespaces := True;
                    end;
   dtfSample:       begin                           //fixed character width and
                     Result := '\par' + FNewLine +  //preserve whitespaces
//                               '{\b Sample:}\line' + NewLine +
                               '{\f1 ';
                     //line breaks already inserted?
                     if KeepRawLineBreaks then
                      Result := Result + Text         //just add text
                     else
                      Result := Result + LineFeeded;  //add line feeds
                     Result := Result + '}\par ';
                     SkipWhitespaces := True;
                    end;
 else
  Result := Text;
 end;
end;






{Gets the (internal) identification (for links) of pages in the user
 documentation.
~param PageIndex the number of the page (-1 for index)
~result the identification (internal URI) of the page }
function TWinHelpDoc.GetPageURI(PageIndex: Integer): String;
begin
 if PageIndex = -1 then                        //URI of the index requested?
  Result := 'Index'                              //name of the main page
 else
  Result := Format('User_%d', [PageIndex]);      //name of the page
end;



{Writes a link to an identifier or file in the documentation.
~param URI       the URI in the documentation to write a link to
~param LinkLabel the label for the link; if empty URI is used
~result a link to the identifier }
function TWinHelpDoc.InternalLink(const URI, LinkLabel: String): String;
var      LinkText    :String;           //the text being the link
begin
 if LinkLabel = '' then                 //no label given?
  LinkText := HandleRawText(URI)          //use encoded URI
 else
  LinkText := LinkLabel;

 //return the link to the URI
 Result := Format((*'{\uldb %s}{\v %s}', //*) '{\uldb %s}{\v %s>%s}',
                  [LinkText, URI, HelpWindowNames[hwMain]]);
end;

{Writes a link to an external URI.
~param URI       the URI to write a link to
~param LinkLabel the label for the link; if empty URI is used
~result a link to the URI }
function TWinHelpDoc.ExternalLink(const URI, LinkLabel: String): String;
var      LinkText    :String;           //the text being the link
begin
 if LinkLabel = '' then                 //no label given?
  LinkText := HandleRawText(URI)          //use encoded URI
 else
  LinkText := LinkLabel;

 //return the link to the URI
 Result := Format('{\cf2{\uldb %s}{\v *!ExecFile("%s","",SW_SHOW,"HTTPLinkError")}}',
                  [LinkText, URI]);
end;




{Includes an image in the documentation.
~param CharFormat      if the image should be included as a simple
                       character instead of centered in an own paragraph
~param JPEGFormat      if the file should be converted to JPEg instead of
                       PNG (only for HTML formats)
~param Resolution      resolution to use, (0,0) means auto-detect;
                       only for JPEG images for PDF-generator if no JPEG
                       support is available
~param BMP             the image to include or nil
~param FileName        the name of the file with the image to include, if BMP
                       is nil
~param Links           list of links inside the image
~param AlternativeText alternative text/description of the image
~result the format to include the image }
function TWinHelpDoc.WriteImage(CharFormat, JPEGFormat: Boolean;
                                Resolution: TPoint;
                                BMP: TBitmap; const FileName: String;
                                Links: TImageLinkList;
                                const AlternativeText: String): String;
         //character to align the image in the command to include it
const    ImageAlignmentCharacter: array[Boolean] of Char =
                                  ('l', 'c');
var      WholeLink              :Boolean;    //only one link on the whole image
         HotSpots               :TStringList; //list of links inside the image
         i                      :Integer;     //counter through links
begin
 if CharFormat then                           //image is like a character?
  Result := ''
 else
  Result := '\line' + FNewLine;                 //end the current line

 WholeLink := (Links.Count = 1) and Links[0].IsAll;
 if not WholeLink and (Links.Count > 0) then  //image has several links?
  begin

   HotSpots := TStringList.Create;       //create list for hot-spots
   try
     for i := 0 to Links.Count - 1 do    //for each link
      with Links[i] do
       if not IsAll then                   //if it is valid
        if ExternLink then                   //add the link as a hot-spot
         HotSpots.Append(#$CC#04#00 + GetSHGRectString(Position) +
                         #00#00#00#00 + 'EF("' + LinkTarget +
{$IFNDEF LINUX}
                                        '","",' + IntToStr(SW_SHOW) +
                                        ',"HTTPLinkError")'
{$ELSE}
                                        '","",5,"HTTPLinkError")'
{$ENDIF}
                         )
        else
         HotSpots.Append(#$E7#04#00 + GetSHGRectString(Position) +
                         GetTopicNameHashValue(LinkTarget) + LinkTarget);

     //create SHG file from the screen shot and with the hot-spots/links
     CreateSegmentedHyperGraphic(BMP, FileName, HotSpots,
                                 FDestPath +
                                 ChangeFileExt(ExtractFileName(FileName),
                                               '.shg'));
   finally
    HotSpots.Free;                       //free list for hot-spots
   end;

   //write that the screen shot with the hot-spots (links) should be included
   Result := Result + '\{bm' + ImageAlignmentCharacter[CharFormat] + ' ' +
                      ChangeFileExt(ExtractFileName(FileName), '.shg') + '\}';
  end
 else
  begin
   if assigned(BMP) then
    //save the image to a file
    BMP.SaveToFile(FDestPath + ExtractFileName(FileName))
   else
    //just copy the bitmap file of the image
    CopyFile(FileName, FDestPath + ExtractFileName(FileName));

   if WholeLink then                  //link on whole image?
    Result := Result + '{\uldb ';       //start the link

   //write that the screen shot should be included
   Result := Result + '\{bm' + ImageAlignmentCharacter[CharFormat] + ' ' +
                      ExtractFileName(FileName) + '\}';

   if WholeLink then                  //link on whole image?
    begin
     //end the text (image) of the link and start the "action"
     Result := Result + '}{\v ';
     if Links[0].ExternLink then        //external link?
      Result := Result + '*!ExecFile("' + Links[0].LinkTarget +
                         '","",SW_SHOW,"HTTPLinkError")'
     else
      Result := Result + Links[0].LinkTarget;
     Result := Result + '}';              //end the link
    end; //if WholeLink
  end; //else not WholeLink and Links.Count > 0

 if not CharFormat then                       //image is not like a character?
  //make sure text follows below and not beside it
  Result := Result + '\par' + FNewLine;
end;




















{Writes a BMP image in the given color.
~param Color       the color to use, it's more like a boolean array for each
                   RGB value what color to use
~param FilePrefix  base name of the file to create (without path and extension)
~param Darker      the value to darken the resulting image by }
procedure TWinHelpDoc.WriteDotBmp(Color: TColor; const FilePrefix: String;
                                  Darker: Byte = 0);

          //the header of the image file (before the palette)
const     BMPFileHeader = 'BM'#$76#$00#$00#$00#$00#$00#$00#$00#$56#$00#$00#$00#$28#$00#$00#$00#$08#$00#$00#$00#$08#$00#$00#$00#$01#$00#$04#$00#$00#$00#$00#$00#$20#$00#$00#$00#$12#$0B#$00#$00#$12#$0B#$00#$00#$08#$00#$00#$00#$08#$00#$00#$00;
          //the palette entry of the white color
          BMPFileWhiteColor = #$FF#$FF#$FF#$00;
          //the palette of the image file
//        BMPFileColors =     #$FF#$FF#$FF#$00#$00#$00#$FF#$00#$3F#$3F#$FF#$00#$7F#$7F#$FF#$00#$00#$00#$E0#$00#$00#$00#$C0#$00#$20#$20#$FF#$00#$00#$00#$D0#$00;

          //the body of the image file (after the palette)
          BMPFileBody = #$00#$05#$50#$00#$02#$47#$55#$20#$01#$11#$47#$50#$11#$22#$64#$75#$11#$32#$21#$45#$01#$33#$21#$40#$02#$11#$11#$20#$00#$01#$10#$00;



          //number of entries in the palette of the image
          PalSize = 8 - 1;


          //an entry in the palette the value of a color component to use, if
          //the color is R/G/B-value is activated or not
type      TPaletteColorEntry = packed array[Boolean] of Char;
          //for each palette entry the value to use, if the color component
          //R/G/B is activated or not
const     PalCols: array[0..PalSize-1] of TPaletteColorEntry =
                   ({(#$FF, #$FF),} (#$00, #$FF), (#$3F, #$FF), (#$7F, #$FF),
                     (#$00, #$E0),  (#$00, #$C0), (#$20, #$FF), (#$00, #$D0));


var       F               :TextFile;           //the file to write
          i               :Integer;            //counter through the palette
          R, G, B         :Boolean;            //if R/G/B-value is activated
          NoYes           :TPaletteColorEntry; //the R/G/B-values to use
begin
 AssignFile(F, FDestPath + FilePrefix + '.bmp');
 Rewrite(F);                                   //open the file
 try
   Write(F, BMPFileHeader);                    //write the header of the image
   Write(F, BMPFileWhiteColor);                //and the first, white color

   R := (Color and $FF) <> 0;                  //get what color component R/G/B
   G := (Color and $FF00) <> 0;                //should be set
   B := (Color and $FF0000) <> 0;
   //for each palette entry
   for i := low(PalCols) to high(PalCols) do
    begin
     NoYes := PalCols[i];                          //get its color values
     if ord(NoYes[True]) < Darker then             //darken it
      NoYes[True] := #$00
     else
      dec(NoYes[True], Darker);
     Write(F, NoYes[B], NoYes[G], NoYes[R], #$00); //write the palette entry
    end;
   Write(F, BMPFileBody);                      //write the body of the image
 finally
  CloseFile(F);                                //close the file
 end;
end;

{Writes a BMP image indicating an abstract method.
~param FilePrefix base name of the file to create (without path and extension) }
procedure TWinHelpDoc.WriteAbstractBmp(const FilePrefix: String);

          //the header of the image file (before the palette)
const     BMPFileHeader = 'BM'#$76#$00#$00#$00#$00#$00#$00#$00#$56#$00#$00#$00#$28#$00#$00#$00#$08#$00#$00#$00#$08#$00#$00#$00#$01#$00#$04#$00#$00#$00#$00#$00#$20#$00#$00#$00#$EB#$0A#$00#$00#$EB#$0A#$00#$00#$08#$00#$00#$00#$08#$00#$00#$00;
          //the palette of the image file
          BMPFileColors = #$FF#$FF#$FF#$00#$00#$00#$FF#$00#$3F#$3F#$FF#$00#$7F#$7F#$FF#$00#$00#$00#$E0#$00#$00#$00#$C0#$00#$20#$20#$FF#$00#$00#$00#$D0#$00;
          //the body of the image file (after the palette)
          BMPFileBody = #$00#$04#$50#$00#$02#$47#$55#$40#$01#$10#$27#$50#$11#$00#$02#$75#$27#$60#$00#$44#$02#$56#$01#$40#$03#$27#$11#$20#$00#$02#$10#$00;
var       F               :TextFile;           //the file to write
begin
 AssignFile(F, FDestPath + FilePrefix + '.bmp');
 Rewrite(F);                                   //open the file
 try
   Write(F, BMPFileHeader);                    //write header of the image
   Write(F, BMPFileColors);                    //write its palette
   Write(F, BMPFileBody);                      //write the body of the image
 finally
  CloseFile(F);                                //close the file
 end;
end;



{Writes a BMP image in the given color indicating a portability issue.
~param Color       the color to use, it's more like a boolean array for each
                   RGB value what color to use
~param FilePrefix  base name of the file to create (without path and extension)
~param Darker      the value to darken the resulting image by }
procedure TWinHelpDoc.WritePortabilityBmp(Color: TColor;
                                          const FilePrefix: String;
                                          Darker: Byte = 0);

          //the header of the image file (before the palette)
const     BMPFileHeader = 'BM'#$76#$00#$00#$00#$00#$00#$00#$00#$56#$00#$00#$00#$28#$00#$00#$00#$08#$00#$00#$00#$08#$00#$00#$00#$01#$00#$04#$00#$00#$00#$00#$00#$20#$00#$00#$00#$EB#$0A#$00#$00#$EB#$0A#$00#$00#$08#$00#$00#$00#$08#$00#$00#$00;
          //the palette entry of the white color
          BMPFileWhiteColor = #$FF#$FF#$FF#$00;
          //the palette of the image file
//        BMPFileColors =     #$FF#$FF#$FF#$00#$FF#$00#$00#$00#$FF#$3F#$3F#$00#$FF#$7F#$7F#$00#$E0#$00#$00#$00#$C0#$00#$00#$00#$FF#$20#$20#$00#$00#$00#$00#$00;