Merge branch 'feature/140-save-snippet-info-to-disk' into develop

Fixes #140

Author: delphidabbler

Docs/Design/FileFormats/saved.html

@@ -5,7 +5,7 @@
  * v. 2.0. If a copy of the MPL was not distributed with this file, You can
  * obtain one at https://mozilla.org/MPL/2.0/
  *
- * Copyright (C) 2012-2021, Peter Johnson (gravatar.com/delphidabbler).
+ * Copyright (C) 2012-2025, Peter Johnson (gravatar.com/delphidabbler).
  *
  * CodeSnip File Format Documentation: Saved Files
 -->
@@ -46,20 +46,27 @@ <h2>
 </h2>
 
 <p>
-  CodeSnip saves external files in two different ways:
+  CodeSnip saves external files in three different ways:
 </p>
 
 <ol>
   <li>
-    By saving snippets to file from the <em>File | Save Snippet</em> menu.
+    By saving snippet information to file from the <em>File | Save Snippet Information</em> menu option.
   </li>
   <li>
-    By saving units to file from the <em>File | Save Unit</em> menu.
+    By saving snippets to file from the <em>File | Save Snippet</em> menu option.
+  </li>
+  <li>
+    By saving units to file from the <em>File | Save Unit</em> menu option.
   </li>
 </ol>
 
 <p>
-  In each case the following file types can be chosen by the user:
+  In the first case the snippet is always saved in rich text format.
+</p>
+
+<p>
+  In the second two cases the following file types can be chosen by the user:
 </p>
 
 <ul>
@@ -87,7 +94,11 @@ <h2>
 </h2>
 
 <p>
-  The encodings used depend on the file type and user choice. Different file
+  In the first case the RTF is always saved in ASCII format.
+</p>
+
+<p>
+  In the 2nd and 3rd cases the encodings used depend on the file type and user choice. Different file
   types have different encoding choices, as follows:
 </p>
 
@@ -140,7 +151,7 @@ <h2>
   <dd>
     <ul class="squashed">
       <li>
-        ANSI (system default code page)
+        ANSI (system default code page). ASCII format is actually used.
       </li>
     </ul>
   </dd>

Src/CodeSnip.dpr

@@ -374,7 +374,8 @@ uses
   Compilers.USettings in 'Compilers.USettings.pas',
   FmRegisterCompilersDlg in 'FmRegisterCompilersDlg.pas' {RegisterCompilersDlg},
   ClassHelpers.UGraphics in 'ClassHelpers.UGraphics.pas',
-  ClassHelpers.UActions in 'ClassHelpers.UActions.pas';
+  ClassHelpers.UActions in 'ClassHelpers.UActions.pas',
+  USaveInfoMgr in 'USaveInfoMgr.pas';
 
 // Include resources
 {$Resource ExternalObj.tlb}       // Type library file

Src/CodeSnip.dproj

@@ -581,6 +581,7 @@
 			</DCCReference>
 			<DCCReference Include="ClassHelpers.UGraphics.pas"/>
 			<DCCReference Include="ClassHelpers.UActions.pas"/>
+			<DCCReference Include="USaveInfoMgr.pas"/>
 			<None Include="CodeSnip.todo"/>
 			<BuildConfiguration Include="Base">
 				<Key>Base</Key>

Src/FmMain.dfm

@@ -877,6 +877,16 @@ inherited MainForm: TMainForm
       OnExecute = actDeleteUserDatabaseExecute
       OnUpdate = ActNonEmptyUserDBUpdate
     end
+    object actSaveInfo: TAction
+      Category = 'File'
+      Caption = 'Save Snippet Information...'
+      Hint = 
+        'Save snippet information|Save information about the selected sni' +
+        'ppet to file'
+      ShortCut = 24649
+      OnExecute = actSaveInfoExecute
+      OnUpdate = actSaveInfoUpdate
+    end
   end
   object mnuMain: TMainMenu
     Images = ilMain
