Hi All,
I am trying to integrate a CHM help file into my application, but I can only find HTML components in Lazarus 1.2
Is CHM help still supported or should I be doing just HTML

Thanks in advance

Richard
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20140321/9c147261/attachment.html>

Richard Mace wrote

Is CHM help still supported or should I be doing just HTML

You can always use DocView as well. DocView is a stand-alone help viewer (no external dependencies). Very fast, and with inline user annotation support, bookmark support, font customization, advanced search etc. It reads the INF help file format which is also very easy to author, and very compact.

To see DocView in action, you can download a binary and same sample INF help files from:

DocView binaries:
http://sourceforge.net/projects/fpgui/files/fpGUI/1.0/ INF docs:
http://sourceforge.net/projects/fpgui/files/fpGUI/Documentation/

Screenshot:
http://fpgui.sourceforge.net/screenshots_apps.shtml

Regards,
- Graeme -

Hi Graeme,
It looks very interesting.
How would I instruct DocView to open at a particular section of a help file from Lazarus?

Richard

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20140322/f00152af/attachment-0001.html>

Does the "INF" help file format support screen shots? I notice that when I open my existing CHM file in lhelp, it doesn't show the embedded screen shots, but when I just double click on the .CHM file within Windows, Microsoft's own viewer is displayed and the screen shots are there.

Richard
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20140322/69fce9ae/attachment.html>

Richard Mace wrote

Hi All, I am trying to integrate a CHM help file into my application,

Well did you look here
http://wiki.lazarus.freepascal.org/Add_Help_to_Your_Application#CHM

but I can only find HTML components in Lazarus 1.2 Is CHM help still supported or should I be doing just HTML

Do you think it's likely CHM support (the default Lazarus help file format) has been withdrawn without any mention in the release notes?

I did look at that wiki page and after I installed the chm components it did load the chm file, but it won't display any images?

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20140322/dbc04731/attachment.html>

Richard Mace wrote

I did look at that wiki page and after I installed the chm components it did load the chm file, but it won't display any images?

I have no idea (haven't used images in CHM myself); perhaps post a sample file somewhere so somebody else could have a look?

Richard Mace wrote

I did look at that wiki page and after I installed the chm components it did load the chm file, but it won't display any images?

The FPC ref.chm has images (.pngs); you could check out how these are generated...

I have uploaded a test.chm file to www.rocksolidpbx.co.uk/downloads if anyone has the time/interest in taking a look.

Richard

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20140322/42db1cfc/attachment.html>

Richard Mace wrote

Does the "INF" help file format support screen shots?

Yes it does. And you can map clickable areas (hotspots) on screenshots too.

Regards,
- Graeme -

Richard Mace wrote

Hi Graeme, It looks very interesting. How would I instruct DocView to open at a particular section of a help file from Lazarus?

DocView (binary download) comes with an extensive help file explaining all it's uses (concatenating help files at runtime, defining help as an environment variable, etc).

But to answer your question, DocView accepts many parameters. The docview.inf help file explains that or select "Help->Command Line Parameters" inside DocView

Supported command line parameters:

<filename> Load the help file <filename>
-h Show this help
-k <text> Search for keyword <<text> in open help files -n <id> Open Topic with numeric ID equal to <id> -s <id> Open Topic with string ID equal to <id> -debuglog <filename> Log information to a file

So you can define numerical or keyword help inside your application - just like you would do with LCL or VCL applications. I don't know if you can override the default help viewer in LCL based apps. But if not, simply trap the F1 key (or probably the OnHelp event) and launch DocView with the the appropriate parameters listed above.

I'm planning on more parameters and integration too. eg: placement and size of DocView, as well as IPC communication between the application and docview. The latter will allow you to control docview from your application.

Regards,
- Graeme -

Reinier Olislagers wrote

Do you think it's likely CHM support (the default Lazarus help file format) has been withdrawn without any mention in the release notes?

No, but the do seem to make it incredible difficult to use CHM help in applications - whereas HTML help is easy. At least that is how it was the last time I CHM support in the Lazarus IDE is made much easier though.

Regards,
- Graeme -

El 22/03/14 19:59, Graeme Geldenhuys ha escrit:

So you can define numerical or keyword help inside your application - just like you would do with LCL or VCL applications. I don't know if you can override the default help viewer in LCL based apps.

Sure you can.
You just have to create a class derived from THelmManager (in unit HelpIntfs).
I use it to invoke a pdf reader (sumatrapdf, since it accepts a keyword as a command line parameter).

Bye

Richard Mace wrote

I have uploaded a test.chm file to www.rocksolidpbx.co.uk/downloads if anyone has the time/interest in taking a look.

That file seems to contain GIFs, a format deprecated for a long time. Probably nobody got around to implementing it in the viewer.

Luca Olivetti wrote

You just have to create a class derived from THelmManager (in unit HelpIntfs).

Thanks for that info.

On a side note:
I see the Lazarus team still didn't update the OnHelp event - which uses the event signature written for Windows 3.1 help viewers (also showing Delphi's ancestry). I have suggested in the past they take up the Kylix 3 OnHelp signature (shown below) which makes a lot more sense for cross-platform, newer or custom written help systems.

type
 THelpEvent = function (HelpType: THelpType; HelpContext: Integer;
HelpKeyword: string; HelpFile: string; var Handled: Boolean): Boolean of
object;

Regards,
- Graeme -

Please explain, what it should do.

Mattias

The current OnHelp event signature is define as follows:

THelpEvent = function(Command: Word; Data: PtrInt; var CallHelp: Boolean): Boolean of object

