View View source History

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

Jump to: navigation, search
(Abstract. I'm gonna write the code and then I'll be back :))
m (Text replace - "<code ini n>" to "<syntaxhighlight lang="ini" line>")
 
(18 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==
−
''Author'': [[User:Milliams|Matt Williams]]
+
''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.
 
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
+
 
−
[[Category:Tutorial]]
+
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

Retrieved from ‘http://techbase.kde.org/index.php?title=Development/Tutorials/Programming_Tutorial_KDE_4/Using_KConfig&oldid=61011’

This page was last modified on 29 June 2011, at 22:05. This page has been accessed 6,107 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