SynchronousProcess Class | Extending Qt Creator Manual

Extending Qt Creator Manual | SynchronousProcess

Extending Qt Creator Manual 4.6.0

# SynchronousProcess Class

(Utils::SynchronousProcess)

The SynchronousProcess class runs a synchronous process in its own event loop that blocks only user input events. Thus, it allows for the GUI to repaint and append output to log windows. More...

Header: | #include <SynchronousProcess>

- List of all members, including inherited members

## Public Types

enum | Flags { UnixTerminalDisabled }

## Public Functions

| SynchronousProcess()
virtual | ~SynchronousProcess()
QTextCodec * | codec() const
QStringList | environment() const
ExitCodeInterpreter | exitCodeInterpreter() const
unsigned | flags() const
QProcess::ProcessChannelMode | processChannelMode() const
QProcessEnvironment | processEnvironment() const
SynchronousProcessResponse | run(const QString &binary, const QStringList &args)
SynchronousProcessResponse | runBlocking(const QString &binary, const QStringList &args)
void | setCodec(QTextCodec *c)
void | setEnvironment(const QStringList &)
void | setExitCodeInterpreter(const ExitCodeInterpreter &interpreter)
void | setFlags(unsigned)
void | setProcessChannelMode(QProcess::ProcessChannelMode m)
void | setProcessEnvironment(const QProcessEnvironment &environment)
void | setStdErrBufferedSignalsEnabled(bool)
void | setStdOutBufferedSignalsEnabled(bool)
void | setTimeOutMessageBoxEnabled(bool)
void | setTimeoutS(int timeoutS)
void | setWorkingDirectory(const QString &workingDirectory)
bool | stdErrBufferedSignalsEnabled() const
bool | stdOutBufferedSignalsEnabled() const
bool | timeOutMessageBoxEnabled() const
int | timeoutS() const
QString | workingDirectory() const

## Public Slots

bool | terminate()

## Signals

void | stdErrBuffered(const QString &lines, bool firstTime)
void | stdOutBuffered(const QString &lines, bool firstTime)

## Static Public Members

QSharedPointer<QProcess> | createProcess(unsigned flags)
QString | locateBinary(const QString &binary)
QString | locateBinary(const QString &path, const QString &binary)
QString | normalizeNewlines(const QString &text)
bool | readDataFromProcess(QProcess &p, int timeoutS, QByteArray *rawStdOut = 0, QByteArray *rawStdErr = 0, bool timeOutMessageBox = false)
bool | stopProcess(QProcess &p)

## Detailed Description

The SynchronousProcess class runs a synchronous process in its own event loop that blocks only user input events. Thus, it allows for the GUI to repaint and append output to log windows.

The stdOut(), stdErr() signals are emitted unbuffered as the process writes them.

The stdOutBuffered(), stdErrBuffered() signals are emitted with complete lines based on the '\n' marker if they are enabled using stdOutBufferedSignalsEnabled()/setStdErrBufferedSignalsEnabled(). They would typically be used for log windows.

There is a timeout handling that takes effect after the last data have been read from stdout/stdin (as opposed to waitForFinished(), which measures time since it was invoked). It is thus also suitable for slow processes that continously output data (like version system operations).

The property timeOutMessageBoxEnabled influences whether a message box is shown asking the user if they want to kill the process on timeout (default: false).

There are also static utility functions for dealing with fully synchronous processes, like reading the output with correct timeout handling.

Caution: This class should NOT be used if there is a chance that the process triggers opening dialog boxes (for example, by file watchers triggering), as this will cause event loop problems.

## Member Type Documentation

### enum SynchronousProcess::Flags

## Member Function Documentation

### SynchronousProcess::SynchronousProcess()

Default constructs an instance of SynchronousProcess.

### `[virtual]` SynchronousProcess::~SynchronousProcess()

Destroys the instance of SynchronousProcess. The destructor is virtual.

### QTextCodec *SynchronousProcess::codec() const

See also setCodec().

### `[static]` QSharedPointer<QProcess> SynchronousProcess::createProcess(unsigned flags)

### QStringList SynchronousProcess::environment() const

See also setEnvironment().

### ExitCodeInterpreter SynchronousProcess::exitCodeInterpreter() const

See also setExitCodeInterpreter().

### unsigned SynchronousProcess::flags() const

See also setFlags().

### `[static]` QString SynchronousProcess::locateBinary(const QString &binary)

### `[static]` QString SynchronousProcess::locateBinary(const QString &path, const QString &binary)

### `[static]` QString SynchronousProcess::normalizeNewlines(const QString &text)

### QProcess::ProcessChannelMode SynchronousProcess::processChannelMode() const

See also setProcessChannelMode().

### QProcessEnvironment SynchronousProcess::processEnvironment() const

See also setProcessEnvironment().

### `[static]` bool SynchronousProcess::readDataFromProcess(QProcess &p, int timeoutS, QByteArray *rawStdOut = 0, QByteArray *rawStdErr = 0, bool timeOutMessageBox = false)

### SynchronousProcessResponse SynchronousProcess::run(const QString &binary, const QStringList &args)

### SynchronousProcessResponse SynchronousProcess::runBlocking(const QString &binary, const QStringList &args)

### void SynchronousProcess::setCodec(QTextCodec *c)

See also codec().

### void SynchronousProcess::setEnvironment(const QStringList &)

See also environment().

### void SynchronousProcess::setExitCodeInterpreter(const ExitCodeInterpreter &interpreter)

See also exitCodeInterpreter().

### void SynchronousProcess::setFlags(unsigned)

See also flags().

### void SynchronousProcess::setProcessChannelMode(QProcess::ProcessChannelMode m)

See also processChannelMode().

### void SynchronousProcess::setProcessEnvironment(const QProcessEnvironment &environment)

See also processEnvironment().

### void SynchronousProcess::setStdErrBufferedSignalsEnabled(bool)

See also stdErrBufferedSignalsEnabled().

### void SynchronousProcess::setStdOutBufferedSignalsEnabled(bool)

See also stdOutBufferedSignalsEnabled().

### void SynchronousProcess::setTimeOutMessageBoxEnabled(bool)

See also timeOutMessageBoxEnabled().

### void SynchronousProcess::setTimeoutS(int timeoutS)

See also timeoutS().

### void SynchronousProcess::setWorkingDirectory(const QString &workingDirectory)

See also workingDirectory().

### `[signal]` void SynchronousProcess::stdErrBuffered(const QString &lines, bool firstTime)

### bool SynchronousProcess::stdErrBufferedSignalsEnabled() const

See also setStdErrBufferedSignalsEnabled().

### `[signal]` void SynchronousProcess::stdOutBuffered(const QString &lines, bool firstTime)

### bool SynchronousProcess::stdOutBufferedSignalsEnabled() const

See also setStdOutBufferedSignalsEnabled().

### `[static]` bool SynchronousProcess::stopProcess(QProcess &p)

### `[slot]` bool SynchronousProcess::terminate()

### bool SynchronousProcess::timeOutMessageBoxEnabled() const

See also setTimeOutMessageBoxEnabled().

### int SynchronousProcess::timeoutS() const

See also setTimeoutS().

### QString SynchronousProcess::workingDirectory() const

See also setWorkingDirectory().