1/*
2 * klangbutton.h - Button with language selection drop down menu.
3 * Derived from the KLangCombo class by Hans Petter Bieker.
4 *
5 * Copyright (c) 1999-2003 Hans Petter Bieker <bieker@kde.org>
6 * (c) 2001 Martijn Klingens <klingens@kde.org>
7 * (c) 2007 David Jarvie <software@astrojar.org.uk>
8 *
9 * This library is free software; you can redistribute it and/or
10 * modify it under the terms of the GNU Library General Public
11 * License as published by the Free Software Foundation; either
12 * version 2 of the License, or (at your option) any later version.
13 *
14 * This library is distributed in the hope that it will be useful,
15 * but WITHOUT ANY WARRANTY; without even the implied warranty of
16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 * Library General Public License for more details.
18 *
19 * You should have received a copy of the GNU Library General Public License
20 * along with this library; see the file COPYING.LIB. If not, write to
21 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
22 * Boston, MA 02110-1301, USA.
23 */
24
25#ifndef KLANGUAGEBUTTON_H
26#define KLANGUAGEBUTTON_H
27
28#include <kdeui_export.h>
29#include <QtGui/QWidget>
30
31class QAction;
32class KLocale;
33class KLanguageButtonPrivate;
34
35/**
36 * KLanguageButton is a pushbutton which allows a language to be selected from
37 * a popup list.
38 *
39 * Languages are identified by their ISO 639-1 codes, e.g. en, pt_BR.
40 *
41 * \image html klanguagebutton.png "KDE Language Selection Widget"
42 *
43 * @author Hans Petter Bieker <bieker@kde.org>, Martijn Klingens <klingens@kde.org>,
44 * David Jarvie <software@astrojar.org.uk>
45 */
46class KDEUI_EXPORT KLanguageButton : public QWidget
47{
48 Q_OBJECT
49
50public:
51 /**
52 * Constructs a button whose text is determined by the current language
53 * in the popup list.
54 *
55 * @param parent the parent of the button
56 */
57 explicit KLanguageButton(QWidget * parent = 0);
58
59 /**
60 * Constructs a button with static text.
61 *
62 * @param text the text of the button
63 * @param parent the parent of the button
64 */
65 explicit KLanguageButton(const QString & text, QWidget * parent = 0 );
66
67 /**
68 * Deconstructor
69 */
70 virtual ~KLanguageButton();
71
72 /**
73 * Sets the locale to display language names. By default, KGlobal::locale() is used.
74 *
75 * @param locale locale to use
76 */
77 void setLocale( const KLocale *locale );
78
79 /**
80 * Sets a static button text.
81 *
82 * @param text button text
83 */
84 void setText( const QString &text );
85
86 /**
87 * Specifies whether language codes should be shown alongside language names
88 * in the popup. Calling this method does not affect any previously
89 * inserted language texts, so it should normally be called before
90 * populating the list.
91 *
92 * @param show true to show codes, false to hide codes
93 */
94 void showLanguageCodes( bool show );
95
96 /**
97 * Load all known languages into the popup list.
98 * The current language in the list is set to the default language for the
99 * current locale (as modified by setLocale()).
100 */
101 void loadAllLanguages();
102
103 /**
104 * Inserts a language into the combo box.
105 * Normally the display name of the language is obtained automatically, but
106 * if either the language code does not exist, or there are special display
107 * requirements, the name of the language can be specified in @p name.
108 *
109 * @param languageCode the code for the language
110 * @param name language name. If empty, the name is obtained automatically.
111 * @param index the insertion position, or -1 to insert in alphabetical order
112 */
113 void insertLanguage( const QString &languageCode, const QString &name = QString(), int index = -1 );
114
115 /**
116 * Inserts a separator item into the combo box. A negative index will append the item.
117 *
118 * @param index the insertion position
119 */
120 void insertSeparator( int index = -1 );
121
122 /**
123 * Returns the number of items in the combo box.
124 */
125 int count() const;
126
127 /**
128 * Removes all combobox items.
129 */
130 void clear();
131
132 /**
133 * Returns the language code of the combobox's current item.
134 *
135 * @return the current item's language code
136 */
137 QString current() const;
138
139 /**
140 * Checks whether the specified language is in the popup list.
141 *
142 * @param languageCode the language's code
143 * @return true if in the list
144 */
145 bool contains( const QString &languageCode ) const;
146
147 /**
148 * Sets a given language to be the current item.
149 *
150 * @param languageCode the language's code
151 */
152 void setCurrentItem( const QString &languageCode );
153
154Q_SIGNALS:
155 /**
156 * This signal is emitted when a new item is activated.
157 *
158 * @param languageCode code of the activated language
159 */
160 void activated( const QString &languageCode );
161 /**
162 * This signal is emitted when a new item is highlighted.
163 *
164 * @param languageCode code of the highlighted language
165 */
166 void highlighted( const QString &languageCode );
167
168private Q_SLOTS:
169 void slotTriggered( QAction* );
170 void slotHovered( QAction* );
171
172private:
173 KLanguageButtonPrivate * const d;
174};
175
176#endif
177