summaryrefslogtreecommitdiffstats
path: root/tools/assistant/compat/lib/qassistantclient.cpp
blob: df5e74a8d60bbc796b06c2565c5ee54da681c539 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
/****************************************************************************
**
** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the Qt Assistant of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:LGPL$
** No Commercial Usage
** This file contains pre-release code and may not be distributed.
** You may use this file in accordance with the terms and conditions
** contained in the either Technology Preview License Agreement or the
** Beta Release License Agreement.
**
** GNU Lesser General Public License Usage
** Alternatively, this file may be used under the terms of the GNU Lesser
** General Public License version 2.1 as published by the Free Software
** Foundation and appearing in the file LICENSE.LGPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU Lesser General Public License version 2.1 requirements
** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
**
** In addition, as a special exception, Nokia gives you certain
** additional rights. These rights are described in the Nokia Qt LGPL
** Exception version 1.0, included in the file LGPL_EXCEPTION.txt in this
** package.
**
** GNU General Public License Usage
** Alternatively, this file may be used under the terms of the GNU
** General Public License version 3.0 as published by the Free Software
** Foundation and appearing in the file LICENSE.GPL included in the
** packaging of this file.  Please review the following information to
** ensure the GNU General Public License version 3.0 requirements will be
** met: http://www.gnu.org/copyleft/gpl.html.
**
** If you are unsure which license is appropriate for your use, please
** contact the sales department at http://www.qtsoftware.com/contact.
** $QT_END_LICENSE$
**
****************************************************************************/

#include "qassistantclient.h"

#include <qtcpsocket.h>
#include <qtextstream.h>
#include <qtimer.h>
#include <qfileinfo.h>
#include <qmap.h>

QT_BEGIN_NAMESPACE

class QAssistantClientPrivate
{
    friend class QAssistantClient;
    QStringList arguments;
};

static QMap<const QAssistantClient*,QAssistantClientPrivate*> *dpointers = 0;

static QAssistantClientPrivate *data( const QAssistantClient *client, bool create=false )
{
    if( !dpointers )
        dpointers = new QMap<const QAssistantClient*,QAssistantClientPrivate*>;
    QAssistantClientPrivate *d = (*dpointers)[client];
    if( !d && create ) {
        d = new QAssistantClientPrivate;
        dpointers->insert( client, d );
    }
    return d;
}

/*!
    \class QAssistantClient
    \obsolete
    \brief The QAssistantClient class provides a means of using Qt
    Assistant as an application's help tool.

    \inmodule QtAssistant
    \ingroup helpsystem

    \bold{Note:} \e{This class is obsolete and only required when using
    the old Qt Assistant, now called assistant_adp. If you want to use
    the new Qt Assistant as a remote help viewer, simple create a
    QProcess instance and specify \tt{assistant} as its executable.
    The following code shows how to start Qt Assistant and request a
    certain page to be shown:}

    \snippet doc/src/snippets/code/tools_assistant_compat_lib_qassistantclient.cpp 0
    
    \e{For a complete example using the Qt Assistant remotely, see the \l
    {help/remotecontrol}{Remote Control} example.}
    
    In order to make Qt Assistant act as a customized help tool for
    your application, you must provide your application with a
    QAssistantClient object in addition to a \l
    {assistant-manual.html} {Qt Assistant Document Profile} (\c .adp
    file) and the associated documentation.

    Note that the QAssistantClient class is not included in the Qt
    library. To use it you must add the following line to your pro
    file:

    \snippet doc/src/snippets/code/tools_assistant_compat_lib_qassistantclient.cpp 1

    A QAssistantClient instance can open or close Qt Assistant
    whenever it is required.

    Once you have created a QAssistantClient instance, specifying the
    path to the Qt Assistant executable, using Qt Assistant is
    simple: You can either call the openAssistant() slot to show the
    defined start page of the documentation, or you can call the
    showPage() slot to show a particular help page. When you call
    openAssistant() and showPage(), Qt Assistant will be launched if
    it isn't already running. When Qt Assistant is running, the
    isOpen() function returns true.

    When calling showPage() the Qt Assistant instance will also be
    brought to the foreground if its hidden. The showPage() slot can
    be called multiple times, while calling openAssistant() several
    times without closing the application in between, will have no
    effect.

    You can close Qt Assistant at any time using the closeAssistant()
    slot. When you call openAssistant(), or you call showPage()
    without a previous call to openAssistant(), the assistantOpened()
    signal is emitted. Similarly when closeAssistant() is called,
    assistantClosed() is emitted. In either case, if an error occurs,
    error() is emitted.

    One QAssistantClient instance interacts with one Qt Assistant
    instance, so every time you call openAssistant(), showPage() or
    closeAssistant() they are applied to the particular Qt Assistant
    instance associated with the QAssistantClient.

    Qt Assistant's documentation set can be altered using the command
    line arguments that are passed to the application when it is
    launched. When started without any options, Qt Assistant displays
    a default set of documentation. When Qt is installed, the default
    documentation set in Qt Assistant contains the Qt reference
    documentation as well as the tools that come with Qt, such as \QD
    and \c qmake.

    Use the setArguments() function to specify the command line
    arguments. You can add or remove documentation from Qt Assistant
    by adding and removing the relevant content files: The command
    line arguments are \c {-addContentFile file.dcf} and \c
    {-removeContentFile file.dcf} respectively. You can make Qt
    Assistant run customized documentation sets that are separate from
    the Qt documentation, by specifying a profile: \c {-profile
    myapplication.adp}. The profile format can also be used to alter
    several of Qt Assistant's properties such as its title and
    startpage.

    The Documentation Content File (\c .dcf) and Qt Assistant
    Documentation Profile (\c .adp) formats are documented in the \l
    {assistant-manual.html}{Qt Assistant Manual}.

    For a complete example using the QAssistantClient class, see the
    \e{Simple Text Viewer} example. The example shows how you can make
    Qt Assistant act as a customized help tool for your application
    using the QAssistantClient class combined with a Qt Assistant
    Document Profile.

    \sa {Qt Assistant Manual}, {Simple Text Viewer Example}
*/