@@ -887,6 +897,9 @@ inherited MainForm: TMainForm
       object miSaveSnippet: TMenuItem
         Action = actSaveSnippet
       end
+      object miSaveInfo: TMenuItem
+        Action = actSaveInfo
+      end
       object miSaveUnit: TMenuItem
         Action = actSaveUnit
       end

Src/FmMain.pas

@@ -241,6 +241,8 @@   TMainForm = class(THelpAwareForm)
     tbSpacer7: TToolButton;
     tbSpacer8: TToolButton;
     tbTestCompile: TToolButton;
+    miSaveInfo: TMenuItem;
+    actSaveInfo: TAction;
     ///  <summary>Displays About Box.</summary>
     procedure actAboutExecute(Sender: TObject);
     ///  <summary>Gets a new category from user and adds to database.</summary>
@@ -501,6 +503,8 @@   TMainForm = class(THelpAwareForm)
     procedure splitVertCanResize(Sender: TObject; var NewSize: Integer;
       var Accept: Boolean);
     procedure ActNonEmptyUserDBUpdate(Sender: TObject);
+    procedure actSaveInfoUpdate(Sender: TObject);
+    procedure actSaveInfoExecute(Sender: TObject);
   strict private
     var
       ///  <summary>Object that notifies user-initiated events by triggering
@@ -596,9 +600,9 @@ implementation
   UCodeShareMgr, UCommandBars, UConsts, UCopyInfoMgr,
   UCopySourceMgr, UDatabaseLoader, UDatabaseLoaderUI, UDetailTabAction,
   UEditSnippetAction, UExceptions, UHelpMgr, UHistoryMenus, UKeysHelper,
-  UMessageBox, UNotifier, UNulDropTarget, UPrintMgr, UQuery, USaveSnippetMgr,
-  USaveUnitMgr, USelectionIOMgr, UUrl, UUserDBMgr, UView, UViewItemAction,
-  UWBExternal;
+  UMessageBox, UNotifier, UNulDropTarget, UPrintMgr, UQuery, USaveInfoMgr,
+  USaveSnippetMgr, USaveUnitMgr, USelectionIOMgr, UUrl, UUserDBMgr, UView,
+  UViewItemAction, UWBExternal;
 
 
 {$R *.dfm}
@@ -1025,6 +1029,17 @@ procedure TMainForm.actSaveDatabaseUpdate(Sender: TObject);
   (Sender as TAction).Enabled := TUserDBMgr.CanSave;
 end;
 
+procedure TMainForm.actSaveInfoExecute(Sender: TObject);
+begin
+  TSaveInfoMgr.Execute(fMainDisplayMgr.CurrentView);
+end;
+
+procedure TMainForm.actSaveInfoUpdate(Sender: TObject);
+begin
+  (Sender as TAction).Enabled :=
+    TSaveInfoMgr.CanHandleView(fMainDisplayMgr.CurrentView);
+end;
+
 procedure TMainForm.actSaveSelectionExecute(Sender: TObject);
 begin
   TSelectionIOMgr.SaveCurrentSelection;

Src/Help/CodeSnip.hhp

@@ -57,6 +57,7 @@ HTML\dlg_registercompilers.htm
 HTML\dlg_renamecategory.htm
 HTML\dlg_restore.htm
 HTML\dlg_savehiliter.htm
+HTML\dlg_saveinfo.htm
 HTML\dlg_saveselection.htm
 HTML\dlg_savesnippet.htm
 HTML\dlg_selectcompiler.htm

Src/Help/HTML/dlg_saveinfo.htm

