diff options
Diffstat (limited to 'src/libcommuni/doc/qml.dox')
| -rw-r--r-- | src/libcommuni/doc/qml.dox | 160 |
1 files changed, 160 insertions, 0 deletions
diff --git a/src/libcommuni/doc/qml.dox b/src/libcommuni/doc/qml.dox new file mode 100644 index 0000000..da46191 --- /dev/null +++ b/src/libcommuni/doc/qml.dox @@ -0,0 +1,160 @@ +/* + Copyright (C) 2008-2014 The Communi Project + + You may use this file under the terms of BSD license as follows: + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions are met: + * Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + * Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + * Neither the name of the copyright holder nor the names of its + contributors may be used to endorse or promote products derived + from this software without specific prior written permission. + + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND + ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED + WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR + ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; + LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS + SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. +*/ + +/*! + \page qml 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: + + \code + import Communi 3.0 + \endcode + + \section qml-type-registration 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. + + \snippet src/imports/qml2/plugin.cpp qml-register-types + + \section qml-connecting-to-irc Connecting to IRC + + In order to connect to IRC in QML, declare an IrcConnection instance, + set the desired properties, and call \ref IrcConnection::open() + "connection.open()". + + \code + IrcConnection { + id: freenode + host: "irc.freenode.net" + userName: "communi" + nickName: "Communi" + Math.round(Math.random() * 9999) + realName: "Communi QML example" + } + \endcode + + \section qml-sending-commands 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(). + + \code + IrcCommand { id: command } + + IrcConnection { + onConnected: { + var cmd = command.createJoin(channel) + sendCommand(cmd) + } + } + \endcode + + \section qml-channels-and-queries 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. + + \code + IrcBufferModel { + id: bufferModel + connection: freenode + } + \endcode + + 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. + + \code + IrcBuffer { + id: serverBuffer + name: freenode.displayName + Component.onCompleted: bufferModel.add(serverBuffer) + } + + IrcBufferModel { + id: bufferModel + connection: freenode + onMessageIgnored: serverBuffer.receiveMessage(message) + } + \endcode + + \section qml-channel-users 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. + + \code + IrcUserModel { + id: userModel + channel: currentBuffer.toChannel() + } + \endcode + + \section qml-parsing-user-commands 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. + + \code + 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...>"); + } + } + \endcode + */ |