Difference between revisions of "Development/Tutorials/Programming Tutorial KDE 4/Using KConfig"

Jump to: navigation, search
(Create skellington)
 
m (Text replace - "<code ini n>" to "<syntaxhighlight lang="ini" line>")
 
(20 intermediate revisions by 5 users not shown)
Line 1: Line 1:
 +
{{Warning|The subject matter that I was going to cover in this tutorial is already covered in [[Development/Tutorials/KConfig]] and so this tutorial will probably be removed.}}
 +
 
[[image:introtokdetutorial4.png|frame|center]]
 
[[image:introtokdetutorial4.png|frame|center]]
 
==Abstract==
 
==Abstract==
TODO:Using KConfig XT in an application
+
''Author'': Fabian Korak
 +
 
 +
''Author'': [[User:Milliams|Matt Williams]](presets)
 +
 
 +
In this tutorial, we're going to be showing you how to utilise KConfig XT in an application. It is recommended that you read [[Development/Tutorials/Using KConfig XT]] before continuing in order to familiarise yourself with the framework.
 +
 
 
==Prerequisites==
 
==Prerequisites==
* [[Development/Tutorials/Programming_Tutorial_KDE_4/Using_KActions|Tutorial 3 - KActions]]
+
* [[Development/Tutorials/Using_KActions|Tutorial 3 - KActions]]
 +
 
 +
* [[Development/Tutorials/Using_KConfig_XT]]
  
 
==KConfig XT==
 
==KConfig XT==
TODO
+
 
 +
At first we make new File called tutorial4.kcfg within the source directory of your project.
 +
 
 +
<syntaxhighlight lang="xml">
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
 +
<kcfg>
 +
<kcfgfile name="kjotsrc"/>
 +
<include>kglobalsettings.h</include>
 +
<group name="kjots">
 +
<entry name="showAction" type="Bool">
 +
<label>Whether setupAction is called</label>
 +
<default>true</default>
 +
</entry>
 +
</group>
 +
</kcfg>
 +
</syntaxhighlight>
 +
 
 +
This code makes a setting of the type bool, which determines whether we want to do something. Then we set the default value to be true.
 +
 
 +
'''Always start the value of <entry name=""> in lower case since KConfig XT sets them to lower case within the generated headers either way. If you don't this could give you some nearly untraceable errors'''
 +
 
 +
Now we make a new File called tutorial4.kcfgc.
 +
 
 +
<syntaxhighlight lang="ini">
 +
File=tutorial4.kcfg
 +
ClassName=tutorial4
 +
Singleton=true
 +
Mutators=true
 +
</syntaxhighlight>
 +
 
 +
This should set up your configuration for now.
 +
 
 
==The Code==
 
==The Code==
 
===mainwindow.h===
 
===mainwindow.h===
<code cppqt n>
+
<syntaxhighlight lang="cpp-qt" line>
TODO
+
#ifndef MAINWINDOW_H
</code>
+
#define MAINWINDOW_H
 +
 
 +
#include <KXmlGuiWindow>
 +
#include <KTextEdit>
 +
 
 +
 
 +
class MainWindow : public KXmlGuiWindow
 +
{
 +
 
 +
public:
 +
MainWindow(QWidget *parent=0);
 +
private:
 +
KTextEdit* textArea;
 +
void setupActions();
 +
void setupConfig();
 +
void readConfig();
 +
void saveSettings();
 +
int m_showAction;
 +
 
 +
};
 +
 
 +
#endif
 +
 
 +
 
 +
</syntaxhighlight>
 +
 
 +
There are some new voids in here, as well as m_showAction witch determines the value stored in KConfig XT. Despite that value being a bool we can actually use an integer here, since the type is converted either way.
 +
 
 
===mainwindow.cpp===
 
===mainwindow.cpp===
<code cppqt n>
+
<syntaxhighlight lang="cpp-qt" line>
TODO
+
#include "mainwindow.h"
</code>
+
#include "tutorial4.h"
 +
 
 +
#include <KApplication>
 +
#include <KAction>
 +
#include <KLocale>
 +
#include <KActionCollection>
 +
#include <KStandardAction>
 +
#include <KConfigDialog>
 +
 
 +
MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent)
 +
{
 +
 
 +
textArea = new KTextEdit;
 +
setCentralWidget(textArea);
 +
setupConfig();
 +
}
 +
 
 +
void MainWindow::setupActions()
 +
{
 +
 
 +
QAction* clearAction = actionCollection()->addAction( "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();
 +
 
 +
}
 +
 
 +
void MainWindow::setupConfig()
 +
{
 +
readConfig();
 +
 +
 +
}
 +
 
 +
void MainWindow::readConfig() {
 +
m_showAction    = tutorial4::showAction();
 +
if(m_showAction = (true))
 +
setupActions();
 +
 +
}
 +
 
 +
void MainWindow::saveSettings() {
 +
tutorial4::setShowAction(m_showAction);
 +
tutorial4::self()->writeConfig();
 +
}
 +
 
 +
 
 +
 
 +
</syntaxhighlight>
 +
 
 +
At first we import "tutorial4.h", which should be auto-generated at runtime by KConfig XT every time you compile this. MainWindow and SetupActions are copied from the tutorials before. The only thing new is that we now call a new void called setupConfig. This then calls readConfig. We '''could''' also call saveSettings(but only after we called readConfig), but since we don't change any values there this is more of a "proof of concept".
 +
 
 +
Within readConfig we assign m_showAction the value of the setting showAction. If this returns true setupsActions makes buttons and all that. When false it doesn't.
 +
 
 +
The setShowActions() in saveSettings() overwrites showAction with a value of your choice, in this case with itself. Then you need to call writeConfig() to apply the changes you made.
 +
 
 
===main.cpp===
 
===main.cpp===
<code cppqt n>
+
<syntaxhighlight lang="cpp-qt" line>
TODO
+
 
</code>
+
#include "mainwindow.h"
===tutorial3ui.rc===
+
 
<code xml n>
+
 
TODO
+
#include <KApplication>
</code>
+
#include <KAboutData>
 +
#include <KCmdLineArgs>
 +
 +
int main (int argc, char *argv[])
 +
{
 +
KAboutData aboutData( "tutorial4", "tutorial4",
 +
      "0.4", "KMessageBox popup",
 +
KAboutData::License_GPL, "(c) 2007" );
 +
KCmdLineArgs::init( argc, argv, &aboutData );
 +
 +
KApplication app;
 +
 +
MainWindow* window = new MainWindow();
 +
window->show();
 +
 +
return app.exec();
 +
 
 +
}
 +
</syntaxhighlight>
 +
 
 +
No news in here
 +
 
 +
===tutorial4ui.rc===
 +
<syntaxhighlight lang="xml" line>
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<gui name="tutorial4"
 +
    version="1"
 +
    xmlns="http://www.kde.org/standards/kxmlgui/1.0"
 +
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 +
    xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
 +
                        http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >
 +
 
 +
  <MenuBar>
 +
    <Menu name="file" >
 +
      <text>&amp;File</text>
 +
      <Action name="clear" />
 +
    </Menu>
 +
  </MenuBar>
 +
 
 +
  <ToolBar name="mainToolBar" >
 +
    <text>Main Toolbar</text>
 +
    <Action name="clear" />
 +
  </ToolBar>
 +
 
 +
</gui>
 +
 
 +
</syntaxhighlight>
  
 
==CMake==
 
==CMake==
TODO
 
 
===CMakeLists.txt===
 
===CMakeLists.txt===
<code ini n>
+
<syntaxhighlight lang="ini" line>
TODO
+
PROJECT(tutorial4)
</code>
+
 
 +
FIND_PACKAGE(KDE4 REQUIRED)
 +
INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} ${CMAKE_CURRENT_BINARY_DIR})
 +
 
 +
SET(tutorial4_SRCS
 +
  main.cpp
 +
  mainwindow.cpp
 +
)
 +
 
 +
KDE4_ADD_KCFG_FILES(tutorial4_SRCS settings.kcfgc)
 +
 
 +
KDE4_ADD_EXECUTABLE(tutorial4 ${tutorial4_SRCS})
 +
 
 +
TARGET_LINK_LIBRARIES( tutorial4 ${KDE4_KDEUI_LIBS})
 +
 
 +
