1 {
2 /***************************************************************************
3 helpintfs.pas
4 -------------
5 Component Library Code
6
7
8 ***************************************************************************/
9
10 *****************************************************************************
11 This file is part of the Lazarus Component Library (LCL)
12
13 See the file COPYING.modifiedLGPL.txt, included in this distribution,
14 for details about the license.
15 *****************************************************************************
16
17 Author: Mattias Gaertner
18
19 Abstract:
20 Interfaces to define the abstract HelpSystem.
21 You can create your own HelpSystem based on these interfaces
22 or use the LCL help system in lazhelpintf.pas.
23 The THTMLHelpDatabase and THTMLBrowserHelpViewer in lazhelphtml.pas use the
24 LCL help system.
25
26 To create your own help system, implement a descendant of THelpManager.
27 }
28 unit HelpIntfs;
29
30 {$mode objfpc}{$H+}
31
32 interface
33
34 uses
35 Classes, SysUtils, LCLProc;
36
37 type
38 // All help-specific errors should be thrown as this type.
39 EHelpSystemException = class(Exception);
40
41 TShowHelpResult = (
42 shrNone,
43 shrSuccess,
44 shrCancel,
45 shrDatabaseNotFound,
46 shrContextNotFound, // database found, but the element was not found
47 shrViewerNotFound, // no viewer registered for this format
48 shrHelpNotFound,
49 shrViewerError,
50 shrSelectorError
51 );
52 TShowHelpResults = set of TShowHelpResult;
53
54 THelpDatabaseID = string;
55
56 { THelpQuery }
57
58 THelpQuery = class(TPersistent)
59 private
60 FHelpDatabaseID: THelpDatabaseID;
61 public
62 constructor Create(const TheHelpDatabaseID: THelpDatabaseID);
63 property HelpDatabaseID: THelpDatabaseID read FHelpDatabaseID
64 write FHelpDatabaseID;
65 end;
66
67
68 { THelpQueryTOC }
69
70 THelpQueryTOC = class(THelpQuery)
71 end;
72
73
74 { THelpQueryContext }
75
76 THelpQueryContext = class(THelpQuery)
77 private
78 FContext: THelpContext;
79 public
80 constructor Create(const TheHelpDatabaseID: THelpDatabaseID;
81 const TheContext: THelpContext);
82 property Context: THelpContext read FContext write FContext;
83 end;
84
85
86 { THelpQueryKeyword }
87
88 THelpQueryKeyword = class(THelpQuery)
89 private
90 FKeyword: string;
91 public
92 constructor Create(const TheHelpDatabaseID: THelpDatabaseID;
93 const TheKeyWord: string);
94 property Keyword: string read FKeyword write FKeyword;
95 end;
96
97
98 { THelpQueryDirective }
99
100 THelpQueryDirective = class(THelpQuery)
101 private
102 FDirective: string;
103 public
104 constructor Create(const TheHelpDatabaseID: THelpDatabaseID;
105 const TheDirective: string);
106 property Directive: string read FDirective write FDirective;
107 end;
108
109
110 { THelpQuerySourcePosition }
111
112 THelpQuerySourcePosition = class(THelpQuery)
113 private
114 FFilename: string;
115 FSourcePosition: TPoint;
116 public
117 constructor Create(const TheHelpDatabaseID: THelpDatabaseID;
118 const TheFilename: string; const SrcPos: TPoint);
119 property Filename: string read FFilename write FFilename;
120 property SourcePosition: TPoint read FSourcePosition write FSourcePosition;
121 end;
122
123
124 { THelpQueryPascalContexts }
125
126 THelpQueryPascalContexts = class(THelpQuerySourcePosition)
127 private
128 FContextLists: TList;
129 public
130 constructor Create(const TheHelpDatabaseID: THelpDatabaseID;
131 const TheFilename: string; const SrcPos: TPoint;
132 ContextLists: TList);
133 property ListOfPascalHelpContextList: TList read FContextLists
134 write FContextLists;
135 end;
136
137
138 { THelpQueryMessage
139 A query for messages, like the compiler warnings and errors.
140
141 'WholeMessage' is the complete line as string.
142
143 'MessageParts' can be a list of Name=Value pairs, that has been extracted
144 by the IDE. Common names and values are:
145 Name | Value
146 --------|-----------------------------------------------------------------
147 Stage Indicates what part of the build process the message
148 belongs to. Common values are 'FPC', 'Linker' or 'make'
149 Type For FPC: 'Hint', 'Note', 'Warning', 'Error', 'Fatal', 'Panic',
150 'Compiling', 'Assembling'
151 For make:
152 For Linker:
153 Line An integer for the linenumber as given by FPC in brackets.
154 Column An integer for the column as given by FPC in brackets.
155 Message The message text without other parsed items.
156
157
158 Example:
159 Message written by FPC:
160 unit1.pas(21,3) Warning: unit buttons not used
161
162 Results in
163 Stage=FPC
164 Type=Warning
165 Line=21
166 Column=3
167 Message=unit buttons not used
168
169 }
170
171 THelpQueryMessage = class(THelpQuery)
172 private
173 FMessageParts: TStrings;
174 FWholeMessage: string;
175 public
176 constructor Create(const TheHelpDatabaseID: THelpDatabaseID;
177 const TheMessage: string;
178 TheMessageParts: TStrings);
179 destructor Destroy; override;
180 property WholeMessage: string read FWholeMessage write FWholeMessage;
181 property MessageParts: TStrings read FMessageParts write FMessageParts;
182 end;
183
184
185 { THelpQueryClass }
186
187 THelpQueryClass = class(THelpQuery)
188 private
189 FTheClass: TClass;
190 public
191 constructor Create(const TheHelpDatabaseID: THelpDatabaseID;
192 const AClass: TClass);
193 property TheClass: TClass read FTheClass write FTheClass;
194 end;
195
196
197 { THelpManager }
198
199 THelpManager = class(TObject)
200 public
DoHelpNotFoundnull201 function DoHelpNotFound(var ErrMsg: string): TShowHelpResult;
ShowTableOfContentsnull202 function ShowTableOfContents(var ErrMsg: string): TShowHelpResult; virtual;
203 procedure ShowError(ShowResult: TShowHelpResult; const ErrMsg: string); virtual; abstract;
204 // show help for ...
ShowHelpForQuerynull205 function ShowHelpForQuery(Query: THelpQuery; AutoFreeQuery: boolean;
206 var ErrMsg: string): TShowHelpResult; virtual;
ShowHelpForContextnull207 function ShowHelpForContext(Query: THelpQueryContext;
208 var ErrMsg: string): TShowHelpResult; virtual;
ShowHelpForKeywordnull209 function ShowHelpForKeyword(Query: THelpQueryKeyword;
210 var ErrMsg: string): TShowHelpResult; virtual;
ShowHelpForDirectivenull211 function ShowHelpForDirective(Query: THelpQueryDirective;
212 var ErrMsg: string): TShowHelpResult; virtual;
ShowHelpForPascalContextsnull213 function ShowHelpForPascalContexts(Query: THelpQueryPascalContexts;
214 var ErrMsg: string): TShowHelpResult; virtual;
ShowHelpForSourcePositionnull215 function ShowHelpForSourcePosition(Query: THelpQuerySourcePosition;
216 var ErrMsg: string): TShowHelpResult; virtual;
ShowHelpForMessageLinenull217 function ShowHelpForMessageLine(Query: THelpQueryMessage;
218 var ErrMsg: string): TShowHelpResult; virtual;
ShowHelpForClassnull219 function ShowHelpForClass(Query: THelpQueryClass;
220 var ErrMsg: string): TShowHelpResult; virtual;
ShowHelpFilenull221 function ShowHelpFile(const Filename, Title, MimeType: string;
222 var ErrMsg: string): TShowHelpResult; virtual;
ShowHelpnull223 function ShowHelp(const URL, Title, MimeType: string;
224 var ErrMsg: string): TShowHelpResult; virtual;
225 end;
226
227 var
228 HelpManager: THelpManager = nil;// set by the IDE
229 // LCL applications can call CreateLCLHelpSystem in unit LazHelpIntf
230
231 //==============================================================================
232 { Showing help (how it works):
233
234 - starts the help system, if not already started
235 - search all appropriate help Databases for the given context
236 If multiple contexts fit, a help selector is shown and the user chooses one.
237 - calls the help Database to show the context
238 The help Database will search an appropriate help viewer and starts it.
239 }
240
241 // table of contents
ShowTableOfContentsnull242 function ShowTableOfContents: TShowHelpResult;
ShowTableOfContentsnull243 function ShowTableOfContents(var ErrMsg: string): TShowHelpResult;
244
245 // help by ID
ShowHelpOrErrorForContextnull246 function ShowHelpOrErrorForContext(HelpDatabaseID: THelpDatabaseID;
247 HelpContext: THelpContext): TShowHelpResult; overload;
ShowHelpForContextnull248 function ShowHelpForContext(HelpDatabaseID: THelpDatabaseID;
249 HelpContext: THelpContext; var ErrMsg: string): TShowHelpResult; overload;
ShowHelpForContextnull250 function ShowHelpForContext(HelpContext: THelpContext; var ErrMsg: string
251 ): TShowHelpResult; overload;
252
253 // help by keyword (an arbitrary keyword, not only FPC keyword)
ShowHelpOrErrorForKeywordnull254 function ShowHelpOrErrorForKeyword(HelpDatabaseID: THelpDatabaseID;
255 const HelpKeyword: string): TShowHelpResult;
ShowHelpForKeywordnull256 function ShowHelpForKeyword(HelpDatabaseID: THelpDatabaseID;
257 const HelpKeyword: string; var ErrMsg: string): TShowHelpResult; overload;
ShowHelpForKeywordnull258 function ShowHelpForKeyword(const HelpKeyword: string; var ErrMsg: string
259 ): TShowHelpResult; overload;
260
261 // help by compiler directive
ShowHelpForDirectivenull262 function ShowHelpForDirective(HelpDatabaseID: THelpDatabaseID;
263 const HelpDirective: string; var ErrMsg: string): TShowHelpResult; overload;
ShowHelpForDirectivenull264 function ShowHelpForDirective(const HelpDirective: string; var ErrMsg: string
265 ): TShowHelpResult; overload;
266
267 // help for Pascal sources
ShowHelpForPascalContextsnull268 function ShowHelpForPascalContexts(const Filename: string;
269 const SourcePosition: TPoint; ListOfPascalHelpContextList: TList;
270 var ErrMsg: string): TShowHelpResult;
ShowHelpOrErrorForSourcePositionnull271 function ShowHelpOrErrorForSourcePosition(const Filename: string;
272 const SourcePosition: TPoint): TShowHelpResult;
273
274 // help for messages (compiler messages, codetools messages, make messages, ...)
ShowHelpForMessageLinenull275 function ShowHelpForMessageLine(const MessageLine: string;
276 MessageParts: TStrings; var ErrMsg: string): TShowHelpResult;
ShowHelpOrErrorForMessageLinenull277 function ShowHelpOrErrorForMessageLine(const MessageLine: string;
278 MessageParts: TStrings): TShowHelpResult;
279
280 // view help
ShowHelpFilenull281 function ShowHelpFile(const Filename, Title, MimeType: string;
282 var ErrMsg: string): TShowHelpResult;
ShowHelpFileOrErrornull283 function ShowHelpFileOrError(const Filename, Title, MimeType: string
284 ): TShowHelpResult;
ShowHelpnull285 function ShowHelp(const URL, Title, MimeType: string;
286 var ErrMsg: string): TShowHelpResult;
ShowHelpOrErrornull287 function ShowHelpOrError(const URL, Title, MimeType: string
288 ): TShowHelpResult;
289
dbgsnull290 function dbgs(HelpResult: TShowHelpResult): string; overload;
291
292 implementation
293
294
ShowTableOfContentsnull295 function ShowTableOfContents: TShowHelpResult;
296 var
297 ErrMsg: String;
298 begin
299 ErrMsg:='';
300 Result:=ShowTableOfContents(ErrMsg);
301 HelpManager.ShowError(Result,ErrMsg);
302 end;
303
ShowTableOfContentsnull304 function ShowTableOfContents(var ErrMsg: string): TShowHelpResult;
305 begin
306 Result:=HelpManager.ShowTableOfContents(ErrMsg);
307 end;
308
ShowHelpOrErrorForContextnull309 function ShowHelpOrErrorForContext(HelpDatabaseID: THelpDatabaseID;
310 HelpContext: THelpContext): TShowHelpResult;
311 var
312 ErrMsg: String;
313 begin
314 ErrMsg:='';
315 Result:=ShowHelpForContext(HelpDatabaseID,HelpContext,ErrMsg);
316 HelpManager.ShowError(Result,ErrMsg);
317 end;
318
ShowHelpForContextnull319 function ShowHelpForContext(HelpDatabaseID: THelpDatabaseID;
320 HelpContext: THelpContext; var ErrMsg: string): TShowHelpResult;
321 begin
322 Result:=HelpManager.ShowHelpForQuery(
323 THelpQueryContext.Create(HelpDatabaseID,HelpContext),
324 true,ErrMsg);
325 end;
326
ShowHelpForContextnull327 function ShowHelpForContext(HelpContext: THelpContext; var ErrMsg: string
328 ): TShowHelpResult;
329 begin
330 Result:=ShowHelpForContext('',HelpContext,ErrMsg);
331 end;
332
ShowHelpOrErrorForKeywordnull333 function ShowHelpOrErrorForKeyword(HelpDatabaseID: THelpDatabaseID;
334 const HelpKeyword: string): TShowHelpResult;
335 var
336 ErrMsg: String;
337 begin
338 ErrMsg:='';
339 Result:=ShowHelpForKeyword(HelpDatabaseID,HelpKeyword,ErrMsg);
340 HelpManager.ShowError(Result,ErrMsg);
341 end;
342
ShowHelpForKeywordnull343 function ShowHelpForKeyword(HelpDatabaseID: THelpDatabaseID;
344 const HelpKeyword: string; var ErrMsg: string): TShowHelpResult;
345 begin
346 if HelpManager=nil then begin
347 ErrMsg:='HelpManager=nil';
348 exit(shrHelpNotFound);
349 end;
350 Result:=HelpManager.ShowHelpForQuery(
351 THelpQueryKeyword.Create(HelpDatabaseID,HelpKeyword),
352 true,ErrMsg);
353 end;
354
ShowHelpForKeywordnull355 function ShowHelpForKeyword(const HelpKeyword: string; var ErrMsg: string
356 ): TShowHelpResult;
357 begin
358 Result:=ShowHelpForKeyword('',HelpKeyword,ErrMsg);
359 end;
360
ShowHelpForDirectivenull361 function ShowHelpForDirective(HelpDatabaseID: THelpDatabaseID;
362 const HelpDirective: string; var ErrMsg: string): TShowHelpResult;
363 begin
364 Result:=HelpManager.ShowHelpForQuery(
365 THelpQueryDirective.Create(HelpDatabaseID,HelpDirective),
366 true,ErrMsg);
367 end;
368
ShowHelpForDirectivenull369 function ShowHelpForDirective(const HelpDirective: string;
370 var ErrMsg: string): TShowHelpResult;
371 begin
372 Result:=ShowHelpForDirective('',HelpDirective,ErrMsg);
373 end;
374
ShowHelpForPascalContextsnull375 function ShowHelpForPascalContexts(const Filename: string;
376 const SourcePosition: TPoint; ListOfPascalHelpContextList: TList;
377 var ErrMsg: string): TShowHelpResult;
378 begin
379 Result:=HelpManager.ShowHelpForQuery(
380 THelpQueryPascalContexts.Create('',Filename,
381 SourcePosition,ListOfPascalHelpContextList),
382 true,ErrMsg);
383 end;
384
ShowHelpOrErrorForSourcePositionnull385 function ShowHelpOrErrorForSourcePosition(const Filename: string;
386 const SourcePosition: TPoint): TShowHelpResult;
387 var
388 ErrMsg: String;
389 begin
390 ErrMsg:='';
391 Result:=HelpManager.ShowHelpForQuery(
392 THelpQuerySourcePosition.Create('',Filename,
393 SourcePosition),
394 true,ErrMsg);
395 HelpManager.ShowError(Result,ErrMsg);
396 end;
397
ShowHelpForMessageLinenull398 function ShowHelpForMessageLine(const MessageLine: string;
399 MessageParts: TStrings; var ErrMsg: string): TShowHelpResult;
400 // MessageParts will be freed
401 begin
402 Result:=HelpManager.ShowHelpForQuery(
403 THelpQueryMessage.Create('',MessageLine,MessageParts),
404 true,ErrMsg);
405 end;
406
ShowHelpOrErrorForMessageLinenull407 function ShowHelpOrErrorForMessageLine(const MessageLine: string;
408 MessageParts: TStrings): TShowHelpResult;
409 var
410 ErrMsg: String;
411 begin
412 ErrMsg:='';
413 Result:=ShowHelpForMessageLine(MessageLine,MessageParts,ErrMsg);
414 //debugln(['ShowHelpOrErrorForMessageLine Result=',ord(Result),' ErrMsg=',ErrMsg,' ',dbgsName(HelpManager)]);
415 HelpManager.ShowError(Result,ErrMsg);
416 end;
417
ShowHelpFilenull418 function ShowHelpFile(const Filename, Title, MimeType: string;
419 var ErrMsg: string): TShowHelpResult;
420 begin
421 Result:=HelpManager.ShowHelpFile(Filename,Title,MimeType,ErrMsg);
422 end;
423
ShowHelpFileOrErrornull424 function ShowHelpFileOrError(const Filename, Title, MimeType: string
425 ): TShowHelpResult;
426 var
427 ErrMsg: String;
428 begin
429 ErrMsg:='';
430 Result:=ShowHelpFile(Filename,Title,MimeType,ErrMsg);
431 HelpManager.ShowError(Result,ErrMsg);
432 end;
433
ShowHelpnull434 function ShowHelp(const URL, Title, MimeType: string; var ErrMsg: string
435 ): TShowHelpResult;
436 begin
437 Result:=HelpManager.ShowHelp(URL,Title,MimeType,ErrMsg);
438 end;
439
ShowHelpOrErrornull440 function ShowHelpOrError(const URL, Title, MimeType: string): TShowHelpResult;
441 var
442 ErrMsg: String;
443 begin
444 ErrMsg:='';
445 Result:=ShowHelp(URL,Title,MimeType,ErrMsg);
446 HelpManager.ShowError(Result,ErrMsg);
447 end;
448
dbgsnull449 function dbgs(HelpResult: TShowHelpResult): string;
450 const
451 ResultNames: array[TShowHelpResult] of shortstring = (
452 'shrNone',
453 'shrSuccess',
454 'shrCancel',
455 'shrDatabaseNotFound',
456 'shrContextNotFound',
457 'shrViewerNotFound',
458 'shrHelpNotFound',
459 'shrViewerError',
460 'shrSelectorError'
461 );
462 begin
463 Result:=ResultNames[HelpResult];
464 end;
465
466 { THelpQueryDirective }
467
468 constructor THelpQueryDirective.Create(
469 const TheHelpDatabaseID: THelpDatabaseID; const TheDirective: string);
470 begin
471 inherited Create(TheHelpDatabaseID);
472 FDirective := TheDirective;
473 end;
474
475 { THelpQuery }
476
477 constructor THelpQuery.Create(const TheHelpDatabaseID: THelpDatabaseID);
478 begin
479 FHelpDatabaseID:=TheHelpDatabaseID;
480 end;
481
482 { THelpQueryContext }
483
484 constructor THelpQueryContext.Create(const TheHelpDatabaseID: THelpDatabaseID;
485 const TheContext: THelpContext);
486 begin
487 inherited Create(TheHelpDatabaseID);
488 FContext:=TheContext;
489 end;
490
491 { THelpQueryKeyword }
492
493 constructor THelpQueryKeyword.Create(const TheHelpDatabaseID: THelpDatabaseID;
494 const TheKeyWord: string);
495 begin
496 inherited Create(TheHelpDatabaseID);
497 FKeyword:=TheKeyWord;
498 end;
499
500 { THelpQuerySourcePosition }
501
502 constructor THelpQuerySourcePosition.Create(
503 const TheHelpDatabaseID: THelpDatabaseID; const TheFilename: string;
504 const SrcPos: TPoint);
505 begin
506 inherited Create(TheHelpDatabaseID);
507 FFilename:=TheFilename;
508 FSourcePosition:=SrcPos;
509 end;
510
511 { THelpQueryPascalContext }
512
513 constructor THelpQueryPascalContexts.Create(
514 const TheHelpDatabaseID: THelpDatabaseID; const TheFilename: string;
515 const SrcPos: TPoint; ContextLists: TList);
516 begin
517 inherited Create(TheHelpDatabaseID,TheFilename,SrcPos);
518 FContextLists:=ContextLists;
519 end;
520
521 { THelpQueryMessage }
522
523 constructor THelpQueryMessage.Create(const TheHelpDatabaseID: THelpDatabaseID;
524 const TheMessage: string; TheMessageParts: TStrings);
525 begin
526 inherited Create(TheHelpDatabaseID);
527 FWholeMessage:=TheMessage;
528 FMessageParts:=TheMessageParts;
529 end;
530
531 destructor THelpQueryMessage.Destroy;
532 begin
533 FMessageParts.Free;
534 inherited Destroy;
535 end;
536
537 { THelpQueryClass }
538
539 constructor THelpQueryClass.Create(const TheHelpDatabaseID: THelpDatabaseID;
540 const AClass: TClass);
541 begin
542 inherited Create(TheHelpDatabaseID);
543 FTheClass:=AClass;
544 end;
545
546 { THelpManager }
547
THelpManager.DoHelpNotFoundnull548 function THelpManager.DoHelpNotFound(var ErrMsg: string): TShowHelpResult;
549 begin
550 Result:=shrHelpNotFound;
551 ErrMsg:='Help not found';
552 end;
553
THelpManager.ShowTableOfContentsnull554 function THelpManager.ShowTableOfContents(var ErrMsg: string): TShowHelpResult;
555 begin
556 Result:=DoHelpNotFound(ErrMsg);
557 end;
558
ShowHelpForQuerynull559 function THelpManager.ShowHelpForQuery(Query: THelpQuery;
560 AutoFreeQuery: boolean; var ErrMsg: string): TShowHelpResult;
561 begin
562 Result:=DoHelpNotFound(ErrMsg);
563 end;
564
THelpManager.ShowHelpForContextnull565 function THelpManager.ShowHelpForContext(Query: THelpQueryContext;
566 var ErrMsg: string): TShowHelpResult;
567 begin
568 Result:=DoHelpNotFound(ErrMsg);
569 end;
570
THelpManager.ShowHelpForKeywordnull571 function THelpManager.ShowHelpForKeyword(Query: THelpQueryKeyword;
572 var ErrMsg: string): TShowHelpResult;
573 begin
574 Result:=DoHelpNotFound(ErrMsg);
575 end;
576
ShowHelpForDirectivenull577 function THelpManager.ShowHelpForDirective(Query: THelpQueryDirective;
578 var ErrMsg: string): TShowHelpResult;
579 begin
580 Result:=DoHelpNotFound(ErrMsg);
581 end;
582
ShowHelpForPascalContextsnull583 function THelpManager.ShowHelpForPascalContexts(
584 Query: THelpQueryPascalContexts; var ErrMsg: string): TShowHelpResult;
585 begin
586 Result:=DoHelpNotFound(ErrMsg);
587 end;
588
THelpManager.ShowHelpForSourcePositionnull589 function THelpManager.ShowHelpForSourcePosition(
590 Query: THelpQuerySourcePosition; var ErrMsg: string): TShowHelpResult;
591 begin
592 Result:=DoHelpNotFound(ErrMsg);
593 end;
594
THelpManager.ShowHelpForMessageLinenull595 function THelpManager.ShowHelpForMessageLine(Query: THelpQueryMessage;
596 var ErrMsg: string): TShowHelpResult;
597 begin
598 Result:=DoHelpNotFound(ErrMsg);
599 end;
600
ShowHelpForClassnull601 function THelpManager.ShowHelpForClass(Query: THelpQueryClass;
602 var ErrMsg: string): TShowHelpResult;
603 begin
604 Result:=DoHelpNotFound(ErrMsg);
605 end;
606
ShowHelpFilenull607 function THelpManager.ShowHelpFile(const Filename, Title, MimeType: string;
608 var ErrMsg: string): TShowHelpResult;
609 begin
610 Result:=DoHelpNotFound(ErrMsg);
611 end;
612
THelpManager.ShowHelpnull613 function THelpManager.ShowHelp(const URL, Title, MimeType: string;
614 var ErrMsg: string): TShowHelpResult;
615 begin
616 Result:=DoHelpNotFound(ErrMsg);
617 end;
618
619 end.
620
621