~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">Application Example</h1>

Files:

<ul>

<li><a href="mainwindows-application-mainwindow-cpp.html">mainwindows/application/mainwindow.cpp</a></li>

<li><a href="mainwindows-application-mainwindow-h.html">mainwindows/application/mainwindow.h</a></li>

<li><a href="mainwindows-application-main-cpp.html">mainwindows/application/main.cpp</a></li>

<li><a href="mainwindows-application-application-qrc.html">mainwindows/application/application.qrc</a></li>

</ul>

The Application example shows how to implement a standard GUI application with menus, toolbars, and a status bar. The example itself is a simple text editor program built around <a href="qtextedit.html">QTextEdit</a>.

<center><img src="images/application.png" alt="Screenshot of the Application example" /></center>Nearly all of the code for the Application example is in the <tt>MainWindow</tt> class, which inherits <a href="qmainwindow.html">QMainWindow</a>. <a href="qmainwindow.html">QMainWindow</a> provides the framework for windows that have menus, toolbars, dock windows, and a status bar. The application provides File, Edit, and Help entries in the menu bar, with the following popup menus:

<center><img src="images/application-menus.png" alt="The Application example's menu system" /></center>The status bar at the bottom of the main window shows a description of the menu item or toolbar button under the cursor.

To keep the example simple, recently opened files aren't shown in the File menu, even though this feature is desired in 90% of applications. The <a href="mainwindows-recentfiles.html">Recent Files</a> example shows how to implement this. Furthermore, this example can only load one file at a time. The <a href="mainwindows-sdi.html">SDI</a> and <a href="mainwindows-mdi.html">MDI</a> examples shows how to lift these restrictions.

<h2>MainWindow Class Definition</h2>

Here's the class definition:

<pre>  class MainWindow : public QMainWindow

{

Q_OBJECT

public:

MainWindow();

protected:

void closeEvent(QCloseEvent *event);

private slots:

void newFile();

void open();

bool save();

bool saveAs();

void about();

void documentWasModified();

private:

void createActions();

void createMenus();

void createToolBars();

void createStatusBar();

void readSettings();

void writeSettings();

bool maybeSave();

void loadFile(const QString &fileName);

bool saveFile(const QString &fileName);

void setCurrentFile(const QString &fileName);

QString strippedName(const QString &fullFileName);

QTextEdit *textEdit;

QString curFile;

QMenu *fileMenu;

QMenu *editMenu;

QMenu *helpMenu;

QToolBar *fileToolBar;

QToolBar *editToolBar;

QAction *newAct;

QAction *openAct;

QAction *saveAct;

QAction *saveAsAct;

QAction *exitAct;

QAction *cutAct;

QAction *copyAct;

QAction *pasteAct;

QAction *aboutAct;

QAction *aboutQtAct;

};</pre>

The public API is restricted to the constructor. In the <tt>protected</tt> section, we reimplement <a href="qwidget.html#closeEvent">QWidget::closeEvent</a>() to detect when the user attempts to close the window, and warn the user about unsaved changes. In the <tt>private slots</tt> section, we declare slots that correspond to menu entries, as well as a mysterious <tt>documentWasModified()</tt> slot. Finally, in the <tt>private</tt> section of the class, we have various members that will be explained in due time.

<h2>MainWindow Class Implementation</h2>

<pre>  #include <QtGui>

#include "mainwindow.h"</pre>

We start by including <tt><QtGui></tt>, a header file that contains the definition of all classes in the <a href="qtcore.html#qtcore">QtCore</a> and <a href="qtgui.html#qtgui">QtGui</a> libraries. This saves us from the trouble of having to include every class individually. We also include <tt>mainwindow.h</tt>.

You might wonder why we don't include <tt><QtGui></tt> in <tt>mainwindow.h</tt> and be done with it. The reason is that including such a large header from another header file can rapidly degrade performances. Here, it wouldn't do any harm, but it's still generally a good idea to include only the header files that are strictly necessary from another header file.

<pre>  MainWindow::MainWindow()

