ueditguitopics.pas

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

{Creates the dialog to edit the content of the main index.
~param GUIMainIndexRoot the root of the entries to be edited
~param GUIHelpData      if available the parsed comments on a GUI to allow
                        easier selection of a link target, may be nil
~param UserComments     if available the parses user documentation on the GUI
                        to allow easier selection of a page as a link target,
                        may be nil }
constructor TFormGUITopics.Create(GUIMainIndexRoot: TGUIMainIndexEntry;
                                  GUIHelpData: TICGUIHelpList;
                                  UserComments: TICUserDocComments);
var         Settings      :TMainIndexContentFormSettings; //reads ini settings
begin
 inherited Create(nil);                 //create the dialog

 FGUIMainIndexRoot := GUIMainIndexRoot; //save the parameters

 FGUIHelpData := GUIHelpData;
 FUserComments := UserComments;




 //create the (fixed) TreeView
 TreeView :=
{$IFDEF VER120}
             TFixedTreeView
{$ELSE}
             TTreeView
{$ENDIF}
                           .Create(Self);
 TreeView.Parent := Self;
 TreeView.Name := 'TreeView';
 TreeView.Left := 10;
 TreeView.Top := 44;
 TreeView.Width := 247;
 TreeView.Height := 394;
 TreeView.Anchors := [akLeft, akTop, akRight, akBottom];
 TreeView.Hint := 'The content of the main index of the documentation.';
 TreeView.HelpContext := HelpContext + 2; //+ 1 is ComboBoxNodeCaptions
 TreeView.Indent := 20;
 TreeView.Images := ImageList;
 TreeView.RowSelect := True;
 TreeView.ReadOnly := True;
{$IFNDEF LINUX}
 TreeView.HideSelection := False;
{$ENDIF}
 TreeView.TabOrder := 0;
 TreeView.DragMode := dmAutomatic;
 TreeView.OnChange := TreeViewChange;
 TreeView.OnDragDrop := TreeViewDragDrop;
 TreeView.OnDragOver := TreeViewDragOver;



 //by default show link and text of the nodes
 ComboBoxNodeCaptions.ItemIndex := 2;

{$IFNDEF LINUX}
 //register the overlay-images for checked valid and invalid links
 ImageList.Overlay(Ord(iOverlayOK), Ord(iOverlayOK));
 ImageList.Overlay(Ord(iOverlayError), Ord(iOverlayError));
{$ENDIF}


 //get object to load the settings from
 Settings := TMainIndexContentFormSettings(TMainIndexContentFormSettings.
                                                       GetSettings(ClassName));
 if not Assigned(Settings) then        //no object initialized?
  begin                                  //create a new object
   Settings := TMainIndexContentFormSettings.Create(ClassName);
   Settings.ReadValues(Self);            //initialize with the default values
   Settings.Initialize;                  //and read from the ini file
  end;
 Settings.SetValuesToForm(Self);       //initialize form with read values
 ComboBoxNodeCaptions.ItemIndex := Settings.NodeCaptionStyle;

 FillTree;                             //show alternative content of main index
 TreeView.Selected := TreeView.Items.GetFirstNode; //select the first node
end;

{Frees the dialog after saving its current state. }
destructor TFormGUITopics.Destroy;
var        Settings      :TMainIndexContentFormSettings; //to save ini settings
begin
 SaveData;                             //save data of current node

 //get object to save the settings in
 Settings := TMainIndexContentFormSettings(TMainIndexContentFormSettings.
                                                       GetSettings(ClassName));
 if Assigned(Settings) then
  Settings.ReadValues(Self);             //save current settings

 inherited Destroy;                    //free the form
end;



{Clears the tree and shows the internal nodes again. }
procedure TFormGUITopics.ReloadTree;
begin
 TreeView.Items.Clear;                 //clear the tree
 FillTree;                             //fill tree with the alternative content
end;

