Development/Tutorials/Plasma4/GettingStarted: Difference between revisions

    From KDE TechBase
    m (Added Information about running the Applet.)
    Line 245: Line 245:
    * cp ./plasma-applet-tutorial1.desktop $KDEDIR/share/kde4/services/
    * cp ./plasma-applet-tutorial1.desktop $KDEDIR/share/kde4/services/


    and run kbuildsycoca. The Applet will be displayed in the Applet Brower.
    and run kbuildsycoca.
    In order to test your Applet you can use the '''plasmoidviewer''' program:
    <code bash>
    plasmoidviewer applet_name
    </code>
     
    Where '''applet_name''' is the value specified into .desktop for the '''X-KDE-PluginInfo-Name''' key.
     
    Otherwise you can restart the KDE session, so the Applet will be displayed in the Applet Browser.

    Revision as of 14:39, 4 December 2007

    Creating your first Plasmoid
    Tutorial Series   Plasma Tutorial
    Previous   C++, Qt, KDE4 development environment
    What's Next  
    Further Reading   CMake

    Abstract

    We're going to start creating a simple plasmoid in this tutorial, to keep things simple we will only create a static plasmoid, it will contain the following items.

    • An SVG Image
    • Icon
    • Some nice text

    The Code

    The .desktop file

    Every Plasmoid needs a .desktop file to tell plasma how they should be started, and what name they carry.

    plasma-applet-tutorial1.desktop [Desktop Entry] Encoding=UTF-8 Name=Tutorial 1 Comment=Plasma Tutorial 1 Type=Service ServiceTypes=Plasma/Applet

    X-KDE-Library=plasma_applet_tutorial1 X-KDE-PluginInfo-Author=Bas Grolleman [email protected] X-KDE-PluginInfo-Name=plasma_applet_tutorial1 X-KDE-PluginInfo-Version=0.1 X-KDE-PluginInfo-Website=http://plasma.kde.org/ X-KDE-PluginInfo-Category=Examples X-KDE-PluginInfo-Depends= X-KDE-PluginInfo-License=GPL X-KDE-PluginInfo-EnabledByDefault=true

    The most important bits are the X-KDE-Library and X-KDE-PluginInfo-Name, they are the "glue" between your class and plasma, without it, nothing will start. For X-KDE-PluginInfo-Category, refer to the PIG.

    The header file

    This is the example header file, I will add lots of comments in the code to explain everything.

    plasma-tutorial1.h // Here we avoid loading the header multiple times

    1. ifndef Tutorial1_HEADER
    2. define Tutorial1_HEADER

    // We need the Plasma Applet headers

    1. include <KIcon>
    1. include <Plasma/Applet>
    2. include <Plasma/Svg>

    class QSizeF;

    // Define our plasma Applet class PlasmaTutorial1 : public Plasma::Applet {

       Q_OBJECT
       public:
           // Basic Create/Destroy
           PlasmaTutorial1(QObject *parent, const QVariantList &args);
           ~PlasmaTutorial1();
    
           // The paintInterface procedure paints the applet to screen
           void paintInterface(QPainter *painter,
                   const QStyleOptionGraphicsItem *option,
                   const QRect& contentsRect);
           void setContentSize(const QSizeF& size);
           QSizeF contentSizeHint() const;
    
       private:
           Plasma::Svg m_svg;
           KIcon m_icon;
    

    QSizeF m_size; };

    // This is the command that links your applet to the .desktop file K_EXPORT_PLASMA_APPLET(tutorial1, PlasmaTutorial1)

    1. endif

    QRectF boundingRect()

    The boundingRect() function tells plasma the actual size of the plasmoid, this is important because we need to know how much space is taken on screen.

    Tip
    If you have issues with your plasmoid leaving pixels behind when dragging this is almost always a result of a incorrect boundingRect()


    void paintInterface(...)

    You could call this the main function, since this paints the plasmoid on screen, here you define how you want your plasmoid to look.

    K_EXPORT_PLASMA_APPLET ( <name>, <class> )

    This is a small but very important part, this links your classname to the applet name in the .desktop file, if your applet doesn't seem to be loaded than chances are there is a difference between this and your .desktop file

    Tip
    The K_EXPORT_PLASMA_APPLET adds "plasma_applet_", please pay attention to this when setting up your .desktop file to avoid a name difference


    The actual work file

    Here is the body of the function, again with a lot of comments in between.

    plasma-tutorial1.cpp

    1. include "plasma-tutorial1.h"
    2. include <QPainter>
    3. include <QFontMetrics>
    4. include <QSizeF>
    1. include <plasma/svg.h>
    2. include <plasma/theme.h>

    PlasmaTutorial1::PlasmaTutorial1(QObject *parent, const QVariantList &args)

       : Plasma::Applet(parent, args),
       m_svg("widgets/background", this),
       m_size(200,200),
       m_icon("document")
    

    {

       // this will get us the standard applet background, for free!
       setDrawStandardBackground(true);
       m_svg.setContentType(Plasma::Svg::SingleImage);
    
       //m_svg->setContentType(Plasma::Svg::SingleImage);
     
       // A small demonstration of the setFailedToLaunch function
       if (m_icon.isNull()) {
           setFailedToLaunch(true, "No world to say hello");
       }
    

    }

    PlasmaTutorial1::~PlasmaTutorial1() {

       if (failedToLaunch()) {
           // Do some cleanup here
       } else {
           // Save settings
       }
    

    }

    void PlasmaTutorial1::setContentSize(const QSizeF& size) {

       m_size = size;
    

    }

    QSizeF PlasmaTutorial1::contentSizeHint() const {

       //If you want to change the size of your plasmoid, update m_size and call updateGeometry() afterwards.
       return m_size;
    

    }

    void PlasmaTutorial1::paintInterface(QPainter *p,

           const QStyleOptionGraphicsItem *option, const QRect &contentsRect)
    

    {

       p->setRenderHint(QPainter::SmoothPixmapTransform);
       p->setRenderHint(QPainter::Antialiasing);
    
       // Now we draw the applet, starting with our svg
       m_svg.resize((int)contentsRect.width(), (int)contentsRect.height());
       m_svg.paint(p, (int)contentsRect.left(), (int)contentsRect.top());
    
       // We place the icon and text
       p->drawPixmap(20, 0, m_icon.pixmap((int)contentsRect.width() - 40));
       p->save();
       p->setPen(Qt::white);
       p->drawText(contentsRect,
                   Qt::AlignBottom | Qt::AlignHCenter,
                   "Hello Plasmoid!");
       p->restore();
    

    }

    1. include "plasma-tutorial1.moc"

    Plasma/Svg

    As you can see in the example code where using the Plasma::Svg object, there are some important things to note here.

    First we're using a relative path widgets/background which causes Plasma::Svg to use Plasma::Theme to locate the SVG data. While Plasma::Svg does support loading arbitrary files when passed an absolute path, use relative paths from the theme as often as possible as it makes Plasma skinable and the individual plasmoids look like a combined whole instead of a group of separate unrelated applications. You can see a list of available image components on the Plasma Theme page.

    Next, note how we set the content type of the SVG object to Plasma::Svg::SingleImage. This is actually the default so technically we didn't have to set it manually. It tells the SVG object that the what we have loaded is a single image in the file.

    The alternative option, Plasma::Svg::ImageSet tells Plasma::Svg that there are multiple individual images in the SVG file. For instance, one might use this method to store a deck of cards in one SVG file. This is useful since we only require a single SVG file to hold all the images.

    In either mode, Plasma::Svg can be used to draw a subset of the SVG file by passing it an element id that appears in the SVG document. As a good example, if you open the clock.svg file that ships with the default theme, you will see that it has a background, 3 handles (hour, minute and seconds) and a foreground (the glass). Due to the ability to put all the elements in one file the SVG file shows a clock. This is much nicer for artists compared to editting 5 separate files that they have to imagine on top of each other, and much nicer for performance as only one SVG renderer and one file read from disk is necessary.

    setDrawStandardBackground(bool)

    Since drawing a background is a common function there is fast and easier way of doing it. By adding setDrawStandardBackground(true) to the code, the default Plasma background gets drawn behind your plasmoid. This not only saves you time and code, but creates a more consistent presentation for the user.

    failedToLaunch()

    If for some reason, the applet fails to get up on its feet (the library couldn't be loaded, necessary hardware support wasn't found, etc..) this method returns true. Using this function gives your application a chance to cleanup before quiting.

    setFailedToLaunch(bool, QString)

    When your application is unable to start, this function allows you to inform Plasma and give an optional reason why. Plasma will then draw a standardized error interface to inform the user of the situation and your applet will not be called upon to do any drawing on its own from that point forward. If your plasmoid becomes more complex and depends on multiple factors this is the nicest way to cleanup.

    dataUpdated

    If you would connect to any of plasma's data-engines you would have to implement a function called dataUpdated in your plasmoid. The latter is called if the data-engine sends you data, i.e. your plasmoid should recalculate its contents.

    Building it all, the CMakeLists.txt

    Finally, to put everything together you need to build everything, to tell cmake what needs to go where there is the CMakeLists.txt file.

    For more details on CMake please read Development/Tutorials/CMake

    1. Project Needs a name ofcourse

    project(plasma-tutorial1)

    1. Find the required Libaries

    find_package(KDE4 REQUIRED) include(KDE4Defaults) find_package(Plasma REQUIRED)

    add_definitions (${QT_DEFINITIONS} ${KDE4_DEFINITIONS}) include_directories(

      ${CMAKE_SOURCE_DIR}
      ${CMAKE_BINARY_DIR}
      ${KDE4_INCLUDES}
      )
    
    1. We add our source code here

    set(tutorial1_SRCS plasma-tutorial1.cpp)

    1. Now make sure all files get to the right place

    kde4_add_plugin(plasma_applet_tutorial1 ${tutorial1_SRCS}) target_link_libraries(plasma_applet_tutorial1

                         ${PLASMA_LIBS} ${KDE4_KDEUI_LIBS})
    

    install(TARGETS plasma_applet_tutorial1

           DESTINATION ${PLUGIN_INSTALL_DIR})
    

    install(FILES plasma-applet-tutorial1.desktop

           DESTINATION ${SERVICES_INSTALL_DIR})
    

    Testing the Applet

    If your current Development Environment differs from the Test Installation, you have to

    • cp ./lib/plasma_applet_tutorial1.so $KDEDIR/lib
    • cp ./plasma-applet-tutorial1.desktop $KDEDIR/share/kde4/services/

    and run kbuildsycoca. In order to test your Applet you can use the plasmoidviewer program: plasmoidviewer applet_name

    Where applet_name is the value specified into .desktop for the X-KDE-PluginInfo-Name key.

    Otherwise you can restart the KDE session, so the Applet will be displayed in the Applet Browser.