{

textEdit = new QTextEdit;

setCentralWidget(textEdit);

createActions();

createMenus();

100

createToolBars();

101

createStatusBar();

102

103

readSettings();

104

105

connect(textEdit->document(), SIGNAL(contentsChanged()),

106

this, SLOT(documentWasModified()));

107

108

setWindowTitle(tr("Application"));

109

}</pre>

110

In the constructor, we start by creating a <a href="qtextedit.html">QTextEdit</a> widget as a child of the main window (the <tt>this</tt> object). Then we call <a href="qmainwindow.html#setCentralWidget">QMainWindow::setCentralWidget</a>() to tell that this is going to be the widget that occupies the central area of the main window, between the toolbars and the status bar.

111

Then we call <tt>createActions()</tt>, <tt>createMenus()</tt>, <tt>createToolBars()</tt>, and <tt>createStatusBar()</tt>, four private functions that set up the user interface. After that, we call <tt>readSettings()</tt> to restore the user's preferences.

112

We establish a signal-slot connection between the <a href="qtextedit.html">QTextEdit</a>'s document object and our <tt>documentWasModified()</tt> slot. Whenever the user modifies the text in the <a href="qtextedit.html">QTextEdit</a>, we want to update the title bar to show that the file was modified.

113

At the end, we set the window title to "Application", the name of our program. The <a href="qobject.html#tr">tr()</a> call around the literal string marks the string for translation. It is a good habit to call <a href="qobject.html#tr">tr()</a> on all user-visible strings, in case you later decide to translate your application to other languages. The <a href="i18n.html">Internationalization with Qt</a> overview convers <a href="qobject.html#tr">tr()</a> in more detail.

114

<a name="close-event-handler"></a><pre>  void MainWindow::closeEvent(QCloseEvent *event)

115

{

116

if (maybeSave()) {

117

writeSettings();

118

event->accept();

119

} else {

120

event->ignore();

121

}

122

}</pre>

123

When the user attempts to close the window, we call the private function <tt>maybeSave()</tt> to give the user the possibility to save pending changes. The function returns true if the user wants the application to close; otherwise, it returns false. In the first case, we save the user's preferences to disk and accept the close event; in the second case, we ignore the close event, meaning that the application will stay up and running as if nothing happened.

124

<pre>  void MainWindow::newFile()

125

{

126

if (maybeSave()) {

127

textEdit->clear();

128

setCurrentFile("");

129

}

130

}</pre>

131

The <tt>newFile()</tt> slot is invoked when the user selects File|New from the menu. We call <tt>maybeSave()</tt> to save any pending changes and if the user accepts to go on, we clear the <a href="qtextedit.html">QTextEdit</a> and call the private function <tt>setCurrentFile()</tt> to update the window title and clear the <a href="qwidget.html#windowModified-prop">windowModified</a> flag.

132

<pre>  void MainWindow::open()

133

{

134

if (maybeSave()) {

135

QString fileName = QFileDialog::getOpenFileName(this);

136

if (!fileName.isEmpty())

137

loadFile(fileName);

138

}

139

}</pre>

140

The <tt>open()</tt> slot is invoked when the user clicks File|Open. We pop up a <a href="qfiledialog.html">QFileDialog</a> asking the user to choose a file. If the user chooses a file (i.e., <tt>fileName</tt> is not an empty string), we call the private function <tt>loadFile()</tt> to actually load the file.

141

<pre>  bool MainWindow::save()

142

{

143

if (curFile.isEmpty()) {

144

return saveAs();

145

} else {

146

return saveFile(curFile);

147

}

148

}</pre>

149

The <tt>save()</tt> slot is invoked when the user clicks File|Save. If the user hasn't provided a name for the file yet, we call <tt>saveAs()</tt>; otherwise, we call the private function <tt>saveFile()</tt> to actually save the file.

150

<pre>  bool MainWindow::saveAs()

151

{

152

QString fileName = QFileDialog::getSaveFileName(this);

153

if (fileName.isEmpty())

154

return false;

155

156

return saveFile(fileName);

157

}</pre>

