QHelpEngine how-to

[goetz]

Does it work with the docs on the hard disk?
Did you add the file to the .qrc configuration file?
Are the files present in the resources? You can use QDir on file path ":/" to look at the contents.

[willypuzzle]

bq. Does it work with the docs on the hard disk?
Did you add the file to the .qrc configuration file?
Are the files present in the resources? You can use QDir on file path “:/” to look at the contents.

It doesn't work with docs on the hard disk because I tried to add the absolute path of .qhc file (for example: QHelpEngine("/home/willy/help.qhc")) and it doesn't work.

I added it to .qrc configuration file and the file is present in the resources.

I don't understand why I have to use QDir.

[goetz]

You can use QDir to list the bundled resources (are all expected files in there, etc.). It does not help in using the help engine, though.

Does your help collection work with Qt Assistant? You can test it by adding "-collectionFile xxx" on the command line.

[willypuzzle]

Strange, If I add collection file by Preferences panel of Qt Assistant I see it, but if I use -collectionFile command line option I don't see it...

[goetz]

It works for me, but only if I add data to the keywords and toc sections in the XML configuration file.

[willypuzzle]

This is the help.qhp file:
@
<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
<namespace>wchords-client</namespace>
<virtualFolder>help</virtualFolder>
<customFilter name="wchords-client">
<filterAttribute>wchords-client</filterAttribute>
<filterAttribute>all</filterAttribute>
</customFilter>
<filterSection>
<filterAttribute>wchords-client</filterAttribute>
<filterAttribute>all</filterAttribute>
<toc>
<section title="WChords-client Manual" ref="description.html">
<section title="Import Tool" ref="import_tool.html" />
</section>
</toc>
<keywords>
<keyword name="import" id="wchords-client::import" ref="import_tool.html" />
<keyword name="description" id="wchords-client::description" ref="description.html" />
</keywords>
<files>
<file>.html</file>
<file>images/.jpg</file>
</files>
</filterSection>
</QtHelpProject>
@
It seems correct for me...

[goetz]