@@ -0,0 +1,48 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<!--
+ * This Source Code Form is subject to the terms of the Mozilla Public License,
+ * v. 2.0. If a copy of the MPL was not distributed with this file, You can
+ * obtain one at https://mozilla.org/MPL/2.0/
+ *
+ * Copyright (C) 2025, Peter Johnson (gravatar.com/delphidabbler).
+ *
+ * Help topic for Save Snippet Information dialogue box.
+-->
+<html>
+
+<head>
+    <meta name="generator" content="HTML Tidy, see www.w3.org">
+    <meta http-equiv="Content-Type" content="text-html; charset=Windows-1252">
+    <title>
+        Save Snippet Information Dialogue Box
+    </title>
+    <link rel="stylesheet" href="../css/codesnip.css" type="text/css">
+</head>
+
+<body>
+    <object type="application/x-oleobject" classid="clsid:1e2a7bd0-dab9-11d0-b93a-00c04fc99f9e">
+        <param name="ALink Name" value="SnippetInfoFileDlg">
+    </object>
+    <h1>
+        <a name="dlg_saveinfo"></a>Save Snippet Information Dialogue Box
+    </h1>
+    <p>
+        This dialogue box is displayed when the <em>File | Save Snippet
+        Information</em> menu option is clicked. It is used to specify the
+        name of the file into which information about the currently selected
+        snippet is to be saved.
+    </p>
+    <p>
+        The saved snippet information is written in rich text format.
+    </p>
+    <p>
+        This dialogue is a standard Windows save dialogue box. You specify the
+         name and folder for the file in the usual way.
+    </p>
+    <p>
+        Use the <em>Save</em> button to write the file to disk or press
+        <em>Cancel</em> to abort.
+    </p>
+</body>
+
+</html>

Src/Help/HTML/menu_file.htm

@@ -44,6 +44,22 @@ <h1>
           not routines are ignored.
         </td>
       </tr>
+      <tr>
+        <td class="img">
+          &nbsp;
+        </td>
+        <td class="item">
+          Save Snippet Information<br>
+          [<span class="smallcaps">Shift+Ctrl+I</span>]
+        </td>
+        <td class="desc">
+          Saves information about the currently selected snippet to file, in
+          rich text format. The information saved is that displayed in the
+          <a href="detail_pane.htm">Detail Pane</a>.
+          The <a href="dlg_saveinfo.htm">Save Snippet Information</a> dialogue
+          box is displayed where the required file name is entered.
+        </td>
+      </tr>
       <tr>
         <td class="img">
           <img

Src/Help/Index.hhk

@@ -316,6 +316,10 @@
     <param name="Name" value="rename category dialogue">
     <param name="Local" value="HTML\dlg_renamecategory.htm">
     </OBJECT>
+  <LI> <OBJECT type="text/sitemap">
+    <param name="Name" value="save snippet information dialogue">
+    <param name="Local" value="HTML\dlg_saveinfo.htm">
+    </OBJECT>
   <LI> <OBJECT type="text/sitemap">
     <param name="Name" value="save annotated source dialogue">
     <param name="Local" value="HTML\dlg_savesnippet.htm">

Src/USaveInfoMgr.pas

