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
        Irc::registerMetaTypes();
        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<IrcCommand>(uri, 3, 0, "IrcCommand");
        qmlRegisterType<IrcConnection>(uri, 3, 0, "IrcConnection");
        qmlRegisterUncreatableType<IrcMessage>(uri, 3, 0, "IrcMessage", "Cannot create an instance of IrcMessage. Use IrcConnection::messageReceived() signal instead.");
        qmlRegisterUncreatableType<IrcNetwork>(uri, 3, 0, "IrcNetwork", "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", "Cannot create an instance of IrcPalette. Use IrcTextFormat::palette property instead.");
        qmlRegisterType<IrcCompleter>(uri, 3, 1, "IrcCompleter");

Connecting to IRC

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

IrcConnection {
    id: freenode
    host: "irc.freenode.net"
    userName: "communi"
    nickName: "Communi" + Math.round(Math.random() * 9999)
    realName: "Communi QML example"
}

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 }

IrcConnection {
    onConnected: {
        var cmd = command.createJoin(channel)
        sendCommand(cmd)
    }
}

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.

IrcBufferModel {
    id: bufferModel
    connection: freenode
}

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.

IrcBuffer {
    id: serverBuffer
    name: freenode.displayName
    Component.onCompleted: bufferModel.add(serverBuffer)
}

IrcBufferModel {
    id: bufferModel
    connection: freenode
    onMessageIgnored: serverBuffer.receiveMessage(message)
}

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.

IrcUserModel {
    id: userModel
    channel: currentBuffer.toChannel()
}

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.

IrcCommandParser {
    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...>");
    }
}