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 "kritawidgetutils_export.h"
29 #include <QWidget>
30 
31 class QAction;
32 class KLanguageButtonPrivate;
33 
34 /**
35  * KLanguageButton is a pushbutton which allows a language to be selected from
36  * a popup list.
37  *
38  * Languages are identified by their ISO 639-1 codes, e.g. en, pt_BR.
39  *
40  * \image html klanguagebutton.png "KDE Language Selection Widget"
41  *
42  * @author Hans Petter Bieker <bieker@kde.org>, Martijn Klingens <klingens@kde.org>,
43  *         David Jarvie <software@astrojar.org.uk>
44  */
45 class KRITAWIDGETUTILS_EXPORT KLanguageButton : public QWidget
46 {
47     Q_OBJECT
48 
49 public:
50     /**
51      * Constructs a button whose text is determined by the current language
52      * in the popup list.
53      *
54      * @param parent the parent of the button
55      */
56     explicit KLanguageButton(QWidget *parent = 0);
57 
58     /**
59      * Constructs a button with static text.
60      *
61      * @param text the text of the button
62      * @param parent the parent of the button
63      */
64     explicit KLanguageButton(const QString &text, QWidget *parent = 0);
65 
66     /**
67      * Deconstructor
68      */
69     ~KLanguageButton() override;
70 
71     /**
72      * Sets the locale to display language names. By default, QLocale::system().name() is used.
73      *
74      * @param locale locale to use
75      */
76     void setLocale(const QString &locale);
77 
78     /**
79      * Sets a static button text.
80      *
81      * @param text button text
82      */
83     void setText(const QString &text);
84 
85     /**
86      * Specifies whether language codes should be shown alongside language names
87      * in the popup. Calling this method does not affect any previously
88      * inserted language texts, so it should normally be called before
89      * populating the list.
90      *
91      * @param show true to show codes, false to hide codes
92      */
93     void showLanguageCodes(bool show);
94 
95     /**
96      * Load all known languages into the popup list.
97      * The current language in the list is set to the default language for the
98      * current locale (as modified by setLocale()).
99      */
100     void loadAllLanguages();
101 
102     /**
103      * Inserts a language into the combo box.
104      * Normally the display name of the language is obtained automatically, but
105      * if either the language code does not exist, or there are special display
106      * requirements, the name of the language can be specified in @p name.
107      *
108      * @param languageCode the code for the language
109      * @param name language name. If empty, the name is obtained automatically.
110      * @param index the insertion position, or -1 to insert in alphabetical order
111      */
112     void insertLanguage(const QString &languageCode, const QString &name = QString(), int index = -1);
113 
114     /**
115      * Inserts a separator item into the combo box. A negative index will append the item.
116      *
117      * @param index the insertion position
118      */
119     void insertSeparator(int index = -1);
120 
121     /**
122      * Returns the number of items in the combo box.
123      */
124     int count() const;
125 
126     /**
127      * Removes all combobox items.
128      */
129     void clear();
130 
131     /**
132      * Returns the language code of the combobox's current item.
133      *
134      * @return the current item's language code
135      */
136     QString current() const;
137 
138     /**
139      * Checks whether the specified language is in the popup list.
140      *
141      * @param languageCode the language's code
142      * @return true if in the list
143      */
144     bool contains(const QString &languageCode) const;
145 
146     /**
147      * Sets a given language to be the current item.
148      *
149      * @param languageCode the language's code
150      */
151     void setCurrentItem(const QString &languageCode);
152 
153 Q_SIGNALS:
154     /**
155      * This signal is emitted when a new item is activated.
156      *
157      * @param languageCode code of the activated language
158      */
159     void activated(const QString &languageCode);
160     /**
161      * This signal is emitted when a new item is highlighted.
162      *
163      * @param languageCode code of the highlighted language
164      */
165     void highlighted(const QString &languageCode);
166 
167 private Q_SLOTS:
168     void slotTriggered(QAction *);
169     void slotHovered(QAction *);
170 
171 private:
172     KLanguageButtonPrivate *const d;
173 };
174 
175 #endif
176