View source for Mbarcode Plugin Tutorial - Qt SDK

This tutorial will try to guide you through the process of creating an [[MBarcode]] plugin using the Nokia Qt SDK. The aim of this tutorial is to give you the knowledge necessary to create a basic plugin for [[MBarcode]] without having to rely on Scratchbox.

If you are looking to develop a plugin for mBarcode using Scratchbox then please see this tutorial: [[Mbarcode_Plugin_Tutorial]]


== Prerequisites ==
In this tutorial we'll be using Qt together with C++ to connect to the mBarcode plugin framework. Unlike the other tutorial this one is aimed at using the Nokia Qt SDK. This can be downloaded from Nokia's website at [http://qt.nokia.com/downloads qt.nokia.com/downloads]

You must have:
 * Nokia Qt SDK [http://qt.nokia.com/downloads qt.nokia.com/downloads]
 * An N900 (may work on older tablets as well)
 * A linux OS (haven't tested this on Windows but it would probably work with a few tweaks)
 * Some basic C++ knowledge, though you can probably do this without any

== Initial Setup ==
To start with you will need to install the Nokia Qt SDK, this process is very self explanatory and easy to follow. Just make sure you install the correct version of the SDK, it will have Qt Simulator and the Maemo libraries bundled with it. Provided you download the SDK from the above link ([http://qt.nokia.com qt.nokia.com]) you shouldn't have any problems.

== Getting the required headers ==
Since the Nokia Qt SDK doesn't currently support installing packages in any easy manner the easiest way to do this would be to install "mbarcode-dev" on your N900 and then copying the headers. This can be done by opening a terminal (Ctrl + Shift + X) and typing the following:
<blockquote>
sudo gainroot
apt-get install mbarcode-dev
cp /usr/include/mbarcode-qt/* /home/user/MyDocs/
</blockquote>
That should copy the required header files to your MyDocs directory on the N900, which you can then access by putting it into Mass Storage mode and copying the header files. You should get the following:
* maemobarcodewindow.h
* pluginaction.h
* plugininterfaces.h
These files then need to be copied onto your development machine. Copy them into the following folders on your computer:
* /usr/include/mbarcode-qt/*
* /home/<your username>/QtSDK/Maemo/sysroots/<the only folder>/usr/include/mbarcode-qt/*

== Creating the Project ==
To create the project, launch Qt Creator and click New Project. Select "Empty Qt Application" as the type (under "Other Project"). 
When asked make sure that you choose to include the versions of Qt for Maemo and the Qt Simulator. This will allow you to compile your plugin for your phone and eventually package it.

== Setting up your .PRO file ==
The .PRO file tells Qt what to do with your project, so that will be the first thing we are going to set up. The easiest way to do this is to open up your .PRO file and paste the following code into it (overwriting everything else)
<syntaxhighlight lang="text">
TEMPLATE = lib
CONFIG += plugin
INCLUDEPATH += /usr/include/mbarcode-qt

# Please do not modify the following two lines. Required for deployment.
include(deployment.pri)
qtcAddDeployment()
</syntaxhighlight>

== Setting up your Deployment Script ==

Next we are going to add our deployment script, this in necessary for creating the DEB file used to install your plugin.
Right click on your project's name in the left hand side of Qt Creator and choose "Add New". Choose "Text File" from the "General" category and name the file '''deployment.pri'''.
When that is done you just need to copy the following into your new file. Don't worry about what it does, it is a slightly modified version of the standard '''deployment.pri''' file created when you create a new Qt Mobile Application in Qt Creator.
<syntaxhighlight lang="text">

# checksum 0xfb0c version 0x30001
# This file was generated by an application wizard of Qt Creator.
# The code below handles deployment to Symbian and Maemo, aswell as copying
# of the application data to shadow build directories on desktop.
# It is recommended not to modify this file, since newer versions of Qt Creator
# may offer an updated version of it.

defineTest(qtcAddDeployment) {
for(deploymentfolder, DEPLOYMENTFOLDERS) {
    item = item$${deploymentfolder}
    itemsources = $${item}.sources
    $$itemsources = $$eval($${deploymentfolder}.source)
    itempath = $${item}.path
    $$itempath= $$eval($${deploymentfolder}.target)
    export($$itemsources)
    export($$itempath)
    DEPLOYMENT += $$item
}

MAINPROFILEPWD = $$PWD


maemo5 {
	installPrefix = /usr/share/mbarcode/plugins
    } 
    for(deploymentfolder, DEPLOYMENTFOLDERS) {
	item = item$${deploymentfolder}
	itemfiles = $${item}.files
	$$itemfiles = $$eval($${deploymentfolder}.source)
	itempath = $${item}.path
	$$itempath = $${installPrefix}/$$eval($${deploymentfolder}.target)
	export($$itemfiles)
	export($$itempath)
	INSTALLS += $$item
    }
    target.path = $${installPrefix}
    export(target.path)
    INSTALLS += target
}

export (INSTALLS)
export (DEPLOYMENT)
export (TARGET.EPOCHEAPSIZE)
export (TARGET.CAPABILITY)
export (LIBS)
export (QMAKE_EXTRA_TARGETS)
}
</syntaxhighlight>

The final step is to go back into your .PRO file and remove the line that reads:
<blockquote>
OTHER_FILES += \
    deployment.pri
</blockquote>

== Creating your Plugin ==
Now that you have created the files needed by Qt Creator for packaging your plugin we can start creating the actual plugin. To start off we are going to need to create a new C++ class. This is done in the same way as you created your '''deployment.pri''' file. Give it the name "PluginLogic" and click OK.


=== pluginlogic.h ===
Inside the pluginlogic.h file paste the following code. This will form the basic structure for our plugin and should give you a good idea of what we are going to do with it.

<syntaxhighlight lang="cpp">

#ifndef PLUGINLOGIC_H
#define PLUGINLOGIC_H


// Here we import the core Qt modules which we need for
// all our base classes, we also need to do this so that
// we can generate signals (needed to let mBarcode know
// that we are ready to process a barcode)
#include <QtCore>

// We also import the headers used by mBarcode. These will
// only appear if you have added the
// INCLUDEPATH += /usr/include/mbarcode-qt
// line to your PRO file.
#include "pluginaction.h"
#include "plugininterfaces.h"

class PluginLogic : public PluginAction
{
    Q_OBJECT

public:
    //This will form the constructor that handles initialization of your
    //plugin. In here you can created any refereces to databases or whatever
    //else you want access to in your plugin.
    PluginLogic(const PluginInterface *interface);

    // This is just a name that you are going to give to the plugin.
    // It won't actually be used anywhere
    QString getName() { return "Test Plugin"; }


    // This is the text that will show in the list as the title for the
    // plugin item. It can be used to show the plugin's name or alternatively
    // some information about the barcode.
    QString getText();



    // This acts as a handler for when the plugin's list item gets clicked on
    void clickAction(QWidget *parentWindow);

    // This gets the text that gets shown underneath the plugin's name. It is
    // useful for showing some instructions or giving an idea of what the plugin does.
    void getInformativeText();


signals:

    // This "signal" gets sent if this plugin thinks it can handle the barcode we are sending it
    void isReady();

private slots:

    // This function gets called when a barcode gets scanned.
    // In it we will decide whether our plugin can read it and if so
    // we will let mBarcode know. We can also do a bit of processing
    // here if we want to.
    void barcodeAnalysed(QString barcodeType, QString barcodeData);


private:

    // This variable is used to store the barcode type for use after a barcode
    // has been scanned. You don't technically need this but it tends to make
    // life easier to have access to it from places other than in the
    // barcodeAnalysed function.
    QString barcodeType;

    // Same idea as above, except this one stores the data that the barcode contained.
    QString barcodeData;
};

#endif // PLUGINLOGIC_H
</syntaxhighlight>

=== pluginlogic.cpp ===
We will also need to create the actual code that goes in our pluginlogic.cpp file. This code will do the work of the plugin. I am not going to add it here since using the header you should be able to create it easily enough. It will be added at a later stage though.

=== plugin.h ===
The next thing we will need for our plugin is the class that handles loading of the plugin files. This class we will call Plugin and should be created the same way you created "PluginLogic".
As with "pluginlogic.h" you just need to copy the following code into your header file:

<syntaxhighlight lang="cpp">

#ifndef PLUGIN_H
#define PLUGIN_H

// We need to import this since it is used to allow us access
// to Qt's SIGNALS and SLOTS.
#include <QObject>

// We also need to import the mBarcode plugin headers that we
// are using. Bear in mind that these won't appear unless you added
// INCLUDEPATH += /usr/include/mbarcode-qt
// to your PRO file.
#include "pluginaction.h"
#include "plugininterfaces.h"

// Finally, we also need to import our PluginLogic class since
// we are going to use that to do the actual heavy lifting...
#include "pluginlogic.h"

class Plugin : public QObject, public PluginInterface
{
    Q_OBJECT

    // This just lets Qt know that we are going to structure this
    // class in the same way as a PluginInterfaces class would be.
    // This allows mBarcode to assume that the behave the same way
    // and is the core of how the plugin framework works.
    Q_INTERFACES(PluginInterface)

public:
    // We will do all of our initialization work here, this gets called
    // the first time the plugin is loaded and its purpose is to load
    // all the plugin's actions and get them set up correctly.
    void initInterface(QWidget *parent);

    // This will return a list of all the plugin actions available within
    // this plugin library. This allows one plugin file to provide numerous
    // different plugins.
    QSet<PluginAction*> getPluginActions();

    // This is the name used to describe your plugin.
    // This name appears on the Plugins page of mBarcode
    QString getName() { return "My Plugin"; }

private:
    QWidget *parent;

    // We just use this list to store the list of plugin actions for access
    // later from the getPluginActions() function.
    QSet<PluginAction*> pluginActions;

};

#endif // PLUGIN_H
</syntaxhighlight>

=== plugin.cpp ===
And now we are almost at the final part of creating the plugin, this is where we add the code that initializes the plugin for use by mBarcode. You can copy the following code into it, just make sure to change the plugin name at the bottom to make sure you don't break something ;)

<syntaxhighlight lang="cpp">
// Obviously we need to import our header file...
#include "plugin.h"

// Here is our initialization function, in it we are going to
// do initialization for all of the plugin's features
void Plugin::initInterface(QWidget *parent)
{
    // First lets store the parent object for future reference.
    // In our plugin we won't be using this but it is a good idea
    // to store it regardless.
    this->parent = parent;

    // We need to create a new instance of our PluginLogic class
    // which we will be using.
    PluginLogic *logic = new PluginLogic(this);

    // Now we add our PluginLogic object to the list of available
    // plugin actions. If we don't do this then mBarcode won't realise
    // that our plugin actually can do anything so make sure you don't
    // forget it.
    pluginActions.insert(logic);

    // Now we need to create a signal handler for when a barcode gets
    // scanned. We would need to do this for each instance of our PluginLogic
    // class if we were providing more than one sub plugin.
    connect(parent, SIGNAL(barcodeAnalysedSignal(QString,QString)),
	    scanner, SLOT(barcodeAnalysed(QString,QString)));

    
}

// We need to implement this function to allow mBarcode to get the list of
// our plugins. If you don't mBarcode won't list your plugin, but worse Qt
// will get angry at your for not doing so (beacuse your header has this function
// declared in it)
QSet<PluginAction*> Plugin::getPluginActions() {
    
    // Of course we just need to return the list of actions.
    return pluginActions;
}

// Now for the final part, we let Qt know that this is a plugin.
// Just replace "my_plugin" with the name of your plugin and Qt will handle the rest.
Q_EXPORT_PLUGIN2(my_plugin, Plugin)
</syntaxhighlight>

== Packaging ==
Okay, now that our plugin is complete you can try compiling it. It should do so without any difficulty (provided you didn't break something). Once it has been built you will need to open up your project's folder and open the "qtc_packaging/debian_freemantle" folder. Inside this folder are the files that will be used to create your DEB file. You can read more about what they do [http://www.debian.org/doc/debian-policy/ch-controlfields.html here] but in the mean time I will try to give you a rough guide through. Basically you need to edit the '''control''' file to add information about your package. Simply change whatever needs changing (usually enclosed in &lt; and &gt;). You may also want to change the '''copyright''', '''README''' and '''changelog''' files. Do '''NOT''' edit '''rules''' or '''compat''' though.

Once you have edited the package's details to your liking go back into Qt Creator and choose Maemo as your build target. To do this simply click on the picture of a computer in the bottom left of the window and choose the Maemo option. When that is done click on the Build menu (top of the screen) and choose "Deploy <your plugin name>". This will cause Qt Creator to start building your application and when it is done it will try to send it to your phone. If your phone isn't connected (which I assume it isn't since you have been following this tutorial...you have haven't you?) it will fail on the last step. Don't worry, this is not a problem because if you open up your projects folder you should see a folder called '''<your plugin name>-build-maemo''' and inside that should be your shiny new DEB file.

Copy it onto your N900 and install it using dpkg like so:
<blockquote>
sudo gainroot
cd <the folder on your N900 where you have your deb file, usually /home/user/MyDocs>
dpkg -i <your deb file's name>
</blockquote>

The final step is to open up [[MBarcode]] and scan a barcode...with any luck your plugin will  show up and process the barcode.

--[[User:spartan563|spartan563]] 23:04, 20 May 2011 (UTC)