Development/Tutorials/Using KActions: Difference between revisions

    From KDE TechBase
    (All about KAction)
    (Finish up tutorial. There's still one section TODO if anyone fancies helping :))
    Line 32: Line 32:
    Now our action is fully set up, we need to connect it to something useful. We're going to connect our action to the <tt>clear()</tt> action belonging to a KTextArea.
    Now our action is fully set up, we need to connect it to something useful. We're going to connect our action to the <tt>clear()</tt> action belonging to a KTextArea.
    <code cppqt>connect(clearAction, SIGNAL(triggered(bool)), textArea, SLOT(clear()));</code>
    <code cppqt>connect(clearAction, SIGNAL(triggered(bool)), textArea, SLOT(clear()));</code>
    This is the came as it would be done in Qt with a QAction.
    This is the came as it would be done in Qt with a {{qt|QAction}}.


    ===KStandardAction===
    ===KStandardAction===
    Line 116: Line 116:


    ==Putting the actions in the menus and toolbars==
    ==Putting the actions in the menus and toolbars==
    Now, at the moment, we've only created our new "Clear" action. It won't yet show up in the menus or in the toolbars. To tell the program where to put our actions (and to allow the end-user to move them around) we use an xml file.
    ===XMLGUI===
    ===XMLGUI===
    TODO: Pah, I'm getting tired. Can someone write a bit of an intro to XMLGUI (mentioning that it will be replaced by liveui), walk through what the code below means and mention the naming rules of the .xml file :)
    ===tutorial3ui.rc===
    ===tutorial3ui.rc===
    <code xml n>
    <code xml n>
    Line 135: Line 137:


    ==CMake==
    ==CMake==
     
    Now that we're using XMLGUI, we need to put the <tt>tutorial3ui.rc</tt> somewhere where KDE can find it. This means we need to install our project somewhere.
    ===CMakeLists.txt===
    <code ini n>
    <code ini n>
    PROJECT(tutorial3)
    PROJECT(tutorial3)
    Line 143: Line 146:


    SET(tutorial3_SRCS  
    SET(tutorial3_SRCS  
    main.cpp
      main.cpp
    mainwindow.cpp
      mainwindow.cpp
    )
    )


    Line 154: Line 157:
    install( FILES tutorial3ui.rc DESTINATION  ${DATA_INSTALL_DIR}/tutorial3 )
    install( FILES tutorial3ui.rc DESTINATION  ${DATA_INSTALL_DIR}/tutorial3 )
    </code>
    </code>
    ===Make, Install And Run===
    If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.
    To tell CMake where to install the program, set the <tt>DCMAKE_INSTALL_PREFIX</tt> switch. So to install the program to the KDE directory, do
    cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
    make install
    tutorial3
    ==Moving On==
    ==Moving On==
    Now we can make the GUI look like and do whatever we want, we can move on to storing application settings with [[Development/Tutorials/Programming_Tutorial_KDE_4/Using_KConfig|KConfig XT]]
    Now that we can make the GUI look like and do whatever we want, we can move on to storing application settings with [[Development/Tutorials/Programming_Tutorial_KDE_4/Using_KConfig|KConfig XT]].

    Revision as of 22:18, 3 January 2007

    Abstract

    We're going to introduce the concept of actions. Actions are a unified way of supplying the user with ways to interact with your program.

    Say, for example, we want to let the user clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut; we can provide all of those through one KAction.

    Prerequisites

    KAction

    A KAction is an object which contains all the information about the icon and shortcuts you want associated to a certain action. You then connect the action to a slot which carries out the work of you action.

    Creating Your Own

    To create an action, you need to #include <KAction> in your .cpp file.

    Creating the object

    We're going to create an action which will clear the text area (see Tutorial 2). The KAction is built up in a number of steps. The first is creating the KAction KAction* clearAction = new KAction(actionCollection(), "clear"); This creates a KAction called clearAction. The first constructor argument is telling the action that it is part of the KActionCollection actionCollection() and the second is simply setting a name for internal use (it doesn't necessarily have to be textually similar to the function of the action).

    Text

    Now we have out KAction object, we can start setting its properties. First, we'll set the text that will be displayed in the menu and under its icon in the toolbar. clearAction->setText(i18n("Clear")); As you can see, the text must be passed through the i18n() function if you want your UI to be translatable.

    Icon

    If you're going to display the action in a toolbar, you're going to want to have an icon depicting the action. To set an icon we simply use the setIcon() function thus: clearAction->setIcon(KIcon("filenew")); Here we're setting the icon to the standard KDE filenew icon.

    Shortcut

    We can also set a shortcut that will perform our action. It's as simple as a clearAction->setShortcut(Qt::CTRL+Qt::Key_W); to set Ctrl+W to be associated to this action.

    Connecting the action

    Now our action is fully set up, we need to connect it to something useful. We're going to connect our action to the clear() action belonging to a KTextArea. connect(clearAction, SIGNAL(triggered(bool)), textArea, SLOT(clear())); This is the came as it would be done in Qt with a QAction.

    KStandardAction

    For actions which would likely appear in almost every KDE application such as 'quit', 'save', and 'load' there are pre-created convenience KActions, accessed through KStandardAction.

    They are very simple to use. Once you've done #include <KAction>, you simply need to supply it with what you want the function to do and which KActionCollection to add it to. For example, KStandardAction::quit(kapp, SLOT(quit()), actionCollection()); Will Create a KAction with the correct icon, text and shortcut and will even add it to the File menu.

    The Code

    mainwindow.h

    1. ifndef MAINWINDOW_H
    2. define MAINWINDOW_H
    1. include <KMainWindow>
    2. include <KTextEdit>

    class MainWindow : public KMainWindow {

     public:
       MainWindow(QWidget *parent=0);
    
     private:
       KTextEdit* textArea;
       void setupActions();
    

    };

    1. endif

    mainwindow.cpp

    1. include "mainwindow.h"
    1. include <KApplication>
    2. include <KAction>
    3. include <KStandardAction>

    MainWindow::MainWindow(QWidget *parent) : KMainWindow(parent) {

     textArea = new KTextEdit;
     setCentralWidget(textArea);
    
     setupActions();
    

    }

    void MainWindow::setupActions() {

     KAction* clearAction = new KAction(actionCollection(), "clear");
     clearAction->setText(i18n("Clear"));
     clearAction->setIcon(KIcon("filenew"));
     clearAction->setShortcut(Qt::CTRL+Qt::Key_W);
     connect(clearAction, SIGNAL(triggered(bool)), 
             textArea, SLOT(clear()));
    
     KStandardAction::quit(kapp, SLOT(quit()), actionCollection());
    
     setupGUI();
    

    }

    main.cpp

    1. include <KApplication>
    2. include <KAboutData>
    3. include <KCmdLineArgs>
    1. include "mainwindow.h"

    int main (int argc, char *argv[]) {

     KAboutData aboutData( "tutorial3", "Tutorial 3",
         "1.0", "A simple text area using KAction etc.",
         KAboutData::License_GPL, "(c) 2006" );
     KCmdLineArgs::init( argc, argv, &aboutData );
     KApplication app;
    
     MainWindow* window = new MainWindow();
     window->show();
     return app.exec();
    

    }

    Putting the actions in the menus and toolbars

    Now, at the moment, we've only created our new "Clear" action. It won't yet show up in the menus or in the toolbars. To tell the program where to put our actions (and to allow the end-user to move them around) we use an xml file.

    XMLGUI

    TODO: Pah, I'm getting tired. Can someone write a bit of an intro to XMLGUI (mentioning that it will be replaced by liveui), walk through what the code below means and mention the naming rules of the .xml file :)

    tutorial3ui.rc

    <!DOCTYPE kpartgui SYSTEM "kpartgui.dtd"> <kpartgui name="tutorial3" version="1">

     <ToolBar name="mainToolBar" >
       <text>Main Toolbar</text>
       <Action name="clear" />
     </ToolBar>
     <MenuBar>
       <Menu name="file" >
         <text>&File</text>
         <Action name="clear" />
       </Menu>
     </MenuBar>
    

    </kpartgui>

    CMake

    Now that we're using XMLGUI, we need to put the tutorial3ui.rc somewhere where KDE can find it. This means we need to install our project somewhere.

    CMakeLists.txt

    PROJECT(tutorial3)

    FIND_PACKAGE(KDE4 REQUIRED) INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} )

    SET(tutorial3_SRCS

     main.cpp
     mainwindow.cpp
    

    )

    KDE4_ADD_EXECUTABLE(tutorial3 ${tutorial3_SRCS})

    TARGET_LINK_LIBRARIES( tutorial3 ${KDE4_KDEUI_LIBS})

    install(TARGETS tutorial3 DESTINATION ${BIN_INSTALL_DIR}) install( FILES tutorial3ui.rc DESTINATION ${DATA_INSTALL_DIR}/tutorial3 )

    Make, Install And Run

    If you don't have write access to where your KDE4 installation directory, you can install it to a folder in your home directory.

    To tell CMake where to install the program, set the DCMAKE_INSTALL_PREFIX switch. So to install the program to the KDE directory, do

    cmake . -DCMAKE_INSTALL_PREFIX=$KDEDIR
    make install
    tutorial3
    

    Moving On

    Now that we can make the GUI look like and do whatever we want, we can move on to storing application settings with KConfig XT.