Add an Example Applet Now Tux grins from your Taskbar ;)

4 files changed, 241 insertions, 0 deletions

diff --git a/examples/applet/config.in b/examples/applet/config.in
new file mode 100644
index 0000000..6ea55d3
--- a/dev/null
+++ b/examples/applet/config.in
@@ -0,0 +1,4 @@
+  config APPLET_EXAMPLE
+    boolean "Applet Example"
+    default "y"
+    depends ( LIBQPE || LIBQPE-X11 ) && EXAMPLES 
diff --git a/examples/applet/example.pro b/examples/applet/example.pro
new file mode 100644
index 0000000..3efd31e
--- a/dev/null
+++ b/examples/applet/example.pro
@@ -0,0 +1,16 @@
+CONFIG += warn_on qt
+ 
+TEMPLATE = lib
+DESTDIR = $(OPIEDIR)/plugins/applets
+TARGET  = example
+
+SOURCES = simpleimpl.cpp
+HEADERS = simpleimpl.h
+
+INCLUDEPATH += $(OPIEDIR)/include
+DEPENDSPATH += $(OPIEDIR)/include
+
+LIBS += -lqpe
+
+
+include ( $(OPIEDIR)/include.pro ) 
diff --git a/examples/applet/simpleimpl.cpp b/examples/applet/simpleimpl.cpp
new file mode 100644
index 0000000..981e0ab
--- a/dev/null
+++ b/examples/applet/simpleimpl.cpp
@@ -0,0 +1,149 @@
+#include <qlabel.h>
+#include <qpainter.h>
+#include <qmessagebox.h>
+
+#include <qpe/applnk.h> // for AppLnk
+#include <qpe/resource.h> // for Resource loading
+
+#include "simpleimpl.h"
+
+
+SimpleApplet::SimpleApplet(QWidget *parent)
+    : QWidget( parent,  "Simple Applet" ) {
+/*
+ * we will load an Image, scale it for the right usage
+ * remember your applet might be used by different
+ * resolutions.
+ * Then we will convert the image back to an Pixmap
+ * and draw this Pimxap. We need to use Image because its
+ * the only class that allows scaling.
+ */
+
+    QImage image = Resource::loadImage("Tux");
+    /*
+     * smooth scale to AppLnk smallIconSize for applest
+     * smallIconSize gets adjusted to the resolution
+     * so on some displays like SIMpad and a C-750 the smallIconSize
+     * is greater than on a iPAQ h3870
+     */
+    image = image.smoothScale(AppLnk::smallIconSize(), AppLnk::smallIconSize() );
+
+    /*
+     * now we need to convert the Image to a Pixmap cause these
+     * can be drawn more easily
+     */
+    m_pix = new QPixmap();
+    m_pix->convertFromImage( image );
+
+    /*
+     * Now we will say that we don't want to be bigger than our
+     * Pixmap
+     */
+    setFixedHeight(AppLnk::smallIconSize() );
+    setFixedWidth( AppLnk::smallIconSize() );
+
+}
+
+SimpleApplet::~SimpleApplet() {
+    delete m_pix;
+}
+
+
+/*
+ * here you would normal show or do something
+ * useful. If you want to show a widget at the top left
+ * of your icon you need to map your rect().topLeft() to
+ * global with mapToGlobal(). Then you might also need to
+ * move the widgets so it is visible
+ */
+void SimpleApplet::mousePressEvent(QMouseEvent* ) {
+    QMessageBox::information(this, tr("No action taken"),
+                             tr("<qt>This Plugin does not yet support anything usefule aye.</qt>"),
+                             QMessageBox::Ok );
+
+}
+
+void SimpleApplet::paintEvent( QPaintEvent* ) {
+    QPainter p(this);
+
+    /* simpy draw the pixmap from the start of this widget */
+    p.drawPixmap(0, 0,  *m_pix );
+}
+
+/*
+ * Here comes the implementation of the interface
+ */
+SimpleAppletImpl::SimpleAppletImpl() {
+}
+/* needed cause until it is only pure virtual */
+SimpleAppletImpl::~SimpleAppletImpl() {
+}
+
+/*
+ * For the taskbar interface return a Widget
+ */
+QWidget* SimpleAppletImpl::applet( QWidget* parent ) {
+    /* ownership has the parent */
+    return new SimpleApplet( parent );
+}
+
+/*
+ * A small hint where the Applet Should be displayed
+ */
+int SimpleAppletImpl::position()const {
+    return 1;
+}
+
+
+/*
+ * Now the important QUnkownInterface method without
+ * this one your applet won't load
+ * @param uuid The uuid of the interface
+ * @param iface The pointer to the interface ptr
+ */
+QRESULT SimpleAppletImpl::queryInterface( const QUuid& uuid, QUnknownInterface** iface) {
+    /* set the pointer to the interface to 0 */
+    *iface = 0;
+
+    /*
+     * we check if we support the requested interface
+     * and then assign to the pointer.
+     * You may alos create another interface here so
+     * *iface = this is only in this simple case true you
+     * could also support more interfaces.
+     * But this example below is the most common use.
+     * Now the caller knows that the Interface Pointer
+     * is valid and the interface supported
+     */
+    if ( uuid == IID_QUnknown )
+        *iface = this;
+    else if ( uuid == IID_TaskbarApplet )
+        *iface = this;
+    else
+        return QS_FALSE;
+
+    if ( *iface )
+        (*iface)->addRef();
+
+    return QS_OK;
+}
+
+
+/*
+ * Finally we need to export the Interface.
+ * CREATE_INSTANCE creates a interface and calls
+ * queryInterface for the QUnknownInterface once
+ * With out this function the applet can't be loaded.
+ *
+ * NOTE: If your applet does not load it's likely you've an
+ * unresolved symbol. Change the .pro TEMPLATE = lib to TEMPLATE= app
+ * and recompile. If the linker only complains about a missing
+ * main method the problem is more complex. In most cases it'll say
+ * you which symbols are missing and you can implement them.
+ * The main(int argc, char* argv[] ) does not need to be
+ * included in a library so it's ok that the linker complains
+ */
+Q_EXPORT_INTERFACE() {
+    Q_CREATE_INSTANCE( SimpleAppletImpl )
+}
+
diff --git a/examples/applet/simpleimpl.h b/examples/applet/simpleimpl.h
new file mode 100644
index 0000000..8459c96
--- a/dev/null
+++ b/examples/applet/simpleimpl.h
@@ -0,0 +1,72 @@
+/*
+ * You may use, modify and distribute without any limitation
+ */
+
+/**
+ * Opie and Qtopia uses a component system called QCOM
+ * which was first part of the Qt 3.0 API but was made
+ * prviate during the betas. Opie and Qtopia still use it
+ * and we're happy with it.
+ * Every starts with the QUnknownInterface. It supports functions
+ * for reference counting and the most important one
+ * is for a query. Every QCOM interface got a global unique id ( GUID,UUID )
+ * query is used to see if a interface is supported by
+ * a dynamic shared object ( dso / plugin )
+ * For tasks like loading Applications, InputMethods, Today, MenuButton,
+ * Taskbar, Style, Email Client there are specefic Interfaces you
+ * need to implement. The interfaces inherits from QUnknownInterface and
+ * you'll need inherit from the interface.
+ * As example we will use the Taskbar interface
+ */
+
+#ifndef SIMPLE_OPIE_EXAMPLE_APPLET_H
+#define SIMPLE_OPIE_EXAMPLE_APPLET_H
+
+/*
+ * The taskbar applet interfaces wants us to implement position() and applet()
+ * additionally we need to implement add(), release() and queryInterface for QUnknownInterface
+ * luckiy there is a macro for the reference counting
+ * We provide an Implementation of the interface.
+ */
+#include <qwidget.h>
+#include <qpe/taskbarappletinterface.h>
+
+
+/*
+ * Because we only draw an Icon in a fixed width and height
+ * we declare and define SimpleApplet here and you could use QLabel
+ * setPixmap or use QWidget and draw yourself.
+ * You might also want to reimplement mouse*Event to use some simple actions
+ */
+class SimpleApplet : public QWidget {
+    Q_OBJECT
+public:
+    SimpleApplet(QWidget *parent);
+    ~SimpleApplet();
+private:
+    void mousePressEvent( QMouseEvent* );
+    void paintEvent( QPaintEvent* );
+    QPixmap *m_pix;
+};
+
+class SimpleAppletImpl : public TaskbarAppletInterface {
+public:
+
+    SimpleAppletImpl();
+    virtual ~SimpleAppletImpl();
+
+    QRESULT queryInterface( const QUuid&, QUnknownInterface** );
+
+    QWidget *applet( QWidget* parent );
+    int position()const;
+
+    /*
+     * macro for reference countint
+     * if reference drops to zero
+     * delete this is called
+     */
+    Q_REFCOUNT
+};
+
+
+#endif