Board index » jbuilder » Using HelpTopics

Using HelpTopics


2004-08-23 09:09:48 PM
jbuilder11
Hi all,
I want to integrate help in my OpenTool, but I couldn't find any
documentation how to achieve this neither in JBuilder's built-in
OpenTool doc or on the Borland website. The PrimetimeHelp class is very
sketchy. Are there any other locations for help on how to integrate
HelpTopic in OpenTools ?
Also some sample source code would also help a lot. As far as possible
I'd like to stick to the documentation OpenTool API, but I understand
that this might be difficult to do.
Regards,
Serge Huber.
 
 

Re:Using HelpTopics

Serge Huber wrote:
Quote
I want to integrate help in my OpenTool, but I couldn't find any
documentation how to achieve this neither in JBuilder's built-in
OpenTool doc or on the Borland website. The PrimetimeHelp class is very
sketchy. Are there any other locations for help on how to integrate
HelpTopic in OpenTools ?
For starters, if you are looking to integrate your
Help manual into the contents displayed in the
JBuilder Help window, the short and not so sweet
of it is that you cannot.
However, you can provide contextual help and additions
to the Help menu in a number of ways.
1. Many interfaces and abstract classes in the OTAPI
(Wizards, PropertyPage, XmtForm, etc.) provide a
"getHelpTopic()" method which you may override, returning
a HelpTopic. That's very straightforward.
2. DefaultDialog and its descendents provide a Help
button to which you can attach a HelpTopic. I think
DefaultDialog has JavaDoc.
3. At any point in your interface, you can add a help
button where one doesn't exist, and in its actionPerformed()
method, invoke HelpManager's showHelp() or showURL() methods.
4. You can also add an Action, or if you want to separate
your Help from the other topics, add an ActionGroup, to
the Help menu. To grab a reference to the Help menu,
look at JBuilderMenu.GROUP_Help.
Quote
Also some sample source code would also help a lot.
As far as possible I'd like to stick to the
documentation OpenTool API, but I understand
that this might be difficult to do.
Can you explain what you mean by "sticking to
the documentation API" a bit better. Do you
mean that you would prefer to use existing
API classes and methods rather than roll
your own? If so, look into the items described
above.
For examples, look at a number of the Open Tools
which come with source code, most notably those
written by Keith Woods, at Code Central. My
"Weaver" OpenTool makes use of the "getHelpTopic()",
mentioned in item #1 above. And you might just
find an example of item #3 in the Weaver code
(you'd think I'd know since I wrote it, but
my memory is faulty, and I'm not at a computer
where I can look it up).
In an upcoming release of Weaver, I do use the
approach in item #4 ... but I'm still writing
the documentation -- that is the help topics --
so the release is being delayed a bit.
--
Paul Furbacher (TeamB)
Save time, search the archives:
www.borland.com/newsgroups/ngsearch.html
Is it in Joi Ellis's Faq-O-Matic?
www.visi.com/~gyles19/fom-serve/cache/1.html
Finally, please send responses to the newsgroup only.
That means, do not send email directly to me.
Thank you.
 

Re:Using HelpTopics

Hi Paul,
First of all, thank you for your detailed answer !
Paul Furbacher [TeamB] wrote:
Quote
For starters, if you are looking to integrate your
Help manual into the contents displayed in the
JBuilder Help window, the short and not so sweet
of it is that you cannot.
No I didn't need to do that.
Quote

However, you can provide contextual help and additions
to the Help menu in a number of ways.

1. Many interfaces and abstract classes in the OTAPI
(Wizards, PropertyPage, XmtForm, etc.) provide a
"getHelpTopic()" method which you may override, returning
a HelpTopic. That's very straightforward.

2. DefaultDialog and its descendents provide a Help
button to which you can attach a HelpTopic. I think
DefaultDialog has JavaDoc.
Ok I already knew about the HelpTopic methods, but there are not at all
documented in the OpenTools API, so I have no real idea of what they
could do.
The main problem I have is that it seems that HelpBooks URLs are
relative to the JBUILDER/doc path, which I think is a shame. How would I
go about using a JAR in lib/ext as a HelpBook ? This way I could have a
single JAR to deploy to lib/ext that could contain everything. Or is
that not recommended ?
Quote

