Skip to content

PythonQt.Qt.QIODevice

QIODevice

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

QIODevice provides both a common implementation and an abstract interface for devices that support reading and writing of blocks of data, such as QFile, QBuffer and QTcpSocket. QIODevice is abstract and cannot be instantiated, but it is common to use the interface it defines to provide device-independent I/O features. For example, Qt's XML classes operate on a QIODevice pointer, allowing them to be used with various devices (such as files and buffers).

Before accessing the device, open() must be called to set the correct OpenMode (such as ReadOnly or ReadWrite). You can then write to the device with write() or putChar(), and read by calling either read(), readLine(), or readAll(). Call close() when you are done with the device.

QIODevice distinguishes between two types of devices: random-access devices and sequential devices.

  • Random-access devices support seeking to arbitrary positions using seek(). The current position in the file is available by calling pos(). QFile and QBuffer are examples of random-access devices.
  • Sequential devices don't support seeking to arbitrary positions. The data must be read in one pass. The functions pos() and size() don't work for sequential devices. QTcpSocket and QProcess are examples of sequential devices.

You can use isSequential() to determine the type of device.

QIODevice emits readyRead() when new data is available for reading; for example, if new data has arrived on the network or if additional data is appended to a file that you are reading from. You can call bytesAvailable() to determine the number of bytes that are currently available for reading. It's common to use bytesAvailable() together with the readyRead() signal when programming with asynchronous devices such as QTcpSocket, where fragments of data can arrive at arbitrary points in time. QIODevice emits the bytesWritten() signal every time a payload of data has been written to the device. Use bytesToWrite() to determine the current amount of data waiting to be written.

Certain subclasses of QIODevice, such as QTcpSocket and QProcess, are asynchronous. This means that I/O functions such as write() or read() always return immediately, while communication with the device itself may happen when control goes back to the event loop. QIODevice provides functions that allow you to force these operations to be performed immediately, while blocking the calling thread and without entering the event loop. This allows QIODevice subclasses to be used without an event loop, or in a separate thread:

  • waitForReadyRead() - This function suspends operation in the calling thread until new data is available for reading.
  • waitForBytesWritten() - This function suspends operation in the calling thread until one payload of data has been written to the device.
  • waitFor....() - Subclasses of QIODevice implement blocking functions for device-specific operations. For example, QProcess has a function called waitForStarted() which suspends operation in the calling thread until the process has started.

Calling these functions from the main, GUI thread, may cause your user interface to freeze. Example:

QProcess gzip;
gzip.start("gzip", QStringList() << "-c");
if (!gzip.waitForStarted())
    return false;

gzip.write("uncompressed data");

QByteArray compressed;
while (gzip.waitForReadyRead())
    compressed += gzip.readAll();

By subclassing QIODevice, you can provide the same interface to your own I/O devices. Subclasses of QIODevice are only required to implement the protected readData() and writeData() functions. QIODevice uses these functions to implement all its convenience functions, such as getChar(), readLine() and write(). QIODevice also handles access control for you, so you can safely assume that the device is opened in write mode if writeData() is called.

Some subclasses, such as QFile and QTcpSocket, are implemented using a memory buffer for intermediate storing of data. This reduces the number of required device accessing calls, which are often very slow. Buffering makes functions like getChar() and putChar() fast, as they can operate on the memory buffer instead of directly on the device itself. Certain I/O operations, however, don't work well with a buffer. For example, if several users open the same device and read it character by character, they may end up reading the same data when they meant to read a separate chunk each. For this reason, QIODevice allows you to bypass any buffering by passing the Unbuffered flag to open(). When subclassing QIODevice, remember to bypass any buffer you may use when the device is open in Unbuffered mode.

Usually, the incoming data stream from an asynchronous device is fragmented, and chunks of data can arrive at arbitrary points in time. To handle incomplete reads of data structures, use the transaction mechanism implemented by QIODevice. See startTransaction() and related functions for more details.

