diff options
Diffstat (limited to 'examples/widgets/doc/charactermap.qdoc')
| -rw-r--r-- | examples/widgets/doc/charactermap.qdoc | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/examples/widgets/doc/charactermap.qdoc b/examples/widgets/doc/charactermap.qdoc new file mode 100644 index 0000000000..fee2a42156 --- /dev/null +++ b/examples/widgets/doc/charactermap.qdoc @@ -0,0 +1,274 @@ +/**************************************************************************** +** +** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies). +** Contact: http://www.qt-project.org/ +** +** This file is part of the documentation of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:FDL$ +** GNU Free Documentation License +** 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. +** +** Other Usage +** Alternatively, this file may be used in accordance with the terms +** and conditions contained in a signed written agreement between you +** and Nokia. +** +** +** +** +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! +\example widgets/charactermap +\title Character Map Example + +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. + +\image charactermap-example.png 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. +*/ |