158

In <tt>saveAs()</tt>, we start by popping up a <a href="qfiledialog.html">QFileDialog</a> asking the user to provide a name. If the user clicks Cancel, the returned file name is empty, and we do nothing.

159

<pre>  void MainWindow::about()

160

{

161

QMessageBox::about(this, tr("About Application"),

162

tr("The Application example demonstrates how to "

163

"write modern GUI applications using Qt, with a menu bar, "

164

"toolbars, and a status bar."));

165

}</pre>

166

The application's About box is done using one statement, using the <a href="qmessagebox.html#about">QMessageBox::about</a>() static function and relying on its support for an HTML subset.

167

<pre>  void MainWindow::documentWasModified()

168

{

169

setWindowModified(true);

170

}</pre>

171

The <tt>documentWasModified()</tt> slot is invoked each time the text in the <a href="qtextedit.html">QTextEdit</a> changes because of user edits. We call <a href="qwidget.html#windowModified-prop">QWidget::setWindowModified</a>() to make the title bar show that the file was modified. How this is done depends varies on the different platforms.

172

<pre>  void MainWindow::createActions()

173

{

174

newAct = new QAction(QIcon(":/images/new.png"), tr("&New"), this);

175

newAct->setShortcut(tr("Ctrl+N"));

176

newAct->setStatusTip(tr("Create a new file"));

177

connect(newAct, SIGNAL(triggered()), this, SLOT(newFile()));

178

179

openAct = new QAction(QIcon(":/images/open.png"), tr("&Open..."), this);

180

openAct->setShortcut(tr("Ctrl+O"));

181

openAct->setStatusTip(tr("Open an existing file"));

182

connect(openAct, SIGNAL(triggered()), this, SLOT(open()));

183

...

184

aboutQtAct = new QAction(tr("About &Qt"), this);

185

aboutQtAct->setStatusTip(tr("Show the Qt library's About box"));

186

connect(aboutQtAct, SIGNAL(triggered()), qApp, SLOT(aboutQt()));

187

}</pre>

188

The <tt>createActions()</tt> private function, which is called from the <tt>MainWindow</tt> constructor, creates <a href="qaction.html">QAction</a>s. The code is very repetitive, so we show only the actions corresponding to File|New, File|Open, and Help|About Qt.

189

A <a href="qaction.html">QAction</a> is an object that represents one user action, such as saving a file or invoking a dialog. An action can be put in a <a href="qmenu.html">QMenu</a> or a <a href="qtoolbar.html">QToolBar</a>, or both, or in any other widget that reimplements <a href="qwidget.html#actionEvent">QWidget::actionEvent</a>().

190

An action has a text that is shown in the menu, an icon, a shortcut key, a tooltip, a status tip (shown in the status bar), a "What's This?" text, and more. It emits a <a href="qaction.html#triggered">triggered()</a> signal whenever the user invokes the action (e.g., by clicking the associated menu item or toolbar button). We connect this signal to a slot that performs the actual action.

191

The code above contains one more idiom that must be explained. For some of the actions, we specify an icon as a <a href="qpixmap.html">QPixmap</a> to the <a href="qaction.html">QAction</a> constructor. The <a href="qpixmap.html">QPixmap</a> constructor takes the file name of an image that it tries to load. Here, the file name starts with <tt>:</tt>. Such file names aren't ordinary file names, but rather path in the executable's stored resources. We'll come back to this when we review the <tt>application.qrc</tt> file that's part of the project.

192

<pre>  void MainWindow::createMenus()

193

{

194

fileMenu = menuBar()->addMenu(tr("&File"));

195

fileMenu->addAction(newAct);

196

fileMenu->addAction(openAct);

197

fileMenu->addAction(saveAct);

198

fileMenu->addAction(saveAsAct);

199

fileMenu->addSeparator();

200

fileMenu->addAction(exitAct);

201

202

editMenu = menuBar()->addMenu(tr("&Edit"));

203

editMenu->addAction(cutAct);

204

editMenu->addAction(copyAct);

205

editMenu->addAction(pasteAct);

206

207

menuBar()->addSeparator();

208

209

helpMenu = menuBar()->addMenu(tr("&Help"));

210

helpMenu->addAction(aboutAct);

211

helpMenu->addAction(aboutQtAct);

212

}</pre>