3. At any point in your interface, you can add a help
button where one doesn't exist, and in its actionPerformed()
method, invoke HelpManager's showHelp() or showURL() methods.
Ok, again I think it's a shame that the HelpManager is not documented by
Borland, or am I missing a resource ?
Quote

4. You can also add an Action, or if you want to separate
your Help from the other topics, add an ActionGroup, to
the Help menu. To grab a reference to the Help menu,
look at JBuilderMenu.GROUP_Help.
Actually I was mostly interested in contextual help for a PropertyPage.
But this is also an interesting way of doing it.
Quote

Can you explain what you mean by "sticking to
the documentation API" a bit better. Do you
mean that you would prefer to use existing
API classes and methods rather than roll
your own? If so, look into the items described
above.
Well I've not been in the loop with Borland for a very long time, and
I'm not sure how committed Borland is to keeping the undocumented API's
in PrimeTime and Borland packages stable. So this is what I meant by
sticking to the documented API, assuming it would be the part of the API
that wouldn't change too often.
Quote

For examples, look at a number of the Open Tools
which come with source code, most notably those
written by Keith Woods, at Code Central. My
"Weaver" OpenTool makes use of the "getHelpTopic()",
mentioned in item #1 above. And you might just
find an example of item #3 in the Weaver code
(you'd think I'd know since I wrote it, but
my memory is faulty, and I'm not at a computer
where I can look it up).

In an upcoming release of Weaver, I do use the
approach in item #4 ... but I'm still writing
the documentation -- that is the help topics --
so the release is being delayed a bit.
Ok thanks. I have already released my first public version of my
OpenTool that includes approach #1.
You can find it here :
cc.borland.com/codecentral/ccweb.exe/listing
I'm still working on the associated web site, but that should come soon.
Regards,
Serge Huber.
Quote


 

{smallsort}

Re:Using HelpTopics

Serge Huber wrote:
Quote
Ok I already knew about the HelpTopic methods, but there are not at all
documented in the OpenTools API, so I have no real idea of what they
could do.
There are a few examples in JBuilder's samples/OpenToolsAPI directory.
There's also this book which I highly recommend if you're doing a
measurable amount of OpenTool development:
www.booksurge.com/product.php3
As Paul hinted, most (maybe all?) of the book's examples can be found on
CodeCentral, so that would also be a good source of sample code.
Quote
The main problem I have is that it seems that HelpBooks URLs are
relative to the JBUILDER/doc path, which I think is a shame. How would I
go about using a JAR in lib/ext as a HelpBook ? This way I could have a
single JAR to deploy to lib/ext that could contain everything. Or is
that not recommended ?
I think you do something like this (untested and poorly written, use
Class.getResource as a better way of obtaining the paths for the book):
HelpBook helpBook = new ZipHelpBook("lib/ext/foo.jar",
"/com/mydomain/mypackage/MyClass-help.html");
return new ZipHelpTopic(helpBook, this);
Quote
Ok, again I think it's a shame that the HelpManager is not documented by
Borland, or am I missing a resource ?
Nope. You're right. It's undocumented and a shame. :-)
Quote
Well I've not been in the loop with Borland for a very long time, and
I'm not sure how committed Borland is to keeping the undocumented API's
in PrimeTime and Borland packages stable. So this is what I meant by
sticking to the documented API, assuming it would be the part of the API
that wouldn't change too often.
FWIW, the help API's have been stable since at least JBuilder 3.5 or 4
which is basically the beginning of time as far as PrimeTime is
concerned. Having said that, I do hope they eventually decide to change
it somewhat. The inability to truly plug user documentation into the
help system (including the contents, index, search, etc.) is
unfortunately. But I think if you want to support help from your
property page, you really have no choice except to cross your fingers
and hope it either doesn't change soon or that when it does you'll be
able to deal with it.
--
Gillmer J. Derge [TeamB]
 

