~oif-team/ubuntu/natty/qt4-x11/xi2.1

<td width="1">  </td><td class="postheader" valign="center"><a href="index.html">Home</a> · <a href="classes.html">All Classes</a> · <a href="mainclasses.html">Main Classes</a> · <a href="annotated.html">Annotated</a> · <a href="groups.html">Grouped Classes</a> · <a href="functions.html">Functions</a></td>

<td align="right" valign="top" width="230"><img src="images/trolltech-logo.png" align="right" width="203" height="32" border="0" /></td></tr></table><h1 align="center">Character Map Example</h1>

Files:

<ul>

<li><a href="widgets-charactermap-characterwidget-cpp.html">widgets/charactermap/characterwidget.cpp</a></li>

<li><a href="widgets-charactermap-characterwidget-h.html">widgets/charactermap/characterwidget.h</a></li>

<li><a href="widgets-charactermap-mainwindow-cpp.html">widgets/charactermap/mainwindow.cpp</a></li>

<li><a href="widgets-charactermap-mainwindow-h.html">widgets/charactermap/mainwindow.h</a></li>

<li><a href="widgets-charactermap-main-cpp.html">widgets/charactermap/main.cpp</a></li>

</ul>

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.

<center><img src="images/charactermap-example.png" alt="Screenshot of the Character Map example" /></center>The example consists of the following classes:

<ul>

<li><tt>CharacterWidget</tt> displays the available characters in the current font and style.</li>

<li><tt>MainWindow</tt> 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.</li>

</ul>

<h2>CharacterWidget Class Definition</h2>

The <tt>CharacterWidget</tt> class is used to display an array of characters in a user-specified font and style. For flexibility, we subclass <a href="qwidget.html">QWidget</a> and reimplement only the functions that we need to provide basic rendering and interaction features.

The class definition looks like this:

<pre>  class CharacterWidget : public QWidget

{

Q_OBJECT

public:

CharacterWidget(QWidget *parent = 0);

QSize sizeHint() const;

public slots:

void updateFont(const QString &fontFamily);

void updateStyle(const QString &fontStyle);

signals:

void characterSelected(const QString &character);

protected:

void mouseMoveEvent(QMouseEvent *event);

void mousePressEvent(QMouseEvent *event);

void paintEvent(QPaintEvent *event);

private:

QFont displayFont;

int lastKey;

};</pre>

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 <a href="qwidget.html#paintEvent">QWidget::paintEvent</a>() to draw custom content. We also reimplement <a href="qwidget.html#mousePressEvent">QWidget::mousePressEvent</a>() 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 <a href="qwidget.html#mouseMoveEvent">QWidget::mouseMoveEvent</a>() event handler and define showToolTip() to enable this feature.

The <tt>displayFont</tt> and <tt>currentKey</tt> private data members are used to record the current font and the currently highlighted character in the widget.

<h2>CharacterWidget Class Implementation</h2>

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.

<pre>  CharacterWidget::CharacterWidget(QWidget *parent)

: QWidget(parent)

{

lastKey = -1;

setMouseTracking(true);

}</pre>

We initialize <tt>currentKey</tt> 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():

<pre>  void CharacterWidget::updateFont(const QString &fontFamily)

{

displayFont.setFamily(fontFamily);

displayFont.setPixelSize(16);

update();

}

void CharacterWidget::updateStyle(const QString &fontStyle)

{

QFontDatabase fontDatabase;

displayFont = fontDatabase.font(displayFont.family(), fontStyle, 12);

displayFont.setPixelSize(16);

update();

}</pre>

We use a fixed size font for the display. Similarly, a fixed size hint is provided by the sizeHint() function:

<pre>  QSize CharacterWidget::sizeHint() const

{

return QSize(32*24, (65536/32)*24);

}</pre>

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:

<pre>  void CharacterWidget::paintEvent(QPaintEvent *event)

