| /**************************************************************************** |
| ** |
| ** Copyright (C) 2016 The Qt Company Ltd. |
| ** Contact: https://www.qt.io/licensing/ |
| ** |
| ** This file is part of the documentation of the Qt Toolkit. |
| ** |
| ** $QT_BEGIN_LICENSE:FDL$ |
| ** Commercial License Usage |
| ** Licensees holding valid commercial Qt licenses may use this file in |
| ** accordance with the commercial license agreement provided with the |
| ** Software or, alternatively, in accordance with the terms contained in |
| ** a written agreement between you and The Qt Company. For licensing terms |
| ** and conditions see https://www.qt.io/terms-conditions. For further |
| ** information use the contact form at https://www.qt.io/contact-us. |
| ** |
| ** GNU Free Documentation License Usage |
| ** Alternatively, this file may be used under the terms of the GNU Free |
| ** Documentation License version 1.3 as published by the Free Software |
| ** Foundation and appearing in the file included in the packaging of |
| ** this file. Please review the following information to ensure |
| ** the GNU Free Documentation License version 1.3 requirements |
| ** will be met: https://www.gnu.org/licenses/fdl-1.3.html. |
| ** $QT_END_LICENSE$ |
| ** |
| ****************************************************************************/ |
| |
| /*! |
| \example widgets/charactermap |
| \title Character Map Example |
| \ingroup examples-widgets |
| \brief The Character Map example shows how to create a custom widget that can |
| both display its own content and respond to user input. |
| |
| The example displays an array of characters which the user can click on |
| to enter text in a line edit. The contents of the line edit can then be |
| copied into the clipboard, and pasted into other applications. The |
| purpose behind this sort of tool is to allow users to enter characters |
| that may be unavailable or difficult to locate on their keyboards. |
| |
| \borderedimage charactermap-example.png |
| \caption Screenshot of the Character Map example |
| |
| The example consists of the following classes: |
| |
| \list |
| \li \c CharacterWidget displays the available characters in the current |
| font and style. |
| \li \c MainWindow provides a standard main window that contains font and |
| style information, a view onto the characters, a line edit, and a push |
| button for submitting text to the clipboard. |
| \endlist |
| |
| \section1 CharacterWidget Class Definition |
| |
| The \c CharacterWidget class is used to display an array of characters in |
| a user-specified font and style. For flexibility, we subclass QWidget and |
| reimplement only the functions that we need to provide basic rendering |
| and interaction features. |
| |
| The class definition looks like this: |
| |
| \snippet widgets/charactermap/characterwidget.h 0 |
| |
| The widget does not contain any other widgets, so it must provide its own |
| size hint to allow its contents to be displayed correctly. |
| We reimplement \l{QWidget::paintEvent()} to draw custom content. We also |
| reimplement \l{QWidget::mousePressEvent()} to allow the user to interact |
| with the widget. |
| |
| The updateFont() and updateStyle() slots are used to update the font and |
| style of the characters in the widget whenever the user changes the |
| settings in the application. |
| The class defines the characterSelected() signal so that other parts |
| of the application are informed whenever the user selects a character in |
| the widget. |
| As a courtesy, the widget provides a tooltip that shows the current |
| character value. We reimplement the \l{QWidget::mouseMoveEvent()} event |
| handler and define showToolTip() to enable this feature. |
| |
| The \c columns, \c displayFont and \c currentKey private data members |
| are used to record the number of columns to be shown, the current font, |
| and the currently highlighted character in the widget. |
| |
| \section1 CharacterWidget Class Implementation |
| |
| Since the widget is to be used as a simple canvas, the constructor just |
| calls the base class constructor and defines some default values for |
| private data members. |
| |
| \snippet widgets/charactermap/characterwidget.cpp 0 |
| |
| We initialize \c currentKey with a value of -1 to indicate |
| that no character is initially selected. We enable mouse tracking to |
| allow us to follow the movement of the cursor across the widget. |
| |
| The class provides two functions to allow the font and style to be set up. |
| Each of these modify the widget's display font and call update(): |
| |
| \snippet widgets/charactermap/characterwidget.cpp 1 |
| \codeline |
| \snippet widgets/charactermap/characterwidget.cpp 2 |
| |
| We use a fixed size font for the display. Similarly, a fixed size hint is |
| provided by the sizeHint() function: |
| |
| \snippet widgets/charactermap/characterwidget.cpp 3 |
| |
| Three standard event functions are implemented so that the widget |
| can respond to clicks, provide tooltips, and render the available |
| characters. The paintEvent() shows how the contents of the widget are |
| arranged and displayed: |
| |
| \snippet widgets/charactermap/characterwidget.cpp 6 |
| |
| A QPainter is created for the widget and, in all cases, we ensure that the |
| widget's background is painted. The painter's font is set to the |
| user-specified display font. |
| |
| The area of the widget that needs to be redrawn is used to determine which |
| characters need to be displayed: |
| |
| \snippet widgets/charactermap/characterwidget.cpp 7 |
| |
| Using integer division, we obtain the row and column numbers of each |
| characters that should be displayed, and we draw a square on the widget |
| for each character displayed. |
| |
| \snippet widgets/charactermap/characterwidget.cpp 8 |
| \snippet widgets/charactermap/characterwidget.cpp 9 |
| |
| The symbols for each character in the array are drawn within each square, |
| with the symbol for the most recently selected character displayed in red: |
| |
| \snippet widgets/charactermap/characterwidget.cpp 10 |
| |
| We do not need to take into account the difference between the area |
| displayed in the viewport and the area we are drawing on because |
| everything outside the visible area will be clipped. |
| |
| The mousePressEvent() defines how the widget responds to mouse clicks. |
| |
| \snippet widgets/charactermap/characterwidget.cpp 5 |
| |
| We are only interested when the user clicks with the left mouse button |
| over the widget. When this happens, we calculate which character was |
| selected and emit the characterSelected() signal. |
| The character's number is found by dividing the x and y-coordinates of |
| the click by the size of each character's grid square. Since the number |
| of columns in the widget is defined by the \c columns variable, we |
| simply multiply the row index by that value and add the column number |
| to obtain the character number. |
| |
| If any other mouse button is pressed, the event is passed on to the |
| QWidget base class. This ensures that the event can be handled properly |
| by any other interested widgets. |
| |
| The mouseMoveEvent() maps the mouse cursor's position in global |
| coordinates to widget coordinates, and determines the character that |
| was clicked by performing the calculation |
| |
| \snippet widgets/charactermap/characterwidget.cpp 4 |
| |
| The tooltip is given a position defined in global coordinates. |
| |
| \section1 MainWindow Class Definition |
| |
| The \c MainWindow class provides a minimal user interface for the example, |
| with only a constructor, slots that respond to signals emitted by standard |
| widgets, and some convenience functions that are used to set up the user |
| interface. |
| |
| The class definition looks like this: |
| |
| \snippet widgets/charactermap/mainwindow.h 0 |
| |
| The main window contains various widgets that are used to control how |
| the characters will be displayed, and defines the findFonts() function |
| for clarity and convenience. The findStyles() slot is used by the widgets |
| to determine the styles that are available, insertCharacter() inserts |
| a user-selected character into the window's line edit, and |
| updateClipboard() synchronizes the clipboard with the contents of the |
| line edit. |
| |
| \section1 MainWindow Class Implementation |
| |
| In the constructor, we set up the window's central widget and fill it with |
| some standard widgets (two comboboxes, a line edit, and a push button). |
| We also construct a CharacterWidget custom widget, and add a QScrollArea |
| so that we can view its contents: |
| |
| \snippet widgets/charactermap/mainwindow.cpp 0 |
| |
| QScrollArea provides a viewport onto the \c CharacterWidget when we set |
| its widget and handles much of the work needed to provide a scrolling |
| viewport. |
| |
| The font combo box is automatically popuplated with a list of available |
| fonts. We list the available styles for the current font in the style |
| combobox using the following function: |
| |
| \snippet widgets/charactermap/mainwindow.cpp 1 |
| |
| The line edit and push button are used to supply text to the clipboard: |
| |
| \snippet widgets/charactermap/mainwindow.cpp 2 |
| |
| We also obtain a clipboard object so that we can send text entered by the |
| user to other applications. |
| |
| Most of the signals emitted in the example come from standard widgets. |
| We connect these signals to slots in this class, and to the slots provided |
| by other widgets. |
| |
| \snippet widgets/charactermap/mainwindow.cpp 4 |
| |
| The font combobox's |
| \l{QFontComboBox::currentFontChanged()}{currentFontChanged()} signal is |
| connected to the findStyles() function so that the list of available styles |
| can be shown for each font that is used. Since both the font and the style |
| can be changed by the user, the font combobox's currentFontChanged() signal |
| and the style combobox's |
| \l{QComboBox::currentIndexChanged()}{currentIndexChanged()} are connected |
| directly to the character widget. |
| |
| The final two connections allow characters to be selected in the character |
| widget, and text to be inserted into the clipboard: |
| |
| \snippet widgets/charactermap/mainwindow.cpp 5 |
| |
| The character widget emits the characterSelected() custom signal when |
| the user clicks on a character, and this is handled by the insertCharacter() |
| function in this class. The clipboard is changed when the push button emits |
| the clicked() signal, and we handle this with the updateClipboard() function. |
| |
| The remaining code in the constructor sets up the layout of the central widget, |
| and provides a window title: |
| |
| \snippet widgets/charactermap/mainwindow.cpp 6 |
| |
| The font combobox is automatically populated with a list of available font |
| families. The styles that can be used with each font are found by the |
| findStyles() function. This function is called whenever the user selects a |
| different font in the font combobox. |
| |
| \snippet widgets/charactermap/mainwindow.cpp 7 |
| |
| We begin by recording the currently selected style, and we clear the |
| style combobox so that we can insert the styles associated with the |
| current font family. |
| |
| \snippet widgets/charactermap/mainwindow.cpp 8 |
| |
| We use the font database to collect the styles that are available for the |
| current font, and insert them into the style combobox. The current item is |
| reset if the original style is not available for this font. |
| |
| The last two functions are slots that respond to signals from the character |
| widget and the main window's push button. The insertCharacter() function is |
| used to insert characters from the character widget when the user clicks a |
| character: |
| |
| \snippet widgets/charactermap/mainwindow.cpp 9 |
| |
| The character is inserted into the line edit at the current cursor position. |
| |
| The main window's "To clipboard" push button is connected to the |
| updateClipboard() function so that, when it is clicked, the clipboard is |
| updated to contain the contents of the line edit: |
| |
| \snippet widgets/charactermap/mainwindow.cpp 10 |
| |
| We copy all the text from the line edit to the clipboard, but we do not clear |
| the line edit. |
| */ |