Re:Using HelpTopics

Serge Huber wrote:
Quote
The main problem I have is that it seems that HelpBooks URLs are
relative to the JBUILDER/doc path, which I think is a shame. How would I
go about using a JAR in lib/ext as a HelpBook ? This way I could have a
single JAR to deploy to lib/ext that could contain everything. Or is
that not recommended ?
A single deployable JAR has a lot going for it:
your instructions are no more complicated than
saying "stick this JAR in the lib/ext folder"
and you are done ... and it works. So yes, it
probably is a good practice, but there are reasons
to split up the deployment. (If you look at some
of the OT offerings from Ludovic Hochet, you'll
see that he deploys his in multiple JARs because
many of his OTs share common code.)
Have you tried to deploy your single JAR to the
lib/ext directory, containing the help? It should work.
At least that's sort of what I did with Weaver, even
though I packaged the help and code separately.
(I did that because the download would have been
quite big were it all in one JAR.) But the help
JAR, at least according to the instructions I wrote,
goes in the lib/ext directory, not the doc folder.
So far, I haven't heard any complaints. (Maybe folks
are just being kind?)
If you open the Weaver help JAR, you will see that
the root inside the archive is /doc. Since all JARs
in the lib/ext folder get put on the classpath, the
help becomes accessible.
--
Paul Furbacher (TeamB)
Save time, search the archives:
www.borland.com/newsgroups/ngsearch.html
Is it in Joi Ellis's Faq-O-Matic?
www.visi.com/~gyles19/fom-serve/cache/1.html
Finally, please send responses to the newsgroup only.
That means, do not send email directly to me.
Thank you.
 

Re:Using HelpTopics

Hi,
Many thanks for your detailed explanation.
I'm using HelpManager.showURL() from a BasicWizard help button.
My html page gets displayed in JBuilder's help browser but it is "frozen"
(unable to scroll or select anything) until I close the wizard.
Is there a workaround for this?
Stephane Vandenbussche
"Paul Furbacher [TeamB]" < XXXX@XXXXX.COM >a écrit dans le message de
Quote
Serge Huber wrote:


>I want to integrate help in my OpenTool, but I couldn't find any
>documentation how to achieve this neither in JBuilder's built-in
>OpenTool doc or on the Borland website. The PrimetimeHelp class is very
>sketchy. Are there any other locations for help on how to integrate
>HelpTopic in OpenTools ?

For starters, if you are looking to integrate your
Help manual into the contents displayed in the
JBuilder Help window, the short and not so sweet
of it is that you cannot.

However, you can provide contextual help and additions
to the Help menu in a number of ways.

1. Many interfaces and abstract classes in the OTAPI
(Wizards, PropertyPage, XmtForm, etc.) provide a
"getHelpTopic()" method which you may override, returning
a HelpTopic. That's very straightforward.

2. DefaultDialog and its descendents provide a Help
button to which you can attach a HelpTopic. I think
DefaultDialog has JavaDoc.

3. At any point in your interface, you can add a help
button where one doesn't exist, and in its actionPerformed()
method, invoke HelpManager's showHelp() or showURL() methods.

4. You can also add an Action, or if you want to separate
your Help from the other topics, add an ActionGroup, to
the Help menu. To grab a reference to the Help menu,
look at JBuilderMenu.GROUP_Help.

>Also some sample source code would also help a lot.


>As far as possible I'd like to stick to the
>documentation OpenTool API, but I understand
>that this might be difficult to do.

Can you explain what you mean by "sticking to
the documentation API" a bit better. Do you
mean that you would prefer to use existing
API classes and methods rather than roll
your own? If so, look into the items described
above.

For examples, look at a number of the Open Tools
which come with source code, most notably those
written by Keith Woods, at Code Central. My
"Weaver" OpenTool makes use of the "getHelpTopic()",
mentioned in item #1 above. And you might just
find an example of item #3 in the Weaver code
(you'd think I'd know since I wrote it, but
my memory is faulty, and I'm not at a computer
where I can look it up).

In an upcoming release of Weaver, I do use the
approach in item #4 ... but I'm still writing
the documentation -- that is the help topics --
so the release is being delayed a bit.


--


Paul Furbacher (TeamB)

Save time, search the archives:
www.borland.com/newsgroups/ngsearch.html

Is it in Joi Ellis's Faq-O-Matic?
www.visi.com/~gyles19/fom-serve/cache/1.html

Finally, please send responses to the newsgroup only.
That means, do not send email directly to me.
Thank you.
 

Re:Using HelpTopics

Override BasicWizard.help():
ZipHelpBook helpBook = JBuilderHelp.createBook("myjar.jar");
ZipHelpTopic helpTopic = JBuilderHelp.createTopic(helpBook,
"doc/wizard.html");
public void help(WizardPage currentPage, WizardHost host) {
helpTopic.show(currentPage.getPageComponent(host));
}
"Stéphane Vandenbussche" < XXXX@XXXXX.COM >wrote in message
Quote
Hi,
Many thanks for your detailed explanation.
I'm using HelpManager.showURL() from a BasicWizard help button.
My html page gets displayed in JBuilder's help browser but it is "frozen"
(unable to scroll or select anything) until I close the wizard.
Is there a workaround for this?

Stephane Vandenbussche

 

Re:Using HelpTopics

Thank you for the code.
But I was wondering if I could do something like this:
public void help(WizardPage wizardPage, WizardHost wizardHost) {
HelpManager.showURL("foo.bar.com/product/help.html");
}
Doing so, JBuilderX displays the web page indeed, but the help-browser's
window is disabled/frozen.
The only way to be able to scroll the page or even to close the help-browser
is to close the wizard first, only then the help-browser's window becomes
responsive to mouse clicks. My question was if there's a way to workaround
this freezing window issue.
Or should I avoid using the showURL() method at all to display html pages
which are not in my jar?
"Bill Joy" < XXXX@XXXXX.COM >a écrit dans le message de
Quote
Override BasicWizard.help():

ZipHelpBook helpBook = JBuilderHelp.createBook("myjar.jar");
ZipHelpTopic helpTopic = JBuilderHelp.createTopic(helpBook,
"doc/wizard.html");

public void help(WizardPage currentPage, WizardHost host) {
helpTopic.show(currentPage.getPageComponent(host));
}


"Stéphane Vandenbussche" < XXXX@XXXXX.COM >wrote in message
news:412c62e1$ XXXX@XXXXX.COM ...
>Hi,
>Many thanks for your detailed explanation.
>I'm using HelpManager.showURL() from a BasicWizard help button.
>My html page gets displayed in JBuilder's help browser but it is
"frozen"
>(unable to scroll or select anything) until I close the wizard.
>Is there a workaround for this?
>
>Stephane Vandenbussche
>


 

Re:Using HelpTopics

Stéphane Vandenbussche wrote:
Quote
Thank you for the code.
But I was wondering if I could do something like this:

public void help(WizardPage wizardPage, WizardHost wizardHost) {
HelpManager.showURL("foo.bar.com/product/help.html");
}

Doing so, JBuilderX displays the web page indeed, but the help-browser's
window is disabled/frozen.
I think you want to allow the built-in property page/wizard
help management to do its thing. By invoking the HelpManager
in the "help()" method, you may be compounding problems.
The help window which pops up from the Help button
in property and wizard pages was made modal some time
ago when a show-stopping bug was discovered with
the help window when it was non-modal, somewhere
around JBuilder 4 or 6 if I remember correctly.
The quick and dirty fix was to make the help window
modal. No one ever went back to really fix the original
problem (I cannot remember what it was or why it was a
show-stopper), so it has been modal ever since.
It would be nice if someone on the JBuilder Team would
look into this (finally) and make that window *non-modal*
because there's absolutely no reason for it to be modal.
One possible work-around is to advise your OpenTool users
to run their Help browser in a separate JVM. Tell them
to open the Help browser, go to Tools>Preferences ...,
and select the option to run in a separate JVM. JBuilder
must be restarted for this to take effect. Users should
expect that the first time help is invoked, it will take
a significantly longer time to launch compared to invoking
within the same VM.
--
Paul Furbacher (TeamB)
Save time, search the archives:
www.borland.com/newsgroups/ngsearch.html
Is it in Joi Ellis's Faq-O-Matic?
www.visi.com/~gyles19/fom-serve/cache/1.html
Finally, please send responses to the newsgroup only.
That means, do not send email directly to me.
Thank you.
 

Re:Using HelpTopics

I haven't tested it, but I think this would be more likely to succeed (if
you must use a Web page for help which does not seem a good idea to me):
public void help(WizardPage wizardPage, WizardHost wizardHost) {
HelpSystem.showHelp("foo.bar.com/product/help.html",
wizardHost.getDialogParent());
}
"Stéphane Vandenbussche" < XXXX@XXXXX.COM >wrote in message
Quote
Thank you for the code.
But I was wondering if I could do something like this:

public void help(WizardPage wizardPage, WizardHost wizardHost) {
HelpManager.showURL("foo.bar.com/product/help.html");
}

Doing so, JBuilderX displays the web page indeed, but the help-browser's
window is disabled/frozen.
The only way to be able to scroll the page or even to close the
help-browser
is to close the wizard first, only then the help-browser's window becomes
responsive to mouse clicks. My question was if there's a way to workaround
this freezing window issue.
Or should I avoid using the showURL() method at all to display html pages
which are not in my jar?



"Bill Joy" < XXXX@XXXXX.COM >a écrit dans le message de
news:412d3432$ XXXX@XXXXX.COM ...
>Override BasicWizard.help():
>
>ZipHelpBook helpBook = JBuilderHelp.createBook("myjar.jar");
>ZipHelpTopic helpTopic = JBuilderHelp.createTopic(helpBook,
>"doc/wizard.html");
>
>public void help(WizardPage currentPage, WizardHost host) {
>helpTopic.show(currentPage.getPageComponent(host));
>}
>
>
>"Stéphane Vandenbussche" < XXXX@XXXXX.COM >wrote in message
>news:412c62e1$ XXXX@XXXXX.COM ...
>>Hi,
>>Many thanks for your detailed explanation.
>>I'm using HelpManager.showURL() from a BasicWizard help button.
>>My html page gets displayed in JBuilder's help browser but it is
"frozen"
>>(unable to scroll or select anything) until I close the wizard.
>>Is there a workaround for this?
>>
>>Stephane Vandenbussche
>>
>
>


 

Re:Using HelpTopics

The help system runs in the same VM as JBuilder. When there is a modal
dialog, the JDK event queue is designed to limit input to that dialog or any
window which has it as a parent.
The help window launched from a modal dialog therefore has to be modal in
this situation. If you were to open it with some other parent (while a
modal dialog is active) it would not be able to receive keyboard input.
If help was to run in a separate VM (which it did in very early versions of
JBuilder), it would act like pretty much like a modeless dialog.
However it would have a high startup cost, waste memory because it is a
separate rather large Swing application itself meaning yet another heap and
stack, and there would be usability issues because it would either
constantly hide itself behind JBuilder or else always be on top of JBuilder
depending on implementation. Plus it makes the API more difficult if it
runs in a different VM.
While it might be possible to patch the JDK to allow the help window to
switch back and forth between being modeless and sharing modality with
another dialog not its parent while running in the same VM as JBuilder, it
would probably be difficult to accomplish.
"Paul Furbacher [TeamB]" < XXXX@XXXXX.COM >wrote in message
Quote
Stéphane Vandenbussche wrote:
>Thank you for the code.
>But I was wondering if I could do something like this:
>
>public void help(WizardPage wizardPage, WizardHost wizardHost) {
>HelpManager.showURL("foo.bar.com/product/help.html");
>}
>
>Doing so, JBuilderX displays the web page indeed, but the help-browser's
>window is disabled/frozen.