The file looks ok to me (though I'm not an expert in creating help content).

Can you put together a small sample, just two or three help files, the config files etc. and put a ZIP on pastbin ore something similar. We can have a look then.

[willypuzzle]

Ok I have put all in a zip file containing my help system. It's very small and available at http://dl.dropbox.com/u/7070214/WChords/related_files/help_files.zip

I did
@
qcollectiongenerator help.qhcp -o help.qhc
@
to generate help collection.

[goetz]

Just tried it on the command line, everything is fine:

@
/Applications/Assistant.app/Contents/MacOS/Assistant -collectionFile help.qhc
@

[willypuzzle]

Yes it works to me too. But why it doesn't work with this code?
@
QHelpEngine* he = new QHelpEngine(":help/help.qhc");

QHelpContentModel contentModel = he->contentModel();
QHelpContentWidget contentWidget = he->contentWidget();
QHelpIndexModel indexModel = he->indexModel();
QHelpIndexWidget indexWidget = he->indexWidget();

QSplitter* splitter = new QSplitter();
splitter->addWidget(contentWidget);
splitter->addWidget(indexWidget);

contentWidget->setModel(contentModel);
indexWidget->setModel(indexModel);

splitter->show();
@
Maybe I got wrong in something...

[goetz]

Ok, two things:

First: you must call

@
he->setupData();
@

before you can use the help data. It returns a bool if the setup was ok. Use "QHelpEngineCore::error() ":http://doc.qt.nokia.com/latest/qhelpenginecore.html#error to retrieve an error message (QHelpEngine dervives from QHelpEngineCore).

Second, the more important part: You cannot use Qt resources for storing the help content. You must put it into regular files and distribute them along your application.

The reason for the latter is simple: The compiled help files are actually SQLite databases. Qt does not intercept the file name but hands it over directly to the SQLite functions (by calling toUtf8() on the "path"), which in turn try to open that file - and will eventually fail, of course.

[willypuzzle]

It doesn't work anyway and error() leaves no error. This is the new code:
@
QHelpEngine* he = new QHelpEngine("./help.qhc");
he->setupData();
qDebug() << he->error();

QHelpContentModel *contentModel = he->contentModel();
QHelpContentWidget *contentWidget = he->contentWidget();
QHelpIndexModel* indexModel = he->indexModel();
QHelpIndexWidget* indexWidget = he->indexWidget();

QSplitter* splitter = new QSplitter();
splitter->addWidget(contentWidget);
splitter->addWidget(indexWidget);

contentWidget->setModel(contentModel);
indexWidget->setModel(indexModel);

splitter->show();

@
I took care to call program in the same help.qhc directory.

[goetz]

Try it with an absolute path.

For runtime you can use something like this:

@
QString helpPath = QApplication::applicationDirPath() + "/help_files/help.qhc";
@

Be aware, that this does not work on the Mac due to the applications bundles used there.

[willypuzzle]

I followed your suggest and this is the new code:
@
QFileInfo fileInfo("help.qhc");
if (fileInfo.exists()) {

    QHelpEngine* he = new QHelpEngine(fileInfo.absoluteFilePath());
    he->setupData();
    qDebug() << fileInfo.absoluteFilePath();
    qDebug() << he->error();

    QHelpContentModel *contentModel = he->contentModel();
    QHelpContentWidget *contentWidget = he->contentWidget();
    QHelpIndexModel* indexModel = he->indexModel();
    QHelpIndexWidget* indexWidget = he->indexWidget();

    QSplitter* splitter = new QSplitter();
    splitter->addWidget(contentWidget);
    splitter->addWidget(indexWidget);

    contentWidget->setModel(contentModel);
    indexWidget->setModel(indexModel);

    splitter->show();
}else{
    qDebug() << "File doesn't exist";
}

@
It outputs the correct absolute file name(see line 6) and there is no error.
But it doesn't work....

[goetz]

Do you have help.qch in that directory too? It's needed!

[willypuzzle]

Yes, I checked it with
@
qDebug() << fileInfo.absoluteFilePath();
@
that returns the correct absolute file name of the file.

[goetz]

Ahm... yo need both files:

help.qhc
help.qch

I know, that suffixes are hard to differentiate!

[willypuzzle]

Ahem sorry, I just tried to put that file in the same directory and it seems to work even though it has strange behavior. I have to study the situation...
However thanks :)

[iforce2d]

Sorry to bring up an old thread but I have just spent an embarrassing number of hours on this issue myself. My problem and solution were exactly the same as willypuzzle's, namely that both the .qhc and .qch files must be present.

Looking at those files now, even with my tiny test help pages it's apparent from the file sizes that the .qch contains the actual content, but this is easily overlooked for new users dealing with the plethora of similar file extensions for the first time. Even when the .qch is missing the .qhc is found and loads successfully, and setupData() is successful too, which unfortunately draws attention away from the missing file being the source of the problem.

I think it would be good if it was made clearer in the documentation that both these files are necessary. Specifically, new users will likely arrive at this page as a first reference:
http://qt-project.org/doc/qt-4.8/qthelp-framework.html
From this I got the impression that the compressed help was merely a intermediate step, and the collection was the sole final outcome of the process.

[Woody]

[SOLVED]

I don't know it is appropriate to ask the question here (if not please say so i'll start a new topic)

I have the problem with an error, it happens when calling the setCollectionFile() funtion of QHelpEngine.

@void HelperWindow::initialize()
{
HelperWindow::setWindowFlags(Qt::WindowStaysOnTopHint);

m_helpEngine->setCollectionFile(QApplication::applicationDirPath() + "doc/athleticsmanager.qhc");
m_helpEngine->setupData();

}@

When i look deeper into the code behind this function i get this:
@if (fileName == collectionFile())
return;@

It's in the collectionFile() function, that only does
@return d->collectionHandler->collectionFile();@

, where i get "Segmentation Fault"

I dont really know what to do now, is there someone who can help me with this problem?