213

Creating actions isn't sufficient to make them available to the user; we must also add them to the menu system. This is what <tt>createMenus()</tt> does. We create a File, an Edit, and a Help menu. <a href="qmainwindow.html#menuBar">QMainWindow::menuBar</a>() lets us access the window's menu bar widget. We don't have to worry about creating the menu bar ourselves; the first time we call this function, the <a href="qmenubar.html">QMenuBar</a> is created.

214

Just before we create the Help menu, we call <a href="qmenubar.html#addSeparator">QMenuBar::addSeparator</a>(). This has no effect for most widget styles (e.g., Windows and Mac OS X styles), but for Motif-based styles this makes sure that Help is pushed to the right side of the menu bar. Try running the application with various styles and see the result:

215

<pre>  application -style=windows

216

application -style=motif

217

application -style=cde</pre>

218

Let's now review the toolbars:

219

<pre>  void MainWindow::createToolBars()

220

{

221

fileToolBar = addToolBar(tr("File"));

222

fileToolBar->addAction(newAct);

223

fileToolBar->addAction(openAct);

224

fileToolBar->addAction(saveAct);

225

226

editToolBar = addToolBar(tr("Edit"));

227

editToolBar->addAction(cutAct);

228

editToolBar->addAction(copyAct);

229

editToolBar->addAction(pasteAct);

230

}</pre>

231

Creating toolbars is very similar to creating menus. The same actions that we put in the menus can be reused in the toolbars.

232

<pre>  void MainWindow::createStatusBar()

233

{

234

statusBar()->showMessage(tr("Ready"));

235

}</pre>

236

<a href="qmainwindow.html#statusBar">QMainWindow::statusBar</a>() returns a pointer to the main window's <a href="qstatusbar.html">QStatusBar</a> widget. Like with <a href="qmainwindow.html#menuBar">QMainWindow::menuBar</a>(), the widget is automatically created the first time the function is called.

237

<pre>  void MainWindow::readSettings()

238

{

239

QSettings settings("Trolltech", "Application Example");

240

QPoint pos = settings.value("pos", QPoint(200, 200)).toPoint();

241

QSize size = settings.value("size", QSize(400, 400)).toSize();

242

resize(size);

243

move(pos);

244

}</pre>

245

The <tt>readSettings()</tt> function is called from the constructor to load the user's preferences and other application settings. The <a href="qsettings.html">QSettings</a> class provides a high-level interface for storing settings permanently on disk. On Windows, it uses the (in)famous Windows registry; on Mac OS X, it uses the native XML-based CFPreferences API; on Unix/<a href="winsystem.html#x11">X11</a>, it uses text files.

246

The <a href="qsettings.html">QSettings</a> constructor takes arguments that identify your company and the name of the product. This ensures that the settings for different applications are kept separately.

247

We use <a href="qsettings.html#value">QSettings::value</a>() to extract the value of the "pos" and "size" settings. The second argument to <a href="qsettings.html#value">QSettings::value</a>() is optional and specifies a default value for the setting if there exists none. This value is used the first time the application is run.

248

When restoring the position and size of a window, it's important to call <a href="qwidget.html#size-prop">QWidget::resize</a>() before <a href="qwidget.html#pos-prop">QWidget::move</a>(). The reason why is given in the <a href="geometry.html">Window Geometry</a> overview.

249

<pre>  void MainWindow::writeSettings()

250

{

251

QSettings settings("Trolltech", "Application Example");

252

settings.setValue("pos", pos());

253

settings.setValue("size", size());

254

}</pre>

255

The <tt>writeSettings()</tt> function is called from <tt>closeEvent()</tt>. Writing settings is similar to reading them, except simpler. The arguments to the <a href="qsettings.html">QSettings</a> constructor must be the same as in <tt>readSettings()</tt>.

256

<pre>  bool MainWindow::maybeSave()

257

{

258

if (textEdit->document()->isModified()) {

259

int ret = QMessageBox::warning(this, tr("Application"),

260

tr("The document has been modified.\n"

261

"Do you want to save your changes?"),

262

QMessageBox::Yes | QMessageBox::Default,

263

QMessageBox::No,

264

QMessageBox::Cancel | QMessageBox::Escape);

265

if (ret == QMessageBox::Yes)

266

return save();

267

else if (ret == QMessageBox::Cancel)

268

return false;

269

}

270

return true;

271

}</pre>

272

The <tt>maybeSave()</tt> function is called to save pending changes. If there are pending changes, it pops up a <a href="qmessagebox.html">QMessageBox</a> giving the user to save the document. The options are <a href="qmessagebox.html#Button-enum">QMessageBox::Yes</a>, <a href="qmessagebox.html#Button-enum">QMessageBox::No</a>, and <a href="qmessagebox.html#Button-enum">QMessageBox::Cancel</a>. The Yes button is made the default button (the button that is invoked when the user presses Return) using the <a href="qmessagebox.html#Button-enum">QMessageBox::Default</a> flag; the Cancel button is made the escape button (the button that is invoked when the user presses Esc) using the <a href="qmessagebox.html#Button-enum">QMessageBox::Escape</a> flag.

273

The <tt>maybeSave()</tt> function returns <tt>true</tt> in all cases, except when the user clicks Cancel. The caller must check the return value and stop whatever it was doing if the return value is <tt>false</tt>.

274

<pre>  void MainWindow::loadFile(const QString &fileName)

275

{

276

QFile file(fileName);

277

if (!file.open(QFile::ReadOnly | QFile::Text)) {

278

QMessageBox::warning(this, tr("Application"),

279

tr("Cannot read file %1:\n%2.")

280

.arg(fileName)

281

.arg(file.errorString()));

282

return;

283

}

284

285

QTextStream in(&file);

286

QApplication::setOverrideCursor(Qt::WaitCursor);

287

textEdit->setPlainText(in.readAll());

288

QApplication::restoreOverrideCursor();

289

290

setCurrentFile(fileName);

291

statusBar()->showMessage(tr("File loaded"), 2000);

292

}</pre>

293

In <tt>loadFile()</tt>, we use <a href="qfile.html">QFile</a> and <a href="qtextstream.html">QTextStream</a> to read in the data. The <a href="qfile.html">QFile</a> object provides access to the bytes stored in a file.

294

We start by opening the file in read-only mode. The <a href="qiodevice.html#OpenModeFlag-enum">QFile::Text</a> flag indicates that the file is a text file, not a binary file. On Unix and Mac OS X, this makes no difference, but on Windows, it ensures that the "\r\n" end-of-line sequence is converted to "\n" when reading.

295

If we successfully opened the file, we use a <a href="qtextstream.html">QTextStream</a> object to read in the data. <a href="qtextstream.html">QTextStream</a> automatically converts the 8-bit data into a Unicode <a href="qstring.html">QString</a> and supports various encodings. If no encoding is specified, <a href="qtextstream.html">QTextStream</a> assumes the file is written using the system's default 8-bit encoding (for example, Latin-1; see <a href="qtextcodec.html#codecForLocale">QTextCodec::codecForLocale</a>() for details).

296

Since the call to <a href="qtextstream.html#readAll">QTextStream::readAll</a>() might take some time, we set the cursor to be <a href="qt.html#CursorShape-enum">Qt::WaitCursor</a> for the entire application while it goes on.

297

At the end, we call the private <tt>setCurrentFile()</tt> function, which we'll cover in a moment, and we display the string "File loaded" in the status bar for 2 seconds (2000 milliseconds).

298

<pre>  bool MainWindow::saveFile(const QString &fileName)

299