install( TARGETS tutorial4 DESTINATION ${BIN_INSTALL_DIR})
 +
install( FILES tutorial4ui.rc DESTINATION  ${DATA_INSTALL_DIR}/tutorial4)
 +
install( FILES tutorial4.kcfg  DESTINATION  ${KCFG_INSTALL_DIR} )
 +
</syntaxhighlight>
 +
 
 
==Moving On==
 
==Moving On==
TODO
+
 
 +
For a better understanding of the XML used in KConfig XT you could try
 +
[[Development/Tutorials/Programming_Tutorial_KDE_4/How_to_write_an_XML_parser|to write an Xml Parser]]

Latest revision as of 22:05, 29 June 2011

noframe
 
Warning
The subject matter that I was going to cover in this tutorial is already covered in Development/Tutorials/KConfig and so this tutorial will probably be removed.


Introtokdetutorial4.png

Contents

[edit] Abstract

Author: Fabian Korak

Author: Matt Williams(presets)

In this tutorial, we're going to be showing you how to utilise KConfig XT in an application. It is recommended that you read Development/Tutorials/Using KConfig XT before continuing in order to familiarise yourself with the framework.

[edit] Prerequisites

[edit] KConfig XT

At first we make new File called tutorial4.kcfg within the source directory of your project.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.xsd">
<kcfg>
	<kcfgfile name="kjotsrc"/>
	<include>kglobalsettings.h</include>
	<group name="kjots">
		<entry name="showAction" type="Bool">
			<label>Whether setupAction is called</label>
			<default>true</default>
		</entry>
	</group>
</kcfg>

This code makes a setting of the type bool, which determines whether we want to do something. Then we set the default value to be true.

Always start the value of <entry name=""> in lower case since KConfig XT sets them to lower case within the generated headers either way. If you don't this could give you some nearly untraceable errors

Now we make a new File called tutorial4.kcfgc.

File=tutorial4.kcfg
ClassName=tutorial4
Singleton=true
Mutators=true

This should set up your configuration for now.

[edit] The Code

[edit] mainwindow.h

  1. #ifndef MAINWINDOW_H
  2. #define MAINWINDOW_H
  3.  
  4. #include <KXmlGuiWindow>
  5. #include <KTextEdit>
  6.  
  7.  
  8. class MainWindow : public KXmlGuiWindow
  9. {
  10.  
  11. 	public:
  12. 		MainWindow(QWidget *parent=0);
  13. 	private:
  14. 		KTextEdit* textArea;
  15. 		void setupActions();
  16. 		void setupConfig();
  17. 		void readConfig();
  18. 		void saveSettings();
  19. 		int m_showAction;
  20.  
  21. };
  22.  
  23. #endif

There are some new voids in here, as well as m_showAction witch determines the value stored in KConfig XT. Despite that value being a bool we can actually use an integer here, since the type is converted either way.

[edit] mainwindow.cpp

  1. #include "mainwindow.h"
  2. #include "tutorial4.h"
  3.  
  4. #include <KApplication>
  5. #include <KAction>
  6. #include <KLocale>
  7. #include <KActionCollection>
  8. #include <KStandardAction>
  9. #include <KConfigDialog>
  10.  
  11. MainWindow::MainWindow(QWidget *parent) : KXmlGuiWindow(parent)
  12. {
  13.  
  14. 	textArea = new KTextEdit;
  15. 	setCentralWidget(textArea);
  16. 	setupConfig();
  17. }
  18.  
  19. void MainWindow::setupActions()
  20. {
  21.  
  22. 	QAction* clearAction = actionCollection()->addAction( "clear" );
  23.  
  24. 	clearAction->setText(i18n("Clear"));
  25. 	clearAction->setIcon(KIcon("filenew"));
  26. 	clearAction->setShortcut(Qt::CTRL+ Qt::Key_W);
  27.  
  28. 	connect(clearAction, SIGNAL(triggered(bool)), textArea, SLOT(clear()));
  29.  
  30. 	KStandardAction::quit(kapp, SLOT(quit()), actionCollection());
  31.  
  32. 	setupGUI();
  33.  
  34. }
  35.  
  36. void MainWindow::setupConfig()
  37. {
  38. 	readConfig();	
  39.  
  40.  
  41. }
  42.  
  43. void MainWindow::readConfig() {
  44. 	m_showAction    = tutorial4::showAction();
  45. 	if(m_showAction = (true)) 
  46. 		setupActions();
  47.  
  48. }
  49.  
  50. void MainWindow::saveSettings() { 
  51. 	tutorial4::setShowAction(m_showAction);
  52. 	tutorial4::self()->writeConfig();
  53. }