I think you want to allow the built-in property page/wizard
help management to do its thing. By invoking the HelpManager
in the "help()" method, you may be compounding problems.

The help window which pops up from the Help button
in property and wizard pages was made modal some time
ago when a show-stopping bug was discovered with
the help window when it was non-modal, somewhere
around JBuilder 4 or 6 if I remember correctly.

The quick and dirty fix was to make the help window
modal. No one ever went back to really fix the original
problem (I cannot remember what it was or why it was a
show-stopper), so it has been modal ever since.

It would be nice if someone on the JBuilder Team would
look into this (finally) and make that window *non-modal*
because there's absolutely no reason for it to be modal.


One possible work-around is to advise your OpenTool users
to run their Help browser in a separate JVM. Tell them
to open the Help browser, go to Tools>Preferences ...,
and select the option to run in a separate JVM. JBuilder
must be restarted for this to take effect. Users should
expect that the first time help is invoked, it will take
a significantly longer time to launch compared to invoking
within the same VM.


--


Paul Furbacher (TeamB)

Save time, search the archives:
www.borland.com/newsgroups/ngsearch.html

Is it in Joi Ellis's Faq-O-Matic?
www.visi.com/~gyles19/fom-serve/cache/1.html

Finally, please send responses to the newsgroup only.
That means, do not send email directly to me.
Thank you.
 

Re:Using HelpTopics

Paul Furbacher [TeamB] wrote:
Quote
Serge Huber wrote:

Have you tried to deploy your single JAR to the
lib/ext directory, containing the help? It should work.
At least that's sort of what I did with Weaver, even
though I packaged the help and code separately.
(I did that because the download would have been
quite big were it all in one JAR.) But the help
JAR, at least according to the instructions I wrote,
goes in the lib/ext directory, not the doc folder.
So far, I haven't heard any complaints. (Maybe folks
are just being kind?)

If you open the Weaver help JAR, you will see that
the root inside the archive is /doc. Since all JARs
in the lib/ext folder get put on the classpath, the
help becomes accessible.


Would you mind giving me the line you use to create the HelpBook ?
Regards,
Serge Huber.
 

Re:Using HelpTopics

Serge Huber wrote:
Quote
Would you mind giving me the line you use to create the HelpBook ?
Because I deploy the Weaver help within the same JAR
as the OpenTool itself, I just invoke
ZipHelpTopic topic =
new ZipHelpTopic(null, helpTopicName);
Just as a check, I invoke
HelpManager.validateURL(topic.getURLString())
before returning the HelpTopic to the calling
method. If it's not valid, I return null.
If you were to put your help in a different location,
you'd probably have to:
1. Provide a way to configure that through a "property"
on your OpenTool's Property Page that comes up in
Tools>Preferences ... . Use a BasicUrlPanel to let
the user navigate to the installed Help docs.
2. Read that property and use it as the VFS Url for
the book Url. Then use Bill Joy's way of getting
a help topic:
Quote
ZipHelpBook helpBook = JBuilderHelp.createBook("myjar.jar");
ZipHelpTopic helpTopic = JBuilderHelp.createTopic(helpBook,
"doc/wizard.html");
where instead of "myjar.jar" you'd substitute the VFS Url
which the user named by setting the property.
(I hope point #2 makes sense.)
--
Paul Furbacher (TeamB)
Save time, search the archives:
www.borland.com/newsgroups/ngsearch.html
Is it in Joi Ellis's Faq-O-Matic?
www.visi.com/~gyles19/fom-serve/cache/1.html
Finally, please send responses to the newsgroup only.
That means, do not send email directly to me.
Thank you.
 

Re:Using HelpTopics

I wonder if anybody knows how to use class HelpScanner. It seems to me
that this class should be used for help index rebild. But I fail to
create configuration file for this function.