{

100

QPainter painter(this);

101

painter.fillRect(event->rect(), QBrush(Qt::white));

102

painter.setFont(displayFont);</pre>

103

A <a href="qpainter.html">QPainter</a> 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.

104

The area of the widget that needs to be redrawn is used to determine which characters need to be displayed:

105

<pre>  QRect redrawRect = event->rect();

106

int beginRow = redrawRect.top()/24;

107

int endRow = redrawRect.bottom()/24;

108

int beginColumn = redrawRect.left()/24;

109

int endColumn = redrawRect.right()/24;</pre>

110

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.

111

<pre>  painter.setPen(QPen(Qt::gray));

112

for (int row = beginRow; row <= endRow; ++row) {

113

for (int column = beginColumn; column <= endColumn; ++column) {

114

painter.drawRect(column*24, row*24, 24, 24);

115

}

116

}</pre>

117

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:

118

<pre>  QFontMetrics fontMetrics(displayFont);

119

painter.setPen(QPen(Qt::black));

120

for (int row = beginRow; row <= endRow; ++row) {

121

122

for (int column = beginColumn; column <= endColumn; ++column) {

123

124

int key = row*32 + column;

125

painter.setClipRect(column*24, row*24, 24, 24);

126

127

if (key == lastKey)

128

painter.fillRect(column*24, row*24, 24, 24, QBrush(Qt::red));

129

130

painter.drawText(column*24 + 12 - fontMetrics.width(QChar(key))/2,

131

row*24 + 4 + fontMetrics.ascent(),

132

QString(QChar(key)));

133

}

134

}

135

}</pre>

136

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.

137

The mousePressEvent() defines how the widget responds to mouse clicks.

138

<pre>  void CharacterWidget::mousePressEvent(QMouseEvent *event)

139

{

140

if (event->button() == Qt::LeftButton) {

141

lastKey = (event->y()/24)*32 + event->x()/24;

142

if (QChar(lastKey).category() != QChar::NoCategory)

143

emit characterSelected(QString(QChar(lastKey)));

144

update();

145

}

146

else

147

QWidget::mousePressEvent(event);

148

}</pre>

149

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 there are 32 of these to a row, we simply multiply the row index by 32 and add the column number to obtain the character number.

150

If any other mouse button is pressed, the event is passed on to the <a href="qwidget.html">QWidget</a> base class. This ensures that the event can be handled properly by any other interested widgets.

151

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

152

<pre>  void CharacterWidget::mouseMoveEvent(QMouseEvent *event)

153

{

154

QPoint widgetPosition = mapFromGlobal(event->globalPos());

155

int key = (widgetPosition.y()/24)*32 + widgetPosition.x()/24;

156

QToolTip::showText(event->globalPos(), QString::number(key), this);

157

}</pre>

158

The tooltip is given a position defined in global coordinates.

159

160

<h2>MainWindow Class Definition</h2>

161

The <tt>MainWindow</tt> 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.

162

The class definition looks like this:

163

<pre>  class MainWindow : public QMainWindow

164

{

165

Q_OBJECT

166

167

public:

168

MainWindow();

169

170

public slots:

171

void findStyles();

172

void insertCharacter(const QString &character);

173

void updateClipboard();

174

175

private:

176

void findFonts();

177

178

CharacterWidget *characterWidget;

179

QClipboard *clipboard;

180

QComboBox *fontCombo;

181

QComboBox *styleCombo;

182

QLineEdit *lineEdit;

183

QScrollArea *scrollArea;

184

};</pre>

185

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.

186

187

<h2>MainWindow Class Implementation</h2>

188

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 <a href="qscrollarea.html">QScrollArea</a> so that we can view its contents:

189

<pre>  MainWindow::MainWindow()

190

