📄 uguihelpreader.pas
字号:
{Generate the linked image of the current file of documentation on a GUI.
~param Data the data to generate the image of
~result format to include the image }
function TJADDGUIHelpReader.GenerateGUIHelpImage(
Data: TOldGUIHelpData): String;
var i :Integer; //general counter
Target :TOldGUIHelpData; //target file of a link
Index :Integer; //index of documentation
S, S2 :String; //general strings
AltText :String; //the text to use as alternative text
ExternLink :Boolean; //whether it links outside documentation
URI :String; //URI of the links
//all components with documentation and a help context of 0 (none)
ContextZero :String;
ContextIndex :Integer; //index of help context of documentation
//resolution/size of the screen shot (none, i.e. auto-detect)
Resolution :TPoint;
begin
assert(FCurrentGUIHelpTopic = '');
Generator.FreeImageLinks; //clear list of links
//set the help context of the whole window
if Generator.HelpContextList.IndexOfObject(TObject(Data.WindowHelpContext)) =
-1 then
Generator.HelpContextList.AddObject(Generator.GetGUIHelpURI('#'),
TObject(Data.WindowHelpContext))
else
AddGeneratorMessage(TFormatCommentDoc(Generator).FormatCommentDocMessagesID,
Ord(fcdmkHelpContextMismatch),
'Help context ' + IntToStr(Data.WindowHelpContext) +
' of the form ' + Data.BaseName +
' was already defined for another topic!');
//for each manually defined link region
for i := 0 to Data.ManualLinks.Count - 1 do
begin
S2 := Data.ManualLinks[i]; //use given link as an extern link
if FGUIHelpUseTopicAsLinkText then //use topics of pages as link texts?
begin
Target := Generator.GetGUIHelpPosition(S2, Index); //search position
ExternLink := not assigned(Target);
if assigned(Target) then //link target found?
begin
if Index <> -1 then //not the file itself?
if Index = -2 then //default target? get topic
AltText := Target.DefaultCommentTopic
else
AltText := Target.CommentCommentTopics[Index]
else
AltText := Target.TitleOrBaseName; //get name of the file
AltText := Generator.HandleRawText(AltText);
S2 := Generator.GetGUIHelpURIByIndex(FGUIHelpData.IndexOf(Target),
Index);
end //if assigned(Target)
else
begin
AddMessage(jghrmkInvalidManualExternalLink,
'Invalid or external manual link in ' + Data.BaseName +
' to: ' + S2);
AltText := Generator.Localize(dtGUIHelpManualLinkHint);
end; //else assigned(Target)
end //if FGUIHelpUseTopicAsLinkText
else
begin
S := Generator.GetGUIHelpURI(S2); //get the URI to link to
ExternLink := S = '';
if ExternLink then //link not in the GUI documentation?
AddMessage(jghrmkInvalidManualExternalLink,
'Invalid or external manual link in ' + Data.BaseName +
' to: ' + S2)
else
S2 := S; //use the found link
AltText := Generator.Localize(dtGUIHelpManualLinkHint);
end; //else FGUIHelpUseTopicAsLinkText
Generator.AddImageLink(S2, ExternLink, False,
PRect(Data.ManualLinks.Objects[i])^, AltText);
end; //for i := 0 to Data.ManualLinks.Count - 1
ContextZero := ''; //no documented components with help context = 0 so far
for i := 0 to Data.LoggedComponents.Count - 1 do //for each logged component
begin
//get the name of its documentation topic
S := GUIHelpUnalias(Data.LoggedComponents[i].Name, Data);
Index := Data.CommentNames.IndexOf(S);
if Index <> -1 then //is documented?
begin
Data.CommentNames.Objects[Index] := TObject(True); //documentation used
S := Data.CommentNames[Index]; //use the name
AltText := Data.CommentCommentTopics[Index]; //and its topic
URI := Generator.GetGUIHelpURI('#' + S); //get absolute name
//has a valid help context?
if (Data.LoggedComponents[i].HelpContext <> 0) and
(Data.LoggedComponents[i].HelpContext <> -1) then
begin
ContextIndex := Generator.HelpContextList.IndexOf(URI);
if ContextIndex = -1 then //help context not defined yet?
begin
ContextIndex := Data.LoggedComponents.FindComponent(S2);
if (ContextIndex = -1) or //no real component existing?
//or is the real component, no alias?
(CompareText(Data.LoggedComponents[i].Name, S) = 0) then
if Generator.HelpContextList.IndexOfObject(TObject(Data.
LoggedComponents[i].HelpContext)) = -1 then
//set the help context of the documentation
Generator.HelpContextList.AddObject(URI, TObject(Data.
LoggedComponents[i].HelpContext))
else
AddGeneratorMessage(TFormatCommentDoc(Generator).
FormatCommentDocMessagesID,
Ord(fcdmkHelpContextMismatch),
'Help context ' +
IntToStr(Data.LoggedComponents[i].HelpContext) +
' of component ' +
Data.LoggedComponents[i].Name +
' was already defined for another topic!')
else
begin
if (ContextIndex <> -1) and //wrong help context?
(Data.LoggedComponents[i].HelpContext <>
Data.LoggedComponents[ContextIndex].HelpContext) then
AddGeneratorMessage(TFormatCommentDoc(Generator).
FormatCommentDocMessagesID,
Ord(fcdmkHelpContextMismatch),
'Component ' + Data.LoggedComponents[i].Name +
' in ' + Data.BaseName + ' has help context ' +
IntToStr(Data.LoggedComponents[i].
HelpContext) +
', but the help context for documentation ' +
Data.CommentNames[Index] + ' is ' +
IntToStr(Data.LoggedComponents[ContextIndex].
HelpContext));
end;
end //if ContextIndex = -1
else
//wrong help context?
if THelpContext(Generator.HelpContextList.Objects[ContextIndex]) <>
Data.LoggedComponents[i].HelpContext then
AddGeneratorMessage(TFormatCommentDoc(Generator).
FormatCommentDocMessagesID,
Ord(fcdmkHelpContextMismatch),
'Component ' + Data.LoggedComponents[i].Name +
' in ' + Data.BaseName + ' has help context ' +
IntToStr(Data.LoggedComponents[i].HelpContext) +
', but the help context for documentation ' +
Data.CommentNames[Index] + ' is ' +
IntToStr(Integer(Generator.HelpContextList.
Objects[ContextIndex])));
end //if has a valid help context?
else
//class of component has help contexts?
if Data.LoggedComponents[i].HelpContext <> -1 then
//log missing help context
ContextZero := ContextZero + ', ' + Data.LoggedComponents[i].Name;
end
else
begin
if CompareText(S, '.default') <> 0 then
AddMessage(jghrmkNotDocumented,
'No documentation for ' + Data.BaseName + '.' + S);
URI := Generator.GetGUIHelpURI('#.default'); //use default topic
AltText := Data.DefaultCommentTopic; //and its topic
end;
//don't use topics of pages as link texts?
if not FGUIHelpUseTopicAsLinkText then
AltText := Data.LoggedComponents[i].Name; //use its name
//add the link in the image
Generator.AddImageLink(URI, False, False, Data.LoggedComponents[i].Position,
Generator.HandleRawText(AltText));
end; //for i := 0 to Data.LoggedComponents.Count - 1
if ContextZero <> '' then //some components without valid help context?
AddMessage(jghrmkNoHelpContext,
'Documented components without a help context (i.e. 0) in ' +
Data.BaseName + ': ' +
Copy(ContextZero, 3, High(Length(ContextZero))));
//no known resolution/size fo the screen shot, so use auto-detection
Resolution := Point(0, 0);
//write the image with all links
Result := Generator.WriteImage(False, False, Resolution, nil,
ChangeFileExt(Data.LogFilePath, '.bmp'),
Generator.ImageLinks,
Generator.Localize(dtGUIHelpScreenShotHint));
end;
{Checks if all documentation topic in the help for a GUI are used. }
procedure TJADDGUIHelpReader.CheckGUIDocumentationTopicUsage;
var i :Integer; //counter through the files
Data :TOldGUIHelpData; //each data
Unused :String; //list of unused topics
j :Integer; //counter through the topics
begin
FCurrentGUIHelpTopic := ''; //position are the whole files
//check if there are documentation topics that are not linked to
for i := 0 to FGUIHelpData.Count - 1 do //for each file
begin
FCurrentGUIHelpFileIndex := i; //set current file
Data := FGUIHelpData[i]; //get its data
Unused := ''; //no unused topics so far
for j := 0 to Data.CommentNames.Count - 1 do //for each of its topics
//if no other topic or similar links to it
if not assigned(Data.CommentNames.Objects[j]) then
Unused := Unused + ', ' + Data.CommentNames[j]; //add it to the list
if Unused <> '' then //some not-linked found?
begin
Delete(Unused, 1, 2); //remove first separator
AddMessage(jghrmkUnusedTopics,
'Unused topics in ' + //log documentation topics
ChangeFileExt(ExtractFileName(Data.LogFilePath), '') +
': ' + Unused);
end;
end;
FCurrentGUIHelpFileIndex := -1; //no data anymore
end;
//descriptions of the messages of the class ~[link TJADDGUIHelpReader]
const JADDGUIHelpReaderMessages: array[TJADDGUIHelpReaderMessageKind] of
TMessageDescription =
(
(Text:
'A log file of a GUI is not correct, at least some lines are invalid.';
HelpText:
'Check the log file, re-create it if neccessary.';
Seriousness: msError;
),
(Text:
'A file with help on a GUI can''t be read.';
HelpText:
'Check the file exists and the name and path of the specified file.';
Seriousness: msError;
),
(Text:
'A file with help on a GUI was read more than once, i.e. recursive inclusion of a file.';
HelpText:
'Check the ~guiInclude sections to not include files recursively.';
Seriousness: msWarning;
),
(Text:
'A manual link on the image on the GUI has been specified with an invalid target, it is assume it is an external link.';
HelpText:
'Check the ~guiManual sections if correct link have been specified.';
Seriousness: msWarning;
),
(Text:
'A component on the GUI has not been documented (and not been aliased to another component).';
HelpText:
'Create a ~gui section to comment the component or check an existing section for spelling, or alias it with ~guiAlias to another documented component.';
Seriousness: msWarning;
),
(Text:
'At least one component on the GUI does not have a help context defined.';
HelpText:
'Assign a help context to the component in the Delphi IDE (or in the source code).';
Seriousness: msHint;
),
(Text:
'An alias for GUI components is not correct.';
HelpText:
'Check the ~guiAlias section.';
Seriousness: msError;
),
(Text:
'A manual link inside the image of a GUI is not correct.';
HelpText:
'Check the ~guiManual section.';
Seriousness: msError;
),
(Text:
'Already defined documentation was replaced.';
HelpText:
'Check the names of the GUI topics so no topic is documented twice.';
Seriousness: msWarning;
),
(Text:
'An unknown special topic was documented.';
HelpText:
'Check the spelling of the topic, topics beginning with a dot "." are reserved as special topics.';
Seriousness: msError;
),
(Text:
'An invalid name of a topic or of a component has been specified.';
HelpText:
'Check the spelling of the topic and make sure a component with the same name exists.';
Seriousness: msError;
),
(Text:
'An included file via ~guiInclude contains text outside sections.';
HelpText:
'This text has no meaning and is ignored.';
Seriousness: msHint;
),
(Text:
'A file with documentation is invalid, either an invalid name was specified or the file wasn''t found.';
HelpText:
'Check the name of the file and its path and make sure it exists.';
Seriousness: msError;
),
(Text:
'Some documented topics were not used.';
HelpText:
'Check the spelling of the topics or create links to them.';
Seriousness: msWarning;
),
(Text:
'No heading has been specified for a topic of help on a GUI.';
HelpText:
'The heading should be defined on the same line as the ~gui section starts directly after the name of the topic.';
Seriousness: msWarning;
)
);
initialization
//create object to manage the messages that can be generated by
//~[link TJADDGUIHelpReader]
JADDGUIHelpMessageDescriptions := TMessageDescriptions.Create(
JADDGUIHelpReaderMessages,
'TJADDGUIHelpReader');
finalization
JADDGUIHelpMessageDescriptions.Free; //free list of messages
end.⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -