Qt 4.2 User's Guide: QAssistantClient Class Reference

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 {assistant-manual.htmlprofiles}{Qt Assistant Document Profile} (.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:

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.

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 and 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 {-addContentFile file.dcf} and {-removeContentFile file.dcf} respectively. You can make Qt Assistant run customized documentation sets that are separate from the Qt documentation, by specifying a profile: {-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 (.dcf) and Qt Assistant Documentation Profile (.adp) formats are documented in the {assistant-manual.html}{Qt Assistant Manual}.

For a complete example using the QAssistantClient class, see the {assistant/simpletextviewer}{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.

Constructor & Destructor Documentation

QAssistantClient::QAssistantClient	(	const QString &	path,
		QObject *	parent = `0`
	)

Constructs an assistant client with the given parent. The path specifies the path to the Qt Assistant executable. If path is an empty string the system path ({PATH%} or $PATH) is used.

Definition at line 171 of file qassistantclient.cpp.

References assistantCommand, QObject::connect(), error(), QFileInfo::isDir(), opened, pageBuffer, path, port, proc, procError(), readStdError(), SIGNAL, SLOT, socket, socketConnected(), socketConnectionClosed(), and socketError().

00172     : QObject( parent ), host ( "localhost" )
00173 {
00174     if ( path.isEmpty() )
00175         assistantCommand = "assistant";
00176     else {
00177         QFileInfo fi( path );
00178         if ( fi.isDir() )
00179             assistantCommand = path + "/assistant";
00180         else
00181             assistantCommand = path;
00182     }
00183 
00184 #if defined(Q_OS_MAC)
00185     assistantCommand += ".app/Contents/MacOS/assistant";
00186 #endif
00187 
00188     socket = new QTcpSocket( this );
00189     connect( socket, SIGNAL(connected()),
00190             SLOT(socketConnected()) );
00191     connect( socket, SIGNAL(disconnected()),
00192             SLOT(socketConnectionClosed()) );
00193     connect( socket, SIGNAL(error(QAbstractSocket::SocketError)),
00194              SLOT(socketError()) );
00195     opened = false;
00196     proc = new QProcess( this );
00197     port = 0;
00198     pageBuffer = "";
00199     connect( proc, SIGNAL(readyReadStandardError()),
00200              this, SLOT(readStdError()) );
00201     connect( proc, SIGNAL(error(QProcess::ProcessError)),
00202         this, SLOT(procError(QProcess::ProcessError)) );
00203 }

Here is the call graph for this function:

QAssistantClient::~QAssistantClient ( )

Destroys the assistant client object.

Definition at line 208 of file qassistantclient.cpp.

References d, dpointers, proc, QProcess::Running, QProcess::state(), and QProcess::terminate().

00209 {
00210     if ( proc->state() == QProcess::Running )
00211         proc->terminate();
00212 
00213     if( dpointers ) {
00214         QAssistantClientPrivate *d = (*dpointers)[ this ];
00215         if ( d ) {
00216             dpointers->remove(this);
00217             delete d;
00218             if( dpointers->isEmpty() ) {
00219                 delete dpointers;
00220                 dpointers = 0;
00221             }
00222         }
00223     }
00224 }

Here is the call graph for this function:

Member Function Documentation

bool QAssistantClient::isOpen ( ) const

Definition at line 347 of file qassistantclient.cpp.

References opened.

00348 {
00349     return opened;
00350 }

void QAssistantClient::setArguments ( const QStringList & arguments )

Sets the command line 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.

See also:: {assistant-manual.htmlcustomizing-qt-assistant}{Customizing Qt Assistant}

Definition at line 401 of file qassistantclient.cpp.

References d, and data.

Referenced by MainWindow::initializeAssistant().

00402 {
00403     QAssistantClientPrivate *d = data( this, true );
00404     d->arguments = args;
00405 }

void QAssistantClient::openAssistant ( ) [virtual, slot]

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 {assistant-manual.htmlprofiles}{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.

See also:: showPage(), assistantOpened()

Definition at line 240 of file qassistantclient.cpp.

References QList< T >::append(), assistantCommand, QObject::connect(), d, data, QString::isEmpty(), pageBuffer, proc, readPort(), QProcess::Running, SIGNAL, SLOT, QProcess::start(), and QProcess::state().

Referenced by showPage().

00241 {
00242     if ( proc->state() == QProcess::Running )
00243         return;
00244 
00245     QStringList args;
00246     args.append("-server");
00247     if( !pageBuffer.isEmpty() ) {
00248         args.append( "-file" );
00249         args.append( pageBuffer );
00250     }
00251 
00252     QAssistantClientPrivate *d = data( this );
00253     if( d ) {
00254         QStringList::ConstIterator it = d->arguments.constBegin();
00255         while( it!=d->arguments.constEnd() ) {
00256             args.append( *it );
00257             ++it;
00258         }
00259     }
00260 
00261     connect( proc, SIGNAL(readyReadStandardOutput()),
00262         this, SLOT(readPort()) );
00263 
00264     proc->start(assistantCommand, args);
00265 }

void QAssistantClient::closeAssistant ( ) [virtual, slot]

Closes the Qt Assistant instance.

See also:: openAssistant(), assistantClosed()

Definition at line 300 of file qassistantclient.cpp.

References QObject::blockSignals(), QProcess::kill(), opened, proc, QProcess::terminate(), and QProcess::waitForFinished().

00301 {
00302     if ( !opened )
00303         return;
00304 
00305     bool blocked = proc->blockSignals(true);
00306     proc->terminate();
00307     if (!proc->waitForFinished(2000)) {
00308         // If the process hasn't died after 2 seconds,
00309         // we kill it, causing it to exit immediately.
00310         proc->kill();
00311     }
00312     proc->blockSignals(blocked);
00313 }

void QAssistantClient::showPage ( const QString & page ) [virtual, slot]

Brings Qt Assistant to the foreground showing the given page. The page parameter is a path to an HTML file (e.g., "/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.

See also:: openAssistant()

Definition at line 326 of file qassistantclient.cpp.

References QString::clear(), QProcess::NotRunning, openAssistant(), opened, pageBuffer, proc, socket, and QProcess::state().

Referenced by MainWindow::assistant(), FindFileDialog::help(), TrWindow::manual(), Launcher::showExampleDocumentation(), QDesignerActions::showHelp(), QPixelTool::showHelp(), and socketConnected().

00327 {
00328     if (opened) {
00329         QTextStream os( socket );
00330         os << page << "\n";
00331     } else {
00332         pageBuffer = page;
00333 
00334         if (proc->state() == QProcess::NotRunning) {
00335             openAssistant();
00336             pageBuffer.clear();
00337             return;
00338         }
00339     }
00340 }

void QAssistantClient::assistantOpened ( ) [signal]

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

See also:: openAssistant(), showPage()

Referenced by socketConnected().

void QAssistantClient::assistantClosed ( ) [signal]

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.

See also:: closeAssistant()

Referenced by socketConnectionClosed().

void QAssistantClient::error ( const QString & message ) [signal]

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 message provides an explanation of the error.

Referenced by procError(), QAssistantClient(), readPort(), readStdError(), and socketError().

void QAssistantClient::socketConnected ( ) [private, slot]

Definition at line 352 of file qassistantclient.cpp.

References assistantOpened(), emit, QString::isEmpty(), opened, pageBuffer, and showPage().

Referenced by QAssistantClient().

00353 {
00354     opened = true;
00355     if ( !pageBuffer.isEmpty() )
00356         showPage( pageBuffer );
00357     emit assistantOpened();
00358 }

void QAssistantClient::socketConnectionClosed ( ) [private, slot]

Definition at line 360 of file qassistantclient.cpp.

References assistantClosed(), emit, and opened.

Referenced by QAssistantClient().

00361 {
00362     opened = false;
00363     emit assistantClosed();
00364 }

void QAssistantClient::readPort ( ) [private, slot]

Definition at line 282 of file qassistantclient.cpp.

References QAbstractSocket::connectToHost(), QObject::disconnect(), emit, error(), host, p, port, proc, QProcess::readAllStandardOutput(), SIGNAL, SLOT, and socket.

Referenced by openAssistant().

00283 {
00284     QString p = proc->readAllStandardOutput();
00285     quint16 port = p.toUShort();
00286     if ( port == 0 ) {
00287         emit error( tr( "Cannot connect to Qt Assistant." ) );
00288         return;
00289     }
00290     socket->connectToHost( host, port );
00291     disconnect( proc, SIGNAL(readyReadStandardOutput()),
00292                 this, SLOT(readPort()) );
00293 }

void QAssistantClient::procError ( QProcess::ProcessError err ) [private, slot]

Definition at line 267 of file qassistantclient.cpp.

References QProcess::Crashed, emit, error(), and QProcess::FailedToStart.

Referenced by QAssistantClient().

00268 {
00269     switch (err)
00270     {
00271     case QProcess::FailedToStart:
00272         emit error( tr( "Failed to start Qt Assistant." ) );
00273         break;
00274     case QProcess::Crashed:
00275         emit error( tr( "Qt Assistant crashed." ) );
00276         break;
00277     default:
00278         emit error( tr( "Error while running Qt Assistant." ) );
00279     }
00280 }

void QAssistantClient::socketError ( ) [private, slot]

Definition at line 366 of file qassistantclient.cpp.

References QAbstractSocket::ConnectionRefusedError, emit, QAbstractSocket::error(), error(), QAbstractSocket::HostNotFoundError, QAbstractSocket::RemoteHostClosedError, and socket.

Referenced by QAssistantClient().

00367 {
00368     QAbstractSocket::SocketError err = socket->error();
00369     if (err == QTcpSocket::ConnectionRefusedError)
00370         emit error( tr( "Could not connect to Assistant: Connection refused" ) );
00371     else if (err == QTcpSocket::HostNotFoundError)
00372         emit error( tr( "Could not connect to Assistant: Host not found" ) );
00373     else if (err != QTcpSocket::RemoteHostClosedError)
00374         emit error( tr( "Communication error" ) );
00375 }

void QAssistantClient::readStdError ( ) [private, slot]

Definition at line 377 of file qassistantclient.cpp.

References emit, error(), QString::isEmpty(), proc, QProcess::readAllStandardError(), and QString::simplified().

Referenced by QAssistantClient().

00378 {
00379     QString errmsg = proc->readAllStandardError();
00380 
00381     if (!errmsg.isEmpty())
00382         emit error( errmsg.simplified() );
00383 }


Public Slots
virtual void	openAssistant ()
virtual void	closeAssistant ()
virtual void	showPage (const QString &page)
Signals
void	assistantOpened ()
void	assistantClosed ()
void	error (const QString &msg)
Public Member Functions
	QAssistantClient (const QString &path, QObject *parent=0)
	~QAssistantClient ()
bool	isOpen () const
void	setArguments (const QStringList &args)
Private Slots
void	socketConnected ()
void	socketConnectionClosed ()
void	readPort ()
void	procError (QProcess::ProcessError err)
void	socketError ()
void	readStdError ()
Private Attributes
QTcpSocket *	socket
QProcess *	proc
quint16	port
QString	host
QString	assistantCommand
QString	pageBuffer
bool	opened

QAssistantClient Class Reference

Detailed Description

Public Slots

Signals

Public Member Functions

Private Slots

Private Attributes

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation