Communi  3.7.0
A cross-platform IRC framework written with Qt
Loading...
Searching...
No Matches
QML compatibility

Communi strives for full QML support. The property-based APIs have been designed QML compatibility in mind. Almost all the types can be registered to QML and used as is.

A ready-made QML plugin is also provided for convenience. The plugin does QML type registration and is made available via the following import:

import Communi 3.0

Type registration

The following snippet illustrates how the Communi QML plugin does the type registration. The same can be done manually in application code to avoid the need of deploying the Communi QML plugin.

// IrcCore
qmlRegisterType<Irc>(uri, 3, 0, "Irc");
qmlRegisterType<Irc>(uri, 3, 2, "Irc");
qmlRegisterType<Irc>(uri, 3, 3, "Irc");
qmlRegisterType<Irc>(uri, 3, 4, "Irc");
qmlRegisterType<Irc>(uri, 3, 5, "Irc");
qmlRegisterType<Irc>(uri, 3, 6, "Irc");
qmlRegisterType<Irc>(uri, 3, 7, "Irc");
qmlRegisterType<IrcCommand>(uri, 3, 0, "IrcCommand");
qmlRegisterType<IrcConnection>(uri, 3, 0, "IrcConnection");
qmlRegisterUncreatableType<IrcMessage>(uri, 3, 0, "IrcMessage", QStringLiteral("Cannot create an instance of IrcMessage. Use IrcConnection::messageReceived() signal instead."));
qmlRegisterUncreatableType<IrcNetwork>(uri, 3, 0, "IrcNetwork", QStringLiteral("Cannot create an instance of IrcNetwork. Use IrcConnection::network property instead."));
qmlRegisterType<IrcQmlFilter>(uri, 3, 0, "IrcMessageFilter");
qmlRegisterType<IrcQmlFilter>(uri, 3, 0, "IrcCommandFilter");
qmlRegisterType<IrcQmlFilter>(uri, 3, 0, "IrcFilter");
// IrcModel
qmlRegisterType<IrcBuffer>(uri, 3, 0, "IrcBuffer");
qmlRegisterType<IrcBufferModel>(uri, 3, 0, "IrcBufferModel");
qmlRegisterType<IrcChannel>(uri, 3, 0, "IrcChannel");
qmlRegisterType<IrcUser>(uri, 3, 0, "IrcUser");
qmlRegisterType<IrcUserModel>(uri, 3, 0, "IrcUserModel");
// IrcUtil
qmlRegisterType<IrcCommandParser>(uri, 3, 0, "IrcCommandParser");
qmlRegisterType<IrcLagTimer>(uri, 3, 0, "IrcLagTimer");
qmlRegisterType<IrcTextFormat>(uri, 3, 0, "IrcTextFormat");
qmlRegisterUncreatableType<IrcPalette>(uri, 3, 0, "IrcPalette", QStringLiteral("Cannot create an instance of IrcPalette. Use IrcTextFormat::palette property instead."));
qmlRegisterType<IrcCompleter>(uri, 3, 1, "IrcCompleter");
static Q_INVOKABLE void registerMetaTypes()
Definition irc.cpp:199

Connecting to IRC

In order to connect to IRC in QML, declare an IrcConnection instance, set the desired properties, and call connection.open().

id: libera
host: "irc.libera.chat"
userName: "communi"
nickName: "Communi" + Math.round(Math.random() * 9999)
realName: "Communi QML example"
}
Provides means to establish a connection to an IRC server.
Definition ircconnection.h:49

Sending commands

Even though the IrcCommand::createXxx() methods are static, QML does not provide a way to call them without an IrcCommand instance. Thus, in order to create and send commands, declare an instance of IrcCommand, call any createXxx() method to create a command, and finally send it via IrcCommand::sendCommand().

IrcCommand { id: command }
onConnected: {
var cmd = command.createJoin(channel)
sendCommand(cmd)
}
}
Provides the most common commands.
Definition irccommand.h:45

Channels and queries

In order to keep track of channels and queries, declare an instance of IrcBufferModel. Notice that it can be used directly as a data model for QML types such as ListView and Repeater.

id: bufferModel
connection: libera
}
Keeps track of buffers.
Definition ircbuffermodel.h:48

IrcBufferModel creates channel and query buffers automatically when the client joins channels and receives private messages, respectively.

A typical IRC client has a special server buffer for messages that are not targeted to any specific channel or query. This can be easily achieved by declaring an instance of IrcBuffer and forwarding the messages ignored by IrcBufferModel to it.

id: serverBuffer
name: libera.displayName
Component.onCompleted: bufferModel.add(serverBuffer)
}
id: bufferModel
connection: libera
onMessageIgnored: serverBuffer.receiveMessage(message)
}
void receiveMessage(IrcMessage *message)
Definition ircbuffermodel.cpp:1045
Keeps track of buffer status.
Definition ircbuffer.h:50

Channel users

In order to keep track of channel users, create an instance of IrcUserModel. It can be also used directly as a data model for QML types such as ListView and Repeater.

id: userModel
channel: currentBuffer.toChannel()
}
Keeps track of channel users.
Definition ircusermodel.h:46

Parsing user commands

IrcCommandParser helps with parsing commands from user input. In order to take it in use, declare an instance of IrcCommandParser and introduce the desired commands.

Notice that commands are often context sensitive. While some command may accept an optional parameter that is filled up with the current target (channel/query) name when absent, another command may always inject the current target name as a certain parameter. Therefore IrcCommandParser must be kept up-to-date with the current target and the list of channels.

id: parser
triggers: ["/"]
target: currentBuffer.title
channels: bufferModel.channels
Component.onCompleted: {
parser.addCommand(IrcCommand.Join, "JOIN <#channel> (<key>)");
parser.addCommand(IrcCommand.Part, "PART (<#channel>) (<message...>)");
parser.addCommand(IrcCommand.Kick, "KICK (<#channel>) <nick> (<reason...>)");
parser.addCommand(IrcCommand.CtcpAction, "ME [target] <message...>");
}
}
Parses commands from user input.
Definition irccommandparser.h:43
@ Kick
A kick command (KICK) is used to forcibly remove a user from a channel.
Definition irccommand.h:66
@ Part
A part command (PART) causes the client to be removed from the channel.
Definition irccommand.h:75
@ Join
A join command (JOIN) is used to start listening a specific channel.
Definition irccommand.h:65
@ CtcpAction
A CTCP action command is used to send an action message to channels and users.
Definition irccommand.h:59