KDE TechBase - User contributions [en]

Schedules/KDE4/4.1 Release Goals

2008-01-20T22:15:49Z

CuCullin: KDE on Windows Link

Goals for the 4.1 Release:

* [[Projects/KDE_on_Windows|Windows port]] (Framworks and Applications)
* [[Projects/KDE_on_Mac_OS_X|Mac port]] (Frameworks and Applications)
* OpenSolaris port
* Plasma with widgets on canvas, makes things like layouting much easier, and generally integrating widgets into Plasmoids
* Webkit in Plasma
* GStreamer, Quicktime, DirectShow9 Phonon backends
* Apple dashboard widgets support in Plasma
* Decibel VOIP and real-time communication framework
* Dragon Player multimedia player
* Kaider computer-aided translation system
* More polished Kopete
* KDevelop and KDevplatform modules
* KDE-PIM module, with some Akonadi functionality
* Move Akonadi library into the kdepimlibs module
* GetHotNewStuff2 / DXS
* Plasmagik plasma packages and add-on creator
* Lots of smaller features

Development/Languages/Perl

2007-07-03T17:15:16Z

CuCullin: Created page

Perl is a powerful and versatile high-level programming language. You can find out more about the language itself on the [http://www.perl.org/ Perl Mongers website].

Complete object-oriented bindings for Qt based on [[Development/Languages/Smoke|SMOKE]] are available on the [http://perlqt.sourceforge.net/ PerlQt project page].

Those bindings provide virtual functions overloading, custom slots and signals, and Rapid Application Development (RAD) through puic, a Qt Designer compatible user interface compiler.

Projects/Oxygen/Sound Theme Naming Specification

2007-01-31T19:40:16Z

CuCullin:

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

Sound is an important element used to communicate with users. It is important, then, that there be a unified and simplified way of organizing sounds.

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Critical Stop
* Default Beep
* Show Toolbar
* System Notification

{| border="1"
|+ Table 3. System Events
! Name !! Description !! Filename
|-
| Startup || ||
|-
| Shutdown || ||
|-
| Hibernate || ||
|-
| Standby || ||
|-
| Logon || ||
|-
| Logoff || ||
|-
| Logon error || ||
|}

== User Interface Events ==
=== Desktop UI ===

{| border="1"
|+ Table 3. Desktop UI
! Name !! Description !! Filename
|-
| Minimize || ||
|-
| Minimize to Tray || ||
|-
| Maximize || ||
|-
| Restore || ||
|-
| Restore from Tray || ||
|-
| Shade Up || ||
|-
| Shade Down || ||
|-
| Icon Hover || ||
|-
| Icon Select || ||
|}

=== Menu UI ===

{| border="1"
|+ Table 3. Menu UI
! Name !! Description !! Filename
|-
| Menu Button Select || Selecting the K Menu || menu-button-select
|-
| Menu Browse || Browsing through the menu, on a new menu item hover || menu-browse
|-
| Menu Item Select || Selecting a menu item || menu-item-select
|}

== Application Level Events ==

=== Communication Events ===

{| border="1"
|+ Table 3. Communication Events
! Name !! Description !! Filename
|-
| New Email || A new email message is received || new-email
|-
| New IM || a new instant message is received || new-message
|-
| New alert || ||
|-
| Name mentioned in chat room? || ||
|-
| Connected to messaging service || ||
|-
| Disconnected from messaging service || ||
|-
| Person Joins || ||
|-
| Person Leaves || ||
|-
| Receive Call || ||
|-
| Receive Request to Join || ||
|-
| Contact Online || ||
|}

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== Hardware Events ==

{| border="1"
|+ Table 3. Hardware Events
! Name !! Description !! Filename
|-
| Battery Charging || ||
|-
| Running on AC || ||
|-
| Low Battery Alarm || ||
|-
| Critical Battery Alarm || ||
|-
| Device Connected || ||
|-
| Device Disconnected || ||
|-
| Device Failed to Connect || ||
|-
| Print sent to Queue || ||
|-
| Print Complete || ||
|}

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Projects/Oxygen/Sound Theme Naming Specification

2007-01-30T15:32:08Z

CuCullin: /* Hardware Events */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

Sound is an important element used to communicate with users. It is important, then, that there be a unified and simplified way of organizing sounds.

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
* Critical Stop
* Default Beep
* Exit
* Menu Popup
* Open Program
* Program Error
* Question
* Restore Down
* Restore Up
* Select
* Show Toolbar
* System Notification
* Logoff
* Logon

== User Interface Events ==
=== Desktop UI ===

{| border="1"
|+ Table 3. Desktop UI
! Name !! Description !! Filename
|-
| Minimize || ||
|-
| Minimize to Tray || ||
|-
| Maximize || ||
|-
| Restore || ||
|-
| Restore from Tray || ||
|-
| Shade Up || ||
|-
| Shade Down || ||
|-
| Icon Hover || ||
|-
| Icon Select || ||
|}

=== Menu UI ===

{| border="1"
|+ Table 3. Menu UI
! Name !! Description !! Filename
|-
| Menu Button Select || Selecting the K Menu || menu-button-select
|-
| Menu Browse || Browsing through the menu, on a new menu item hover || menu-browse
|-
| Menu Item Select || Selecting a menu item || menu-item-select
|}

== Application Level Events ==

=== Communication Events ===

{| border="1"
|+ Table 3. Communication Events
! Name !! Description !! Filename
|-
| New Email || A new email message is received || new-email
|-
| New IM || a new instant message is received || new-message
|-
| New alert || ||
|-
| Name mentioned in chat room? || ||
|-
| Connected to messaging service || ||
|-
| Disconnected from messaging service || ||
|-
| Person Joins || ||
|-
| Person Leaves || ||
|-
| Receive Call || ||
|-
| Receive Request to Join || ||
|-
| Contact Online || ||
|}

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== Hardware Events ==

{| border="1"
|+ Table 3. Hardware Events
! Name !! Description !! Filename
|-
| Battery Charging || ||
|-
| Running on AC || ||
|-
| Low Battery Alarm || ||
|-
| Critical Battery Alarm || ||
|-
| Device Connected || ||
|-
| Device Disconnected || ||
|-
| Device Failed to Connect || ||
|-
| Print sent to Queue || ||
|-
| Print Complete || ||
|}

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Projects/Oxygen/Sound Theme Naming Specification

2007-01-30T15:31:44Z

CuCullin: /* Communication Events */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

Sound is an important element used to communicate with users. It is important, then, that there be a unified and simplified way of organizing sounds.

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
* Critical Stop
* Default Beep
* Exit
* Menu Popup
* Open Program
* Program Error
* Question
* Restore Down
* Restore Up
* Select
* Show Toolbar
* System Notification
* Logoff
* Logon

== User Interface Events ==
=== Desktop UI ===

{| border="1"
|+ Table 3. Desktop UI
! Name !! Description !! Filename
|-
| Minimize || ||
|-
| Minimize to Tray || ||
|-
| Maximize || ||
|-
| Restore || ||
|-
| Restore from Tray || ||
|-
| Shade Up || ||
|-
| Shade Down || ||
|-
| Icon Hover || ||
|-
| Icon Select || ||
|}

=== Menu UI ===

{| border="1"
|+ Table 3. Menu UI
! Name !! Description !! Filename
|-
| Menu Button Select || Selecting the K Menu || menu-button-select
|-
| Menu Browse || Browsing through the menu, on a new menu item hover || menu-browse
|-
| Menu Item Select || Selecting a menu item || menu-item-select
|}

== Application Level Events ==

=== Communication Events ===

{| border="1"
|+ Table 3. Communication Events
! Name !! Description !! Filename
|-
| New Email || A new email message is received || new-email
|-
| New IM || a new instant message is received || new-message
|-
| New alert || ||
|-
| Name mentioned in chat room? || ||
|-
| Connected to messaging service || ||
|-
| Disconnected from messaging service || ||
|-
| Person Joins || ||
|-
| Person Leaves || ||
|-
| Receive Call || ||
|-
| Receive Request to Join || ||
|-
| Contact Online || ||
|}

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== Hardware Events ==

* Critical Battery Alarm
* Device Connect
* Device Disconnect
* Device Failed to Connect
* Low Battery Alarm
* '''Print Complete?'''

{| border="1"
|+ Table 3. Hardware Events
! Name !! Description !! Filename
|-
| Battery Charging || ||
|-
| Running on AC || ||
|-
| Low Battery Alarm || ||
|-
| Critical Battery Alarm || ||
|-
| Device Connected || ||
|-
| Device Disconnected || ||
|-
| Device Failed to Connect || ||
|-
| Print sent to Queue || ||
|-
| Print Complete || ||
|}

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Projects/Oxygen/Sound Theme Naming Specification

2007-01-30T15:31:23Z

CuCullin: /* Hardware Events */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

Sound is an important element used to communicate with users. It is important, then, that there be a unified and simplified way of organizing sounds.

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
* Critical Stop
* Default Beep
* Exit
* Menu Popup
* Open Program
* Program Error
* Question
* Restore Down
* Restore Up
* Select
* Show Toolbar
* System Notification
* Logoff
* Logon

== User Interface Events ==
=== Desktop UI ===

{| border="1"
|+ Table 3. Desktop UI
! Name !! Description !! Filename
|-
| Minimize || ||
|-
| Minimize to Tray || ||
|-
| Maximize || ||
|-
| Restore || ||
|-
| Restore from Tray || ||
|-
| Shade Up || ||
|-
| Shade Down || ||
|-
| Icon Hover || ||
|-
| Icon Select || ||
|}

=== Menu UI ===

{| border="1"
|+ Table 3. Menu UI
! Name !! Description !! Filename
|-
| Menu Button Select || Selecting the K Menu || menu-button-select
|-
| Menu Browse || Browsing through the menu, on a new menu item hover || menu-browse
|-
| Menu Item Select || Selecting a menu item || menu-item-select
|}

== Application Level Events ==

=== Communication Events ===

{| border="1"
|+ Table 3. Communication Events
! Name !! Description !! Filename
|-
| New Email || A new email message is received || new-email
|-
| New IM || a new instant message is received || new-message
|-
| New alert || ||
|-
| Name mentioned in chat room? || ||
|-
| Connected to messaging service || ||
|-
| Disconnected from messaging service || ||
|-
| Person Joins || ||
|-
| Person Leaves || ||
|-
| Receive Call || ||
|-
| Receive Request to Join || ||
|-
| Contact Online || ||
|}

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== Hardware Events ==

* Critical Battery Alarm
* Device Connect
* Device Disconnect
* Device Failed to Connect
* Low Battery Alarm
* '''Print Complete?'''

=== Communication Events ===

{| border="1"
|+ Table 3. Hardware Events
! Name !! Description !! Filename
|-
| Battery Charging || ||
|-
| Running on AC || ||
|-
| Low Battery Alarm || ||
|-
| Critical Battery Alarm || ||
|-
| Device Connected || ||
|-
| Device Disconnected || ||
|-
| Device Failed to Connect || ||
|-
| Print sent to Queue || ||
|-
| Print Complete || ||
|}

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Projects/Oxygen/Sound Theme Naming Specification

2007-01-30T15:29:17Z

CuCullin: /* Communication Events */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

Sound is an important element used to communicate with users. It is important, then, that there be a unified and simplified way of organizing sounds.

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
* Critical Stop
* Default Beep
* Exit
* Menu Popup
* Open Program
* Program Error
* Question
* Restore Down
* Restore Up
* Select
* Show Toolbar
* System Notification
* Logoff
* Logon

== User Interface Events ==
=== Desktop UI ===

{| border="1"
|+ Table 3. Desktop UI
! Name !! Description !! Filename
|-
| Minimize || ||
|-
| Minimize to Tray || ||
|-
| Maximize || ||
|-
| Restore || ||
|-
| Restore from Tray || ||
|-
| Shade Up || ||
|-
| Shade Down || ||
|-
| Icon Hover || ||
|-
| Icon Select || ||
|}

=== Menu UI ===

{| border="1"
|+ Table 3. Menu UI
! Name !! Description !! Filename
|-
| Menu Button Select || Selecting the K Menu || menu-button-select
|-
| Menu Browse || Browsing through the menu, on a new menu item hover || menu-browse
|-
| Menu Item Select || Selecting a menu item || menu-item-select
|}

== Application Level Events ==

=== Communication Events ===

{| border="1"
|+ Table 3. Communication Events
! Name !! Description !! Filename
|-
| New Email || A new email message is received || new-email
|-
| New IM || a new instant message is received || new-message
|-
| New alert || ||
|-
| Name mentioned in chat room? || ||
|-
| Connected to messaging service || ||
|-
| Disconnected from messaging service || ||
|-
| Person Joins || ||
|-
| Person Leaves || ||
|-
| Receive Call || ||
|-
| Receive Request to Join || ||
|-
| Contact Online || ||
|}

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== Hardware Events ==

* Critical Battery Alarm
* Device Connect
* Device Disconnect
* Device Failed to Connect
* Low Battery Alarm
* '''Print Complete?'''

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Development/Further Information

2007-01-30T15:22:36Z

CuCullin: /* IRC Channels */

== Web Sites ==
* [http://www.KDE.org KDE Home]
* [http://dot.kde.org KDE Dot News]
* [http://www.planetkde.org Planet KDE]

==Blogs==

== Books ==
Below are a list of books associated with KDE 4 development. These may be specific to applications, using the Qt Toolkit, or specifically KDE 4 books.

===KDE 4 Development Books===

===Qt 4 Development Books===

==== English ====

[http://www.phptr.com/bookstore/product.asp?isbn=0131879057&rl=1|The Book of Qt 4: The Art of Building Qt Applications By Alan Ezust, Paul Ezust.]

[http://www.phptr.com/bookstore/product.asp?isbn=0131872494&rl=1|C++ GUI Programming with Qt 4 By Jasmin Blanchette, Mark Summerfield.]

==== German ====

[https://www.opensourcepress.de/index.php?26&backPID=15&tt_products=23 Qt 4: Einführung in die Applikationsentwicklung von Daniel Molkentin]

== IRC Channels ==
In general, IRC channels mentioned here are available on FreeNode. Connect to irc.kde.org, and check these channels out for further information.

*KDE 4 Development - [irc://irc.kde.org:6667/kde4-devel #kde4-devel]
*KDE Development - [irc://irc.kde.org:6667/kde-devel #kde-devel]
*KDevelop - [irc://irc.kde.org:6667/kdevelop #kdevelop]
*Phonon - [irc://irc.kde.org:6667/phonon #phonon]
*Decibel - [irc://irc.kde.org:6667/decibel #decibel]
*Solid - [irc://irc.kde.org:6667/solid #solid]

== Newsgroups ==
== Forums ==
== Events ==
== Courses and Certifications ==
== Audio and Video Casts ==
== Source Code Repositories ==

Projects/Oxygen/Sound Theme Naming Specification

2007-01-30T15:20:48Z

CuCullin: /* Desktop UI */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

Sound is an important element used to communicate with users. It is important, then, that there be a unified and simplified way of organizing sounds.

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
* Critical Stop
* Default Beep
* Exit
* Menu Popup
* Open Program
* Program Error
* Question
* Restore Down
* Restore Up
* Select
* Show Toolbar
* System Notification
* Logoff
* Logon

== User Interface Events ==
=== Desktop UI ===

{| border="1"
|+ Table 3. Desktop UI
! Name !! Description !! Filename
|-
| Minimize || ||
|-
| Minimize to Tray || ||
|-
| Maximize || ||
|-
| Restore || ||
|-
| Restore from Tray || ||
|-
| Shade Up || ||
|-
| Shade Down || ||
|-
| Icon Hover || ||
|-
| Icon Select || ||
|}

=== Menu UI ===

{| border="1"
|+ Table 3. Menu UI
! Name !! Description !! Filename
|-
| Menu Button Select || Selecting the K Menu || menu-button-select
|-
| Menu Browse || Browsing through the menu, on a new menu item hover || menu-browse
|-
| Menu Item Select || Selecting a menu item || menu-item-select
|}

== Application Level Events ==

=== Communication Events ===
* New Email
* New IM
* Name mentioned in chat room
* Connected to messaging server
* Disconnected from messaging server
* Person Joins
* Person Leaves
* Receive Call
* Receive Request to Join
* Contact Online
* New Alert
* New Message
* New Mail

{| border="1"
|+ Table 3. Communication Events
! Name !! Description !! Filename
|-
| New Email || A new email message is received || new-email
|-
| New IM || a new instant message is received || new-message
|}

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== Hardware Events ==

* Critical Battery Alarm
* Device Connect
* Device Disconnect
* Device Failed to Connect
* Low Battery Alarm
* '''Print Complete?'''

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Projects/Oxygen/Sound Theme Naming Specification

2007-01-29T18:18:08Z

CuCullin: /* Communication Events */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

Sound is an important element used to communicate with users. It is important, then, that there be a unified and simplified way of organizing sounds.

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
* Critical Stop
* Default Beep
* Exit
* Menu Popup
* Open Program
* Program Error
* Question
* Restore Down
* Restore Up
* Select
* Show Toolbar
* System Notification
* Logoff
* Logon

== User Interface Events ==
=== Desktop UI ===
* Minimize
* Minimize to Tray
* Maximize
* Restore
* Restore from Tray
* Shade Up
* Shade Down
* Icon Hover?
* Icon Select?

=== Menu UI ===

{| border="1"
|+ Table 3. Menu UI
! Name !! Description !! Filename
|-
| Menu Button Select || Selecting the K Menu || menu-button-select
|-
| Menu Browse || Browsing through the menu, on a new menu item hover || menu-browse
|-
| Menu Item Select || Selecting a menu item || menu-item-select
|}

== Application Level Events ==

=== Communication Events ===
* New Email
* New IM
* Name mentioned in chat room
* Connected to messaging server
* Disconnected from messaging server
* Person Joins
* Person Leaves
* Receive Call
* Receive Request to Join
* Contact Online
* New Alert
* New Message
* New Mail

{| border="1"
|+ Table 3. Communication Events
! Name !! Description !! Filename
|-
| New Email || A new email message is received || new-email
|-
| New IM || a new instant message is received || new-message
|}

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== Hardware Events ==

* Critical Battery Alarm
* Device Connect
* Device Disconnect
* Device Failed to Connect
* Low Battery Alarm
* '''Print Complete?'''

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Projects/Partners

2007-01-29T18:14:23Z

CuCullin: /* Current/Immediate Initiatives (Target: March) */

This page is a collection area for thoughts on how to construct a strategy for partnerships with independant software vendors (ISVs) and system integrators (SIs) as well as implementation notes for same. Other partners are surely on the map as well, but right now we are focussing on the ISV/SI issue.

The immediate game plan is:
* define what we will be doing with and for each of these groups
* turn that into a releasable communique for the press channel
* garner feedback and registrations of interest from people in both groups
* world domination.

As this plan is fleshed out and we achieve points one and two, the results will be taken to the MWG, e.V. and then the general community. This will allow a staged introduction with peer review at each point.

== ISVs ==

The challenges we hear from ISVs tend to fall into a few common categories:
* binary compat across distributions
* clear desktop integration strategies for third party software
* lack of documentation (MSDN is often brought up)
* lack of relationship / partnership points with the community that are recognizable / make sense to them
* traditional tech support options

The first two are out of scope of KDE itself, but we need to stress in our communications that we are involved in significant ways with both the LSB and Portland.

== System Integrators (SIs) ==

The initial target SIs will be regional companies with 5-500 employees. Obviously these are not the "big boys" but they are probably more accessible targets. The goal is to raise the number of companies that provide service and support for KDE based installations.

== Sys Admins (SAs) ==

There is obvious appeal to SAs and companies built around their professional services given the information on the wiki. There is overlap here with SIs, but it may be worthwhile to look at the implications unique to SAs.

== KDE e.V. Supporting Members Program (SMP) ==

The SMP relies on parties with vested interests in KDE. While there are many such entities today, this partner program will be used to widen the top of the prospects funnel by creating vested interests and identifying existing ones. It should be a natural consequence for those most involved with this program will become interested over time in the SMP.

In one sense, this program and the SMP work in opposite directions: this program gives information and interface to the outside world and the SMP is a means for the beneficiaries of the program to give back to KDE.

== The Plan ==

=== Current/Immediate Initiatives (Target: March) ===
* kdelibs.com
** repositioned as an isv site
** rebranded to match devnew
** win32 build system settles down and the tutorials are then moved to devnew
** isv.kde.org is registered and points to kdelibs.com
** the isv section on devnew moves to isv.kde.org as its main page content
*** the tools and libraries link there point to devnew

* devnew
** becomes [[Projects/NamingTheWiki|${SOMETHING}.k.o]] and will be launched with KDE4 as our answer to MSDN and the Apple Developer Connection
** isv entry points to isv.kde.org

* online registration and survey form to be referenced from announcement

=== Mid-term ===

* create membership programs for ISVs and SIs
** online registry where they can be found by possible clients, list their titles, etc
** mail-out packages for each group
*** glossy version of our isv.kde.org info
*** pointers to online information sources
*** information they can pass on to potential clients

* organize an ISV/SI conference

* an ISV issue tracker (Staniek)

=== Blue Sky Thinking ===

* build the online registry in a social B2B networking system?

Projects/Oxygen/Sound Theme Naming Specification

2007-01-22T19:31:05Z

CuCullin: /* Menu UI */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

Sound is an important element used to communicate with users. It is important, then, that there be a unified and simplified way of organizing sounds.

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
* Critical Stop
* Default Beep
* Exit
* Menu Popup
* Open Program
* Program Error
* Question
* Restore Down
* Restore Up
* Select
* Show Toolbar
* System Notification
* Logoff
* Logon

== User Interface Events ==
=== Desktop UI ===
* Minimize
* Minimize to Tray
* Maximize
* Restore
* Restore from Tray
* Shade Up
* Shade Down
* Icon Hover?
* Icon Select?

=== Menu UI ===

{| border="1"
|+ Table 3. Menu UI
! Name !! Description !! Filename
|-
| Menu Button Select || Selecting the K Menu || menu-button-select
|-
| Menu Browse || Browsing through the menu, on a new menu item hover || menu-browse
|-
| Menu Item Select || Selecting a menu item || menu-item-select
|}

== Application Level Events ==

=== Communication Events ===
* New Email
* New IM
* Name mentioned in chat room
* Connected to messaging server
* Disconnected from messaging server
* Person Joins
* Person Leaves
* Receive Call
* Receive Request to Join
* Contact Online
* New Alert
* New Message
* New Mail

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== Hardware Events ==

* Critical Battery Alarm
* Device Connect
* Device Disconnect
* Device Failed to Connect
* Low Battery Alarm
* '''Print Complete?'''

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Projects/Oxygen/Sound Theme Naming Specification

2007-01-22T18:54:48Z

CuCullin: /* Menu UI */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

Sound is an important element used to communicate with users. It is important, then, that there be a unified and simplified way of organizing sounds.

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
* Critical Stop
* Default Beep
* Exit
* Menu Popup
* Open Program
* Program Error
* Question
* Restore Down
* Restore Up
* Select
* Show Toolbar
* System Notification
* Logoff
* Logon

== User Interface Events ==
=== Desktop UI ===
* Minimize
* Minimize to Tray
* Maximize
* Restore
* Restore from Tray
* Shade Up
* Shade Down
* Icon Hover?
* Icon Select?

=== Menu UI ===

{| border="1"
|+ Table 1. Menu UI
! Name !! Description !! Filename
|-
| Menu Button Select || Selecting the K Menu || menu-button-select
|-
| Menu Browse || Browsing through the menu, on a new menu item hover || menu-browse
|-
| Menu Item Select || Selecting a menu item || menu-item-select
|}

== Application Level Events ==

=== Communication Events ===
* New Email
* New IM
* Name mentioned in chat room
* Connected to messaging server
* Disconnected from messaging server
* Person Joins
* Person Leaves
* Receive Call
* Receive Request to Join
* Contact Online
* New Alert
* New Message
* New Mail

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== Hardware Events ==

* Critical Battery Alarm
* Device Connect
* Device Disconnect
* Device Failed to Connect
* Low Battery Alarm
* '''Print Complete?'''

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Projects/Oxygen/Sound Theme Naming Specification

2007-01-22T18:41:13Z

CuCullin: /* Desktop UI */

Projects/Oxygen/Sound Theme Naming Specification

2007-01-22T18:40:42Z

CuCullin:

Projects/Oxygen/Sound Theme Naming Specification

2007-01-22T18:33:54Z

CuCullin: /* Overview */

Projects/Oxygen/Sound Theme Naming Specification

2007-01-22T18:20:36Z

CuCullin: /* System Events */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

1.5 INFORMATION DIALOG

1.6 WARNING DIALOG

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
* Critical Battery Alarm
* Critical Stop
* Default Beep
* Device Connect
* Device Disconnect
* Device Failed to Connect
* Exit
* Low Battery Alarm
* Menu Popup
* Open Program
* Print Complete
* Program Error
* Question
* Restore Down
* Restore Up
* Select
* Show Toolbar
* Start
* System Notification
* Logoff
* Logon

== User Interface Events ==
* Minimize
* Minimize to Tray
* Maximize
* Restore
* Restore from Tray
* Shade Up
* Shade Down
* Menu Browse
* Menu Select

== Application Level Events ==

=== Communication Events ===
* New Email
* New IM
* Name mentioned in chat room
* Connected to messaging server
* Disconnected from messaging server
* Person Joins
* Person Leaves
* Receive Call
* Receive Request to Join
* Contact Online
* New Alert
* New Message
* New Mail

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Projects/Oxygen/Sound Theme Naming Specification

2007-01-22T18:19:23Z

CuCullin: /* References */

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
Critical Battery Alarm
Critical Stop
Default Beep
Device Connect
Device Disconnect
Device Failed to Connect
Exclamation
Exit
Low Battery Alarm
Menu Popup
Open Program
Print Complete
Program Error
Question
Restore Down
Restore Up
Select
Show Toolbar
Start
System Notification
Logoff
Logon

== User Interface Events ==
* Minimize
* Minimize to Tray
* Maximize
* Restore
* Restore from Tray
* Shade Up
* Shade Down
* Menu Browse
* Menu Select

== Application Level Events ==

=== Communication Events ===
* New Email
* New IM
* Name mentioned in chat room
* Connected to messaging server
* Disconnected from messaging server
* Person Joins
* Person Leaves
* Receive Call
* Receive Request to Join
* Contact Online
* New Alert
* New Message
* New Mail

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== File/Web Browser ==
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

Talk:Projects/NamingTheWiki

2007-01-19T18:49:44Z

CuCullin: /* Name Suggestions */

= Name Suggestions =

: '''TechZone''': I like this name for several reasons: They give a clue on the pages purpose, are not biased towards either devs or system integrators, and leave room to brand them (Question to Promo team: is that a good idea). Please note that we will redirect developer.kde.org to this domain, so people who are looking for this domain straight will still end up in the right place. The word ''Base'' in '''Tech''Base''''' was criticized as being meaningless plus there is already a domain called devbase.com, and I want to stay out of tm issues. --[[User:Danimo|Danimo]] 01:42, 19 January 2007 (CET)

::I agree with these ideas. Regarding not biasing articles, that imho is a particularly important idea. While the major apps/suites (KOffice, Kontact, Kolab, Kopete, etc) are taken care of, there is an incredibly vast set of vertical markets untouched by KDE. These markets are not often discussed, yet make up a rather significant developer market. Examples would be software to manage a dental office, consulting firm, accounting firm, millwork companies, etc. Those working on this won't necessarily fall into a neat and clean category, so I'd consider this advantageous. --[[User:CuCullin|CuCullin]] 16:21, 19 January 2007 (CET)

: '''TechBase''': I like this name because we already call the site that elsewhere, so there's some continuity. It also is representative of the fact that this site (as i understand it) is meant to be the base of technical information for and about KDE on the interwebs. There is a company called TechBase International"KDE Technical Reference" which does things completely unrelated to KDE so maybe there's some tm issues, but I doubt it. Perhaps we might want to have a thing where the full name of the site is ''KDE Technical Base'' and we just call it ''TechBase'' for short --[[User:Mattr|Mattr]] 02:22, 19 January 2007 (CET)

: '''TechCenter''': Similar to TechZone and TechBase. Maybe also similar to the [http://www.qtcentre.org/ qt-centre].

: '''TechZone and TechBase ''': I feel that "tech[base|zone]"is a poor choice of name - it's a made up word and as such will age rapidly. It's a lowest common denominator, meaningless choice. The KDE project is bigger than that and would be better served by clean, functional terms such as "KDE Technical Reference", "KDE Technical Resource". If it has to be one word, "Learn" or "Platform". --[[User:Bille|Bille]] 23:18, 17 January 2007 (CET)

: '''KDE Wiki''': ''Wiki'' is now a noun just like a ''web page''. Many of us are used to talking ''KDevelop wiki'', ''SUSE wiki'', and even below, Daniel used ''Kolab Wiki'' for Kolab. After all ''it's easy to remember'' and compatible with KISS principles... --[[User:Jstaniek|jstaniek]] 16:10, 19 January 2007 (CET)

:: The thing I don't like about this is that it ''is'' just a noun like "web page". This site has a purpose, and I think the name should promote that purpose - otherwise, there would be no limitation on any KDE content going on here. Users might add application manuals, or e.V. info could go on here, whatever. That would only create confusion imho. --[[User:CuCullin|CuCullin]] 16:21, 19 January 2007 (CET)

:: Isn't the ''KDE wiki'' wiki.kde.org? That's already taken. Besides, we still need a name on the right of the KDE logo. "KDE Technical Reference" or similar titles are better than "KDE wiki". --[[User:Dhaumann|Dhaumann]] 16:56, 19 January 2007 (CET)

::: I thought the old wiki.kde.org, now '''redundant''' (look at its TOC), is pretty much a history now when the new ''developernew'' wiki appeared, and as Mediawiki not only contains predictable hyperlinks and good interwiki and templates support, but its engine is far superior to the old one and constantly improved. <br/><br/>At least I consider moving all of my content out of it elsewhere. There's no day when I did not have problems with its tikiwiki's configuration, html layout and speed. <br/><br/>Application manuals? The old wiki.kde.org does not contain this kind of stuff, so history shows it's not a problem. Every larger KDE apps can host its own wiki, as we know in case of KOffice, Kexi, KDevelop, KDEWebDev family, etc. <u>So ''Wiki'' is still my favourite term.</u><br/><br/>Regarding "KDE Technical Reference", it sounds a bit serious. There's similar very popular (100x more according to google) term: '''"Knowledge Base"'''. Personally I have no problem with having wiki.kde.org (because it's as short as possible) and "Knowledge Base" title. --[[User:Jstaniek|jstaniek]] 18:54, 19 January 2007 (CET)

:::: Part of that, imho, is that wiki.kde.org (and TikiWiki) isn't as friendly as MediaWiki. Perhaps it should be wiki.kde.org, and simply have a nice listing somewhere on this site discussing what does and does not belong on here, just to direct content that may be more appropriate elsewhere. Personally, I like a more descriptive name because I think it separates this wiki from others. --[[User:CuCullin|CuCullin]] 19:49, 19 January 2007 (CET)

: Do you also mean platform.kde.org or reference.kde.org then? We are searching for both a readable name and a subdomain name. --[[User:Dhaumann|Dhaumann]] 16:56, 19 January 2007 (CET)

Hi! First time ever helping this community(I hope it's not the last time either)

The name should reflect the whole KDE project as (the way I see it) it tries to group everything KDE will be doing in the future to one wiki.

My name: '''Conquer KDE''' or '''Konquer KDE''' depending if you like to replace the "C" by a "K".

As I read on the mailing list, we are trying to promote KDE to the OSV and to the system admins as well so the Slogan would be a nice way to name the wiki.--[[User:Imagine|Imagine]] 19:11, 19 January 2007 (CET)

= Thoughts on the Scope of This Wiki =

= Thoughts on the Target Audiences =

:Perhaps someone could clarify what is meant by "system administrators". At the extreme this term could apply to everyone from those with root on their local desktop install to people managing a network of thousands of PCs. I suspect the first of these includes the vast majority of KDE users. I assume this is not what is intended as this is a separate site to wiki.kde.org. -- TheoSpears

::We're talking about people that administer a multitude of PCs, probably they are doing this professionally most of the time. We want to provide resources for them (howtos, scripts, pittfalls and workarounds). The wiki also gives us the unique chance that they can contribute their knowledge back (works fine e.g. on the [http://wiki.kolab.org Kolab Wiki]. --[[User:Danimo|Danimo]] 02:12, 19 January 2007 (CET)

:::Also, do we need to put this up on this site? The question being, does Sys Admin information belong? Or should it remain at http://www.kde.org/areas/sysadmin/ ? --[[User:CuCullin|CuCullin]] 18:22, 19 January 2007 (CET)

:::This is also a place where sys admins can find out more about the whole KDE community. This Wiki should be more like the very first place for anyone who wants to know what is KDE. Screenshot, announcement, the best apps(amarok, k3b, koffice, konqueror, etc.), so that the user will WANT to try this out.--[[User:Imagine|Imagine]] 19:16, 19 January 2007 (CET)

:With such an international audience, presumably we need to think about how the name carries around the world. I know that this can sink any discussion with concerns from every country, but I wonder how well (for example) 'zone' and 'base' are understood in this context, particularly since both have more than one meaning in English. [[User:Tomchance|Tomchance]] 08:24, 19 January 2007 (CET)

Talk:Projects/NamingTheWiki

2007-01-19T17:22:24Z

CuCullin: /* Thoughts on the Target Audiences */

Talk:Projects/NamingTheWiki

2007-01-19T17:22:08Z

CuCullin: /* Thoughts on the Target Audiences */

Development/Further Information

2007-01-19T17:12:56Z

CuCullin: /* IRC Channels */

== Web Sites ==
* [http://www.KDE.org KDE Home]
* [http://dot.kde.org KDE Dot News]
* [http://www.planetkde.org Planet KDE]

==Blogs==

== Books ==
Below are a list of books associated with KDE 4 development. These may be specific to applications, using the Qt Toolkit, or specifically KDE 4 books.

===KDE 4 Development Books===

===Qt 4 Development Books===

==== English ====

[http://www.phptr.com/bookstore/product.asp?isbn=0131879057&rl=1|The Book of Qt 4: The Art of Building Qt Applications By Alan Ezust, Paul Ezust.]

[http://www.phptr.com/bookstore/product.asp?isbn=0131872494&rl=1|C++ GUI Programming with Qt 4 By Jasmin Blanchette, Mark Summerfield.]

==== German ====

[https://www.opensourcepress.de/index.php?26&backPID=15&tt_products=23 Qt 4: Einführung in die Applikationsentwicklung von Daniel Molkentin]

== IRC Channels ==
In general, IRC channels mentioned here are available on FreeNode. Connect to irc.kde.org, and check these channels out for further information.

*KDE 4 Development - #kde4-devel
*KDE Development - #kde-devel
*KDevelop - #kdevelop
*Phonon - #phonon
*Decibel - #decibel
*Solid - #solid

== Newsgroups ==
== Forums ==
== Events ==
== Courses and Certifications ==
== Audio and Video Casts ==
== Source Code Repositories ==

Development/Further Information

2007-01-19T17:12:39Z

CuCullin: /* IRC Channels */

== Web Sites ==
* [http://www.KDE.org KDE Home]
* [http://dot.kde.org KDE Dot News]
* [http://www.planetkde.org Planet KDE]

==Blogs==

== Books ==
Below are a list of books associated with KDE 4 development. These may be specific to applications, using the Qt Toolkit, or specifically KDE 4 books.

===KDE 4 Development Books===

===Qt 4 Development Books===

==== English ====

[http://www.phptr.com/bookstore/product.asp?isbn=0131879057&rl=1|The Book of Qt 4: The Art of Building Qt Applications By Alan Ezust, Paul Ezust.]

[http://www.phptr.com/bookstore/product.asp?isbn=0131872494&rl=1|C++ GUI Programming with Qt 4 By Jasmin Blanchette, Mark Summerfield.]

==== German ====

[https://www.opensourcepress.de/index.php?26&backPID=15&tt_products=23 Qt 4: Einführung in die Applikationsentwicklung von Daniel Molkentin]

== IRC Channels ==
In general, IRC channels mentioned here are available on FreeNode. Connect to irc.kde.org, and check these channels out for further information.

KDE 4 Development - #kde4-devel
KDE Development - #kde-devel
KDevelop - #kdevelop
Phonon - #phonon
Decibel - #decibel
Solid - #solid

== Newsgroups ==
== Forums ==
== Events ==
== Courses and Certifications ==
== Audio and Video Casts ==
== Source Code Repositories ==

Development/Further Information

2007-01-19T17:10:33Z

CuCullin: /* Web Sites */

Development/Further Information

2007-01-19T16:16:02Z

CuCullin:

== Web Sites ==

==Blogs==

== Books ==
Below are a list of books associated with KDE 4 development. These may be specific to applications, using the Qt Toolkit, or specifically KDE 4 books.

===KDE 4 Development Books===

===Qt 4 Development Books===

==== English ====

[http://www.phptr.com/bookstore/product.asp?isbn=0131879057&rl=1|The Book of Qt 4: The Art of Building Qt Applications By Alan Ezust, Paul Ezust.]

[http://www.phptr.com/bookstore/product.asp?isbn=0131872494&rl=1|C++ GUI Programming with Qt 4 By Jasmin Blanchette, Mark Summerfield.]

==== German ====

[https://www.opensourcepress.de/index.php?26&backPID=15&tt_products=23 Qt 4: Einführung in die Applikationsentwicklung von Daniel Molkentin]

== IRC Channels ==
== Newsgroups ==
== Forums ==
== Events ==
== Courses and Certifications ==
== Audio and Video Casts ==
== Source Code Repositories ==

Development/Further Information

2007-01-19T16:15:31Z

CuCullin:

Places to put your code
irc channels
Newsgroups
Forums
Events
Could also house sections designated to vertical markets such as medical, education, government, etc.
Applicable courses and certifications
Audio and Video casts

== Web Sites ==

==Blogs==

== Books ==
Below are a list of books associated with KDE 4 development. These may be specific to applications, using the Qt Toolkit, or specifically KDE 4 books.

===KDE 4 Development Books===

===Qt 4 Development Books===

==== English ====

[http://www.phptr.com/bookstore/product.asp?isbn=0131879057&rl=1|The Book of Qt 4: The Art of Building Qt Applications By Alan Ezust, Paul Ezust.]

[http://www.phptr.com/bookstore/product.asp?isbn=0131872494&rl=1|C++ GUI Programming with Qt 4 By Jasmin Blanchette, Mark Summerfield.]

==== German ====

[https://www.opensourcepress.de/index.php?26&backPID=15&tt_products=23 Qt 4: Einführung in die Applikationsentwicklung von Daniel Molkentin]

== IRC Channels ==
== Newsgroups ==
== Forums ==
== Events ==
== Courses and Certifications ==
== Audio and Video Casts ==

Development/Further Information

2007-01-19T16:12:15Z

CuCullin: Development/Further Reading moved to Development/Further Information: Wrong name by accident...

Development/Further Information

2007-01-19T16:10:17Z

CuCullin:

Talk:Projects/NamingTheWiki

2007-01-19T15:21:09Z

CuCullin: /* Name Suggestions */ TechZone (and proofreading qt-centre)

Projects/TechBase

2007-01-18T19:53:53Z

CuCullin: /* Developer Forums */

{{Improve}}

== Tutorials Wanted/Needed ==
Ordered based on priority.

=== Security ===
* Techniques and available software
* Privacy concerns
* Regulatory compliance
* For network-oriented applications (see further down the task list)
* Important points of note for each OS (Linux, Solaris, Windows, Mac OS, etc)

=== Further Information ===
The "Further Information section replaces "Recommended Books" under the Development section. It should include:

* Books
* Blogs
* Places to put your code
* irc channels
* Newsgroups
* Forums
* Events
* Could also house sections designated to vertical markets such as medical, education, government, etc.
* Applicable courses and certifications
* Audio and Video casts

=== Web Development ===

With khtml, webkit, firefox, opera, ie6 via wine - and now the ie7 rendering engine via wine - KDE is a premier web testing environment. It is beneficial to cover such topics on the site, along with tools used to develop sites (Quanta, KImageMapEditor, KLinkStatus, etc), setting up such testing environments, etc.

=== Rapid Application Development ===
* Ruby/Python/Perl/etc
* Need to get communities on board and contributing.

=== KDevelop ===
* Learning the languages
* Tutorials using KDevelop; such as a tutorial in Getting Started
* kde edu people have done some tutorials in this area, contact and bring those tutorials here.
* Contact KDevelop developers to get their involvement on the wiki in this regard.

=== Networked Services ===
* Web/Internet services
* How ISV's can make use of such things as ghns, kdepim/kode...

=== KOffice as a Software Design Platform ===
* For collaboration and communication
* Get KOffice team on the wiki

=== Portable Devices ===
*Working with them and KDE
*Creating a KDE app that makes use of OpenSync
*Links to Qtopia with info on interoperability
*ie: Konqueror Embedded

=== Error Reporting Functionality ===
An ISV's ability to use a bug management system in place, by taking the app and setting up their own server as well, so that there is a reporting system in place already. They could automate bug information like if desired, like grabbing logs, etc.

=== Design Patterns ===
* KDE specific elements should come first. Low on the priority list.

== Further Discussion Required ==
=== SysAdmin Tools ===
* http://kde.org/areas/sysadmin

*'''Held off for further discussion'''. May or may not belong, as this site will not be developer.kde.org, but TechBase.KDE.org.

=== Developer Forums ===
* Forum admins should be subscribed to the MLs
* Forum is more for application developers than core developers
* Forum could have a gateway to the MLs, or the Admins and Moderators would act as the communications link when the need arises.
* Could be a subforum of a greater official KDE forum

*'''May have manpower issues'''.

== Sidelined ==
=== Business Communications Flow ===

Developing software for the flow of enterprise communications has become an extremely wide are of software development as of late. Nepomuk/Akonadi may be part of this.

* '''Sidelined until Akonadi can be further developed.'''

Talk:Welcome to KDE TechBase

2007-01-16T21:28:02Z

CuCullin: "Develop" section....

__NOTOC__ __NOEDITSECTION__

==License==
I suggest we move to [http://creativecommons.org/licenses/by-sa/2.5/ cc-by-sa] right from the beginning. Please see the [http://people.debian.org/~srivasta/Position_Statement.xhtml Draft Debian Position Statement About The GNU Free Documentation License(GFDL)]. [[User:Logixoul|Logixoul]] 14:10, 8 September 2006 (CEST)

:Or dual license, keep GFDL and use CC. (There was some discussion about this on Wikipedia iirc) [[User:CuCullin|CuCullin]] 19:31, 9 January 2007 (CET)

== Oxygen theme ==

I really like the Oxygen theme on this wiki, but might we reconsider the fixed width bit? It makes some of the pages (e.g. recent changes) not work as well, wrapping lines and making them difficult to read. --[[User:Axiom|Axiom]] 20:50, 14 January 2007 (CET)

: We have had this discussion over and over again but at the same time we got very positive feedback (e.g. on the kde-www mailing list). Changing the layout is very unlikely. I agree that due to our use of subpages the urls get long and a bit unreadable, but that's hardly a reason to change the layout of all *kde.org pages. --[[User:Dhaumann|Dhaumann]] 23:49, 14 January 2007 (CET)

== Develop ==

"Develop: Development wikis of various KDE projects" No longer seems an appropriate title considering the links inside it. Perhaps "Develop: KDE Projects" and then the description "Various KDE Projects, including links to development wikis, task lists, etc" or some such. --[[User:CuCullin|CuCullin]] 22:28, 16 January 2007 (CET)

MediaWiki talk:Sidebar

2007-01-16T21:24:37Z

CuCullin:

I feel that the sidebar links are not really appropriate. The sidebar should be used to enable quick navigation of the site. The links should be to the top level pages like it is at [http://developer.kde.org/ http://developer.kde.org/]. Furthermore I propose removing "Random page" and maybe even "Recent changes" since they're not really useful to the reader (that is a developer who comes to this site looking for documentation etc.). --[[User:Milliams|milliams]] 16:28, 8 January 2007 (CET)

: yes, i have to say i'm not sure what real value "Recent changes" has for the average reader given the prominence of its location. i like that we have the sections there now, but i can't help but think that we could collapse "Navigation" and "Sections" into one group since they are essentially both the same thing.

: "Donations" is under the "Interact" area on the main page. i'm uncertain it really belongs as a top-level item on every page's navigation though (feels a bit pushy?) the page it points to is also completely inappropriate and outdated content-wise. that page should simply be deleted and point to the support page on kde.org

: finally, 'contribute' is "out of order" compared to the main page listings and i don't know if we need a link to projects in the sidebar since those aren't really "techbase" per say as much as a convenient place for individual projects and therefore not generally useful.

: this would leave us with main page, help, getting started, development, policies, contribute, schedules under one heading. this would shorten the sidebar up to be only slightly longer than the "sections" section is on its own now. --[[User:Aseigo|Aseigo]] 18:05, 16 January 2007 (CET)

:: I agree on all counts, but it would be nice to keep Recent Changes (perhaps under personal tools?) for Wiki watching. --[[User:CuCullin|CuCullin]] 22:24, 16 January 2007 (CET)

Projects/TechBase

2007-01-16T20:43:36Z

CuCullin: /* Networked Services */

{{Improve}}

== Tutorials Wanted/Needed ==
Ordered based on priority.

=== Security ===
* Techniques and available software
* Privacy concerns
* Regulatory compliance
* For network-oriented applications (see further down the task list)
* Important points of note for each OS (Linux, Solaris, Windows, Mac OS, etc)

=== Further Information ===
The "Further Information section replaces "Recommended Books" under the Development section. It should include:

* Books
* Blogs
* Places to put your code
* irc channels
* Newsgroups
* Forums
* Events
* Could also house sections designated to vertical markets such as medical, education, government, etc.
* Applicable courses and certifications
* Audio and Video casts

=== Web Development ===

With khtml, webkit, firefox, opera, ie6 via wine - and now the ie7 rendering engine via wine - KDE is a premier web testing environment. It is beneficial to cover such topics on the site, along with tools used to develop sites (Quanta, KImageMapEditor, KLinkStatus, etc), setting up such testing environments, etc.

=== Rapid Application Development ===
* Ruby/Python/Perl/etc
* Need to get communities on board and contributing.

=== KDevelop ===
* Learning the languages
* Tutorials using KDevelop; such as a tutorial in Getting Started
* kde edu people have done some tutorials in this area, contact and bring those tutorials here.
* Contact KDevelop developers to get their involvement on the wiki in this regard.

=== Networked Services ===
* Web/Internet services
* How ISV's can make use of such things as ghns, kdepim/kode...

=== KOffice as a Software Design Platform ===
* For collaboration and communication
* Get KOffice team on the wiki

=== Portable Devices ===
*Working with them and KDE
*Creating a KDE app that makes use of OpenSync
*Links to Qtopia with info on interoperability
*ie: Konqueror Embedded

=== Error Reporting Functionality ===
An ISV's ability to use a bug management system in place, by taking the app and setting up their own server as well, so that there is a reporting system in place already. They could automate bug information like if desired, like grabbing logs, etc.

=== Design Patterns ===
* KDE specific elements should come first. Low on the priority list.

== Further Discussion Required ==
=== SysAdmin Tools ===
* http://kde.org/areas/sysadmin

*'''Held off for further discussion'''. May or may not belong, as this site will not be developer.kde.org, but TechBase.KDE.org.

=== Developer Forums ===
* Forum admins should be subscribed to the MLs
* Forum is more for application developers than core developers
* Forum could have a gateway to the MLs, or the Admins and Moderators would act as the communications link when the need arises.
* Could be a subforum of a greater official KDE forum

**'''May have manpower issues'''.

== Sidelined ==
=== Business Communications Flow ===

Developing software for the flow of enterprise communications has become an extremely wide are of software development as of late. Nepomuk/Akonadi may be part of this.

* '''Sidelined until Akonadi can be further developed.'''

Projects/TechBase

2007-01-16T19:47:52Z

CuCullin: /* Security */

{{Improve}}

== Tutorials Wanted/Needed ==
Ordered based on priority.

=== Security ===
* Techniques and available software
* Privacy concerns
* Regulatory compliance
* For network-oriented applications (see further down the task list)
* Important points of note for each OS (Linux, Solaris, Windows, Mac OS, etc)

=== Further Information ===
The "Further Information section replaces "Recommended Books" under the Development section. It should include:

* Books
* Blogs
* Places to put your code
* irc channels
* Newsgroups
* Forums
* Events
* Could also house sections designated to vertical markets such as medical, education, government, etc.
* Applicable courses and certifications
* Audio and Video casts

=== Web Development ===

With khtml, webkit, firefox, opera, ie6 via wine - and now the ie7 rendering engine via wine - KDE is a premier web testing environment. It is beneficial to cover such topics on the site, along with tools used to develop sites (Quanta, KImageMapEditor, KLinkStatus, etc), setting up such testing environments, etc.

=== Rapid Application Development ===
* Ruby/Python/Perl/etc
* Need to get communities on board and contributing.

=== KDevelop ===
* Learning the languages
* Tutorials using KDevelop; such as a tutorial in Getting Started
* kde edu people have done some tutorials in this area, contact and bring those tutorials here.
* Contact KDevelop developers to get their involvement on the wiki in this regard.

=== Networked Services ===
* Web/Internet services
* How ISV's can make use of such things as ghns, kdepim/kode...

=== KOffice as a Software Design Platform
* For collaboration and communication
* Get KOffice team on the wiki

=== Portable Devices ===
*Working with them and KDE
*Creating a KDE app that makes use of OpenSync
*Links to Qtopia with info on interoperability
*ie: Konqueror Embedded

=== Error Reporting Functionality ===
An ISV's ability to use a bug management system in place, by taking the app and setting up their own server as well, so that there is a reporting system in place already. They could automate bug information like if desired, like grabbing logs, etc.

=== Design Patterns ===
* KDE specific elements should come first. Low on the priority list.

== Further Discussion Required ==
=== SysAdmin Tools ===
* http://kde.org/areas/sysadmin

*'''Held off for further discussion'''. May or may not belong, as this site will not be developer.kde.org, but TechBase.KDE.org.

=== Developer Forums ===
* Forum admins should be subscribed to the MLs
* Forum is more for application developers than core developers
* Forum could have a gateway to the MLs, or the Admins and Moderators would act as the communications link when the need arises.
* Could be a subforum of a greater official KDE forum

**'''May have manpower issues'''.

== Sidelined ==
=== Business Communications Flow ===

Developing software for the flow of enterprise communications has become an extremely wide are of software development as of late. Nepomuk/Akonadi may be part of this.

* '''Sidelined until Akonadi can be further developed.'''

Talk:Projects/TechBase

2007-01-16T19:40:42Z

CuCullin:

Any issues with the write up, or can this be linked to through Projects, and begin discussions where applicable? --[[User:CuCullin|CuCullin]] 20:40, 16 January 2007 (CET)

Projects/TechBase

2007-01-16T02:52:37Z

CuCullin: /* KDevelop */

{{Improve}}

== Tutorials Wanted/Needed ==
Ordered based on priority.

=== Security ===
* Techniques and available software

=== Further Information ===
The "Further Information section replaces "Recommended Books" under the Development section. It should include:

* Books
* Blogs
* Places to put your code
* irc channels
* Newsgroups
* Forums
* Events
* Could also house sections designated to vertical markets such as medical, education, government, etc.
* Applicable courses and certifications
* Audio and Video casts

=== Web Development ===

With khtml, webkit, firefox, opera, ie6 via wine - and now the ie7 rendering engine via wine - KDE is a premier web testing environment. It is beneficial to cover such topics on the site, along with tools used to develop sites (Quanta, KImageMapEditor, KLinkStatus, etc), setting up such testing environments, etc.

=== Rapid Application Development ===
* Ruby/Python/Perl/etc
* Need to get communities on board and contributing.

=== KDevelop ===
* Learning the languages
* Tutorials using KDevelop; such as a tutorial in Getting Started
* kde edu people have done some tutorials in this area, contact and bring those tutorials here.
* Contact KDevelop developers to get their involvement on the wiki in this regard.

=== Networked Services ===
* Web/Internet services
* How ISV's can make use of such things as ghns, kdepim/kode...

=== KOffice as a Software Design Platform
* For collaboration and communication
* Get KOffice team on the wiki

=== Portable Devices ===
*Working with them and KDE
*Creating a KDE app that makes use of OpenSync
*Links to Qtopia with info on interoperability
*ie: Konqueror Embedded

=== Error Reporting Functionality ===
An ISV's ability to use a bug management system in place, by taking the app and setting up their own server as well, so that there is a reporting system in place already. They could automate bug information like if desired, like grabbing logs, etc.

=== Design Patterns ===
* KDE specific elements should come first. Low on the priority list.

== Further Discussion Required ==
=== SysAdmin Tools ===
* http://kde.org/areas/sysadmin

*'''Held off for further discussion'''. May or may not belong, as this site will not be developer.kde.org, but TechBase.KDE.org.

=== Developer Forums ===
* Forum admins should be subscribed to the MLs
* Forum is more for application developers than core developers
* Forum could have a gateway to the MLs, or the Admins and Moderators would act as the communications link when the need arises.
* Could be a subforum of a greater official KDE forum

**'''May have manpower issues'''.

== Sidelined ==
=== Business Communications Flow ===

Developing software for the flow of enterprise communications has become an extremely wide are of software development as of late. Nepomuk/Akonadi may be part of this.

* '''Sidelined until Akonadi can be further developed.'''

User talk:CuCullin

2007-01-16T02:49:20Z

CuCullin: Discussion bits moved to Projects/TechBase

Moved to [[Projects/TechBase|TechBase]]. Keeping this up as a reference for a bit...

-----

I've noticed the following things that may have a place on devnew...

# Forums - ISV's have regular public communication on MSDN, while KDE has a single forum KDE-Forum.org, which, iirc, is not KDE eV (or other) owned. There should be a developer specific forum, with subforums aligned with the wiki. This will also ease the addition of information to the wiki as specific incidents are encountered during the ongoing development cycle.
# Architecture
## Software as a Service
## Service oriented architecture
## Service oriented infrastructure
## Security
## Rapid development, case studies, etc.
## KOffice as a software design platform, in terms of collaboration and communication
# Web development - Its obvious that this is a KDE site, but one thing included in sites such as MSDN is the inclusion of information relative to web development. With khtml, webkit, firefox, opera, ie6 via wine - and now the ie7 rendering engine via wine - KDE could be called a premier web testing environment. It may be beneficial to cover such topics on the site, along with tools used to develop sites (Quanta, KImageMapEditor, KLinkStatus, whatever the case may be), setting up such testing environments, etc.
# Server Tools - specifically any KDE tools that manage, create, extend sql servers, apache, whatever
# Business communications flow - Developing software for the flow of enterprise communications has become an extremely wide area of software development as of late. I believe in part this is nepomuk, but I don't have a full understanding of nepomuk to go on. This may be another point of note.
# Error reporting functionality. -Right now, for error reporting there is bugs.kde.org. Is there any interface out there to ease error reporting for users? This may be considered separate from development, but perhaps some sort of reporting software, and configuration information for a bug server that would be bugs.kde.org compatible (to keep changes to a bug reporting app to a minimum) would be something ISV's would hold a specific interest in.
# KOffice - Kross is included on devnew - are there other ways ISV's can add onto KOffice? This would probably tie in well with #5 Business Communications Flow. Also, additional projects that maintain the same style as KOffice would be good to note specifically here.
# Design Patterns?
# KDevelop
## Learning the languages
## Tutorials using KDevelop
# Portable devices - Zaurus, Palm, etc, working with them and KDE, how to create a KDE app using opensync (im guessing here), links to qtopia and interoperability here, etc?
# More info - blogs, places to put code, irc channels, newsgroups, events, etc. Could also house sections designated to education, government, corporate, or even perhaps medical and other specific types. Courses and certifications, if applicable.
# Audio & Video casts?

Just some random thoughts... Opinions?

: Especially video casts could be interesting. Blender once had some videos. KDevelop could benefit here, as well as Quanta. Besides, this are quite some ideas we definitely should think about. This discussion could also go to the discussion of [[Projects/Partners]] =) --[[User:Dhaumann|Dhaumann]] 21:30, 15 January 2007 (CET)

:: True, I didn't want to clutter the Projects page with too much stuff. I'll reformat it for easier reading/more coherent thoughts later, and add it then. --[[User:CuCullin|CuCullin]] 21:42, 15 January 2007 (CET)

:1. Forums - I really think that KDE would benefit from an official user forum. But for core development issues, I think that the mailing lists are preferred. You'd never manage to convince everyone to switch to using a forum anyway. A forum.kde.org could only be a benefit as far as I'm concerned. Just as long as we have people willing to devote time to it.<br />6. Error reporting functionality - The problems with any sort of non-bugzilla interface were brought up when ''LikeBack'' was discussed on the mailing lists. Having more than one place where bugs are stored will cause unnecessary work. But I do agree, a simpler entry point wouldn't go amiss.<br />7. KOffice - I guess it depends on what the KOffice devs want (since they'd be the best ones to maintain something like that).<br />8. Design Patterns - These definitely should be located on devnew. Most likely in the Tutorials section.

::6. Error reporting - I was thinking more of an application-type interface such as KBugBuster, but I believe that just scrapes bugs.kde.org. Something that could interface more directly would probably be a big benefit.

Projects/TechBase

2007-01-16T02:47:40Z

CuCullin: Ok, reflowed. Please keep orphaned for the moment until it has a chance to be reviewed. In the meantime, review and discuss, or take on tasks as desired.

{{Improve}}

== Tutorials Wanted/Needed ==
Ordered based on priority.

=== Security ===
* Techniques and available software

=== Further Information ===
The "Further Information section replaces "Recommended Books" under the Development section. It should include:

* Books
* Blogs
* Places to put your code
* irc channels
* Newsgroups
* Forums
* Events
* Could also house sections designated to vertical markets such as medical, education, government, etc.
* Applicable courses and certifications
* Audio and Video casts

=== Web Development ===

With khtml, webkit, firefox, opera, ie6 via wine - and now the ie7 rendering engine via wine - KDE is a premier web testing environment. It is beneficial to cover such topics on the site, along with tools used to develop sites (Quanta, KImageMapEditor, KLinkStatus, etc), setting up such testing environments, etc.

=== Rapid Application Development ===
* Ruby/Python/Perl/etc
* Need to get communities on board and contributing.

=== KDevelop ===
* Learning the languages
* Tutorials using KDevelop; such as a tutorial in Getting Started
* kde edu people have done some tutorials in this area, contact and bring those tutorials here.

=== Networked Services ===
* Web/Internet services
* How ISV's can make use of such things as ghns, kdepim/kode...

=== KOffice as a Software Design Platform
* For collaboration and communication
* Get KOffice team on the wiki

=== Portable Devices ===
*Working with them and KDE
*Creating a KDE app that makes use of OpenSync
*Links to Qtopia with info on interoperability
*ie: Konqueror Embedded

=== Error Reporting Functionality ===
An ISV's ability to use a bug management system in place, by taking the app and setting up their own server as well, so that there is a reporting system in place already. They could automate bug information like if desired, like grabbing logs, etc.

=== Design Patterns ===
* KDE specific elements should come first. Low on the priority list.

== Further Discussion Required ==
=== SysAdmin Tools ===
* http://kde.org/areas/sysadmin

*'''Held off for further discussion'''. May or may not belong, as this site will not be developer.kde.org, but TechBase.KDE.org.

=== Developer Forums ===
* Forum admins should be subscribed to the MLs
* Forum is more for application developers than core developers
* Forum could have a gateway to the MLs, or the Admins and Moderators would act as the communications link when the need arises.
* Could be a subforum of a greater official KDE forum

**'''May have manpower issues'''.

== Sidelined ==
=== Business Communications Flow ===

Developing software for the flow of enterprise communications has become an extremely wide are of software development as of late. Nepomuk/Akonadi may be part of this.

* '''Sidelined until Akonadi can be further developed.'''

Projects/TechBase

2007-01-16T02:31:52Z

CuCullin: Being updated - keep orphaned

{{Improve}}

Being edited.... saving changes so its not lost....

Keep orphaned.

== To Do ==

=== Tutorials Wanted/Needed ===
=== Security ===

=== Further Information ===
The "Further Information section replaces "Recommended Books" under the Development section. It should include:

* Books
* Blogs
* Places to put your code
* irc channels
* Newsgroups
* Forums
* Events
* Could also house sections designated to vertical markets such as medical, education, government, etc.
* Applicable courses and certifications
* Audio and Video casts

=== Web Development ===

With khtml, webkit, firefox, opera, ie6 via wine - and now the ie7 rendering engine via wine - KDE is a premier web testing environment. It is beneficial to cover such topics on the site, along with tools used to develop sites (Quanta, KImageMapEditor, KLinkStatus, etc), setting up such testing environments, etc.

=== RAPID DEVELOPMENT & CASE STUDIES ===

Ruby/Python/Perl/etc
Need to get communities on board and contributing.

6 KDEVELOP

Learning the languages
Tutorials using KDevelop
e.g. a tutorial in Getting Started/ woudl be awsome.. i believe the kde edu people have done some tutorials here as well

7 NETWORKED SERVICES

16:53:38) aseigo: sure... web services <-> internet services, at some point those things got confused... so that would be things like gethotnewstuff for us

(16:56:11) aseigo: yes ... "networked services" ... would include ghns, kdepim/kode ...

8 KOFFICE AS A SOFTWARE DESIGN PLATFORM

For collaboration and communication
Get KOffice team on the wiki

9 PORTABLE DEVICES

Working with them and KDE
Creating a KDE app using OpenSync
Links to Qtopia with info on interoperability
Konqueror Embedded

10 ERROR REPORTING FUNCTIONALITY

my thought was on an ISV's ability to use a bug management system in place, by taking the app and setting up their own server as well, so that there is a reporting system in place already. They could automate bug information like MS if desired, like grabbing logs, etc.

11 DEVELOPER FORUMS

Forum admins should be subscribed to the MLs
Forum is more for application developers than core developers
May have manpower issues
Could be a subforum of a greater official KDE forum

12 DESIGN PATTERNS

KDE specific should come first. Low on the priority list.

13 SIDELINED

13.1 BUSINESS COMMUNICATIONS FLOW

Developing software for the flow of enterprise communications has become an extremely wide are of software development as of late. nepomuk/Akonadi may be part of this.
Sidelined until technologies catch up.

14 FURTHER DISCUSSION REQUIRED

14.1 SYSADMIN TOOLS

http://kde.org/areas/sysadmin
held off for further discussion

Projects/Oxygen/Sound Theme Naming Specification

2007-01-15T21:08:31Z

CuCullin: Projects/Oxygen/Sound Scheme Naming Specification moved to Projects/Oxygen/Sound Theme Naming Specification: Should be Theme, really.

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
Critical Battery Alarm
Critical Stop
Default Beep
Device Connect
Device Disconnect
Device Failed to Connect
Exclamation
Exit
Low Battery Alarm
Menu Popup
Open Program
Print Complete
Program Error
Question
Restore Down
Restore Up
Select
Show Toolbar
Start
System Notification
Logoff
Logon

== User Interface Events ==
* Minimize
* Minimize to Tray
* Maximize
* Restore
* Restore from Tray
* Shade Up
* Shade Down
* Menu Browse
* Menu Select

== Application Level Events ==

=== Communication Events ===
* New Email
* New IM
* Name mentioned in chat room
* Connected to messaging server
* Disconnected from messaging server
* Person Joins
* Person Leaves
* Receive Call
* Receive Request to Join
* Contact Online
* New Alert
* New Message
* New Mail

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

----File/Web Browser----
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

User talk:CuCullin

2007-01-15T21:07:32Z

CuCullin:

I've noticed the following things that may have a place on devnew...

# Forums - ISV's have regular public communication on MSDN, while KDE has a single forum KDE-Forum.org, which, iirc, is not KDE eV (or other) owned. There should be a developer specific forum, with subforums aligned with the wiki. This will also ease the addition of information to the wiki as specific incidents are encountered during the ongoing development cycle.
# Architecture
## Software as a Service
## Service oriented architecture
## Service oriented infrastructure
## Security
## Rapid development, case studies, etc.
## KOffice as a software design platform, in terms of collaboration and communication
# Web development - Its obvious that this is a KDE site, but one thing included in sites such as MSDN is the inclusion of information relative to web development. With khtml, webkit, firefox, opera, ie6 via wine - and now the ie7 rendering engine via wine - KDE could be called a premier web testing environment. It may be beneficial to cover such topics on the site, along with tools used to develop sites (Quanta, KImageMapEditor, KLinkStatus, whatever the case may be), setting up such testing environments, etc.
# Server Tools - specifically any KDE tools that manage, create, extend sql servers, apache, whatever
# Business communications flow - Developing software for the flow of enterprise communications has become an extremely wide area of software development as of late. I believe in part this is nepomuk, but I don't have a full understanding of nepomuk to go on. This may be another point of note.
# Error reporting functionality. -Right now, for error reporting there is bugs.kde.org. Is there any interface out there to ease error reporting for users? This may be considered separate from development, but perhaps some sort of reporting software, and configuration information for a bug server that would be bugs.kde.org compatible (to keep changes to a bug reporting app to a minimum) would be something ISV's would hold a specific interest in.
# KOffice - Kross is included on devnew - are there other ways ISV's can add onto KOffice? This would probably tie in well with #5 Business Communications Flow. Also, additional projects that maintain the same style as KOffice would be good to note specifically here.
# Design Patterns?
# KDevelop
## Learning the languages
## Tutorials using KDevelop
# Portable devices - Zaurus, Palm, etc, working with them and KDE, how to create a KDE app using opensync (im guessing here), links to qtopia and interoperability here, etc?
# More info - blogs, places to put code, irc channels, newsgroups, events, etc. Could also house sections designated to education, government, corporate, or even perhaps medical and other specific types. Courses and certifications, if applicable.
# Audio & Video casts?

Just some random thoughts... Opinions?

: Especially video casts could be interesting. Blender once had some videos. KDevelop could benefit here, as well as Quanta. Besides, this are quite some ideas we definitely should think about. This discussion could also go to the discussion of [[Projects/Partners]] =) --[[User:Dhaumann|Dhaumann]] 21:30, 15 January 2007 (CET)

:: True, I didn't want to clutter the Projects page with too much stuff. I'll reformat it for easier reading/more coherent thoughts later, and add it then. --[[User:CuCullin|CuCullin]] 21:42, 15 January 2007 (CET)

:1. Forums - I really think that KDE would benefit from an official user forum. But for core development issues, I think that the mailing lists are preferred. You'd never manage to convince everyone to switch to using a forum anyway. A forum.kde.org could only be a benefit as far as I'm concerned. Just as long as we have people willing to devote time to it.<br />6. Error reporting functionality - The problems with any sort of non-bugzilla interface were brought up when ''LikeBack'' was discussed on the mailing lists. Having more than one place where bugs are stored will cause unnecessary work. But I do agree, a simpler entry point wouldn't go amiss.<br />7. KOffice - I guess it depends on what the KOffice devs want (since they'd be the best ones to maintain something like that).<br />8. Design Patterns - These definitely should be located on devnew. Most likely in the Tutorials section.

::6. Error reporting - I was thinking more of an application-type interface such as KBugBuster, but I believe that just scrapes bugs.kde.org. Something that could interface more directly would probably be a big benefit.

User talk:CuCullin

2007-01-15T20:42:06Z

CuCullin:

Projects/Oxygen/Sound Theme Naming Specification

2007-01-15T19:30:00Z

CuCullin:

*NOTE - '''This section is under HEAVY development. Keep it as an orphaned page for the time being.'''

== Overview ==

== Context ==

The contexts for a sound theme are (these are more or less placeholders as this schema is sorted out):

{| border="1"
|+ Table 1. Sound Theme Contexts
! Name !! Description !! Directory
|-
| System Events || Sounds which are generally used to notify the user of events relating to the system, ie: startup, warning dialogs, etc || system
|-
| User Interface Events || Sounds associated with the desktop environment, such as minimize, shade, or kicker events || ui
|-
| Misc. Application Events || Sounds associated with application events, such as a successful cd burn, which don't fit within other categories || application
|}

== System Events ==
A list for now

* Network events
* Startup
* Shutdown
* Hibernate
* Standby
* Close Program
Critical Battery Alarm
Critical Stop
Default Beep
Device Connect
Device Disconnect
Device Failed to Connect
Exclamation
Exit
Low Battery Alarm
Menu Popup
Open Program
Print Complete
Program Error
Question
Restore Down
Restore Up
Select
Show Toolbar
Start
System Notification
Logoff
Logon

== User Interface Events ==
* Minimize
* Minimize to Tray
* Maximize
* Restore
* Restore from Tray
* Shade Up
* Shade Down
* Menu Browse
* Menu Select

== Application Level Events ==

=== Communication Events ===
* New Email
* New IM
* Name mentioned in chat room
* Connected to messaging server
* Disconnected from messaging server
* Person Joins
* Person Leaves
* Receive Call
* Receive Request to Join
* Contact Online
* New Alert
* New Message
* New Mail

=== Miscellaneous and Cross-Category Events ===
* Successful (cd burn, file transfer, etc. Possibly separate these)

== References ==
* [http://tango.freedesktop.org/Standard_Icon_Naming_Specification Tango Icon Specification]

----File/Web Browser----
Blocked Pop up
Empty Trash
Information Bar
Move Menu Item
Main Menu Navigation

User talk:CuCullin

2007-01-15T16:26:44Z

CuCullin:

ISV/KDE Community

2007-01-14T18:04:14Z

CuCullin: Got the page started....

{{improve}}

KDE attracts many people with different backgrounds. As such, the day-by-day growing KDE community includes many '''developers''', '''translators''', '''artists''' as well as '''usability and accessibility experts''' and - of course - '''lots of users'''. For several years now all those people are welcome to meet at the '''annual KDE Conference [http://akademy.kde.org/ aKademy]''' to discuss KDE related topics and shape the ''roadmap'' for future development.

ISV/Why use KDE

2007-01-14T18:01:50Z

CuCullin: /* Sub-Projects */ Reworded sub-project text

This page intends to help '''Independent Software Vendors (ISVs)''' getting into KDE related topics. This includes companies developing commercial applications as well as other Open Source Projects.

== The KDE Community ==
The KDE project attracts many people with different backgrounds. As such, the day-by-day growing KDE community includes many '''developers''', '''translators''', '''artists''' as well as '''usability and accessibility experts''' and - of course - '''lots of users'''. For several years now all those people are welcome to meet at the '''annual KDE Conference [http://akademy.kde.org/ aKademy]''' to discuss KDE related topics and shape the ''roadmap'' for future development.

== KDE e.V. ==
The non-profit organization [http://ev.kde.org KDE e.V.] helps in creating and distributing KDE by securing cash, hardware, and other donations, then using donations to aid KDE development and promotion. All its members are part of the KDE community which means the KDE e.V. plays an important role in the KDE project. Members of the KDE e.V. form several '''working groups''' like the [http://www.spreadkde.org/handbook/mwg/charter Marketing Working Group (MWG)] and the Human-Computer Interaction (HCI) Working Group to help realize KDE's vision.

== Adoption of KDE ==
KDE is one of the biggest Open Source projects making the Linux/UNIX desktop's experience much more user friendly. As such, distributions strongly support KDE by actively taking part in its development process and ship KDE as their default desktop environment. Many companies use KDE for production use.

== Development ==
The KDE development process takes place in steady release cycles. '''[http://developer.kde.org/development-versions/release.html Release schedules]''' and '''feature plans''' help the KDE project coordinating a KDE release by introducing several ''phases'' like ''feature freeze'' and ''message freeze''. This phases make sure that developers concentrate on polishing the release and the translation teams have time enough to translate all the KDE software into many different languages. Further information about KDE development tools can be found on the [[Development|development pages]].

=== Documentation ===
The KDE project provides excellent documentation about its API and its technologies, such as KParts or KXmlGui. There are many '''Tutorials and HOWTOs''' which help getting into KDE development. An overview can be found at the [[Development|development pages]].

=== Technologies ===
KDE provides a wide range of '''powerful technologies''' such as [http://khtml.info KHTML and KJS] which are adopted by other companies like Apple (Safari browsers) and Nokia. Additionally there are several '''development frameworks''' like KParts (KDE's component technology), KIO (network/protocol architecture) or KXmlGui (build GUIs based on XML definitions).

KDE uses '''well-known standards''' like DCOP in KDE 3 or [http://hal.freedesktop.org HAL (Hardware Abstraction Layer)] and [http://dbus.freedesktop.org D-Bus] (interprocess communication) in upcoming KDE 4.

=== Compatibility & Integration ===
The last major KDE release was KDE 3. All KDE 3.x versions are '''binary compatible''', i.e. software written five years ago is compatible to the latest stable release KDE 3.5. As KDE is based on standards it is for instance easy to integrate applications with plain [http://todo-link-to-howto .desktop files].

==== Freedesktop.org & Portland ====
As an ISV, your target is probably not only KDE but all Linux/UNIX desktops. This is made possible due to '''strong collaboration between KDE and other projects''' like [http://freedesktop.org freedesktop.org] which defines standards and software that helps integrating applications in all standard conform desktop environments.

One of those projects is the [http://developer.kde.org/portland/ Portland project], which intends to develop a common set of Linux Desktop Programming Interfaces and Tools to allow applications to '''easily integrate''' with the free desktop configuration an end user has chosen to work with.

=== Sub-Projects ===
KDE has many sub-projects to more specifically coordinate unique project goals of major supporting applications. Several of these significant projects are noted below:

; KDE Pim
: The goal of [http://pim.kde.org KDE Pim] (Personal information management) is to provide an application suite to manage personal information. This includes applications like an email client, a calender etc. The main result is '''KDE Kontact''', our personal information manager.

; KOffice
: [http://koffice.kde.org KOffice] is an '''integrated office suite''' using KDE-technology and features a full set of applications which work together seamlessly to provide the best user experience possible. The office suite contains applications like KWord, KSpread, KPresenter, Krita and many more.

; KDevelop
: [http://kdevelop.kde.org KDevelop] is an '''Integrated Development Environment''' (IDE) for KDE. It supports language like C/C++ and Java and helps with rapid application development.

=== Licensing ===
An often arising question is: ''Can I use KDE to develop commercial applications?'' - '''Yes, you can develop commercial applications for KDE'''. KDE's foundation libraries {{path|kdelibs}} and {{path|kdepimlibs}} but also KOffice libraries and several of its major apps are licensed under the LGPL, which means you can link closed source applications against those libraries. A valid Qt developer license is required for closed source development, however.

== Roadmap ==
KDE development follows a release schedule in order to coordinate releases. These usually cover for minor releases the last 10 weeks and for major releases the last 20 weeks before the official release. The features planned for a release are usually published at the same time as the schedule.

Further details can be found in the [[../Roadmap|roadmap page]].

[[Category:ISV]]

ISV/Licensing

2007-01-14T17:59:14Z

CuCullin: /* Licensing */ - rewording.....

=== Licensing ===
An often arising question is: ''Can I use KDE to develop commercial applications?'' - '''Yes, you can develop commercial applications for KDE'''. KDE's foundation libraries {{path|kdelibs}} and {{path|kdepimlibs}}, as well as KOffice libraries and other major supporting applications, are licensed under the [http://www.gnu.org/copyleft/lesser.html LGPL]. The [http://www.gnu.org/copyleft/lesser.html LGPL] allows the linking of closed source applications against those libraries. Though, a [http://www.trolltech.com/products/qt/licenses Qt developer license] is required for closed source development.

[[Category:ISV]]

ISV/Roadmap

2007-01-14T17:53:42Z

CuCullin: /* Sub-projects */

This page intends to help '''Independent Software Vendors''' (ISVs) understanding the background of the KDE Roadmap.

== KDE stable releases ==

The current KDE release is KDE version 3.5.5. Based on the knowledge and experiences of the first KDE 3.x releases the KDE 3.5 series is a well matured and stable platform to rely on.

The development of the KDE 3.5.x series will continue to improve this platform without breaking any compatibility, ensuring that every developer can rely on it. Different from previous KDE release, however, the KDE 3.5.x series will include selected new features to include new technologies and provide new possibilities while the long KDE 4 development cycle takes place.

The Roadmap of KDE 3.5.x is divided into the [[Schedules/KDE_3.5_Release_Schedule|Release Schedule]] and the [http://developer.kde.org/development-versions/kde-3.5-features.html Feature Plan].

== KDE development ==

The current KDE development concentrates on KDE 4, which will be a major release. It will include several new features as well as new APIs and frameworks and therefore will break the API compatibility. However, at the same time there are several efforts in the community making porting apps to KDE 4 quite easy.

The Roadmap of KDE 4 is divided into the [[Schedules/KDE_4.0_Release_Schedule| Release Schedule]] and the [http://developer.kde.org/development-versions/kde-4.0-features.html Feature Plan].

== Sub-projects ==

Some KDE sub-projects have their own roadmaps:
* [http://multimedia.kde.org/roadmap.php KDE Multimedia project] - supported by [http://phonon.kde.org/ Phonon], a new multimedia API.
* [http://koffice.kde.org/developer/ KOffice] - a free, integrated office suite for KDE

[[Category:ISV]]

Development/Architecture/KDE3

2007-01-12T21:40:26Z

CuCullin: /* Development HOWTOs */

{{improve}}

==Development Framework==
#[[/Library Structure|Library Structure]]
#Accessing System Resources
##[[/Standard Resources|Standard Resources]]
##[[/Icon Loader|Icon Loading]]
##[[/System Configuration Cache|System Configuration Cache (KSycoca)]]
#Graphics
##[[/Low-level Graphics|Low-level graphics with QPainter]]
##[[/Structured Graphics|Structured graphics with QCanvas]]
##[[/OpenGL Support|3D graphics with OpenGL]]
#User Interface
##[[/Action Pattern|Action Pattern]]
##[[/XMLGUI Technology|Defining menus and toolbars in XML]]
##[[/Providing Online Help|Providing online help]]
#Complex Widgets
##[[/KHTML|HTML renderer]] with JavaScript
##[[/KFile Library|File dialog]]
##[[/Data Views|Displaying large amounts of data - Using QListView, QListBox and QIconView]]
#Components and Services
##[[/Services|KDE services]]
##[[/MIME Types|MIME types]]
##[[/Network Transparency|Network transparency]]
#Inter Client Communication
##[[/DCOP|Desktop Communication Protocol (DCOP)]]
#[[/Starting Other Programs|Starting Other Programs]]
#[[/i18n and l10n|il8n and l10n]]

==Desktop Framework==
#[[/Panel Applets|Panel Applets]]
#[[/Control Center Modules|Control Center Modules]]

==Multimedia Framework==
#[http://space.twc.de/~stefan/kde/arts-mcop-doc/ aRts] - the current state
#[[/Imaging and Animation|Imaging and Animation]]

==Component Architecture==
#[[/KParts|KParts]]
#[[/Docking Into the Panel's System Tray|Docking Into the Panel's System Tray]]
#[[/Java Integration|Java Integration]]

==KOffice Architecture==
#[[/Document and View Introduction|Document and View Introduction]]
#[http://www.koffice.org/filters/ File Format Filters]

==Protocols==
#[http://www.freedesktop.org/wiki/Standards_2fwm_2dspec Window Management]
#[[/Session Management|Session Management]]
#[[/System Tray Docking|System Tray Docking]]
#[[/Drag-And-Drop|Drag-And-Drop]]
#[[/Printing|Printing]]

==Development Tools==
#[[/Interface Documentation Tool|Interface Documentation Tool (Doxygen)]]
#[[/Integrated Development Environment|Integrated Development Environment (KDevelop)]]
#[[/Graphical Debugger|Graphical Debugger (kdbg)]]
#[[/VCS Frontend|VCS Frontend (Subversion)]]
#[[/Advanced Developer Text Editor|Advanced Developer Text Editor (Kate)]]
#[[/Icon Editor|Icon Editor (KIconEdit)]]
#[[/Hex Editor|Hex Editor]]

==Development HOWTOs==
#[[Development/Architecture/Binary_Compatibility_Issues_With_C%2B%2B|Binary Compatibility Issues With C++]]

[[Category:KDE3]]

Development/Architecture/KDE3

2007-01-12T21:39:28Z

CuCullin: /* Development HOWTOs */

{{improve}}

==Development Framework==
#[[/Library Structure|Library Structure]]
#Accessing System Resources
##[[/Standard Resources|Standard Resources]]
##[[/Icon Loader|Icon Loading]]
##[[/System Configuration Cache|System Configuration Cache (KSycoca)]]
#Graphics
##[[/Low-level Graphics|Low-level graphics with QPainter]]
##[[/Structured Graphics|Structured graphics with QCanvas]]
##[[/OpenGL Support|3D graphics with OpenGL]]
#User Interface
##[[/Action Pattern|Action Pattern]]
##[[/XMLGUI Technology|Defining menus and toolbars in XML]]
##[[/Providing Online Help|Providing online help]]
#Complex Widgets
##[[/KHTML|HTML renderer]] with JavaScript
##[[/KFile Library|File dialog]]
##[[/Data Views|Displaying large amounts of data - Using QListView, QListBox and QIconView]]
#Components and Services
##[[/Services|KDE services]]
##[[/MIME Types|MIME types]]
##[[/Network Transparency|Network transparency]]
#Inter Client Communication
##[[/DCOP|Desktop Communication Protocol (DCOP)]]
#[[/Starting Other Programs|Starting Other Programs]]
#[[/i18n and l10n|il8n and l10n]]

==Desktop Framework==
#[[/Panel Applets|Panel Applets]]
#[[/Control Center Modules|Control Center Modules]]

==Multimedia Framework==
#[http://space.twc.de/~stefan/kde/arts-mcop-doc/ aRts] - the current state
#[[/Imaging and Animation|Imaging and Animation]]

==Component Architecture==
#[[/KParts|KParts]]
#[[/Docking Into the Panel's System Tray|Docking Into the Panel's System Tray]]
#[[/Java Integration|Java Integration]]

==KOffice Architecture==
#[[/Document and View Introduction|Document and View Introduction]]
#[http://www.koffice.org/filters/ File Format Filters]

==Protocols==
#[http://www.freedesktop.org/wiki/Standards_2fwm_2dspec Window Management]
#[[/Session Management|Session Management]]
#[[/System Tray Docking|System Tray Docking]]
#[[/Drag-And-Drop|Drag-And-Drop]]
#[[/Printing|Printing]]

==Development Tools==
#[[/Interface Documentation Tool|Interface Documentation Tool (Doxygen)]]
#[[/Integrated Development Environment|Integrated Development Environment (KDevelop)]]
#[[/Graphical Debugger|Graphical Debugger (kdbg)]]
#[[/VCS Frontend|VCS Frontend (Subversion)]]
#[[/Advanced Developer Text Editor|Advanced Developer Text Editor (Kate)]]
#[[/Icon Editor|Icon Editor (KIconEdit)]]
#[[/Hex Editor|Hex Editor]]

==Development HOWTOs==
#[[/Development/Architecture/Binary_Compatibility_Issues_With_C%2B%2B|Binary Compatibility Issues With C++]]

[[Category:KDE3]]

Development/Architecture/KDE3/Java Integration

2007-01-12T21:20:25Z

CuCullin:

{{Improve}}

==Introduction==

KDE makes it easy for application developers to add support for Java applets to their applications. The ''kdejava'' library provides a high level API that allows Java applets to be manipulated as if they were a normal QWidget. Lars and I added support for applets to khtml in a matter of hours at the KDE II conference - it really is that easy. KDE's Java support is in two parts, there is a pure Java server which provides the environment in which applets run etc. and a KDE library which handles the embedding of the applet window into the application. The Java and C++ code communicates via standard UNIX pipes using a simple text based protocol. It should be possible to use '''any''' Java VM with KJAS, including Java 2.

==Simple Usage Example==

<nowiki>
#include <kapp.h>
#include <kjavaappletwidget.h>
#include <qstring.h>

int main(int argc, char **argv)
{
KApplication app( argc, argv );

QString a,b,c,d,e,f;

// The name of the applet
a = "fred";
// The name of the class to be run
b = "Lake.class";
// The base url it can be found at. Note the trailing '/', we could
// also have written it as "file:/dos/pcplus/java/lake/Lake.html"
c = "file:/dos/pcplus/java/lake/";

// Create the applet widget. We are using the default context and
// server implicitly. We could have specified different ones. We
// could also specify a parent QWidget, but we might as well make
// the applet widget top level for this example.
KJavaAppletWidget *applet = new KJavaAppletWidget();
CHECK_PTR( applet );

// You must set these BEFORE calling show()
applet->setAppletName( a );
applet->setAppletClass( b );
applet->setBaseURL( c );

// My test applet needs an image to be specified as a parameter.
d = "image";
e = "arch.jpg";
applet->setParameter( d, e );

// We show the widget as normal
applet->show();

// Then start the event loop
app.exec();
}
</nowiki>

==Design==

The diagram below shows the relationships between some of the more important classes involved in the KDE Java support. Those classes in libkdejava are C++ classes, all of the rest of the system is written in Java. There is no dependency other than the JVM for the KJAS server, this is the core of the KDE Java environment and could also be used to add Java support to other systems - you can control applets from a shell script using a KJAS server for example.

<center>[[Image:kdejava.gif|KDE Java Architecture]]</center>

Unlike the Java support in Netscape or MS IE, KDE's support uses an out of process JVM - i.e. the JVM itself is not linked to the application that embeds the applet. The table below should explain some of the reasons behind this decision: <br />

<center>

{| width="90%" bgcolor="#CCFFFF"
! bgcolor="#66FFFF" align="CENTER" | In process
! bgcolor="#66FFFF" align="CENTER" | Out of process
|-
| Have to contend with threading issues
| No threading problems
|-
| JVM crash will kill Konqueror
| JVM crash easy to handle
|-
| JVM load may block the application UI
| No problem
|-
| JVM cannot be unloaded
| JVM unload by killing child process
|-
| Fairly easy to communicate with the JVM (JNI)
| Need custom communication mechanism
|-
| Multiple VMs impossible
| Multiple VMs possible
|-
| Depends on a working Qt AWT port
| Can use the standard AWT
|}

</center>

An important advantage of the out of process approach is that it allows us to make use of the standard Motif implementation of the AWT, if we were using an in-process implementation this would require us to merge the Motif and Qt event loops which would be tricky to implement without the AWT peer class sources. Ultimately the plan is to remove the Motif dependency (and the associated memory hit) completely, but until the Qt port of the AWT is finished, this is impossible. The existing solution using swallowing is not perfect, but works reasonably well, when the QtAWT is finished it will be possible to use the QXEmbed API to provide a more polished embedding mechanism. It will also be possible to provide the option an in process JVM which may prove useful in some situations.

==Class overview==

This section outlines the major classes in ''libkdejava'', more detailed information is provided by the kdoc documentation.

* '''KJavaAppletWidget'''<br />This is the class responsible for the integration of the applet window into the KDE applications GUI. In simple cases, this is the only class you need to worry about and it provides a very straightforward API.
* '''KJavaApplet'''<br />This is the class responsible for managing an applet. It ensures the applet is downloaded and provides the ability to start and stop the applet etc.
* '''KJavaAppletContext'''<br />This is the environment in which applets exist. Applets in the same context can communicate with each other, those in different contexts cannot. In a web browser all the applets in a single frame will exist in the same context. The context can also be used by applets to communicate with the application they are embedded in, though this communication is currently very limited.
* '''KJavaAppletServer'''<br />This is the class that provides access to the KJAS server. Normally, you can ignore this class as you will be automatically assigned a default server.
* '''KJavaProcess'''<br />This is a wrapper for KProcess that provides a higher level API for invoking a JVM.

There are a number of other classes in the library, but at the moment they should be regarded as ''internal'' parts of the implementation.

===The road ahead===

The current implementation of KDE-Java is not the end of the story, there are a number of other developments in the works. This section is simply intended to inform you of what to expect, if you want more detailed information then check out the ''kdejava'' CVS module where the code is kept.

As I mentioned earlier I am working on QtAWT, a port of the AWT to the Qt toolkit. This is important for the future development of KDE Java, and has made significant progress. It is possible to create most of the predefined widgets, and to set properties such as the text of push buttons. There is currently no event dispatching, and no support for important classes such as the Canvas however, so the port cannot be considered even half complete. The port is now working with Qt 2.0, though the handling of Unicode strings is not optimal.

In addition to support for standard Applets as used on the web, I also plan to support some extra facilities to allow applications to provide custom applet types/plugins. This facility is not currently very high priority, so it is unlikely to be ready for KDE 2.0, perhaps you'll see it in version 2.1.

==Help required==

There are a number of other projects that I would love to see someone working on, but which I don't have the time to do myself. If you know Java and are looking for a project then why not give one of these a try?

* A Swing look and feel that integrates with KDE widget themes
* A JNI binding to the KDE libraries
* Java protocol handlers that provide access to the KIO library. This will allow Java to support SSL, tar files etc.

In addition to the above, help with either the QtAWT , KJAS or libkdejava is always welcome.

Development/Architecture/KDE3/Docking Into the Panel's System Tray

2007-01-12T21:17:09Z

CuCullin:

{{Improve}}

A tray window is a small window (typically 24x24 pixel) that docks into the system tray in the desktop panel. It usually displays an icon or an animated icon there. The icon serves as representative for the application, similar to a taskbar button, but consumes less screen space.

[[Image:docking.png|System tray screenshot]]

A CD Player and a Notes application inside the panel's system tray.

When the user clicks with the left mouse button on the icon, the main application window is shown/raised and activated. With the right mouse button, she gets a popupmenu with application specific commands, including "Minimize/Restore" and "Quit".

Having an icon on the system tray is a useful technique for daemon-like applications that may run for some time without user interaction but have to be there immediately when the user needs them. Examples are kppp, kisdn, kscd, kmix or knotes. With kppp and kisdn, the docked icon even provides real-time information about the network status.

With the KSystemTray in libkdeui, KDE provides a very simple API to add system tray items from your application. See the KSystemTray documentation in the [http://developer.kde.org/documentation/library/3.1-api/classref/kdeui/KSystemTray.html KDE 3.1 API Reference ] for further details.

The mechanism works for non-KDE applications just as well. See the description of the [http://developer.kde.org/documentation/library/kdeqt/kde3arch/protocols-docking.html system tray docking protocol] for details.

Development/Architecture/KDE3/KParts

2007-01-12T21:15:27Z

CuCullin:

{{Improve}}

The main idea behind components is reusability. Often, an application wants to use a functionality that another application provides. Of course, the way to do that is simply to create a shared library that both applications use. But without a standard framework for this, it means both applications are very much coupled to the library's API and will need to be changed if the applications decide to use another library instead. Furthermore, integrating the shared functionality has to be done manually by every application.

A framework for components enables an application to use a component it never heard of - and wasn't specifically adapted for - because both the application and the component comply to the framework and know what to expect from each other. An existing component can be replaced with a new implementation of the same functionality, without changing a single line of code in the application, because the interface remains the same.

The framework presented here concerns elaborate graphical components, such as an image viewer, a text editor, a mail composer, and so on. Simpler graphical components are usually widgets; I refine this distinction in the next section. Nongraphical components, such as a parser or a string manipulation class, are usually libraries with a specific Application Programming Interface (API).

Similar frameworks for graphical components exist for a different environment, such as IBM and Apple's OpenDoc, Microsoft's OLE, Gnome's Bonobo, and KDE's previous OpenParts.

==The Difference Between Components and Widgets==

A KDE component is called a ''part'', and it encapsulates three things: a widget, the functionality that comes with it, and the user interface for this functionality.

The usual example is a text editor component. Its widget is a multiline text widget; its functionality might include Search And Replace, Copy, Cut, Paste, Undo, Redo, Spell Checking. To make it possible for the user to access this functionality, the component also provides the user interface for it: menu items and toolbar buttons.

An application using this component will get the widget embedded into a parent widget it provides, as well as the component's user interface merged into its own menubar and toolbars. This is like embedding a MS Excel document into MS Word, an example everybody knows, or when embedding a KSpread document into KWord, an example that will hopefully become very well known as well.

Another example of very useful component is an image viewer. When using KDE's file manager (Konqueror), clicking an image file opens the image viewer component from KDE's image viewer (KView) and shows it inside Konqueror's window. The part provides actions for zoom in, zoom out, rotate, reset to original size, and orientation.

{| width="90%" cellpadding="3" align="center"
| bgcolor="#DDDDDD" |
'''Note -''' Note that KOffice parts are a bit different because they don't embed as a full window, but as a frame into the parent's view, which can be moved, resized, and even rotated - a functionality only KOffice has. This and the document/view architecture of KOffice applications mean that the framework for KOffice parts, although based on KParts, is much more elaborate and out of topic here.
|}

<br />

So, when do you use a part and when do you use a widget?

Use a widget when all the functionality is in the widget itself and doesn't need additional user interface (menu items or toolbar buttons). A button is a widget, a multiline edit is a widget, but a text editor with all the functionality previously mentioned is a part. As you can see there is no problem choosing which one to use.

==The KDE Component Framework==

KParts is the framework for KDE parts, based on standard KDE/Qt objects, such as QWidget and KTMainWindow. It defines a very simple set of classes: part, plugin, mainwindow, and part manager.

<blockquote>

A ''part'', as previously described, is the name for a KDE component. To define a new part, you need to provide the widget, of course, but also the actions that give access to the part's functionality and an XML file that describes the layout of those actions in the user interface.

A ''plugin''is a small piece of functionality that is not implemented by an embedded widget, but that defines some actions to be merged in the application's user interface, such as the calculator plugin for KSpread. It can be graphical, however, like a dialog box or a separate window popping up, or it can be an application-specific plugin and act on the application itself - a spell checker for a word processor, for example.

A KParts ''mainwindow''is a special KTMainWindow whose user interface is described in XML and with actions so that it is able to embed parts. The reason it has to use XML is because merging user interfaces is implemented by merging XML documents.

A ''part manager''is a more abstract object whose task is to handle the activation and the deactivation of the parts. Of course, this is useful only for mainwindows that embed more than one part, such as KOffice documents (where the main document is also a part), or Konqueror (where each view is a part). KWrite, which embeds only its own part, doesn't need a part manager.

</blockquote>

In the following sections, you create a part for a simple text editor, a main window able to embed an existing PostScript-viewer part, a part manager to embed more than one part, and even a plug-in; thus, you will know everything about KParts.

==Describing User Interface in XML==

The XML file used by a part or a mainwindow provides only the layout of the actions in the user interface. The actions themselves are still implemented in the code, with slots, as usual.

More precisely, the XML file describes the layout of the menus and submenus in the menubar (only one menubar is always present) and the menu items within those menus, as well as the toolbars and the toolbar buttons. The menubar, menus, and toolbars are containers; menu items and toolbar buttons are the actions.

A sample XML file for a mainwindow looks like the one shown in Listing 13.1.

====''Listing 13.1 Excerpt of konqueror.rc: A User Interface Described in XML''====

<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<kpartgui name="Konqueror" version="1">
<MenuBar>
<Menu name="file"><Text>&File</Text>
<Action name="find"/>
<Separator/>
<Action name="print"/>
<Separator/>
<Action name="close"/>
</Menu>
<Menu name="edit"><Text>&Edit</Text>
<Action name="cut"/>
<Action name="copy"/>
<Action name="paste"/>
<Action name="trash"/>
<Action name="del"/>
<Separator/>
<Merge/>
<Separator/>
</Menu>
<Merge/>
</MenuBar>
<ToolBar fullWidth="true" name="mainToolBar"><Text>Main</Text>
<Action name="cut"/>
<Action name="copy"/>
<Action name="paste"/>
<Action name="print"/>
<Separator/>
<Merge/>
<Separator/>
<Action name="animated_logo"/>
</ToolBar>
<ToolBar name="locationToolBar"><Text>Location</Text>
<Action name="toolbar_url_combo"/>
</ToolBar>

</kpartgui>

The DOCTYPE tag contains the name of the main element, which should be set to kpartgui. The top-level elements are MenuBar and ToolBar, as expected. In the MenuBar, the menus are described. Note that they have a name, used for merging later on, and a text, which is displayed in the user interface, possibly translated. Because this is XML, & has to be encoded as &. Inside a Menu tag, the actions, some separators, and possibly submenus are laid out. The action names are very important because they are used to match the actions created in the code.

The toolbars are then described. Note that the main toolbar has to be called mainToolBar because its settings can be different. KToolBar takes care of adding text under icons for this particular toolbar, if the user wants them. Actions are laid out in the toolbars the usual way. The text for a toolbar is used where the name of the toolbar is to be displayed to the user, possibly translated, such as the toolbar editor.

Another important tag is the Merge tag. This tag tells the framework where the actions of the active part - and the plug-ins - should be merged in a given container. As you can see, this XML file inserts the part's actions before a separator in the Edit menu, whereas it doesn't specify a position for items in the File menu. This means that if the part defines actions for the File menu, they will be appended to the File menu of the mainwindow.

The merging happens when a part simply uses the same menu name or toolbar name as the mainwindow.

If a Merge tag is specified as a child of the MenuBar tag, the merging happens at that position; otherwise, it takes place on the right of the existing menus. The toolbar allows merging of the part's actions as well, based on the same principle.

The Merge tag can also appear in a part's XML. It will be used for merging plug-ins or for more advanced uses; the merging engine can merge any number of "inputs" and it is possible to define specific inputs, such as the one Konqueror defines for its View menu.

Another advanced use of the Merge tag is to set a name attribute for it. For instance, if another XML file wants to embed a part and any other parts or plug-ins at different positions in a given menu, it can use two merge tags:

<Merge name="MyPart"/>
.
.
.

<Merge />

Using the name attribute for the Merge tag allows you to control at which position each XML fragment is merged, but it is usually unnecessary.

==Read-Only and Read/Write Parts==

The framework defines three kind of parts. The generic class is Part and is the one that provides the basic functionality for a part: widget, XML, and actions.

===Read-Only Parts===

The class ReadOnlyPart provides a common framework for all parts that implement any kind of viewer. A text viewer, an image viewer, a PostScript viewer, and a Web browser are all viewers. What they have in common is that they all act on a URL, and in a read-only way. It has always been a design decision in KDE to provide network transparency wherever possible, which is why most KDE applications use URLs, not only filenames. The framework defines methods for opening a URL, closing a URL, and above all provides network transparency - by downloading the file, if remote, and emitting signals (started, progression, completed). The part itself has to provide only openFile(), which opens a local file.

This common framework for read-only parts enables applications to embed all viewers the same way and to better control those parts. For instance, when Konqueror uses a read-only part to display a file, it can make it open the file using openURL() and get all the progress information from the part. All this is not available in the generic Part class.

===Read-Write Parts===

The third kind of part is the ReadWritePart, which is an extension of the read-only one, to which it obviously adds the possibility to modify and save the document. This is the one used by a text editor part such as KWrite's, as well as all KOffice parts.

For read/write parts, the framework provides the other half of the network transparency - re-uploading the document when saving, for remote files. A read/write part must also know how to act read-only, in case it is used as a read-only part. This is what happens when embedding KWrite or KOffice into Konqueror to view a text file, without being allowed to edit the file. More generally, any editor can be and must know how to be a viewer, as well.

==Creating a Part==

In this section, you create a very simple part for a text editor. If you have closely followed the previous section, you know that the part should inherit KParts::ReadWritePart.

At this point, it is a very good idea to read kparts/part.h, directly or preferably after running kdoc on it (see Chapter 16, "Creating Documentation," for information about kdoc). This tells you that a read/write part implementation has to provide the methods openFile() and saveFile().

The task of openFile() is obviously to open a local file, which the framework has previously downloaded for us in case the URL that the user wants to open is a remote one. In this case, the file you open is a temporary local file.

In saveFile(), the part saves to the local file, and in case it's a temporary file, the framework takes care of uploading the new file.

You can now sketch the header file for your part, which is called NotepadPart (see Listing 13.2).

====''Listing 13.2 notepad_part.h: Header of the ''NotepadPart'' Class''====

1: #ifndef __notepad_h__
2: #define __notepad_h__
3:
4: #include <kparts/part.h>
5:
6: class QMultiLineEdit;
7:
8: class NotepadPart : public KParts::ReadWritePart
9: {
10: Q_OBJECT
11: public:
12: NotepadPart( QWidget * parent, const char * name = 0L );
13: virtual ~NotepadPart() {}
14:
15: virtual void setReadWrite( bool rw );
16:
17: protected:
18: virtual bool openFile();
19: virtual bool saveFile();
20:
21: protected slots:
22: void slotSelectAll();
23:
24: protected:
25: QMultiLineEdit * m_edit;
26: KInstance *m_instance;
27: };
28:

29: #endif

The parent passed to the constructor is both the parent of the widget and the parent of the part itself, so that both get destroyed if the parent is destroyed. Note that having the same parent is not mandatory. If they have different parents, the framework deletes the widget if the part is destroyed and deletes the part if the widget is destroyed.

The class members are a QMultiLineEdit (the multiline widget from Qt), and a KInstance. An instance enables access to global KDE objects, which can be different from the ones of the application. The application's configuration file and the one of any other instance is different, as well as the search paths for locate(), and so on. In KParts, this is used to locate the XML file describing the part, which is usually installed into share/apps/''instancename''/.

In addition, you define a slot, slotSelectAll(), to be connected to the action your part provides.

The corresponding XML file for the part NotepadPart is listed in Listing 13.3 and defines its GUI by an action named selectall, to be inserted into the menu Edit in the menubar. Note that the text for the Edit menu is specified, which is mandatory even if mainwindows usually specify it, because it has to work even if a mainwindow doesn't have an Edit menu on its own. So the rule is simple: always provide a text for all menus.

====''Listing 13.3 notepadpart.rc: XML Description of the Notepad Part's User Interface''====

<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<kpartgui name="NotepadPart" version="1">
<MenuBar>
<Menu name="Edit"><Text>&Edit</Text>
<Action name="selectall"/>
</Menu>
</MenuBar>
<StatusBar/>

</kpartgui>

An important task in the definition of a part is its constructor. It must at least define the instance, the widget, the actions, and the XML File. The constructor for this example could be as shown in Listing 13.4.

====''Listing 13.4 notepad_part.cpp part 1: Constructor''====

1: NotepadPart::NotepadPart( QWidget * parent, const char * name )
2: : KParts::ReadWritePart( parent, name )
3: {
4: KInstance * instance = new KInstance( "notepadpart" );
5: setInstance( instance );
6:
7: m_edit = new QMultiLineEdit( parent, "multilineedit" );
8: m_edit->setFocus();
9: setWidget( m_edit );
10:
11: (void)new KAction( i18n( "Select All" ), 0, this,
12: SLOT( slotSelectAll() ), actionCollection(), "selectall" );
13: setXMLFile( "notepadpart.rc" );
14:
15: setReadWrite( true );

16: }

After calling the parent constructor with parent and name, you create an instance, named notepadpart, and declare it to the framework using setInstance(). This is a temporary solution; you'll see later how to use a library-factory's instance. Then you create the multiline edit widget, give it the focus, and declare it as well, using setWidget().

The next step is to create the actions that your part provides. The "selectall" action is given a translated label, is connected to slotSelectAll(), and is created as a child of the action collection that the framework provides. This is important, because it's the only way to make it find the action later on, when parsing the XML file. This is why you don't even need to store the action in a variable, unless you want to be able to enable or disable it later.

You also need to give the framework the name of the XML file describing the part's GUI. As mentioned previously, it is usually installed into share/apps/''instancename''/, and in this case, you simply pass the filename with no path. It is also possible, but not recommended, to install the XML file anywhere else and provide a full path in setXMLFile().

Finally, the part is set to read/write mode. Read/write parts feature the setReadWrite() call, which enables you to set the read/write mode on or off. Most parts should reimplement this method to enable or disable anything that modifies the part, KActions as well as any direct modification provided by the widget itself. The reimplementation of setReadWrite() for the NotepadPart is shown in Listing 13.5.

====''Listing 13.5 notepad_part.cpp part 2: Implementation of setReadWrite''====

void NotepadPart::setReadWrite( bool rw )
{
m_edit->setReadOnly( !rw );
if (rw)
connect( m_edit, SIGNAL( textChanged() ), this, SLOT( setModified() ) );
else
disconnect( m_edit, SIGNAL( textChanged() ), this, SLOT( setModified() ) );

ReadWritePart::setReadWrite( rw ); // always call the parent implementation

}

In the example, there are no actions to disable, but the multiline widget has to be set to its read-only mode.

The connection to setModified(), done in read/write mode only, enables the framework to keep track of the state of the document. When closing a document that has been modified, the framework automatically asks whether it should save it and allow you to cancel the close. Note that to make all this work, you just needed to connect a signal when the part is in read/write mode and disconnect it when it's in read-only mode. This avoids warnings when a loading a file, which changes the text.

It might seem a bit painful to have to handle both read/write and read-only mode, but doing this gives for free the possibility to embed the part as a viewer, in Konqueror, for instance, so it's usually worth doing.

Your part is created; you need to make it useful. The method that all read-only parts - and by inheritance, all read/write parts as well - must reimplement is the openFile() method. This is where a part opens and displays the local file, whose full path is provided in the member variable m_file, and which the framework downloaded from a remote location first, if necessary. Because your part is a text viewer, all it has to do is read the file into a QString and set the multiline widget's text from it, as shown in Listing 13.6.

====''Listing 13.6 notepad_part.cpp part 3: Implementation of openFile''====

1: bool NotepadPart::openFile()
2: {
3: QFile f(m_file);
4: QString s;
5: if ( f.open(IO_ReadOnly) )
6: {
7: QTextStream t( &f );
8: while ( !t.eof() ) {
9: s += t.readLine() + "\n";
10: }
11: f.close();
12: }
13: m_edit->setText(s);
14:
15: return true;

16: }

The last thing you need to do is, of course, to provide saving; otherwise, the user will not like it! All read/write parts have to reimplement saveFile() to save the document to m_file, as shown in Listing 13.7. Note that the framework takes care of Save As (changing the URL to Save To), as well as uploading the saved file, if necessary.

====''Listing 13.7 notepad_part.cpp part 4: Implementation of saveFile''====

1: bool NotepadPart::saveFile()
2: {
3: if ( !isReadWrite() )
4: return false;
5: QFile f(m_file);
6: QString s;
7: if ( f.open(IO_WriteOnly) ) {
8: QTextStream t( &f );
9: t << m_edit->text();
10: f.close();
11: return true ;
12: } else
13: return false;

14: }

==Making a Part Available Using Shared Libraries==

You know how to create a part now. But currently, it can be used only by linking directly to its code. Although this is enough in some cases, such as KWrite's part embedded by KWrite itself, it is much more flexible to provide dynamic linking to the library containing the part. This is not directly related to KParts, but it is necessary to make it possible for any application to use the part.

The first step is to compile the part in a shared library, which is really simple using automake. The relevant portion of Makefile.am is shown in Listing 13.8

====''Listing 13.8 Extract from Makefile.am''====

lib_LTLIBRARIES = libnotepad.la
libnotepad_la_SOURCES = notepad_part.cpp notepad_factory.cpp
libnotepad_la_LIBADD = $(LIB_KFILE) $(LIB_KPARTS)
libnotepad_la_LDFLAGS = $(all_libraries) $(KDE_PLUGIN)

METASOURCES = AUTO

Your part is now available in a shared library, but this is not enough. You must provide a way for anybody opening that library dynamically to create a part. This is done using a factory, derived from KLibFactory, which you'll do in the class NotepadFactory. An application willing to open a shared library dynamically uses the class KLibLoader, which takes care of locating the library, opening it, and calling an initialization function - here init_libnotepad(). This function creates a NotepadFactory and returns it to KLibLoader, which can then call the create method on the factory. This means that all you need to do in the library itself is define init_libnotepad() and the NotepadFactory.

The header for the factory is the one shown in Listing 13.9.

====''Listing 13.9 notepad_factory.h: Header File for NotepadFactory''====

1: #include <klibloader.h>
2: class KInstance;
3: class KAboutData;
4: class NotepadFactory: public KLibFactory
5: {
6: Q_OBJECT
7: public:
8: NotepadFactory( QObject * parent = 0, const char * name = 0 );
9: ~NotepadFactory();
10:
11: // reimplemented from KLibFactory
12: virtual QObject * create( QObject * parent = 0, const char * name = 0,
13: const char * classname = "QObject",
14: const QStringList &args = QStringList());
15:
16: static KInstance * instance();
17:
18: private:
19: static KInstance * s_instance;
20: static KAboutData * s_about;

21: };

As required by KLibFactory, your factory implements the create method, which creates a Notepad part and sets it to read/write mode or read-only mode, depending on whether the classname is KParts::ReadWritePart or KParts::ReadOnlyPart.

It also features a static instance, which is used in the part, instead of creating your own instance for each part. It is static because usually there is only one instance per library.

This means the code of notepad_part.cpp should be modified to call setInstance( NotepadFactory::instance() ); instead of creating its own instance.

The implementation for the NotepadFactory is shown in Listing 13.10.

====''Listing 13.10 notepad_factory.cpp: NotepadFactory Implementation.''====

1: #include "notepad_factory.h"
2:
3: #include <klocale.h>
4: #include <kstddirs.h>
5: #include <kinstance.h>
6: #include <kaboutdata.h>
7:
8: #include "notepad_part.h"
9:
10: extern "C"
11: {
12: void* init_libnotepad()
13: {
14: return new NotepadFactory;
15: }
16: };
17:
18: KInstance* NotepadFactory::s_instance = 0L;
19: KAboutData* NotepadFactory::s_about = 0L;
20:
21: NotepadFactory::NotepadFactory( QObject* parent, const char* name )
22: : KLibFactory( parent, name )
23: {
24: }
25:
26: NotepadFactory::~NotepadFactory()
27: {
28: delete s_instance;
29: s_instance = 0L;
30: delete s_about;
31: }
32:
33: QObject* NotepadFactory::create( QObject* parent, const char* name,
34: const char* classname, const QStringList & )
35: {
36: if ( parent && !parent->inherits("QWidget") )
37: {
38: kdError() << "NotepadFactory: parent does not inherit QWidget" << endl;
39: return 0L;
40: }
41:
42: NotepadPart* part = new NotepadPart( (QWidget*) parent, name );
43: // readonly ?
44: if (QCString(classname) == "KParts::ReadOnlyPart")
45: part->setReadWrite(false);
46:
47: // otherwise, it has to be readwrite
48: else if (QCString(classname) != "KParts::ReadWritePart")
49: {
50: kdError() << "classname isn't ReadOnlyPart nor ReadWritePart !" << endl;
51: return 0L;
52: }
53:
54: emit objectCreated( part );
55: return part;
56: }
57:
58: KInstance* NotepadFactory::instance()
59: {
60: if( !s_instance )
61: {
62: s_about = new KAboutData( "notepadpart",
63: I18N_NOOP( "Notepad" ), "2.0pre" );
64: s_instance = new KInstance( s_about );
65: }
66: return s_instance;
67: }
68:

69: #include "notepad_factory.moc"

The implementation is a bit long but contains nothing complex. Basically, you define the function that is the entry point of the library, init_libnotepad(). It needs to be linked as a C function to avoid C++ name mangling. C linkage means that the symbol in the library will match the function name.

Then you define the NotepadFactory. The create method checks that the parent is a widget because this is needed for your part (remember, you create your widget with the parent widget given as an argument to the constructor). After creating the part, it has to emit objectCreated so that the library loader can do a proper reference counting; it automatically unloads the library after all objects created from it have been destroyed.

The instance() method returns the static instance, creating it first, if necessary. To create an instance, I recommend that you give it a KAboutData pointer. This gives some information about the instance representing the library (here an instance name, a translatable description of it, and a version number). You can add a lot more information in the KAboutData object, such as authors, home page, and bug-report address. See the documentation for details.

The standard KDE dialogs such as the Bug Report Dialog and the About Dialog use the data stored in KAboutData to show information about the current program, but in the future they will probably be improved to show information about the active part as well, which can have completely different About data from the application.

{| width="90%" cellpadding="3" align="center"
| bgcolor="#DDDDDD" |
'''Note -''' KParts provides a factory base class, KParts::Factory, which enhances KlibFactory by making it possible to have a parent for the widget different from the parent for the part. It also takes care of loading the translation message catalog for the newly created part. Look in kparts/factory.h for more on this.
|}

<br />

==Creating a KParts Application==

If an application wants to use parts and the GUI merging feature, its own GUI needs to be defined in XML. The top level windows of the application will then use the class KParts::MainWindow.

Note that it's also possible to use a part in a standard application, using KTMainWindow, but then no GUI merging happens. In this case, only the functionality provided by the widget and by the part API are available, so the application has to create the GUI for part's functionality itself, or the part has to provide it through context menus. In any case, it is much less flexible.

As an example of a window based on KParts::MainWindow, you are going to create a PostScript viewer very easily, by embedding the part provided by KDE's PostScript viewer, KGhostView.

{| width="90%" cellpadding="3" align="center"
| bgcolor="#DDDDDD" |
'''Note -''' You need to install the package kdegraphics if you want to test this example.
|}

<br />

The first thing to look at is the mainwindow's GUI; an example is given in Listing 13.11.

====''Listing 13.11 ghostviewtest_shell.rc: The Mainwindow's GUI''====

<!DOCTYPE kpartgui SYSTEM "kpartgui.dtd">
<kpartgui name="KGVShell" version="1">
<MenuBar>
<Menu name="file"><text>&File</text>
<Action name="file_open"/>
<Merge/>
<Action name="file_quit"/>
</Menu>
</MenuBar>
<ToolBar name="KGV-ToolBar"><text>KGhostView</text>
<Action name="file_open"/>
<Action name="file_quit"/>
</ToolBar>

</kpartgui>

By analogy with a command line's shell, a main window is often called a shell. In its GUI you define the actions that will always be shown, whichever part is active. The listing for a simple KParts mainwindow is shown in Listing 13.12

====''Listing 13.12 ghostviewtest.h: Header for a Simple KParts Mainwindow''====

1: #include <kparts/mainwindow.h>
2:
3: class Shell : public KParts::MainWindow
4: {
5: Q_OBJECT
6: public:
7: Shell();
8: virtual ~Shell();
9:
10: void openURL( const KURL & url );
11:
12: protected slots:
13: void slotFileOpen();
14:
15: private:
16: KParts::ReadOnlyPart *m_gvpart;

17: };

The mainwindow inherits KParts::MainWindow instead of KTMainWindow. Nothing else is required; the openURL() here is just so that main() can call openURL() on the window. The URL could be passed to the constructor instead.

The code for the mainwindow embedding the KGhostView part is part of the KParts examples, which can be found under kdelibs/kparts/tests/ghostview*, so Listing 13.13 only shows the relevant lines of ghostview.cpp.

====''Listing 13.13 Excerpt of ghostviewtest.cpp: Implementation of the Simple KParts Mainwindow''====

1: Shell::Shell()
2: {
3: setXMLFile( "ghostviewtest_shell.rc" );
4:
5: KAction * paOpen = new KAction( i18n( "&Open file" ), "fileopen", 0,
6: this, SLOT( slotFileOpen() ), actionCollection(), "file_open" );
7:
8: KAction * paQuit = new KAction( i18n( "&Quit" ), "exit", 0,
9: this, SLOT( close() ), actionCollection(), "file_quit" );
10:
11: // Try to find libkghostview
12: KLibFactory *factory = KLibLoader::self()->factory( "libkghostview" );
13: if (factory)
14: {
15: // Create the part
16: m_gvpart = (KParts::ReadOnlyPart *)factory->create( this, "kgvpart",
17: "KParts::ReadOnlyPart" );
18: // Set the main widget
19: setView( m_gvpart->widget() );
20: // Integrate its GUI
21: createGUI( m_gvpart );
22: }
23: else
24: kdFatal() << "No libkghostview found !" << endl;
25: }
26:
27: Shell::~Shell()
28: {
29: delete m_gvpart;
30: }
31:
32: void Shell::openURL( const KURL & url )
33: {
34: m_gvpart->openURL( url );

35: }

A mainwindow is created much like a part, with an XML file and actions. To find a part, it uses KLibLoader to get the KLibFactory for the library. A flexible application would use .desktop files for this and KIO's trader for selecting the user's preferred component, but for the sake of simplicity, open the library by its name here. After the factory has been created, the mainwindow makes it create a ReadOnlyPart, and because here you have only one part in the window, the part's widget is set as the main widget of the window with setView. Then a mainwindow needs to call createGUI() to make the framework create the GUI, merging the actions of the mainwindow with those of the active part. A mainwindow with no part will simply call createGUI(0L).

Using this mainwindow, for instance from main(), is as simple as

Shell *shell = new Shell;
shell->openURL( url );

shell->show();

Compile kdelibs/kparts/tests/ghostviewtest to test this simple example of how to embed a part.

==Embedding More Than One Part in the Same Window==

The previous example showed how to embed a part as the single widget of a window. KParts also makes it possible to embed more than one part in the same window, and it handles the activation of a part when the user clicks it (or uses Tab to give it the focus). This is the task of the PartManager.

To display more than one part in a window, the solution is usually to use a splitter, or even nested splitters, such as in Konqueror. KOffice has another way of embedding several parts - by using frames for the child parts - but it still uses PartManager.

Now modify the example to make it display, in addition to the PostScript document, the PostScript code for it. To display the text, the application uses the Notepad part in read-only mode. The two widgets will be hosted by a splitter.

Displaying raw PostScript is not very useful, but this example could, for instance, be turned into an application showing the LaTeX source and the PostScript result side by side.

ghostviewtest.h needs to be modified slightly to add the following private members:

KParts::ReadOnlyPart *m_notepadpart;
KParts::PartManager *m_manager;

QSplitter *m_splitter;

ghostviewtest.cpp needs to be more modified. To include the PartManager definition, use the following:

<nowiki>#include <kparts/partmanager.h>
</nowiki>

In the constructor, create the part manager and connect its main signal, activePartChanged, to your createGUI slot. This means you don't need to call createGUI directly; it is called every time the active part changes.

m_manager = new KParts::PartManager( this );
// When the manager says the active part changes,
// the builder updates (recreates) the GUI
connect( m_manager, SIGNAL( activePartChanged( KParts::Part * ) ),

this, SLOT( createGUI( KParts::Part * ) ) );

Then create the splitter and transform the setView statement into the following:

m_splitter = new QSplitter( this );

setView( m_splitter );

so that the main widget is now the splitter. Both parts need to be created with the splitter as a parent (instead of the window):

KLibFactory *factory = KLibLoader::self()->factory( "libkghostview" );
if (factory)
{
m_gvpart = (KParts::ReadOnlyPart *)factory->create( m_splitter,
"kgvpart", "KParts::ReadOnlyPart" );
}
else
kdFatal() << "No libkghostview found !" << endl;

factory = KLibLoader::self()->factory( "libnotepad" );
if (factory)
m_notepadpart = (KParts::ReadOnlyPart *)factory->create( m_splitter,
"knotepadpart", "KParts::ReadOnlyPart" );
else

kdFatal() << "No libnotepad found !" << endl;

After the parts are created, they should be added to the part manager. At the same time, you can specify which one should initially be active:

m_manager->addPart( m_gvpart, true ); // sets as the active part

m_manager->addPart( m_notepadpart, false );

Then the splitter can be set to a minimum size, as shown:

m_splitter->setMinimumSize( 400, 300 );

m_splitter->show();

Finally, add the following line to openURL() to open the same URL in both parts:

m_notepadpart->openURL( url );

As you can see, the main idea is that the mainwindow creates a main widget (here, the splitter), creates all parts inside it, and registers the part to a part manager. Try clicking one part and then the other; each time the active part changes, the GUI is updated (both menus and toolbars) to show the GUI of the active part.

Note also the change in the window caption. This is handled by the Part class, which receives the GUIActivateEvent from the mainwindow when the part is activated or deactivated. To set a different caption for a part, you need to emit setWindowCaption both in openFile() and in guiActivateEvent().

==Creating a KParts Plug-in==

A plug-in is the way to implement some functionality out of a part but still in a shared library, with actions defined by the plug-in to access this functionality. Those actions, whose layout is described in XML as usual, can be merged in a part's user interface or in a mainwindow's, depending on whether it applies to a part or to an application.

Several reasons exist for using plug-ins. One is saving memory, because the plug-in is not loaded until one of its actions is called, but the main reason is reusability - the same plug-in can apply to several parts or applications. For instance, a spell-checker plug-in can apply to all kinds of text editors, mail composers, word processors, and even presenters.

A plug-in can have a user interface, such as the dialog box for the spell checker, but not necessarily. Plug-ins can also act directly on the part or the application or anything else.

The XML for a spell-checker plug-in is shown below:

<!DOCTYPE kpartgui>
<kpartgui library="libspellcheck">
<MenuBar>
<Menu name="edit"><Text>&Edit</Text>
<Action name="spellcheck"/>
</Menu>
</MenuBar>
</kpartgui>

</kpartplugin>

Note the additional attribute in the main tag: library defines the name of the library to open to find the plug-in. This is because no .desktop file exists for plug-ins. Installing the preceding XML file in partplugins/, under share/apps/notepadpart, automatically inserts the plug-in's action in the NotepadPart user interface.

You know how the plug-in's library will be opened; now you need only to create a factory in the library, as usual, and let it create an instance of the plug-in. Writing the factory, which doesn't even need an instance in the simple case, and the init_libspellcheck() function will be left as an exercise to the reader.

To define a plug-in, simply inherit KParts::Plugin and add slots for its actions:

<nowiki>#include <kparts/plugin.h>

class PluginSpellCheck : public KParts::Plugin
{
Q_OBJECT
public:
PluginSpellCheck( QObject* parent = 0, const char* name = 0 );
virtual ~PluginSpellCheck() {}

public slots:
void slotSpellCheck();
</nowiki>

};

In the implementation, you have to create the plug-in actions; no setXMLFile is here because it has been found by the part already.

Because in this example you are not going to create a real spell checker - a libkspell exists for that - call the action "select current line" and implement that in the slot.

<nowiki>#include "plugin_spellcheck.h"
#include "notepad.h" // this plugin applies to a notepad part
#include <qmultilineedit.h>
#include <kaction.h>

PluginSpellCheck::PluginSpellCheck( QObject* parent, const char* name )
: Plugin( parent, name )
{
(void) new KAction( i18n( "&Select current line (plug-in)" ), 0, this,
SLOT(slotSpellCheck()), actionCollection(), "spellcheck" );
}

void PluginSpellCheck::slotSpellCheck()
{
// Check that the parent is a NotepadPart
if ( !parent()->inherits("NotepadPart") )
kdFatal() << "Spell-check plug-in for wrong part (not NotepadPart)" << endl;
else
{
NotepadPart * part = (NotepadPart *) parent();
QMultiLineEdit * widget = (QMultiLineEdit *) part->widget();
widget->selectAll(); //selects current line !
}
</nowiki>

}

Note that to access the part's widget, the plug-in has to assume - and check - that it has been installed for a NotepadPart. This means that you should not install it under another part's directory. But selecting the current line in an image viewer wouldn't mean much anyway.

A more flexible plug-in would instead check and cast the parent to ReadWritePart and then check the type of its widget to be QMultiLineEdit.

==Summary==

After the presentation of component technology and how to lay out actions using XML, you have seen most of what KParts can do: three types of parts, part mainwindows, part manager, plug-ins, as well as how dynamic loading works - library factories and library loader.

You can do other interesting things with parts. Having a part embed itself in Konqueror is very simple; it's just a matter of providing a .desktop file for it, stating that it is a service that implements some servicetypes, which are the mimetypes that the part allows to view, plus the servicetype KParts::ReadOnlyPart. That's it. Konqueror will use the part to view the files of those mimetypes if no other service is set as more preferred in Configure File Types.

To provide better integration with Konqueror, you can also provide a KParts::BrowserExtension for the part, as defined in kparts/browserextension.h. This is what makes it possible to save and restore a view in Konqueror's history and for the part to use Konqueror's "standard actions." Examples of parts using the browser extension can be found in KView, KDVI, KGhostView, KWrite and all built-in Konqueror views.

Development/Architecture/KDE3/Imaging and Animation

2007-01-12T21:10:31Z

CuCullin:

{{improve}}

==KDE Image I/O library kimgio==

(kdelibs/kimgio)

===Reading and writing images===

This library allows applications that use the Qt library to read and write images in extra formats. Current formats include:

{| border="4" bgcolor="#F0F0FF"
! format
! read
! write
|-
| JPEG
| X
| if QImgio/libjpeg is installed
|-
| JPEG 2000
|
if [http://www.ece.uvic.ca/~mdadams/jasper/ JasPer] is installed
|-
| XV
| X
| X
|-
| EPS
| X
| X
|-
| NETPBM
| incomplete
|-
| TIFF
| X
|-
| KRL
| X
|-
| PNG (Qt)
| X
| X
|-
| BMP (Qt)
| X
| X
|-
| XBM (Qt)
| X
| X
|-
| PNM (several variants) (Qt)
| X
| X
|-
| PBM (several variants) (Qt)
| X
| X
|-
| GIF<sup><nowiki>*</nowiki></sup> (87 & 89a) (Qt)
| X
| X
|}

* Due to patent reasons, GIF support isn't compiled in Qt by default. You need to enable it with <tt>./configure -gif</tt> when compiling Qt.

'''Note''' that this is only legal if you've got a license from Unisys or don't live in a country where Unisys holds a patent on the LZW compression. Countries in that Unisys holds a patent include Canada, Japan, the USA, France, Germany, Italy and the UK. There is more information about that topic on the [http://www.unisys.com/unisys/lzw/ Unisys web site].

To use these formats, you must

# link the application with the libkimgio library
# Include the <nowiki>#include <kimgio.h></nowiki> header file.
# call kimgioRegister() once, somewhere in your code before you load an image.

===Writing handlers===

Please read the documentation for the [http://doc.trolltech.com/qimageio.html QImageIO] class in the Qt documentation.

# When writing handlers, there is a function naming convention; suppose, for example, we were writing PNG read and write handlers, we would name them
<code>
void kimgio_png_read ( QImageIO * );
void kimgio_png_write( QImageIO * );
i.e.

kimgio_<format>_<read/write>
</code>
This should reduce the chance of identifier clashes with other code.
# If you only have either a reader or the writer for a particular format, don't use NULL in QImageIO::defineIOHandler. Instead, write a stub function for the unimplemented handler which displays a message on standard output. This prevents kimgio-using programs dumping core when attempting to call the unimplemented handler.

==QImage==

Qt's QImage class provides a hardware independent image representation class for the programmer. It can load and save files and allows - contrary to a QPixmap - direct access to the image data. This is useful for direct pixel based image manipulation.

The QImage class has already some useful builtin functions like color depth conversion, smooth scaling, mirroring an image, painting text strings into it and also some other stuff. Be sure to read the [http://doc.trolltech.com/qimage.html QImage documentation] for more details.

There are '''slow''' functions to convert between a QPixmap and QImage. They should be avoided especially for large images if possible. They're slow because the image data might need to be converted in depth and byte order and need to be transferred over a possibly slow network connection to the X server.

==QMovie==

Qt's QMovie class provides incrementally loading an image or an image animation, signalling as it progresses.

A QMovie provides a QPixmap as the framePixmap(), and connections can be made via connectResize() and connectUpdate() to receive notification of size and pixmap changes. All decoding is driven by the normal event processing mechanisms, so make sure that you regularly return to the X11 event loop to make the animation not look ugly. The simplest way to display a QMovie, is to use a QLabel and QLabel::setMovie().

The movie begins playing as soon as the QMovie is created (actually, once control returns to the event loop). When the last frame in the movie has been played, it may loop back to the start if such looping is defined in the input source.

QMovie objects are explicitly shared. This means that a QMovie copied from another QMovie will be displaying the same frame at all times. If one shared movie pauses, all pause. To make independent movies, they must be constructed separately.

The set of data formats supported by QMovie is determined by the decoder factories which have been installed, and the format of the input is determined as the input is decoded.

QMovie's animations can be loaded from animated GIF files only if the gif support has been compiled in Qt. See the section about Kimgio above for more information.

QMovie doesn't yet support the MNG format, that is the animated "variant" of PNG. However, Troll Tech has implemented a very nice and far superiour add-on to PNG as an replacement, which is unfortunately not yet standardized. However, they're working on adding it to the PNG standard and we all hope that they will succeed.

The animated, well compressed PNG animation is supported by the yet experimental [http://doc.trolltech.com/qpngimagepacker.html QPNGImagePacker] class. The resulting PNG files are far better compressed than the animated GIF equivalents, because in every frames there is only the "difference" to the previous frame is stored. This is done by using transparency in the parts of the frame that hasn't changed.

It is currently only recommended to use the non-standardized PNG animations if you fully control the creation and loading of these images, i.e. the user doesn't need to manipulate the images with other programs for obvious reasons.

'''Note''' that currently the animated PNG files are only supported if Qt was linked statically with it's own distributed libpng. This is done by default. It will not work with the standard libpng that may be part of your system, as it uses a non-standardized extension.

==KPixmap==

(kdelibs/kdecore)

KPixmap inherits QPixmap, so it can be used as a compatible drop-in replacement for QPixmap. It has become a little bit obsolete in my opinion, but it still provides some nice features over [http://doc.trolltech.com/qpixmap.html QPixmap].

KPixmap provides an easier and probably a little bit faster dithering management and conversion code. It has two new color modes, WebColor and LowColor, applicable to 8bpp displays.

In WebColor mode all images are dithered to the Netscape palette, even when they have their own color table. WebColor is the default mode for KPixmap so that standard applications can share the Netscape palette across the desktop.

In LowColor mode images are checked to see if their color table matches the KDE icon palette. If the color tables do not match, the images are dithered to a minimal 3x3x3 color cube. LowColor mode can be used to load icons, background images etc. so that components of the desktop which are always present use no more than 40 colors.

It can also check if the color table of an image matches the Icon (KPixmap) palette or not. An image with one color not found in the Icon palette is considered to make a match, since this extra color may be a transparent background.

==KSharedPixmap==

(kdelibs/kdecore)

KSharedPixmap is a very cool new class that is now used in KDE's core applications. It enables sharing of pixmaps between different programs. This is currently used to share the pixmap that is set by kdesktop, the desktop management and wallpaper painting program of KDE, between kdesktop and konsole which might use it to implement the pseudo transparency feature.

A shared pixmap is a pixmap that resides only once in the X server. Every shared pixmap is referenced by an ID string, which has to be globally unique (unique among all X clients).

You make a pixmap accessible to other X client by publishing it, using publish().

Normally, if an X client exits, all its resources (including pixmaps) are deleted. This might give undesireable effects when other clients are using that pixmap. If you want to keep the pixmaps around, use setKeepResources(). This will keep _all_ this client's X recources in the server until it resets so don't use without thought.

KSharedPixmap inherits of course KPixmap, so it can be used wherever a KPixmap or a QPixmap can be used.

==KPixmapEffects==

(kdelibs/kdeui)

Did you ever see breathtaking gradient effects i.e. in popup menues of other window managers? Now you don't need to miss them any longer with KDE! KDE developers have implemented a wide variety of QPixmap based effects. As they're based on QPixmaps, they're normally hardware-accelerated by your graphics card and therefore bleeding fast.

KPixmapEffects supports a wide variety of gradient effects including

* VerticalGradient
* HorizontalGradient
* DiagonalGradient
* CrossDiagonalGradient
* PyramidGradient
* RectangleGradient
* PipeCrossGradient
* EllipticGradient

both in a "balanced" and in a "unbalanced" variant. As an image helps more than thousand words, you'll see some samples of them here:

{| border="4" bgcolor="#F0F0FF"
! Balanced Gradients
|-
|
[[Image:balancedgradient.png|balanced gradient picture]]
|}

{| border="4" bgcolor="#F0F0FF"
! Unbalanced Gradients
|-
|
[[Image:unbalancedgradient.png|unbalanced gradient picture]]
|}

Additional effects include changing the intensity of pixmaps, providing blend effects, creating pattered "images", or "flattening" as well as fading. Be sure you don't miss them!

Development/Architecture/KDE3/Imaging and Animation

2007-01-12T21:09:29Z

CuCullin: /* Writing handlers */

==KDE Image I/O library kimgio==

(kdelibs/kimgio)

===Reading and writing images===

This library allows applications that use the Qt library to read and write images in extra formats. Current formats include:

{| border="4" bgcolor="#F0F0FF"
! format
! read
! write
|-
| JPEG
| X
| if QImgio/libjpeg is installed
|-
| JPEG 2000
|
if [http://www.ece.uvic.ca/~mdadams/jasper/ JasPer] is installed
|-
| XV
| X
| X
|-
| EPS
| X
| X
|-
| NETPBM
| incomplete
|-
| TIFF
| X
|-
| KRL
| X
|-
| PNG (Qt)
| X
| X
|-
| BMP (Qt)
| X
| X
|-
| XBM (Qt)
| X
| X
|-
| PNM (several variants) (Qt)
| X
| X
|-
| PBM (several variants) (Qt)
| X
| X
|-
| GIF<sup><nowiki>*</nowiki></sup> (87 & 89a) (Qt)
| X
| X
|}

* Due to patent reasons, GIF support isn't compiled in Qt by default. You need to enable it with <tt>./configure -gif</tt> when compiling Qt.

'''Note''' that this is only legal if you've got a license from Unisys or don't live in a country where Unisys holds a patent on the LZW compression. Countries in that Unisys holds a patent include Canada, Japan, the USA, France, Germany, Italy and the UK. There is more information about that topic on the [http://www.unisys.com/unisys/lzw/ Unisys web site].

To use these formats, you must

# link the application with the libkimgio library
# Include the <nowiki>#include <kimgio.h></nowiki> header file.
# call kimgioRegister() once, somewhere in your code before you load an image.

===Writing handlers===

Please read the documentation for the [http://doc.trolltech.com/qimageio.html QImageIO] class in the Qt documentation.

# When writing handlers, there is a function naming convention; suppose, for example, we were writing PNG read and write handlers, we would name them
<code>
void kimgio_png_read ( QImageIO * );
void kimgio_png_write( QImageIO * );
i.e.

kimgio_<format>_<read/write>
</code>
This should reduce the chance of identifier clashes with other code.
# If you only have either a reader or the writer for a particular format, don't use NULL in QImageIO::defineIOHandler. Instead, write a stub function for the unimplemented handler which displays a message on standard output. This prevents kimgio-using programs dumping core when attempting to call the unimplemented handler.

==QImage==

Qt's QImage class provides a hardware independent image representation class for the programmer. It can load and save files and allows - contrary to a QPixmap - direct access to the image data. This is useful for direct pixel based image manipulation.

The QImage class has already some useful builtin functions like color depth conversion, smooth scaling, mirroring an image, painting text strings into it and also some other stuff. Be sure to read the [http://doc.trolltech.com/qimage.html QImage documentation] for more details.

There are '''slow''' functions to convert between a QPixmap and QImage. They should be avoided especially for large images if possible. They're slow because the image data might need to be converted in depth and byte order and need to be transferred over a possibly slow network connection to the X server.

==QMovie==

Qt's QMovie class provides incrementally loading an image or an image animation, signalling as it progresses.

A QMovie provides a QPixmap as the framePixmap(), and connections can be made via connectResize() and connectUpdate() to receive notification of size and pixmap changes. All decoding is driven by the normal event processing mechanisms, so make sure that you regularly return to the X11 event loop to make the animation not look ugly. The simplest way to display a QMovie, is to use a QLabel and QLabel::setMovie().

The movie begins playing as soon as the QMovie is created (actually, once control returns to the event loop). When the last frame in the movie has been played, it may loop back to the start if such looping is defined in the input source.

QMovie objects are explicitly shared. This means that a QMovie copied from another QMovie will be displaying the same frame at all times. If one shared movie pauses, all pause. To make independent movies, they must be constructed separately.

The set of data formats supported by QMovie is determined by the decoder factories which have been installed, and the format of the input is determined as the input is decoded.

QMovie's animations can be loaded from animated GIF files only if the gif support has been compiled in Qt. See the section about Kimgio above for more information.

QMovie doesn't yet support the MNG format, that is the animated "variant" of PNG. However, Troll Tech has implemented a very nice and far superiour add-on to PNG as an replacement, which is unfortunately not yet standardized. However, they're working on adding it to the PNG standard and we all hope that they will succeed.

The animated, well compressed PNG animation is supported by the yet experimental [http://doc.trolltech.com/qpngimagepacker.html QPNGImagePacker] class. The resulting PNG files are far better compressed than the animated GIF equivalents, because in every frames there is only the "difference" to the previous frame is stored. This is done by using transparency in the parts of the frame that hasn't changed.

It is currently only recommended to use the non-standardized PNG animations if you fully control the creation and loading of these images, i.e. the user doesn't need to manipulate the images with other programs for obvious reasons.

'''Note''' that currently the animated PNG files are only supported if Qt was linked statically with it's own distributed libpng. This is done by default. It will not work with the standard libpng that may be part of your system, as it uses a non-standardized extension.

==KPixmap==

(kdelibs/kdecore)

KPixmap inherits QPixmap, so it can be used as a compatible drop-in replacement for QPixmap. It has become a little bit obsolete in my opinion, but it still provides some nice features over [http://doc.trolltech.com/qpixmap.html QPixmap].

KPixmap provides an easier and probably a little bit faster dithering management and conversion code. It has two new color modes, WebColor and LowColor, applicable to 8bpp displays.

In WebColor mode all images are dithered to the Netscape palette, even when they have their own color table. WebColor is the default mode for KPixmap so that standard applications can share the Netscape palette across the desktop.

In LowColor mode images are checked to see if their color table matches the KDE icon palette. If the color tables do not match, the images are dithered to a minimal 3x3x3 color cube. LowColor mode can be used to load icons, background images etc. so that components of the desktop which are always present use no more than 40 colors.

It can also check if the color table of an image matches the Icon (KPixmap) palette or not. An image with one color not found in the Icon palette is considered to make a match, since this extra color may be a transparent background.

==KSharedPixmap==

(kdelibs/kdecore)

KSharedPixmap is a very cool new class that is now used in KDE's core applications. It enables sharing of pixmaps between different programs. This is currently used to share the pixmap that is set by kdesktop, the desktop management and wallpaper painting program of KDE, between kdesktop and konsole which might use it to implement the pseudo transparency feature.

A shared pixmap is a pixmap that resides only once in the X server. Every shared pixmap is referenced by an ID string, which has to be globally unique (unique among all X clients).

You make a pixmap accessible to other X client by publishing it, using publish().

Normally, if an X client exits, all its resources (including pixmaps) are deleted. This might give undesireable effects when other clients are using that pixmap. If you want to keep the pixmaps around, use setKeepResources(). This will keep _all_ this client's X recources in the server until it resets so don't use without thought.

KSharedPixmap inherits of course KPixmap, so it can be used wherever a KPixmap or a QPixmap can be used.

==KPixmapEffects==

(kdelibs/kdeui)

Did you ever see breathtaking gradient effects i.e. in popup menues of other window managers? Now you don't need to miss them any longer with KDE! KDE developers have implemented a wide variety of QPixmap based effects. As they're based on QPixmaps, they're normally hardware-accelerated by your graphics card and therefore bleeding fast.

KPixmapEffects supports a wide variety of gradient effects including

* VerticalGradient
* HorizontalGradient
* DiagonalGradient
* CrossDiagonalGradient
* PyramidGradient
* RectangleGradient
* PipeCrossGradient
* EllipticGradient

both in a "balanced" and in a "unbalanced" variant. As an image helps more than thousand words, you'll see some samples of them here:

{| border="4" bgcolor="#F0F0FF"
! Balanced Gradients
|-
|
[[Image:balancedgradient.png|balanced gradient picture]]
|}

{| border="4" bgcolor="#F0F0FF"
! Unbalanced Gradients
|-
|
[[Image:unbalancedgradient.png|unbalanced gradient picture]]
|}

Additional effects include changing the intensity of pixmaps, providing blend effects, creating pattered "images", or "flattening" as well as fading. Be sure you don't miss them!

Development/Architecture/KDE3/Imaging and Animation

2007-01-12T21:02:41Z

CuCullin: /* Writing handlers */

==KDE Image I/O library kimgio==

(kdelibs/kimgio)

===Reading and writing images===

This library allows applications that use the Qt library to read and write images in extra formats. Current formats include:

{| border="4" bgcolor="#F0F0FF"
! format
! read
! write
|-
| JPEG
| X
| if QImgio/libjpeg is installed
|-
| JPEG 2000
|
if [http://www.ece.uvic.ca/~mdadams/jasper/ JasPer] is installed
|-
| XV
| X
| X
|-
| EPS
| X
| X
|-
| NETPBM
| incomplete
|-
| TIFF
| X
|-
| KRL
| X
|-
| PNG (Qt)
| X
| X
|-
| BMP (Qt)
| X
| X
|-
| XBM (Qt)
| X
| X
|-
| PNM (several variants) (Qt)
| X
| X
|-
| PBM (several variants) (Qt)
| X
| X
|-
| GIF<sup><nowiki>*</nowiki></sup> (87 & 89a) (Qt)
| X
| X
|}

* Due to patent reasons, GIF support isn't compiled in Qt by default. You need to enable it with <tt>./configure -gif</tt> when compiling Qt.

'''Note''' that this is only legal if you've got a license from Unisys or don't live in a country where Unisys holds a patent on the LZW compression. Countries in that Unisys holds a patent include Canada, Japan, the USA, France, Germany, Italy and the UK. There is more information about that topic on the [http://www.unisys.com/unisys/lzw/ Unisys web site].

To use these formats, you must

# link the application with the libkimgio library
# Include the <nowiki>#include <kimgio.h></nowiki> header file.
# call kimgioRegister() once, somewhere in your code before you load an image.

===Writing handlers===

Please read the documentation for the [http://doc.trolltech.com/qimageio.html QImageIO] class in the Qt documentation.

# When writing handlers, there is a function naming convention; suppose, for example, we were writing PNG read and write handlers, we would name them

void kimgio_png_read ( QImageIO * );
void kimgio_png_write( QImageIO * );
i.e.

kimgio_<format>_<read/write>

This should reduce the chance of identifier clashes with other code.
# If you only have either a reader or the writer for a particular format, don't use NULL in QImageIO::defineIOHandler. Instead, write a stub function for the unimplemented handler which displays a message on standard output. This prevents kimgio-using programs dumping core when attempting to call the unimplemented handler.

==QImage==

Qt's QImage class provides a hardware independent image representation class for the programmer. It can load and save files and allows - contrary to a QPixmap - direct access to the image data. This is useful for direct pixel based image manipulation.

The QImage class has already some useful builtin functions like color depth conversion, smooth scaling, mirroring an image, painting text strings into it and also some other stuff. Be sure to read the [http://doc.trolltech.com/qimage.html QImage documentation] for more details.

There are '''slow''' functions to convert between a QPixmap and QImage. They should be avoided especially for large images if possible. They're slow because the image data might need to be converted in depth and byte order and need to be transferred over a possibly slow network connection to the X server.

==QMovie==

Qt's QMovie class provides incrementally loading an image or an image animation, signalling as it progresses.

A QMovie provides a QPixmap as the framePixmap(), and connections can be made via connectResize() and connectUpdate() to receive notification of size and pixmap changes. All decoding is driven by the normal event processing mechanisms, so make sure that you regularly return to the X11 event loop to make the animation not look ugly. The simplest way to display a QMovie, is to use a QLabel and QLabel::setMovie().

The movie begins playing as soon as the QMovie is created (actually, once control returns to the event loop). When the last frame in the movie has been played, it may loop back to the start if such looping is defined in the input source.

QMovie objects are explicitly shared. This means that a QMovie copied from another QMovie will be displaying the same frame at all times. If one shared movie pauses, all pause. To make independent movies, they must be constructed separately.

The set of data formats supported by QMovie is determined by the decoder factories which have been installed, and the format of the input is determined as the input is decoded.

QMovie's animations can be loaded from animated GIF files only if the gif support has been compiled in Qt. See the section about Kimgio above for more information.

QMovie doesn't yet support the MNG format, that is the animated "variant" of PNG. However, Troll Tech has implemented a very nice and far superiour add-on to PNG as an replacement, which is unfortunately not yet standardized. However, they're working on adding it to the PNG standard and we all hope that they will succeed.

The animated, well compressed PNG animation is supported by the yet experimental [http://doc.trolltech.com/qpngimagepacker.html QPNGImagePacker] class. The resulting PNG files are far better compressed than the animated GIF equivalents, because in every frames there is only the "difference" to the previous frame is stored. This is done by using transparency in the parts of the frame that hasn't changed.

It is currently only recommended to use the non-standardized PNG animations if you fully control the creation and loading of these images, i.e. the user doesn't need to manipulate the images with other programs for obvious reasons.

'''Note''' that currently the animated PNG files are only supported if Qt was linked statically with it's own distributed libpng. This is done by default. It will not work with the standard libpng that may be part of your system, as it uses a non-standardized extension.

==KPixmap==

(kdelibs/kdecore)

KPixmap inherits QPixmap, so it can be used as a compatible drop-in replacement for QPixmap. It has become a little bit obsolete in my opinion, but it still provides some nice features over [http://doc.trolltech.com/qpixmap.html QPixmap].

KPixmap provides an easier and probably a little bit faster dithering management and conversion code. It has two new color modes, WebColor and LowColor, applicable to 8bpp displays.

In WebColor mode all images are dithered to the Netscape palette, even when they have their own color table. WebColor is the default mode for KPixmap so that standard applications can share the Netscape palette across the desktop.

In LowColor mode images are checked to see if their color table matches the KDE icon palette. If the color tables do not match, the images are dithered to a minimal 3x3x3 color cube. LowColor mode can be used to load icons, background images etc. so that components of the desktop which are always present use no more than 40 colors.

It can also check if the color table of an image matches the Icon (KPixmap) palette or not. An image with one color not found in the Icon palette is considered to make a match, since this extra color may be a transparent background.

==KSharedPixmap==

(kdelibs/kdecore)

KSharedPixmap is a very cool new class that is now used in KDE's core applications. It enables sharing of pixmaps between different programs. This is currently used to share the pixmap that is set by kdesktop, the desktop management and wallpaper painting program of KDE, between kdesktop and konsole which might use it to implement the pseudo transparency feature.

A shared pixmap is a pixmap that resides only once in the X server. Every shared pixmap is referenced by an ID string, which has to be globally unique (unique among all X clients).

You make a pixmap accessible to other X client by publishing it, using publish().

Normally, if an X client exits, all its resources (including pixmaps) are deleted. This might give undesireable effects when other clients are using that pixmap. If you want to keep the pixmaps around, use setKeepResources(). This will keep _all_ this client's X recources in the server until it resets so don't use without thought.

KSharedPixmap inherits of course KPixmap, so it can be used wherever a KPixmap or a QPixmap can be used.

==KPixmapEffects==

(kdelibs/kdeui)

Did you ever see breathtaking gradient effects i.e. in popup menues of other window managers? Now you don't need to miss them any longer with KDE! KDE developers have implemented a wide variety of QPixmap based effects. As they're based on QPixmaps, they're normally hardware-accelerated by your graphics card and therefore bleeding fast.

KPixmapEffects supports a wide variety of gradient effects including

* VerticalGradient
* HorizontalGradient
* DiagonalGradient
* CrossDiagonalGradient
* PyramidGradient
* RectangleGradient
* PipeCrossGradient
* EllipticGradient

both in a "balanced" and in a "unbalanced" variant. As an image helps more than thousand words, you'll see some samples of them here:

{| border="4" bgcolor="#F0F0FF"
! Balanced Gradients
|-
|
[[Image:balancedgradient.png|balanced gradient picture]]
|}

{| border="4" bgcolor="#F0F0FF"
! Unbalanced Gradients
|-
|
[[Image:unbalancedgradient.png|unbalanced gradient picture]]
|}

Additional effects include changing the intensity of pixmaps, providing blend effects, creating pattered "images", or "flattening" as well as fading. Be sure you don't miss them!

Development/Architecture/KDE3/Imaging and Animation

2007-01-12T21:01:21Z

CuCullin:

==KDE Image I/O library kimgio==

(kdelibs/kimgio)

===Reading and writing images===

This library allows applications that use the Qt library to read and write images in extra formats. Current formats include:

{| border="4" bgcolor="#F0F0FF"
! format
! read
! write
|-
| JPEG
| X
| if QImgio/libjpeg is installed
|-
| JPEG 2000
|
if [http://www.ece.uvic.ca/~mdadams/jasper/ JasPer] is installed
|-
| XV
| X
| X
|-
| EPS
| X
| X
|-
| NETPBM
| incomplete
|-
| TIFF
| X
|-
| KRL
| X
|-
| PNG (Qt)
| X
| X
|-
| BMP (Qt)
| X
| X
|-
| XBM (Qt)
| X
| X
|-
| PNM (several variants) (Qt)
| X
| X
|-
| PBM (several variants) (Qt)
| X
| X
|-
| GIF<sup><nowiki>*</nowiki></sup> (87 & 89a) (Qt)
| X
| X
|}

* Due to patent reasons, GIF support isn't compiled in Qt by default. You need to enable it with <tt>./configure -gif</tt> when compiling Qt.

'''Note''' that this is only legal if you've got a license from Unisys or don't live in a country where Unisys holds a patent on the LZW compression. Countries in that Unisys holds a patent include Canada, Japan, the USA, France, Germany, Italy and the UK. There is more information about that topic on the [http://www.unisys.com/unisys/lzw/ Unisys web site].

To use these formats, you must

# link the application with the libkimgio library
# Include the <nowiki>#include <kimgio.h></nowiki> header file.
# call kimgioRegister() once, somewhere in your code before you load an image.

===Writing handlers===

Please read the documentation for the [http://doc.trolltech.com/qimageio.html QImageIO] class in the Qt documentation.

# When writing handlers, there is a function naming convention; suppose, for example, we were writing PNG read and write handlers, we would name them

void kimgio_png_read ( QImageIO * );
void kimgio_png_write( QImageIO * );
i.e.

kimgio_<format>_<read/write>

This should reduce the chance of identifier clashes with other code.
# If you only have either a reader or the writer for a particular format, don't use NULL in QImageIO::defineIOHandler. Instead, write a stub function for the unimplemented handler which displays a message on standard output. This prevents kimgio-using programs dumping core when attempting to call the unimplemented handler.

[mailto:taj@kde.org Sirtaj Singh Kang].

==QImage==

Qt's QImage class provides a hardware independent image representation class for the programmer. It can load and save files and allows - contrary to a QPixmap - direct access to the image data. This is useful for direct pixel based image manipulation.

The QImage class has already some useful builtin functions like color depth conversion, smooth scaling, mirroring an image, painting text strings into it and also some other stuff. Be sure to read the [http://doc.trolltech.com/qimage.html QImage documentation] for more details.

There are '''slow''' functions to convert between a QPixmap and QImage. They should be avoided especially for large images if possible. They're slow because the image data might need to be converted in depth and byte order and need to be transferred over a possibly slow network connection to the X server.

==QMovie==

Qt's QMovie class provides incrementally loading an image or an image animation, signalling as it progresses.

A QMovie provides a QPixmap as the framePixmap(), and connections can be made via connectResize() and connectUpdate() to receive notification of size and pixmap changes. All decoding is driven by the normal event processing mechanisms, so make sure that you regularly return to the X11 event loop to make the animation not look ugly. The simplest way to display a QMovie, is to use a QLabel and QLabel::setMovie().

The movie begins playing as soon as the QMovie is created (actually, once control returns to the event loop). When the last frame in the movie has been played, it may loop back to the start if such looping is defined in the input source.

QMovie objects are explicitly shared. This means that a QMovie copied from another QMovie will be displaying the same frame at all times. If one shared movie pauses, all pause. To make independent movies, they must be constructed separately.

The set of data formats supported by QMovie is determined by the decoder factories which have been installed, and the format of the input is determined as the input is decoded.

QMovie's animations can be loaded from animated GIF files only if the gif support has been compiled in Qt. See the section about Kimgio above for more information.

QMovie doesn't yet support the MNG format, that is the animated "variant" of PNG. However, Troll Tech has implemented a very nice and far superiour add-on to PNG as an replacement, which is unfortunately not yet standardized. However, they're working on adding it to the PNG standard and we all hope that they will succeed.

The animated, well compressed PNG animation is supported by the yet experimental [http://doc.trolltech.com/qpngimagepacker.html QPNGImagePacker] class. The resulting PNG files are far better compressed than the animated GIF equivalents, because in every frames there is only the "difference" to the previous frame is stored. This is done by using transparency in the parts of the frame that hasn't changed.

It is currently only recommended to use the non-standardized PNG animations if you fully control the creation and loading of these images, i.e. the user doesn't need to manipulate the images with other programs for obvious reasons.

'''Note''' that currently the animated PNG files are only supported if Qt was linked statically with it's own distributed libpng. This is done by default. It will not work with the standard libpng that may be part of your system, as it uses a non-standardized extension.

==KPixmap==

(kdelibs/kdecore)

KPixmap inherits QPixmap, so it can be used as a compatible drop-in replacement for QPixmap. It has become a little bit obsolete in my opinion, but it still provides some nice features over [http://doc.trolltech.com/qpixmap.html QPixmap].

KPixmap provides an easier and probably a little bit faster dithering management and conversion code. It has two new color modes, WebColor and LowColor, applicable to 8bpp displays.

In WebColor mode all images are dithered to the Netscape palette, even when they have their own color table. WebColor is the default mode for KPixmap so that standard applications can share the Netscape palette across the desktop.

In LowColor mode images are checked to see if their color table matches the KDE icon palette. If the color tables do not match, the images are dithered to a minimal 3x3x3 color cube. LowColor mode can be used to load icons, background images etc. so that components of the desktop which are always present use no more than 40 colors.

It can also check if the color table of an image matches the Icon (KPixmap) palette or not. An image with one color not found in the Icon palette is considered to make a match, since this extra color may be a transparent background.

==KSharedPixmap==

(kdelibs/kdecore)

KSharedPixmap is a very cool new class that is now used in KDE's core applications. It enables sharing of pixmaps between different programs. This is currently used to share the pixmap that is set by kdesktop, the desktop management and wallpaper painting program of KDE, between kdesktop and konsole which might use it to implement the pseudo transparency feature.

A shared pixmap is a pixmap that resides only once in the X server. Every shared pixmap is referenced by an ID string, which has to be globally unique (unique among all X clients).

You make a pixmap accessible to other X client by publishing it, using publish().

Normally, if an X client exits, all its resources (including pixmaps) are deleted. This might give undesireable effects when other clients are using that pixmap. If you want to keep the pixmaps around, use setKeepResources(). This will keep _all_ this client's X recources in the server until it resets so don't use without thought.

KSharedPixmap inherits of course KPixmap, so it can be used wherever a KPixmap or a QPixmap can be used.

==KPixmapEffects==

(kdelibs/kdeui)

Did you ever see breathtaking gradient effects i.e. in popup menues of other window managers? Now you don't need to miss them any longer with KDE! KDE developers have implemented a wide variety of QPixmap based effects. As they're based on QPixmaps, they're normally hardware-accelerated by your graphics card and therefore bleeding fast.

KPixmapEffects supports a wide variety of gradient effects including

* VerticalGradient
* HorizontalGradient
* DiagonalGradient
* CrossDiagonalGradient
* PyramidGradient
* RectangleGradient
* PipeCrossGradient
* EllipticGradient

both in a "balanced" and in a "unbalanced" variant. As an image helps more than thousand words, you'll see some samples of them here:

{| border="4" bgcolor="#F0F0FF"
! Balanced Gradients
|-
|
[[Image:balancedgradient.png|balanced gradient picture]]
|}

{| border="4" bgcolor="#F0F0FF"
! Unbalanced Gradients
|-
|
[[Image:unbalancedgradient.png|unbalanced gradient picture]]
|}

Additional effects include changing the intensity of pixmaps, providing blend effects, creating pattered "images", or "flattening" as well as fading. Be sure you don't miss them!

Development/Architecture

2007-01-12T20:42:57Z

CuCullin: /* Design Documents */

The following pages contain documentation about KDE's design and architecture in detail. They do not replace other documentation like API Documentation, tutorials, howtos and standards, see the [[Development|development portal]] for further information.

For a better understanding it might help to be familiar with Trolltech's™ excellent [http://doc.trolltech.com/3.3/index.html Qt 3.3] or [http://doc.trolltech.com/4.2/index.html Qt 4.2] documentation and their [http://www.trolltech.com/developer/ Developer Pages].

== Design Documents ==
; [[/KDE 4 Architecture|KDE 4 Architecture Overview]]
: An overview of the KDE 4 architecture, including discussions of common techniques, library classes, and general development issues. This is for ''KDE 4.0''.

; [[/KDE 3 Architecture|KDE 3 Architecture Overview]] [http://developer.kde.org/documentation/library/kdeqt/kde3arch/ (Original)]
: An overview of the KDE 3 architecture, including discussions of common techniques, library classes, and general development issues. This is for ''KDE 3.0''.

; [[/KDE 2 Architecture|KDE 2 Architecture Overview]] [http://developer.kde.org/documentation/library/kdeqt/kde2arch/ (Original)]
: An overview of the KDE 2 architecture, similar to the above. This is for ''KDE 2.2''.

; [[/DCOP|DCOP]]
: Design documents from 1999-2000.

; [[Development/Architecture/Binary Compatibility Issues With C++|Binary Compatibility Issues With C++]] ([http://developer.kde.org/documentation/other/binarycompatibility.html Original])
: A quick overview of issues with binary compatibility with C++. Keep this in mind while altering the API of kdelibs.

; [http://developer.kde.org/documentation/design/kde/simplinux-presentation/html-800x600/index.htm The design of the K Desktop Environment]
: This is a presentation given at the SIMPLINUX conference in Portugal. It discusses the design of KDE and how it has changed through the different releases. You can browse the [http://developer.kde.org/documentation/design/kde/simplinux-presentation/html-800x600/index.htm slides online], or [http://developer.kde.org/documentation/design/kde/simplinux-presentation/html-800x600.tar.gz download] them in one go. There is also a [http://developer.kde.org/documentation/design/kde/simplinux-presentation/html-800x600/tsld001.htm text only version] (only a couple of the slides are really pictures, the rest are fine as text). You can also see some photos of the presentation. (Design documents from 1999)

Policies/Binary Compatibility Issues With C++

2007-01-12T20:38:41Z

CuCullin:

== Definition ==

A library is '''binary compatible''', if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn't require any further modifications, the library is '''source compatible'''.

Binary compatibility saves a lot of trouble. It makes it much easier to distribute software for a certain platform. Without ensuring binary compatibility between releases, people will be forced to provide statically linked binaries. Static binaries are bad because they
* waste resources (especially memory)
* don't allow the program to benefit from bugfixes or extensions in the libraries

In the KDE project, we will provide binary compatibility within the life-span of a major release.

== The Do's and Don'ts ==

You can...

* add new non-virtual functions including signals and slots.
* add a new enum to a class.
* append new enumerators to an existing enum.
* reimplement virtual functions defined in one of the base classes '''if''' it is safe that programs linked with the prior version of the library call the implementation in the base class rather than the new one. ''This is tricky and might be dangerous. Think twice before doing it. Alternatively see below for a workaround.''
* change an inline function or make an inline function non-inline '''if''' it is safe that programs linked with the prior version of the library call the old implementation. ''This is tricky and might be dangerous. Think twice before doing it.'' Because of this, classes that are supposed to stay binary compatible should '''always''' have non-inline destructor, even if it's empty, otherwise the compiler will automatically generate an empty inlined one.
* Remove private non-virtual functions '''if''' they are not called
by any inline functions.
* change the default arguments of a method. It requires recompilation to use the actual new default argument values, though.
* add new '''static''' data members.
* add new classes.

You cannot...
* add new virtual functions as this will change the layout of the virtual table and thus break subclasses. ''See below for some workarounds or ask on mailing lists.''
* change the order of virtual functions in the class declaration. This will just as well change the layout of the virtual table.
* change the signature of a function. This includes:
** changing any of the types of the arguments in the parameter list (instead, add a new method)
** changing the return type
** extending a function with another parameter, even if this parameter has a default argument
Suggestion: when adding new functions with the same name and different/extended argument lists, you may want to add a short note that the two functions shall be merged with a default argument in later versions of the library:

<code>
void functionname( int a );
void functionname( int a, int b ); //BCI: merge with int b = 0
</code>

* change the access rights to some functions or data members, for example from
<tt>private</tt> to <tt>public</tt>. With some compilers, this information may be part of the signature. If you need to make a private function protected or even public, you have to add a new function that calls the private one.
* add new data members to a class or change order of data members in a class (doesn't apply to static ones).
* change the class hierachy apart from adding new classes.

You should...

In order to make a class to extend in the future you should follow these rules:
* add d-pointer. ''See below''.
* add non-inline virtual destructor even if the body is empty.
* reimplement <tt>event</tt> in widget classes, even if the body for the function is empty.
* make all constructors non-inline.
* write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value (e.g. classes inherited from QObject can't be)

== Techniques for Library Programmers ==

The biggest problem when writing libraries is, that one cannot safely add data members since this would change the size and layout of every class, struct, or array containing objects of the type, including subclasses.

=== Bitflags ===
One exception are bitflags. If you use bitflags for enums or bools, you can safely round up to at least the next byte minus 1. A class with members

<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
</code>
<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
uint m4 : 2; // new member
</code>
without breaking binary compatibility. Please round up to a maxmimum of 7 bits (or 15 if the bitfield was already larger than 8). Using the very last bit may cause problems on some compilers.

=== Using a d-Pointer===
Bitflags and predefined reserved variables are nice, but far from being sufficient. This is where the d-pointer technique comes into play. The name "d-pointer" stems from Trolltech's Arnt Gulbrandsen, who first introduced the technique into Qt, making it one of the first C++ GUI libraries to maintain binary compatibility even between bigger release. The technique was quickly adapted as general programming pattern for the KDE libraries by everyone who saw it. It's a great trick to be able to add new private data members to a class without breaking binary compatibility.

'''Remark:''' The d-pointer pattern has been described many
times in computer science history under various names, e.g. as pimpl,
as handle/body or as cheshire cat. Google helps finding online papers
for any of these, just add C++ to the search terms.</small>

In your class definition for class Foo, define a forward declaration
<code>
class FooPrivate;
</code>
and the d-pointer in the private section:
<code>
private:
FooPrivate* d;
</code>
The FooPrivate class itself is purely defined in the clas implementation file (usually *.cpp ), for example:
<code>
class FooPrivate {
public:
FooPrivate()
: m1(0), m2(0)
{};
int m1;
int m2;
QString s;
};
</code>

All you have to do now is to create the private data in your constructors or your init function with
<code>
d = new FooPrivate;
</code>
and to delete it again in your destructor with
<code>
delete d;
</code>

You may not want all member variables to live in the private data object, though. For very often used members, it's faster to put them directly in the class, since inline functions cannot access the d-pointer data. Also note that all data covered by the d-pointer is obviously private. For public or protected access, provide both a set and a get function. Example
<code>
QString Foo::string() const
{
return d->s;
}

void setString( const QString& s )
{
d->s = s;
}
</code>

<h2>Trouble shooting</h2>

=== Adding new data members to classes without d-pointer ===

If you don't have free bitflags, reserved variables and no d-pointer either, but you absolutely have to add a new private member variable, there are still some possibilities left. If your class inherits QObject, you can for example place the additional data in a special child and find it by traversing over the list of children. You can access the list of children with QObject::children(). However, a fancier and usually faster approach is to use a hashtable to store a
mapping between your object and the extra data. For this purpose, Qt provides a pointer-based dictionary called QHash (or QPtrDict in Qt3).

The basic trick in your class implementation of class Foo is:
* Create a private data class FooPrivate.
* Create a static QHash<Foo *, FooPrivate>.
*Note that some compilers/linkers (almost all, unfortunately) do not manage to create static objects in shared libraries. They simply forget to call the constructor. Therefore you should use the <tt>Q_GLOBAL_STATIC</tt> macro to create and access the object:

<code>
// BCI: Add a real d-pointer
Q_GLOBAL_STATIC(QHash<Foo *,FooPrivate>, d_func);
static FooPrivate* d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
if ( ! ret ) {
ret = new FooPrivate;
d_func()->insert( foo, ret );
}
return ret;
}
static void delete_d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
delete ret;
d_func()->remove( foo );
}
</code>

* Now you can use the d-pointer in your class almost as simple as in the code before, just with a function call to d(this). For example:

<code>
d(this)->m1 = 5;
</code>

* Add a line to your destructor:
<code>
delete_d(this);
</code>
* Do not forget to add a BCI remark, so that the hack can be removed in the next version of the library.
* Do not forget to add a d-pointer to your next class.

=== Adding a reimplemented virtual function ===

As already explained, you can safely reimplement a virtual function defined in one of the base classes only if it is safe that the programs linked with the prior version call the implementation in the base class rather than the new one. This is because the compiler sometimes calls virtual functions directly if it can determine which one to call. For example, if you have
<code>
void C::foo()
{
B::foo();
}
</code>

then B::foo() is called directly. If class B inherits from class A which implements foo() and B itself doesn't reimplement it, then C::foo() will in fact call A::foo(). If a newer version of the library adds B::foo(), C::foo() will call it only after a recompilation.

Another more common example is:
<code>
B b; // B derives from A
b.foo();
</code>
then the call to foo() will not use the virtual table. That means that
if B::foo() didn't exist in the library but now does, code that was
compiled with the earlier version will still call A::foo().

If you can't guarantee things will continue to work without a recompilation, move functionality from A::foo() to a new protected function A::foo2() and use this code:
<code>
void A::foo()
{
if( B* b = dynamic_cast< B* >( this ))
b->B::foo(); // B:: is important
else
foo2();
}
void B::foo()
{
// added functionality
A::foo2(); // call base function with real functionality
}
</code>
All calls to A::foo() for objects of type B (or inherited) will result in calling B::foo(). The only case that will not work as expected are calls to A::foo() that explicitly specify A::foo(), but B::foo() calls A::foo2() instead and there should not be other places doing so.

=== Using a new class ===

A relatively simple method of "extending" a class can be writing a replacement class that will include also the new functionality (and that may inherit from the old class to reuse the code). This of course requires adapting and recompiling applications using the library, so it is not possible this way to fix or extend functionality of classes that are used by applications compiled against an older version of the library. However, especially with small and/or performance-critical classes it may be simpler to write them without making sure they'll be simple to extend in the future and if the need arises later write a new replacement class that will provide new features or better performance.

=== Adding new virtual functions to leaf classes ===
This technique is one of cases of using a new class that can help if there's a need to add new virtual functions to a class that should stay binary compatible and there is no class inheriting from it that should also stay binary compatible (i.e. all classes inheriting from it are in applications). In such case it's possible to add a new class inheriting from the original one that will add them. Applications using the new functionality will of course have to be modified to use the new class.
<code>
class A {
public:
virtual void foo();
};
class B : public A { // newly added class
public:
virtual void bar(); // newly added virtual function
};
void A::foo()
{
// here it's needed to call a new virtual function
if( B* this2 = dynamic_cast< B* >( this ))
this2->bar();
}
</code>
It is not possible to use this technique when there are other inherited classes that should also stay binary compatible because they'd have to inherit from the new class.

=== Using signals instead of virtual functions ===
Qt's signals and slots are invoked using a special virtual method created by the Q_OBJECT macro and it exists in every class inherited from QObject. Therefore adding new signals and slots doesn't affect binary compatibility and the signals/slots mechanism can be used to emulate virtual functions.

<code>
class A : public QObject {
Q_OBJECT
public:
A();
virtual void foo();
signals:
void bar( int* ); // added new "virtual" function
protected slots:
void barslot( int* ); // implementation of the virtual function in A
};

A::A()
{
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void A::foo()
{
int ret;
emit bar( &ret );
}

void A::barslot( int* ret )
{
*ret = 10;
}
</code>

Function bar() will act like a virtual function, barslot() implements the actual functionality of it. Since signals have void return value, data must be returned using arguments. As there will be only one slot connected to the signal returning data from the slot this way will work without problems. Note that with Qt4 for this to work the connection type will have to be Qt::DirectConnection.

If an inherited class will want to re-implement the functionality of bar() it will have to provide its own slot:
<code>
class B : public A {
Q_OBJECT
public:
B();
protected slots: // necessary to specify as a slot again
void barslot( int* ); // reimplemented functionality of bar()
};

B::B()
{
disconnect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void B::barslot( int* ret )
{
*ret = 20;
}
</code>

Now B::barslot() will act like virtual reimplementation of A::bar(). Note that it is necessary to specify barslot() again as a slot in B and that in the constructor it is necessary to first disconnect and then connect again, that will disconnect A::barslot() and connect B::barslot() instead.

Note: the same can be accomplished by implementing a virtual slot.

Policies/Binary Compatibility Issues With C++

2007-01-12T20:36:14Z

CuCullin:

== Definition ==

A library is '''binary compatible''', if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn't require any further modifications, the library is '''source compatible'''.

Binary compatibility saves a lot of trouble. It makes it much easier to distribute software for a certain platform. Without ensuring binary compatibility between releases, people will be forced to provide statically linked binaries. Static binaries are bad because they
* waste resources (especially memory)
* don't allow the program to benefit from bugfixes or extensions in the libraries

In the KDE project, we will provide binary compatibility within the life-span of a major release.

== The Do's and Don'ts ==

You can...

* add new non-virtual functions including signals and slots.
* add a new enum to a class.
* append new enumerators to an existing enum.
* reimplement virtual functions defined in one of the base classes '''if''' it is safe that programs linked with the prior version of the library call the implementation in the base class rather than the new one. ''This is tricky and might be dangerous. Think twice before doing it. Alternatively see below for a workaround.''
* change an inline function or make an inline function non-inline '''if''' it is safe that programs linked with the prior version of the library call the old implementation. ''This is tricky and might be dangerous. Think twice before doing it.'' Because of this, classes that are supposed to stay binary compatible should '''always''' have non-inline destructor, even if it's empty, otherwise the compiler will automatically generate an empty inlined one.
* Remove private non-virtual functions '''if''' they are not called
by any inline functions.
* change the default arguments of a method. It requires recompilation to use the actual new default argument values, though.
* add new '''static''' data members.
* add new classes.

You cannot...
* add new virtual functions as this will change the layout of the virtual table and thus break subclasses. ''See below for some workarounds or ask on mailing lists.''
* change the order of virtual functions in the class declaration. This will just as well change the layout of the virtual table.
* change the signature of a function. This includes:
** changing any of the types of the arguments in the parameter list (instead, add a new method)
** changing the return type
** extending a function with another parameter, even if this parameter has a default argument
Suggestion: when adding new functions with the same name and different/extended argument lists, you may want to add a short note that the two functions shall be merged with a default argument in later versions of the library:

<code>
void functionname( int a );
void functionname( int a, int b ); //BCI: merge with int b = 0
</code>

* change the access rights to some functions or data members, for example from
<tt>private</tt> to <tt>public</tt>. With some compilers, this information may be part of the signature. If you need to make a private function protected or even public, you have to add a new function that calls the private one.
* add new data members to a class or change order of data members in a class (doesn't apply to static ones).
* change the class hierachy apart from adding new classes.

You should...

In order to make a class to extend in the future you should follow these rules:
* add d-pointer. ''See below''.
* add non-inline virtual destructor even if the body is empty.
* reimplement <tt>event</tt> in widget classes, even if the body for the function is empty.
* make all constructors non-inline.
* write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value (e.g. classes inherited from QObject can't be)

== Techniques for Library Programmers ==

The biggest problem when writing libraries is, that one cannot safely add data members since this would change the size and layout of every class, struct, or array containing objects of the type, including subclasses.

=== Bitflags ===
One exception are bitflags. If you use bitflags for enums or bools, you can safely round up to at least the next byte minus 1. A class with members

<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
</code>
<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
uint m4 : 2; // new member
</code>
without breaking binary compatibility. Please round up to a maxmimum of 7 bits (or 15 if the bitfield was already larger than 8). Using the very last bit may cause problems on some compilers.

=== Using a d-Pointer===
Bitflags and predefined reserved variables are nice, but far from being sufficient. This is where the d-pointer technique comes into play. The name "d-pointer" stems from Trolltech's Arnt Gulbrandsen, who first introduced the technique into Qt, making it one of the first C++ GUI libraries to maintain binary compatibility even between bigger release. The technique was quickly adapted as general programming pattern for the KDE libraries by everyone who saw it. It's a great trick to be able to add new private data members to a class without breaking binary compatibility.

'''Remark:''' The d-pointer pattern has been described many
times in computer science history under various names, e.g. as pimpl,
as handle/body or as cheshire cat. Google helps finding online papers
for any of these, just add C++ to the search terms.</small>

In your class definition for class Foo, define a forward declaration
<code>
class FooPrivate;
</code>
and the d-pointer in the private section:
<code>
private:
FooPrivate* d;
</code>
The FooPrivate class itself is purely defined in the clas implementation file (usually *.cpp ), for example:
<code>
class FooPrivate {
public:
FooPrivate()
: m1(0), m2(0)
{};
int m1;
int m2;
QString s;
};
</code>

All you have to do now is to create the private data in your constructors or your init function with
<code>
d = new FooPrivate;
</code>
and to delete it again in your destructor with
<code>
delete d;
</code>

You may not want all member variables to live in the private data object, though. For very often used members, it's faster to put them directly in the class, since inline functions cannot access the d-pointer data. Also note that all data covered by the d-pointer is obviously private. For public or protected access, provide both a set and a get function. Example
<code>
QString Foo::string() const
{
return d->s;
}

void setString( const QString& s )
{
d->s = s;
}
</code>

<h2>Trouble shooting</h2>

=== Adding new data members to classes without d-pointer ===

If you don't have free bitflags, reserved variables and no d-pointer either, but you absolutely have to add a new private member variable, there are still some possibilities left. If your class inherits QObject, you can for example place the additional data in a special child and find it by traversing over the list of children. You can access the list of children with QObject::children(). However, a fancier and usually faster approach is to use a hashtable to store a
mapping between your object and the extra data. For this purpose, Qt provides a pointer-based dictionary called QHash (or QPtrDict in Qt3).

The basic trick in your class implementation of class Foo is:
* Create a private data class FooPrivate.
* Create a static QHash<Foo *, FooPrivate>.
*Note that some compilers/linkers (almost all, unfortunately) do not manage to create static objects in shared libraries. They simply forget to call the constructor. Therefore you should use the <tt>Q_GLOBAL_STATIC</tt> macro to create and access the object:

<code>
// BCI: Add a real d-pointer
Q_GLOBAL_STATIC(QHash<Foo *,FooPrivate>, d_func);
static FooPrivate* d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
if ( ! ret ) {
ret = new FooPrivate;
d_func()->insert( foo, ret );
}
return ret;
}
static void delete_d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
delete ret;
d_func()->remove( foo );
}
</code>

* Now you can use the d-pointer in your class almost as simple as in the code before, just with a function call to d(this). For example:

<code>
d(this)->m1 = 5;
</code>

* Add a line to your destructor:
<code>
delete_d(this);
</code>
* Do not forget to add a BCI remark, so that the hack can be removed in the next version of the library.
* Do not forget to add a d-pointer to your next class.

=== Adding a reimplemented virtual function ===

As already explained, you can safely reimplement a virtual function defined in one of the base classes only if it is safe that the programs linked with the prior version call the implementation in the base class rather than the new one. This is because the compiler sometimes calls virtual functions directly if it can determine which one to call. For example, if you have
<code>
void C::foo()
{
B::foo();
}
</code>

then B::foo() is called directly. If class B inherits from class A which implements foo() and B itself doesn't reimplement it, then C::foo() will in fact call A::foo(). If a newer version of the library adds B::foo(), C::foo() will call it only after a recompilation.

Another more common example is:
<code>
B b; // B derives from A
b.foo();
</code>
then the call to foo() will not use the virtual table. That means that
if B::foo() didn't exist in the library but now does, code that was
compiled with the earlier version will still call A::foo().

If you can't guarantee things will continue to work without a recompilation, move functionality from A::foo() to a new protected function A::foo2() and use this code:
<code>
void A::foo()
{
if( B* b = dynamic_cast< B* >( this ))
b->B::foo(); // B:: is important
else
foo2();
}
void B::foo()
{
// added functionality
A::foo2(); // call base function with real functionality
}
</code>
All calls to A::foo() for objects of type B (or inherited) will result in calling B::foo(). The only case that will not work as expected are calls to A::foo() that explicitly specify A::foo(), but B::foo() calls A::foo2() instead and there should not be other places doing so.

=== Using a new class ===

A relatively simple method of "extending" a class can be writing a replacement class that will include also the new functionality (and that may inherit from the old class to reuse the code). This of course requires adapting and recompiling applications using the library, so it is not possible this way to fix or extend functionality of classes that are used by applications compiled against an older version of the library. However, especially with small and/or performance-critical classes it may be simpler to write them without making sure they'll be simple to extend in the future and if the need arises later write a new replacement class that will provide new features or better performance.

=== Adding new virtual functions to leaf classes ===
This technique is one of cases of using a new class that can help if there's a need to add new virtual functions to a class that should stay binary compatible and there is no class inheriting from it that should also stay binary compatible (i.e. all classes inheriting from it are in applications). In such case it's possible to add a new class inheriting from the original one that will add them. Applications using the new functionality will of course have to be modified to use the new class.
<code>
class A {
public:
virtual void foo();
};
class B : public A { // newly added class
public:
virtual void bar(); // newly added virtual function
};
void A::foo()
{
// here it's needed to call a new virtual function
if( B* this2 = dynamic_cast< B* >( this ))
this2->bar();
}
</code>
It is not possible to use this technique when there are other inherited classes that should also stay binary compatible because they'd have to inherit from the new class.

<h3>Using signals instead of virtual functions</h3>
<p>
Qt's signals and slots are invoked using a special virtual method created by the Q_OBJECT macro
and it exists in every class inherited from QObject. Therefore adding new
signals and slots doesn't affect binary compatibility and the signals/slots mechanism can be
used to emulate virtual functions.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A : public QObject {
Q_OBJECT
public:
A();
virtual void foo();
signals:
void bar( int* ); // added new "virtual" function
protected slots:
void barslot( int* ); // implementation of the virtual function in A
};

A::A()
{
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void A::foo()
{
int ret;
emit bar( &ret );
}

void A::barslot( int* ret )
{
*ret = 10;
}
</pre></td></tr></table>
Function bar() will act like a virtual function, barslot() implements the actual functionality
of it. Since signals have void return value, data must be returned using arguments. As
there will be only one slot connected to the signal returning data from the slot this way will
work without problems. Note that with Qt4 for this to work the connection type will have to be
Qt::DirectConnection.</p>
<p>
If an inherited class will want to reimplement the functionality of bar() it will have to provide
its own slot:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class B : public A {
Q_OBJECT
public:
B();
protected slots: // necessary to specify as a slot again
void barslot( int* ); // reimplemented functionality of bar()
};

B::B()
{
disconnect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void B::barslot( int* ret )
{
*ret = 20;
}
</pre></td></tr></table>
Now B::barslot() will act like virtual reimplementation of A::bar(). Note that it is necessary
to specify barslot() again as a slot in B and that in the constructor it is necessary to first
disconnect and then connect again, that will disconnect A::barslot() and connect B::barslot()
instead.</p>

<p>Note: the same can be accomplished by implementing a virtual slot.</p>

<p align="right"> <small> <em>
Matthias Ettrich <a href="mailto:ettrich@kde.org">ettrich@kde.org</a><br>
Lubos Lunak <a href="mailto:l.lunak@kde.org">l.lunak@kde.org</a>
</em></small></p>

Policies/Binary Compatibility Issues With C++

2007-01-12T20:35:35Z

CuCullin:

== Definition ==

A library is '''binary compatible''', if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn't require any further modifications, the library is '''source compatible'''.

Binary compatibility saves a lot of trouble. It makes it much easier to distribute software for a certain platform. Without ensuring binary compatibility between releases, people will be forced to provide statically linked binaries. Static binaries are bad because they
* waste resources (especially memory)
* don't allow the program to benefit from bugfixes or extensions in the libraries

In the KDE project, we will provide binary compatibility within the life-span of a major release.

== The Do's and Don'ts ==

You can...

* add new non-virtual functions including signals and slots.
* add a new enum to a class.
* append new enumerators to an existing enum.
* reimplement virtual functions defined in one of the base classes '''if''' it is safe that programs linked with the prior version of the library call the implementation in the base class rather than the new one. ''This is tricky and might be dangerous. Think twice before doing it. Alternatively see below for a workaround.''
* change an inline function or make an inline function non-inline '''if''' it is safe that programs linked with the prior version of the library call the old implementation. ''This is tricky and might be dangerous. Think twice before doing it.'' Because of this, classes that are supposed to stay binary compatible should '''always''' have non-inline destructor, even if it's empty, otherwise the compiler will automatically generate an empty inlined one.
* Remove private non-virtual functions '''if''' they are not called
by any inline functions.
* change the default arguments of a method. It requires recompilation to use the actual new default argument values, though.
* add new '''static''' data members.
* add new classes.

You cannot...
* add new virtual functions as this will change the layout of the virtual table and thus break subclasses. ''See below for some workarounds or ask on mailing lists.''
* change the order of virtual functions in the class declaration. This will just as well change the layout of the virtual table.
* change the signature of a function. This includes:
** changing any of the types of the arguments in the parameter list (instead, add a new method)
** changing the return type
** extending a function with another parameter, even if this parameter has a default argument
Suggestion: when adding new functions with the same name and different/extended argument lists, you may want to add a short note that the two functions shall be merged with a default argument in later versions of the library:

<code>
void functionname( int a );
void functionname( int a, int b ); //BCI: merge with int b = 0
</code>

* change the access rights to some functions or data members, for example from
<tt>private</tt> to <tt>public</tt>. With some compilers, this information may be part of the signature. If you need to make a private function protected or even public, you have to add a new function that calls the private one.
* add new data members to a class or change order of data members in a class (doesn't apply to static ones).
* change the class hierachy apart from adding new classes.

You should...

In order to make a class to extend in the future you should follow these rules:
* add d-pointer. ''See below''.
* add non-inline virtual destructor even if the body is empty.
* reimplement <tt>event</tt> in widget classes, even if the body for the function is empty.
* make all constructors non-inline.
* write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value (e.g. classes inherited from QObject can't be)

== Techniques for Library Programmers ==

The biggest problem when writing libraries is, that one cannot safely add data members since this would change the size and layout of every class, struct, or array containing objects of the type, including subclasses.

=== Bitflags ===
One exception are bitflags. If you use bitflags for enums or bools, you can safely round up to at least the next byte minus 1. A class with members

<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
</code>
<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
uint m4 : 2; // new member
</code>
without breaking binary compatibility. Please round up to a maxmimum of 7 bits (or 15 if the bitfield was already larger than 8). Using the very last bit may cause problems on some compilers.

=== Using a d-Pointer===
Bitflags and predefined reserved variables are nice, but far from being sufficient. This is where the d-pointer technique comes into play. The name "d-pointer" stems from Trolltech's Arnt Gulbrandsen, who first introduced the technique into Qt, making it one of the first C++ GUI libraries to maintain binary compatibility even between bigger release. The technique was quickly adapted as general programming pattern for the KDE libraries by everyone who saw it. It's a great trick to be able to add new private data members to a class without breaking binary compatibility.

'''Remark:''' The d-pointer pattern has been described many
times in computer science history under various names, e.g. as pimpl,
as handle/body or as cheshire cat. Google helps finding online papers
for any of these, just add C++ to the search terms.</small>

In your class definition for class Foo, define a forward declaration
<code>
class FooPrivate;
</code>
and the d-pointer in the private section:
<code>
private:
FooPrivate* d;
</code>
The FooPrivate class itself is purely defined in the clas implementation file (usually *.cpp ), for example:
<code>
class FooPrivate {
public:
FooPrivate()
: m1(0), m2(0)
{};
int m1;
int m2;
QString s;
};
</code>

All you have to do now is to create the private data in your constructors or your init function with
<code>
d = new FooPrivate;
</code>
and to delete it again in your destructor with
<code>
delete d;
</code>

You may not want all member variables to live in the private data object, though. For very often used members, it's faster to put them directly in the class, since inline functions cannot access the d-pointer data. Also note that all data covered by the d-pointer is obviously private. For public or protected access, provide both a set and a get function. Example
<code>
QString Foo::string() const
{
return d->s;
}

void setString( const QString& s )
{
d->s = s;
}
</code>

<h2>Trouble shooting</h2>

=== Adding new data members to classes without d-pointer ===

If you don't have free bitflags, reserved variables and no d-pointer either, but you absolutely have to add a new private member variable, there are still some possibilities left. If your class inherits QObject, you can for example place the additional data in a special child and find it by traversing over the list of children. You can access the list of children with QObject::children(). However, a fancier and usually faster approach is to use a hashtable to store a
mapping between your object and the extra data. For this purpose, Qt provides a pointer-based dictionary called QHash (or QPtrDict in Qt3).

The basic trick in your class implementation of class Foo is:
* Create a private data class FooPrivate.
* Create a static QHash<Foo *, FooPrivate>.
*Note that some compilers/linkers (almost all, unfortunately) do not manage to create static objects in shared libraries. They simply forget to call the constructor. Therefore you should use the <tt>Q_GLOBAL_STATIC</tt> macro to create and access the object:

<code>
// BCI: Add a real d-pointer
Q_GLOBAL_STATIC(QHash<Foo *,FooPrivate>, d_func);
static FooPrivate* d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
if ( ! ret ) {
ret = new FooPrivate;
d_func()->insert( foo, ret );
}
return ret;
}
static void delete_d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
delete ret;
d_func()->remove( foo );
}
</code>

* Now you can use the d-pointer in your class almost as simple as in the code before, just with a function call to d(this). For example:

<code>
d(this)->m1 = 5;
</code>

* Add a line to your destructor:
<code>
delete_d(this);
</code>
* Do not forget to add a BCI remark, so that the hack can be removed in the next version of the library.
* Do not forget to add a d-pointer to your next class.

=== Adding a reimplemented virtual function ===

As already explained, you can safely reimplement a virtual function defined in one of the base classes only if it is safe that the programs linked with the prior version call the implementation in the base class rather than the new one. This is because the compiler sometimes calls virtual functions directly if it can determine which one to call. For example, if you have
<code>
void C::foo()
{
B::foo();
}
</code>

then B::foo() is called directly. If class B inherits from class A which implements foo() and B itself doesn't reimplement it, then C::foo() will in fact call A::foo(). If a newer version of the library adds B::foo(), C::foo() will call it only after a recompilation.

Another more common example is:
<code>
B b; // B derives from A
b.foo();
</code>
then the call to foo() will not use the virtual table. That means that
if B::foo() didn't exist in the library but now does, code that was
compiled with the earlier version will still call A::foo().

If you can't guarantee things will continue to work without a recompilation, move functionality from A::foo() to a new protected function A::foo2() and use this code:
<code>
void A::foo()
{
if( B* b = dynamic_cast< B* >( this ))
b->B::foo(); // B:: is important
else
foo2();
}
void B::foo()
{
// added functionality
A::foo2(); // call base function with real functionality
}
</code>
All calls to A::foo() for objects of type B (or inherited) will result in calling B::foo(). The only case that will not work as expected are calls to A::foo() that explicitly specify A::foo(), but B::foo() calls A::foo2() instead and there should not be other places doing so.

=== Using a new class ===

A relatively simple method of "extending" a class can be writing a replacement class that will include also the new functionality (and that may inherit from the old class to reuse the code). This of course requires adapting and recompiling applications using the library, so it is not possible this way to fix or extend functionality of classes that are used by applications compiled against an older version of the library. However, especially with small and/or performance-critical classes it may be simpler to write them without making sure they'll be simple to extend in the future and if the need arises later write a new replacement class that will provide new features or better performance.

<h3>Adding new virtual functions to leaf classes</h3>
<p>
This technique is one of cases of using a new class that can help if there's a need to add
new virtual functions to a class that should stay binary compatible and there is no class
inheriting from it that should also stay binary compatible (i.e. all classes inheriting from it are
in applications). In such case it's possible to add a new class inheriting from the original one
that will add them. Applications using the new functionality will of course have to be modified
to use the new class.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A {
public:
virtual void foo();
};
class B : public A { // newly added class
public:
virtual void bar(); // newly added virtual function
};
void A::foo()
{
// here it's needed to call a new virtual function
if( B* this2 = dynamic_cast< B* >( this ))
this2->bar();
}
</pre></td></tr></table>
It is not possible to use this technique when there are other inherited classes that should also
stay binary compatible because they'd have to inherit from the new class.</p>

<h3>Using signals instead of virtual functions</h3>
<p>
Qt's signals and slots are invoked using a special virtual method created by the Q_OBJECT macro
and it exists in every class inherited from QObject. Therefore adding new
signals and slots doesn't affect binary compatibility and the signals/slots mechanism can be
used to emulate virtual functions.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A : public QObject {
Q_OBJECT
public:
A();
virtual void foo();
signals:
void bar( int* ); // added new "virtual" function
protected slots:
void barslot( int* ); // implementation of the virtual function in A
};

A::A()
{
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void A::foo()
{
int ret;
emit bar( &ret );
}

void A::barslot( int* ret )
{
*ret = 10;
}
</pre></td></tr></table>
Function bar() will act like a virtual function, barslot() implements the actual functionality
of it. Since signals have void return value, data must be returned using arguments. As
there will be only one slot connected to the signal returning data from the slot this way will
work without problems. Note that with Qt4 for this to work the connection type will have to be
Qt::DirectConnection.</p>
<p>
If an inherited class will want to reimplement the functionality of bar() it will have to provide
its own slot:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class B : public A {
Q_OBJECT
public:
B();
protected slots: // necessary to specify as a slot again
void barslot( int* ); // reimplemented functionality of bar()
};

B::B()
{
disconnect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void B::barslot( int* ret )
{
*ret = 20;
}
</pre></td></tr></table>
Now B::barslot() will act like virtual reimplementation of A::bar(). Note that it is necessary
to specify barslot() again as a slot in B and that in the constructor it is necessary to first
disconnect and then connect again, that will disconnect A::barslot() and connect B::barslot()
instead.</p>

<p>Note: the same can be accomplished by implementing a virtual slot.</p>

<p align="right"> <small> <em>
Matthias Ettrich <a href="mailto:ettrich@kde.org">ettrich@kde.org</a><br>
Lubos Lunak <a href="mailto:l.lunak@kde.org">l.lunak@kde.org</a>
</em></small></p>

Policies/Binary Compatibility Issues With C++

2007-01-12T20:34:52Z

CuCullin:

== Definition ==

A library is '''binary compatible''', if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn't require any further modifications, the library is '''source compatible'''.

Binary compatibility saves a lot of trouble. It makes it much easier to distribute software for a certain platform. Without ensuring binary compatibility between releases, people will be forced to provide statically linked binaries. Static binaries are bad because they
* waste resources (especially memory)
* don't allow the program to benefit from bugfixes or extensions in the libraries

In the KDE project, we will provide binary compatibility within the life-span of a major release.

== The Do's and Don'ts ==

You can...

* add new non-virtual functions including signals and slots.
* add a new enum to a class.
* append new enumerators to an existing enum.
* reimplement virtual functions defined in one of the base classes '''if''' it is safe that programs linked with the prior version of the library call the implementation in the base class rather than the new one. ''This is tricky and might be dangerous. Think twice before doing it. Alternatively see below for a workaround.''
* change an inline function or make an inline function non-inline '''if''' it is safe that programs linked with the prior version of the library call the old implementation. ''This is tricky and might be dangerous. Think twice before doing it.'' Because of this, classes that are supposed to stay binary compatible should '''always''' have non-inline destructor, even if it's empty, otherwise the compiler will automatically generate an empty inlined one.
* Remove private non-virtual functions '''if''' they are not called
by any inline functions.
* change the default arguments of a method. It requires recompilation to use the actual new default argument values, though.
* add new '''static''' data members.
* add new classes.

You cannot...
* add new virtual functions as this will change the layout of the virtual table and thus break subclasses. ''See below for some workarounds or ask on mailing lists.''
* change the order of virtual functions in the class declaration. This will just as well change the layout of the virtual table.
* change the signature of a function. This includes:
** changing any of the types of the arguments in the parameter list (instead, add a new method)
** changing the return type
** extending a function with another parameter, even if this parameter has a default argument
Suggestion: when adding new functions with the same name and different/extended argument lists, you may want to add a short note that the two functions shall be merged with a default argument in later versions of the library:

<code>
void functionname( int a );
void functionname( int a, int b ); //BCI: merge with int b = 0
</code>

* change the access rights to some functions or data members, for example from
<tt>private</tt> to <tt>public</tt>. With some compilers, this information may be part of the signature. If you need to make a private function protected or even public, you have to add a new function that calls the private one.
* add new data members to a class or change order of data members in a class (doesn't apply to static ones).
* change the class hierachy apart from adding new classes.

You should...

In order to make a class to extend in the future you should follow these rules:
* add d-pointer. ''See below''.
* add non-inline virtual destructor even if the body is empty.
* reimplement <tt>event</tt> in widget classes, even if the body for the function is empty.
* make all constructors non-inline.
* write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value (e.g. classes inherited from QObject can't be)

== Techniques for Library Programmers ==

The biggest problem when writing libraries is, that one cannot safely add data members since this would change the size and layout of every class, struct, or array containing objects of the type, including subclasses.

=== Bitflags ===
One exception are bitflags. If you use bitflags for enums or bools, you can safely round up to at least the next byte minus 1. A class with members

<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
</code>
<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
uint m4 : 2; // new member
</code>
without breaking binary compatibility. Please round up to a maxmimum of 7 bits (or 15 if the bitfield was already larger than 8). Using the very last bit may cause problems on some compilers.

=== Using a d-Pointer===
Bitflags and predefined reserved variables are nice, but far from being sufficient. This is where the d-pointer technique comes into play. The name "d-pointer" stems from Trolltech's Arnt Gulbrandsen, who first introduced the technique into Qt, making it one of the first C++ GUI libraries to maintain binary compatibility even between bigger release. The technique was quickly adapted as general programming pattern for the KDE libraries by everyone who saw it. It's a great trick to be able to add new private data members to a class without breaking binary compatibility.

'''Remark:''' The d-pointer pattern has been described many
times in computer science history under various names, e.g. as pimpl,
as handle/body or as cheshire cat. Google helps finding online papers
for any of these, just add C++ to the search terms.</small>

In your class definition for class Foo, define a forward declaration
<code>
class FooPrivate;
</code>
and the d-pointer in the private section:
<code>
private:
FooPrivate* d;
</code>
The FooPrivate class itself is purely defined in the clas implementation file (usually *.cpp ), for example:
<code>
class FooPrivate {
public:
FooPrivate()
: m1(0), m2(0)
{};
int m1;
int m2;
QString s;
};
</code>

All you have to do now is to create the private data in your constructors or your init function with
<code>
d = new FooPrivate;
</code>
and to delete it again in your destructor with
<code>
delete d;
</code>

You may not want all member variables to live in the private data object, though. For very often used members, it's faster to put them directly in the class, since inline functions cannot access the d-pointer data. Also note that all data covered by the d-pointer is obviously private. For public or protected access, provide both a set and a get function. Example
<code>
QString Foo::string() const
{
return d->s;
}

void setString( const QString& s )
{
d->s = s;
}
</code>

<h2>Trouble shooting</h2>

=== Adding new data members to classes without d-pointer ===

If you don't have free bitflags, reserved variables and no d-pointer either, but you absolutely have to add a new private member variable, there are still some possibilities left. If your class inherits QObject, you can for example place the additional data in a special child and find it by traversing over the list of children. You can access the list of children with QObject::children(). However, a fancier and usually faster approach is to use a hashtable to store a
mapping between your object and the extra data. For this purpose, Qt provides a pointer-based dictionary called QHash (or QPtrDict in Qt3).

The basic trick in your class implementation of class Foo is:
* Create a private data class FooPrivate.
* Create a static QHash<Foo *, FooPrivate>.
*Note that some compilers/linkers (almost all, unfortunately) do not manage to create static objects in shared libraries. They simply forget to call the constructor. Therefore you should use the <tt>Q_GLOBAL_STATIC</tt> macro to create and access the object:

<code>
// BCI: Add a real d-pointer
Q_GLOBAL_STATIC(QHash<Foo *,FooPrivate>, d_func);
static FooPrivate* d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
if ( ! ret ) {
ret = new FooPrivate;
d_func()->insert( foo, ret );
}
return ret;
}
static void delete_d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
delete ret;
d_func()->remove( foo );
}
</code>

* Now you can use the d-pointer in your class almost as simple as in the code before, just with a function call to d(this). For example:

<code>
d(this)->m1 = 5;
</code>

* Add a line to your destructor:
<code>
delete_d(this);
</code>
* Do not forget to add a BCI remark, so that the hack can be removed in the next version of the library.
* Do not forget to add a d-pointer to your next class.

=== Adding a reimplemented virtual function ===

As already explained, you can safely reimplement a virtual function defined in one of the base classes only if it is safe that the programs linked with the prior version call the implementation in the base class rather than the new one. This is because the compiler sometimes calls virtual functions directly if it can determine which one to call. For example, if you have
<code>
void C::foo()
{
B::foo();
}
</code>

then B::foo() is called directly. If class B inherits from class A which implements foo() and B itself doesn't reimplement it, then C::foo() will in fact call A::foo(). If a newer version of the library adds B::foo(), C::foo() will call it only after a recompilation.

Another more common example is:
<code>
B b; // B derives from A
b.foo();
</code>
then the call to foo() will not use the virtual table. That means that
if B::foo() didn't exist in the library but now does, code that was
compiled with the earlier version will still call A::foo().

If you can't guarantee things will continue to work without a recompilation, move functionality from A::foo() to a new protected function A::foo2() and use this code:
<code>
void A::foo()
{
if( B* b = dynamic_cast< B* >( this ))
b->B::foo(); // B:: is important
else
foo2();
}
void B::foo()
{
// added functionality
A::foo2(); // call base function with real functionality
}
</code>
All calls to A::foo() for objects of type B (or inherited) will result in calling B::foo(). The only case that will not work as expected are calls to A::foo() that explicitly specify A::foo(), but B::foo() calls A::foo2() instead and there should not be other places doing so.

<h3>Using a new class</h3>

<p>A relatively simple method of "extending" a class can be writing a replacement
class that will include also the new functionality (and that may inherit from the old
class to reuse the code). This of course requires adapting and recompiling applications using
the library, so it is not possible this way to fix or extend functionality of classes
that are used by applications compiled against an older version of the library. However,
especially with small and/or performance-critical classes it may be simpler to write
them without making sure they'll be simple to extend in the future and if the need arises
later write a new replacement class that will provide new features or better performance.</p>

<h3>Adding new virtual functions to leaf classes</h3>
<p>
This technique is one of cases of using a new class that can help if there's a need to add
new virtual functions to a class that should stay binary compatible and there is no class
inheriting from it that should also stay binary compatible (i.e. all classes inheriting from it are
in applications). In such case it's possible to add a new class inheriting from the original one
that will add them. Applications using the new functionality will of course have to be modified
to use the new class.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A {
public:
virtual void foo();
};
class B : public A { // newly added class
public:
virtual void bar(); // newly added virtual function
};
void A::foo()
{
// here it's needed to call a new virtual function
if( B* this2 = dynamic_cast< B* >( this ))
this2->bar();
}
</pre></td></tr></table>
It is not possible to use this technique when there are other inherited classes that should also
stay binary compatible because they'd have to inherit from the new class.</p>

<h3>Using signals instead of virtual functions</h3>
<p>
Qt's signals and slots are invoked using a special virtual method created by the Q_OBJECT macro
and it exists in every class inherited from QObject. Therefore adding new
signals and slots doesn't affect binary compatibility and the signals/slots mechanism can be
used to emulate virtual functions.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A : public QObject {
Q_OBJECT
public:
A();
virtual void foo();
signals:
void bar( int* ); // added new "virtual" function
protected slots:
void barslot( int* ); // implementation of the virtual function in A
};

A::A()
{
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void A::foo()
{
int ret;
emit bar( &ret );
}

void A::barslot( int* ret )
{
*ret = 10;
}
</pre></td></tr></table>
Function bar() will act like a virtual function, barslot() implements the actual functionality
of it. Since signals have void return value, data must be returned using arguments. As
there will be only one slot connected to the signal returning data from the slot this way will
work without problems. Note that with Qt4 for this to work the connection type will have to be
Qt::DirectConnection.</p>
<p>
If an inherited class will want to reimplement the functionality of bar() it will have to provide
its own slot:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class B : public A {
Q_OBJECT
public:
B();
protected slots: // necessary to specify as a slot again
void barslot( int* ); // reimplemented functionality of bar()
};

B::B()
{
disconnect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void B::barslot( int* ret )
{
*ret = 20;
}
</pre></td></tr></table>
Now B::barslot() will act like virtual reimplementation of A::bar(). Note that it is necessary
to specify barslot() again as a slot in B and that in the constructor it is necessary to first
disconnect and then connect again, that will disconnect A::barslot() and connect B::barslot()
instead.</p>

<p>Note: the same can be accomplished by implementing a virtual slot.</p>

<p align="right"> <small> <em>
Matthias Ettrich <a href="mailto:ettrich@kde.org">ettrich@kde.org</a><br>
Lubos Lunak <a href="mailto:l.lunak@kde.org">l.lunak@kde.org</a>
</em></small></p>

Policies/Binary Compatibility Issues With C++

2007-01-12T20:31:41Z

CuCullin:

== Definition ==

A library is '''binary compatible''', if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn't require any further modifications, the library is '''source compatible'''.

Binary compatibility saves a lot of trouble. It makes it much easier to distribute software for a certain platform. Without ensuring binary compatibility between releases, people will be forced to provide statically linked binaries. Static binaries are bad because they
* waste resources (especially memory)
* don't allow the program to benefit from bugfixes or extensions in the libraries

In the KDE project, we will provide binary compatibility within the life-span of a major release.

== The Do's and Don'ts ==

You can...

* add new non-virtual functions including signals and slots.
* add a new enum to a class.
* append new enumerators to an existing enum.
* reimplement virtual functions defined in one of the base classes '''if''' it is safe that programs linked with the prior version of the library call the implementation in the base class rather than the new one. ''This is tricky and might be dangerous. Think twice before doing it. Alternatively see below for a workaround.''
* change an inline function or make an inline function non-inline '''if''' it is safe that programs linked with the prior version of the library call the old implementation. ''This is tricky and might be dangerous. Think twice before doing it.'' Because of this, classes that are supposed to stay binary compatible should '''always''' have non-inline destructor, even if it's empty, otherwise the compiler will automatically generate an empty inlined one.
* Remove private non-virtual functions '''if''' they are not called
by any inline functions.
* change the default arguments of a method. It requires recompilation to use the actual new default argument values, though.
* add new '''static''' data members.
* add new classes.

You cannot...
* add new virtual functions as this will change the layout of the virtual table and thus break subclasses. ''See below for some workarounds or ask on mailing lists.''
* change the order of virtual functions in the class declaration. This will just as well change the layout of the virtual table.
* change the signature of a function. This includes:
** changing any of the types of the arguments in the parameter list (instead, add a new method)
** changing the return type
** extending a function with another parameter, even if this parameter has a default argument
Suggestion: when adding new functions with the same name and different/extended argument lists, you may want to add a short note that the two functions shall be merged with a default argument in later versions of the library:

<code>
void functionname( int a );
void functionname( int a, int b ); //BCI: merge with int b = 0
</code>

* change the access rights to some functions or data members, for example from
<tt>private</tt> to <tt>public</tt>. With some compilers, this information may be part of the signature. If you need to make a private function protected or even public, you have to add a new function that calls the private one.
* add new data members to a class or change order of data members in a class (doesn't apply to static ones).
* change the class hierachy apart from adding new classes.

You should...

In order to make a class to extend in the future you should follow these rules:
* add d-pointer. ''See below''.
* add non-inline virtual destructor even if the body is empty.
* reimplement <tt>event</tt> in widget classes, even if the body for the function is empty.
* make all constructors non-inline.
* write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value (e.g. classes inherited from QObject can't be)

== Techniques for Library Programmers ==

The biggest problem when writing libraries is, that one cannot safely add data members since this would change the size and layout of every class, struct, or array containing objects of the type, including subclasses.

=== Bitflags ===
One exception are bitflags. If you use bitflags for enums or bools, you can safely round up to at least the next byte minus 1. A class with members

<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
</code>
<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
uint m4 : 2; // new member
</code>
without breaking binary compatibility. Please round up to a maxmimum of 7 bits (or 15 if the bitfield was already larger than 8). Using the very last bit may cause problems on some compilers.

=== Using a d-Pointer===
Bitflags and predefined reserved variables are nice, but far from being sufficient. This is where the d-pointer technique comes into play. The name "d-pointer" stems from Trolltech's Arnt Gulbrandsen, who first introduced the technique into Qt, making it one of the first C++ GUI libraries to maintain binary compatibility even between bigger release. The technique was quickly adapted as general programming pattern for the KDE libraries by everyone who saw it. It's a great trick to be able to add new private data members to a class without breaking binary compatibility.

'''Remark:''' The d-pointer pattern has been described many
times in computer science history under various names, e.g. as pimpl,
as handle/body or as cheshire cat. Google helps finding online papers
for any of these, just add C++ to the search terms.</small>

In your class definition for class Foo, define a forward declaration
<code>
class FooPrivate;
</code>
and the d-pointer in the private section:
<code>
private:
FooPrivate* d;
</code>
The FooPrivate class itself is purely defined in the clas implementation file (usually *.cpp ), for example:
<code>
class FooPrivate {
public:
FooPrivate()
: m1(0), m2(0)
{};
int m1;
int m2;
QString s;
};
</code>

All you have to do now is to create the private data in your constructors or your init function with
<code>
d = new FooPrivate;
</code>
and to delete it again in your destructor with
<code>
delete d;
</code>

You may not want all member variables to live in the private data object, though. For very often used members, it's faster to put them directly in the class, since inline functions cannot access the d-pointer data. Also note that all data covered by the d-pointer is obviously private. For public or protected access, provide both a set and a get function. Example
<code>
QString Foo::string() const
{
return d->s;
}

void setString( const QString& s )
{
d->s = s;
}
</code>

<h2>Trouble shooting</h2>

=== Adding new data members to classes without d-pointer ===

If you don't have free bitflags, reserved variables and no d-pointer either, but you absolutely have to add a new private member variable, there are still some possibilities left. If your class inherits QObject, you can for example place the additional data in a special child and find it by traversing over the list of children. You can access the list of children with QObject::children(). However, a fancier and usually faster approach is to use a hashtable to store a
mapping between your object and the extra data. For this purpose, Qt provides a pointer-based dictionary called QHash (or QPtrDict in Qt3).

The basic trick in your class implementation of class Foo is:
* Create a private data class FooPrivate.
* Create a static QHash<Foo *, FooPrivate>.
*Note that some compilers/linkers (almost all, unfortunately) do not manage to create static objects in shared libraries. They simply forget to call the constructor. Therefore you should use the <tt>Q_GLOBAL_STATIC</tt> macro to create and access the object:

<code>
// BCI: Add a real d-pointer
Q_GLOBAL_STATIC(QHash<Foo *,FooPrivate>, d_func);
static FooPrivate* d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
if ( ! ret ) {
ret = new FooPrivate;
d_func()->insert( foo, ret );
}
return ret;
}
static void delete_d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
delete ret;
d_func()->remove( foo );
}
</code>

* Now you can use the d-pointer in your class almost as simple as in the code before, just with a function call to d(this). For example:

<code>
d(this)->m1 = 5;
</code>

* Add a line to your destructor:
<code>
delete_d(this);
</code>
* Do not forget to add a BCI remark, so that the hack can be removed in the next version of the library.
* Do not forget to add a d-pointer to your next class.

<h3>Adding a reimplemented virtual function</h3>

<p>As already explained, you can safely reimplement a virtual function defined
in one of the base classes only if it is safe that the programs linked
with the prior version call the implementation in the base class rather than
the new one. This is because the compiler sometimes calls virtual functions
directly if it can determine which one to call (for example if you have
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
void C::foo()
{
B::foo();
}
</pre></td></tr></table>
then B::foo() is called directly. If class B inherits from class A which implements
foo() and B itself doesn't reimplement it, then C::foo() will in fact call A::foo().
If a newer version of the library adds B::foo(), C::foo() will call it only after
a recompilation.</p>

<p>Another more common example is:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
B b; // B derives from A
b.foo();
</pre></td></tr></table>
then the call to foo() will not use the virtual table. That means that
if B::foo() didn't exist in the library but now does, code that was
compiled with the earlier version will still call A::foo().</p>

<p>If you can't guarantee things will continue to work without a recompilation, move
functionality from A::foo() to a new protected function A::foo2() and use this code:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
void A::foo()
{
if( B* b = dynamic_cast< B* >( this ))
b->B::foo(); // B:: is important
else
foo2();
}
void B::foo()
{
// added functionality
A::foo2(); // call base function with real functionality
}
</pre></td></tr></table>
All calls to A::foo() for objects of type B (or inherited) will result in calling B::foo().
The only case that will not work as expected are calls to A::foo() that explicitly specify
A::foo(), but B::foo() calls A::foo2() instead and there should not be other places doing so.
</p>

<h3>Using a new class</h3>

<p>A relatively simple method of "extending" a class can be writing a replacement
class that will include also the new functionality (and that may inherit from the old
class to reuse the code). This of course requires adapting and recompiling applications using
the library, so it is not possible this way to fix or extend functionality of classes
that are used by applications compiled against an older version of the library. However,
especially with small and/or performance-critical classes it may be simpler to write
them without making sure they'll be simple to extend in the future and if the need arises
later write a new replacement class that will provide new features or better performance.</p>

<h3>Adding new virtual functions to leaf classes</h3>
<p>
This technique is one of cases of using a new class that can help if there's a need to add
new virtual functions to a class that should stay binary compatible and there is no class
inheriting from it that should also stay binary compatible (i.e. all classes inheriting from it are
in applications). In such case it's possible to add a new class inheriting from the original one
that will add them. Applications using the new functionality will of course have to be modified
to use the new class.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A {
public:
virtual void foo();
};
class B : public A { // newly added class
public:
virtual void bar(); // newly added virtual function
};
void A::foo()
{
// here it's needed to call a new virtual function
if( B* this2 = dynamic_cast< B* >( this ))
this2->bar();
}
</pre></td></tr></table>
It is not possible to use this technique when there are other inherited classes that should also
stay binary compatible because they'd have to inherit from the new class.</p>

<h3>Using signals instead of virtual functions</h3>
<p>
Qt's signals and slots are invoked using a special virtual method created by the Q_OBJECT macro
and it exists in every class inherited from QObject. Therefore adding new
signals and slots doesn't affect binary compatibility and the signals/slots mechanism can be
used to emulate virtual functions.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A : public QObject {
Q_OBJECT
public:
A();
virtual void foo();
signals:
void bar( int* ); // added new "virtual" function
protected slots:
void barslot( int* ); // implementation of the virtual function in A
};

A::A()
{
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void A::foo()
{
int ret;
emit bar( &ret );
}

void A::barslot( int* ret )
{
*ret = 10;
}
</pre></td></tr></table>
Function bar() will act like a virtual function, barslot() implements the actual functionality
of it. Since signals have void return value, data must be returned using arguments. As
there will be only one slot connected to the signal returning data from the slot this way will
work without problems. Note that with Qt4 for this to work the connection type will have to be
Qt::DirectConnection.</p>
<p>
If an inherited class will want to reimplement the functionality of bar() it will have to provide
its own slot:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class B : public A {
Q_OBJECT
public:
B();
protected slots: // necessary to specify as a slot again
void barslot( int* ); // reimplemented functionality of bar()
};

B::B()
{
disconnect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void B::barslot( int* ret )
{
*ret = 20;
}
</pre></td></tr></table>
Now B::barslot() will act like virtual reimplementation of A::bar(). Note that it is necessary
to specify barslot() again as a slot in B and that in the constructor it is necessary to first
disconnect and then connect again, that will disconnect A::barslot() and connect B::barslot()
instead.</p>

<p>Note: the same can be accomplished by implementing a virtual slot.</p>

<p align="right"> <small> <em>
Matthias Ettrich <a href="mailto:ettrich@kde.org">ettrich@kde.org</a><br>
Lubos Lunak <a href="mailto:l.lunak@kde.org">l.lunak@kde.org</a>
</em></small></p>

Policies/Binary Compatibility Issues With C++

2007-01-12T20:27:51Z

CuCullin: /* Using a d-Pointer */

== Definition ==

A library is '''binary compatible''', if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn't require any further modifications, the library is '''source compatible'''.

Binary compatibility saves a lot of trouble. It makes it much easier to distribute software for a certain platform. Without ensuring binary compatibility between releases, people will be forced to provide statically linked binaries. Static binaries are bad because they
* waste resources (especially memory)
* don't allow the program to benefit from bugfixes or extensions in the libraries

In the KDE project, we will provide binary compatibility within the life-span of a major release.

== The Do's and Don'ts ==

You can...

* add new non-virtual functions including signals and slots.
* add a new enum to a class.
* append new enumerators to an existing enum.
* reimplement virtual functions defined in one of the base classes '''if''' it is safe that programs linked with the prior version of the library call the implementation in the base class rather than the new one. ''This is tricky and might be dangerous. Think twice before doing it. Alternatively see below for a workaround.''
* change an inline function or make an inline function non-inline '''if''' it is safe that programs linked with the prior version of the library call the old implementation. ''This is tricky and might be dangerous. Think twice before doing it.'' Because of this, classes that are supposed to stay binary compatible should '''always''' have non-inline destructor, even if it's empty, otherwise the compiler will automatically generate an empty inlined one.
* Remove private non-virtual functions '''if''' they are not called
by any inline functions.
* change the default arguments of a method. It requires recompilation to use the actual new default argument values, though.
* add new '''static''' data members.
* add new classes.

You cannot...
* add new virtual functions as this will change the layout of the virtual table and thus break subclasses. ''See below for some workarounds or ask on mailing lists.''
* change the order of virtual functions in the class declaration. This will just as well change the layout of the virtual table.
* change the signature of a function. This includes:
** changing any of the types of the arguments in the parameter list (instead, add a new method)
** changing the return type
** extending a function with another parameter, even if this parameter has a default argument
Suggestion: when adding new functions with the same name and different/extended argument lists, you may want to add a short note that the two functions shall be merged with a default argument in later versions of the library:

<code>
void functionname( int a );
void functionname( int a, int b ); //BCI: merge with int b = 0
</code>

* change the access rights to some functions or data members, for example from
<tt>private</tt> to <tt>public</tt>. With some compilers, this information may be part of the signature. If you need to make a private function protected or even public, you have to add a new function that calls the private one.
* add new data members to a class or change order of data members in a class (doesn't apply to static ones).
* change the class hierachy apart from adding new classes.

You should...

In order to make a class to extend in the future you should follow these rules:
* add d-pointer. ''See below''.
* add non-inline virtual destructor even if the body is empty.
* reimplement <tt>event</tt> in widget classes, even if the body for the function is empty.
* make all constructors non-inline.
* write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value (e.g. classes inherited from QObject can't be)

== Techniques for Library Programmers ==

The biggest problem when writing libraries is, that one cannot safely add data members since this would change the size and layout of every class, struct, or array containing objects of the type, including subclasses.

=== Bitflags ===
One exception are bitflags. If you use bitflags for enums or bools, you can safely round up to at least the next byte minus 1. A class with members

<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
</code>
<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
uint m4 : 2; // new member
</code>
without breaking binary compatibility. Please round up to a maxmimum of 7 bits (or 15 if the bitfield was already larger than 8). Using the very last bit may cause problems on some compilers.

=== Using a d-Pointer===
Bitflags and predefined reserved variables are nice, but far from being sufficient. This is where the d-pointer technique comes into play. The name "d-pointer" stems from Trolltech's Arnt Gulbrandsen, who first introduced the technique into Qt, making it one of the first C++ GUI libraries to maintain binary compatibility even between bigger release. The technique was quickly adapted as general programming pattern for the KDE libraries by everyone who saw it. It's a great trick to be able to add new private data members to a class without breaking binary compatibility.

'''Remark:''' The d-pointer pattern has been described many
times in computer science history under various names, e.g. as pimpl,
as handle/body or as cheshire cat. Google helps finding online papers
for any of these, just add C++ to the search terms.</small>

In your class definition for class Foo, define a forward declaration
<code>
class FooPrivate;
</code>
and the d-pointer in the private section:
<code>
private:
FooPrivate* d;
</code>
The FooPrivate class itself is purely defined in the clas implementation file (usually *.cpp ), for example:
<code>
class FooPrivate {
public:
FooPrivate()
: m1(0), m2(0)
{};
int m1;
int m2;
QString s;
};
</code>

All you have to do now is to create the private data in your constructors or your init function with
<code>
d = new FooPrivate;
</code>
and to delete it again in your destructor with
<code>
delete d;
</code>

You may not want all member variables to live in the private data object, though. For very often used members, it's faster to put them directly in the class, since inline functions cannot access the d-pointer data. Also note that all data covered by the d-pointer is obviously private. For public or protected access, provide both a set and a get function. Example
<code>
QString Foo::string() const
{
return d->s;
}

void setString( const QString& s )
{
d->s = s;
}
</code>

<h2>Trouble shooting</h2>

<h3>Adding new data members to classes without d-pointer</h3>

<p> If you don't have free bitflags, reserved variables and no
d-pointer either, but you absolutely have to add a new private member
variable, there are still some possibilities left. If your class
inherits QObject, you can for example place the additional data in a
special child and find it by traversing over the list of children. You
can access the list of children with QObject::children(). However, a
fancier and usually faster approach is to use a hashtable to store a
mapping between your object and the extra data. For this purpose, Qt
provides a pointer-based dictionary called QHash (or QPtrDict in Qt3).</p>

<p> The basic trick in your class implementation of class Foo is:</p>
<ol>
<li> Create a private data class FooPrivate.</li>
<li> Create a static QHash<Foo *, FooPrivate>.

<p> Note that some compilers/linkers (almost all, unfortunately) do
not manage to create static objects in shared libraries. They simply
forget to call the constructor. Therefore you should use the
<tt>Q_GLOBAL_STATIC</tt> macro to create and access the object:</p>

<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
// BCI: Add a real d-pointer
Q_GLOBAL_STATIC(QHash<Foo *,FooPrivate>, d_func);
static FooPrivate* d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
if ( ! ret ) {
ret = new FooPrivate;
d_func()->insert( foo, ret );
}
return ret;
}
static void delete_d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
delete ret;
d_func()->remove( foo );
}
</pre></td></tr></table></li>

<li> Now you can use the d-pointer in your class almost as simple as
in the code before, just with a function call to d(this). For example:

<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
d(this)->m1 = 5;
</pre></td></tr></table></li>

<li> Add a line to your destructor:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
delete_d(this);
</pre></td></tr></table></li>

<li> Do not forget to add a BCI remark, so that the hack can be
removed in the next version of the library.</li>
<li> Do not forget to add a d-pointer to your next class.</li>
</ol>

<h3>Adding a reimplemented virtual function</h3>

<p>As already explained, you can safely reimplement a virtual function defined
in one of the base classes only if it is safe that the programs linked
with the prior version call the implementation in the base class rather than
the new one. This is because the compiler sometimes calls virtual functions
directly if it can determine which one to call (for example if you have
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
void C::foo()
{
B::foo();
}
</pre></td></tr></table>
then B::foo() is called directly. If class B inherits from class A which implements
foo() and B itself doesn't reimplement it, then C::foo() will in fact call A::foo().
If a newer version of the library adds B::foo(), C::foo() will call it only after
a recompilation.</p>

<p>Another more common example is:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
B b; // B derives from A
b.foo();
</pre></td></tr></table>
then the call to foo() will not use the virtual table. That means that
if B::foo() didn't exist in the library but now does, code that was
compiled with the earlier version will still call A::foo().</p>

<p>If you can't guarantee things will continue to work without a recompilation, move
functionality from A::foo() to a new protected function A::foo2() and use this code:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
void A::foo()
{
if( B* b = dynamic_cast< B* >( this ))
b->B::foo(); // B:: is important
else
foo2();
}
void B::foo()
{
// added functionality
A::foo2(); // call base function with real functionality
}
</pre></td></tr></table>
All calls to A::foo() for objects of type B (or inherited) will result in calling B::foo().
The only case that will not work as expected are calls to A::foo() that explicitly specify
A::foo(), but B::foo() calls A::foo2() instead and there should not be other places doing so.
</p>

<h3>Using a new class</h3>

<p>A relatively simple method of "extending" a class can be writing a replacement
class that will include also the new functionality (and that may inherit from the old
class to reuse the code). This of course requires adapting and recompiling applications using
the library, so it is not possible this way to fix or extend functionality of classes
that are used by applications compiled against an older version of the library. However,
especially with small and/or performance-critical classes it may be simpler to write
them without making sure they'll be simple to extend in the future and if the need arises
later write a new replacement class that will provide new features or better performance.</p>

<h3>Adding new virtual functions to leaf classes</h3>
<p>
This technique is one of cases of using a new class that can help if there's a need to add
new virtual functions to a class that should stay binary compatible and there is no class
inheriting from it that should also stay binary compatible (i.e. all classes inheriting from it are
in applications). In such case it's possible to add a new class inheriting from the original one
that will add them. Applications using the new functionality will of course have to be modified
to use the new class.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A {
public:
virtual void foo();
};
class B : public A { // newly added class
public:
virtual void bar(); // newly added virtual function
};
void A::foo()
{
// here it's needed to call a new virtual function
if( B* this2 = dynamic_cast< B* >( this ))
this2->bar();
}
</pre></td></tr></table>
It is not possible to use this technique when there are other inherited classes that should also
stay binary compatible because they'd have to inherit from the new class.</p>

<h3>Using signals instead of virtual functions</h3>
<p>
Qt's signals and slots are invoked using a special virtual method created by the Q_OBJECT macro
and it exists in every class inherited from QObject. Therefore adding new
signals and slots doesn't affect binary compatibility and the signals/slots mechanism can be
used to emulate virtual functions.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A : public QObject {
Q_OBJECT
public:
A();
virtual void foo();
signals:
void bar( int* ); // added new "virtual" function
protected slots:
void barslot( int* ); // implementation of the virtual function in A
};

A::A()
{
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void A::foo()
{
int ret;
emit bar( &ret );
}

void A::barslot( int* ret )
{
*ret = 10;
}
</pre></td></tr></table>
Function bar() will act like a virtual function, barslot() implements the actual functionality
of it. Since signals have void return value, data must be returned using arguments. As
there will be only one slot connected to the signal returning data from the slot this way will
work without problems. Note that with Qt4 for this to work the connection type will have to be
Qt::DirectConnection.</p>
<p>
If an inherited class will want to reimplement the functionality of bar() it will have to provide
its own slot:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class B : public A {
Q_OBJECT
public:
B();
protected slots: // necessary to specify as a slot again
void barslot( int* ); // reimplemented functionality of bar()
};

B::B()
{
disconnect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void B::barslot( int* ret )
{
*ret = 20;
}
</pre></td></tr></table>
Now B::barslot() will act like virtual reimplementation of A::bar(). Note that it is necessary
to specify barslot() again as a slot in B and that in the constructor it is necessary to first
disconnect and then connect again, that will disconnect A::barslot() and connect B::barslot()
instead.</p>

<p>Note: the same can be accomplished by implementing a virtual slot.</p>

<p align="right"> <small> <em>
Matthias Ettrich <a href="mailto:ettrich@kde.org">ettrich@kde.org</a><br>
Lubos Lunak <a href="mailto:l.lunak@kde.org">l.lunak@kde.org</a>
</em></small></p>

Policies/Binary Compatibility Issues With C++

2007-01-12T20:26:21Z

CuCullin: /* The Do's and Don'ts */

== Definition ==

A library is '''binary compatible''', if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn't require any further modifications, the library is '''source compatible'''.

Binary compatibility saves a lot of trouble. It makes it much easier to distribute software for a certain platform. Without ensuring binary compatibility between releases, people will be forced to provide statically linked binaries. Static binaries are bad because they
* waste resources (especially memory)
* don't allow the program to benefit from bugfixes or extensions in the libraries

In the KDE project, we will provide binary compatibility within the life-span of a major release.

== The Do's and Don'ts ==

You can...

* add new non-virtual functions including signals and slots.
* add a new enum to a class.
* append new enumerators to an existing enum.
* reimplement virtual functions defined in one of the base classes '''if''' it is safe that programs linked with the prior version of the library call the implementation in the base class rather than the new one. ''This is tricky and might be dangerous. Think twice before doing it. Alternatively see below for a workaround.''
* change an inline function or make an inline function non-inline '''if''' it is safe that programs linked with the prior version of the library call the old implementation. ''This is tricky and might be dangerous. Think twice before doing it.'' Because of this, classes that are supposed to stay binary compatible should '''always''' have non-inline destructor, even if it's empty, otherwise the compiler will automatically generate an empty inlined one.
* Remove private non-virtual functions '''if''' they are not called
by any inline functions.
* change the default arguments of a method. It requires recompilation to use the actual new default argument values, though.
* add new '''static''' data members.
* add new classes.

You cannot...
* add new virtual functions as this will change the layout of the virtual table and thus break subclasses. ''See below for some workarounds or ask on mailing lists.''
* change the order of virtual functions in the class declaration. This will just as well change the layout of the virtual table.
* change the signature of a function. This includes:
** changing any of the types of the arguments in the parameter list (instead, add a new method)
** changing the return type
** extending a function with another parameter, even if this parameter has a default argument
Suggestion: when adding new functions with the same name and different/extended argument lists, you may want to add a short note that the two functions shall be merged with a default argument in later versions of the library:

<code>
void functionname( int a );
void functionname( int a, int b ); //BCI: merge with int b = 0
</code>

* change the access rights to some functions or data members, for example from
<tt>private</tt> to <tt>public</tt>. With some compilers, this information may be part of the signature. If you need to make a private function protected or even public, you have to add a new function that calls the private one.
* add new data members to a class or change order of data members in a class (doesn't apply to static ones).
* change the class hierachy apart from adding new classes.

You should...

In order to make a class to extend in the future you should follow these rules:
* add d-pointer. ''See below''.
* add non-inline virtual destructor even if the body is empty.
* reimplement <tt>event</tt> in widget classes, even if the body for the function is empty.
* make all constructors non-inline.
* write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value (e.g. classes inherited from QObject can't be)

== Techniques for Library Programmers ==

The biggest problem when writing libraries is, that one cannot safely add data members since this would change the size and layout of every class, struct, or array containing objects of the type, including subclasses.

=== Bitflags ===
One exception are bitflags. If you use bitflags for enums or bools, you can safely round up to at least the next byte minus 1. A class with members

<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
</code>
<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
uint m4 : 2; // new member
</code>
without breaking binary compatibility. Please round up to a maxmimum of 7 bits (or 15 if the bitfield was already larger than 8). Using the very last bit may cause problems on some compilers.

=== Using a d-Pointer===
Bitflags and predefined reserved variables are nice, but far from being sufficient. This is where the d-pointer technique comes into play. The name "d-pointer" stems from Trolltech's Arnt Gulbrandsen, who first introduced the technique into Qt, making it one of the first C++ GUI libraries to maintain binary compatibility even between bigger release. The technique was quickly adapted as general programming pattern for the KDE libraries by everyone who saw it. It's a great trick to be able to add new private data members to a class without breaking binary compatibility.

'''Remark:''' The d-pointer pattern has been described many
times in computer science history under various names, e.g. as pimpl,
as handle/body or as cheshire cat. Google helps finding online papers
for any of these, just add C++ to the search terms.</small>

<p> In your class definition for class Foo, define a forward declaration
</p>
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class FooPrivate;
</pre></td></tr></table>
and the d-pointer in the private section:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
private:
FooPrivate* d;
</pre></td></tr></table>
The FooPrivate class itself is purely defined in the clas implementation file (usually *.cpp ), for example:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class FooPrivate {
public:
FooPrivate()
: m1(0), m2(0)
{};
int m1;
int m2;
QString s;
};
</pre></td></tr></table>
All you have to do now is to create the private data in your constructors or your init function with
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
d = new FooPrivate;
</pre></td></tr></table>
and to delete it again in your destructor with
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
delete d;
</pre></td></tr></table>

<p> You may not want all member variables to live in the private data
object, though. For very often used members, it's faster to put them
directly in the class, since inline functions cannot access the
d-pointer data. Also note that all data covered by the d-pointer is
obviously private. For public or protected access, provide both a set
and a get function. Example</p>
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
QString Foo::string() const
{
return d->s;
}

void setString( const QString& s )
{
d->s = s;
}
</pre></td></tr></table>

<h2>Trouble shooting</h2>

<h3>Adding new data members to classes without d-pointer</h3>

<p> If you don't have free bitflags, reserved variables and no
d-pointer either, but you absolutely have to add a new private member
variable, there are still some possibilities left. If your class
inherits QObject, you can for example place the additional data in a
special child and find it by traversing over the list of children. You
can access the list of children with QObject::children(). However, a
fancier and usually faster approach is to use a hashtable to store a
mapping between your object and the extra data. For this purpose, Qt
provides a pointer-based dictionary called QHash (or QPtrDict in Qt3).</p>

<p> The basic trick in your class implementation of class Foo is:</p>
<ol>
<li> Create a private data class FooPrivate.</li>
<li> Create a static QHash<Foo *, FooPrivate>.

<p> Note that some compilers/linkers (almost all, unfortunately) do
not manage to create static objects in shared libraries. They simply
forget to call the constructor. Therefore you should use the
<tt>Q_GLOBAL_STATIC</tt> macro to create and access the object:</p>

<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
// BCI: Add a real d-pointer
Q_GLOBAL_STATIC(QHash<Foo *,FooPrivate>, d_func);
static FooPrivate* d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
if ( ! ret ) {
ret = new FooPrivate;
d_func()->insert( foo, ret );
}
return ret;
}
static void delete_d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
delete ret;
d_func()->remove( foo );
}
</pre></td></tr></table></li>

<li> Now you can use the d-pointer in your class almost as simple as
in the code before, just with a function call to d(this). For example:

<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
d(this)->m1 = 5;
</pre></td></tr></table></li>

<li> Add a line to your destructor:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
delete_d(this);
</pre></td></tr></table></li>

<li> Do not forget to add a BCI remark, so that the hack can be
removed in the next version of the library.</li>
<li> Do not forget to add a d-pointer to your next class.</li>
</ol>

<h3>Adding a reimplemented virtual function</h3>

<p>As already explained, you can safely reimplement a virtual function defined
in one of the base classes only if it is safe that the programs linked
with the prior version call the implementation in the base class rather than
the new one. This is because the compiler sometimes calls virtual functions
directly if it can determine which one to call (for example if you have
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
void C::foo()
{
B::foo();
}
</pre></td></tr></table>
then B::foo() is called directly. If class B inherits from class A which implements
foo() and B itself doesn't reimplement it, then C::foo() will in fact call A::foo().
If a newer version of the library adds B::foo(), C::foo() will call it only after
a recompilation.</p>

<p>Another more common example is:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
B b; // B derives from A
b.foo();
</pre></td></tr></table>
then the call to foo() will not use the virtual table. That means that
if B::foo() didn't exist in the library but now does, code that was
compiled with the earlier version will still call A::foo().</p>

<p>If you can't guarantee things will continue to work without a recompilation, move
functionality from A::foo() to a new protected function A::foo2() and use this code:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
void A::foo()
{
if( B* b = dynamic_cast< B* >( this ))
b->B::foo(); // B:: is important
else
foo2();
}
void B::foo()
{
// added functionality
A::foo2(); // call base function with real functionality
}
</pre></td></tr></table>
All calls to A::foo() for objects of type B (or inherited) will result in calling B::foo().
The only case that will not work as expected are calls to A::foo() that explicitly specify
A::foo(), but B::foo() calls A::foo2() instead and there should not be other places doing so.
</p>

<h3>Using a new class</h3>

<p>A relatively simple method of "extending" a class can be writing a replacement
class that will include also the new functionality (and that may inherit from the old
class to reuse the code). This of course requires adapting and recompiling applications using
the library, so it is not possible this way to fix or extend functionality of classes
that are used by applications compiled against an older version of the library. However,
especially with small and/or performance-critical classes it may be simpler to write
them without making sure they'll be simple to extend in the future and if the need arises
later write a new replacement class that will provide new features or better performance.</p>

<h3>Adding new virtual functions to leaf classes</h3>
<p>
This technique is one of cases of using a new class that can help if there's a need to add
new virtual functions to a class that should stay binary compatible and there is no class
inheriting from it that should also stay binary compatible (i.e. all classes inheriting from it are
in applications). In such case it's possible to add a new class inheriting from the original one
that will add them. Applications using the new functionality will of course have to be modified
to use the new class.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A {
public:
virtual void foo();
};
class B : public A { // newly added class
public:
virtual void bar(); // newly added virtual function
};
void A::foo()
{
// here it's needed to call a new virtual function
if( B* this2 = dynamic_cast< B* >( this ))
this2->bar();
}
</pre></td></tr></table>
It is not possible to use this technique when there are other inherited classes that should also
stay binary compatible because they'd have to inherit from the new class.</p>

<h3>Using signals instead of virtual functions</h3>
<p>
Qt's signals and slots are invoked using a special virtual method created by the Q_OBJECT macro
and it exists in every class inherited from QObject. Therefore adding new
signals and slots doesn't affect binary compatibility and the signals/slots mechanism can be
used to emulate virtual functions.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A : public QObject {
Q_OBJECT
public:
A();
virtual void foo();
signals:
void bar( int* ); // added new "virtual" function
protected slots:
void barslot( int* ); // implementation of the virtual function in A
};

A::A()
{
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void A::foo()
{
int ret;
emit bar( &ret );
}

void A::barslot( int* ret )
{
*ret = 10;
}
</pre></td></tr></table>
Function bar() will act like a virtual function, barslot() implements the actual functionality
of it. Since signals have void return value, data must be returned using arguments. As
there will be only one slot connected to the signal returning data from the slot this way will
work without problems. Note that with Qt4 for this to work the connection type will have to be
Qt::DirectConnection.</p>
<p>
If an inherited class will want to reimplement the functionality of bar() it will have to provide
its own slot:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class B : public A {
Q_OBJECT
public:
B();
protected slots: // necessary to specify as a slot again
void barslot( int* ); // reimplemented functionality of bar()
};

B::B()
{
disconnect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void B::barslot( int* ret )
{
*ret = 20;
}
</pre></td></tr></table>
Now B::barslot() will act like virtual reimplementation of A::bar(). Note that it is necessary
to specify barslot() again as a slot in B and that in the constructor it is necessary to first
disconnect and then connect again, that will disconnect A::barslot() and connect B::barslot()
instead.</p>

<p>Note: the same can be accomplished by implementing a virtual slot.</p>

<p align="right"> <small> <em>
Matthias Ettrich <a href="mailto:ettrich@kde.org">ettrich@kde.org</a><br>
Lubos Lunak <a href="mailto:l.lunak@kde.org">l.lunak@kde.org</a>
</em></small></p>

Policies/Binary Compatibility Issues With C++

2007-01-12T20:20:48Z

CuCullin:

== Definition ==

A library is '''binary compatible''', if a program linked dynamically to a former version of the library continues running with newer versions of the library without the need to recompile.

If a program needs to be recompiled to run with a new version of library but doesn't require any further modifications, the library is '''source compatible'''.

Binary compatibility saves a lot of trouble. It makes it much easier to distribute software for a certain platform. Without ensuring binary compatibility between releases, people will be forced to provide statically linked binaries. Static binaries are bad because they
* waste resources (especially memory)
* don't allow the program to benefit from bugfixes or extensions in the libraries

In the KDE project, we will provide binary compatibility within the life-span of a major release.

== The Do's and Don'ts ==

You can...

* add new non-virtual functions including signals and slots.
* add a new enum to a class.
* append new enumerators to an existing enum.
* reimplement virtual functions defined in one of the base classes '''if''' it is safe that programs linked with the prior version of the library call the implementation in the base class rather than the new one. '''This is tricky and might be dangerous. Think twice before doing it. Alternatively see below for a workaround.''
* change an inline function or make an inline function non-inline '''if''' it is safe that programs linked with the prior version of the library call the old implementation. ''This is tricky and might be dangerous. Think twice before doing it.'' Because of this, classes that are supposed to stay binary compatible should '''always''' have non-inline destructor, even if it's empty, otherwise the compiler will automatically generate an empty inlined one.
* Remove private non-virtual functions '''if''' they are not called
by any inline functions.
* change the default arguments of a method. It requires recompilation to use the actual new default argument values, though.
* add new '''static''' data members.
* add new classes.

You cannot...
* add new virtual functions as this will change the layout of the virtual table and thus break subclasses. ''See below for some workarounds or ask on mailing lists.''
* change the order of virtual functions in the class declaration. This will just as well change the layout of the virtual table.
* change the signature of a function. This includes:
** changing any of the types of the arguments in the parameter list (instead, add a new method)
** changing the return type
** extending a function with another parameter, even if this parameter has a default argument
Suggestion: when adding new functions with the same name and different/extended argument lists, you may want to add a short note that the two functions shall be merged with a default argument in later versions of the library:

<code>
void functionname( int a );
void functionname( int a, int b ); //BCI: merge with int b = 0
</code>

* change the access rights to some functions or data members, for example from
<tt>private</tt> to <tt>public</tt>. With some compilers, this information may be part of the signature. If you need to make a private function protected or even public, you have to add a new function that calls the private one.
* add new data members to a class or change order of data members in a class (doesn't apply to static ones).
* change the class hierachy apart from adding new classes.

You should...

In order to make a class to extend in the future you should follow these rules:
* add d-pointer. ''See below''.
* add non-inline virtual destructor even if the body is empty.
* reimplement <tt>event</tt> in widget classes, even if the body for the function is empty.
* make all constructors non-inline.
* write non-inline implementations of the copy constructor and assignment operator unless the class cannot be copied by value (e.g. classes inherited from QObject can't be)

== Techniques for Library Programmers ==

The biggest problem when writing libraries is, that one cannot safely add data members since this would change the size and layout of every class, struct, or array containing objects of the type, including subclasses.

=== Bitflags ===
One exception are bitflags. If you use bitflags for enums or bools, you can safely round up to at least the next byte minus 1. A class with members

<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
</code>
<code>
uint m1 : 1;
uint m2 : 3;
uint m3 : 1;
uint m4 : 2; // new member
</code>
without breaking binary compatibility. Please round up to a maxmimum of 7 bits (or 15 if the bitfield was already larger than 8). Using the very last bit may cause problems on some compilers.

=== Using a d-Pointer===
Bitflags and predefined reserved variables are nice, but far from being sufficient. This is where the d-pointer technique comes into play. The name "d-pointer" stems from Trolltech's Arnt Gulbrandsen, who first introduced the technique into Qt, making it one of the first C++ GUI libraries to maintain binary compatibility even between bigger release. The technique was quickly adapted as general programming pattern for the KDE libraries by everyone who saw it. It's a great trick to be able to add new private data members to a class without breaking binary compatibility.

'''Remark:''' The d-pointer pattern has been described many
times in computer science history under various names, e.g. as pimpl,
as handle/body or as cheshire cat. Google helps finding online papers
for any of these, just add C++ to the search terms.</small>

<p> In your class definition for class Foo, define a forward declaration
</p>
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class FooPrivate;
</pre></td></tr></table>
and the d-pointer in the private section:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
private:
FooPrivate* d;
</pre></td></tr></table>
The FooPrivate class itself is purely defined in the clas implementation file (usually *.cpp ), for example:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class FooPrivate {
public:
FooPrivate()
: m1(0), m2(0)
{};
int m1;
int m2;
QString s;
};
</pre></td></tr></table>
All you have to do now is to create the private data in your constructors or your init function with
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
d = new FooPrivate;
</pre></td></tr></table>
and to delete it again in your destructor with
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
delete d;
</pre></td></tr></table>

<p> You may not want all member variables to live in the private data
object, though. For very often used members, it's faster to put them
directly in the class, since inline functions cannot access the
d-pointer data. Also note that all data covered by the d-pointer is
obviously private. For public or protected access, provide both a set
and a get function. Example</p>
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
QString Foo::string() const
{
return d->s;
}

void setString( const QString& s )
{
d->s = s;
}
</pre></td></tr></table>

<h2>Trouble shooting</h2>

<h3>Adding new data members to classes without d-pointer</h3>

<p> If you don't have free bitflags, reserved variables and no
d-pointer either, but you absolutely have to add a new private member
variable, there are still some possibilities left. If your class
inherits QObject, you can for example place the additional data in a
special child and find it by traversing over the list of children. You
can access the list of children with QObject::children(). However, a
fancier and usually faster approach is to use a hashtable to store a
mapping between your object and the extra data. For this purpose, Qt
provides a pointer-based dictionary called QHash (or QPtrDict in Qt3).</p>

<p> The basic trick in your class implementation of class Foo is:</p>
<ol>
<li> Create a private data class FooPrivate.</li>
<li> Create a static QHash<Foo *, FooPrivate>.

<p> Note that some compilers/linkers (almost all, unfortunately) do
not manage to create static objects in shared libraries. They simply
forget to call the constructor. Therefore you should use the
<tt>Q_GLOBAL_STATIC</tt> macro to create and access the object:</p>

<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
// BCI: Add a real d-pointer
Q_GLOBAL_STATIC(QHash<Foo *,FooPrivate>, d_func);
static FooPrivate* d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
if ( ! ret ) {
ret = new FooPrivate;
d_func()->insert( foo, ret );
}
return ret;
}
static void delete_d( const Foo* foo )
{
FooPrivate* ret = d_func()->value( foo, 0 );
delete ret;
d_func()->remove( foo );
}
</pre></td></tr></table></li>

<li> Now you can use the d-pointer in your class almost as simple as
in the code before, just with a function call to d(this). For example:

<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
d(this)->m1 = 5;
</pre></td></tr></table></li>

<li> Add a line to your destructor:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
delete_d(this);
</pre></td></tr></table></li>

<li> Do not forget to add a BCI remark, so that the hack can be
removed in the next version of the library.</li>
<li> Do not forget to add a d-pointer to your next class.</li>
</ol>

<h3>Adding a reimplemented virtual function</h3>

<p>As already explained, you can safely reimplement a virtual function defined
in one of the base classes only if it is safe that the programs linked
with the prior version call the implementation in the base class rather than
the new one. This is because the compiler sometimes calls virtual functions
directly if it can determine which one to call (for example if you have
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
void C::foo()
{
B::foo();
}
</pre></td></tr></table>
then B::foo() is called directly. If class B inherits from class A which implements
foo() and B itself doesn't reimplement it, then C::foo() will in fact call A::foo().
If a newer version of the library adds B::foo(), C::foo() will call it only after
a recompilation.</p>

<p>Another more common example is:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
B b; // B derives from A
b.foo();
</pre></td></tr></table>
then the call to foo() will not use the virtual table. That means that
if B::foo() didn't exist in the library but now does, code that was
compiled with the earlier version will still call A::foo().</p>

<p>If you can't guarantee things will continue to work without a recompilation, move
functionality from A::foo() to a new protected function A::foo2() and use this code:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
void A::foo()
{
if( B* b = dynamic_cast< B* >( this ))
b->B::foo(); // B:: is important
else
foo2();
}
void B::foo()
{
// added functionality
A::foo2(); // call base function with real functionality
}
</pre></td></tr></table>
All calls to A::foo() for objects of type B (or inherited) will result in calling B::foo().
The only case that will not work as expected are calls to A::foo() that explicitly specify
A::foo(), but B::foo() calls A::foo2() instead and there should not be other places doing so.
</p>

<h3>Using a new class</h3>

<p>A relatively simple method of "extending" a class can be writing a replacement
class that will include also the new functionality (and that may inherit from the old
class to reuse the code). This of course requires adapting and recompiling applications using
the library, so it is not possible this way to fix or extend functionality of classes
that are used by applications compiled against an older version of the library. However,
especially with small and/or performance-critical classes it may be simpler to write
them without making sure they'll be simple to extend in the future and if the need arises
later write a new replacement class that will provide new features or better performance.</p>

<h3>Adding new virtual functions to leaf classes</h3>
<p>
This technique is one of cases of using a new class that can help if there's a need to add
new virtual functions to a class that should stay binary compatible and there is no class
inheriting from it that should also stay binary compatible (i.e. all classes inheriting from it are
in applications). In such case it's possible to add a new class inheriting from the original one
that will add them. Applications using the new functionality will of course have to be modified
to use the new class.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A {
public:
virtual void foo();
};
class B : public A { // newly added class
public:
virtual void bar(); // newly added virtual function
};
void A::foo()
{
// here it's needed to call a new virtual function
if( B* this2 = dynamic_cast< B* >( this ))
this2->bar();
}
</pre></td></tr></table>
It is not possible to use this technique when there are other inherited classes that should also
stay binary compatible because they'd have to inherit from the new class.</p>

<h3>Using signals instead of virtual functions</h3>
<p>
Qt's signals and slots are invoked using a special virtual method created by the Q_OBJECT macro
and it exists in every class inherited from QObject. Therefore adding new
signals and slots doesn't affect binary compatibility and the signals/slots mechanism can be
used to emulate virtual functions.
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class A : public QObject {
Q_OBJECT
public:
A();
virtual void foo();
signals:
void bar( int* ); // added new "virtual" function
protected slots:
void barslot( int* ); // implementation of the virtual function in A
};

A::A()
{
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void A::foo()
{
int ret;
emit bar( &ret );
}

void A::barslot( int* ret )
{
*ret = 10;
}
</pre></td></tr></table>
Function bar() will act like a virtual function, barslot() implements the actual functionality
of it. Since signals have void return value, data must be returned using arguments. As
there will be only one slot connected to the signal returning data from the slot this way will
work without problems. Note that with Qt4 for this to work the connection type will have to be
Qt::DirectConnection.</p>
<p>
If an inherited class will want to reimplement the functionality of bar() it will have to provide
its own slot:
<table align="center" width="80%"><tr><td BGCOLOR="#F0F0FF"><pre>
class B : public A {
Q_OBJECT
public:
B();
protected slots: // necessary to specify as a slot again
void barslot( int* ); // reimplemented functionality of bar()
};

B::B()
{
disconnect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
connect( this, SIGNAL( bar( int* )), this, SLOT( barslot( int* )));
}

void B::barslot( int* ret )
{
*ret = 20;
}
</pre></td></tr></table>
Now B::barslot() will act like virtual reimplementation of A::bar(). Note that it is necessary
to specify barslot() again as a slot in B and that in the constructor it is necessary to first
disconnect and then connect again, that will disconnect A::barslot() and connect B::barslot()
instead.</p>

<p>Note: the same can be accomplished by implementing a virtual slot.</p>

<p align="right"> <small> <em>
Matthias Ettrich <a href="mailto:ettrich@kde.org">ettrich@kde.org</a><br>
Lubos Lunak <a href="mailto:l.lunak@kde.org">l.lunak@kde.org</a>
</em></small></p>

Development/Tutorials/Introduction to Get Hot New Stuff

2007-01-12T18:13:45Z

CuCullin: Improve... TODO...

{{improve}}

== Introduction ==
Similar to how programming languages shifted focus from algorithms to data structures in the 70s, desktop application development emphasizes more and more on user data, i.e. data intentionally produced or consumed by the user. Both on the internet and in corporate intranets, sharing this data is considered an easy way to customize desktops and to advertise one's creativity. The 'Get Hot New Stuff' (GHNS) framework in KDE exists to support this approach, and the KNewStuff library is the key for application authors to enable GHNS.

== Preparations ==
The first steps are usually made in preparing the usage of KNewStuff. For this matter, the library must be available (a task which could be done using autoconf, but since it's part of kdelibs, we simply assume it's available with any recent KDE installation.) Authors of 3rd pary applications can ensure the availability as part of kdepim-libs in KDE 3.2 using the AC_KNEWSTUFF macro. It must also be included in the set of libraries against which the application is linked, so modifying the Makefile.am and reconfiguring the application are to be done.

<code>
bin_PROGRAMS = myapp
myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff
</code>

The header files are installed under $kdedir/include/knewstuff/, so in the relevant files, they're included with statements such as:

<code>
#include <knewstuff/downloaddialog.h>
</code>

The following header files are provided by KNewStuff:
* downloaddialog.h: Easy to use download dialog
* engine.h: Access to the complex, but customizable background operations
* entry.h: (internal) Data fields of entries, such as Author or Title
* ghns.h: [not installed]
* knewstuffgeneric.h: Easy to use installation handler for the downloaded files
* knewstuff.h: Main knewstuff functionality
* providerdialog.h: Preconfigured dialog for provider selection
* provider.h: Provider entries, and ProviderLoader
* testnewstuff.h: [not installed]
* uploaddialog.h: Easy to use upload dialog

For more information on the background processes, please have a look at the information provided by [http://www.kstuff.org/docs/ kstuff.org]. However application authors should only need a basic understanding of those.

== Downloading Data ==

Depending on the application, providing additional data can be accomplished using the 'File Import' dialog, 'Internet Level' menu item, or just an 'Update now' KAction. All of those have in common that they invoke a slot which will contain the actual KNewStuff calls.

<code>
void MyApp::slotDownload()
{
KNewStuff::DownloadDialog::open("myapp/templates");
}
</code>

This is all. If desired, more control can be exercised on the whole download process, as outlined below. For the beginning, the above is already fully functional, and should be used at first.

== TODO Downloading in Detail ==
The example above implicitely constructs an internal Engine object, retrieves the directory list, fetches the provider lists specified in the directory, and the entries in each of the provider lists, compares them to the data files previously installed, and displays them in the download dialog. This dialog in turn handles all the installation issues. Of course there is no magic involved, and for more control about the subtasks, the following is recommended:

<code>
(to be precised)
</code>

== Installation ==

Similar to the provider list, the installation procedures are described in the application's configuration file. The default (if these entries are missing) is to just download the file to a temporary location, which is not useful in most of the cases. There are two entries: target location, and post-installation command. The target location can either be StandardResource, matching the KDE resource types, or TargetDir, matching an application directory under $KDEHOME/share/apps/appname. The post installation command can be a binary with '%f' as parameter (note the single quotes to prevent string format attacks), but it can as well be a DCOP call, so the application can directly work with the data.

<code>
[KNewStuff]
StandardResource=wallpaper
InstallationCommand=dcop kdesktop KBackgroundIface setWallpaper '%f' 2

TargetDir=kamikaze
</code>

== Uploads ==

The beginning of the upload process works similar to downloads. A MasterServer or ProvidersUrl is used to retrieve the provider list, and one of the providers is selected by the user. Only providers which allow uploads are taken into account. After this selection however, the differences begin. The user has to fill in the necessary information such as title, author name or version number into the upload dialog. Also, the payload and preview files have to be selected, this however will in most cases be the application's task. In Kamikaze, the level file is pre-rendered to an invisible QCanvas, and the resulting graphics is minimized and automatically specified for the upload. The upload will then happen using the protocol accepted by the provider, which in most cases will be anonymous FTP.

<code>
#include <knewstuff/knewstuffgeneric.h>
#include <knewstuff/engine.h>
#include <knewstuff/uploaddialog.h>
// ...
QString file, previewfile;
KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this);
ns->upload(file.name(), previewfile.name());
</code>

== Conclusion ==

Sharing creativity should become a default property of modern desktops, and KDE once again leads the pack by providing both upload and download facilities. If enough applications of different areas make use of them, it helps users to be more productive and have more fun with their computer.

Development/Tutorials/Introduction to Get Hot New Stuff

2007-01-12T18:13:18Z

CuCullin: /* Downloading in Detail */

== Introduction ==
Similar to how programming languages shifted focus from algorithms to data structures in the 70s, desktop application development emphasizes more and more on user data, i.e. data intentionally produced or consumed by the user. Both on the internet and in corporate intranets, sharing this data is considered an easy way to customize desktops and to advertise one's creativity. The 'Get Hot New Stuff' (GHNS) framework in KDE exists to support this approach, and the KNewStuff library is the key for application authors to enable GHNS.

== Preparations ==
The first steps are usually made in preparing the usage of KNewStuff. For this matter, the library must be available (a task which could be done using autoconf, but since it's part of kdelibs, we simply assume it's available with any recent KDE installation.) Authors of 3rd pary applications can ensure the availability as part of kdepim-libs in KDE 3.2 using the AC_KNEWSTUFF macro. It must also be included in the set of libraries against which the application is linked, so modifying the Makefile.am and reconfiguring the application are to be done.

<code>
bin_PROGRAMS = myapp
myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff
</code>

The header files are installed under $kdedir/include/knewstuff/, so in the relevant files, they're included with statements such as:

<code>
#include <knewstuff/downloaddialog.h>
</code>

The following header files are provided by KNewStuff:
* downloaddialog.h: Easy to use download dialog
* engine.h: Access to the complex, but customizable background operations
* entry.h: (internal) Data fields of entries, such as Author or Title
* ghns.h: [not installed]
* knewstuffgeneric.h: Easy to use installation handler for the downloaded files
* knewstuff.h: Main knewstuff functionality
* providerdialog.h: Preconfigured dialog for provider selection
* provider.h: Provider entries, and ProviderLoader
* testnewstuff.h: [not installed]
* uploaddialog.h: Easy to use upload dialog

For more information on the background processes, please have a look at the information provided by [http://www.kstuff.org/docs/ kstuff.org]. However application authors should only need a basic understanding of those.

== Downloading Data ==

Depending on the application, providing additional data can be accomplished using the 'File Import' dialog, 'Internet Level' menu item, or just an 'Update now' KAction. All of those have in common that they invoke a slot which will contain the actual KNewStuff calls.

<code>
void MyApp::slotDownload()
{
KNewStuff::DownloadDialog::open("myapp/templates");
}
</code>

This is all. If desired, more control can be exercised on the whole download process, as outlined below. For the beginning, the above is already fully functional, and should be used at first.

== TODO Downloading in Detail ==
The example above implicitely constructs an internal Engine object, retrieves the directory list, fetches the provider lists specified in the directory, and the entries in each of the provider lists, compares them to the data files previously installed, and displays them in the download dialog. This dialog in turn handles all the installation issues. Of course there is no magic involved, and for more control about the subtasks, the following is recommended:

<code>
(to be precised)
</code>

== Installation ==

Similar to the provider list, the installation procedures are described in the application's configuration file. The default (if these entries are missing) is to just download the file to a temporary location, which is not useful in most of the cases. There are two entries: target location, and post-installation command. The target location can either be StandardResource, matching the KDE resource types, or TargetDir, matching an application directory under $KDEHOME/share/apps/appname. The post installation command can be a binary with '%f' as parameter (note the single quotes to prevent string format attacks), but it can as well be a DCOP call, so the application can directly work with the data.

<code>
[KNewStuff]
StandardResource=wallpaper
InstallationCommand=dcop kdesktop KBackgroundIface setWallpaper '%f' 2

TargetDir=kamikaze
</code>

== Uploads ==

The beginning of the upload process works similar to downloads. A MasterServer or ProvidersUrl is used to retrieve the provider list, and one of the providers is selected by the user. Only providers which allow uploads are taken into account. After this selection however, the differences begin. The user has to fill in the necessary information such as title, author name or version number into the upload dialog. Also, the payload and preview files have to be selected, this however will in most cases be the application's task. In Kamikaze, the level file is pre-rendered to an invisible QCanvas, and the resulting graphics is minimized and automatically specified for the upload. The upload will then happen using the protocol accepted by the provider, which in most cases will be anonymous FTP.

<code>
#include <knewstuff/knewstuffgeneric.h>
#include <knewstuff/engine.h>
#include <knewstuff/uploaddialog.h>
// ...
QString file, previewfile;
KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this);
ns->upload(file.name(), previewfile.name());
</code>

== Conclusion ==

Sharing creativity should become a default property of modern desktops, and KDE once again leads the pack by providing both upload and download facilities. If enough applications of different areas make use of them, it helps users to be more productive and have more fun with their computer.

Development/Tutorials

2007-01-12T03:34:13Z

CuCullin: /* Shell */ Original Link

Tutorials are the fastest way of finding out what KDE will do for you, and how to do it. Here is a list of currently available tutorials.

== Getting started ==
;[[/Programming Tutorial KDE 4|Introduction To KDE 4 Programming]]
:''You are interested in writing applications with KDE 4? This tutorial series is aimed at those completely new to KDE programming.''

;[[/CMake|Introduction to CMake]]
:''How to use the CMake build system used by KDE4''

;[[/Using Qt Designer|Using Qt Designer to build user interfaces]]
:''How to create UI files with designer, and how to integrate them into a KDE program''

;[[/Command-Line Options|Using Command-line Options]]
:''How to use the KDE Command-line arguments system''

;[[/Debugging|Debugging your application]]
:''Tips, tools and techniques to apply when debugging your KDE application''

;[[Development/Tutorials/Unittests|Writing Unittests for Qt4 and KDE4 with QTestLib]] ([http://developer.kde.org/documentation/tutorials/writingunittests/writingunittests.html Original link])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to write unit tests using the QTestLib framework. It is presented as an example based tutorial, and is still under development.'' '''Does this belong in this section? It's hardly a beginner tutorial.'''

;[[/Code_Checking|Semi-automatic ways to detect code errors]]
:''Techniques you can use to detect errors in KDE code'' '''Maybe this should be put under the Dubugging page? Or maybe both these pages should be put in their own subsection on this page?'''

== Managing Configuration Data With KConfig ==

;[[/Using KConfig XT|Using KConfig XT]]
:''Tutorial on how to efficiently use the KConfig XT framework.''

== File Access With KIO ==

== Localization ==
;[[/Localization/Unicode|101: Unicode]]
:''An introduction to what Unicode is as well as how to handle Unicode data in KDE applications.''

; [[/Localization/i18n|110: Writing Applications With Localization in Mind]]
:''This tutorial covers what localization is, why it's important and how to ensure your application is ready to be localized. A must read for all application developers.''

; [[/Localization/i18n Mistakes|115: Avoiding Common Localization Pitfalls]]
:''There are several common mistakes that prevent applications from being properly localized. Find out what they are and how to easily avoid them in this tutorial.''

; [[/Localization/Building KDE's l10n Module|120: Building KDE's Localization Module]]
:''Building and installing language support from KDE's localization (l10n) module is a good idea for those working on applications in the main KDE repository. Doing so will allow you to test your application in another language and spot problem areas. Learn how to do just that in this tutorial.''

; [[/Localization/i18n Build Systems|200: Incorporating i18n Into the Build System]]
:''Once your application is ready to be localized, the next step is to ensure that translation files are built automatically and kept up to date. This tutorial covers the necessary CMakeFiles.txt additions as well the process of distributing the resulting message catalogs with your application.''

; [[/Localization/i18n Challenges|210: Common i18n Challenges and Solutions]]
:''This tutorial covers challenges that you may eventually run into such as translating handbooks and other data that exists outside of the source code, merging and handling obsolete .po files, deeling with freezes, coding in languages other than English and creating independent releases of or moving applications between KDE modules.''

== Components and Plugins ==

== Application Automation and Scripting ==

=== D-Bus ===
; [[/D-Bus/Introduction|101: Introduction to D-Bus]]
:''A straight-forward introduction to the core concepts in D-Bus from an application developer's perspective, this tutorial covers what D-Bus is and how it can be used by applications.''
; [[/D-Bus/Accessing Interfaces|201: Accessing D-Bus Interfaces]]
:''A step-by-step guide to calling D-Bus methods and connecting to D-Bus signals using QtDBus.''
; [[/D-Bus/Creating Interfaces|211: Creating D-Bus Interfaces]]
:''Learn how to expose functionality in your application by creating and using custom D-Bus interfaces. Covers generating the XML descriptions, instantiating interfaces at run time and setting up the build system with CMake.''
; [[/D-Bus/Autostart Services|300: D-Bus Autostart Services]]
:''Turn your application into a D-Bus autostart service with this tutorial. This D-Bus feature will ensure that even when your application isn't running that D-Bus calls made to it will work by relying on the D-Bus daemon itself to start your app if and when needed.''

=== Konqueror ===
; [[/Creating Konqueror Service Menus|Creating Konqueror Service Menus]]
:''This tutorial shows you how to create mimetype-specific actions in Konqueror's context menu (aka "servicemenus").''

===Kross===
; [[Development/Tutorials/Kross-Tutorial|Kross Tutorial]] ([http://wiki.koffice.org/index.php?title=Kross/Tutorial Original Link])
:''This tutorial explains how to integrate the Kross scripting framework into an application.''

== Search and Metadata ==

; [[/Writing file analyzers|Writing file analyzers]]
:''File analyzers extract data from files to display in the file dialogs and file managers. The data gathered this way is also used to search for files. KDE4 allows the use of multiple analyzers per file type. This tutorial describes how you can write new analyzers.''

== Hardware Awareness ==

;[[/Solid_Tutorials|Introduction to Solid]]
:''An introduction to using the Solid hardware discovery and interaction system in KDE applications.''

;[[/Solid_Network_Tutorial|Accessing Network Information]]
:''How to use the Solid system to get information about the network''

==Printing==

;[[/Printing Hello World|101: Hello World]]
:''Introduction to the KDE printing system''

;TODO 110 Print Dialog
:''Using the KDE print dialog''

== Get Hot New Stuff ==
; [[Development/Tutorials/Introduction to Get Hot New Stuff|Introduction to Get Hot New Stuff]] ([http://edu.kde.org/development/ghns.php Original Link])
:''An introduction to the developer-friendly network update system that allows KDE applications to fetch new application data at runtime in a user friendly manner.''

;[[Development/Tutorials/KNewStuffSecure|KNewStuff Secure]] ([http://developer.kde.org/documentation/tutorials/knewstuffsecure/index.html Original Link])
:''Tutorial showing how to share resources in a secured way (KDE 3.4 and later).'' By András Mantia <amantia@kde.org>.

== Rapid Application Development ==

=== Python ===

;[[Development/Tutorials/101_Python_introduction_to_signal_and_slots|101 Introduction to signal and slots]]
:''A simple introduction to QT's signal and slots architecture.''

;[http://www.xs4all.nl/~bsarempt/python/tutorial.html KDE-Python tutorial]
:''A python version of Daniel's KDE tutorial by Boudewijn Rempt.''

=== Ruby ===

;[http://developer.kde.org/language-bindings/ruby/kde3tutorial/index.html KDE Ruby Korundum tutorial]
:''A ruby version of Antonio Larrosa Jiménez's KDE tutorial by Richard Dale. See the [http://developer.kde.org/language-bindings/ruby/index.html Ruby Developers Corner] for Qt tutorials and other info.''

;[[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
:''Trolltech's fabulous introductory tutorial to Qt, translated to Ruby.''

=== Shell ===

;[[Development/Tutorials/Shell_Scripting_with_KDE_Dialogs|Shell Scripting with KDE dialogs]] ([http://developer.kde.org/documentation/tutorials/kdialog/t1.html Original Link]) ([http://developer.kde.org/documentation/tutorials/kdialog-german/t1.html German Version])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to use KDE dialogs in shell scripts with kdialog. It is presented as an example based tutorial.''

== Other tutorials ==

;[http://developer.kde.org/documentation/tutorials/kdeeduplot/kdeeduplot_tutorial.tar.bz2 Using and extending the KDE EDU Plot widget (docbook archive)]
:''This tutorial introduces Jason Harris' KPlotWidget that is part of the KDE EDU package. Contains information about defining your own widget in QT / KDevelop designer and about subclassing widgets and overriding member functions to extend functionality.''

== KDE2 and KDE3 Materials ==

;[[Development/Tutorials/KDE3|KDE3 Tutorials]]
:''These tutorials cover topics related to KDE3.''

;[[Development/Tutorials/KDE2|KDE2 Tutorials]]
:''These tutorials cover topics related to KDE2.''

Development/Tutorials

2007-01-12T03:33:18Z

CuCullin: /* Get Hot New Stuff */ Original Link

Tutorials are the fastest way of finding out what KDE will do for you, and how to do it. Here is a list of currently available tutorials.

== Getting started ==
;[[/Programming Tutorial KDE 4|Introduction To KDE 4 Programming]]
:''You are interested in writing applications with KDE 4? This tutorial series is aimed at those completely new to KDE programming.''

;[[/CMake|Introduction to CMake]]
:''How to use the CMake build system used by KDE4''

;[[/Using Qt Designer|Using Qt Designer to build user interfaces]]
:''How to create UI files with designer, and how to integrate them into a KDE program''

;[[/Command-Line Options|Using Command-line Options]]
:''How to use the KDE Command-line arguments system''

;[[/Debugging|Debugging your application]]
:''Tips, tools and techniques to apply when debugging your KDE application''

;[[Development/Tutorials/Unittests|Writing Unittests for Qt4 and KDE4 with QTestLib]] ([http://developer.kde.org/documentation/tutorials/writingunittests/writingunittests.html Original link])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to write unit tests using the QTestLib framework. It is presented as an example based tutorial, and is still under development.'' '''Does this belong in this section? It's hardly a beginner tutorial.'''

;[[/Code_Checking|Semi-automatic ways to detect code errors]]
:''Techniques you can use to detect errors in KDE code'' '''Maybe this should be put under the Dubugging page? Or maybe both these pages should be put in their own subsection on this page?'''

== Managing Configuration Data With KConfig ==

;[[/Using KConfig XT|Using KConfig XT]]
:''Tutorial on how to efficiently use the KConfig XT framework.''

== File Access With KIO ==

== Localization ==
;[[/Localization/Unicode|101: Unicode]]
:''An introduction to what Unicode is as well as how to handle Unicode data in KDE applications.''

; [[/Localization/i18n|110: Writing Applications With Localization in Mind]]
:''This tutorial covers what localization is, why it's important and how to ensure your application is ready to be localized. A must read for all application developers.''

; [[/Localization/i18n Mistakes|115: Avoiding Common Localization Pitfalls]]
:''There are several common mistakes that prevent applications from being properly localized. Find out what they are and how to easily avoid them in this tutorial.''

; [[/Localization/Building KDE's l10n Module|120: Building KDE's Localization Module]]
:''Building and installing language support from KDE's localization (l10n) module is a good idea for those working on applications in the main KDE repository. Doing so will allow you to test your application in another language and spot problem areas. Learn how to do just that in this tutorial.''

; [[/Localization/i18n Build Systems|200: Incorporating i18n Into the Build System]]
:''Once your application is ready to be localized, the next step is to ensure that translation files are built automatically and kept up to date. This tutorial covers the necessary CMakeFiles.txt additions as well the process of distributing the resulting message catalogs with your application.''

; [[/Localization/i18n Challenges|210: Common i18n Challenges and Solutions]]
:''This tutorial covers challenges that you may eventually run into such as translating handbooks and other data that exists outside of the source code, merging and handling obsolete .po files, deeling with freezes, coding in languages other than English and creating independent releases of or moving applications between KDE modules.''

== Components and Plugins ==

== Application Automation and Scripting ==

=== D-Bus ===
; [[/D-Bus/Introduction|101: Introduction to D-Bus]]
:''A straight-forward introduction to the core concepts in D-Bus from an application developer's perspective, this tutorial covers what D-Bus is and how it can be used by applications.''
; [[/D-Bus/Accessing Interfaces|201: Accessing D-Bus Interfaces]]
:''A step-by-step guide to calling D-Bus methods and connecting to D-Bus signals using QtDBus.''
; [[/D-Bus/Creating Interfaces|211: Creating D-Bus Interfaces]]
:''Learn how to expose functionality in your application by creating and using custom D-Bus interfaces. Covers generating the XML descriptions, instantiating interfaces at run time and setting up the build system with CMake.''
; [[/D-Bus/Autostart Services|300: D-Bus Autostart Services]]
:''Turn your application into a D-Bus autostart service with this tutorial. This D-Bus feature will ensure that even when your application isn't running that D-Bus calls made to it will work by relying on the D-Bus daemon itself to start your app if and when needed.''

=== Konqueror ===
; [[/Creating Konqueror Service Menus|Creating Konqueror Service Menus]]
:''This tutorial shows you how to create mimetype-specific actions in Konqueror's context menu (aka "servicemenus").''

===Kross===
; [[Development/Tutorials/Kross-Tutorial|Kross Tutorial]] ([http://wiki.koffice.org/index.php?title=Kross/Tutorial Original Link])
:''This tutorial explains how to integrate the Kross scripting framework into an application.''

== Search and Metadata ==

; [[/Writing file analyzers|Writing file analyzers]]
:''File analyzers extract data from files to display in the file dialogs and file managers. The data gathered this way is also used to search for files. KDE4 allows the use of multiple analyzers per file type. This tutorial describes how you can write new analyzers.''

== Hardware Awareness ==

;[[/Solid_Tutorials|Introduction to Solid]]
:''An introduction to using the Solid hardware discovery and interaction system in KDE applications.''

;[[/Solid_Network_Tutorial|Accessing Network Information]]
:''How to use the Solid system to get information about the network''

==Printing==

;[[/Printing Hello World|101: Hello World]]
:''Introduction to the KDE printing system''

;TODO 110 Print Dialog
:''Using the KDE print dialog''

== Get Hot New Stuff ==
; [[Development/Tutorials/Introduction to Get Hot New Stuff|Introduction to Get Hot New Stuff]] ([http://edu.kde.org/development/ghns.php Original Link])
:''An introduction to the developer-friendly network update system that allows KDE applications to fetch new application data at runtime in a user friendly manner.''

;[[Development/Tutorials/KNewStuffSecure|KNewStuff Secure]] ([http://developer.kde.org/documentation/tutorials/knewstuffsecure/index.html Original Link])
:''Tutorial showing how to share resources in a secured way (KDE 3.4 and later).'' By András Mantia <amantia@kde.org>.

== Rapid Application Development ==

=== Python ===

;[[Development/Tutorials/101_Python_introduction_to_signal_and_slots|101 Introduction to signal and slots]]
:''A simple introduction to QT's signal and slots architecture.''

;[http://www.xs4all.nl/~bsarempt/python/tutorial.html KDE-Python tutorial]
:''A python version of Daniel's KDE tutorial by Boudewijn Rempt.''

=== Ruby ===

;[http://developer.kde.org/language-bindings/ruby/kde3tutorial/index.html KDE Ruby Korundum tutorial]
:''A ruby version of Antonio Larrosa Jiménez's KDE tutorial by Richard Dale. See the [http://developer.kde.org/language-bindings/ruby/index.html Ruby Developers Corner] for Qt tutorials and other info.''

;[[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
:''Trolltech's fabulous introductory tutorial to Qt, translated to Ruby.''

=== Shell ===

;[[Development/Tutorials/Shell_Scripting_with_KDE_Dialogs|Shell Scripting with KDE dialogs]] ([http://developer.kde.org/documentation/tutorials/kdialog-german/t1.html German Version])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to use KDE dialogs in shell scripts with kdialog. It is presented as an example based tutorial.''

== Other tutorials ==

;[http://developer.kde.org/documentation/tutorials/kdeeduplot/kdeeduplot_tutorial.tar.bz2 Using and extending the KDE EDU Plot widget (docbook archive)]
:''This tutorial introduces Jason Harris' KPlotWidget that is part of the KDE EDU package. Contains information about defining your own widget in QT / KDevelop designer and about subclassing widgets and overriding member functions to extend functionality.''

== KDE2 and KDE3 Materials ==

;[[Development/Tutorials/KDE3|KDE3 Tutorials]]
:''These tutorials cover topics related to KDE3.''

;[[Development/Tutorials/KDE2|KDE2 Tutorials]]
:''These tutorials cover topics related to KDE2.''

Development/Tutorials

2007-01-12T03:31:51Z

CuCullin: /* Shell */

Tutorials are the fastest way of finding out what KDE will do for you, and how to do it. Here is a list of currently available tutorials.

== Getting started ==
;[[/Programming Tutorial KDE 4|Introduction To KDE 4 Programming]]
:''You are interested in writing applications with KDE 4? This tutorial series is aimed at those completely new to KDE programming.''

;[[/CMake|Introduction to CMake]]
:''How to use the CMake build system used by KDE4''

;[[/Using Qt Designer|Using Qt Designer to build user interfaces]]
:''How to create UI files with designer, and how to integrate them into a KDE program''

;[[/Command-Line Options|Using Command-line Options]]
:''How to use the KDE Command-line arguments system''

;[[/Debugging|Debugging your application]]
:''Tips, tools and techniques to apply when debugging your KDE application''

;[[Development/Tutorials/Unittests|Writing Unittests for Qt4 and KDE4 with QTestLib]] ([http://developer.kde.org/documentation/tutorials/writingunittests/writingunittests.html Original link])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to write unit tests using the QTestLib framework. It is presented as an example based tutorial, and is still under development.'' '''Does this belong in this section? It's hardly a beginner tutorial.'''

;[[/Code_Checking|Semi-automatic ways to detect code errors]]
:''Techniques you can use to detect errors in KDE code'' '''Maybe this should be put under the Dubugging page? Or maybe both these pages should be put in their own subsection on this page?'''

== Managing Configuration Data With KConfig ==

;[[/Using KConfig XT|Using KConfig XT]]
:''Tutorial on how to efficiently use the KConfig XT framework.''

== File Access With KIO ==

== Localization ==
;[[/Localization/Unicode|101: Unicode]]
:''An introduction to what Unicode is as well as how to handle Unicode data in KDE applications.''

; [[/Localization/i18n|110: Writing Applications With Localization in Mind]]
:''This tutorial covers what localization is, why it's important and how to ensure your application is ready to be localized. A must read for all application developers.''

; [[/Localization/i18n Mistakes|115: Avoiding Common Localization Pitfalls]]
:''There are several common mistakes that prevent applications from being properly localized. Find out what they are and how to easily avoid them in this tutorial.''

; [[/Localization/Building KDE's l10n Module|120: Building KDE's Localization Module]]
:''Building and installing language support from KDE's localization (l10n) module is a good idea for those working on applications in the main KDE repository. Doing so will allow you to test your application in another language and spot problem areas. Learn how to do just that in this tutorial.''

; [[/Localization/i18n Build Systems|200: Incorporating i18n Into the Build System]]
:''Once your application is ready to be localized, the next step is to ensure that translation files are built automatically and kept up to date. This tutorial covers the necessary CMakeFiles.txt additions as well the process of distributing the resulting message catalogs with your application.''

; [[/Localization/i18n Challenges|210: Common i18n Challenges and Solutions]]
:''This tutorial covers challenges that you may eventually run into such as translating handbooks and other data that exists outside of the source code, merging and handling obsolete .po files, deeling with freezes, coding in languages other than English and creating independent releases of or moving applications between KDE modules.''

== Components and Plugins ==

== Application Automation and Scripting ==

=== D-Bus ===
; [[/D-Bus/Introduction|101: Introduction to D-Bus]]
:''A straight-forward introduction to the core concepts in D-Bus from an application developer's perspective, this tutorial covers what D-Bus is and how it can be used by applications.''
; [[/D-Bus/Accessing Interfaces|201: Accessing D-Bus Interfaces]]
:''A step-by-step guide to calling D-Bus methods and connecting to D-Bus signals using QtDBus.''
; [[/D-Bus/Creating Interfaces|211: Creating D-Bus Interfaces]]
:''Learn how to expose functionality in your application by creating and using custom D-Bus interfaces. Covers generating the XML descriptions, instantiating interfaces at run time and setting up the build system with CMake.''
; [[/D-Bus/Autostart Services|300: D-Bus Autostart Services]]
:''Turn your application into a D-Bus autostart service with this tutorial. This D-Bus feature will ensure that even when your application isn't running that D-Bus calls made to it will work by relying on the D-Bus daemon itself to start your app if and when needed.''

=== Konqueror ===
; [[/Creating Konqueror Service Menus|Creating Konqueror Service Menus]]
:''This tutorial shows you how to create mimetype-specific actions in Konqueror's context menu (aka "servicemenus").''

===Kross===
; [[Development/Tutorials/Kross-Tutorial|Kross Tutorial]] ([http://wiki.koffice.org/index.php?title=Kross/Tutorial Original Link])
:''This tutorial explains how to integrate the Kross scripting framework into an application.''

== Search and Metadata ==

; [[/Writing file analyzers|Writing file analyzers]]
:''File analyzers extract data from files to display in the file dialogs and file managers. The data gathered this way is also used to search for files. KDE4 allows the use of multiple analyzers per file type. This tutorial describes how you can write new analyzers.''

== Hardware Awareness ==

;[[/Solid_Tutorials|Introduction to Solid]]
:''An introduction to using the Solid hardware discovery and interaction system in KDE applications.''

;[[/Solid_Network_Tutorial|Accessing Network Information]]
:''How to use the Solid system to get information about the network''

==Printing==

;[[/Printing Hello World|101: Hello World]]
:''Introduction to the KDE printing system''

;TODO 110 Print Dialog
:''Using the KDE print dialog''

== Get Hot New Stuff ==
; [[Development/Tutorials/Introduction to Get Hot New Stuff|Introduction to Get Hot New Stuff]]
:''An introduction to the developer-friendly network update system that allows KDE applications to fetch new application data at runtime in a user friendly manner.''

;[[Development/Tutorials/KNewStuffSecure|KNewStuff Secure]] ([http://developer.kde.org/documentation/tutorials/knewstuffsecure/index.html Original Link])
:''Tutorial showing how to share resources in a secured way (KDE 3.4 and later).'' By András Mantia <amantia@kde.org>.

== Rapid Application Development ==

=== Python ===

;[[Development/Tutorials/101_Python_introduction_to_signal_and_slots|101 Introduction to signal and slots]]
:''A simple introduction to QT's signal and slots architecture.''

;[http://www.xs4all.nl/~bsarempt/python/tutorial.html KDE-Python tutorial]
:''A python version of Daniel's KDE tutorial by Boudewijn Rempt.''

=== Ruby ===

;[http://developer.kde.org/language-bindings/ruby/kde3tutorial/index.html KDE Ruby Korundum tutorial]
:''A ruby version of Antonio Larrosa Jiménez's KDE tutorial by Richard Dale. See the [http://developer.kde.org/language-bindings/ruby/index.html Ruby Developers Corner] for Qt tutorials and other info.''

;[[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
:''Trolltech's fabulous introductory tutorial to Qt, translated to Ruby.''

=== Shell ===

;[[Development/Tutorials/Shell_Scripting_with_KDE_Dialogs|Shell Scripting with KDE dialogs]] ([http://developer.kde.org/documentation/tutorials/kdialog-german/t1.html German Version])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to use KDE dialogs in shell scripts with kdialog. It is presented as an example based tutorial.''

== Other tutorials ==

;[http://developer.kde.org/documentation/tutorials/kdeeduplot/kdeeduplot_tutorial.tar.bz2 Using and extending the KDE EDU Plot widget (docbook archive)]
:''This tutorial introduces Jason Harris' KPlotWidget that is part of the KDE EDU package. Contains information about defining your own widget in QT / KDevelop designer and about subclassing widgets and overriding member functions to extend functionality.''

== KDE2 and KDE3 Materials ==

;[[Development/Tutorials/KDE3|KDE3 Tutorials]]
:''These tutorials cover topics related to KDE3.''

;[[Development/Tutorials/KDE2|KDE2 Tutorials]]
:''These tutorials cover topics related to KDE2.''

Development/Tutorials

2007-01-12T03:29:22Z

CuCullin: /* Get Hot New Stuff */

Tutorials are the fastest way of finding out what KDE will do for you, and how to do it. Here is a list of currently available tutorials.

== Getting started ==
;[[/Programming Tutorial KDE 4|Introduction To KDE 4 Programming]]
:''You are interested in writing applications with KDE 4? This tutorial series is aimed at those completely new to KDE programming.''

;[[/CMake|Introduction to CMake]]
:''How to use the CMake build system used by KDE4''

;[[/Using Qt Designer|Using Qt Designer to build user interfaces]]
:''How to create UI files with designer, and how to integrate them into a KDE program''

;[[/Command-Line Options|Using Command-line Options]]
:''How to use the KDE Command-line arguments system''

;[[/Debugging|Debugging your application]]
:''Tips, tools and techniques to apply when debugging your KDE application''

;[[Development/Tutorials/Unittests|Writing Unittests for Qt4 and KDE4 with QTestLib]] ([http://developer.kde.org/documentation/tutorials/writingunittests/writingunittests.html Original link])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to write unit tests using the QTestLib framework. It is presented as an example based tutorial, and is still under development.'' '''Does this belong in this section? It's hardly a beginner tutorial.'''

;[[/Code_Checking|Semi-automatic ways to detect code errors]]
:''Techniques you can use to detect errors in KDE code'' '''Maybe this should be put under the Dubugging page? Or maybe both these pages should be put in their own subsection on this page?'''

== Managing Configuration Data With KConfig ==

;[[/Using KConfig XT|Using KConfig XT]]
:''Tutorial on how to efficiently use the KConfig XT framework.''

== File Access With KIO ==

== Localization ==
;[[/Localization/Unicode|101: Unicode]]
:''An introduction to what Unicode is as well as how to handle Unicode data in KDE applications.''

; [[/Localization/i18n|110: Writing Applications With Localization in Mind]]
:''This tutorial covers what localization is, why it's important and how to ensure your application is ready to be localized. A must read for all application developers.''

; [[/Localization/i18n Mistakes|115: Avoiding Common Localization Pitfalls]]
:''There are several common mistakes that prevent applications from being properly localized. Find out what they are and how to easily avoid them in this tutorial.''

; [[/Localization/Building KDE's l10n Module|120: Building KDE's Localization Module]]
:''Building and installing language support from KDE's localization (l10n) module is a good idea for those working on applications in the main KDE repository. Doing so will allow you to test your application in another language and spot problem areas. Learn how to do just that in this tutorial.''

; [[/Localization/i18n Build Systems|200: Incorporating i18n Into the Build System]]
:''Once your application is ready to be localized, the next step is to ensure that translation files are built automatically and kept up to date. This tutorial covers the necessary CMakeFiles.txt additions as well the process of distributing the resulting message catalogs with your application.''

; [[/Localization/i18n Challenges|210: Common i18n Challenges and Solutions]]
:''This tutorial covers challenges that you may eventually run into such as translating handbooks and other data that exists outside of the source code, merging and handling obsolete .po files, deeling with freezes, coding in languages other than English and creating independent releases of or moving applications between KDE modules.''

== Components and Plugins ==

== Application Automation and Scripting ==

=== D-Bus ===
; [[/D-Bus/Introduction|101: Introduction to D-Bus]]
:''A straight-forward introduction to the core concepts in D-Bus from an application developer's perspective, this tutorial covers what D-Bus is and how it can be used by applications.''
; [[/D-Bus/Accessing Interfaces|201: Accessing D-Bus Interfaces]]
:''A step-by-step guide to calling D-Bus methods and connecting to D-Bus signals using QtDBus.''
; [[/D-Bus/Creating Interfaces|211: Creating D-Bus Interfaces]]
:''Learn how to expose functionality in your application by creating and using custom D-Bus interfaces. Covers generating the XML descriptions, instantiating interfaces at run time and setting up the build system with CMake.''
; [[/D-Bus/Autostart Services|300: D-Bus Autostart Services]]
:''Turn your application into a D-Bus autostart service with this tutorial. This D-Bus feature will ensure that even when your application isn't running that D-Bus calls made to it will work by relying on the D-Bus daemon itself to start your app if and when needed.''

=== Konqueror ===
; [[/Creating Konqueror Service Menus|Creating Konqueror Service Menus]]
:''This tutorial shows you how to create mimetype-specific actions in Konqueror's context menu (aka "servicemenus").''

===Kross===
; [[Development/Tutorials/Kross-Tutorial|Kross Tutorial]] ([http://wiki.koffice.org/index.php?title=Kross/Tutorial Original Link])
:''This tutorial explains how to integrate the Kross scripting framework into an application.''

== Search and Metadata ==

; [[/Writing file analyzers|Writing file analyzers]]
:''File analyzers extract data from files to display in the file dialogs and file managers. The data gathered this way is also used to search for files. KDE4 allows the use of multiple analyzers per file type. This tutorial describes how you can write new analyzers.''

== Hardware Awareness ==

;[[/Solid_Tutorials|Introduction to Solid]]
:''An introduction to using the Solid hardware discovery and interaction system in KDE applications.''

;[[/Solid_Network_Tutorial|Accessing Network Information]]
:''How to use the Solid system to get information about the network''

==Printing==

;[[/Printing Hello World|101: Hello World]]
:''Introduction to the KDE printing system''

;TODO 110 Print Dialog
:''Using the KDE print dialog''

== Get Hot New Stuff ==
; [[Development/Tutorials/Introduction to Get Hot New Stuff|Introduction to Get Hot New Stuff]]
:''An introduction to the developer-friendly network update system that allows KDE applications to fetch new application data at runtime in a user friendly manner.''

;[[Development/Tutorials/KNewStuffSecure|KNewStuff Secure]] ([http://developer.kde.org/documentation/tutorials/knewstuffsecure/index.html Original Link])
:''Tutorial showing how to share resources in a secured way (KDE 3.4 and later).'' By András Mantia <amantia@kde.org>.

== Rapid Application Development ==

=== Python ===

;[[Development/Tutorials/101_Python_introduction_to_signal_and_slots|101 Introduction to signal and slots]]
:''A simple introduction to QT's signal and slots architecture.''

;[http://www.xs4all.nl/~bsarempt/python/tutorial.html KDE-Python tutorial]
:''A python version of Daniel's KDE tutorial by Boudewijn Rempt.''

=== Ruby ===

;[http://developer.kde.org/language-bindings/ruby/kde3tutorial/index.html KDE Ruby Korundum tutorial]
:''A ruby version of Antonio Larrosa Jiménez's KDE tutorial by Richard Dale. See the [http://developer.kde.org/language-bindings/ruby/index.html Ruby Developers Corner] for Qt tutorials and other info.''

;[[Development/Tutorials/Qt4_Ruby_Tutorial|Qt4 Ruby Tutorial]]
:''Trolltech's fabulous introductory tutorial to Qt, translated to Ruby.''

=== Shell ===

;[http://developer.kde.org/documentation/tutorials/kdialog/t1.html Shell Scripting with KDE dialogs] ([http://developer.kde.org/documentation/tutorials/kdialog-german/t1.html German Version])
:''Tutorial by [mailto:bradh@frogmouth.net Brad Hards] that describes how to use KDE dialogs in shell scripts with kdialog. It is presented as an example based tutorial.''

== Other tutorials ==

;[http://developer.kde.org/documentation/tutorials/kdeeduplot/kdeeduplot_tutorial.tar.bz2 Using and extending the KDE EDU Plot widget (docbook archive)]
:''This tutorial introduces Jason Harris' KPlotWidget that is part of the KDE EDU package. Contains information about defining your own widget in QT / KDevelop designer and about subclassing widgets and overriding member functions to extend functionality.''

== KDE2 and KDE3 Materials ==

;[[Development/Tutorials/KDE3|KDE3 Tutorials]]
:''These tutorials cover topics related to KDE3.''

;[[Development/Tutorials/KDE2|KDE2 Tutorials]]
:''These tutorials cover topics related to KDE2.''

Development/Tutorials/Introduction to Get Hot New Stuff

2007-01-12T03:26:05Z

CuCullin: /* Preparations */

== Introduction ==
Similar to how programming languages shifted focus from algorithms to data structures in the 70s, desktop application development emphasizes more and more on user data, i.e. data intentionally produced or consumed by the user. Both on the internet and in corporate intranets, sharing this data is considered an easy way to customize desktops and to advertise one's creativity. The 'Get Hot New Stuff' (GHNS) framework in KDE exists to support this approach, and the KNewStuff library is the key for application authors to enable GHNS.

== Preparations ==
The first steps are usually made in preparing the usage of KNewStuff. For this matter, the library must be available (a task which could be done using autoconf, but since it's part of kdelibs, we simply assume it's available with any recent KDE installation.) Authors of 3rd pary applications can ensure the availability as part of kdepim-libs in KDE 3.2 using the AC_KNEWSTUFF macro. It must also be included in the set of libraries against which the application is linked, so modifying the Makefile.am and reconfiguring the application are to be done.

<code>
bin_PROGRAMS = myapp
myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff
</code>

The header files are installed under $kdedir/include/knewstuff/, so in the relevant files, they're included with statements such as:

<code>
#include <knewstuff/downloaddialog.h>
</code>

The following header files are provided by KNewStuff:
* downloaddialog.h: Easy to use download dialog
* engine.h: Access to the complex, but customizable background operations
* entry.h: (internal) Data fields of entries, such as Author or Title
* ghns.h: [not installed]
* knewstuffgeneric.h: Easy to use installation handler for the downloaded files
* knewstuff.h: Main knewstuff functionality
* providerdialog.h: Preconfigured dialog for provider selection
* provider.h: Provider entries, and ProviderLoader
* testnewstuff.h: [not installed]
* uploaddialog.h: Easy to use upload dialog

For more information on the background processes, please have a look at the information provided by [http://www.kstuff.org/docs/ kstuff.org]. However application authors should only need a basic understanding of those.

== Downloading Data ==

Depending on the application, providing additional data can be accomplished using the 'File Import' dialog, 'Internet Level' menu item, or just an 'Update now' KAction. All of those have in common that they invoke a slot which will contain the actual KNewStuff calls.

<code>
void MyApp::slotDownload()
{
KNewStuff::DownloadDialog::open("myapp/templates");
}
</code>

This is all. If desired, more control can be exercised on the whole download process, as outlined below. For the beginning, the above is already fully functional, and should be used at first.

== Downloading in Detail ==
The example above implicitely constructs an internal Engine object, retrieves the directory list, fetches the provider lists specified in the directory, and the entries in each of the provider lists, compares them to the data files previously installed, and displays them in the download dialog. This dialog in turn handles all the installation issues. Of course there is no magic involved, and for more control about the subtasks, the following is recommended:

<code>
(to be precised)
</code>

== Installation ==

Similar to the provider list, the installation procedures are described in the application's configuration file. The default (if these entries are missing) is to just download the file to a temporary location, which is not useful in most of the cases. There are two entries: target location, and post-installation command. The target location can either be StandardResource, matching the KDE resource types, or TargetDir, matching an application directory under $KDEHOME/share/apps/appname. The post installation command can be a binary with '%f' as parameter (note the single quotes to prevent string format attacks), but it can as well be a DCOP call, so the application can directly work with the data.

<code>
[KNewStuff]
StandardResource=wallpaper
InstallationCommand=dcop kdesktop KBackgroundIface setWallpaper '%f' 2

TargetDir=kamikaze
</code>

== Uploads ==

The beginning of the upload process works similar to downloads. A MasterServer or ProvidersUrl is used to retrieve the provider list, and one of the providers is selected by the user. Only providers which allow uploads are taken into account. After this selection however, the differences begin. The user has to fill in the necessary information such as title, author name or version number into the upload dialog. Also, the payload and preview files have to be selected, this however will in most cases be the application's task. In Kamikaze, the level file is pre-rendered to an invisible QCanvas, and the resulting graphics is minimized and automatically specified for the upload. The upload will then happen using the protocol accepted by the provider, which in most cases will be anonymous FTP.

<code>
#include <knewstuff/knewstuffgeneric.h>
#include <knewstuff/engine.h>
#include <knewstuff/uploaddialog.h>
// ...
QString file, previewfile;
KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this);
ns->upload(file.name(), previewfile.name());
</code>

== Conclusion ==

Sharing creativity should become a default property of modern desktops, and KDE once again leads the pack by providing both upload and download facilities. If enough applications of different areas make use of them, it helps users to be more productive and have more fun with their computer.

Development/Tutorials/Introduction to Get Hot New Stuff

2007-01-12T03:25:11Z

CuCullin: /* Preparations */

== Introduction ==
Similar to how programming languages shifted focus from algorithms to data structures in the 70s, desktop application development emphasizes more and more on user data, i.e. data intentionally produced or consumed by the user. Both on the internet and in corporate intranets, sharing this data is considered an easy way to customize desktops and to advertise one's creativity. The 'Get Hot New Stuff' (GHNS) framework in KDE exists to support this approach, and the KNewStuff library is the key for application authors to enable GHNS.

== Preparations ==
The first steps are usually made in preparing the usage of KNewStuff. For this matter, the library must be available (a task which could be done using autoconf, but since it's part of kdelibs, we simply assume it's available with any recent KDE installation.) Authors of 3rd pary applications can ensure the availability as part of kdepim-libs in KDE 3.2 using the AC_KNEWSTUFF macro. It must also be included in the set of libraries against which the application is linked, so modifying the Makefile.am and reconfiguring the application are to be done.

<code>
bin_PROGRAMS = myapp
myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff
</code>

The header files are installed under $kdedir/include/knewstuff/, so in the relevant files, they're included with statements such as:

<code>
#include <knewstuff/downloaddialog.h>
</code>

The following header files are provided by KNewStuff:
* downloaddialog.h: Easy to use download dialog
* engine.h: Access to the complex, but customizable background operations
* entry.h: (internal) Data fields of entries, such as Author or Title
* ghns.h: [not installed]
* knewstuffgeneric.h: Easy to use installation handler for the downloaded files
* knewstuff.h: Main knewstuff functionality
* providerdialog.h: Preconfigured dialog for provider selection
* provider.h: Provider entries, and ProviderLoader
* testnewstuff.h: [not installed]
* uploaddialog.h: Easy to use upload dialog

For more information on the background processes, please have a look at the information provided by [http://www.kstuff.org/docs/ kstuff.org]. However application authors should only need a basic understanding of those.

== Downloading Data ==

Depending on the application, providing additional data can be accomplished using the 'File Import' dialog, 'Internet Level' menu item, or just an 'Update now' KAction. All of those have in common that they invoke a slot which will contain the actual KNewStuff calls.

<code>
void MyApp::slotDownload()
{
KNewStuff::DownloadDialog::open("myapp/templates");
}
</code>

This is all. If desired, more control can be exercised on the whole download process, as outlined below. For the beginning, the above is already fully functional, and should be used at first.

== Downloading in Detail ==
The example above implicitely constructs an internal Engine object, retrieves the directory list, fetches the provider lists specified in the directory, and the entries in each of the provider lists, compares them to the data files previously installed, and displays them in the download dialog. This dialog in turn handles all the installation issues. Of course there is no magic involved, and for more control about the subtasks, the following is recommended:

<code>
(to be precised)
</code>

== Installation ==

Similar to the provider list, the installation procedures are described in the application's configuration file. The default (if these entries are missing) is to just download the file to a temporary location, which is not useful in most of the cases. There are two entries: target location, and post-installation command. The target location can either be StandardResource, matching the KDE resource types, or TargetDir, matching an application directory under $KDEHOME/share/apps/appname. The post installation command can be a binary with '%f' as parameter (note the single quotes to prevent string format attacks), but it can as well be a DCOP call, so the application can directly work with the data.

<code>
[KNewStuff]
StandardResource=wallpaper
InstallationCommand=dcop kdesktop KBackgroundIface setWallpaper '%f' 2

TargetDir=kamikaze
</code>

== Uploads ==

The beginning of the upload process works similar to downloads. A MasterServer or ProvidersUrl is used to retrieve the provider list, and one of the providers is selected by the user. Only providers which allow uploads are taken into account. After this selection however, the differences begin. The user has to fill in the necessary information such as title, author name or version number into the upload dialog. Also, the payload and preview files have to be selected, this however will in most cases be the application's task. In Kamikaze, the level file is pre-rendered to an invisible QCanvas, and the resulting graphics is minimized and automatically specified for the upload. The upload will then happen using the protocol accepted by the provider, which in most cases will be anonymous FTP.

<code>
#include <knewstuff/knewstuffgeneric.h>
#include <knewstuff/engine.h>
#include <knewstuff/uploaddialog.h>
// ...
QString file, previewfile;
KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this);
ns->upload(file.name(), previewfile.name());
</code>

== Conclusion ==

Sharing creativity should become a default property of modern desktops, and KDE once again leads the pack by providing both upload and download facilities. If enough applications of different areas make use of them, it helps users to be more productive and have more fun with their computer.

Development/Tutorials/Introduction to Get Hot New Stuff

2007-01-12T03:24:15Z

CuCullin:

== Introduction ==
Similar to how programming languages shifted focus from algorithms to data structures in the 70s, desktop application development emphasizes more and more on user data, i.e. data intentionally produced or consumed by the user. Both on the internet and in corporate intranets, sharing this data is considered an easy way to customize desktops and to advertise one's creativity. The 'Get Hot New Stuff' (GHNS) framework in KDE exists to support this approach, and the KNewStuff library is the key for application authors to enable GHNS.

== Preparations ==
The first steps are usually made in preparing the usage of KNewStuff. For this matter, the library must be available (a task which could be done using autoconf, but since it's part of kdelibs, we simply assume it's available with any recent KDE installation.) Authors of 3rd pary applications can ensure the availability as part of kdepim-libs in KDE 3.2 using the AC_KNEWSTUFF macro. It must also be included in the set of libraries against which the application is linked, so modifying the Makefile.am and reconfiguring the application are to be done.

<code>
bin_PROGRAMS = myapp
myapp_LDADD = $(LIB_KDECORE) ... -lknewstuff
</code>

The header files are installed under $kdedir/include/knewstuff/, so in the relevant files, they're included with statements such as:

<code>
#include <knewstuff/downloaddialog.h>
</code>

The following header files are provided by KNewStuff:
* downloaddialog.h: Easy to use download dialog
* engine.h: Access to the complex, but customizable background operations
* entry.h: (internal) Data fields of entries, such as Author or Title
* ghns.h: [not installed]
* knewstuffgeneric.h: Easy to use installation handler for the downloaded files
* knewstuff.h: Main knewstuff functionality
* providerdialog.h: Preconfigured dialog for provider selection
* provider.h: Provider entries, and ProviderLoader
* testnewstuff.h: [not installed]
* uploaddialog.h: Easy to use upload dialog

For more information on the background processes, please have a look at the information provided by [http://www.kstuff.org/docs/ kstuff.org]. However application authors should only need a basic understanding of those.

== Downloading Data ==

Depending on the application, providing additional data can be accomplished using the 'File Import' dialog, 'Internet Level' menu item, or just an 'Update now' KAction. All of those have in common that they invoke a slot which will contain the actual KNewStuff calls.

<code>
void MyApp::slotDownload()
{
KNewStuff::DownloadDialog::open("myapp/templates");
}
</code>

This is all. If desired, more control can be exercised on the whole download process, as outlined below. For the beginning, the above is already fully functional, and should be used at first.

== Downloading in Detail ==
The example above implicitely constructs an internal Engine object, retrieves the directory list, fetches the provider lists specified in the directory, and the entries in each of the provider lists, compares them to the data files previously installed, and displays them in the download dialog. This dialog in turn handles all the installation issues. Of course there is no magic involved, and for more control about the subtasks, the following is recommended:

<code>
(to be precised)
</code>

== Installation ==

Similar to the provider list, the installation procedures are described in the application's configuration file. The default (if these entries are missing) is to just download the file to a temporary location, which is not useful in most of the cases. There are two entries: target location, and post-installation command. The target location can either be StandardResource, matching the KDE resource types, or TargetDir, matching an application directory under $KDEHOME/share/apps/appname. The post installation command can be a binary with '%f' as parameter (note the single quotes to prevent string format attacks), but it can as well be a DCOP call, so the application can directly work with the data.

<code>
[KNewStuff]
StandardResource=wallpaper
InstallationCommand=dcop kdesktop KBackgroundIface setWallpaper '%f' 2

TargetDir=kamikaze
</code>

== Uploads ==

The beginning of the upload process works similar to downloads. A MasterServer or ProvidersUrl is used to retrieve the provider list, and one of the providers is selected by the user. Only providers which allow uploads are taken into account. After this selection however, the differences begin. The user has to fill in the necessary information such as title, author name or version number into the upload dialog. Also, the payload and preview files have to be selected, this however will in most cases be the application's task. In Kamikaze, the level file is pre-rendered to an invisible QCanvas, and the resulting graphics is minimized and automatically specified for the upload. The upload will then happen using the protocol accepted by the provider, which in most cases will be anonymous FTP.

<code>
#include <knewstuff/knewstuffgeneric.h>
#include <knewstuff/engine.h>
#include <knewstuff/uploaddialog.h>
// ...
QString file, previewfile;
KNewStuffGeneric *ns = new KNewStuffGeneric("myapp/templates", this);
ns->upload(file.name(), previewfile.name());
</code>

== Conclusion ==

Sharing creativity should become a default property of modern desktops, and KDE once again leads the pack by providing both upload and download facilities. If enough applications of different areas make use of them, it helps users to be more productive and have more fun with their computer.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T03:15:50Z

CuCullin: /* Progress Dialogs */

{{Improve}}
Original - http://developer.kde.org/documentation/tutorials/kdialog/t1.html

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.

--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.

Example 11. --passivepopup dialog box
<code>
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
</code>

Figure 6. --passivepopup dialog box screenshot

=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.

A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.

Example 12. --yesno message box
<code>
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
</code>

Figure 7. --yesno message box screenshot

A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.

Example 13. --warningyesno message box
<code>
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
</code>

Figure 8. --warningyesno warning screenshot

A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.

Example 14. --warningcontinuecancel message box
<code>
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
</code>

Figure 9. --warningcontinuecancel warning screenshot

Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.

Example 15. --yesnocancel message box
<code>
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
/code>

Figure 10. --yesnocancel message box screenshot

There is also a --warningyesnocancel variation, as shown below.

Example 16. --warningyesnocancel message box
<code>
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
</code>

Figure 11. --warningyesnocancel message box screenshot

The return value ($?) from all these dialog boxes follows a common pattern. A ''Yes'', ''OK'' or ''Continue'' returns '''0'''. A ''No'' returns '''1'''. A ''Cancel'' returns '''2'''.

=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.

The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.

As an example, consider an information level message box for display of a file missing message.

Example 17. Information level message box, with --dontagain
<code>
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
</code>

Figure 12. Information level message box, with --dontagain, screenshot

As noted above, an entry is written to a file when the user selects the checkbox.

Example 18. --dontagain file listing
<code>
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
</code>

The effect of this entry is to suppress future display of dialogs using that filename. In the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.

=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.

The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.

Example 19. --inputbox dialog box
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
</code>

Figure 13. --inputbox dialog box screenshot

Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:

Example 20. --inputbox dialog box with default parameter
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
</code>

Figure 14. --inputbox dialog box screenshot showing default text

The return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses ''Cancel'', no output is sent.

=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.

Example 21. --textbox dialog box
<code>
kdialog --textbox Makefile
</code>

Figure 15. --textbox dialog box

Example 22. --textbox dialog box with dimensions
<code>
kdialog --textbox Makefile 440 200
</code>

Figure 16. --textbox dialog box with dimensions

=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.

Example 23. --menu dialog box
<code>kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
</code>

Figure 17. --menu dialog box

If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.

As with the other examples we've seen, the return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.

Example 24. --checklist dialog box
<code>
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
</code>

Figure 18. --checklist dialog box

Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the ''--separate-output'' to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.

Example 25. --checklist dialog box
<code>
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
</code>

As for the menu example, the return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:

Example 26. --checklist dialog box
<code>
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
</code>

Figure 19. --checklist dialog box

Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.

A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:

Example 27. --combobox dialog box
<code>
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
</code>

Figure 20. --combobox dialog box

=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.

The dialog to select a file to open is invoked with ''--getopenfilename'' or ''--getopenurl''. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:

Example 28. --getopenfilename dialog box
<code>
kdialog --getopenfilename .
</code>

Figure 21. --getopenfilename dialog box

As for previous examples, the return value depends on the button used. ''OK'' returns '''0'''. Cancel returns '''1'''.

As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:

Example 29. --getopenfilename dialog box
<code>
[watson@bakerst]$ kdialog --getopenfilename .
/home/watson/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[watson@bakerst]$ kdialog --getopenurl .
file:/home/watson/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
</code>

Note that the user can only select an existing file with these options. When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:

Example 30. --getopenfilename dialog box with directory support
<code>
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
</code>

Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.

Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labeling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:

Example 31. --getopenfilename dialog box with MIME filter
<code>
kdialog --getopenfilename ~/doc/ethereal-userguide "image/png text/html text/plain"
</code>

Figure 22. --getopenfilename dialog box with MIME filter

If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:

Example 32. --getopenfilename dialog box with wildcard filter
<code>
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
</code>

Figure 23. --getopenfilename dialog box with wildcard filter

The ''--getsavefilename'' and ''--getsaveurl'' commands are directly analogous to the file opening dialogs. A simple example is shown below:

Example 33. --getsavefilename dialog box
<code>
kdialog --getsavefilename .
</code>

Figure 24. --getsavefilename dialog box

Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist. As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:

Example 34. --getsavefilename dialog box with filter
<code>
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
</code>

Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the ''--getexistingdirectory'' type, as shown below:

Example 35. --getexistingdirectory dialog box
<code>
kdialog --getexistingdirectory .
</code>

Figure 25. --getexistingdirectory dialog box

''--getexistingdirectory'' does not provide any filtering, but it does provide the same starting directory options, including the colon notation.

=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.

Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.

A simple use of the ''--progressbar'' command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.

Example 36. --progressbar dialog box example
<code>
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
</code>

Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.

Example 37. --progressbar dialog box example, with Cancel
<code>
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true
3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done
8 dcop $dcopRef close
</code>

As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.

Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T03:14:08Z

CuCullin: /* File Selection Dialogs */

{{Improve}}
Original - http://developer.kde.org/documentation/tutorials/kdialog/t1.html

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.

--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.

Example 11. --passivepopup dialog box
<code>
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
</code>

Figure 6. --passivepopup dialog box screenshot

=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.

A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.

Example 12. --yesno message box
<code>
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
</code>

Figure 7. --yesno message box screenshot

A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.

Example 13. --warningyesno message box
<code>
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
</code>

Figure 8. --warningyesno warning screenshot

A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.

Example 14. --warningcontinuecancel message box
<code>
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
</code>

Figure 9. --warningcontinuecancel warning screenshot

Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.

Example 15. --yesnocancel message box
<code>
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
/code>

Figure 10. --yesnocancel message box screenshot

There is also a --warningyesnocancel variation, as shown below.

Example 16. --warningyesnocancel message box
<code>
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
</code>

Figure 11. --warningyesnocancel message box screenshot

The return value ($?) from all these dialog boxes follows a common pattern. A ''Yes'', ''OK'' or ''Continue'' returns '''0'''. A ''No'' returns '''1'''. A ''Cancel'' returns '''2'''.

=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.

The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.

As an example, consider an information level message box for display of a file missing message.

Example 17. Information level message box, with --dontagain
<code>
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
</code>

Figure 12. Information level message box, with --dontagain, screenshot

As noted above, an entry is written to a file when the user selects the checkbox.

Example 18. --dontagain file listing
<code>
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
</code>

The effect of this entry is to suppress future display of dialogs using that filename. In the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.

=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.

The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.

Example 19. --inputbox dialog box
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
</code>

Figure 13. --inputbox dialog box screenshot

Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:

Example 20. --inputbox dialog box with default parameter
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
</code>

Figure 14. --inputbox dialog box screenshot showing default text

The return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses ''Cancel'', no output is sent.

=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.

Example 21. --textbox dialog box
<code>
kdialog --textbox Makefile
</code>

Figure 15. --textbox dialog box

Example 22. --textbox dialog box with dimensions
<code>
kdialog --textbox Makefile 440 200
</code>

Figure 16. --textbox dialog box with dimensions

=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.

Example 23. --menu dialog box
<code>kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
</code>

Figure 17. --menu dialog box

If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.

As with the other examples we've seen, the return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.

Example 24. --checklist dialog box
<code>
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
</code>

Figure 18. --checklist dialog box

Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the ''--separate-output'' to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.

Example 25. --checklist dialog box
<code>
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
</code>

As for the menu example, the return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:

Example 26. --checklist dialog box
<code>
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
</code>

Figure 19. --checklist dialog box

Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.

A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:

Example 27. --combobox dialog box
<code>
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
</code>

Figure 20. --combobox dialog box

=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.

The dialog to select a file to open is invoked with ''--getopenfilename'' or ''--getopenurl''. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:

Example 28. --getopenfilename dialog box
<code>
kdialog --getopenfilename .
</code>

Figure 21. --getopenfilename dialog box

As for previous examples, the return value depends on the button used. ''OK'' returns '''0'''. Cancel returns '''1'''.

As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:

Example 29. --getopenfilename dialog box
<code>
[watson@bakerst]$ kdialog --getopenfilename .
/home/watson/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[watson@bakerst]$ kdialog --getopenurl .
file:/home/watson/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
</code>

Note that the user can only select an existing file with these options. When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:

Example 30. --getopenfilename dialog box with directory support
<code>
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
</code>

Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.

Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labeling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:

Example 31. --getopenfilename dialog box with MIME filter
<code>
kdialog --getopenfilename ~/doc/ethereal-userguide "image/png text/html text/plain"
</code>

Figure 22. --getopenfilename dialog box with MIME filter

If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:

Example 32. --getopenfilename dialog box with wildcard filter
<code>
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
</code>

Figure 23. --getopenfilename dialog box with wildcard filter

The ''--getsavefilename'' and ''--getsaveurl'' commands are directly analogous to the file opening dialogs. A simple example is shown below:

Example 33. --getsavefilename dialog box
<code>
kdialog --getsavefilename .
</code>

Figure 24. --getsavefilename dialog box

Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist. As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:

Example 34. --getsavefilename dialog box with filter
<code>
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
</code>

Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the ''--getexistingdirectory'' type, as shown below:

Example 35. --getexistingdirectory dialog box
<code>
kdialog --getexistingdirectory .
</code>

Figure 25. --getexistingdirectory dialog box

''--getexistingdirectory'' does not provide any filtering, but it does provide the same starting directory options, including the colon notation.

=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T03:08:53Z

CuCullin: /* Menu and Selection Dialogs */

{{Improve}}
Original - http://developer.kde.org/documentation/tutorials/kdialog/t1.html

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.

--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.

Example 11. --passivepopup dialog box
<code>
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
</code>

Figure 6. --passivepopup dialog box screenshot

=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.

A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.

Example 12. --yesno message box
<code>
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
</code>

Figure 7. --yesno message box screenshot

A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.

Example 13. --warningyesno message box
<code>
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
</code>

Figure 8. --warningyesno warning screenshot

A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.

Example 14. --warningcontinuecancel message box
<code>
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
</code>

Figure 9. --warningcontinuecancel warning screenshot

Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.

Example 15. --yesnocancel message box
<code>
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
/code>

Figure 10. --yesnocancel message box screenshot

There is also a --warningyesnocancel variation, as shown below.

Example 16. --warningyesnocancel message box
<code>
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
</code>

Figure 11. --warningyesnocancel message box screenshot

The return value ($?) from all these dialog boxes follows a common pattern. A ''Yes'', ''OK'' or ''Continue'' returns '''0'''. A ''No'' returns '''1'''. A ''Cancel'' returns '''2'''.

=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.

The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.

As an example, consider an information level message box for display of a file missing message.

Example 17. Information level message box, with --dontagain
<code>
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
</code>

Figure 12. Information level message box, with --dontagain, screenshot

As noted above, an entry is written to a file when the user selects the checkbox.

Example 18. --dontagain file listing
<code>
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
</code>

The effect of this entry is to suppress future display of dialogs using that filename. In the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.

=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.

The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.

Example 19. --inputbox dialog box
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
</code>

Figure 13. --inputbox dialog box screenshot

Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:

Example 20. --inputbox dialog box with default parameter
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
</code>

Figure 14. --inputbox dialog box screenshot showing default text

The return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses ''Cancel'', no output is sent.

=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.

Example 21. --textbox dialog box
<code>
kdialog --textbox Makefile
</code>

Figure 15. --textbox dialog box

Example 22. --textbox dialog box with dimensions
<code>
kdialog --textbox Makefile 440 200
</code>

Figure 16. --textbox dialog box with dimensions

=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.

Example 23. --menu dialog box
<code>kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
</code>

Figure 17. --menu dialog box

If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.

As with the other examples we've seen, the return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.

Example 24. --checklist dialog box
<code>
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
</code>

Figure 18. --checklist dialog box

Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the ''--separate-output'' to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.

Example 25. --checklist dialog box
<code>
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
</code>

As for the menu example, the return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:

Example 26. --checklist dialog box
<code>
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
</code>

Figure 19. --checklist dialog box

Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.

A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:

Example 27. --combobox dialog box
<code>
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
</code>

Figure 20. --combobox dialog box

=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
Example 28. --getopenfilename dialog box
kdialog --getopenfilename .
Figure 21. --getopenfilename dialog box
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 29. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename .
/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[bradh@rachel kdialog]$ kdialog --getopenurl .
file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 30. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 31. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain"
Figure 22. --getopenfilename dialog box with MIME filter
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 32. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
Figure 23. --getopenfilename dialog box with wildcard filter
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Example 33. --getsavefilename dialog box
kdialog --getsavefilename .
Figure 24. --getsavefilename dialog box
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 34. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
Example 35. --getexistingdirectory dialog box
kdialog --getexistingdirectory .
Figure 25. --getexistingdirectory dialog box
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.
=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:57:11Z

CuCullin: /* Displaying files */

{{Improve}}
Original - http://developer.kde.org/documentation/tutorials/kdialog/t1.html

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.

--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.

Example 11. --passivepopup dialog box
<code>
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
</code>

Figure 6. --passivepopup dialog box screenshot

=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.

A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.

Example 12. --yesno message box
<code>
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
</code>

Figure 7. --yesno message box screenshot

A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.

Example 13. --warningyesno message box
<code>
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
</code>

Figure 8. --warningyesno warning screenshot

A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.

Example 14. --warningcontinuecancel message box
<code>
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
</code>

Figure 9. --warningcontinuecancel warning screenshot

Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.

Example 15. --yesnocancel message box
<code>
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
/code>

Figure 10. --yesnocancel message box screenshot

There is also a --warningyesnocancel variation, as shown below.

Example 16. --warningyesnocancel message box
<code>
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
</code>

Figure 11. --warningyesnocancel message box screenshot

The return value ($?) from all these dialog boxes follows a common pattern. A ''Yes'', ''OK'' or ''Continue'' returns '''0'''. A ''No'' returns '''1'''. A ''Cancel'' returns '''2'''.

=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.

The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.

As an example, consider an information level message box for display of a file missing message.

Example 17. Information level message box, with --dontagain
<code>
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
</code>

Figure 12. Information level message box, with --dontagain, screenshot

As noted above, an entry is written to a file when the user selects the checkbox.

Example 18. --dontagain file listing
<code>
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
</code>

The effect of this entry is to suppress future display of dialogs using that filename. In the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.

=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.

The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.

Example 19. --inputbox dialog box
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
</code>

Figure 13. --inputbox dialog box screenshot

Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:

Example 20. --inputbox dialog box with default parameter
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
</code>

Figure 14. --inputbox dialog box screenshot showing default text

The return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses ''Cancel'', no output is sent.

=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.

Example 21. --textbox dialog box
<code>
kdialog --textbox Makefile
</code>

Figure 15. --textbox dialog box

Example 22. --textbox dialog box with dimensions
<code>
kdialog --textbox Makefile 440 200
</code>

Figure 16. --textbox dialog box with dimensions

=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.
Example 23. --menu dialog box
kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
Figure 17. --menu dialog box
If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.
As with the other examples we've seen, the return value depends on the button used. OK returns zero. Cancel returns one.
A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.
Example 24. --checklist dialog box
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
Figure 18. --checklist dialog box
Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the --separate-output to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.
Example 25. --checklist dialog box
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
As for the menu example, the return value depends on the button used. OK returns zero. Cancel returns one.
The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:
Example 26. --checklist dialog box
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
Figure 19. --checklist dialog box
Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.
A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:
Example 27. --combobox dialog box
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
Figure 20. --combobox dialog box
=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
Example 28. --getopenfilename dialog box
kdialog --getopenfilename .
Figure 21. --getopenfilename dialog box
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 29. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename .
/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[bradh@rachel kdialog]$ kdialog --getopenurl .
file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 30. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 31. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain"
Figure 22. --getopenfilename dialog box with MIME filter
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 32. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
Figure 23. --getopenfilename dialog box with wildcard filter
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Example 33. --getsavefilename dialog box
kdialog --getsavefilename .
Figure 24. --getsavefilename dialog box
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 34. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
Example 35. --getexistingdirectory dialog box
kdialog --getexistingdirectory .
Figure 25. --getexistingdirectory dialog box
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.
=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:56:02Z

CuCullin:

{{Improve}}
Original - http://developer.kde.org/documentation/tutorials/kdialog/t1.html

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.

--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.

Example 11. --passivepopup dialog box
<code>
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
</code>

Figure 6. --passivepopup dialog box screenshot

=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.

A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.

Example 12. --yesno message box
<code>
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
</code>

Figure 7. --yesno message box screenshot

A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.

Example 13. --warningyesno message box
<code>
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
</code>

Figure 8. --warningyesno warning screenshot

A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.

Example 14. --warningcontinuecancel message box
<code>
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
</code>

Figure 9. --warningcontinuecancel warning screenshot

Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.

Example 15. --yesnocancel message box
<code>
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
/code>

Figure 10. --yesnocancel message box screenshot

There is also a --warningyesnocancel variation, as shown below.

Example 16. --warningyesnocancel message box
<code>
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
</code>

Figure 11. --warningyesnocancel message box screenshot

The return value ($?) from all these dialog boxes follows a common pattern. A ''Yes'', ''OK'' or ''Continue'' returns '''0'''. A ''No'' returns '''1'''. A ''Cancel'' returns '''2'''.

=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.

The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.

As an example, consider an information level message box for display of a file missing message.

Example 17. Information level message box, with --dontagain
<code>
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
</code>

Figure 12. Information level message box, with --dontagain, screenshot

As noted above, an entry is written to a file when the user selects the checkbox.

Example 18. --dontagain file listing
<code>
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
</code>

The effect of this entry is to suppress future display of dialogs using that filename. In the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.

=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.

The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.

Example 19. --inputbox dialog box
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
</code>

Figure 13. --inputbox dialog box screenshot

Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:

Example 20. --inputbox dialog box with default parameter
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
</code>

Figure 14. --inputbox dialog box screenshot showing default text

The return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses ''Cancel'', no output is sent.

=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.
Example 21. --textbox dialog box
kdialog --textbox Makefile
Figure 15. --textbox dialog box
Example 22. --textbox dialog box with dimensions
kdialog --textbox Makefile 440 200
Figure 16. --textbox dialog box with dimensions
=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.
Example 23. --menu dialog box
kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
Figure 17. --menu dialog box
If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.
As with the other examples we've seen, the return value depends on the button used. OK returns zero. Cancel returns one.
A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.
Example 24. --checklist dialog box
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
Figure 18. --checklist dialog box
Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the --separate-output to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.
Example 25. --checklist dialog box
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
As for the menu example, the return value depends on the button used. OK returns zero. Cancel returns one.
The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:
Example 26. --checklist dialog box
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
Figure 19. --checklist dialog box
Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.
A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:
Example 27. --combobox dialog box
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
Figure 20. --combobox dialog box
=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
Example 28. --getopenfilename dialog box
kdialog --getopenfilename .
Figure 21. --getopenfilename dialog box
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 29. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename .
/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[bradh@rachel kdialog]$ kdialog --getopenurl .
file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 30. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 31. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain"
Figure 22. --getopenfilename dialog box with MIME filter
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 32. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
Figure 23. --getopenfilename dialog box with wildcard filter
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Example 33. --getsavefilename dialog box
kdialog --getsavefilename .
Figure 24. --getsavefilename dialog box
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 34. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
Example 35. --getexistingdirectory dialog box
kdialog --getexistingdirectory .
Figure 25. --getexistingdirectory dialog box
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.
=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:54:50Z

CuCullin: /* User Input dialogs */

{{Improve}}

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.

--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.

Example 11. --passivepopup dialog box
<code>
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
</code>

Figure 6. --passivepopup dialog box screenshot

=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.

A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.

Example 12. --yesno message box
<code>
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
</code>

Figure 7. --yesno message box screenshot

A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.

Example 13. --warningyesno message box
<code>
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
</code>

Figure 8. --warningyesno warning screenshot

A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.

Example 14. --warningcontinuecancel message box
<code>
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
</code>

Figure 9. --warningcontinuecancel warning screenshot

Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.

Example 15. --yesnocancel message box
<code>
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
/code>

Figure 10. --yesnocancel message box screenshot

There is also a --warningyesnocancel variation, as shown below.

Example 16. --warningyesnocancel message box
<code>
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
</code>

Figure 11. --warningyesnocancel message box screenshot

The return value ($?) from all these dialog boxes follows a common pattern. A ''Yes'', ''OK'' or ''Continue'' returns '''0'''. A ''No'' returns '''1'''. A ''Cancel'' returns '''2'''.

=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.

The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.

As an example, consider an information level message box for display of a file missing message.

Example 17. Information level message box, with --dontagain
<code>
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
</code>

Figure 12. Information level message box, with --dontagain, screenshot

As noted above, an entry is written to a file when the user selects the checkbox.

Example 18. --dontagain file listing
<code>
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
</code>

The effect of this entry is to suppress future display of dialogs using that filename. In the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.

=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.

The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.

Example 19. --inputbox dialog box
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
</code>

Figure 13. --inputbox dialog box screenshot

Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:

Example 20. --inputbox dialog box with default parameter
<code>
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
</code>

Figure 14. --inputbox dialog box screenshot showing default text

The return value depends on the button used. ''OK'' returns '''0'''. ''Cancel'' returns '''1'''.

The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses ''Cancel'', no output is sent.

=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.
Example 21. --textbox dialog box
kdialog --textbox Makefile
Figure 15. --textbox dialog box
Example 22. --textbox dialog box with dimensions
kdialog --textbox Makefile 440 200
Figure 16. --textbox dialog box with dimensions
=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.
Example 23. --menu dialog box
kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
Figure 17. --menu dialog box
If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.
As with the other examples we've seen, the return value depends on the button used. OK returns zero. Cancel returns one.
A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.
Example 24. --checklist dialog box
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
Figure 18. --checklist dialog box
Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the --separate-output to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.
Example 25. --checklist dialog box
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
As for the menu example, the return value depends on the button used. OK returns zero. Cancel returns one.
The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:
Example 26. --checklist dialog box
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
Figure 19. --checklist dialog box
Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.
A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:
Example 27. --combobox dialog box
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
Figure 20. --combobox dialog box
=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
Example 28. --getopenfilename dialog box
kdialog --getopenfilename .
Figure 21. --getopenfilename dialog box
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 29. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename .
/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[bradh@rachel kdialog]$ kdialog --getopenurl .
file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 30. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 31. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain"
Figure 22. --getopenfilename dialog box with MIME filter
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 32. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
Figure 23. --getopenfilename dialog box with wildcard filter
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Example 33. --getsavefilename dialog box
kdialog --getsavefilename .
Figure 24. --getsavefilename dialog box
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 34. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
Example 35. --getexistingdirectory dialog box
kdialog --getexistingdirectory .
Figure 25. --getexistingdirectory dialog box
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.
=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:49:03Z

CuCullin: /* Suppressing the display of a dialog */

{{Improve}}

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.

--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.

Example 11. --passivepopup dialog box
<code>
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
</code>

Figure 6. --passivepopup dialog box screenshot

=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.

A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.

Example 12. --yesno message box
<code>
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
</code>

Figure 7. --yesno message box screenshot

A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.

Example 13. --warningyesno message box
<code>
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
</code>

Figure 8. --warningyesno warning screenshot

A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.

Example 14. --warningcontinuecancel message box
<code>
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
</code>

Figure 9. --warningcontinuecancel warning screenshot

Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.

Example 15. --yesnocancel message box
<code>
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
/code>

Figure 10. --yesnocancel message box screenshot

There is also a --warningyesnocancel variation, as shown below.

Example 16. --warningyesnocancel message box
<code>
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
</code>

Figure 11. --warningyesnocancel message box screenshot

The return value ($?) from all these dialog boxes follows a common pattern. A ''Yes'', ''OK'' or ''Continue'' returns '''0'''. A ''No'' returns '''1'''. A ''Cancel'' returns '''2'''.

=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.

The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.

As an example, consider an information level message box for display of a file missing message.

Example 17. Information level message box, with --dontagain
<code>
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
</code>

Figure 12. Information level message box, with --dontagain, screenshot

As noted above, an entry is written to a file when the user selects the checkbox.

Example 18. --dontagain file listing
<code>
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
</code>

The effect of this entry is to suppress future display of dialogs using that filename. In the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.

=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.
The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.
Example 19. --inputbox dialog box
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
An input dialog box is shown below.
Figure 13. --inputbox dialog box screenshot
Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:
Example 20. --inputbox dialog box with default parameter
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
An input dialog box with initial default text is shown below.
Figure 14. --inputbox dialog box screenshot showing default text
The return value depends on the button used. OK returns zero. Cancel returns one.
The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses Cancel, no output is sent.
=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.
Example 21. --textbox dialog box
kdialog --textbox Makefile
Figure 15. --textbox dialog box
Example 22. --textbox dialog box with dimensions
kdialog --textbox Makefile 440 200
Figure 16. --textbox dialog box with dimensions
=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.
Example 23. --menu dialog box
kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
Figure 17. --menu dialog box
If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.
As with the other examples we've seen, the return value depends on the button used. OK returns zero. Cancel returns one.
A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.
Example 24. --checklist dialog box
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
Figure 18. --checklist dialog box
Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the --separate-output to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.
Example 25. --checklist dialog box
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
As for the menu example, the return value depends on the button used. OK returns zero. Cancel returns one.
The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:
Example 26. --checklist dialog box
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
Figure 19. --checklist dialog box
Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.
A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:
Example 27. --combobox dialog box
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
Figure 20. --combobox dialog box
=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
Example 28. --getopenfilename dialog box
kdialog --getopenfilename .
Figure 21. --getopenfilename dialog box
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 29. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename .
/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[bradh@rachel kdialog]$ kdialog --getopenurl .
file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 30. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 31. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain"
Figure 22. --getopenfilename dialog box with MIME filter
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 32. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
Figure 23. --getopenfilename dialog box with wildcard filter
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Example 33. --getsavefilename dialog box
kdialog --getsavefilename .
Figure 24. --getsavefilename dialog box
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 34. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
Example 35. --getexistingdirectory dialog box
kdialog --getexistingdirectory .
Figure 25. --getexistingdirectory dialog box
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.
=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:46:38Z

CuCullin: /* More Message Boxes */

{{Improve}}

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.

--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.

Example 11. --passivepopup dialog box
<code>
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
</code>

Figure 6. --passivepopup dialog box screenshot

=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.

A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.

Example 12. --yesno message box
<code>
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
</code>

Figure 7. --yesno message box screenshot

A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.

Example 13. --warningyesno message box
<code>
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
</code>

Figure 8. --warningyesno warning screenshot

A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.

Example 14. --warningcontinuecancel message box
<code>
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
</code>

Figure 9. --warningcontinuecancel warning screenshot

Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.

Example 15. --yesnocancel message box
<code>
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
/code>

Figure 10. --yesnocancel message box screenshot

There is also a --warningyesnocancel variation, as shown below.

Example 16. --warningyesnocancel message box
<code>
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
</code>

Figure 11. --warningyesnocancel message box screenshot

The return value ($?) from all these dialog boxes follows a common pattern. A ''Yes'', ''OK'' or ''Continue'' returns '''0'''. A ''No'' returns '''1'''. A ''Cancel'' returns '''2'''.

=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.
The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.
As an example, consider an information level message box for display of a file missing message.
Example 17. Information level message box, with --dontagain
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
A typical information level message box, with --dontagain is shown below.
Figure 12. Information level message box, with --dontagain, screenshot
As noted above, an entry is written to a file when the user selects the checkbox.
Example 18. --dontagain file listing
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
The effect of this entry is to suppress future display of dialogs using that filename, entry tuple (in the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.
=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.
The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.
Example 19. --inputbox dialog box
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
An input dialog box is shown below.
Figure 13. --inputbox dialog box screenshot
Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:
Example 20. --inputbox dialog box with default parameter
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
An input dialog box with initial default text is shown below.
Figure 14. --inputbox dialog box screenshot showing default text
The return value depends on the button used. OK returns zero. Cancel returns one.
The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses Cancel, no output is sent.
=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.
Example 21. --textbox dialog box
kdialog --textbox Makefile
Figure 15. --textbox dialog box
Example 22. --textbox dialog box with dimensions
kdialog --textbox Makefile 440 200
Figure 16. --textbox dialog box with dimensions
=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.
Example 23. --menu dialog box
kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
Figure 17. --menu dialog box
If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.
As with the other examples we've seen, the return value depends on the button used. OK returns zero. Cancel returns one.
A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.
Example 24. --checklist dialog box
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
Figure 18. --checklist dialog box
Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the --separate-output to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.
Example 25. --checklist dialog box
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
As for the menu example, the return value depends on the button used. OK returns zero. Cancel returns one.
The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:
Example 26. --checklist dialog box
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
Figure 19. --checklist dialog box
Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.
A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:
Example 27. --combobox dialog box
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
Figure 20. --combobox dialog box
=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
Example 28. --getopenfilename dialog box
kdialog --getopenfilename .
Figure 21. --getopenfilename dialog box
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 29. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename .
/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[bradh@rachel kdialog]$ kdialog --getopenurl .
file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 30. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 31. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain"
Figure 22. --getopenfilename dialog box with MIME filter
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 32. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
Figure 23. --getopenfilename dialog box with wildcard filter
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Example 33. --getsavefilename dialog box
kdialog --getsavefilename .
Figure 24. --getsavefilename dialog box
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 34. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
Example 35. --getexistingdirectory dialog box
kdialog --getexistingdirectory .
Figure 25. --getexistingdirectory dialog box
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.
=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:44:10Z

CuCullin: /* Non-Interrupting Notifications */

{{Improve}}

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.

--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.

Example 11. --passivepopup dialog box
<code>
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
</code>

Figure 6. --passivepopup dialog box screenshot

=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.
A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.
Example 12. --yesno message box
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
A Yes/No message box is shown below.
Figure 7. --yesno message box screenshot
A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.
Example 13. --warningyesno message box
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
A Yes/No warning box is shown below.
Figure 8. --warningyesno warning screenshot
A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.
Example 14. --warningcontinuecancel message box
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
A Continue/Cancel warning box is shown below.
Figure 9. --warningcontinuecancel warning screenshot
Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.
Example 15. --yesnocancel message box
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
A Yes/No/Cancel message box is shown below.
Figure 10. --yesnocancel message box screenshot
There is also a --warningyesnocancel variation, as shown below.
Example 16. --warningyesnocancel message box
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
A Yes/No/Cancel warning message box is shown below.
Figure 11. --warningyesnocancel message box screenshot
The return value ($?) from all these dialog boxes follows a common pattern. A Yes, OK or Continue returns zero. A No returns one. A Cancel returns two.
=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.
The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.
As an example, consider an information level message box for display of a file missing message.
Example 17. Information level message box, with --dontagain
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
A typical information level message box, with --dontagain is shown below.
Figure 12. Information level message box, with --dontagain, screenshot
As noted above, an entry is written to a file when the user selects the checkbox.
Example 18. --dontagain file listing
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
The effect of this entry is to suppress future display of dialogs using that filename, entry tuple (in the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.
=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.
The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.
Example 19. --inputbox dialog box
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
An input dialog box is shown below.
Figure 13. --inputbox dialog box screenshot
Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:
Example 20. --inputbox dialog box with default parameter
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
An input dialog box with initial default text is shown below.
Figure 14. --inputbox dialog box screenshot showing default text
The return value depends on the button used. OK returns zero. Cancel returns one.
The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses Cancel, no output is sent.
=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.
Example 21. --textbox dialog box
kdialog --textbox Makefile
Figure 15. --textbox dialog box
Example 22. --textbox dialog box with dimensions
kdialog --textbox Makefile 440 200
Figure 16. --textbox dialog box with dimensions
=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.
Example 23. --menu dialog box
kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
Figure 17. --menu dialog box
If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.
As with the other examples we've seen, the return value depends on the button used. OK returns zero. Cancel returns one.
A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.
Example 24. --checklist dialog box
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
Figure 18. --checklist dialog box
Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the --separate-output to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.
Example 25. --checklist dialog box
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
As for the menu example, the return value depends on the button used. OK returns zero. Cancel returns one.
The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:
Example 26. --checklist dialog box
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
Figure 19. --checklist dialog box
Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.
A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:
Example 27. --combobox dialog box
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
Figure 20. --combobox dialog box
=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
Example 28. --getopenfilename dialog box
kdialog --getopenfilename .
Figure 21. --getopenfilename dialog box
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 29. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename .
/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[bradh@rachel kdialog]$ kdialog --getopenurl .
file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 30. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 31. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain"
Figure 22. --getopenfilename dialog box with MIME filter
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 32. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
Figure 23. --getopenfilename dialog box with wildcard filter
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Example 33. --getsavefilename dialog box
kdialog --getsavefilename .
Figure 24. --getsavefilename dialog box
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 34. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
Example 35. --getexistingdirectory dialog box
kdialog --getexistingdirectory .
Figure 25. --getexistingdirectory dialog box
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.
=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:43:12Z

CuCullin: /* Basic message boxes */

{{Improve}}

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.

Example 8. Information level message box
<code>
kdialog --msgbox "Password correct.\n About to connect to server"
</code>

Figure 3. Information level message box screenshot

Example 9. Sorry level message box
<code>
kdialog --sorry "Password incorrect.\n Will not connect to server"
</code>

Figure 4. Sorry level message box screenshot

Example 10. Error level message box
<code>
kdialog --error "Server protocol error."
</code>

Figure 5. Error level message box screenshot

The return value for these basic message boxes is zero.

While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.

=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.
--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.
Example 11. --passivepopup dialog box
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
A passive popup is shown below.
Figure 6. --passivepopup dialog box screenshot
=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.
A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.
Example 12. --yesno message box
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
A Yes/No message box is shown below.
Figure 7. --yesno message box screenshot
A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.
Example 13. --warningyesno message box
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
A Yes/No warning box is shown below.
Figure 8. --warningyesno warning screenshot
A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.
Example 14. --warningcontinuecancel message box
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
A Continue/Cancel warning box is shown below.
Figure 9. --warningcontinuecancel warning screenshot
Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.
Example 15. --yesnocancel message box
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
A Yes/No/Cancel message box is shown below.
Figure 10. --yesnocancel message box screenshot
There is also a --warningyesnocancel variation, as shown below.
Example 16. --warningyesnocancel message box
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
A Yes/No/Cancel warning message box is shown below.
Figure 11. --warningyesnocancel message box screenshot
The return value ($?) from all these dialog boxes follows a common pattern. A Yes, OK or Continue returns zero. A No returns one. A Cancel returns two.
=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.
The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.
As an example, consider an information level message box for display of a file missing message.
Example 17. Information level message box, with --dontagain
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
A typical information level message box, with --dontagain is shown below.
Figure 12. Information level message box, with --dontagain, screenshot
As noted above, an entry is written to a file when the user selects the checkbox.
Example 18. --dontagain file listing
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
The effect of this entry is to suppress future display of dialogs using that filename, entry tuple (in the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.
=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.
The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.
Example 19. --inputbox dialog box
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
An input dialog box is shown below.
Figure 13. --inputbox dialog box screenshot
Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:
Example 20. --inputbox dialog box with default parameter
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
An input dialog box with initial default text is shown below.
Figure 14. --inputbox dialog box screenshot showing default text
The return value depends on the button used. OK returns zero. Cancel returns one.
The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses Cancel, no output is sent.
=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.
Example 21. --textbox dialog box
kdialog --textbox Makefile
Figure 15. --textbox dialog box
Example 22. --textbox dialog box with dimensions
kdialog --textbox Makefile 440 200
Figure 16. --textbox dialog box with dimensions
=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.
Example 23. --menu dialog box
kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
Figure 17. --menu dialog box
If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.
As with the other examples we've seen, the return value depends on the button used. OK returns zero. Cancel returns one.
A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.
Example 24. --checklist dialog box
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
Figure 18. --checklist dialog box
Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the --separate-output to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.
Example 25. --checklist dialog box
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
As for the menu example, the return value depends on the button used. OK returns zero. Cancel returns one.
The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:
Example 26. --checklist dialog box
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
Figure 19. --checklist dialog box
Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.
A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:
Example 27. --combobox dialog box
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
Figure 20. --combobox dialog box
=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
Example 28. --getopenfilename dialog box
kdialog --getopenfilename .
Figure 21. --getopenfilename dialog box
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 29. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename .
/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[bradh@rachel kdialog]$ kdialog --getopenurl .
file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 30. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 31. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain"
Figure 22. --getopenfilename dialog box with MIME filter
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 32. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
Figure 23. --getopenfilename dialog box with wildcard filter
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Example 33. --getsavefilename dialog box
kdialog --getsavefilename .
Figure 24. --getsavefilename dialog box
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 34. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
Example 35. --getexistingdirectory dialog box
kdialog --getexistingdirectory .
Figure 25. --getexistingdirectory dialog box
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.
=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:37:08Z

CuCullin:

{{Improve}}

== Introduction and Scope ==
There are some misconceptions that KDE is only a graphical environment. While it is true that KDE is an outstanding desktop environment, the Unix heritage of command line and scripting is also well supported by KDE. In particular, KDE applications can be controlled from the command line, and shell scripts can make use of some of the KDE widget set.

To use this tutorial, you'll need to have some basic familiarity with command line fundamentals, and be at least aware of shell scripting. Like any other programming environment, effective shell scripting requires solid knowledge of the environment. However, you should be able to make sense of the examples with only basic understanding. The downside to this is that if you are very familiar with shell scripting, some of the explanation is likely to be redundant.

This tutorial assumes that you are using the GNU bash shell, or something directly compatible. Users of other shells (especially csh and variants) may need to modify the examples.

Shell scripting techniques and usage varies a lot. Sometimes a script is only meant to be run by the system (e.g. as cron job), and other times scripts are really applications intended to be run by users. KDE includes features that allow you to use some KDE functionality from a shell script, which can save work, and can also make your script feel like it is part of a nicely integrated application set.

As an example, consider something like a password dialog. If you need a user to enter a password, you can easily generate a dialog from your script that looks like the following:

[[Image:Shell_Scripting_with_KDE_Dialogs-Password_Dialog.png]]

== kdialog Usage ==
=== Example 1: Password Dialog ===

The key to using KDE dialogs in shell scripts is an application named ''kdialog''. To generate a password dialog as shown in above, you could use the following command line.

<code>
kdialog --password "Please enter the server access code:"
</code>

Let's look at the code in a bit more detail. The arguments to kdialog are used to control the type of dialog that is produced and the parameter or parameters of that dialog box. In the case of the password dialog, you use --password to specify the dialog type, and then follow that with the parameter, which is the text that appears in the dialog box.

=== Example 2: Shell Script Return Values ===

Each time you run kdialog (or any other application), there is a return value that indicates whether the application ran as expected, or failed in some way. You can access this return value as $?, as shown in the following example.

<code>
[watson@bakerst]$ kdialog --password "Some Text"
hello
[watson@bakerst]$ echo $?
0
</code>

* Note - The $? variable is updated when each foreground process exits. If you need to use that variable later, you need to save it away.

In this example, the return value is zero. It would be one if the ''Cancel'' button had been selected instead of the ''OK'' button.

* Note - This is different to the convention used by the underlying widgets. If you are familiar with the underlying Qt widgets, this might be a bit confusing, however it is important to conform to the standard approach to shell scripting.

=== Example 3: Shell Script Return Value with Error ===

The convention is that negative numbers indicate failure, however the shell normally subtracts them from 256. This means that if you fail to specify a required argument, the system returns -2, and $? returns 254.

<code>
[watson@bakerst]$ kdialog --password
kdialog: '<text>' missing.
kdialog: Use --help to get a list of available command line options.
[watson@bakerst]$ echo $?
254
</code>

=== Example 4: Password Dialog, with Return Value Check ===

In a shell script, you might choose to test the return value after each invocation.

<code>
kdialog --password "Please enter the server access code:"
if [ $? = 0 ]; then
echo " you selected: OK"
else
echo " you selected: Cancel"
fi
</code>

In addition to the return value, you also get the password itself (assuming that you selected OK). After all, what is the point of a password dialog unless you can use the result?

=== Example 5: Password Dialog Showing Redirection ===
For the password dialog, and other kdialog dialogs that provide input capabilities, the output is sent to standard output. This allows you to redirect the input to a file, or pipe it to another program. In the case of the password dialog, the text that is entered will be echoed as shown in [[#Example 2|Example 2]], unless you redirect it.

<code>
[watson@bakerst]$ kdialog --password "Enter the password" > password.file
[watson@bakerst]$ cat password.file
Secrter
</code>

=== Example 6: Password Dialog Using a Shell Variable ===

Instead of saving the result in a file, you can also use a shell variable. Note that you need to use the "backtick" notation - this key is normally found on the top left of English (British or American) layout keyboards, above the "7" key on French layout keyboards, and on the top right of German layout keyboards.

<code>
[watson@bakerst]$ password=`kdialog --password "Enter the password"`
[watson@bakerst]$ echo $password
Secreter
</code>

=== Example 7: Password Dialog with Title ===
While not shown in the previous examples, you can also use the --title option to specify the title of the dialog box, as shown in the following example.

<code>
kdialog --title "ACAP entry" --password "Please enter the server access code:"
</code>

Which results in:

[[Image:Shell Scripting with KDE Dialogs-Password Dialog with Title.png]]

== kdialog Dialog Types ==

The password dialog is just one of the many dialogs that kdialog can provide. This section provides an overview of each type, and describes the arguments you need to provide for each dialog type.

=== Basic message boxes ===
Basic message boxes are intended to provide status type information. There are variations to indicate the importance of the information (information, warnings, or errors). In each case, the argument is the text to provide, as shown in the following examples.
Example 8. Information level message box
kdialog --msgbox "Password correct.\n About to connect to server"
A typical information level message box is shown below.
Figure 3. Information level message box screenshot
Example 9. Sorry level message box
kdialog --sorry "Password incorrect.\n Will not connect to server"
A typical sorry level message box is shown below.
Figure 4. Sorry level message box screenshot
Example 10. Error level message box
kdialog --error "Server protocol error."
A typical error level message box is shown below.
Figure 5. Error level message box screenshot
The return value for these basic message boxes is zero.
While not used in these examples, you can use the --title to set the window title as well. This option can be used with any of the dialog types.
=== Non-Interrupting Notifications ===
kdialog supports the concept of a popup dialog that does not grab focus, called a passive popup.
--passivepopup takes a text label to display, and a timeout. The display will be automatically removed when the timeout (which is in seconds) has elapsed, or when the user clicks on the popup.
Example 11. --passivepopup dialog box
kdialog --title "This is a passive popup" --passivepopup \
"It will disappear in about 10 seconds" 10
A passive popup is shown below.
Figure 6. --passivepopup dialog box screenshot
=== More Message Boxes ===
Sometimes you need more than the basic message box allows. Perhaps you have a potentially dangerous action, and you need to give the user a second chance. Or perhaps you just need a decision based on some information. kdialog provides some of the tools you might need.
A --yesno type dialog is probably the simplest of this type, as shown below. Like the simple message boxes previously, it requires a text string, which is shown in the message box.
Example 12. --yesno message box
kdialog --title "Example YesNo dialog" --yesno "System is not \
currently connected.\n Do you want to connect now?"
A Yes/No message box is shown below.
Figure 7. --yesno message box screenshot
A variation on the --yesno dialog type is the --warningyesno, which modifies the dialog box appearance a bit.
Example 13. --warningyesno message box
kdialog --title "Example YesNo warning dialog" --warningyesno "Are \
you sure you want to delete all that hard work?"
A Yes/No warning box is shown below.
Figure 8. --warningyesno warning screenshot
A further variation is to use a --warningcontinuecancel dialog type, which has the same usage, but has different button labels, and may fit some situations better.
Example 14. --warningcontinuecancel message box
kdialog --title "Example ContinueCancel warning dialog" \
--warningcontinuecancel "Are you sure you want to delete all that \
hard work?"
A Continue/Cancel warning box is shown below.
Figure 9. --warningcontinuecancel warning screenshot
Another variation on the --yesno dialog type is to add a third option, as shown in the --yesnocancel dialog type.
Example 15. --yesnocancel message box
kdialog --title "YesNoCancel dialog" --yesnocancel "About to exit.\n \
Do you want to save the file first?"
A Yes/No/Cancel message box is shown below.
Figure 10. --yesnocancel message box screenshot
There is also a --warningyesnocancel variation, as shown below.
Example 16. --warningyesnocancel message box
kdialog --title "YesNoCancel warning dialog" --warningyesnocancel \
"About to exit.\n Do you want to save the file first?"
A Yes/No/Cancel warning message box is shown below.
Figure 11. --warningyesnocancel message box screenshot
The return value ($?) from all these dialog boxes follows a common pattern. A Yes, OK or Continue returns zero. A No returns one. A Cancel returns two.
=== Suppressing the display of a dialog ===
Sometimes you will be using kdialog in a loop, or other situation where a message may be repeated. For example, you might be iterating through a list of files, and you raise an error for each file you cannot open because of permission problems. This can produce a really bad user experience because the error is repeated over and over.
The normal KDE way to deal with this is to allow the user to suppress the display of a message in the future by selecting a checkbox, and kdialog allows you to do this with the --dontagain option. This option takes a file name and an entry name, and if the user selects the checkbox, then an entry is written to the specified file, with the specified entry name.
As an example, consider an information level message box for display of a file missing message.
Example 17. Information level message box, with --dontagain
kdialog --dontagain myscript:nofilemsg --msgbox "File not found."
A typical information level message box, with --dontagain is shown below.
Figure 12. Information level message box, with --dontagain, screenshot
As noted above, an entry is written to a file when the user selects the checkbox.
Example 18. --dontagain file listing
$ cat ~/.kde/share/config/myscript
[Notification Messages]
nofilemsg=false
The effect of this entry is to suppress future display of dialogs using that filename, entry tuple (in the example above, this means myscript:nofilemsg. This will take effect across all KDE applications, so be careful of the filename you use.
=== User Input dialogs ===
There are two basic free-form user input dialog types - the --inputbox type and the --password type. The password dialog was covered in depth in a previous section - see the Section called kdialog Usage.
The --inputbox dialog type requires at least one parameter, which is used as the text in the dialog box.
Example 19. --inputbox dialog box
kdialog --title "Input dialog" --inputbox "What name would you like to
use"
An input dialog box is shown below.
Figure 13. --inputbox dialog box screenshot
Sometimes you want to provide a default text string in the input dialog. You can do this by providing that string as the optional second parameter, as shown below:
Example 20. --inputbox dialog box with default parameter
kdialog --title "Input dialog" --inputbox "What name would you like to
use" "default Name"
An input dialog box with initial default text is shown below.
Figure 14. --inputbox dialog box screenshot showing default text
The return value depends on the button used. OK returns zero. Cancel returns one.
The string that is entered (or modified / accepted if default text is used) is returned on standard output. If the user chooses Cancel, no output is sent.
=== Displaying files ===
A common requirement for shell scripts is the ability to display a file. kdialog supports this with the --textbox dialog type. This dialog type has one mandatory parameter, which is the name of the file to be displayed. There are also two optional parameters which specify the width and height of the dialog box in pixels. If these are not specified, 100 pixels by 100 pixels is used.
Example 21. --textbox dialog box
kdialog --textbox Makefile
Figure 15. --textbox dialog box
Example 22. --textbox dialog box with dimensions
kdialog --textbox Makefile 440 200
Figure 16. --textbox dialog box with dimensions
=== Menu and Selection Dialogs ===
This section covers simple menus, checklists, radio buttons and combo-boxes. These are typically used for providing a choice of options.
The menu is used to select one of a range of options. Each option is defined using two arguments, which you might like to think of as a key and a label. An example of the usage is shown below.
Example 23. --menu dialog box
kdialog --menu "Select a language:" a "American English" b French d "Oz' English"
Figure 17. --menu dialog box
If you select the first option (in this case American English and press OK, then kdialog will send the associated key (in this case the letter a) to standard output. Note that the keys do not need to be lower case letters - you can equally use numbers, upper case letters, strings or the contents of shell variables.
As with the other examples we've seen, the return value depends on the button used. OK returns zero. Cancel returns one.
A checklist is similar to a menu, except that the user can select more than one option. In addition, a reasonable set of default selections can be provided. To do this, each option is defined using three arguments, which you might like to think of as a key, a label and a default state. An example of the usage is shown below.
Example 24. --checklist dialog box
kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
Figure 18. --checklist dialog box
Clearly the result can contain more than one string, since the user can select more than one label. By default, the results are returned on a single line, however you can use the --separate-output to get a carriage return between each result. These two cases are shown in the example below, where all of the options were selected in each case.
Example 25. --checklist dialog box
$ kdialog --checklist "Select languages:" 1 "American English" off \
2 French on 3 "Oz' English" off
"1" "2" "3"
$ kdialog --separate-output --checklist "Select languages:" \
1 "American English" off 2 French on 3 "Oz' English" off
1
2
3
As for the menu example, the return value depends on the button used. OK returns zero. Cancel returns one.
The radiolist is very similar to the checklist, except that the user can only select one of the options. An example is shown below:
Example 26. --checklist dialog box
$ kdialog --radiolist "Select a default language:" 1 "American \
English" off 2 French on 3 "Oz' English" off
Figure 19. --checklist dialog box
Note that if you try to turn on more than one option by default, only the last option turned on will be selected. If you don't turn on any of the options, and the user doesn't select any, kdialog will raise an assertion, so don't do this.
A combo-box is slightly different to the previous menu options, in that it doesn't use keys, but instead just returns the selected text. An example is shown below:
Example 27. --combobox dialog box
$ kdialog --combobox "Select a flavour:" "Vanilla" "Chocolate" "Strawberry" "Fudge"
Chocolate
Figure 20. --combobox dialog box
=== File Selection Dialogs ===
This section covers dialogs to select files to open and save. These dialogs access the power of the underlying KDE dialogs, including advanced filtering techniques and can provide either paths or URLs.
The dialog to select a file to open is invoked with --getopenfilename or --getopenurl. These two commands are used in the same way - only the format of the result changes, so every example shown here can be applied for either format. You have to specify a starting directory, and can optionally provide a filter. Here is a simple example that doesn't provide any filtering, and accesses the current directory:
Example 28. --getopenfilename dialog box
kdialog --getopenfilename .
Figure 21. --getopenfilename dialog box
As for previous examples, the return value depends on the button used. OK returns zero. Cancel returns one.
As mentioned previously, the result format varies between the two variations. This is shown below, in each case selecting the same file:
Example 29. --getopenfilename dialog box
[bradh@rachel kdialog]$ kdialog --getopenfilename .
/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
[bradh@rachel kdialog]$ kdialog --getopenurl .
file:/home/bradh/coding/cvs-vers/kde-head/kdebase/kdialog/Makefile.am
Note that the user can only select an existing file with these options.
When you doing a lot of opening of files, it can be useful to open the dialog in the directory that was navigated to last time. While you can potentially do this by extracting the directory from the filename, you can use a special KDE feature based on labels, as shown below:
Example 30. --getopenfilename dialog box with directory support
kdialog --getopenfilename :label1
kdialog --getopenfilename :label1
Each time you use the same label (with the colon notation), the last used directory will be used as the starting directory. This will normally improve the user experience. If that label hasn't been used before, the user's home directory will be used.
Note that the colon notation selects the last used directory for that label for the kdialog application. If you use two colons instead of one, the labelling scope becomes global and applies to all applications. This global scope is rarely what you want, and is mentioned only for completeness.
Since not all files are applicable, it can be useful to restrict the files displayed. This is done using the optional filter argument. The best way to do this is with MIME types, as shown below:
Example 31. --getopenfilename dialog box with MIME filter
kdialog --getopenfilename ~/doco/ethereal-userguide "image/png text/html text/plain"
Figure 22. --getopenfilename dialog box with MIME filter
If it isn't possible to use MIME types, you can specify a range of wildcards and an optional label, as shown below:
Example 32. --getopenfilename dialog box with wildcard filter
kdialog --getopenfilename . "*.cpp *.cc *.c |C and C++ Source Files"
Figure 23. --getopenfilename dialog box with wildcard filter
The --getsavefilename and --getsaveurl commands are directly analogous to the file opening dialogs. A simple example is shown below:
Example 33. --getsavefilename dialog box
kdialog --getsavefilename .
Figure 24. --getsavefilename dialog box
Unlike the file opening dialogs, the file saving dialogs allow to user to specify a filename that doesn't yet exist.
As for the file opening dialogs, the file saving dialogs allow use of the colon notation, and also allow filtering using MIME types and wildcards, as shown below:
Example 34. --getsavefilename dialog box with filter
kdialog --getsavefilename :label1 "*.cpp *.cc *.c |C and C++ Source Files"
Sometimes you don't want to specify a filename, but instead need a directory. While you can specify a "inode/directory" filter to a file open dialog, it is sometimes better to use the --getexistingdirectory type, as shown below:
Example 35. --getexistingdirectory dialog box
kdialog --getexistingdirectory .
Figure 25. --getexistingdirectory dialog box
--getexistingdirectory does not provide any filtering, but it does provide the same starting directory options, including the colon notation.
=== Progress Dialogs ===
A progress bar dialog is a useful GUI element when you have a process that will take a long time, and you want to reassure the user that things are happening correctly, rather than having the user believe that the machine may have locked up. If you ever find yourself thinking about writing an information dialog that says something like "..., this may take a while", it may be appropriate to use a progress bar dialog.
Because you need to make the progress bar change, you can't use kdialog in the normal way. Instead, you set up the dialog, and use the dcop to make the required changes.
A simple use of the --progressbar command is shown below. Because it is fairly long, I've numbered the lines. The numbers aren't part of the script you would type in - they are purely for reference in the explanation.
Example 36. --progressbar dialog box example
1 dcopRef=`kdialog --progressbar "Initialising" 4`
2 dcop $dcopRef setProgress 1
3 dcop $dcopRef setLabel "Thinking really hard"
4 sleep 2
5 dcop $dcopRef setProgress 2
6 sleep 2
7 dcop $dcopRef setLabel "Thinking some more"
8 dcop $dcopRef setProgress 3
9 sleep 2
10 dcop $dcopRef setProgress 4
11 sleep 2
12 dcop $dcopRef close
I'll work through each line in turn. Line 1 runs kdialog, with an initial label of Initialising, and a progress bar with four elements. We capture the return value in a variable (which can be named just about anything - I chose dcopRef) for later use with the dcop command. Line 2 sets the bar to one stage along, and line 3 changes the label to Thinking really hard. Line 4 is just a delay (which would be when your script would perform the first part of the lengthy task in a real application). Line 5 then increases the progress bar, followed by another delay (representing more processing) in line 6. Line 7 changes the label, while lines 8 through 11 further increase the progress bar over a few seconds. Line 12 closes the progress bar dialog - without this, it will remain displayed. If you'd prefer that the progress bar dialog closed as soon as the bar gets to 100%, you can use the setAutoClose true argument to dcop.
If a task is taking a very long time, the user may decide that it is better cancelled. kdialog can assist with this too, as shown in the example below.
Example 37. --progressbar dialog box example, with Cancel
1 dcopRef=`kdialog --progressbar "Press Cancel at Any time" 10`
2 dcop $dcopRef showCancelButton true

3 until test "true" == `dcop $dcopRef wasCancelled`; do
4 sleep 1
5 inc=$((`dcop $dcopRef progress` + 1))
6 dcop $dcopRef setProgress $inc;
7 done

8 dcop $dcopRef close
As in the previous example, the first line executes kdialog with some initial text, this time with 10 segments; and again we capture the return value in a variable for later use with dcop. Line 2 turns on the display of the Cancel button, which is off by default.
Lines 3 through 7 are a loop. Line three runs dcop to check if the Cancel button has been pressed, and if it hasn't been pressed yet, runs line 4 through 6. Line 4 is again a delay, representing processing in a real application. Line 5 runs dcop to get the current progress bar setting, and adds one to the count (I could have just kept a counter variable, but this approach shows another dcop usage). Line 6 then sets the progress bar to the incremented value. Line 8 closes the progress bar dialog if the Cancel button has been pressed.

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:17:19Z

CuCullin: /* Example 5: Password Dialog Showing Redirection */

Development/Tutorials/Shell Scripting with KDE Dialogs

2007-01-12T02:08:57Z

CuCullin: Created Page

File:Shell Scripting with KDE Dialogs-Password Dialog with Title.png

2007-01-12T02:06:22Z

CuCullin: Shell Scripting with KDE Dialogs-Password Dialog with Title Should be updated to show new look

Shell Scripting with KDE Dialogs-Password Dialog with Title

Should be updated to show new look

File:Shell Scripting with KDE Dialogs-Password Dialog.png

2007-01-12T01:48:55Z

CuCullin: Shell Scripting with KDE Dialogs - Example Password Dialog. Should be updated to show a newer look.

Shell Scripting with KDE Dialogs - Example Password Dialog.

Should be updated to show a newer look.

User talk:Jstaniek

2007-01-11T20:36:57Z

CuCullin: /* KDElibs.com and developernew.kde.org coexistence */

__TOC__

== TODOs ==
*Check [[Development/Tutorials/Localization/Unicode]] content against the Qt4 API, check the theory against Wikipedia's Unicode page.

== KDElibs.com and developernew.kde.org coexistence ==
* Mind if I copy the build info over from kdelibs.com to here under Getting_Started/Build/Unstable_Version-Windows, and then could you review it for current correctness? Thanks --[[User:CuCullin|CuCullin]] 16:13, 11 January 2007 (CET)
**I do not recommend making redundant copies of http://www.kdelibs.com. The content there is under heavy development now. I won't be able to maintain another wiki (I already have FOUR :) ). '''We can make a move (not a copy) to kdelibs once KDE4 buildsystem is stable.''' Why? Because many steps are common and we want to share them between targets. For now the instructions are even splitted between msvc and mingw compilers, what's not optimal for maintenance. <br>'''According to my vision: eventually, kdelibs.com will be more ISVs-oriented while *.kde.org stays oriented at the community in general.''' -- [[User:Jstaniek|jstaniek]] 17:27, 11 January 2007 (CET)
*** Moving once its settled in sounds good. As long as at some point we have all our information in one place we should be good. The issue of kdelibs.com becoming an ISV portal raises a question with regards to the ISV section on this website. We don't need two of them IMHO, it'll only split resources and give opportunity for confusion to those looking for ISV info. Jaroslaw: i'll see if i can find you on irc to discuss kdelibs.com a bit since that's a bit off-topic here. =) --[[User:Aseigo|Aseigo]] 20:43, 11 January 2007 (CET)
****In fact, kdelibs.com is planned as a web site about kdelibs technology only (or mostly), as it sounds, and how to use it for developemnt and deployment. Among other plans I think the web site will have a variation of kde.org's look&feel, with some "commercial" touch. Something like trolltech.com is for Qt while there exist various forums devoted Qt, I'd risk such comparison. Companies/organizations having multiple web sites, one per orthogonal topic, are not unusual these days... These are random thoughts for now. ---[[User:Jstaniek|jstaniek]] 21:08, 11 January 2007 (CET)
*** I'm not wanting to move all of it - specifically, what I'd like to do is just get basic build information onto this wiki and also a working windows version of the "hello world" for KDE 4 tutorial posted. This is partially to coordinate with something upcoming.... if you're available, I'm on freenode to chat about it further. --[[User:CuCullin|CuCullin]] 21:36, 11 January 2007 (CET)

User talk:Jstaniek

2007-01-11T15:13:39Z

CuCullin: /* TODOs */ Getting_Started/Build/Unstable_Version-Windows Question...

== TODOs ==
*Check [[Development/Tutorials/Localization/Unicode]] content against the Qt4 API, check the theory against Wikipedia's Unicode page.

----
* Mind if I copy the build info over from kdelibs.com to here under Getting_Started/Build/Unstable_Version-Windows, and then could you review it for current correctness? Thanks --[[User:CuCullin|CuCullin]] 16:13, 11 January 2007 (CET)

Talk:Installing third party softwares in terminal/Build/KDE4/Mac OS X

2007-01-10T19:51:10Z

CuCullin:

Once a KDE-Darwin person has reviewed this for accuracy, I'd like to post a link under Getting Started/Build, at "KDE 4 (Unstable version, trunk), For OSX, For Windows" or some such. However, I don't even have a mac to try this on, so if someone could that would be great :) --[[User:CuCullin|CuCullin]] 16:49, 10 January 2007 (CET)

:I'm all for it. We also need to propagate [http://www.kdelibs.com the windows] build (and maybe also [http://solaris.kde.org/ solaris]. --[[User:Dhaumann|Dhaumann]] 18:41, 10 January 2007 (CET)

::I'm right now waiting for explicit permission to copy the existing tutorial on kdelibs.com over here. I doubt it will be an issue, but I always ask on any non kde.org site :) --[[User:CuCullin|CuCullin]] 20:51, 10 January 2007 (CET)

Talk:Installing third party softwares in terminal/Build/KDE4/Mac OS X

2007-01-10T15:49:56Z

CuCullin: For review & Getting Started/Build link

Development/Tutorials/KDE3/Qt Designer and KDevelop 3.0 for Beginners

2007-01-10T03:11:44Z

CuCullin: Having an issue uploading images - if someone could do that it would be great!

{{improve}}
{{KDE3}}

==Introduction==
To get us started doing something useful with [http://www.trolltech.com/products/qt/features/designer Qt Designer], we are going to build a simple program that will show you the power of Qt Designer and [http://www.kdevelop.org/ KDevelop]. I hope that this will help you to create your first "real" KDE application.

[http://www.trolltech.com/products/qt/features/designer KDevelop] will help you to build a complete KDE application. The KDE project uses the autoconf and automake tools for KDE 3.x, and [http://www.kdevelop.org/ KDevelop] will provide you with all the necessary files (admin directory, Makefile.cvs, Makefile.am,...).

==Requirements==

===How to Get Qt Designer===
====From your Distribution====
Qt Designer is part of the qt-3.2.x package and above. If you have an older Qt on your system, you should get at least this version. At the time of writing, Qt latest version is 3.3.2.

Please remember to check if you have all the qt-related packages installed. You need the qt headers in order to compile this tutorial application. These headers usually come in the ''devel'' package. You also need to be sure you have designer. In some distributions, it comes in a separate package.

To check if you have everything, do a:

<code>locate qstring.h</code>

If you get something like ''/usr/lib/qt3/include/qstring.h'' then you can set your ''QTDIR'' variable to ''/usr/lib/qt3/''. In bash environment, this is done by typing:

<code>export QTDIR= /usr/lib/qt3</code>

====Tarball or Anonymous Subversion====
You can download the tarball from the [http://www.trolltech.com/download/qt/x11.html Trolltech website], or get the ''qt-copy'' module from SVN. Please note that Qt for [http://www.kernel.org/ Linux] is [http://www.gnu.org/copyleft/gpl.html GPL].

For an explanation for how to use anonymous SVN, get the ''qt-copy'' and ''kde'' modules and compile them, please see a great documentation at [[Getting_Started/Sources/Using Subversion with KDE|Using Subversion with KDE]].

You must then set the ''QTDIR'' environment variable. This should point to the directory into which you installed Qt. In bash, for example, you would type:

<code>export QTDIR= /usr/local/qt</code>

provided that ''/usr/local/qt'' is the directory into which you installed Qt. Please read the INSTALL file for more details.

You then compile by issuing the following commands, here is the recommended compile line:

<code>./configure -system-zlib -qt-gif -system-libpng -system-libjpeg \
-plugin-imgfmt-mng -thread -no-exceptions -debug -fast
make</code>

The command ''make install'' is not needed.

Qt Designer is located in the ''bin'' directory of your Qt installation directory. You can run it by typing:
<code>/usr/local/qt/bin/designer</code>
in a console.

To compile Qt from source, please see [http://www.trolltech.com/ Trolltech]'s [http://www.trolltech.com/developer/downloads/qt/x11 Qt/X11 Open Source Edition] page.

===How to get KDevelop 3===
====From your Distribution====
KDevelop 3 should be part of your distribution. Pre 3 versions of KDevelop were nicknamed Gideon, but they are obsolete now.

====From Tarball====
KDevelop can be downloaded from the [http://www.kdevelop.org KDevelop website], under the '''Quick download''' heading.

To compile KDevelop 3, you need qt-3.1.0 or higher and kdelibs-3.1.0 or higher. The environment variables ''QTDIR'' and ''KDEDIR'' should point to those directories.

Don't forget to set up the KDE and Qt paths. The most common errors while using KDevelop come from the environment variables not set up properly. Check in a console by issuing the command '''set''' to see all your environment variables. You should set your ''PATH'' variable as follow as well as your ''LD_LIBRARY_PATH'':

<code>export PATH=$QTDIR/bin:$KDEDIR/bin:$PATH
export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH</code>

If you have any problem getting KDevelop running, please refer to the [http://www.kdevelop.org/phorum5/ KDevelop Forum] to find the answer to your problem.

If you never used KDevelop before, try to create a new project and to compile it to get used to the interface and the icons.

====KDevelop 3.4====
Please refer to [http://www.kdevelop.org/index.html?filename=3.4/download.html Downloading KDevelop 3.4] and [http://www.kdevelop.org/index.html?filename=3.4/branches_compiling.html Compiling KDevelop 3.4].

===Lexicon===
* '''Widget''': a widget is an element of an graphical interface such as a container window, a button or a field for entering text.
* '''Layout management''': this term describes the way in which widgets are arranged in a window. In its simplest form, an element may be placed at a specific position and given a specific height and width. But when the user resizes the window, the widgets should stay in their position and change their size accordingly. Linux allows to do that by using layouts to place the widgets in.
* '''Signal and Slots''': Signals and slots are used for communication between objects. The signal/slot mechanism is a central feature of Qt. Signals are emitted by objects when they change their state in a way that may be interesting to the outside world. Slots can be used for receiving signals, but they are normal member functions. You can connect as many signals as you want to a single slot, and a signal can be connected to as many slots as you desire. Please see the [http://doc.trolltech.com/3.3/signalsandslots.html TrollTech documentation on signals and slots] for more details. In the excellent online documentation that comes with Qt, you'll find the signals and the public slots that go with each class. You can then implement your own slots.

==Creating the Application==
===Starting the project===
====Creating the framework with KDevelop====

The framework in which our program will sit in (i.e. the main window) can be done easily and quickly by using KDevelop. Start KDevelop and select ''New Project'' in the Project menu. The Application Wizard appears then. Choose a ''C++ -> KDE -> Simple KDE Application''. Fill in the blank lines with the project name '''SigCreate''', your name as author, and your email. Refer to [[:Image:KDevelop3-CreateNewProject.png|this screen shot]] as a reference.

Click on ''Next''. Have a look to the CVS option and the header templates. Then click on ''Finish'' on the last screen. KDevelop creates all the files that you need to compile your project. You can use the file selector to view the code of the 3 files which are main.cpp, sigcreate.cpp and sigcreate.h, as shown [[:Image:KDevelop3-FileSelector.png|here]].

Once the ''Application Wizard'' has created your application, compile it to ensure that everything is fine. To do that, select '''Build -> Run automake & friends''' then '''Build -> Run configure'''. The ''Messages output window'' should say

<code>" Good - your configure finished. Start make now
*
* *** Success ***</code>

so you can run ''make'' with '''Build -> Build Project''' (or using the F8 shortcut). Then '''Build -> Install'''. Then '''Build -> Execute program''' (or F9). The result is shown [[:Image:KDevelop-SigCreate.png|here]].

*'''NOTE''' - If KDevelop does not recognize your ''QTDIR'' and ''KDEDIR'' variables, you can set them in '''Project -> Project Options...''' in ''Configure Options'', as [[:Image:KDevelop3-ConfigureOptions.png|shown]].

====Using Qt Designer====
Qt Designer is a tool for designing and implementing user interfaces. It helps you arranging your widgets on a form and adding a proper layout so your interface can be resized properly. I recommend that you read the [http://doc.trolltech.com/3.3/designer-manual.html Qt Designer manual] to know everything about Qt Designer. Qt Designer includes a code editor but we'll use KDevelop to edit and modify all code.

We will now create the interface of our application using Qt Designer. A form from Qt Designer is saved with a .ui extension because it is then processed by the uic program to generate a .h and .cpp files. KDevelop takes care of that, the only thing we need to do is to create the form.

* '''Note''' - Each time you add or remove a file (now we will add a .ui file) in your KDevelop project, the Makefile.am will be changed. KDevelop does that itself but you will need to ''Run automake & friends'' after such changes.

In KDevelop, click on '''File -> New''' and fill the dialog window that appears. First write the file name: ''sigcreatedlg'' and select what new file you want in the combobox: here we want a ''Widget (.ui)''. Please be sure that '''Add to project''' is checked, this ensures that the Makefile.am is updated. Refer to [[:Image:KDevelop3-NewFile-Widget.png|this screen shot]].

Click the ''OK'' button. The [[:Image:KDevelop3-AutomakeManagerDialog.png|Automake manager dialog]] then pops up. Click the ''OK'' button for this dialog as well.

If the new file ''sigcreatedlg.ui'' is not open in Qt Designer, open the ''Automake Manager'', right-click on the file and select ''Open With'', then ''Qt Designer''. Qt Designer will open.

* '''Note''' - About the names: it is a good idea to finish a dialog name or a form name by ''dlg'' to ensure a nice visibility for people who want to have a look at the code. ''sigcreatedlg'' says that it is a dialog, i.e an interface class, only.

The [[:Image:QtDesigner3-Interface.png|Qt Designer interface]] is essentially split into three areas. On the left is the '''toolbox''', where you can select your widgets. On the right, several dialogs can be selected. I'll keep only the '''Property Editor''' dialog (I close the 2 others). Your widgets can be fine tuned to behave how you want them to. You can choose the size of the widget, its background color (palette), and so on. Between those 2 windows is the '''Form''', your program window, within which you will design your user interface.

* '''Note''' - After adding the ''sigcreatedlg.ui'' file, you will have to run ''Automake & friends'' and ''Run configure'' before building the program. This ensures that the updated ''Makefile.am'' is now read.

===Designing the Program===

Each time you want to use Qt Designer, you should have a precise visual idea of the design of your interface. You can see in [[:Image:KDevelop3-SigCreateDialog.png|this picture]] what the program will be like. It is a window with a number of different items (or widgets) on it, designed so that the user puts the right information in the right boxes. You should always design your program from the user's point of view, as it must be easy to use.

This application creates an email signature, which is then displayed on the screen. The user should enter her/his name, email address, and then select one of three comments. When you click the '''Create!''' button, the generated signature is shown in a ''MultiLineEdit''. When you click '''Cancel''', the program quits.

* '''Note''' - Note that this project is meant as a tutorial, so this is somewhat far away from practical use.

Go back to the Qt Designer window with the new dialog open. You will see that the property editor has been filled with details about the form you have created. The first line in the '''Property Editor''' [[:Image:QtDesigner3-PropertyEditor.png|shows]] the name of the form which is Form1. Click on the field with this name to change it and type SigCreateDlg. This will form the class name of the dialog so you should name it something useful.

To change properties, select the property you wish to change, then alter its setting on the right. Change the '''Caption''' property to "SigCreateDlg v.01". We will now begin to add widgets on our dialog.

===Adding Widgets===

To start, we will insert the text at the top of the program window, which can be seen [[:Image:KDevelop3-NewFile-Widget.png|here]]. This text tells the user how to operate the program. This type of widget is called a ''Label'' and you can put one on your program like this:

# Select the dialog in ToolBox called '''Common Widgets->TextLabel''', or from the menubar '''Tools->Display->TextLabel'''
# The cursor will become a crosshair over the form. Draw a box for the label, just as you would in a paint program, and you will see that the label is created with some dummy text in it.
# To change this text, double click on the label and type in the text, instead of ''TextLabel1''. The text you should type is ''This program will create an email signature for you. Just fill in the boxes and hit the Create! button.'' Select '''Align Center'' to have the text positioned nicely. Refer to this [[:Image:QtDesigner3-TextEditDialog.png|screenshot]].
# Finally, resize the widget using the handles so it is the correct size and at the top of the box. Try to center the label by moving it with the mouse. This is just a temporary measure. Later on we will look at a more elegant layout management technique. You may refer to [[:Image:QtDesigner3-ResizingBox.png|this screenshot]].

You follow pretty much the same procedure for embedding any type of widget that is supported by Qt Designer; select it, drag it, and finally, change its properties and size.

An interesting concept in Qt Designer is that widgets can act as containers for other widgets. This will be demonstrated in our next task, which is to create the input fields inside the frame. You can see that in Picture 8 we have a bunch of labels and text boxes inside a frame. This frame is called a Group Box and acts as a container for the labels and text boxes inside it. Let's first create the frame by selecting the GroupBox in the '''Toolbox dialog->Containers''' or '''Tools->Containers->GroupBox''' from the menubar. You can drag the mouse to create the box just below the Label you put before. In the ''Property Editor'' you can change the title property to alter the text in the frame. Put ''Details'' in the title text field. You may notice a + symbol in this entry in the ''Property Editor''. This indicates that the property has subproperties that can also be changed.

Once you have created the frame (i.e the GroupBox), create three more labels as before but when you draw them, draw them inside the GroupBox frame. You can then see in the Object Explorer box ('''Windows menu -> Views -> Object Explorer''') to the right that the labels have become children of the GroupBox frame. See [[:Image:QtDesigner3-EditingTheDialog.png|this image]].

Change the text of labels by double-clicking on it.

Once you have done this you can then create the text boxes. They will allow the user to type in text like his(her) name and email address. We use the simplest type of text boxes: a widget called QLineEdit which allows the user to enter one line of text only. You have to create two QLineEdit widgets for the name and the email address. You choose the menu Tools then the entry Input then LineEdit and you draw it beside the 'Your Name' Label. Do the same below for the address.

The witty comment will be selected by the user. We use a ComboBox which will present the user with three comments. Click on the ComboBox icon or select it via the Tools-> Input-> ComboBox menu. Draw it beside the Witty Comment label. Then double-click on it. You will be presented with a box into which you can add the contents of the combo box. Click on the 'New Item' button and type in your comment in the text box at the right. Then click again on 'New Item' for the second and third comments. Click on OK when you have finished.

Adjust the size of the different widgets so they are nicely placed.

Up to now, we have not named any of the widgets that are being placed in our program. It is useful to set an internal name for widgets so we can call them after in the program. Labels don't perform any action so they don't need to be named but other widgets do. It is the case now for our text boxes. We'll need to manipulate the data from the three input widgets (i.e. read the text) so we should give them a name. Names should be easily recognized later and they should make sense. The names are assigned via the name property on the top of the Property Editor. We name the top LineEdit nameBox and the second one mailBox. We name the ComboBox commBox. This will allow us to access the comments. So click on each LineEdit and then besides Name in the Property Editor write nameBox and mailBox. Then click on the ComboBox and name it commBox.

We finish the graphical design by adding a label with 'Generated Signature' as text. Below it, we put a TextEdit ('''Tools->Input->TextEdit'''') where the generated signature will be displayed. We name it 'sigBox'. And then we add two PushButtons at the bottom ('Create!' and 'Cancel'). They don't need names but you can give them some if you want.

Save your form. You can now have a quick preview by selecting the menu '''Preview-> Preview Form'''. [[:Image:QtDesigner3-BeforeLayoutManagement.png|This]] is the form ''before'' layout management.

===Getting Spaced Out===
This section describes the layout management. If you resize the preview window you will then notice that the widgets do not adjust appropriately. They are not resized. To improve things, we need to use a feature in Qt called spacers. Spacers are like virtual springs that push the widgets on each side apart.
* '''Note''' - Having a good layout is essential for your application, as when the strings are translated, they might be longer than the English ones and they need to fit on your widgets. The geometry of the widgets has to be nice if the user can resize your window application. Layouts are done by trial and error so use '''Preview->Preview Form''' to see the result of your layout management and to achieve the best layout.

The use of spacers and layout management is a skill that is developed through trial and error. The main thing to remember when dealing with spacers is that you work horizontally first and then vertically.

We will first use spacers to center the text in the top box. Resize your label so that it only get the size of the text. Then we add two spacers, one at each side. Choose the 'spring' icon or menu '''Layout-> Add Spacer'''. You adjust each of the spacers horizontally. Click the space to the left of the text and the blue spacer will appear . Repeat the same procedure for the right. Then add a spacer on the right of the 'Generated Signature' label, and a last one on the left of the the 'Create!' pushbutton. Please use [[:Image:QtDesigner3-AddingTheSpacers.png|this image]] as a reference.

Now that we have spacers to fill blank space, we need a proper layout management. This will allow the widgets to be nicely resized whenever the main window is resized. It is really compulsory to have good layout management. Again, try to resize several times to see if everything is in place. We can use Vertical or horizontal layout or grid management. The top row of widget is horizontal (spacer + label + spacer) so we need Horizontal management. We need to select the three widgets alltogether: click on the first spring, then click on the label while holding down ''Shift'', then on the second spring while holding down ''Shift''. Then click on the Horizontal Layout icon or menu '''Layout-> Lay Out Horizontally'''. You will then see a resizable red line around the three objects to indicate that their layout is being managed. Resize the red box if it needs to.

We can now repeat this procedure for the three labels inside the GroupBox, this time using vertical layout management. The same vertical management for the two LineEdit and the ComboBox. It is better to use vertical management to keep the object aligned. If we use horizontal management for each label + text box then they will not stay aligned and equally sized. Horizontal management is needed for the label with the spacer and another one for the two pushbuttons and the spacer.

To finish the layout, we need to let the form look after the laid-out boxes. We put everything in a grid. This is done by right clicking the form and selecting "Lay Out in a Grid" from the menu. The final design with layout lines should resemble something similar to [[:Image:QtDesigner3-CompleteLayoutManagement.png|this image]].

===Signals and Slots===

[http://doc.trolltech.com/3.0/signalsandslots.html Signals and Slots] are used for communication between Qt objects. The signal/slot mechanism is a central feature of Qt and probably the part that differs most from other toolkits which often use callbacks. In Qt, a signal is emitted by a widget when a particular event occurs, very often triggered by the user like for example pressing a button or writing something in a LineEdit. A slot is simply a function that is called in reponse to a particular signal.

Now the widgets are implemented and the layout is arranged the final thing we need to do in the design stage of the form is to create the signal/slot connections. To do this manually requires a ''connect()'' function but Qt Designer provides a simple yet effective solution. To create the signal/slot connections we need to use the connecting tool. To do this either select the icon (it looks like a red arrow going into a green square) or select '''Tools-> Connect Signals/Slots''' from the menu (or use the F3 shortcut key). To create a connection, click on the form on the widget that is going to be dealing with the slot, drag the line off the form and release the mouse button.

Let's deal first with the Create! button. Click first on the '''Connect Signal/Slot''' icon or select it from the Tools menu or use the F3 key. Then click on the Create! button with the crosshair and drag the line off the form completely. When you have released the mouse button you will see the connections tool shown [[:Image:QtDesigner3-CreateSlot.png|here]].

What we want to do is to create a slot that will create our signature when the user clicks on the Create! button. The signal will be clicked() (you may choose among five signals for a QPushButton) and we need to create the slot then make the connection.

To create the slot we need to click on the '''Edit Slots''' button. The slot creation box then appears. See [[:Image:QtDesigner3-CreateSlot.png|this example]]. Now click on the '''New Function''' button and a slot will appear in the box. Instead of ''new_slot()'' rename it to ''slotCreateSig()'' and leave the access specifier as public. When you click on ''OK'' you will be returned to the connections box and you will see your new slot in the Slots section of the box.

To [[:Image:QtDesigner3-ViewandEditConnections.png|make a connection]] you simply select the appropriate signal (which is ''clicked()'' in our case) and then select the slot (which is our new slot ''slotCreateSig()''). When you have selected both signal and slot you will see the connection made at the bottom of the screen. After you are finished click OK.

Repeat the procedure for the Cancel button by using the clicked() signal and the close() slot. You are now done with the signals and slots.
* '''Warning''' - Don't forget to save your form!

===Generating the Source===

In this tutorial, we use KDevelop subclassing tool in Automake Manager. If you have KDevelop version which has not that capability, then please go to Chapter 7 where I explain this step without the subclass tool.

Here we start with the KDE simple project named SigCreate and the sigcreatedlg.ui that we have added in our project. In the Automake Manager, in the section sigcreate (Program in bin) you must have three files: sigcreatedlg.ui, sigcreate.cpp and main.cpp. The project must compile and give the main window as in picture 3 (creating.html).

As the sigcreate class is no use for us, we will remove it and use it for subclassing the sigcreatedlg.ui file. In the Automake Manager, right click on sigcreate.cpp and select Remove and a dialog pops up. Please check 'Also Remove it from disk'. Then do the same with sigcreate.h. This is the way to remove obsolete files from your project and the Makefile.am will be updated. Remember to run automake & friends and configure before compiling your project again. We will not do it right now because we will make other changes. We will now use the class name SigCreate for the subclass.

In the Automake Manager, in sigcreate (program in bin), right click on sigcreatedlg.ui and choose Subclass Widget... from the context menu that appears. Then fill in the subclass name which is SigCreate. Check the box: Reformat source and click on OK. Say No then about adding these files in cvs as we did not enable this in our project.
Note
You can see that the slot we created in designer is listed here and checked, the method will be implemented in the generated files. If you uncheck it, the code will not be generated in your class.

(The subclass dialog Image)

We have to suppress some lines in main.cpp as the KDE simple project template refers to a KMainWindow which is usually the base class used. But here, SigCreate is based on QWidget. You have to remove all the lines between KApplication app; and return app.exec(); except the ones I keep here:

<code>SigCreate *mainWin = 0;

mainWin = new SigCreate();
app.setMainWidget( mainWin );
mainWin->show();
</code>

===Implementing the Slot===

Then you implement the slot by adding the following lines in the parenthesis of:

<code>
void SigCreate::slotCreateSig()
{}</code>

to implement the slot
<code>
sigBox->append("\n--");
sigBox->append(nameBox->text());
sigBox->append(mailBox->text());
sigBox->append(commBox->currentText());
</code>
and also the corresponding headers of course:
<code>
#include <qlineedit.h>
#include <qcombobox.h>
#include <qmultilineedit.h>
</code<
Run ''Build -> Run automake & friends'', ''Build-> Run Configure'', ''Build -> Build Project'', ''Build -> Install'' (or ''Build->Install as root user''), ''Build -> Execute Program''. That's it! The program is working!

(Picture 20)

A few more words about signals and slots. The signals and slots mechanism is type safe: the signature of a signal must match the signature of the receiving slot (for example, you will connect valueChanged(int) with a slot having an int as argument). And another thing to keep in mind is that all classes that inherit from QObject or one of its subclasses (e.g. QWidget) can contain signals and slots.

All the strings used in KDE program must be wrapped in the i18n() function (klocale.h as header) because all KDE projects are translated. Please see the KDE Translation HowTo to learn more about i18n to make translations for an application.

==In Short==

This is a short resume on how to work with KDevelop and QtDesigner.
* In the KDevelop menu File->New, select a Widget (.ui) file and give it a name (kprojectdlg for that example), check add to Project. Click OK.
* Qt Designer starts. Work on your form in Qt Designer then save your file and close designer. The designer file appears then in KDevelop under User Interface (kprojectdlg.ui).
* Create a new class (KProject as name for example) (Project menu then New class...) that inherits from your dialog file (kprojectdlg) and is a QWidget-childclass.
* Add your slots and others signals or member functions in the inherited class KProject.

== Make the Translations for a Simple KDE Project==

When your own project is finished, you may like to have one or several translations for the GUI. Here is how you can do that.

=== Install gettext Patched for KDE ===

Install a patched gettext that you can find on developer.kde.org and install it in your home directory. The patched gettext can be found there : http://public.kde.planetmirror.com/pub/kde/devel/gettext-kde/

<code>
$ tar xvzf gettext-0.10.35-kde.tar.gz
$ cd gettext-0.10.35-kde
$ ./configure
$ make
$ mkdir -p ~/bin
$ cp src/gettext src/xgettext ~/bin # copy gettext and xgettext into your HOME/bin directory
$ export PATH=~/bin:$PATH
<code>

=== Prepare the Translations ===

Then, go into your project directory :

<code>
$ cd /path/to/myproject
</code>

Set KDEDIR to match your kde installation - on my Mandrake it is /usr This path can also be found by doing "kde-config --prefix"
<code>
$ export KDEDIR=`kde-config --prefix` # or export KDEDIR=/usr
</code>

Then create the translations files :
<code>
$ make -f admin/Makefile.common package-messages
</code>

=== Make the Translations ===

Translate the .po files using kbabel These files are in the po directory of your project.
* Warning - Do not touch the .pot file!

=== Compile and Install the Translations Files ===
<code>
$ make package-messages
$ sudo make install
</code>

==General Tips==
===General Hints===
==== Your Application Name ====

KDE application names generally start with the letter K followed by a name suggesting what the program does. For example, KMail is very simple and tells the user that this is indeed a KDE application and about email. A good practice is to choose an english name for the name that follows the K. Of course, this is just an indication and you are free to do what you want. But a good name can help to get your program known quicker.

* Note - Run a search in Google (in Konqueror, write gg:your_app_name) to see if the name you want to use is not the name of a copyrighted program. If this is the case or if in doubt, change it.

==== Coding Practice ====

Comments should be in English as it is really easier if someone else has a look at your code.

Class names usually are also in English and the names must indicate what the class does. Good examples: TopLevel, CursorInterface, TaskManager. Note the upper case letters and remember that C++ is case-sensitive.

Function names usually begin with a lower case letter and here are examples of good names:

<code>
void activateRaiseOrIconify();
void toDesktop(int);
void windowAdded(WId);
</code>
Code indentation can be whatever you like as long as the code is visible for other developers. Always keep in mind that other people will have a look in your code and try to make it easy to read.

=== Importing your project in KDE CVS ===

Your program interests people, you feel you have time to really work on it, you need more feedback and help for improving it. You also agree to release it under the GPL license or equivalent. You can ask for a cvs account to import it in kdenonbeta. The kdenonbeta module is quite big and is not distributed with the official KDE. It is not packaged nor translated and feature freeze does not apply to kdenonbeta. Its purpose is to allow other developers to work on your application and to test it. Of course, you will need qt-copy, arts and kdelibs from cvs HEAD at least. Please see a tutorial here on how to get started for compiling KDE from cvs HEAD.
Note
When your application has the most important features, when it's totally KDE compatible (i18n, xml GUI, ect.), you will be able to ask for moving it in a KDE official package.

In order to get a cvs account, please follow theses instructions. Send a mail to sysadmin (at) office (dot) kde (dot) org to justify why you need cvs access. Tell that you want to import your application (app_name) in the kdenonbeta module. Make sure to specify your full name and e-mail address, if the From field in your mails doesn't specify them. You can also choose a nickname for your user login. You can currently choose between the standard non-encrypted CVS protocol (pserver) and the encrypted CVS-over-ssh. If you choose pserver, send also an encrypted password (for instance using useradd dummy ; passwd dummy ; grep dummy /etc/passwd /etc/shadow). If you choose CVS-over-ssh, send a public ssh key (e.g. ~/.ssh/id_dsa.pub).

Wait for the answer from a KDE sysadmin.

Once you have compiled at least qt-copy, arts and kdelibs, you need to check out kdenonbeta files. Log in the cvs server with your login user and password.
<code>
$ cvs co -l kdenonbeta
$ cd kdenonbeta
$ cvs co admin (or ln -s ../kde-common/admin .admin)
</code>
You copy your project main dir with everything in kdenonbeta and then, in your project main dir, you issue a:
<code>
$ make disclean
</code>
All the .o files must be gone. You can also remove by hand all Makefile, Makefile.in (not Makefile.am) and all kdevelop related files. Remove the admin, autom4te.cache, debug, doc, po and templates folders. You must just keep some files and the src subdir. Then, you cd .. to go back in kdenonbeta and you type:
<code>
$ make -f Makefile.cvs
$ ./configure --prefix=$KDEDIR
$ cd your_project_name
$ make
$ su -c 'make install'
</code>

All these steps must go well. If there are errors, you should be able to correct them by carefully reading the error message. If you are really stuck, please go to IRC and ask on #kde or #kde-devel, someone will help you.

then, in kdenonbeta dir:

<code>
$ cvs add your_project_name
$ cvs add your_project_name/*
$ cvs add your_project_name/src
$ cvs add your_project_name/src/*
$ cvs commit
</code>

You get the window (vi editor as default) where you can log your message. It's a good practice to note what your commit is about. In your case, you will say (type i first if you are in vi to get in edit mode):

First import of your_app_name which does this and that.

Check if all the files are added correctly. If not, cvs add filename and cvs commit.

Each time you want to work on your project, don't forget to log in the kde server with your user login and password and do a:
<code>
$ cvs up
</code>
to be sure you have the latest version.

Development/Tutorials/KDE3/Qt Designer and KDevelop 3.0 for Beginners

2007-01-10T03:03:52Z

CuCullin: /* Implementing the Slot */

{{improve}}
{{KDE3}}

==Introduction==
To get us started doing something useful with [http://www.trolltech.com/products/qt/features/designer Qt Designer], we are going to build a simple program that will show you the power of Qt Designer and [http://www.kdevelop.org/ KDevelop]. I hope that this will help you to create your first "real" KDE application.

[http://www.trolltech.com/products/qt/features/designer KDevelop] will help you to build a complete KDE application. The KDE project uses the autoconf and automake tools for KDE 3.x, and [http://www.kdevelop.org/ KDevelop] will provide you with all the necessary files (admin directory, Makefile.cvs, Makefile.am,...).

==Requirements==

===How to Get Qt Designer===
====From your Distribution====
Qt Designer is part of the qt-3.2.x package and above. If you have an older Qt on your system, you should get at least this version. At the time of writing, Qt latest version is 3.3.2.

Please remember to check if you have all the qt-related packages installed. You need the qt headers in order to compile this tutorial application. These headers usually come in the ''devel'' package. You also need to be sure you have designer. In some distributions, it comes in a separate package.

To check if you have everything, do a:

<code>locate qstring.h</code>

If you get something like ''/usr/lib/qt3/include/qstring.h'' then you can set your ''QTDIR'' variable to ''/usr/lib/qt3/''. In bash environment, this is done by typing:

<code>export QTDIR= /usr/lib/qt3</code>

====Tarball or Anonymous Subversion====
You can download the tarball from the [http://www.trolltech.com/download/qt/x11.html Trolltech website], or get the ''qt-copy'' module from SVN. Please note that Qt for [http://www.kernel.org/ Linux] is [http://www.gnu.org/copyleft/gpl.html GPL].

For an explanation for how to use anonymous SVN, get the ''qt-copy'' and ''kde'' modules and compile them, please see a great documentation at [[Getting_Started/Sources/Using Subversion with KDE|Using Subversion with KDE]].

You must then set the ''QTDIR'' environment variable. This should point to the directory into which you installed Qt. In bash, for example, you would type:

<code>export QTDIR= /usr/local/qt</code>

provided that ''/usr/local/qt'' is the directory into which you installed Qt. Please read the INSTALL file for more details.

You then compile by issuing the following commands, here is the recommended compile line:

<code>./configure -system-zlib -qt-gif -system-libpng -system-libjpeg \
-plugin-imgfmt-mng -thread -no-exceptions -debug -fast
make</code>

The command ''make install'' is not needed.

Qt Designer is located in the ''bin'' directory of your Qt installation directory. You can run it by typing:
<code>/usr/local/qt/bin/designer</code>
in a console.

To compile Qt from source, please see [http://www.trolltech.com/ Trolltech]'s [http://www.trolltech.com/developer/downloads/qt/x11 Qt/X11 Open Source Edition] page.

===How to get KDevelop 3===
====From your Distribution====
KDevelop 3 should be part of your distribution. Pre 3 versions of KDevelop were nicknamed Gideon, but they are obsolete now.

====From Tarball====
KDevelop can be downloaded from the [http://www.kdevelop.org KDevelop website], under the '''Quick download''' heading.

To compile KDevelop 3, you need qt-3.1.0 or higher and kdelibs-3.1.0 or higher. The environment variables ''QTDIR'' and ''KDEDIR'' should point to those directories.

Don't forget to set up the KDE and Qt paths. The most common errors while using KDevelop come from the environment variables not set up properly. Check in a console by issuing the command '''set''' to see all your environment variables. You should set your ''PATH'' variable as follow as well as your ''LD_LIBRARY_PATH'':

<code>export PATH=$QTDIR/bin:$KDEDIR/bin:$PATH
export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH</code>

If you have any problem getting KDevelop running, please refer to the [http://www.kdevelop.org/phorum5/ KDevelop Forum] to find the answer to your problem.

If you never used KDevelop before, try to create a new project and to compile it to get used to the interface and the icons.

====KDevelop 3.4====
Please refer to [http://www.kdevelop.org/index.html?filename=3.4/download.html Downloading KDevelop 3.4] and [http://www.kdevelop.org/index.html?filename=3.4/branches_compiling.html Compiling KDevelop 3.4].

===Lexicon===
* '''Widget''': a widget is an element of an graphical interface such as a container window, a button or a field for entering text.
* '''Layout management''': this term describes the way in which widgets are arranged in a window. In its simplest form, an element may be placed at a specific position and given a specific height and width. But when the user resizes the window, the widgets should stay in their position and change their size accordingly. Linux allows to do that by using layouts to place the widgets in.
* '''Signal and Slots''': Signals and slots are used for communication between objects. The signal/slot mechanism is a central feature of Qt. Signals are emitted by objects when they change their state in a way that may be interesting to the outside world. Slots can be used for receiving signals, but they are normal member functions. You can connect as many signals as you want to a single slot, and a signal can be connected to as many slots as you desire. Please see the [http://doc.trolltech.com/3.3/signalsandslots.html TrollTech documentation on signals and slots] for more details. In the excellent online documentation that comes with Qt, you'll find the signals and the public slots that go with each class. You can then implement your own slots.

==Creating the Application==
===Starting the project===
====Creating the framework with KDevelop====

The framework in which our program will sit in (i.e. the main window) can be done easily and quickly by using KDevelop. Start KDevelop and select ''New Project'' in the Project menu. The Application Wizard appears then. Choose a ''C++ -> KDE -> Simple KDE Application''. Fill in the blank lines with the project name '''SigCreate''', your name as author, and your email. Refer to [[:Image:KDevelop3-CreateNewProject.png|this screen shot]] as a reference.

Click on ''Next''. Have a look to the CVS option and the header templates. Then click on ''Finish'' on the last screen. KDevelop creates all the files that you need to compile your project. You can use the file selector to view the code of the 3 files which are main.cpp, sigcreate.cpp and sigcreate.h, as shown [[:Image:KDevelop3-FileSelector.png|here]].

Once the ''Application Wizard'' has created your application, compile it to ensure that everything is fine. To do that, select '''Build -> Run automake & friends''' then '''Build -> Run configure'''. The ''Messages output window'' should say

<code>" Good - your configure finished. Start make now
*
* *** Success ***</code>

so you can run ''make'' with '''Build -> Build Project''' (or using the F8 shortcut). Then '''Build -> Install'''. Then '''Build -> Execute program''' (or F9). The result is shown [[:Image:KDevelop-SigCreate.png|here]].

*'''NOTE''' - If KDevelop does not recognize your ''QTDIR'' and ''KDEDIR'' variables, you can set them in '''Project -> Project Options...''' in ''Configure Options'', as [[:Image:KDevelop3-ConfigureOptions.png|shown]].

====Using Qt Designer====
Qt Designer is a tool for designing and implementing user interfaces. It helps you arranging your widgets on a form and adding a proper layout so your interface can be resized properly. I recommend that you read the [http://doc.trolltech.com/3.3/designer-manual.html Qt Designer manual] to know everything about Qt Designer. Qt Designer includes a code editor but we'll use KDevelop to edit and modify all code.

We will now create the interface of our application using Qt Designer. A form from Qt Designer is saved with a .ui extension because it is then processed by the uic program to generate a .h and .cpp files. KDevelop takes care of that, the only thing we need to do is to create the form.

* '''Note''' - Each time you add or remove a file (now we will add a .ui file) in your KDevelop project, the Makefile.am will be changed. KDevelop does that itself but you will need to ''Run automake & friends'' after such changes.

In KDevelop, click on '''File -> New''' and fill the dialog window that appears. First write the file name: ''sigcreatedlg'' and select what new file you want in the combobox: here we want a ''Widget (.ui)''. Please be sure that '''Add to project''' is checked, this ensures that the Makefile.am is updated. Refer to [[:Image:KDevelop3-NewFile-Widget.png|this screen shot]].

Click the ''OK'' button. The [[:Image:KDevelop3-AutomakeManagerDialog.png|Automake manager dialog]] then pops up. Click the ''OK'' button for this dialog as well.

If the new file ''sigcreatedlg.ui'' is not open in Qt Designer, open the ''Automake Manager'', right-click on the file and select ''Open With'', then ''Qt Designer''. Qt Designer will open.

* '''Note''' - About the names: it is a good idea to finish a dialog name or a form name by ''dlg'' to ensure a nice visibility for people who want to have a look at the code. ''sigcreatedlg'' says that it is a dialog, i.e an interface class, only.

The [[:Image:QtDesigner3-Interface.png|Qt Designer interface]] is essentially split into three areas. On the left is the '''toolbox''', where you can select your widgets. On the right, several dialogs can be selected. I'll keep only the '''Property Editor''' dialog (I close the 2 others). Your widgets can be fine tuned to behave how you want them to. You can choose the size of the widget, its background color (palette), and so on. Between those 2 windows is the '''Form''', your program window, within which you will design your user interface.

* '''Note''' - After adding the ''sigcreatedlg.ui'' file, you will have to run ''Automake & friends'' and ''Run configure'' before building the program. This ensures that the updated ''Makefile.am'' is now read.

===Designing the Program===

Each time you want to use Qt Designer, you should have a precise visual idea of the design of your interface. You can see in [[:Image:KDevelop3-SigCreateDialog.png|this picture]] what the program will be like. It is a window with a number of different items (or widgets) on it, designed so that the user puts the right information in the right boxes. You should always design your program from the user's point of view, as it must be easy to use.

This application creates an email signature, which is then displayed on the screen. The user should enter her/his name, email address, and then select one of three comments. When you click the '''Create!''' button, the generated signature is shown in a ''MultiLineEdit''. When you click '''Cancel''', the program quits.

* '''Note''' - Note that this project is meant as a tutorial, so this is somewhat far away from practical use.

Go back to the Qt Designer window with the new dialog open. You will see that the property editor has been filled with details about the form you have created. The first line in the '''Property Editor''' [[:Image:QtDesigner3-PropertyEditor.png|shows]] the name of the form which is Form1. Click on the field with this name to change it and type SigCreateDlg. This will form the class name of the dialog so you should name it something useful.

To change properties, select the property you wish to change, then alter its setting on the right. Change the '''Caption''' property to "SigCreateDlg v.01". We will now begin to add widgets on our dialog.

===Adding Widgets===

To start, we will insert the text at the top of the program window, which can be seen [[:Image:KDevelop3-NewFile-Widget.png|here]]. This text tells the user how to operate the program. This type of widget is called a ''Label'' and you can put one on your program like this:

# Select the dialog in ToolBox called '''Common Widgets->TextLabel''', or from the menubar '''Tools->Display->TextLabel'''
# The cursor will become a crosshair over the form. Draw a box for the label, just as you would in a paint program, and you will see that the label is created with some dummy text in it.
# To change this text, double click on the label and type in the text, instead of ''TextLabel1''. The text you should type is ''This program will create an email signature for you. Just fill in the boxes and hit the Create! button.'' Select '''Align Center'' to have the text positioned nicely. Refer to this [[:Image:QtDesigner3-TextEditDialog.png|screenshot]].
# Finally, resize the widget using the handles so it is the correct size and at the top of the box. Try to center the label by moving it with the mouse. This is just a temporary measure. Later on we will look at a more elegant layout management technique. You may refer to [[:Image:QtDesigner3-ResizingBox.png|this screenshot]].

You follow pretty much the same procedure for embedding any type of widget that is supported by Qt Designer; select it, drag it, and finally, change its properties and size.

An interesting concept in Qt Designer is that widgets can act as containers for other widgets. This will be demonstrated in our next task, which is to create the input fields inside the frame. You can see that in Picture 8 we have a bunch of labels and text boxes inside a frame. This frame is called a Group Box and acts as a container for the labels and text boxes inside it. Let's first create the frame by selecting the GroupBox in the '''Toolbox dialog->Containers''' or '''Tools->Containers->GroupBox''' from the menubar. You can drag the mouse to create the box just below the Label you put before. In the ''Property Editor'' you can change the title property to alter the text in the frame. Put ''Details'' in the title text field. You may notice a + symbol in this entry in the ''Property Editor''. This indicates that the property has subproperties that can also be changed.

Once you have created the frame (i.e the GroupBox), create three more labels as before but when you draw them, draw them inside the GroupBox frame. You can then see in the Object Explorer box ('''Windows menu -> Views -> Object Explorer''') to the right that the labels have become children of the GroupBox frame. See [[:Image:QtDesigner3-EditingTheDialog.png|this image]].

Change the text of labels by double-clicking on it.

Once you have done this you can then create the text boxes. They will allow the user to type in text like his(her) name and email address. We use the simplest type of text boxes: a widget called QLineEdit which allows the user to enter one line of text only. You have to create two QLineEdit widgets for the name and the email address. You choose the menu Tools then the entry Input then LineEdit and you draw it beside the 'Your Name' Label. Do the same below for the address.

The witty comment will be selected by the user. We use a ComboBox which will present the user with three comments. Click on the ComboBox icon or select it via the Tools-> Input-> ComboBox menu. Draw it beside the Witty Comment label. Then double-click on it. You will be presented with a box into which you can add the contents of the combo box. Click on the 'New Item' button and type in your comment in the text box at the right. Then click again on 'New Item' for the second and third comments. Click on OK when you have finished.

Adjust the size of the different widgets so they are nicely placed.

Up to now, we have not named any of the widgets that are being placed in our program. It is useful to set an internal name for widgets so we can call them after in the program. Labels don't perform any action so they don't need to be named but other widgets do. It is the case now for our text boxes. We'll need to manipulate the data from the three input widgets (i.e. read the text) so we should give them a name. Names should be easily recognized later and they should make sense. The names are assigned via the name property on the top of the Property Editor. We name the top LineEdit nameBox and the second one mailBox. We name the ComboBox commBox. This will allow us to access the comments. So click on each LineEdit and then besides Name in the Property Editor write nameBox and mailBox. Then click on the ComboBox and name it commBox.

We finish the graphical design by adding a label with 'Generated Signature' as text. Below it, we put a TextEdit ('''Tools->Input->TextEdit'''') where the generated signature will be displayed. We name it 'sigBox'. And then we add two PushButtons at the bottom ('Create!' and 'Cancel'). They don't need names but you can give them some if you want.

Save your form. You can now have a quick preview by selecting the menu '''Preview-> Preview Form'''. [[:Image:QtDesigner3-BeforeLayoutManagement.png|This]] is the form ''before'' layout management.

===Getting Spaced Out===
This section describes the layout management. If you resize the preview window you will then notice that the widgets do not adjust appropriately. They are not resized. To improve things, we need to use a feature in Qt called spacers. Spacers are like virtual springs that push the widgets on each side apart.
* '''Note''' - Having a good layout is essential for your application, as when the strings are translated, they might be longer than the English ones and they need to fit on your widgets. The geometry of the widgets has to be nice if the user can resize your window application. Layouts are done by trial and error so use '''Preview->Preview Form''' to see the result of your layout management and to achieve the best layout.

The use of spacers and layout management is a skill that is developed through trial and error. The main thing to remember when dealing with spacers is that you work horizontally first and then vertically.

We will first use spacers to center the text in the top box. Resize your label so that it only get the size of the text. Then we add two spacers, one at each side. Choose the 'spring' icon or menu '''Layout-> Add Spacer'''. You adjust each of the spacers horizontally. Click the space to the left of the text and the blue spacer will appear . Repeat the same procedure for the right. Then add a spacer on the right of the 'Generated Signature' label, and a last one on the left of the the 'Create!' pushbutton. Please use [[:Image:QtDesigner3-AddingTheSpacers.png|this image]] as a reference.

Now that we have spacers to fill blank space, we need a proper layout management. This will allow the widgets to be nicely resized whenever the main window is resized. It is really compulsory to have good layout management. Again, try to resize several times to see if everything is in place. We can use Vertical or horizontal layout or grid management. The top row of widget is horizontal (spacer + label + spacer) so we need Horizontal management. We need to select the three widgets alltogether: click on the first spring, then click on the label while holding down ''Shift'', then on the second spring while holding down ''Shift''. Then click on the Horizontal Layout icon or menu '''Layout-> Lay Out Horizontally'''. You will then see a resizable red line around the three objects to indicate that their layout is being managed. Resize the red box if it needs to.

We can now repeat this procedure for the three labels inside the GroupBox, this time using vertical layout management. The same vertical management for the two LineEdit and the ComboBox. It is better to use vertical management to keep the object aligned. If we use horizontal management for each label + text box then they will not stay aligned and equally sized. Horizontal management is needed for the label with the spacer and another one for the two pushbuttons and the spacer.

To finish the layout, we need to let the form look after the laid-out boxes. We put everything in a grid. This is done by right clicking the form and selecting "Lay Out in a Grid" from the menu. The final design with layout lines should resemble something similar to [[:Image:QtDesigner3-CompleteLayoutManagement.png|this image]].

===Signals and Slots===

[http://doc.trolltech.com/3.0/signalsandslots.html Signals and Slots] are used for communication between Qt objects. The signal/slot mechanism is a central feature of Qt and probably the part that differs most from other toolkits which often use callbacks. In Qt, a signal is emitted by a widget when a particular event occurs, very often triggered by the user like for example pressing a button or writing something in a LineEdit. A slot is simply a function that is called in reponse to a particular signal.

Now the widgets are implemented and the layout is arranged the final thing we need to do in the design stage of the form is to create the signal/slot connections. To do this manually requires a ''connect()'' function but Qt Designer provides a simple yet effective solution. To create the signal/slot connections we need to use the connecting tool. To do this either select the icon (it looks like a red arrow going into a green square) or select '''Tools-> Connect Signals/Slots''' from the menu (or use the F3 shortcut key). To create a connection, click on the form on the widget that is going to be dealing with the slot, drag the line off the form and release the mouse button.

Let's deal first with the Create! button. Click first on the '''Connect Signal/Slot''' icon or select it from the Tools menu or use the F3 key. Then click on the Create! button with the crosshair and drag the line off the form completely. When you have released the mouse button you will see the connections tool shown [[:Image:QtDesigner3-CreateSlot.png|here]].

What we want to do is to create a slot that will create our signature when the user clicks on the Create! button. The signal will be clicked() (you may choose among five signals for a QPushButton) and we need to create the slot then make the connection.

To create the slot we need to click on the '''Edit Slots''' button. The slot creation box then appears. See [[:Image:QtDesigner3-CreateSlot.png|this example]]. Now click on the '''New Function''' button and a slot will appear in the box. Instead of ''new_slot()'' rename it to ''slotCreateSig()'' and leave the access specifier as public. When you click on ''OK'' you will be returned to the connections box and you will see your new slot in the Slots section of the box.

To [[:Image:QtDesigner3-ViewandEditConnections.png|make a connection]] you simply select the appropriate signal (which is ''clicked()'' in our case) and then select the slot (which is our new slot ''slotCreateSig()''). When you have selected both signal and slot you will see the connection made at the bottom of the screen. After you are finished click OK.

Repeat the procedure for the Cancel button by using the clicked() signal and the close() slot. You are now done with the signals and slots.
* '''Warning''' - Don't forget to save your form!

===Generating the Source===

In this tutorial, we use KDevelop subclassing tool in Automake Manager. If you have KDevelop version which has not that capability, then please go to Chapter 7 where I explain this step without the subclass tool.

Here we start with the KDE simple project named SigCreate and the sigcreatedlg.ui that we have added in our project. In the Automake Manager, in the section sigcreate (Program in bin) you must have three files: sigcreatedlg.ui, sigcreate.cpp and main.cpp. The project must compile and give the main window as in picture 3 (creating.html).

As the sigcreate class is no use for us, we will remove it and use it for subclassing the sigcreatedlg.ui file. In the Automake Manager, right click on sigcreate.cpp and select Remove and a dialog pops up. Please check 'Also Remove it from disk'. Then do the same with sigcreate.h. This is the way to remove obsolete files from your project and the Makefile.am will be updated. Remember to run automake & friends and configure before compiling your project again. We will not do it right now because we will make other changes. We will now use the class name SigCreate for the subclass.

In the Automake Manager, in sigcreate (program in bin), right click on sigcreatedlg.ui and choose Subclass Widget... from the context menu that appears. Then fill in the subclass name which is SigCreate. Check the box: Reformat source and click on OK. Say No then about adding these files in cvs as we did not enable this in our project.
Note
You can see that the slot we created in designer is listed here and checked, the method will be implemented in the generated files. If you uncheck it, the code will not be generated in your class.

(The subclass dialog Image)

We have to suppress some lines in main.cpp as the KDE simple project template refers to a KMainWindow which is usually the base class used. But here, SigCreate is based on QWidget. You have to remove all the lines between KApplication app; and return app.exec(); except the ones I keep here:

<code>SigCreate *mainWin = 0;

mainWin = new SigCreate();
app.setMainWidget( mainWin );
mainWin->show();
</code>

===Implementing the Slot===

Then you implement the slot by adding the following lines in the parenthesis of:

<code>
void SigCreate::slotCreateSig()
{}</code>

to implement the slot
<code>
sigBox->append("\n--");
sigBox->append(nameBox->text());
sigBox->append(mailBox->text());
sigBox->append(commBox->currentText());
</code>
and also the corresponding headers of course:
<code>
#include <qlineedit.h>
#include <qcombobox.h>
#include <qmultilineedit.h>
</code<
Run ''Build -> Run automake & friends'', ''Build-> Run Configure'', ''Build -> Build Project'', ''Build -> Install'' (or ''Build->Install as root user''), ''Build -> Execute Program''. That's it! The program is working!

(Picture 20)

A few more words about signals and slots. The signals and slots mechanism is type safe: the signature of a signal must match the signature of the receiving slot (for example, you will connect valueChanged(int) with a slot having an int as argument). And another thing to keep in mind is that all classes that inherit from QObject or one of its subclasses (e.g. QWidget) can contain signals and slots.

All the strings used in KDE program must be wrapped in the i18n() function (klocale.h as header) because all KDE projects are translated. Please see the KDE Translation HowTo to learn more about i18n to make translations for an application.

==In Short==
==Make the translations for a simple kde project==
==A few general tips==
==Generating the source (alternate)==
==Credits and License==

Development/Tutorials/KDE3/Qt Designer and KDevelop 3.0 for Beginners

2007-01-10T03:01:07Z

CuCullin: /* Generating the Source */

{{improve}}
{{KDE3}}

==Introduction==
To get us started doing something useful with [http://www.trolltech.com/products/qt/features/designer Qt Designer], we are going to build a simple program that will show you the power of Qt Designer and [http://www.kdevelop.org/ KDevelop]. I hope that this will help you to create your first "real" KDE application.

[http://www.trolltech.com/products/qt/features/designer KDevelop] will help you to build a complete KDE application. The KDE project uses the autoconf and automake tools for KDE 3.x, and [http://www.kdevelop.org/ KDevelop] will provide you with all the necessary files (admin directory, Makefile.cvs, Makefile.am,...).

==Requirements==

===How to Get Qt Designer===
====From your Distribution====
Qt Designer is part of the qt-3.2.x package and above. If you have an older Qt on your system, you should get at least this version. At the time of writing, Qt latest version is 3.3.2.

Please remember to check if you have all the qt-related packages installed. You need the qt headers in order to compile this tutorial application. These headers usually come in the ''devel'' package. You also need to be sure you have designer. In some distributions, it comes in a separate package.

To check if you have everything, do a:

<code>locate qstring.h</code>

If you get something like ''/usr/lib/qt3/include/qstring.h'' then you can set your ''QTDIR'' variable to ''/usr/lib/qt3/''. In bash environment, this is done by typing:

<code>export QTDIR= /usr/lib/qt3</code>

====Tarball or Anonymous Subversion====
You can download the tarball from the [http://www.trolltech.com/download/qt/x11.html Trolltech website], or get the ''qt-copy'' module from SVN. Please note that Qt for [http://www.kernel.org/ Linux] is [http://www.gnu.org/copyleft/gpl.html GPL].

For an explanation for how to use anonymous SVN, get the ''qt-copy'' and ''kde'' modules and compile them, please see a great documentation at [[Getting_Started/Sources/Using Subversion with KDE|Using Subversion with KDE]].

You must then set the ''QTDIR'' environment variable. This should point to the directory into which you installed Qt. In bash, for example, you would type:

<code>export QTDIR= /usr/local/qt</code>

provided that ''/usr/local/qt'' is the directory into which you installed Qt. Please read the INSTALL file for more details.

You then compile by issuing the following commands, here is the recommended compile line:

<code>./configure -system-zlib -qt-gif -system-libpng -system-libjpeg \
-plugin-imgfmt-mng -thread -no-exceptions -debug -fast
make</code>

The command ''make install'' is not needed.

Qt Designer is located in the ''bin'' directory of your Qt installation directory. You can run it by typing:
<code>/usr/local/qt/bin/designer</code>
in a console.

To compile Qt from source, please see [http://www.trolltech.com/ Trolltech]'s [http://www.trolltech.com/developer/downloads/qt/x11 Qt/X11 Open Source Edition] page.

===How to get KDevelop 3===
====From your Distribution====
KDevelop 3 should be part of your distribution. Pre 3 versions of KDevelop were nicknamed Gideon, but they are obsolete now.

====From Tarball====
KDevelop can be downloaded from the [http://www.kdevelop.org KDevelop website], under the '''Quick download''' heading.

To compile KDevelop 3, you need qt-3.1.0 or higher and kdelibs-3.1.0 or higher. The environment variables ''QTDIR'' and ''KDEDIR'' should point to those directories.

Don't forget to set up the KDE and Qt paths. The most common errors while using KDevelop come from the environment variables not set up properly. Check in a console by issuing the command '''set''' to see all your environment variables. You should set your ''PATH'' variable as follow as well as your ''LD_LIBRARY_PATH'':

<code>export PATH=$QTDIR/bin:$KDEDIR/bin:$PATH
export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH</code>

If you have any problem getting KDevelop running, please refer to the [http://www.kdevelop.org/phorum5/ KDevelop Forum] to find the answer to your problem.

If you never used KDevelop before, try to create a new project and to compile it to get used to the interface and the icons.

====KDevelop 3.4====
Please refer to [http://www.kdevelop.org/index.html?filename=3.4/download.html Downloading KDevelop 3.4] and [http://www.kdevelop.org/index.html?filename=3.4/branches_compiling.html Compiling KDevelop 3.4].

===Lexicon===
* '''Widget''': a widget is an element of an graphical interface such as a container window, a button or a field for entering text.
* '''Layout management''': this term describes the way in which widgets are arranged in a window. In its simplest form, an element may be placed at a specific position and given a specific height and width. But when the user resizes the window, the widgets should stay in their position and change their size accordingly. Linux allows to do that by using layouts to place the widgets in.
* '''Signal and Slots''': Signals and slots are used for communication between objects. The signal/slot mechanism is a central feature of Qt. Signals are emitted by objects when they change their state in a way that may be interesting to the outside world. Slots can be used for receiving signals, but they are normal member functions. You can connect as many signals as you want to a single slot, and a signal can be connected to as many slots as you desire. Please see the [http://doc.trolltech.com/3.3/signalsandslots.html TrollTech documentation on signals and slots] for more details. In the excellent online documentation that comes with Qt, you'll find the signals and the public slots that go with each class. You can then implement your own slots.

==Creating the Application==
===Starting the project===
====Creating the framework with KDevelop====

The framework in which our program will sit in (i.e. the main window) can be done easily and quickly by using KDevelop. Start KDevelop and select ''New Project'' in the Project menu. The Application Wizard appears then. Choose a ''C++ -> KDE -> Simple KDE Application''. Fill in the blank lines with the project name '''SigCreate''', your name as author, and your email. Refer to [[:Image:KDevelop3-CreateNewProject.png|this screen shot]] as a reference.

Click on ''Next''. Have a look to the CVS option and the header templates. Then click on ''Finish'' on the last screen. KDevelop creates all the files that you need to compile your project. You can use the file selector to view the code of the 3 files which are main.cpp, sigcreate.cpp and sigcreate.h, as shown [[:Image:KDevelop3-FileSelector.png|here]].

Once the ''Application Wizard'' has created your application, compile it to ensure that everything is fine. To do that, select '''Build -> Run automake & friends''' then '''Build -> Run configure'''. The ''Messages output window'' should say

<code>" Good - your configure finished. Start make now
*
* *** Success ***</code>

so you can run ''make'' with '''Build -> Build Project''' (or using the F8 shortcut). Then '''Build -> Install'''. Then '''Build -> Execute program''' (or F9). The result is shown [[:Image:KDevelop-SigCreate.png|here]].

*'''NOTE''' - If KDevelop does not recognize your ''QTDIR'' and ''KDEDIR'' variables, you can set them in '''Project -> Project Options...''' in ''Configure Options'', as [[:Image:KDevelop3-ConfigureOptions.png|shown]].

====Using Qt Designer====
Qt Designer is a tool for designing and implementing user interfaces. It helps you arranging your widgets on a form and adding a proper layout so your interface can be resized properly. I recommend that you read the [http://doc.trolltech.com/3.3/designer-manual.html Qt Designer manual] to know everything about Qt Designer. Qt Designer includes a code editor but we'll use KDevelop to edit and modify all code.

We will now create the interface of our application using Qt Designer. A form from Qt Designer is saved with a .ui extension because it is then processed by the uic program to generate a .h and .cpp files. KDevelop takes care of that, the only thing we need to do is to create the form.

* '''Note''' - Each time you add or remove a file (now we will add a .ui file) in your KDevelop project, the Makefile.am will be changed. KDevelop does that itself but you will need to ''Run automake & friends'' after such changes.

In KDevelop, click on '''File -> New''' and fill the dialog window that appears. First write the file name: ''sigcreatedlg'' and select what new file you want in the combobox: here we want a ''Widget (.ui)''. Please be sure that '''Add to project''' is checked, this ensures that the Makefile.am is updated. Refer to [[:Image:KDevelop3-NewFile-Widget.png|this screen shot]].

Click the ''OK'' button. The [[:Image:KDevelop3-AutomakeManagerDialog.png|Automake manager dialog]] then pops up. Click the ''OK'' button for this dialog as well.

If the new file ''sigcreatedlg.ui'' is not open in Qt Designer, open the ''Automake Manager'', right-click on the file and select ''Open With'', then ''Qt Designer''. Qt Designer will open.

* '''Note''' - About the names: it is a good idea to finish a dialog name or a form name by ''dlg'' to ensure a nice visibility for people who want to have a look at the code. ''sigcreatedlg'' says that it is a dialog, i.e an interface class, only.

The [[:Image:QtDesigner3-Interface.png|Qt Designer interface]] is essentially split into three areas. On the left is the '''toolbox''', where you can select your widgets. On the right, several dialogs can be selected. I'll keep only the '''Property Editor''' dialog (I close the 2 others). Your widgets can be fine tuned to behave how you want them to. You can choose the size of the widget, its background color (palette), and so on. Between those 2 windows is the '''Form''', your program window, within which you will design your user interface.

* '''Note''' - After adding the ''sigcreatedlg.ui'' file, you will have to run ''Automake & friends'' and ''Run configure'' before building the program. This ensures that the updated ''Makefile.am'' is now read.

===Designing the Program===

Each time you want to use Qt Designer, you should have a precise visual idea of the design of your interface. You can see in [[:Image:KDevelop3-SigCreateDialog.png|this picture]] what the program will be like. It is a window with a number of different items (or widgets) on it, designed so that the user puts the right information in the right boxes. You should always design your program from the user's point of view, as it must be easy to use.

This application creates an email signature, which is then displayed on the screen. The user should enter her/his name, email address, and then select one of three comments. When you click the '''Create!''' button, the generated signature is shown in a ''MultiLineEdit''. When you click '''Cancel''', the program quits.

* '''Note''' - Note that this project is meant as a tutorial, so this is somewhat far away from practical use.

Go back to the Qt Designer window with the new dialog open. You will see that the property editor has been filled with details about the form you have created. The first line in the '''Property Editor''' [[:Image:QtDesigner3-PropertyEditor.png|shows]] the name of the form which is Form1. Click on the field with this name to change it and type SigCreateDlg. This will form the class name of the dialog so you should name it something useful.

To change properties, select the property you wish to change, then alter its setting on the right. Change the '''Caption''' property to "SigCreateDlg v.01". We will now begin to add widgets on our dialog.

===Adding Widgets===

To start, we will insert the text at the top of the program window, which can be seen [[:Image:KDevelop3-NewFile-Widget.png|here]]. This text tells the user how to operate the program. This type of widget is called a ''Label'' and you can put one on your program like this:

# Select the dialog in ToolBox called '''Common Widgets->TextLabel''', or from the menubar '''Tools->Display->TextLabel'''
# The cursor will become a crosshair over the form. Draw a box for the label, just as you would in a paint program, and you will see that the label is created with some dummy text in it.
# To change this text, double click on the label and type in the text, instead of ''TextLabel1''. The text you should type is ''This program will create an email signature for you. Just fill in the boxes and hit the Create! button.'' Select '''Align Center'' to have the text positioned nicely. Refer to this [[:Image:QtDesigner3-TextEditDialog.png|screenshot]].
# Finally, resize the widget using the handles so it is the correct size and at the top of the box. Try to center the label by moving it with the mouse. This is just a temporary measure. Later on we will look at a more elegant layout management technique. You may refer to [[:Image:QtDesigner3-ResizingBox.png|this screenshot]].

You follow pretty much the same procedure for embedding any type of widget that is supported by Qt Designer; select it, drag it, and finally, change its properties and size.

An interesting concept in Qt Designer is that widgets can act as containers for other widgets. This will be demonstrated in our next task, which is to create the input fields inside the frame. You can see that in Picture 8 we have a bunch of labels and text boxes inside a frame. This frame is called a Group Box and acts as a container for the labels and text boxes inside it. Let's first create the frame by selecting the GroupBox in the '''Toolbox dialog->Containers''' or '''Tools->Containers->GroupBox''' from the menubar. You can drag the mouse to create the box just below the Label you put before. In the ''Property Editor'' you can change the title property to alter the text in the frame. Put ''Details'' in the title text field. You may notice a + symbol in this entry in the ''Property Editor''. This indicates that the property has subproperties that can also be changed.

Once you have created the frame (i.e the GroupBox), create three more labels as before but when you draw them, draw them inside the GroupBox frame. You can then see in the Object Explorer box ('''Windows menu -> Views -> Object Explorer''') to the right that the labels have become children of the GroupBox frame. See [[:Image:QtDesigner3-EditingTheDialog.png|this image]].

Change the text of labels by double-clicking on it.

Once you have done this you can then create the text boxes. They will allow the user to type in text like his(her) name and email address. We use the simplest type of text boxes: a widget called QLineEdit which allows the user to enter one line of text only. You have to create two QLineEdit widgets for the name and the email address. You choose the menu Tools then the entry Input then LineEdit and you draw it beside the 'Your Name' Label. Do the same below for the address.

The witty comment will be selected by the user. We use a ComboBox which will present the user with three comments. Click on the ComboBox icon or select it via the Tools-> Input-> ComboBox menu. Draw it beside the Witty Comment label. Then double-click on it. You will be presented with a box into which you can add the contents of the combo box. Click on the 'New Item' button and type in your comment in the text box at the right. Then click again on 'New Item' for the second and third comments. Click on OK when you have finished.

Adjust the size of the different widgets so they are nicely placed.

Up to now, we have not named any of the widgets that are being placed in our program. It is useful to set an internal name for widgets so we can call them after in the program. Labels don't perform any action so they don't need to be named but other widgets do. It is the case now for our text boxes. We'll need to manipulate the data from the three input widgets (i.e. read the text) so we should give them a name. Names should be easily recognized later and they should make sense. The names are assigned via the name property on the top of the Property Editor. We name the top LineEdit nameBox and the second one mailBox. We name the ComboBox commBox. This will allow us to access the comments. So click on each LineEdit and then besides Name in the Property Editor write nameBox and mailBox. Then click on the ComboBox and name it commBox.

We finish the graphical design by adding a label with 'Generated Signature' as text. Below it, we put a TextEdit ('''Tools->Input->TextEdit'''') where the generated signature will be displayed. We name it 'sigBox'. And then we add two PushButtons at the bottom ('Create!' and 'Cancel'). They don't need names but you can give them some if you want.

Save your form. You can now have a quick preview by selecting the menu '''Preview-> Preview Form'''. [[:Image:QtDesigner3-BeforeLayoutManagement.png|This]] is the form ''before'' layout management.

===Getting Spaced Out===
This section describes the layout management. If you resize the preview window you will then notice that the widgets do not adjust appropriately. They are not resized. To improve things, we need to use a feature in Qt called spacers. Spacers are like virtual springs that push the widgets on each side apart.
* '''Note''' - Having a good layout is essential for your application, as when the strings are translated, they might be longer than the English ones and they need to fit on your widgets. The geometry of the widgets has to be nice if the user can resize your window application. Layouts are done by trial and error so use '''Preview->Preview Form''' to see the result of your layout management and to achieve the best layout.

The use of spacers and layout management is a skill that is developed through trial and error. The main thing to remember when dealing with spacers is that you work horizontally first and then vertically.

We will first use spacers to center the text in the top box. Resize your label so that it only get the size of the text. Then we add two spacers, one at each side. Choose the 'spring' icon or menu '''Layout-> Add Spacer'''. You adjust each of the spacers horizontally. Click the space to the left of the text and the blue spacer will appear . Repeat the same procedure for the right. Then add a spacer on the right of the 'Generated Signature' label, and a last one on the left of the the 'Create!' pushbutton. Please use [[:Image:QtDesigner3-AddingTheSpacers.png|this image]] as a reference.

Now that we have spacers to fill blank space, we need a proper layout management. This will allow the widgets to be nicely resized whenever the main window is resized. It is really compulsory to have good layout management. Again, try to resize several times to see if everything is in place. We can use Vertical or horizontal layout or grid management. The top row of widget is horizontal (spacer + label + spacer) so we need Horizontal management. We need to select the three widgets alltogether: click on the first spring, then click on the label while holding down ''Shift'', then on the second spring while holding down ''Shift''. Then click on the Horizontal Layout icon or menu '''Layout-> Lay Out Horizontally'''. You will then see a resizable red line around the three objects to indicate that their layout is being managed. Resize the red box if it needs to.

We can now repeat this procedure for the three labels inside the GroupBox, this time using vertical layout management. The same vertical management for the two LineEdit and the ComboBox. It is better to use vertical management to keep the object aligned. If we use horizontal management for each label + text box then they will not stay aligned and equally sized. Horizontal management is needed for the label with the spacer and another one for the two pushbuttons and the spacer.

To finish the layout, we need to let the form look after the laid-out boxes. We put everything in a grid. This is done by right clicking the form and selecting "Lay Out in a Grid" from the menu. The final design with layout lines should resemble something similar to [[:Image:QtDesigner3-CompleteLayoutManagement.png|this image]].

===Signals and Slots===

[http://doc.trolltech.com/3.0/signalsandslots.html Signals and Slots] are used for communication between Qt objects. The signal/slot mechanism is a central feature of Qt and probably the part that differs most from other toolkits which often use callbacks. In Qt, a signal is emitted by a widget when a particular event occurs, very often triggered by the user like for example pressing a button or writing something in a LineEdit. A slot is simply a function that is called in reponse to a particular signal.

Now the widgets are implemented and the layout is arranged the final thing we need to do in the design stage of the form is to create the signal/slot connections. To do this manually requires a ''connect()'' function but Qt Designer provides a simple yet effective solution. To create the signal/slot connections we need to use the connecting tool. To do this either select the icon (it looks like a red arrow going into a green square) or select '''Tools-> Connect Signals/Slots''' from the menu (or use the F3 shortcut key). To create a connection, click on the form on the widget that is going to be dealing with the slot, drag the line off the form and release the mouse button.

Let's deal first with the Create! button. Click first on the '''Connect Signal/Slot''' icon or select it from the Tools menu or use the F3 key. Then click on the Create! button with the crosshair and drag the line off the form completely. When you have released the mouse button you will see the connections tool shown [[:Image:QtDesigner3-CreateSlot.png|here]].

What we want to do is to create a slot that will create our signature when the user clicks on the Create! button. The signal will be clicked() (you may choose among five signals for a QPushButton) and we need to create the slot then make the connection.

To create the slot we need to click on the '''Edit Slots''' button. The slot creation box then appears. See [[:Image:QtDesigner3-CreateSlot.png|this example]]. Now click on the '''New Function''' button and a slot will appear in the box. Instead of ''new_slot()'' rename it to ''slotCreateSig()'' and leave the access specifier as public. When you click on ''OK'' you will be returned to the connections box and you will see your new slot in the Slots section of the box.

To [[:Image:QtDesigner3-ViewandEditConnections.png|make a connection]] you simply select the appropriate signal (which is ''clicked()'' in our case) and then select the slot (which is our new slot ''slotCreateSig()''). When you have selected both signal and slot you will see the connection made at the bottom of the screen. After you are finished click OK.

Repeat the procedure for the Cancel button by using the clicked() signal and the close() slot. You are now done with the signals and slots.
* '''Warning''' - Don't forget to save your form!

===Generating the Source===

In this tutorial, we use KDevelop subclassing tool in Automake Manager. If you have KDevelop version which has not that capability, then please go to Chapter 7 where I explain this step without the subclass tool.

Here we start with the KDE simple project named SigCreate and the sigcreatedlg.ui that we have added in our project. In the Automake Manager, in the section sigcreate (Program in bin) you must have three files: sigcreatedlg.ui, sigcreate.cpp and main.cpp. The project must compile and give the main window as in picture 3 (creating.html).

As the sigcreate class is no use for us, we will remove it and use it for subclassing the sigcreatedlg.ui file. In the Automake Manager, right click on sigcreate.cpp and select Remove and a dialog pops up. Please check 'Also Remove it from disk'. Then do the same with sigcreate.h. This is the way to remove obsolete files from your project and the Makefile.am will be updated. Remember to run automake & friends and configure before compiling your project again. We will not do it right now because we will make other changes. We will now use the class name SigCreate for the subclass.

In the Automake Manager, in sigcreate (program in bin), right click on sigcreatedlg.ui and choose Subclass Widget... from the context menu that appears. Then fill in the subclass name which is SigCreate. Check the box: Reformat source and click on OK. Say No then about adding these files in cvs as we did not enable this in our project.
Note
You can see that the slot we created in designer is listed here and checked, the method will be implemented in the generated files. If you uncheck it, the code will not be generated in your class.

(The subclass dialog Image)

We have to suppress some lines in main.cpp as the KDE simple project template refers to a KMainWindow which is usually the base class used. But here, SigCreate is based on QWidget. You have to remove all the lines between KApplication app; and return app.exec(); except the ones I keep here:

<code>SigCreate *mainWin = 0;

mainWin = new SigCreate();
app.setMainWidget( mainWin );
mainWin->show();
</code>

===Implementing the Slot===

==In Short==
==Make the translations for a simple kde project==
==A few general tips==
==Generating the source (alternate)==
==Credits and License==

Development/Tutorials/Localization/i18n Mistakes

2007-01-10T02:42:10Z

CuCullin: /* Pitfall #1: Pixel Based Layouts */ Proofreading - "compared"

{{TutorialBrowser|

series=Localization|

name=Avoiding Common Localization Pitfalls|

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

next=[[Development/Tutorials/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 much 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 [[http://doc.trolltech.com/qlayout.html 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 QString::arg() which lets the translator 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. Because of this latter advantage, QString::arg() is also recommended to use instead of sprintf and similar functions.

The above example written properly would then look like this:

<code cppqt>QString msg=i18n("Do you want to replace %1 with %2?").arg(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.}}

Similarly, messages that contain a version string or other often changing parts should use QString::arg() to insert them 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 which does not use 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/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).}}

== 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]]

Development/Architecture/KDE4/KParts

2007-01-10T02:38:58Z

CuCullin: Category KDE4

'''KParts''' is the name of the component framework for KDE. An individual component is called a '''KPart'''. As an example, Konsole is available as a KPart and is used in applications like Konqueror and Kate. Good examples about how KParts can be used are Konqueror, which (among other things) uses the KWord part to display documents, KMPlayer part to play multimedia, and Kontact, which embeds kdepim applications under one roof.

===Further reading===
* [http://api.kde.org/cvs-api/kdelibs-apidocs/kparts/html/index.html KParts API Reference]
* [http://api.kde.org/cvs-api/kdelibs-apidocs/kparts/html/classKParts_1_1Part.html KParts Class Reference]
* [http://www-106.ibm.com/developerworks/library/l-kparts/ Coding with KParts] (from IBM)

[[Category:KDE4]]

Development/Architecture/KDE4

2007-01-10T02:38:28Z

CuCullin: Category KDE4

[[/KParts|KParts]]
[[Category:KDE4]]

Development/Architecture/KDE3/XMLGUI Technology

2007-01-10T02:37:34Z

CuCullin: Category KDE3

'''Defining the menu and toolbar structure in XML'''

== Introduction ==

While the [[../Action_Pattern|action pattern]] allows to encapsulate
actions triggered by the user in an object which can be "plugged" somewhere in
the menu bars or toolbars, it does not by itself solve the problem of
constructing the menus themselves. In particular, you have build all popup menus
in C++ code and explicitly insert the actions in a certain order, under
consideration of the style guide for standard actions. This makes it pretty
difficult to allow the user to customize the menus or change shortcuts to
fit his needs, without changing the source code.

This problem is solved by a set of classes called ''XMLGUI''. Basically,
this separates actions (coded in C++) from their appearance in menu bars
and tool bars (coded in XML). Without modifying any source code, menus
can be simply customized by adjusting an XML file. Furthermore, it helps
to make sure that standard actions (such as <tt>File->Open</tt> or
<tt>Help->About</tt>) appear in the locations suggested by the style guide.
XMLGUI is especially important for modular programs, where the items
appearing in the menu bar may come from many different plugins or parts.

KDE's class for toplevel windows,
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KMainWindow],
inherits
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdeui/html/classKMainWindow.html KXMLGUIClient]
and therefore supports XMLGUI out of the box. All actions created within it must
have the client's actionCollection() as parent. A call to createGUI() will then
build the whole set of menu and tool bars defined the applications XML file
(conventionally with the suffix ui.rc).

== An example: Menu in KView ==

In the following, we take KDE's image view KView as example. It has a ui.rc
file kviewui.rc, which is installed with the Makefile.am snippet

rcdir = $(kde_datadir)/kview
rc_DATA = kviewui.rc

Here is an excerpt from the kviewui.rc file. For simplicity, we show
only the definition of the View menu.
<code xml>
<!DOCTYPE kpartgui>
<kpartgui name="kview">
<MenuBar>
<Menu name="view" >
<Action name="zoom50" />
<Action name="zoom100" />
<Action name="zoom200" />
<Action name="zoomMaxpect" />
<Separator/>
<Action name="fullscreen" />
</Menu>
</MenuBar>
</kpartgui>
</code>

The corresponding part of the setup in C++ is:

<code cppqt3>
KStdAction::zoomIn (this, SLOT(slotZoomIn()), actionCollection());
KStdAction::zoomOut(this, SLOT(slotZoomOut()), actionCollection());
KStdAction::zoom (this, SLOT(slotZoom()), actionCollection());
new KAction (i18n("&Half size"), ALT+Key_0,
this, SLOT(slotHalfSize()),
actionCollection(), "zoom50");
new KAction (i18n("&Normal size"), ALT+Key_1,
this, SLOT(slotDoubleSize()),
actionCollection(), "zoom100");
new KAction (i18n("&Double size"), ALT+Key_2,
this, SLOT(slotDoubleSize()),
actionCollection(), "zoom200");
new KAction (i18n("&Fill Screen"), ALT+Key_3,
this, SLOT(slotFillScreen()),
actionCollection(), "zoomMaxpect");
new KAction (i18n("Fullscreen &Mode"), CTRL+SHIFT+Key_F,
this, SLOT(slotFullScreen()),
actionCollection(), "fullscreen");
</code>

The View menu resulting from this GUI definition looks like in this
screenshot:

[[Image:k3view-menu.png|frame|center|KView menu screenshot]]

The XML file begins with a document type declaration. The DTD for kpartgui can
be found in the kdelibs sources in {{path|kdeui/kpartgui.dtd}}. The outermost
element of the file contains the instance name of the application as attribute.
It can also contain a version number in the form "version=2". This is useful
when you release new versions of an application with a changed menu structure,
e.g. with more features. If you bump up the version number of the {{path|ui.rc}} file,
KDE makes sure that any customized version of the file is discarded and the new
file is used instead.

The next line, <MenuBar> contains a declaration of a menu bar. You can
also insert any number of <ToolBar> declarations in order to create some
tool bars. The menu contains a submenu with the name "view". This name is
already predefined, and thus you see a translated version of the word "View"
in the screenshot. If you declare your own submenus, you have to add the title
explicitly. For example, KView has a submenu with the title "Image" which is
declared as follows:

<code xml>
<Menu name="image">
<text>&Image</text>
...
</Menu>
</code>

In KDE's automake framework, such titles are automatically extracted and put
into the application's [kde-i18n-howto.html <tt>.po</tt>] file, so
it is considered by translators. Note that you have to write the accelerator
marker "&" in the form XML compliant form "&&".

Let us come back to the example. KView's View menu contains a couple of custom
actions: zoom50, zoom100, zoom200, zoomMaxpect and fullscreen, declared with a
<Action> element. The separator in the screenshots corresponds with the
<Separator> element.

You will note that some menu items do not not have a corresponding element in
the XML file. These are ''standard actions''. Standard actions are created by
the class
[http://api.kde.org/3.5-api/kdelibs-apidocs/kdeui/html/kstdaction_8h-source.html KStdAction].
When you create such actions in your application (such as in the C++ example
above), they will automatically be inserted in a prescribed position, and
possibly with an icon and a shortcut key. You can look up these locations in
the file <tt>kdeui/ui_standards.rc</tt> in the kdelibs sources.

== An example: Toolbars in Konqueror ==

For the discussion of toolbars, we switch to Konqueror's GUI
definition. This excerpt defines the location bar, which contains the input
field for URLs.

<code xml>
<ToolBar name="locationToolBar" fullWidth="true" newline="true" >
<text>Location Toolbar</text>
<Action name="clear_location" />
<Action name="location_label" />
<Action name="toolbar_url_combo" />
<Action name="go_url" />
</ToolBar>
</code>

The first thing we notice is that there are a lot more attributes than for
menu bars. These include:

*'''<tt>fullWidth</tt>''': Tells XMLGUI that the toolbar has the same width as the toplevel window. Af this is "false", the toolbar only takes as much space as necessary, and further toolbars are put in the same row.
*'''<tt>newline</tt>''': This is related to the option above. If newline is "true", the toolbar starts a new row. Otherwise it may be put in the row together with the previous toolbar.
*'''<tt>noEdit</tt>''': Normally toolbars can be customized by the user, e.g. in <tt>Settings->Configure Toolbars</tt> in Konqueror. Setting this option to "true" marks this toolbar as not editable. This is important for toolbars which are filled with items at runtime, e.g. Konqueror's bookmark toolbar.
*'''<tt>iconText</tt>''': Tells XMLGUI to show the text of the action next to the icon. Normally, the text is only shown as a tooltip when the mouse cursor remains over the icon for a while. Possible values for this attribute are "icononly" (shows only the icon), "textonly" (shows only the text), "icontextright" (shows the text on the right side of the icon) and "icontextbottom" (shows the text beneath the icon).
*'''<tt>hidden</tt>''': If this is "true", the toolbar is not visible initially and must be activated by some menu item.
*'''<tt>position</tt>''': The default for this attribute is "top", meaning that the toolbar is positioned under the menu bar. For programs with many tools, such as graphics programs, it may be interesting to replace this with "left", "right" or "bottom".

== Dynamical menus ==

Obviously, an XML can only contain a static description of a user interface.
Often, there are menus which change at runtime. For example, Konqueror's
<tt>Location</tt> menu contains a set of items <tt>Open with Foo</tt> with
the applications able to load a file with a given MIME type. Each time the
document shown changes, the list of menu items is updated. XMLGUI is prepared
to handle such cases with the notion of ''action lists''. An action list
is declared as one item in the XML file, but consists of several actions which
are plugged into the menu at runtime. The above example is implemented with
the following declaration in Konqueror's XML file:

<code xml>
<Menu name="file">
<text>&Location</text>
...
<ActionList name="openwith">
...
</Menu>
</code>

The function KXMLGUIClient::plugActionList() is then used to add actions to be
displayed, whereas the function KXMLGuiClient::unplugActionList() removes all
plugged actions. The routine responsible for updating looks as follows:

<code cppqt3>
void MainWindow::updateOpenWithActions()
{
unplugActionList("openwith");
openWithActions.clear();
for ( /* iterate over the relevant services */ ) {
KAction *action = new KAction( ...);
openWithActions.append(action);
}
plugActionList("openwith", openWithActions);
}
</code>

Note that in contrast to the static actions, the ones created here are
''not'' constructed with the action collection as parent, and you are
responsible for deleting them for yourself. The simplest way to achieve this
is by using <tt>openWithActions.setAutoDelete(true)</tt> in the above
example.

Also note that to be able to extend menus this way, you need to call
<tt>createGUI()</tt> with the second parameter (conserveMemory) set to "false".
If you don't, you won't get any error but your actions won't appear in the
menu.

== Context menus ==

The examples above only contained cases where a main window's menubar and
toolbars were created. In the cases, the processes of constructing these
containers is completely hidden from you behind the createGUI() call
(except if you have custom containers). However, there are cases, where
you want to construct other containers and populate them with GUI definitions
from the XML file. One such example are context menus. In order to get a
pointer to a context menu, you have to ask the client's factory for it:

<code cppqt3>
void MainWindow::popupRequested()
{
QWidget *w = factory()->container("context_popup", this);
QPopupMenu *popup = static_cast<QPopupMenu *>;(w);
popup->exec(QCursor::pos());
}
</code>

The method KXMLGUIFactory::container() used above looks whether it finds a
container in the XML file with the given name. Thus, a possible definition
could look as follows:

<code xml>
...
<Menu name="context_popup">
<Action name="file_add"/>
<Action name="file_remove"/>
</Menu>
...
</code>

''Initial Author:'' [mailto:bernd@kdevelop.org Bernd Gehrmann]

[[Category:KDE3]]