As you can see Command is of Word type, Data is of PtrInt etc. Pretty meaningless parameters to a developer. The will have to go hunt down the Win32 documentation to see what they mean.

Yet everywhere else in LCL's help context, the help is define by a help file, a THelpType, a HelpKeyword or a HelpContext number. Nowhere else is PtrData or Word types used? So why must OnHelp be such a old (and Windows specific) signature that was designed for a very old Windows help viewer.

Using the Kylix 3 style THelpEvent signature means it makes it MUCH easier to use for the developer - knowing exactly what each parameter means and contains. It is also then very easy for the developer to implement new help systems into their LCL applications - be that a custom viewer (eg: built into the application), MAN style help viewer, PDF lookup, DocView etc.

The Kylix 3 style signature also makes it much more cross-platform friendly... one of the goals of CLX and LCL.

Regards,
- Graeme -

[...lots of words, maybe helpful for someone having Kylix 3...]

I will try to rephrase my question:
Please describe where the event should be added, what the parameters and result do, what the default implementation does, for those people not having Kylix.

Mattias

It is not really Kylix, but probably anything D6+. The old definition

THelpEvent = function(Command: Word; Data: PtrInt; var CallHelp: Boolean): Boolean of object

requires an integer for a topic, like .hlp, and is not very suitable for helptypes that lookup topics by string (like also CHM). CHM also can call topics by integer, but that is the "legacy" way.

The newer definition is for CHM, but some attempt was made to make it multiple helptypes compatible (since they also had to support .hlp)

 THelpEvent = function (HelpType: THelpType; HelpContext: Integer;
HelpKeyword: string; HelpFile: string; var Handled: Boolean): Boolean of
object;

The first param is probably some enum that denotes the helptype. The second and fourth parameter is the key (file+context id) for .hlp like helpsystems.

The third and fourth are the key (file+ textual context) for helpsystems that have a string as context.

Since the generic helpsystems polls various plugged helphandlers (enumerates over the THelpType enums, and if registers calls it), probably the handled boolean is to signal that the current handling found a result.

Mattias Gaertner wrote

Please describe where the event should be added, what the parameters and result do, what the default implementation does, for those people not having Kylix.

Marco explained it. The event should replace the TApplication.OnHelp and TCustomForm.OnHelp implementations.

Here is the details as described by the Kylix documentation.

============================================================ THelpEvent defines event handlers for user help requests.

Unit
----
QForms

Delphi syntax:
--------------
type
  THelpEvent = function (HelpType: THelpType; HelpContext: Integer;
HelpKeyword: string; HelpFile: string; var Handled: Boolean): Boolean of
object;

Description
-----------
The help request event handler has the following parameters.

HelpType indicates whether the help topic is identified by context ID or by keyword.

HelpContext identifies the help topic to display when HelpType is htContext.

HelpKeyword identifies the help topic to display when HelpType is htKeyword.

HelpFile identifies the help file that contains the specified topic.

Handled returns an indication of whether the default help system should display the specified topic after the event handler exits. Set Handled to true if the event handler displays a help topic, and this prevents the application from proceeding to display the identified topic.The event handler should return true if it succeeds, false if it fails. ============================================================

The OnHelp event handler is defined for the TApplication and TCustomForm classes.

Here is the OnHelp event (TApplication) documentation

============================================================ Occurs when the application receives a request for help.

Delphi syntax:
property OnHelp: THelpEvent;

Description

Write an OnHelp event handler to perform special processing when the user requests help. This event occurs when the help system is invoked by a call to InvokeHelp, ContextHelp, or KeywordHelp.The event handler returns true if it succeeds, false if it fails.
============================================================

Here is a very simplistic example as shown by the Kylix help.

============================================================ The following code changes the Help file depending on the active form, before the help viewer is called. AppHelp is assigned to the OnHelp event handler of Application in the OnCreate event of Form1.

function TForm1.AppHelp(Command: Word; Data: Longint; var CallHelp:
Boolean): Boolean;
begin
  Application.HelpFile := Screen.ActiveForm.Name + '.hlp';
  CallHelp := True;
end;
function TForm1.FormCreate(Sender: TObject);
begin
  Application.OnHelp := AppHelp;
end;
============================================================

As Marco mentioned, the THelpEvent, as currently defined, is right out of the Win32 documentation on how to communicate with the MS Windows .HLP help viewer.

I hope this answers your question.

Regards,
- Graeme -

El 23/03/14 19:06, Graeme Geldenhuys ha escrit:

While that is true for the OnHelp event, by subclassing THelpManager you can bypass it and actually query by keyword or context. Not as straightforward but it's possible.

Bye

Luca Olivetti wrote

Not as straightforward but it's possible.

The thing is, I like things straightforward, cross-platform and developer friendly. ;-)

Again, thanks for the info on THelpManager.

Regards,
- Graeme -

Graeme,
Thanks for the info. I'll check it out and see if I can start using it. Hopefully the actuall creating of the .INF file will be a straight forward process as well :)

Richard
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.lazarus.freepascal.org/pipermail/lazarus/attachments/20140324/a6564839/attachment.html>

Richard Mace wrote

Hopefully the actuall creating of the .INF file will be a straight forward process as well :)

The DocView help has a section for developers briefly explaining how to create INF files. More detailed information is in the fpGUI code repository in the <fpgui>/docview/docs/ directory. The WIPF compiler is also included in the fpGUI repository, in the tools/wipfc/ directory.

If you need any further assistance, don't hesitate to ask. The IPF syntax is very easy. And if you are creating Class documentation, the Free Pascal Compiler's fpdoc tool can already generate IPF output for you.

Regards,
- Graeme -