{Shows the internal nodes in the tree. }
procedure TFormGUITopics.FillTree;

 {Fills the tree with the entry and its child entries.
 ~param Parent the node to add the entry as child to
 ~param Entry  the entry to add to the tree }
 procedure FillEntries(Parent: TTreeNode; Entry: TGUIMainIndexEntry);
 var       i          :Integer;             //counter through child entries
 begin                                      //add the entry
  Parent := TreeView.Items.AddChildObject(Parent, Entry.Text, Entry);
  SetNodeText(Parent);                      //show its text of selected kind
  SetNodeImage(Parent);                     //set its image
  for i := 0 to Entry.SubTopicCount - 1 do  //add all it child entries
   FillEntries(Parent, Entry.SubTopics[i]);
 end;

var       i             :Integer;           //counter through top-level entries
          Node          :TTreeNode;         //runner through top-level nodes
begin
 for i := 0 to FGUIMainIndexRoot.SubTopicCount - 1 do //add all entries
  FillEntries(nil, FGUIMainIndexRoot.SubTopics[i]);
 Node := TreeView.Items.GetFirstNode;
 while Assigned(Node) do                    //for each part of the tree
  begin
   SetOverlay(Node);                          //calculate validity of its links
   Node := Node.GetNextSibling;
  end;

 TreeView.FullExpand;                       //show all nodes
end;




{Shows the values of the entry represented by the node so they can be edited.
~param Node the node whose entry should be edited }
procedure TFormGUITopics.StartEditing(Node: TTreeNode);
          //the entry whose values should be shown
var       Entry         :TGUIMainIndexEntry;
          Link          :String;      //the link of the entry
          Index         :Integer;     //index of separator in link
begin
 SetEditing(False);                   //stop editing previous entry

 UpdateButtonState;                   //and deactivate buttons

 Entry := Node.Data;                  //get entry of the node
 EditText.Text := Entry.Text;         //show its text
 RadioGroupLinkType.ItemIndex := Ord(Entry.LinkKind); //and its kind

 Link := Entry.LinkTarget;            //get its link
 if Entry.LinkKind = gmilkGUI then    //is link into a GUI?
  begin
   Index := pos('#', Link);             //search separator
   if Index = 0 then                    //link to GUI itself?
    Index := Length(Link) + 1;            //use whole link for base name of GUI
  end
 else
  Index := Length(Link) + 1;            //use whole link

 ComboBoxLinkTarget.Text := Copy(Link, 1, Index - 1);  //show link
 //show name of comment in documentation of GUI to link to
 ComboBoxComment.Text := Copy(Link, Index + 1, High(Length(Link)));

 if Entry.LinkKind = gmilkGUI then    //link inside GUI?
  ComboBoxLinkTargetChange(ComboBoxLinkTarget); //load names of comments of GUI

 FEditNode := Node;                   //set node whose entry is being edited
 SetEditing(True);                    //allow editing
end;

{Saves the data from the GUI to the currently edited entry. }
procedure TFormGUITopics.SaveData;
var       Entry         :TGUIMainIndexEntry; //the entry to save the values to
          Link          :String;             //the link of the entry
begin
 if assigned(FEditNode) then                 //entry currently being edited?
  begin
   Entry := FEditNode.Data;                    //get the entry

   Entry.Text := EditText.Text;                //save its text and kind of link
   Entry.LinkKind := TGUIMainIndexLinkKind(RadioGroupLinkType.ItemIndex);

   case Entry.LinkKind of                      //and the link itself
     gmilkNone:    Link := '';
     gmilkGUI:     begin
                    Link := ComboBoxComment.Text;
                    if Link <> '' then
                     Link := '#' + Link;
                    Link := ComboBoxLinkTarget.Text + Link;
                   end;
     gmilkUserDoc: Link := ComboBoxLinkTarget.Text;
     gmilkExtern:  Link := ComboBoxLinkTarget.Text;
   else
    assert(False);
   end;
   Entry.LinkTarget := Link;

   UpdateNode(FEditNode);                      //show new values in the tree
  end;
end;