At first we import "tutorial4.h", which should be auto-generated at runtime by KConfig XT every time you compile this. MainWindow and SetupActions are copied from the tutorials before. The only thing new is that we now call a new void called setupConfig. This then calls readConfig. We could also call saveSettings(but only after we called readConfig), but since we don't change any values there this is more of a "proof of concept".

Within readConfig we assign m_showAction the value of the setting showAction. If this returns true setupsActions makes buttons and all that. When false it doesn't.

The setShowActions() in saveSettings() overwrites showAction with a value of your choice, in this case with itself. Then you need to call writeConfig() to apply the changes you made.

[edit] main.cpp

  1. #include "mainwindow.h"
  2.  
  3.  
  4. #include <KApplication>
  5. #include <KAboutData>
  6. #include <KCmdLineArgs>
  7.  
  8. int main (int argc, char *argv[])
  9. {
  10. 	KAboutData aboutData( "tutorial4", "tutorial4",
  11. 			      "0.4", "KMessageBox popup",
  12. 	 KAboutData::License_GPL, "(c) 2007" );
  13. 	KCmdLineArgs::init( argc, argv, &aboutData );
  14.  
  15. 	KApplication app;
  16.  
  17. 	MainWindow* window = new MainWindow();
  18. 	window->show();
  19.  
  20. 	return app.exec();
  21.  
  22. }

No news in here

[edit] tutorial4ui.rc

  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <gui name="tutorial4"
  3.      version="1"
  4.      xmlns="http://www.kde.org/standards/kxmlgui/1.0"
  5.      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  6.      xsi:schemaLocation="http://www.kde.org/standards/kxmlgui/1.0
  7.                          http://www.kde.org/standards/kxmlgui/1.0/kxmlgui.xsd" >
  8.  
  9.   <MenuBar>
  10.     <Menu name="file" >
  11.       <text>&amp;File</text>
  12.       <Action name="clear" />
  13.     </Menu>
  14.   </MenuBar>
  15.  
  16.   <ToolBar name="mainToolBar" >
  17.     <text>Main Toolbar</text>
  18.     <Action name="clear" />
  19.   </ToolBar>
  20.  
  21. </gui>

[edit] CMake

[edit] CMakeLists.txt

  1. PROJECT(tutorial4)
  2.  
  3. FIND_PACKAGE(KDE4 REQUIRED)
  4. INCLUDE_DIRECTORIES( ${KDE4_INCLUDES} ${CMAKE_CURRENT_BINARY_DIR})
  5.  
  6. SET(tutorial4_SRCS 
  7.   main.cpp
  8.   mainwindow.cpp
  9. )
  10.  
  11. KDE4_ADD_KCFG_FILES(tutorial4_SRCS settings.kcfgc)
  12.  
  13. KDE4_ADD_EXECUTABLE(tutorial4 ${tutorial4_SRCS})
  14.  
  15. TARGET_LINK_LIBRARIES( tutorial4 ${KDE4_KDEUI_LIBS})
  16.  
  17. install( TARGETS tutorial4 DESTINATION ${BIN_INSTALL_DIR})
  18. install( FILES tutorial4ui.rc DESTINATION  ${DATA_INSTALL_DIR}/tutorial4)
  19. install( FILES tutorial4.kcfg  DESTINATION  ${KCFG_INSTALL_DIR} )

[edit] Moving On

For a better understanding of the XML used in KConfig XT you could try to write an Xml Parser


This page was last modified on 29 June 2011, at 22:05. This page has been accessed 7,345 times. Content is available under Creative Commons License SA 3.0 as well as the GNU Free Documentation License 1.2.
KDE® and the K Desktop Environment® logo are registered trademarks of KDE e.V.Legal