Some sequential devices support communicating via multiple channels. These channels represent separate streams of data that have the property of independently sequenced delivery. Once the device is opened, you can determine the number of channels by calling the readChannelCount() and writeChannelCount() functions. To switch between channels, call setCurrentReadChannel() and setCurrentWriteChannel(), respectively. QIODevice also provides additional signals to handle asynchronous communication on a per-channel basis.

Source: https://doc.qt.io/archives/qt-5.15/qiodevice.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
Append attribute Any (shared captured text)
NotOpen attribute Any (shared captured text)
OpenMode attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
OpenModeFlag attribute type Convert a number or string to an integer, or return 0 if no arguments are given. (shared captured text)
ReadOnly attribute Any (shared captured text)
ReadWrite attribute Any (shared captured text)
Text attribute Any (shared captured text)
Truncate attribute Any (shared captured text)
Unbuffered attribute Any (shared captured text)
WriteOnly attribute Any (shared captured text)
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
aboutToClose function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QIODevice.aboutToClose; argument details are not documented.
atEnd function (self) -> bool X.atEnd() -> bool (shared captured text)
blockSignals function (self, b: Any) -> bool X.blockSignals(b) -> bool (shared captured text)
bytesAvailable function (self) -> int X.bytesAvailable() -> int (shared captured text)
bytesToWrite function (self) -> int X.bytesToWrite() -> int (shared captured text)
bytesWritten function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QIODevice.bytesWritten; argument details are not documented.
canReadLine function (self) -> bool X.canReadLine() -> bool (shared captured text)
channelBytesWritten function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QIODevice.channelBytesWritten; argument details are not documented.
channelReadyRead function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QIODevice.channelReadyRead; argument details are not documented.
childEvent function (self, event: Any) -> Any (shared captured text)
children function (self) -> tuple X.children() -> tuple (shared captured text)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
close function (self) -> None First emits [aboutToClose](https://doc.qt.io/archives/qt-5.15/qiodevice.html#aboutToClose)(), then closes the device and sets its… (shared captured text)
connect function (self, signal: Any, receiver: Any, slot: Any, type: Any) -> bool X.connect(signal, receiver, slot, type) -> bool (shared captured text)
customEvent function (self, event: Any) -> Any (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
deleteLater function (self) -> Any (shared captured text)
destroyed function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QIODevice.destroyed; argument details are not documented.
disconnect function (self, signal: Any, receiver: Any, slot: Any) -> bool X.disconnect(signal, receiver, slot) -> bool (shared captured text)
dumpObjectInfo function (self) -> Any (shared captured text)
dumpObjectTree function (self) -> Any (shared captured text)
dynamicPropertyNames function (self) -> Any (shared captured text)
errorString function (self) -> str X.errorString() -> str (shared captured text)
event function (self, event: Any) -> bool X.event(event) -> bool (shared captured text)
eventFilter function (self, watched: Any, event: Any) -> bool X.eventFilter(watched, event) -> bool (shared captured text)
findChild function (self, type: Any, name: Any) -> Any X.findChild(type, name) -> PythonQt.private.QObject (shared captured text)
findChildren function (self, type: Any, name: Any) -> tuple X.findChildren(type, name) -> tuple (shared captured text)
getChar function (self, c: str) -> bool X.getChar(c) -> bool (shared captured text)
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
installEventFilter function (self, filterObj: Any) -> Any (shared captured text)
isOpen function (self) -> bool X.isOpen() -> bool (shared captured text)
isReadable function (self) -> bool X.isReadable() -> bool (shared captured text)
isSequential function (self) -> bool X.isSequential() -> bool (shared captured text)
isSignalConnected function (self, signal: Any) -> bool X.isSignalConnected(signal) -> bool (shared captured text)
isTextModeEnabled function (self) -> bool X.isTextModeEnabled() -> bool (shared captured text)
isWidgetType function (self) -> bool X.isWidgetType() -> bool (shared captured text)
isWindowType function (self) -> bool X.isWindowType() -> bool (shared captured text)
isWritable function (self) -> bool X.isWritable() -> bool (shared captured text)
killTimer function (self, id: Any) -> Any (shared captured text)
metaObject function (self) -> Any X.metaObject() -> PythonQt.QtCore.QMetaObject (shared captured text)
moveToThread function (self, thread: Any) -> Any (shared captured text)
objectName attribute Any (shared captured text)
objectNameChanged function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QIODevice.objectNameChanged; argument details are not documented.
open function (self, mode: Any) -> bool X.open(mode) -> bool (shared captured text)
openMode function (self) -> Any Returns the mode in which the device has been opened; i.e. (shared captured text)
parent function (self) -> Any X.parent() -> PythonQt.private.QObject (shared captured text)
peek function (self, maxlen: int) -> Any X.peek(maxlen) -> PythonQt.QtCore.QByteArray (shared captured text)
pos function (self) -> int X.pos() -> int (shared captured text)
property function (self, name: Any) -> Any X.property(name) -> object (shared captured text)
putChar function (self, c: int) -> bool X.putChar(c) -> bool (shared captured text)
read function (self, maxlen: int) -> Any X.read(maxlen) -> PythonQt.QtCore.QByteArray (shared captured text)
readAll function (self) -> Any X.readAll() -> PythonQt.QtCore.QByteArray (shared captured text)
readChannelFinished function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QIODevice.readChannelFinished; argument details are not documented.
readData function (self, data: str, maxlen: int) -> int X.readData(data, maxlen) -> int (shared captured text)
readLine function (self, maxlen: int) -> Any X.readLine(maxlen) -> PythonQt.QtCore.QByteArray (shared captured text)
readLineData function (self, data: str, maxlen: int) -> int X.readLineData(data, maxlen) -> int (shared captured text)
readyRead function (self, *args: Any, **kwargs: Any) -> Any Native PythonQt.Qt.QIODevice.readyRead; argument details are not documented.
removeEventFilter function (self, obj: Any) -> Any (shared captured text)
reset function (self) -> bool X.reset() -> bool (shared captured text)
seek function (self, pos: int) -> bool X.seek(pos) -> bool (shared captured text)
sender function (self) -> Any X.sender() -> PythonQt.private.QObject (shared captured text)
senderSignalIndex function (self) -> int X.senderSignalIndex() -> int (shared captured text)
setErrorString function (self, errorString: str) -> None Sets the human readable description of the last device error that occurred to str. (shared captured text)
setObjectName function (self, name: Any) -> Any (shared captured text)
setOpenMode function (self, openMode: Any) -> None Sets the [OpenMode](https://doc.qt.io/archives/qt-5.15/qiodevice.html#OpenModeFlag-enum) of the device to openMode. (shared captured text)
setParent function (self, parent: Any) -> Any (shared captured text)
setProperty function (self, name: Any, value: Any) -> bool X.setProperty(name, value) -> bool (shared captured text)
setTextModeEnabled function (self, enabled: bool) -> None If enabled is true, this function sets the [Text](https://doc.qt.io/archives/qt-5.15/qiodevice.html#OpenModeFlag-enum) flag on the device; otherwise the… (shared captured text)
signalsBlocked function (self) -> bool X.signalsBlocked() -> bool (shared captured text)
size function (self) -> int X.size() -> int (shared captured text)
startTimer function (self, interval: Any, timerType: Any) -> int X.startTimer(interval, timerType) -> int (shared captured text)
thread function (self) -> Any (shared captured text)
timerEvent function (self, event: Any) -> Any (shared captured text)
tr function (self, text: Any, ambig: Any, n: Any) -> str X.tr(text, ambig, n) -> str (shared captured text)
ungetChar function (self, c: int) -> None Puts the character c back into the device, and decrements the current position unless the position is 0. (shared captured text)
waitForBytesWritten function (self, msecs: int) -> bool X.waitForBytesWritten(msecs) -> bool (shared captured text)
waitForReadyRead function (self, msecs: int) -> bool X.waitForReadyRead(msecs) -> bool (shared captured text)
write function (self, data: Any) -> int X.write(data) -> int (shared captured text)
writeData function (self, data: str, len: int) -> int X.writeData(data, len) -> int (shared captured text)