{

300

QFile file(fileName);

301

if (!file.open(QFile::WriteOnly | QFile::Text)) {

302

QMessageBox::warning(this, tr("Application"),

303

tr("Cannot write file %1:\n%2.")

304

.arg(fileName)

305

.arg(file.errorString()));

306

return false;

307

}

308

309

QTextStream out(&file);

310

QApplication::setOverrideCursor(Qt::WaitCursor);

311

out << textEdit->toPlainText();

312

QApplication::restoreOverrideCursor();

313

314

setCurrentFile(fileName);

315

statusBar()->showMessage(tr("File saved"), 2000);

316

return true;

317

}</pre>

318

Saving a file is very similar to loading one. Here, the <a href="qiodevice.html#OpenModeFlag-enum">QFile::Text</a> flag ensures that on Windows, "\n" is converted into "\r\n" to conform to the Windows convension.

319

<pre>  void MainWindow::setCurrentFile(const QString &fileName)

320

{

321

curFile = fileName;

322

textEdit->document()->setModified(false);

323

setWindowModified(false);

324

325

if (curFile.isEmpty())

326

setWindowTitle(tr("Application"));

327

else

328

setWindowTitle(tr("%1[*] - %2").arg(strippedName(curFile))

329

.arg(tr("Application")));

330

}</pre>

331

The <tt>setCurrentFile()</tt> function is called to reset the state of a few variables when a file is loaded or saved, or when the user starts editing a new file (in which case <tt>fileName</tt> is empty). We update the <tt>curFile</tt> variable, clear the <a href="qtextdocument.html#modified-prop">QTextDocument::modified</a> flag and the associated <tt>QWidget:windowModified</tt> flag, and update the window title to contain the new file name.

332

The <tt>strippedName()</tt> function call around <tt>curFile</tt> in the <a href="qwidget.html#windowTitle-prop">QWidget::setWindowTitle</a>() call shortens the file name to exclude the path. Here's the function:

333

<pre>  QString MainWindow::strippedName(const QString &fullFileName)

334

{

335

return QFileInfo(fullFileName).fileName();

336

}</pre>

337

338

<h2>The main() Function</h2>

339

The <tt>main()</tt> function for this application is typical of applications that contain one main window:

340

<pre>  #include <QApplication>

341

342

#include "mainwindow.h"

343

344

int main(int argc, char *argv[])

345

{

346

Q_INIT_RESOURCE(application);

347

348

QApplication app(argc, argv);

349

MainWindow mainWin;

350

mainWin.show();

351

return app.exec();

352

}</pre>

353

354

<h2>The Resource File</h2>

355

As you will probably recall, for some of the actions, we specified icons with file names starting with <tt>:</tt> and mentioned that such file names aren't ordinary file names, but path in the executable's stored resources. These resources are compiled

356

The resources associated with an application are specified in a <tt>.qrc</tt> file, an XML-based file format that lists files on the disk. Here's the <tt>application.qrc</tt> file that's used by the Application example:

357

358

359

<file>images/copy.png</file>

360

<file>images/cut.png</file>

361

<file>images/new.png</file>

362

<file>images/open.png</file>

363

<file>images/paste.png</file>

364

<file>images/save.png</file>

365

</qresource>

366

</RCC></pre>

367

The <tt>.png</tt> files listed in the <tt>application.qrc</tt> file are files that are part of the Application example's source tree. Paths are relative to the directory where the <tt>application.qrc</tt> file is located (the <tt>mainwindows/application</tt> directory).

368

The resource file must be mentioned in the <tt>application.pro</tt> file so that <tt>qmake</tt> knows about it:

369

<pre>  RESOURCES = application.qrc</pre>

370

<tt>qmake</tt> will produce make rules to generate a file called <tt>qrc_application.cpp</tt> that is linked into the application. This file contains all the data for the images and other resources as static C++ arrays of compressed binary data. See <a href="resources.html">The Qt Resource System</a> for more information about resources.

371

372

373

374

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

375

376

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

377

</html>

Older »