KDE TechBase - User contributions [en]

User:Chris

2009-04-25T08:35:41Z

Chris: bug 154142 fixed

User:Chris

2009-01-12T03:48:26Z

Chris:

What happens, when you insert [http://www.unicode.org/cgi-bin/GetUnihanData.pl?codepoint=200ca Character U+200ca] using Konqueror 4.1.3: #56522;. Wow! I swear I pasted the character from the Unicode page.

User:Chris

2009-01-12T03:36:13Z

Chris:

What happens, when you insert [http://www.unicode.org/cgi-bin/GetUnihanData.pl?codepoint=200ca Character U+200ca] using Konqueror 4.3: #56522;. Wow! I swear I pasted the character from the Unicode page.

User:Chris

2009-01-12T03:32:16Z

Chris:

What happens, when you insert [http://www.unicode.org/cgi-bin/GetUnihanData.pl?codepoint=20000 Character U+20000] using Konqueror 4.3: Let's check the wiki code.

User:Chris

2009-01-12T03:31:32Z

Chris: New page: What happens, when you insert [http://www.unicode.org/cgi-bin/GetUnihanData.pl?codepoint=20000 Character U+20000] using Konqueror 4.3: Let's check the wiki code.

What happens, when you insert [http://www.unicode.org/cgi-bin/GetUnihanData.pl?codepoint=20000 Character U+20000] using Konqueror 4.3: Let's check the wiki code.

Development/Tutorials/Using KActions

2008-12-21T15:37:00Z

Chris: /* XMLGUI */ link to better though old info

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Using_KActions}}

{{TutorialBrowser|

series=Beginner Tutorial|

name=How To Use KActions and XMLGUI|

pre=[[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 - KXmlGuiWindow]], Basic XML knowledge|

next=[[Development/Tutorials/Saving_and_loading|Tutorial 4 - Saving and loading]]|

reading=None
}}

==Abstract==
This tutorial introduces the concept of actions. Actions are a unified way of supplying the user with ways to interact with your program.

For example, if we wanted to let the user of [[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2 ]] clear the text box by clicking a button in the toolbar, from an option in the File menu or through a keyboard shortcut, it could all be done with one {{class|KAction}}.

[[image:introtokdetutorial3.png|frame|center]]

==KAction==
A {{class|KAction}} is an object which contains all the information about the icon and shortcuts that is associated with a certain action. The action is then connected to a [http://doc.trolltech.com/latest/signalsandslots.html slot] which carries out the work of your action.

== The Code ==

===main.cpp===
<code cppqt>
#include <KApplication>
#include <KAboutData>
#include <KCmdLineArgs>

#include "mainwindow.h"

int main (int argc, char *argv[])
{
KAboutData aboutData( "tutorial3", "tutorial3",
ki18n("Tutorial 3"), "1.0",
ki18n("A simple text area using KAction etc."),
KAboutData::License_GPL,
ki18n("Copyright (c) 2007 Developer") );
KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;

MainWindow* window = new MainWindow();
window->show();
return app.exec();
}
</code>
This time, very little has changed in <tt>main.cpp</tt>, only the KAboutData constructor has been updated to show that we are now on tutorial 3.

===mainwindow.h===
<code cppqt>
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <KXmlGuiWindow>
#include <KTextEdit>

class MainWindow : public KXmlGuiWindow
{
public:
MainWindow(QWidget *parent=0);

private:
KTextEdit* textArea;
void setupActions();
};

#endif
</code>
Only a function <tt>void setupActions()</tt> has been added which will do all the work setting up the KActions.

===mainwindow.cpp===
<code cppqt>
#include "mainwindow.h"

#include <KApplication>
#include <KAction>
#include <KLocale>
#include <KActionCollection>
#include <KStandardAction>

MainWindow::MainWindow(QWidget *parent)
: KXmlGuiWindow(parent)
{
textArea = new KTextEdit;
setCentralWidget(textArea);

setupActions();
}

void MainWindow::setupActions()
{
KAction* clearAction = new KAction(this);
clearAction->setText(i18n("Clear"));
clearAction->setIcon(KIcon("document-new"));
clearAction->setShortcut(Qt::CTRL + Qt::Key_W);
actionCollection()->addAction("clear", clearAction);
connect(clearAction, SIGNAL(triggered(bool)),
textArea, SLOT(clear()));

KStandardAction::quit(kapp, SLOT(quit()),
actionCollection());

setupGUI();
}
</code>

==Explanation==
This builds upon the KXmlGuiWindow code from [[Development/Tutorials/Using_KXmlGuiWindow|Tutorial 2]]. Most of the changes are to <tt>mainwindow.cpp</tt>, an important structural change being that the constructor for MainWindow now calls <tt>setupActions()</tt> instead of <tt>setupGUI()</tt>. <tt>setupActions()</tt> is where the new KAction code goes before finally calling <tt>setupGUI()</tt> itself.

===Creating the KAction object===
The KAction is built up in a number of steps. The first is including the <tt>KAction</tt> library and then creating the KAction:
<code cppqt>
#include <KAction>
...
KAction* clearAction = new KAction(this);
</code>
This creates a new KAction called <tt>clearAction</tt>.

===Setting KAction Properties===
====Text====
Now we have our KAction object, we can start setting its properties. The following code sets the text that will be displayed in the menu and under the <tt>KAction</tt>'s icon in the toolbar.
<code cppqt>clearAction->setText(i18n("Clear"));</code>
Note that the text is passed through the i18n() function; this is necessary for the UI to be translatable (more information on this can be found in the [[Development/Tutorials/Localization/i18n|i18n tutorial]]).

====Icon====
If the action is going to be displayed in a toolbar, it's nice to have an icon depicting the action. The following code sets the icon to the standard KDE <tt>document-new</tt> icon through the use of the <tt>setIcon()</tt> function:
<code cppqt>clearAction->setIcon(KIcon("document-new"));</code>

====Keyboard Shortcut====
Setting a keyboard shortcut to perform our action is equally simple:
<code cppqt>clearAction->setShortcut(Qt::CTRL + Qt::Key_W);</code>
This associates Ctrl+W with the KAction.

===Adding to the Collection===
In order for the action to be accessed by the XMLGUI framework (explained in depth later) it must be added to the application's ''action collection''. The action collection is accessed via the <tt>actionCollection()</tt> function like this:
<code cppqt>
actionCollection()->addAction("clear", clearAction);
</code>
Here, the <tt>clearAction</tt> KAction is added to the collection and given a name of ''clear''. This name (''clear'') is used by the XMLGUI framework to refer to the action, ergo, it should not be localized, since it is used internally only.

====Connecting the action====
Now that the action is fully set up, it needs to be connected to something useful. In this case (because we want to clear the text area), we connect our action to the <tt>clear()</tt> action belonging to a KTextEdit (which, unsurprisingly, clears the KTextEdit)
<code cppqt>
connect( clearAction, SIGNAL( triggered(bool) ),
textArea, SLOT( clear() ) );
</code>
This is the same as it would be done in Qt with a {{qt|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 [http://api.kde.org/4.0-api/kdelibs-apidocs/kdeui/html/namespaceKStandardAction.html KStandardAction].

They are very simple to use. Once the library has been included (<tt>#include <KStandardAction></tt>), simply supply it with what you want the function to do and which KActionCollection to add it to. For example:
<code cppqt>KStandardAction::quit(kapp, SLOT(quit()), actionCollection());</code>
This creates a KAction with the correct icon, text and shortcut and even adds it to the File menu.

==Adding the action to menus and toolbars==
At the moment, the new "Clear" action has been created but it hasn't been associated with any menus or toolbars. This is done with a KDE technology called XMLGUI, which does nice things like movable toolbars for you.

{{note|In a later version of KDE4, XMLGUI, may be replaced with a new framework called liveui. For now, XMLGUI, is the only and correct way to set up the UI.}}

==XMLGUI==

The <tt>setupGUI()</tt> function in {{class|KXmlGuiWindow}} depends on the XMLGUI system to construct the GUI, which XMLGUI does by parsing an XML file description of the interface.

The rule for naming this XML file is <tt>appnameui.rc</tt>, where <tt>appname</tt> is the name you set in {{class|KAboutData}} (in this case, ''tutorial3''). So in our example, the file is called <tt>tutorial3ui.rc</tt>, and is located in the build directory. Where the file will ultimately be placed is handled by CMake.

''See also'' [http://developer.kde.org/documentation/library/kdeqt/kde3arch/xmlgui.html developer.kde.org] which still provides valid information for KDE4.

==''appname''ui.rc File==

Since the description of the UI is defined with XML, the layout must follow strict rules. This tutorial will not go into great depth on this topic, but for more information, see the [[Development/Architecture/KDE4/XMLGUI_Technology|detailed XMLGUI page]] (here is an older tutorial: [http://developer.kde.org/documentation/tutorials/xmlui/preface.html]).

===tutorial3ui.rc===
<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<gui name="tutorial3" version="1">
<ToolBar name="mainToolBar" >
<text>Main Toolbar</text>
<Action name="clear" />
</ToolBar>
<MenuBar>
<Menu name="file" >
<Action name="clear" />
</Menu>
</MenuBar>
</gui>
</code>

The <tt><Toolbar></tt> tag allows you to describe the toolbar, which is the bar across the top of the window normally with icons. Here it is given the unique name ''mainToolBar'' and its user visible name set to ''Main Toolbar'' using the <tt><text></tt> tag. The clear action is added to the toolbar using the <tt><Action></tt> tag, the name parameter in this tag being the string that was passed to the KActionCollection with <tt>addAction()</tt> in <tt>mainwindow.cpp</tt>.

Besides having the action in the toolbar, it can also be added to the menubar. Here the action is being added to the ''File'' menu of the <tt>MenuBar</tt> the same way it was added to the toolbar.

Change the 'version' attribute of the <tt><nowiki><gui></nowiki></tt> tag if you changed .rc file since the last install to force a system cache update.

Some notes on the interaction between code and the .rc file: Menus appear automatically and should have a <tt><nowiki><text/></nowiki></tt> child tag unless they refer to standard menus. Actions need to be created manually and inserted into the actionCollection() using the name in the .rc file. Actions can be hidden or disabled, whereas menus can't.

==CMake==
Finally, the <tt>tutorial3ui.rc</tt> needs to go somewhere where KDE can find it (can't just leave it in the source directory!). '''This means the project needs to be installed somewhere.'''
===CMakeLists.txt===
<code ini>
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)
</code>

This file is almost identical to the one for tutorial2, but with two extra lines at the end that describe where the files are to be installed. Firstly, the <tt>tutorial3</tt> target is installed to the <tt>BIN_INSTALL_DIR</tt> then the <tt>tutorial3ui.rc</tt> file that describes the layout of the user interface is installed to the application's data directory.

===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. You probably just want to install it somewhere local for testing (it's probably a bit silly to go to the effort of installing these tutorials to your KDE directory), so the following might be appropriate:
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=$HOME
make install
$HOME/bin/tutorial3
which will create a KDE-like directory structure in your user's home directory directory and will install the executable to {{path|$HOME/bin/tutorial3}}.

==Moving On==
Now you can move on to [[Development/Tutorials/Saving_and_loading|saving and loading]].

[[Category:C++]]

Development/Languages/Python

2008-12-04T14:42:52Z

Chris: /* Documentation and Tutorials */ Phonon Example

{{Template:I18n/Language Navigation Bar|Development/Languages/Python}}

Python is a powerful object oriented, dynamic language. You can find out more about the language itself on the Python website at http://www.python.org/.

Two important pieces of software are needed to develop KDE applications using Python, [http://www.riverbankcomputing.co.uk/software/pyqt/intro PyQt] and PyKDE. PyQt provides Python support for the Qt library which KDE is built on. PyQt can be obtained at http://www.riverbankcomputing.co.uk/software/pyqt/ . Riverbank Computing has a lot of good documentation about how to use PyQt to create pure Qt applications. If you are new to KDE / Python development, then learning how to use PyQt is the best first step.

PyKDE builds on top of PyQt and adds Python support for KDE's libraries and technologies.

PyKDE is distributed as part of the kdebindings module. Stable releases can be downloaded from the normal [http://kde.org/download/ KDE download page], although it is usually easier to install pre-built packages from your operating system distribution. You can also obtain PyKDE from KDE's subversion repository:

svn co svn://anonsvn.kde.org/home/kde/trunk/KDE/kdebindings/python/pykde4

The code in subversion can be browsed online via http://websvn.kde.org/trunk/KDE/kdebindings/python/pykde4/.

==Documentation and Tutorials==
* [http://www.riverbankcomputing.co.uk/software/pyqt/intro PyQt home page and documentation]
* [[/Using PyKDE 4|Using PyKDE 4]]
* [[/PyKDE_WebKit_Tutorial|PyKDE WebKit Tutorial]], a simple web browser application in PyKDE
* [http://api.kde.org/pykde-4.1-api/ KDE API class reference for PyKDE 4.1].
* [[Development/Tutorials/Python introduction to signals and slots|introduction to signals and slots]]
* [http://www.rkblog.rk.edu.pl/w/p/introduction-pyqt4/ Introduction article about PyQt4]
* [[Development/Tutorials/Phonon/Introduction/Python|Phonon Example]]

===KDE 3 and PyKDE 3===
Documentation and tutorials for the older PyQt and PyKDE 3.
* [http://vizzzion.org/?id=pyqt Python-Qt tutorial] '' In this tutorial, the basic steps of creating a Qt-based application with PyQt are explained. ''

==Further reading and information==
*[http://www.riverbankcomputing.com/mailman/listinfo/pyqt PyQt and PyKDE mailing list]
*[http://www.riverbankcomputing.co.uk/software/pykde/intro PyKDE Homepage]
*[http://www.diotavelli.net/PyQtWiki The PyQt and PyKDE community Wiki]
*The book [http://www.qtrac.eu/pyqtbook.html Rapid GUI Programming with Python and Qt] is available and covers Qt 4 programming with Python.
*The IRC channel ''#kubuntu-devel'' on freenode often has PyKDE programmers in it.

==Applications using PyKDE==
*[http://utils.kde.org/projects/printer-applet/ printer-applet]
*[http://websvn.kde.org/trunk/KDE/kdeadmin/system-config-printer-kde/ system-config-printer-kde]
*[http://websvn.kde.org/trunk/extragear/utils/guidance-power-manager/ Guidance Power Manager], a battery applet
*[https://code.launchpad.net/ubiquity/trunk Ubiquity], installer for Kubuntu
*[https://code.launchpad.net/~ubuntu-core-dev/gdebi/ubuntu GDebi], .deb package installer
*[https://code.launchpad.net/~jr/install-package/trunk install-package], graphical apt-get
*[http://websvn.kde.org/trunk/KDE/kdebindings/python/pykde4/examples/ some examples are in the PyKDE source]

[[Category:Python]]

Development/Tutorials/Phonon/Introduction/Python

2008-12-03T10:41:23Z

Chris: Behold C++ programmers, in your face! Python is so beautiful =)

This is the Python port of tutorial2.cpp found under [[Development/Tutorials/Phonon/Introduction]].

<pre>
#This file is part of the KDE project
#Copyright (C) 2007 Matthias Kretz <kretz@kde.org>
#adapted 2008 by Thorsten Staerk
#ported to PyQt4 by Christoph Burgmer

#Permission to use, copy, modify, and distribute this software
#and its documentation for any purpose and without fee is hereby
#granted, provided that the above copyright notice appear in all
#copies and that both that the copyright notice and this
#permission notice and warranty disclaimer appear in supporting
#documentation, and that the name of the author not be used in
#advertising or publicity pertaining to distribution of the
#software without specific, written prior permission.

#The author disclaim all warranties with regard to this
#software, including all implied warranties of merchantability
#and fitness. In no event shall the author be liable for any
#special, indirect or consequential damages or any damages
#whatsoever resulting from loss of use, data or profits, whether
#in an action of contract, negligence or other tortious action,
#arising out of or in connection with the use or performance of
#this software.

import sys

from PyQt4.QtGui import QApplication, QMainWindow, QDirModel, QColumnView
from PyQt4.QtGui import QFrame
from PyQt4.QtCore import SIGNAL
from PyQt4.phonon import Phonon

class MainWindow(QMainWindow):

m_model = QDirModel()

def __init__(self):
QMainWindow.__init__(self)
self.m_fileView = QColumnView(self)
self.m_media = None

self.setCentralWidget(self.m_fileView)
self.m_fileView.setModel(self.m_model)
self.m_fileView.setFrameStyle(QFrame.NoFrame)

self.connect(self.m_fileView,
SIGNAL("updatePreviewWidget(const QModelIndex &)"), self.play)

def play(self, index):
self.delayedInit()
#self.m_media.setCurrentSource(self.m_model.filePath(index))
self.m_media.setCurrentSource(
Phonon.MediaSource(self.m_model.filePath(index)))
self.m_media.play()

def delayedInit(self):
if not self.m_media:
self.m_media = Phonon.MediaObject(self)
audioOutput = Phonon.AudioOutput(Phonon.MusicCategory, self)
Phonon.createPath(self.m_media, audioOutput)

def main():
app = QApplication(sys.argv)
QApplication.setApplicationName("Phonon Tutorial 2 (Python)")
mw = MainWindow()
mw.show()
sys.exit(app.exec_())

if __name__ == '__main__':
main()
</pre>

Development/Tutorials/Phonon/Introduction

2008-12-03T10:38:37Z

Chris: Python example

In order to make the revision process clear, I introduce a confident index, "0" means nobody except me has reviewed the text. I please the reviewers to increment the counter to prove the validity of the tutorials.

You can get help on #phonon on irc.freenode.org.
----

See [[Development/Tutorials/Phonon/Introduction/Python]] for the same example in Python.

= Introduction =
''Confident Index =1''

The following is based on the documentation available here
[http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.0/kdelibs-apidocs/phonon/html/index.html Phonon API].

By getting involved with Phonon, you can choose between three different main tasks.
* '''Using the Phonon API''', which allows you to develop your own multimedia application. In fact any application which needs sound can take benefits from the phonon API. In the tutorials showing the API we will learn how to set up the development environment with kdevelop 3.4.

* '''Hacking the Phonon library''', (try to develop more this topic).

* '''Writing Phonon backend''', this consists in writing interfaces that allows Phonon to use different sound/video engine. This usually requires good skills and knowledge of the engine you interface with.

Beginners will probably be more interested by the first task.

= Using the phonon API =
The following example is taken from http://www.englishbreakfastnetwork.org/apidocs/apidox-kde-4.0/kdelibs-apidocs/phonon/html/index.html. It lets you choose a multimedia file and tries to play it. To change the sound device that is used by default, use the command <tt>systemsettings</tt>.

== tutorial2.cpp ==
<pre>
/* This file is part of the KDE project
Copyright (C) 2007 Matthias Kretz <kretz@kde.org>
adapted 2008 by Thorsten Staerk

Permission to use, copy, modify, and distribute this software
and its documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appear in all
copies and that both that the copyright notice and this
permission notice and warranty disclaimer appear in supporting
documentation, and that the name of the author not be used in
advertising or publicity pertaining to distribution of the
software without specific, written prior permission.

The author disclaim all warranties with regard to this
software, including all implied warranties of merchantability
and fitness. In no event shall the author be liable for any
special, indirect or consequential damages or any damages
whatsoever resulting from loss of use, data or profits, whether
in an action of contract, negligence or other tortious action,
arising out of or in connection with the use or performance of
this software.
*/

#include <phonon/mediaobject.h>
#include <phonon/path.h>
#include <phonon/audiooutput.h>

#include <QtGui/QApplication>
#include <QtGui/QMainWindow>
#include <QtGui/QDirModel>
#include <QtGui/QColumnView>

class MainWindow : public QMainWindow
{
Q_OBJECT
public:
MainWindow();

private slots:
void play(const QModelIndex &index);

private:
void delayedInit();

QColumnView m_fileView;
QDirModel m_model;

Phonon::MediaObject *m_media;
};

MainWindow::MainWindow()
: m_fileView(this),
m_media(0)
{
setCentralWidget(&m_fileView);
m_fileView.setModel(&m_model);
m_fileView.setFrameStyle(QFrame::NoFrame);

connect(&m_fileView, SIGNAL(updatePreviewWidget(const QModelIndex &)), SLOT(play(const QModelIndex &)));
}

void MainWindow::play(const QModelIndex &index)
{
delayedInit();
m_media->setCurrentSource(m_model.filePath(index));
m_media->play();
}

void MainWindow::delayedInit()
{
if (!m_media) {
m_media = new Phonon::MediaObject(this);
Phonon::AudioOutput *audioOutput = new Phonon::AudioOutput(Phonon::MusicCategory, this);
createPath(m_media, audioOutput);
}
}

int main(int argc, char **argv)
{
QApplication app(argc, argv);
QApplication::setApplicationName("Phonon Tutorial 2");
MainWindow mw;
mw.show();
return app.exec();
}

#include "tutorial2.moc"
</pre>

== Compile and run it ==
moc tutorial2.cpp > tutorial2.moc
g++ -o tutorial -lphonon tutorial2.cpp && ./tutorial

Eventually add a "-I/usr/include/qt4" to tell q++ where to look for the header files.

[[Category:KDE4]]
[[Category:Phonon]]

Projects/Marble/HistoricalMaps

2008-10-30T12:56:09Z

Chris: Replaced by better quality

====Historical Maps for Marble====
We'd like to add Historical Maps to Marble. Ideally one would later on be able to travel through time using a slider later on.
For now we concentrate on a more simple approach:

There are lots of very early world maps that are under the public domain. You'll find several on Wikipedia (please add further ones to the list as you find them) and elsewhere on the internet:

* [[/WorldMapSchagen1689|Historical World Map: G. van Schagen (1689) ]]
-- Magnus has completed this one already
* [http://commons.wikimedia.org/wiki/Image:Leonhard_Euler_World_Map_AD1760.jpg Leonhard Euler World Map 1760]
* [http://commons.wikimedia.org/wiki/Image:Moll_-_A_new_map_of_the_whole_world_with_the_trade_winds.png Moll - A new map of the world with the trade winds]
* [http://commons.wikimedia.org/wiki/Image:Nova_Orbis_Tabula_in_Lucem_Edita.jpg Nova Orbis Tabula in Lucem Edita]
* [http://memory.loc.gov/cgi-bin/map_item.pl?data=/home/www/data/gmd/gmd3/g3200/g3200/ct000725.jp2&style=gmd&itemLink=r?ammem/gmd:@field(NUMBER+@band(g3200+ct000725))&title=Universalis%20cosmographia%20secundum%20Ptholomaei%20traditionem%20et%20Americi%20Vespucii%20alioru%5Bm%5Dque%20lustrationes. <nowiki>Universalis cosmographia secundum Ptholomaei traditionem et Americi Vespucii alioru[m]que lustrationes.</nowiki>] ([http://www.loc.gov/rr/geogmap/waldexh.html General information])

====Licensing====

If you find new maps it's always important to check the license. Although ancient maps should usually be under the public domain there are several people who claim copyright on the data due to the image manipulation work they have done as a part of post-processing the scan. No matter whether this is legitimate or not we should respect those claims and look for data that was intended to be published under the public domain (or another free license) and use that.

It's important to note that people like to distribute imagery "free for non-commercial usage". Unfortunately we are not able to use and distribute this data as this would e.g. prohibit most Linux Distributors from distributing our software.
So do not use data that is "free for non-commercial use"! It's not suitable for our purposes. If you think that there is a chance that the author might agree to change the license to a less restrictive one then it might be worth to contact him. However pretty often the "non-commercial" wording is provided intentionally this way to allow for a business case of the author.

====Preparing Historical Maps for use in Marble====
Maps for Marble need to get provided in [http://en.wikipedia.org/wiki/Plate_carrée_projection plate carrée projection] (also referred
to as "Equirectangular projection"):

There are morphing tools and HOWTOS on the web that can tell you how to morph
ancient maps into the desired projection. It doesn't require too many skills. Just some patience and love to detail.

You can have a look at [http://spin3d.com/ Spin3D] for a source of inspiration. Please consider to use Free Software instead of Morph Man (e.g. xmorph).

The "rectangular image" that is the result after half of the tutorial is
what you need.

Development/Tutorials/Printing Hello World

2008-07-24T22:53:01Z

Chris:

{{note|This tutorial seems not to be up to date with current KDE4 development.}}

=The mission=
Print '''Hello World''' on your printer.

=The KDE version=
This code will work for KDE 3 as for KDE 4.

=The code=
<code cppqt n>
#include <kprinter.h>
#include <qpainter.h>
#include <kapplication.h>
#include <kaboutdata.h>
#include <kmessagebox.h>
#include <kcmdlineargs.h>

/*
This prints Hello World on your printer
*/

int main(int argc, char *argv[])
{
KAboutData aboutData( "test", "test", "1.0", "test",
KAboutData::License_GPL, "(c) 2006" );
KCmdLineArgs::init( argc, argv, &aboutData );
KApplication app;

KPrinter job;
job.setFullPage( true );
if ( job.setup() )
{
QPainter painter;
painter.begin( &job );
painter.drawText(100,100,"Hello World");
painter.end();
// this makes the print job start
}
}
</code>

=Explanation=
You need a KDE instance to print, because this instance stores your configuration, including your printer configuration. You create one by instanciating the KApplication class.

=How to compile=
==With KDE 4 and CMake==
===CMakeLists.txt===
<code>
find_package(KDE4 REQUIRED)
include_directories( ${KDE4_INCLUDES} )
kde4_add_executable(printhelloworld printtest.cpp)
target_link_libraries(printhelloworld ${KDE4_KDEPRINT_LIBS})
</code>
===Make and Run===
Then do:
cmake .
make
./printhelloworld

==With KDE 3==
Quite easy:
gcc printtest.cpp -o print -I/usr/lib/qt3/include \
-I/opt/kde3/include -L/opt/kde3/lib \
-L/usr/lib/qt3/lib -lqt-mt -lkdeprint

=See also=
* Point your konqueror to [http://developer.kde.org/documentation/library/cvs-api/kdelibs-apidocs/kdeprint/html/classKPrinter.html kde:kprinter]
[[Category:KDE4]]
[[Category:C++]]

Development/Tutorials/Localization/i18n Mistakes

2008-07-24T20:07:56Z

Chris: + pitfall #4, see the bug filed against Amarok for the Chinese example

{{Template:I18n/Language Navigation Bar|Development/Tutorials/Localization/i18n Mistakes}}

{{TutorialBrowser|

series=Localization|

name=Avoiding Common Localization Pitfalls|

pre=[[../i18n|Writing Applications With Localization in Mind]]|

next=[[../i18n_Build_Systems|Incorporating i18n Into the Build System]]|

}}

== Abstract ==

There are a few common pitfalls that prevent applications from being properly translated or otherwise localized. These include using pixel based layouts, "word puzzles" and writing code that does not deal with Unicode characters properly. This tutorial covers each of these issues, explaining what to avoid and how to do it properly.

== Pitfall #1: Pixel Based Layouts ==

English text is often very compact compared to other languages where the translated text is often substantially longer. Therefore the interface must be able to adjust size to accommodate the length of translations provided at runtime. If it can't do this, then messages will end up misaligned and truncated.

The answer is to use layout managers. Qt provides a number of such layout managers pre-made for you. They include <tt>QHBoxLayout</tt>, <tt>QVBoxLayout</tt>, <tt>QGridLayout</tt> and <tt>QStackedLayout</tt>, all of which are subclasses of <tt>QLayout</tt>. You may also create your own <tt>QLayout</tt> based classes, but this is generally not needed.

These layout classes manage the pixel positioning of widgets for you at runtime, so no matter what the size of the translated strings your interface will adjust properly. For more information look at the documentation for {{qt|QLayout}}.

== Pitfall #2: Word Puzzles ==

Another thing to be aware of is to not concatenate pieces of sentences together like this:

<code cppqt>
QString msg=i18n("Do you want to replace ") +
oldFile+i18n(" with ") +
newFile + "?"</code>

Such "word puzzles" are very hard or even impossible to translate. This is because the structure of the sentence will often be completely different in another language and thus must be controlled by the translator. When the order of words and phrases is hard-coded as in the above example, the translator can not create a proper translation.

Adding to this problem, a translator will only see parts of the sentence while translating and will have to guess at what belongs together.

The solution thankfully is quite simple: use <tt>%number</tt> placeholder substitution, which lets the translators not only make good translations because they can see the entirety of the sentence during translation, but which also lets them change the order of the arguments freely. The arguments themselves are passed as extra parameters to <tt>i18n()</tt>.

The above example written properly would then look like this:

<code cppqt>
QString msg = i18n("Do you want to replace %1 with %2?",
oldFile, newFile)</code>

{{note|Avoid inserting anything other than numbers or nouns with this method, since in some languages the translation depends on the inserted words. It is therefore best to create strings that are as complete sentences as possible.}}

A related mistake is not including markup tags in rich text, such as or , in the translatable string. Not all languages use such markup in an identical fashion to English and so it is necessary for the translator to be able to "translate" the markup accordingly as well.

Similarly, messages that contain a version string or other often changing parts should be inserted by placeholders into the message. This prevents unnecessary changes that cause the translators to have to change the translated messages as well.

Since KDE is translated into more than 65 languages a single string change causes at least 65 people to open the file, find the changed message, look carefully if this is the only thing that has changed, change the translation, save the file again and commit the changed file into the code repository. All in all such a small change might create hours of work which could be easily avoided.

== Pitfall #3: Lack of Unicode Support ==

Whenever there is source code that handles strings using a datatype (such as <tt>char</tt>) or class (such as <tt>std::string</tt>) that can not handle Unicode, translations will break.

To avoid this, never call QString::latin1() or QString::ascii() on translated strings. This also applies to information resulting from user input such as passwords, URLs and filenames. If you really need a plain <tt>char*</tt> representation of a string, it is better to use QString::utf8().

{{note|For more information on character sets and Unicode, see the [[Development/Tutorials/Localization/Unicode|Unicode tutorial]].}}

KIO slaves may also provide paths and file names encoded using UTF-8. It is up to the programmer, however, to take care of passing properly encoded filenames to any KIO method in question. The correct way to do this is not to guess at user's filesystem encoding but to use QFile::encodeName() and QFile::decodeName() instead.

{{tip|You can turn KIO's UTF-8 file name support on for testing by exporting the KDE_UTF8_FILENAMES environment variable in your shell's startup file (e.g. ~/.bashrc).}}

== Pitfall #4: Complex Text Flow ==

When designing an application that needs non-standard text flow, don't assume that the same rules apply for all languages. Given vertical writing as an example East-Asian languages using Chinese characters have a long history of vertical writing, even longer then horizontal. Strings are not rotated by 90 degrees but instead single characters are placed under one another. There might be just a different behaviour with different scripts. Expect the need to implement specialised versions.

== Success! ==

If you avoid the three common categories of pitfalls detailed in this tutorial, your application should be fully localizable by the various KDE translation teams around the world and open up your application to the majority of people on the planet.

[[Category:Programming]]

Contribute/Bugsquad/BugDays/AmarokDay1/Bugs needing users with particular setups

2008-06-17T18:58:42Z

Chris:

===Bugs needing users with particular setups===
Bugs that require particular software or hardware that you don't have available should be listed here with a description of the non-standard requirement.

*{{Bug|118288}} Requires a proxy setup for port 80. [[User:Mdhowe|Mdhowe]]

*<s>{{Bug|116220}} Needs KDE3 running, i really want to close this as INVALID or something :P [[User:Blauzahl|Blauzahl]]</s>
**<s>Ramblurr says that if this still exists, its a WONTFIX</s>
**<s>ack for WONTFIX --[[User:Nightrose|Nightrose]] 09:52, 15 June 2008 (CEST)</s>[[User:Blauzahl|Blauzahl]]

*{{Bug|119087}} Needs KDE3. [[User:Mdhowe|Mdhowe]]
** WONTFIX - even if it is still present we will not fix it --[[User:Nightrose|Nightrose]] 09:52, 15 June 2008 (CEST)

*<s>{{Bug|114285}} Needs two screens [[User:Blauzahl|Blauzahl]]</s>
** <s>very old - likely fixed - WONTFIX anyway --[[User:Nightrose|Nightrose]] 09:52, 15 June 2008 (CEST)</s> closed as REMIND with a message to reopen if it exists in 2 [[User:Blauzahl|Blauzahl]]

*{{Bug|119026}} Requires a RTL language setup such as Arabic or Hebrew. [[User:Mdhowe|Mdhowe]]
** close due to lag of feedback - WONTFIX anyway --[[User:Nightrose|Nightrose]] 09:52, 15 June 2008 (CEST)
** I'd close it as a REMIND, who knows, maybe they'll give you a patch for 2 :D [[User:Blauzahl|Blauzahl]]

*{{Bug|112437}} Needs a proxy [[User:Kage Jittai|Kage Jittai]]

*{{Bug|137346}} crash Needs portable media device to check. [[User:Lemma|Lemma]]

*{{Bug|133609}} Can't get transcode working [[User:progger1986|progger1986]]

*{{Bug|133764}} Needs a DAAP share [[User:progger1986|progger1986]]

*{{Bug|130597}} Need some unplayable files, reporter mentions m4a -- [[User:Aides|Aides]]

*{{Bug|134544}} Needs almost none free disk space [[User:progger1986|progger1986]]

*{{Bug|134614}} Needs mDNSresponder and iTunes 7 [[User:progger1986|progger1986]]

*{{Bug|134718}} Needs cue sheets ans last.fm account [[User:progger1986|progger1986]]

*{{Bug|130929}} Needs media device -- [[User:Aides|Aides]]

*{{Bug|134416}} Needs DAAP client [[User:progger1986|progger1986]]

*{{bug|139030}} - Needs someone with a lot of mp3 files and PostgreSQL. [[User:Lemma|Lemma]]

*{{bug|138240}} - patch Needs someone with a portable media device, includes a patch. [[User:Lemma|Lemma]]

*{{bug|138743}} - crash Needs an mtp mp3 player. [[User:Lemma|Lemma]]

*{{bug|138850}} - Needs someone with an ipod to check. [[User:Lemma|Lemma]]

*{{bug|139218}} - Needs a Creative Vision M portable media device to check. [[User:Lemma|Lemma]]

*{{bug|139271}} - Needs a Creative Zen Vision portable media device to check. [[User:Lemma|Lemma]]

*{{bug|135466}} need an Ogg with multiple logical streams -- [[User:Aides|Aides]]

*{{bug|135665}} need an iPod -- [[User:Aides|Aides]]

*{{bug|135681}} need a media device. -- [[User:Aides|Aides]]

*{{bug|135938}} need a Samba share -- [[User:Aides|Aides]]

*{{bug|135823}} yet to be tested with amarok 2, mark as LATER (conf. by Nightrose) -- [[User:Aides|Aides]]

*{{bug|136153}} should be fixed with recent libgpod (as stated in last comment), but can't verify without iPod -- [[User:Aides|Aides]]

*{{bug|139805}} - Needs a portable media device. [[User:Lemma|Lemma]]

*{{bug|139836}} - Needs someone with Amarok/MySQL to recheck. [[User:Lemma|Lemma]]

*{{bug|140170}} - Needs someone with a MTP media device to check. [[User:Lemma|Lemma]]

*{{bug|140752}} - Needs a podcast with a missing file (possibly a webserver 404 error page). [[User:Lemma|Lemma]]

*{{bug|140752}} - Needs IPod-Nano. Most likely resolved in 1.4.9.1 [[User:Leuty|Leuty]]

*{{bug|142680}} need media with cue-sheet -- [[User:Aides|Aides]]

*{{bug|143421}} need someone to test podcast issues -- [[User:Aides|Aides]]

*{{bug|143485}} another cue-sheet related bug -- [[User:Aides|Aides]]

*{{Bug|139538}} - Need a Sandisk player [[User:Krop|Krop]]

*{{Bug|139772}} - Need someone running KDE3 and Amarok 1.4 (global shortcuts have no effects in KDE4) [[User:Krop|Krop]]

*{{Bug|127832}} Requires a collection over NFS to test [[User:Kage Jittai|Kage Jittai]]

*{{Bug|140270}} - Need a MTP compatible device [[User:Krop|Krop]]

*{{Bug|147755}} needs East Asian locale -- [[User:Aides|Aides]]
*:Actually if the language files are all included, all you need to do is switch the language under the help menu. See the screenshot attached to the bug, to check if the script is still rotated, or if it's written top-down. Sorry, can't check, no nightly builds for Debian :(. But I'll evaluate a screenshot if you give me one. --[[User:Chris|Chris]] 20:58, 17 June 2008 (CEST)
*{{bug|147890}} complex setup, involving NFS shares, MySQL backend and some 60000 items in collection -- [[User:Aides|Aides]]

*{{bug|148108}} need an iPod; bug has been updated recently, reporter is feedbackful -- [[User:Aides|Aides]]

*{{bug|148692}}, {{bug|148691}} and {{bug|154495}} all need CUE files to be tested. Amarok really seems not to handle CUE files correctly. --[[User:Mamarok|Mamarok]] 13:54, 17 June 2008 (CEST)