{

191

QWidget *centralWidget = new QWidget;

192

193

QLabel *fontLabel = new QLabel(tr("Font:"));

194

fontCombo = new QComboBox;

195

QLabel *styleLabel = new QLabel(tr("Style:"));

196

styleCombo = new QComboBox;

197

198

scrollArea = new QScrollArea;

199

characterWidget = new CharacterWidget;

200

scrollArea->setWidget(characterWidget);</pre>

201

<a href="qscrollarea.html">QScrollArea</a> provides a viewport onto the <tt>CharacterWidget</tt> when we set its widget and handles much of the work needed to provide a scrolling viewport.

202

We list the available fonts and styles in the comboboxes using the following functions:

203

<pre>  findFonts();

204

findStyles();</pre>

205

The line edit and push button are used to supply text to the clipboard:

206

<pre>  lineEdit = new QLineEdit;

207

QPushButton *clipboardButton = new QPushButton(tr("&To clipboard"));</pre>

208

We also obtain a clipboard object so that we can send text entered by the user to other applications.

209

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.

210

<pre>  connect(fontCombo, SIGNAL(activated(const QString &)),

211

this, SLOT(findStyles()));

212

connect(fontCombo, SIGNAL(activated(const QString &)),

213

characterWidget, SLOT(updateFont(const QString &)));

214

connect(styleCombo, SIGNAL(activated(const QString &)),

215

characterWidget, SLOT(updateStyle(const QString &)));</pre>

216

The font combobox's activated() 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 activated() signals from both the font and style comboboxes are connected directly to the character widget:

217

<pre>  connect(characterWidget, SIGNAL(characterSelected(const QString &)),

218

this, SLOT(insertCharacter(const QString &)));

219

connect(clipboardButton, SIGNAL(clicked()), this, SLOT(updateClipboard()));</pre>

220

The final two connections allow characters to be selected in the character widget, and text to be inserted into the clipboard. 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.

221

The remaining code in the constructor sets up the layout of the central widget, and provides a window title:

222

<pre>  QHBoxLayout *controlsLayout = new QHBoxLayout;

223

controlsLayout->addWidget(fontLabel);

224

controlsLayout->addWidget(fontCombo, 1);

225

controlsLayout->addWidget(styleLabel);

226

controlsLayout->addWidget(styleCombo, 1);

227

controlsLayout->addStretch(1);

228

229

QHBoxLayout *lineLayout = new QHBoxLayout;

230

lineLayout->addWidget(lineEdit, 1);

231

lineLayout->addSpacing(12);

232

lineLayout->addWidget(clipboardButton);

233

234

QVBoxLayout *centralLayout = new QVBoxLayout;

235

centralLayout->addLayout(controlsLayout);

236

centralLayout->addWidget(scrollArea, 1);

237

centralLayout->addSpacing(4);

238

centralLayout->addLayout(lineLayout);

239

centralWidget->setLayout(centralLayout);

240

241

setCentralWidget(centralWidget);

242

setWindowTitle(tr("Character Map"));

243

}</pre>

244

We implement two functions to set up the fonts because the display font family and style can be set independently. findFonts() uses a font database to provide items in the font combobox:

245

<pre>  void MainWindow::findFonts()

246

{

247

QFontDatabase fontDatabase;

248

fontCombo->clear();

249

250

QString family;

251

foreach (family, fontDatabase.families())

252

fontCombo->addItem(family);

253

}</pre>

254

In this function, we clear the combobox, but only add entries for the 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.

255

<pre>  void MainWindow::findStyles()

256

{

257

QFontDatabase fontDatabase;

258

QString currentItem = styleCombo->currentText();

259

styleCombo->clear();</pre>

260

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.

261

<pre>  QString style;

262

foreach (style, fontDatabase.styles(fontCombo->currentText()))

263

styleCombo->addItem(style);

264

265

if (styleCombo->findText(currentItem) == -1)

266

styleCombo->setCurrentIndex(0);

267

}</pre>

268

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.

269

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:

270

<pre>  void MainWindow::insertCharacter(const QString &character)

271

{

272

lineEdit->insert(character);

273

}</pre>

274

The character is inserted into the line edit at the current cursor position.

275

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:

276

<pre>  void MainWindow::updateClipboard()

277

{

278

clipboard->setText(lineEdit->text(), QClipboard::Clipboard);

279

clipboard->setText(lineEdit->text(), QClipboard::Selection);

280

}</pre>

281

We copy all the text from the line edit to the clipboard, but we do not clear the line edit.

282

283

284

285

<td width="40%" align="center"><a href="trademarks.html">Trademarks</a></td>

286

287

</tr></table></div></address></body>

288

</html>

Older »