@@ -0,0 +1,132 @@
+{
+ * This Source Code Form is subject to the terms of the Mozilla Public License,
+ * v. 2.0. If a copy of the MPL was not distributed with this file, You can
+ * obtain one at https://mozilla.org/MPL/2.0/
+ *
+ * Copyright (C) 2025, Peter Johnson (gravatar.com/delphidabbler).
+ *
+ * Saves information about a snippet to disk in rich text format. Only routine
+ * snippet kinds are supported.
+}
+
+
+unit USaveInfoMgr;
+
+interface
+
+uses
+  // Project
+  UEncodings,
+  UView;
+
+
+type
+  ///  <summary>Method-only record that saves information about a snippet to
+  ///  file in rich text format. The snippet is obtained from a view. Only
+  ///  snippet views are supported.</summary>
+  TSaveInfoMgr = record
+  strict private
+    ///  <summary>Attempts to name of the file to be written from the user.
+    ///  </summary>
+    ///  <param name="AFileName"><c>string</c> [out] Set to the name of the file
+    ///  entered by the user. Undefined if the user cancelled.</param>
+    ///  <returns><c>Boolean</c>. <c>True</c> if the user entered and accepted a
+    ///  file name of <c>False</c> if the user cancelled.</returns>
+    class function TryGetFileNameFromUser(out AFileName: string): Boolean;
+      static;
+    ///  <summary>Returns encoded data containing a RTF representation of
+    ///  information about the snippet represented by the given view.</summary>
+    class function GenerateRichText(View: IView): TEncodedData; static;
+  public
+    ///  <summary>Saves information about the snippet referenced by the a given
+    ///  view to file.</summary>
+    ///  <remarks>The view must be a snippet view.</remarks>
+    class procedure Execute(View: IView); static;
+    ///  <summary>Checks if a given view can be saved to the clipboard. Returns
+    ///  True only if the view represents a snippet.</summary>
+    class function CanHandleView(View: IView): Boolean; static;
+
+  end;
+
+implementation
+
+uses
+  // Delphi
+  SysUtils,
+  Dialogs,
+  // Project
+  Hiliter.UAttrs,
+  Hiliter.UGlobals,
+  UIOUtils,
+  UOpenDialogHelper,
+  URTFSnippetDoc,
+  URTFUtils,
+  USaveDialogEx;
+
+{ TSaveInfoMgr }
+
+class function TSaveInfoMgr.CanHandleView(View: IView): Boolean;
+begin
+  Result := Supports(View, ISnippetView);
+end;
+
+class procedure TSaveInfoMgr.Execute(View: IView);
+var
+  FileName: string;
+  RTF: TRTF;
+begin
+  Assert(Assigned(View), 'TSaveInfoMgr.Execute: View is nil');
+  Assert(CanHandleView(View), 'TSaveInfoMgr.Execute: View not supported');
+  if not TryGetFileNameFromUser(FileName) then
+    Exit;
+  RTF := TRTF.Create(GenerateRichText(View));
+  TFileIO.WriteAllBytes(FileName, RTF.ToBytes);
+end;
+
+class function TSaveInfoMgr.GenerateRichText(View: IView): TEncodedData;
+var
+  Doc: TRTFSnippetDoc;        // object that generates RTF document
+  HiliteAttrs: IHiliteAttrs;  // syntax highlighter formatting attributes
+begin
+  Assert(Supports(View, ISnippetView),
+    'TSaveInfoMgr.GenerateRichText: View is not a snippet view');
+  if (View as ISnippetView).Snippet.HiliteSource then
+    HiliteAttrs := THiliteAttrsFactory.CreateUserAttrs
+  else
+    HiliteAttrs := THiliteAttrsFactory.CreateNulAttrs;
+  Doc := TRTFSnippetDoc.Create(HiliteAttrs);
+  try
+    // TRTFSnippetDoc generates stream of ASCII bytes
+    Result := Doc.Generate((View as ISnippetView).Snippet);
+    Assert(Result.EncodingType = etASCII,
+      'TSaveInfoMgr.GenerateRichText: ASCII encoded data expected');
+  finally
+    Doc.Free;
+  end;
+end;
+
+class function TSaveInfoMgr.TryGetFileNameFromUser(
+  out AFileName: string): Boolean;
+var
+  Dlg: TSaveDialogEx;
+resourcestring
+  sCaption = 'Save Snippet Information';     // dialogue box caption
+  sFilter = 'Rich Text File (*.rtf)|*.rtf|'  // file filter
+    + 'All files (*.*)|*.*';
+begin
+  Dlg := TSaveDialogEx.Create(nil);
+  try
+    Dlg.Title := sCaption;
+    Dlg.Options := [ofShowHelp, ofNoTestFileCreate, ofEnableSizing];
+    Dlg.Filter := sFilter;
+    Dlg.FilterIndex := 1;
+    Dlg.HelpKeyword := 'SnippetInfoFileDlg';
+    Result := Dlg.Execute;
+    if Result then
+      AFileName := FileOpenFileNameWithExt(Dlg)
+  finally
+    Dlg.Free;
+  end;
+end;
+
+end.