Lazarus
Announcements => Third party => Topic started by: Bad Sector on March 18, 2011, 05:42:03 am
-
Hi all,
I've just uploaded at GitHub a new project of mine called LazHelp. LazHelp is a hypertext help system written in LCL/Lazarus which can be used to add an in-program help site. Since it is written in LCL it should, in theory, work everywhere Lazarus works (in practice i've just tested in on Mac OS X/Carbon and it crashes due to some TCanvas/clipping rect issue, but i'm using an old nightly build there which might be the reason).
With LazHelp one can write a help site (a bunch of help pages) using the included editor and use it from his program to show the pages in a panel (TLazHelpViewer), popup box (TLazHelpPopupViewer) or window (TLazHelpWindowedViewer). The panel and popup viewers can redirect their links to an optionally defined windowed viewer.
Here is how the windowed viewer looks like (showing the help from the LazHelp Editor which also contains the documentation for making help sites):
(http://dl.dropbox.com/u/5698454/lhwin.png)
The windowed viewer can also be registered as a "Help Manager" to handle context and keyword queries (show pages based on the HelpContext or HelpKeyword attributes of controls).
You can find it here (http://badsector.github.com/lazhelp/) with links to source downloads (and a windows binary of the editor which can be used to see how the help system behaves).
The license for the components and controls is zlib.
-
Kinda cool, I'll have to take a look at it. You seem to have your own syntax (a mix of RTF and HTML?) so it's another thing to learn.
-
Hi,
Thanks a lot ! It's very helpful !
Cheers !
-
i've just tested in on Mac OS X/Carbon and it crashes due to some TCanvas/clipping rect issue, but i'm using an old nightly build there which might be the reason)
Here's information about Mac's native help support. Can you integrate with it?
http://web.me.com/macpgmr/ObjP/MacXPlatform_Part8.html#Help
Thanks.
-Phil
-
Very nice work, thanks. ;D
regards.
-
Wonderfull! Thanks!
Cheers,
Peter
-
Here's information about Mac's native help support. Can you integrate with it?
http://web.me.com/macpgmr/ObjP/MacXPlatform_Part8.html#Help
I'm not sure how possible it is to integrate with Mac OS X's help. To do that i'll need the ability to hook into the calls that would otherwise show Mac's help system and write some sort of search that gives back the results to the Help menu (for the realtime search).
While i might do these at some point in the future, in the meanwhile i'm more interested in having it work without crashing. The next part would be to make it look more Mac-like than it does right now, although i'm not sure how possible that is without Cocoa support.
-
Have you checked to see whether the Lazarus help system works yet on Mac? The last time I checked I could not get the example even to work:
http://bugs.freepascal.org/view.php?id=17866
I guess the problem with any non-native help system on Mac is that users generally expect help to look and behave and be accessible in the same way with Mac software. Have you gone through various programs on Mac to see whether any programs use their own help viewer? If not, that should be a signal on what the normal way of doing help is on Mac.
The Mac native system also supports features that might be a lot of work to support in a custom viewer, such as video. If you look at the Xcode 4 help, I believe there are videos embedded in it. Also, the native system obviously supports localization.
Maybe another approach you could take would be simply to write a little converter that takes your editor's HTML and adds the tags and what-not that make it Mac-friendly. Then just use the Mac help viewer.
Thanks.
-Phil
-
Work like a charm in ArchLinux..Thanx a lot :))) :)
-
I guess the problem with any non-native help system on Mac is that users generally expect help to look and behave and be accessible in the same way with Mac software. Have you gone through various programs on Mac to see whether any programs use their own help viewer? If not, that should be a signal on what the normal way of doing help is on Mac.
The Mac native system also supports features that might be a lot of work to support in a custom viewer, such as video. If you look at the Xcode 4 help, I believe there are videos embedded in it. Also, the native system obviously supports localization.
I have a bunch of apps that use custom help viewers (or just opening some text file or pdf file), although most of them are cross-platform apps.
I'm not very concerned about following exactly the Mac style since from what i've seen this is a lost cause with Lazarus, unless some features are added, like different "versions" of a form per widgetset (the expected style and layout is different under Windows, GNOME and Mac OS X for example).
LazHelp doesn't provide much features, but this isn't the goal. Instead i want something simple that a) works and b) works across platforms, in that order. Currently the best way with Lazarus (and many other cross platform applications) is to open a help site in the browser. This is good (and i've written a tool to assist in that (http://badsector.github.com/quhelp/)) but it has it's own problems and limitations.
(as a sidenote, while generally i like Mac OS X, i'm not sure i like its help system interface)
Maybe another approach you could take would be simply to write a little converter that takes your editor's HTML and adds the tags and what-not that make it Mac-friendly. Then just use the Mac help viewer.
Writing a HTML exporter for the format that LazHelp currently uses should be trivial since the document structure is very HTML-like and is something i'm planning to do. However that would be far from cross-platform since people will need to have special code for Mac. Although if someone uses Lazarus to make Mac apps which behave as Mac as possible, he'll already have such issues (in a Mac app of mine i had a "Macize" procedure which did stuff like changing properties of some controls -removing borders, etc- and converting Ctrl+<blah> shortcuts to Command+<blah> :-P).
But as i said, having "proper" Mac OS X support is rather low in my priorities. Having it work without crashing is much more important :-). And since the Carbon widgetset is far from stable, i'm not sure if the crashing issue is in my code or the widgetset code. I'll need to checkout from the svn and see if i can replicate the crash with a simpler program.
-
Fair enough.
Sounds like you're well aware of the issues and understand how quickly the idea of a cross-platform UI breaks down. In one of my projects, I convert the forms for use on Mac whenever changes are made to them, using this converter and the -m -s switches:
http://web.me.com/macpgmr/XDev/XDevStatus.html
That way it's completely automatic.
Although now I'm working primarily using FPC's Objective Pascal dialect with Xcode and Cocoa. That allows targeting of iOS too.
Thanks.
-Phil
-
Only for curiosity, the project works with FpGUI?
-
Hmm, like the yer' old WinHelp what all remember from the Windows 3.1 Operating Systems.
Time ago, i written and help system using the IPro Components (Because im lazy to code using the included Laz Components instead create my owns :D)
-
I fixed the Mac OS X issues (by working around them... but still thats the best i could do given the state of the Carbon widgetset). So LazHelp is usable in Windows, GTK+ and Mac OS X. Also i tweaked the appearance a bit in these last two platforms.
Here is an image showing the LazHelp Editor's help window (http://badsector.github.com/lazhelp/lhall.png) under Windows, Mac OS X and GTK+ 2.
@Hydexon:
It probably wont work with fpGUI since the fpGUI LCL backend is in prealpha stage.
-
:D :D works good, used to uses jans Freeware Cheetah in windows, been looking for a simple but neat help system, this really hits the spot, many thanks for your hard work :D :D
Regards
dave
-
Wonderful! Can't tell you how much I appreciate this. I usually create help files using the CHM format & that's tricky to use on Linux.
Now with LazHelp, all things being equal, we'll eventually have something like the C++ library wxWindows' wxHTML Help which runs native on all systems that the library supports. Who knows, maybe LazHelp will one day be like HelpBlocks http://www.helpblocks.com/ (http://www.helpblocks.com/)
Can I insert graphics, like screenshots, in the files that LazHelp creates?
Keep up the good work.
-
Wonderful! Can't tell you how much I appreciate this. I usually create help files using the CHM format & that's tricky to use on Linux.
?
Now with LazHelp, all things being equal, we'll eventually have something like the C++ library wxWindows' wxHTML Help which runs native on all systems that the library supports. Who knows, maybe LazHelp will one day be like HelpBlocks http://www.helpblocks.com/ (http://www.helpblocks.com/)
Helpblocks is a content generator for existing helpsystem, not a helpsystem in itself?
-
Great work. I am about to start on the help system for my cross platform product and have been reading up on the help systems for all three operating systems I will offer my product for and now this will make that a lot easier and with less headaches.
Thank you.
-
Can I insert graphics, like screenshots, in the files that LazHelp creates?
You can (the editor has a screenshot of itself in the help) but it is a bit tricky because your code has somehow to provide the TGraphic instance to use. Use the img element with a name like, f.e. "shot1" and register an event handler for the onGetGraphic event of the TLazHelp instance you use. When the help system requests the graphic it will call this handler with the "shot1" (or whatever you used) in the AName parameter and expect a TGraphic instance for the AGraphic parameter.
Personally in the editor i just used a PNG as a lazarus resource (made with the lazres tool that comes with lazarus). It was a single image so that was ok. If you have many images you might want to automate things a bit and possibly load them from external files. In that case your onGetGraphic should load the image file requested from the disk and provide it as a graphic. Note that TLazHelp will keep the instance cached so it won't ask you each time the image needs to be displayed. However also note that it doesn't make a copy of the instance: it uses the instance you provided so you need to keep the instances around for the lifetime of the TLazHelp instance. An easy method to do that is to use TImage instances to load the graphics and have the TLazHelp instance as the owner of the TImage instance so that once TLazHelp is destroyed it will also destroy the TImages.
Note that if you want to use graphics which are already used in your program (like button icons, etc) you don't need to duplicate things. Just register them with TLazHelp using the TLazHelp.RegisterGraphic method which accepts a name and a TGraphic instance. For image lists use TLazHelp.RegisterImageList which uses a prefix for each image (f.e. for a "il" prefix the first image will be "il0", the second "il1", etc). Note that unlike the above methods, the images from image list are copied to private bitmaps.
In the future i might add the ability to embed base64-encoded images for easier use of external graphics.
-
Lazarus' CHM component makes CHM files look ugly in Linux.
The own generated CHMs should be fine mostly. Of course you can't use all of CSS with an embedded browser.