File indexing completed on 2024-12-01 09:48:11

0001 /*
0002     klangbutton.h - Button with language selection drop down menu.
0003                     Derived from the KLangCombo class by Hans Petter Bieker.
0004 
0005     SPDX-FileCopyrightText: 1999-2003 Hans Petter Bieker <bieker@kde.org>
0006     SPDX-FileCopyrightText: 2001 Martijn Klingens <klingens@kde.org>
0007     SPDX-FileCopyrightText: 2007 David Jarvie <djarvie@kde.org>
0008 
0009     SPDX-License-Identifier: LGPL-2.0-or-later
0010 */
0011 
0012 #ifndef KLANGUAGEBUTTON_H
0013 #define KLANGUAGEBUTTON_H
0014 
0015 #include "kconfigwidgets_export.h"
0016 #include <QWidget>
0017 #include <memory>
0018 
0019 class QAction;
0020 class KLanguageButtonPrivate;
0021 
0022 /**
0023  * @class KLanguageButton klanguagebutton.h KLanguageButton
0024  *
0025  * KLanguageButton is a pushbutton which allows a language to be selected from
0026  * a popup list.
0027  *
0028  * Languages are identified by their ISO 639-1 codes, e.g. en, pt_BR.
0029  *
0030  * \image html klanguagebutton.png "KDE Language Selection Widget"
0031  *
0032  * @author Hans Petter Bieker <bieker@kde.org>, Martijn Klingens <klingens@kde.org>,
0033  *         David Jarvie <djarvie@kde.org>
0034  */
0035 class KCONFIGWIDGETS_EXPORT KLanguageButton : public QWidget
0036 {
0037     Q_OBJECT
0038 
0039 public:
0040     /**
0041      * Constructs a button whose text is determined by the current language
0042      * in the popup list.
0043      *
0044      * @param parent the parent of the button
0045      */
0046     explicit KLanguageButton(QWidget *parent = nullptr);
0047 
0048     /**
0049      * Constructs a button with static text.
0050      *
0051      * @param text the text of the button
0052      * @param parent the parent of the button
0053      */
0054     explicit KLanguageButton(const QString &text, QWidget *parent = nullptr);
0055 
0056     /**
0057      * Deconstructor
0058      */
0059     ~KLanguageButton() override;
0060 
0061     /**
0062      * Sets the locale to display language names. By default, QLocale::system().name() is used.
0063      *
0064      * @param locale locale to use
0065      */
0066     void setLocale(const QString &locale);
0067 
0068     /**
0069      * Sets a static button text.
0070      *
0071      * @param text button text
0072      */
0073     void setText(const QString &text);
0074 
0075     /**
0076      * Specifies whether language codes should be shown alongside language names
0077      * in the popup. Calling this method does not affect any previously
0078      * inserted language texts, so it should normally be called before
0079      * populating the list.
0080      *
0081      * @param show true to show codes, false to hide codes
0082      */
0083     void showLanguageCodes(bool show);
0084 
0085     /**
0086      * Load all known languages into the popup list.
0087      * The current language in the list is set to the default language for the
0088      * current locale (as modified by setLocale()).
0089      */
0090     void loadAllLanguages();
0091 
0092     /**
0093      * Inserts a language into the combo box.
0094      * Normally the display name of the language is obtained automatically, but
0095      * if either the language code does not exist, or there are special display
0096      * requirements, the name of the language can be specified in @p name.
0097      *
0098      * @param languageCode the code for the language
0099      * @param name language name. If empty, the name is obtained automatically.
0100      * @param index the insertion position, or -1 to insert in alphabetical order
0101      */
0102     void insertLanguage(const QString &languageCode, const QString &name = QString(), int index = -1);
0103 
0104     /**
0105      * Inserts a separator item into the combo box. A negative index will append the item.
0106      *
0107      * @param index the insertion position
0108      */
0109     void insertSeparator(int index = -1);
0110 
0111     /**
0112      * Returns the number of items in the combo box.
0113      */
0114     int count() const;
0115 
0116     /**
0117      * Removes all combobox items.
0118      */
0119     void clear();
0120 
0121     /**
0122      * Returns the language code of the combobox's current item.
0123      *
0124      * @return the current item's language code
0125      */
0126     QString current() const;
0127 
0128     /**
0129      * Checks whether the specified language is in the popup list.
0130      *
0131      * @param languageCode the language's code
0132      * @return true if in the list
0133      */
0134     bool contains(const QString &languageCode) const;
0135 
0136     /**
0137      * Sets a given language to be the current item.
0138      *
0139      * @param languageCode the language's code
0140      */
0141     void setCurrentItem(const QString &languageCode);
0142 
0143 Q_SIGNALS:
0144     /**
0145      * This signal is emitted when a new item is activated.
0146      *
0147      * @param languageCode code of the activated language
0148      */
0149     void activated(const QString &languageCode);
0150     /**
0151      * This signal is emitted when a new item is highlighted.
0152      *
0153      * @param languageCode code of the highlighted language
0154      */
0155     void highlighted(const QString &languageCode);
0156 
0157 private Q_SLOTS:
0158     KCONFIGWIDGETS_NO_EXPORT void slotTriggered(QAction *action);
0159     KCONFIGWIDGETS_NO_EXPORT void slotHovered(QAction *action);
0160 
0161 private:
0162     friend class KLanguageButtonPrivate;
0163     std::unique_ptr<KLanguageButtonPrivate> const d;
0164 };
0165 
0166 #endif