Using a Qt Help file in an installed app

Question

I develop a Qt application for windows, and the help file was generated in qch format with the qhc collection file. The help was embedded in the application using QHelpEngine. The help files are put in the same folder as the application executable, and this works well for dev builds.

But when we deploy the application in "Program Files" using a WiX installer, the documentation works but the search function fails, and I get a warning:

virtual void fulltextsearch::clucene::QHelpSearchIndexWriter::run(): Failed because of CLucene exception.

On the dev build, it seems that CLucene create some index files in the help file folder. Here it cannot, since the help file is in the installation folder, and the standard user cannot write there.

Is the error related to missing index file creation rights? How can I make CLucene write to the User folder instead?

Thanks

I've never seen Qt Help System creates any additional files in runtime. You may have a problem because you do not include sqlite sql driver to your installer which is required to process qch/qhc files. — hank, Sep 24 '15 at 10:28
It does, look in C:\Users\Username\appdata\Local\assistant for instance. I have all the necessary DLL — galinette, Sep 25 '15 at 09:55

score 3 · Accepted Answer · edited Aug 08 '17 at 08:58

I found the solution by looking into assistant source code.

CLucene always writes its cache to the same folder as the .qhc

Qt Assistant handles this by not opening the main qhc directly. It copies it to the user profile (Under windows, in C:\User\Username\appdata\Local\assistant) updating the .qch paths accordingly, and then open this user specific file.

I implemented the same approach and it works like a charm. You don't even have to deploy a qhc in the installer, you can directly create one by calling QHelpEngine with a path which does not exists, and register the qch files using registerDocumentation

So the best way I have found is:

Create a QHelpEngine with the path of a .qhc file which may not exist, but in a folder which exists and is writable. I use QStandardPaths::CacheLocation for this. Qt will create a .qhc file if required, or open it again.
Iterate over all your .qch files and check if they are registered using engine->registeredDocumentations()
For the documentations which are not registered, register them with engine->registerDocumentation
Your engine is ready to use

Here is my code with a single qch file:

QString collPath = QStandardPaths::writableLocation(QStandardPaths::CacheLocation);
QDir().mkpath(collPath);
collPath.append("/myapp.qhc");

engine = new QHelpEngine(collPath, this);
engine->setupData();

QString docPath = QApplication::applicationDirPath()+"/myapp.qch";

docNS = QHelpEngineCore::namespaceName(docPath);

if(docNS.isEmpty() || !engine->registeredDocumentations().contains(docNS))
{
    if(engine->registerDocumentation(docPath))
    {
        qInfo("Registered documentation %s", qPrintable(docPath));
    }
    else
    {
        qWarning("Could not register documentation file %s", qPrintable(docPath));
        qWarning("Help engine error : %s", qPrintable(engine->error()));
    }
}

//Now you can use "engine" in a text browser

I am facing the same problem. Could you please elaborate (or even better show me some code) how to "update the .qch paths"? — Tassos, Aug 08 '17 at 07:54
You do not need to update the .qch paths in the .qhc file, as I wrote in the last part, the best is to let qt recreate it. I'm adding some more details — galinette, Aug 08 '17 at 08:16
I was missing the registration part. Now my code is working fine. Thank you very much. — Tassos, Aug 08 '17 at 08:57
This fix worked for me too, although I ALSO had forgotten to ensure that the newly needed SQL drivers got included in my installer. That's an additional silent error that I had to force Qt to tell me about before this would work. — Jorenko, Nov 10 '17 at 16:25

Using a Qt Help file in an installed app

1 Answers1