{Sets whether a node is currently being edited.
~param Editing whether a node is currently being edited }
procedure TFormGUITopics.SetEditing(Editing: Boolean);
var       i             :Integer;          //counter through edit-controls
begin
 if not Editing then                       //if no entry is being edited
  FEditNode := nil;                          //clear the current node

 for i := 0 to GroupBoxEntry.ControlCount - 1 do //en-/disable edit-controls
  GroupBoxEntry.Controls[i].Enabled := Editing;
end;


{Updates the states of the buttons depending on whether a node is selected. }
procedure TFormGUITopics.UpdateButtonState;
var       Node          :TTreeNode;        //the currently selected node
begin
 Node := TreeView.Selected;

 //set states of buttons
 ButtonUp.Enabled := assigned(Node) and assigned(Node.GetPrevSibling());
 ButtonDown.Enabled := assigned(Node) and assigned(Node.GetNextSibling());
 ButtonRight.Enabled := assigned(Node) and assigned(Node.GetPrevSibling());
 ButtonLeft.Enabled := assigned(Node) and assigned(Node.Parent);

 ButtonRemove.Enabled := assigned(Node);
end;

{Sets the caption of the node.
~param Node the node whose caption should be set }
procedure TFormGUITopics.SetNodeText(Node: TTreeNode);
var       Entry         :TGUIMainIndexEntry; //the entry of the node
begin
 Entry := Node.Data;                         //get the entry

 case ComboBoxNodeCaptions.ItemIndex of     //depending on what should be shown
   0: Node.Text := Entry.Text;                //show just the text
   1: Node.Text := Entry.LinkTarget;          //or just the link
   2: Node.Text := Entry.LinkTarget + ' ' + Entry.Text;  //or both
 end;
end;



{Sets the image/icon of the node.
~param Node the node whose icon/image should be set }
procedure TFormGUITopics.SetNodeImage(Node: TTreeNode);

 {Checks whether the target of the link into the help on the GUI is known.
 ~param Link the link to be checked
 ~result whether the target of the link is known }
 function GUIKnown(const Link: String): Boolean;
 var      Separator     :Integer;           //index of separator in the link
          Part          :String;            //each part of the link
          i             :Integer;           //counter through GUIs and comments
          List          :TICGUICommentList; //the list of comments in the GUI
 begin
  Separator := Pos('#', Link);              //search separator in the link
  Part := Link;                             //assume its the base name
  if Separator <> 0 then                    //if a comment is appended
   Delete(Part, Separator, High(Length(Part)));  //remove it

  i := FGUIHelpData.Count - 1;              //search the GUI by its base name
  while (i >= 0) and (CompareText(Part, FGUIHelpData[i].BaseName) <> 0) do
   dec(i);

  Result := i >= 0;                         //GUI with the base name found?
  if Result and (Separator <> 0) then       //and is link to a comment for it?
   begin
    Part := Link;
    Delete(Part, 1, Separator);               //get the comment part
    //is not the default comment for the GUI?
    if CompareText(Part, GUIHelpTopicSpecialPrefix + 'default') <> 0 then
     begin
      List := FGUIHelpData[i].Comments;         //get list of comments in GUI
      i := List.Count - 1;                      //and search the link target
      while (i >= 0) and (CompareText(Part, List[i].Name) <> 0) do
       dec(i);
      Result := i >= 0;                         //return whether it was found
     end;
   end;
 end;

 {Checks whether the page of user documentation to link to exists.
 ~param Link the link to be checked
 ~result whether a page with the name exists }
 function UserDocPageKnown(const Link: String): Boolean;
 var      i               :Integer;      //counter through all pages
 begin
  i := FUserComments.PageCount - 1;      //search a page with the name
  while (i >= 0) and
        (CompareText(Link, FUserComments.Comment[i].TopicName) <> 0) do
   dec(i);

  Result := i >= 0;                      //return whether a page has been found
 end;

var       Entry         :TGUIMainIndexEntry;  //the entry of the node