/*!
    \fn void QAssistantClient::assistantOpened()

    This signal is emitted when Qt Assistant is opened and the
    client-server communication is set up.

    \sa openAssistant(), showPage()
*/

/*!
    \fn void QAssistantClient::assistantClosed()

    This signal is emitted when the connection to Qt Assistant is
    closed. This happens when the user exits Qt Assistant, if an
    error in the server or client occurs, or if closeAssistant() is
    called.

    \sa closeAssistant()
*/

/*!
    \fn void QAssistantClient::error( const QString &message )

    This signal is emitted if Qt Assistant cannot be started, or if an
    error occurs during the initialization of the connection between
    Qt Assistant and the calling application. The \a message provides an
    explanation of the error.
*/

/*!
  Constructs an assistant client with the specified \a parent. For
  systems other than Mac OS, \a path specifies the path to the Qt
  Assistant executable. For Mac OS, \a path specifies a directory
  containing a valid assistant.app bundle. If \a path is the empty
  string, the system path (\c{%PATH%} or \c $PATH) is used.
*/
QAssistantClient::QAssistantClient( const QString &path, QObject *parent )
    : QObject( parent ), host ( QLatin1String("localhost") )
{
#if defined(Q_OS_MAC)
    const QString assistant = QLatin1String("Assistant_adp");
#else
    const QString assistant = QLatin1String("assistant_adp");
#endif

    if ( path.isEmpty() )
        assistantCommand = assistant;
    else {
        QFileInfo fi( path );
        if ( fi.isDir() )
            assistantCommand = path + QLatin1String("/") + assistant;
        else
            assistantCommand = path;
    }

#if defined(Q_OS_MAC)
    assistantCommand += QLatin1String(".app/Contents/MacOS/Assistant_adp");
#endif

    socket = new QTcpSocket( this );
    connect( socket, SIGNAL(connected()),
            SLOT(socketConnected()) );
    connect( socket, SIGNAL(disconnected()),
            SLOT(socketConnectionClosed()) );
    connect( socket, SIGNAL(error(QAbstractSocket::SocketError)),
             SLOT(socketError()) );
    opened = false;
    proc = new QProcess( this );
    port = 0;
    pageBuffer = QLatin1String("");
    connect( proc, SIGNAL(readyReadStandardError()),
             this, SLOT(readStdError()) );
    connect( proc, SIGNAL(error(QProcess::ProcessError)),
        this, SLOT(procError(QProcess::ProcessError)) );
}

/*!
    Destroys the assistant client object.
*/
QAssistantClient::~QAssistantClient()
{
    if ( proc->state() == QProcess::Running )
        proc->terminate();

    if( dpointers ) {
        QAssistantClientPrivate *d = (*dpointers)[ this ];
        if ( d ) {
            dpointers->remove(this);
            delete d;
            if( dpointers->isEmpty() ) {
                delete dpointers;
                dpointers = 0;
            }
        }
    }
}

/*!
    Opens Qt Assistant, i.e. sets up the client-server communication
    between the application and Qt Assistant, and shows the start page
    specified by the current \l {assistant-manual.html}
    {Qt Assistant Document Profile}. If there is no specfied profile,
    and Qt is installed, the default start page is the Qt Reference
    Documentation's index page.

    If the connection is already established, this function does
    nothing. Use the showPage() function to show another page. If an
    error occurs, the error() signal is emitted.

    \sa showPage(), assistantOpened()
*/
void QAssistantClient::openAssistant()
{
    if ( proc->state() == QProcess::Running )
        return;

    QStringList args;
    args.append(QLatin1String("-server"));
    if( !pageBuffer.isEmpty() ) {
        args.append( QLatin1String("-file") );
        args.append( pageBuffer );
    }

    QAssistantClientPrivate *d = data( this );
    if( d ) {
        QStringList::ConstIterator it = d->arguments.constBegin();
        while( it!=d->arguments.constEnd() ) {
            args.append( *it );
            ++it;
        }
    }

    connect( proc, SIGNAL(readyReadStandardOutput()),
        this, SLOT(readPort()) );

    proc->start(assistantCommand, args);
}

void QAssistantClient::procError(QProcess::ProcessError err)
{
    switch (err)
    {
    case QProcess::FailedToStart:
        emit error( tr( "Failed to start Qt Assistant." ) );
        break;
    case QProcess::Crashed:
        emit error( tr( "Qt Assistant crashed." ) );
        break;
    default:
        emit error( tr( "Error while running Qt Assistant." ) );
    }
}

void QAssistantClient::readPort()
{
    QString p(QString::fromLatin1(proc->readAllStandardOutput()));
    quint16 port = p.toUShort();
    if ( port == 0 ) {
        emit error( tr( "Cannot connect to Qt Assistant." ) );
        return;
    }
    socket->connectToHost( host, port );
    disconnect( proc, SIGNAL(readyReadStandardOutput()),
                this, SLOT(readPort()) );
}

/*!
    Closes the Qt Assistant instance.

    \sa openAssistant(), assistantClosed()
*/
void QAssistantClient::closeAssistant()
{
    if ( !opened )
        return;

    bool blocked = proc->blockSignals(true);
    proc->terminate();
    if (!proc->waitForFinished(2000)) {
        // If the process hasn't died after 2 seconds,
        // we kill it, causing it to exit immediately.
        proc->kill();
    }
    proc->blockSignals(blocked);
}

/*!
    Brings Qt Assistant to the foreground showing the given \a page.
    The \a page parameter is a path to an HTML file
    (e.g., QLatin1String("/home/pasquale/superproduct/docs/html/intro.html")).

    If Qt Assistant hasn't been opened yet, this function will call
    the openAssistant() slot with the specified page as the start
    page.

    \note The first time Qt Assistant is started, its window will open
    in front of the application's windows. Subsequent calls to this function
    will only load the specified pages in Qt Assistant and will not display
    its window in front of the application's windows.

    \sa openAssistant()
*/
void QAssistantClient::showPage( const QString &page )
{
    if (opened) {
        QTextStream os( socket );
        os << page << QLatin1String("\n");
    } else {
        pageBuffer = page;

        if (proc->state() == QProcess::NotRunning) {
            openAssistant();
            pageBuffer.clear();
            return;
        }
    }
}

/*!
    \property QAssistantClient::open
    \brief whether Qt Assistant is open

*/
bool QAssistantClient::isOpen() const
{
    return opened;
}

void QAssistantClient::socketConnected()
{
    opened = true;
    if ( !pageBuffer.isEmpty() )
        showPage( pageBuffer );
    emit assistantOpened();
}

void QAssistantClient::socketConnectionClosed()
{
    opened = false;
    emit assistantClosed();
}

void QAssistantClient::socketError()
{
    QAbstractSocket::SocketError err = socket->error();
    if (err == QTcpSocket::ConnectionRefusedError)
        emit error( tr( "Could not connect to Assistant: Connection refused" ) );
    else if (err == QTcpSocket::HostNotFoundError)
        emit error( tr( "Could not connect to Assistant: Host not found" ) );
    else if (err != QTcpSocket::RemoteHostClosedError)
        emit error( tr( "Communication error" ) );
}

void QAssistantClient::readStdError()
{
    QString errmsg = QString::fromLatin1(proc->readAllStandardError());

    if (!errmsg.isEmpty())
        emit error( errmsg.simplified() );
}

/*!
    \fn void QAssistantClient::setArguments(const QStringList &arguments)

    Sets the command line \a arguments that are passed to Qt Assistant
    when it is launched.

    The command line arguments can be used to alter Qt Assistant's
    documentation set. When started without any options, Qt Assistant
    displays a default set of documentation. When Qt is installed, the
    default documentation set in Qt Assistant contains the Qt
    reference documentation as well as the tools that come with Qt,
    such as Qt Designer and qmake.
*/
void QAssistantClient::setArguments( const QStringList &args )
{
    QAssistantClientPrivate *d = data( this, true );
    d->arguments = args;
}

QT_END_NAMESPACE