July 11, 2011

sbaebler sbaebler
Lab Rat
3 posts

Documentation without Qt Assistant

 

Hi

I’ve been reading about the documentation API that Qt provides, but it seems that it does not meet my needs.

We have an existing external documentation in html that is written by a person who does not have access to the source code.
We have introduced a documentation system where the user can rightclick on any widget and jump to the corresponding html page in the documentation.

If I understand it correctly, this feature would be part of the Qt Documentation API if the documentation was in a qch format.

Extract from http://doc.qt.nokia.com/4.7-snapshot/qthelpproject.html:
“To enable the QHelpEngine to retrieve the proper documentation to a given link, every documentation set has to have a unique identifier.”

It is not clear to me, why the target of these links can only be in qch files. Is there a possibility to use the QHelpEngine with normal html files?

Are compiled help files not quite an old concept and nowadays, most documentation is simply a normal html file/folder?

Regards

Sacha

7 replies

July 11, 2011

Volker Volker
Ant Farmer
5331 posts

That’s just the way it works. The source for the .qch files are regular HTML files, so the additional work shouldn’t be too much.

I don’t know for sure, but I’m pretty sure the reason for the compiled format is a more than noticeable speedup.

July 11, 2011

dialingo dialingo
Lab Rat
151 posts

Qt provides lots of different tools for producing help systems:

If you like to keep your files as HTML files, you can use webkit to build your custom viewer. Obviously you have a need for a customized version. Otherwise you would be using firefox. The requirment you mentioned, clicking on an image to jump to another page is a standard browser feature however.

Assistant is a very powerful documentation viewer. You can compile html sources and the result is one file for easy distribution. You get an index and full text search. There are still companies running around selling tools like this for a fortune.

July 11, 2011

sbaebler sbaebler
Lab Rat
3 posts
Volker wrote:
I don’t know for sure, but I’m pretty sure the reason for the compiled format is a more than noticeable speedup.

I can imagine this is the case for larger projects, but for our documentation, the index and search functionality provided by the documentation tool we use is sufficient.

As our customers are not computer scientists, I think they would be confused that they have to use an additional piece of software.

The presentation of the help files in Qt Assistant is not so nice. When I need to read the Qt class reference, I rather use the browser than with Qt assistant.

dialingo wrote:
If you like to keep your files as HTML files, you can use webkit to build your custom viewer. Obviously you have a need for a customized version. Otherwise you would be using firefox. The requirment you mentioned, clicking on an image to jump to another page is a standard browser feature however.

I don’t quite understand what you mean by “build a custom viewer”. Are you refering to displaying help directly in the UserInterface of the application? This is something I might want to do at a later stage, but for now I would like to automate the display of help upon rightclicks.

I’m fine with using firefox, but the functionality I use is right click on a UI element in my software (not on a website), I get a “Get Help” Context menu and upon clicking in that menu, Firefox opens with the apropriate documentation.

July 11, 2011

dialingo dialingo
Lab Rat
151 posts

A feature that might be relevant for you:


and
  1. void QWidget::setWhatsThis ( const QString & )

But sure, if you do not need the features that come with Qt Assistant, you may use an external web browser as well.

July 11, 2011

sbaebler sbaebler
Lab Rat
3 posts

That seems to be a good feature. I will put a short description in this box and also provide a “read more” link that then jumps to the full documentation in the browser:

“If the text is rich text and the user clicks on a link, the widget also receives a QWhatsThisClickedEvent with the link’s reference as QWhatsThisClickedEvent::href().” (from http://doc.qt.nokia.com/4.7-snapshot/qwhatsthis.html)

Thanks for your help

July 11, 2011

Volker Volker
Ant Farmer
5331 posts
sbaebler wrote:
I’m fine with using firefox, but the functionality I use is right click on a UI element in my software (not on a website), I get a “Get Help” Context menu and upon clicking in that menu, Firefox opens with the apropriate documentation.

Alternatively you could just open a modeless dialog containing a QWebView and load the HTML into that.

July 13, 2011

sbaebler sbaebler
Lab Rat
3 posts

I’m currently working on the implementation of the documentation links. It is possible using the whatsThis or modal dialog, but I think the programming and documenting workflow could be improved much.

Rather than having to enable context help and write the text for every UI element that is added, context help should be available by default.

Developers tend to forget to add context help support and it can only be added by modifying the code. It would be better to have the context text and links externalized (I have read into localization, but there a first text is always required, from which is then translated).

Our old implementation was:

  1. class SomeUIElement {
  2.  
  3. Q_OBJECT
  4.  
  5. // context help action is added in constructor
  6. SomeUIElement() {
  7.     QString vHelpText = ...;
  8.     QAction* vContextHelpAction = new QAction(QIcon(""), tr(vHelpText), this);
  9.     connect(vContextHelpAction, SIGNAL(triggered()), this, SLOT(OnContextHelp()));
  10.     addAction(vContextHelpAction);
  11.     setContextMenuPolicy(Qt::ActionsContextMenu);
  12. }
  13.  
  14. void OnContextHelp() {
  15.   QString vLink = GetContextLinkFor("myClassIdentifier");
  16.   OpenHtmlFile(vLink);
  17. }
  18.  
  19. }

A first improvement is that I could replace “myClassIdentifier” by QString vClassName = metaObject()→className(); and use this as the identifier. Like that, the OnContextHelp method is the same for every class.

In a second step, I thought I could create my own version of QWidget

  1. class MyContextHelpEnabledWidget
  2. {
  3.   void OnContextHelp() {
  4.   ...
  5.   }
  6. }

and make all my user interface elements inherit from MyContextHelpEnabledWidget instead of QWidget. But this works only for the dialogs I create. I would prefer to have this on a “core UI element” level, i.e. for every button, dropdown, table, etc. but then I do not know how I could have QButton inherit from MyContextHelpEnabledWidget instead of QWidget. (I guess this is too much hacking anyway).

In short again, how can I implement a default context help for every button in my application?

 
  ‹‹ [solved]Errors when linking to a shared Qt library that I built.      [SOLVED] How to destroy widget when close QDockWidget ››

You must log in to post a reply. Not a member yet? Register here!