<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- controls-texteditor.qdoc -->
<title>Qt Quick Text Editor Guide - UI | Qt 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td ><a href="index.html">Qt 5.9</a></td><td >Qt Quick Text Editor Guide - UI</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<link rel="prev" href="qtquickcontrols-texteditor.html" />
<link rel="next" href="qtquickcontrols-texteditor-logic.html" />
<p class="naviNextPrevious headerNavi">
<a class="prevPage" href="qtquickcontrols-texteditor.html">Qt Quick Text Editor Guide</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="qtquickcontrols-texteditor-logic.html">Qt Quick Text Editor Guide - Logic</a>
</p><p/>
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#defining-the-application-layout">Defining the Application Layout</a></li>
<li class="level1"><a href="#adding-the-controls">Adding the Controls</a></li>
<li class="level1"><a href="#setting-up-the-tool-bar">Setting Up the Tool Bar</a></li>
<li class="level2"><a href="#adding-the-tool-buttons">Adding the Tool Buttons</a></li>
<li class="level1"><a href="#setting-up-the-text-area">Setting Up the Text Area</a></li>
<li class="level1"><a href="#example-files">Example Files</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Quick Text Editor Guide - UI</h1>
<span class="subtitle"></span>
<!-- $$$qtquickcontrols-texteditor-ui.html-description -->
<div class="descr"> <a name="details"></a>
<p>Qt Quick Designer is integrated into Qt Creator, allowing you to switch between <b>Edit</b> and <b>Design</b> modes. To start using Qt Quick Designer, select the QML file, <i>main.qml</i>, and click the <b>Design</b> button on the left panel.</p>
<p>It is important to familiarize yourself with the windows in Qt Quick Designer. This guide uses Qt Quick Designer to add and set up the layout.</p>
<p class="centerAlign"><img src="images/controlstexteditor_designer.png" alt="" /></p><p><b>Note: </b>The default kit for the project must be a Desktop kit, as Qt Quick Designer cannot yet emulate the styles for a mobile platform.</p><p>To start, we can customize the default application created by the wizard. You can delete the <b>MainForm.ui.qml</b> file and remove the following lines from the <b>main.qml</b> file:</p>
<pre class="qml">
MainForm {
anchors.fill: parent
button1.onClicked: messageDialog.show(qsTr("Button 1 pressed"))
button2.onClicked: messageDialog.show(qsTr("Button 2 pressed"))
button3.onClicked: messageDialog.show(qsTr("Button 3 pressed"))
}
MessageDialog {
id: messageDialog
title: qsTr("May I have your attention, please?")
function show(caption) {
messageDialog.text = caption;
messageDialog.open();
}
}
</pre>
<p>The default dimension of the <code>ApplicationWindow</code> may remain but you can change the <code>title</code> property to a relevant name such as:</p>
<pre class="qml">
title: qsTr("Text Editor Example")
</pre>
<p><b>Note: </b>The example uses the <code>qsTr()</code> function to facilitate translation. For more information, visit the <a href="qtquick-internationalization.html">Internationalization and Localization with Qt Quick</a> page.</p><p>Make sure that <b>Resources</b> tab contains the images from the <a href="qtquickcontrols-texteditor.html#resource-files">previous page</a>.</p>
<a name="defining-the-application-layout"></a>
<h2 id="defining-the-application-layout">Defining the Application Layout</h2>
<p>Our application has a simple layout, which consists of a <i>tool bar</i> and a <i>text area</i>. The tool bar contains the <i>tool buttons</i> that the user can choose to manipulate the text area contents. At the top, there are menus, which perform actions such as saving and opening files to edit.</p>
<a name="adding-the-controls"></a>
<h2 id="adding-the-controls">Adding the Controls</h2>
<p>To add a control, you have the following options:</p>
<ol class="1" type="1"><li>Drag and drop a control from the <b>QML Types</b> window onto the main design window. This allows you to drop the control onto a specific area of the layout.</li>
<li>Drag and drop a control from the <b>QML Types</b> window onto the <b>Navigator</b> window. This allows you to set the layout hierarchy.</li>
</ol>
<p>Both these actions give you several options to quickly set up the layout. Whichever method you use, designer gives you a more direct way of setting up a particular aspect of the control, such as the scene hierarchy or the position of the control.</p>
<p>Afterwards, the various properties are set from within the <b>Properties</b> window on the right side of Qt Creator window.</p>
<a name="setting-up-the-tool-bar"></a>
<h2 id="setting-up-the-tool-bar">Setting Up the Tool Bar</h2>
<p>First, we need to add the tool bar. We can do this in the <i>Edit</i> mode and typing in a ToolBar type inside the ApplicationWindow type. This configures the ApplicationWindow object as the tool bar's parent.</p>
<pre class="cpp plain">
ApplicationWindow {
ToolBar {
id: toolBar
}
}
</pre>
<p>In the <b>Design</b> mode, the <b>Properties</b> window lets us set the tool bar <b>id</b> to <code>toolbar</code>.</p>
<p>In the <b>Navigator</b> window, make sure that the tool bar is a child of the application window. To make the tool bar a child of the window, simply drag the tool bar underneath the application window.</p>
<p>Within the tool bar, we need a <i>row</i> layout. Drag the <i>row</i> layout into the <b>Navigator</b> window and set it to be a child of the tool bar.</p>
<p>Similarly, set these layout properties:</p>
<ul>
<li><b>id</b> - set it to <code>rowToolbar</code></li>
<li>click on the fill area button to set the fill area to <i>parent</i>. The parent should be the tool bar.</li>
</ul>
<p class="centerAlign"><img src="images/controlstexteditor_rowproperties.png" alt="" /></p><a name="adding-the-tool-buttons"></a>
<h3 >Adding the Tool Buttons</h3>
<p><i>Tool buttons</i> exist within a tool bar and specifically use the layout within the tool bar. <i>Text Editor</i> has six tool buttons, each performing a specific action, such as <i>copy</i> and <i>paste</i> to and from the clipboard.</p>
<p>The steps for adding the six tool buttons are mainly the same:</p>
<ul>
<li>Drag and drop the <b>Tool Button</b> type as a child of the row layout.</li>
<li>The <b>id</b> should be set to a unique name that is related to the tool button's action. The parent is set to <b>parent</b> and set the <b>margin</b> to <code>0</code>.<p class="centerAlign"><img src="images/controlstexteditor_newproperties.png" alt="" /></p></li>
<li>The first tool button, for example <b>New</b>, should have the left anchor set to the row layout.</li>
<li>The subsequent tool buttons should have the left anchor set to their previous sibling and the <b>margin</b> to <code>0</code>. These settings makes sure that the tool buttons are adjacent to each other.</li>
<li>Set the <b>iconName</b> and <b>iconSource</b> properties in the <b>ToolButton</b> tab. The <b>iconName</b> should be set to a unique name identifying the icon name while the <b>iconSource</b> property should be set to the name of the icon for the tool button.</li>
</ul>
<p>For example, the <b>New</b> tool button has <code>newIcon</code> set as its <b>iconName</b> and <code>images/filenew.png</code> set to the <b>iconSource</b> property. The icons are also viewable in the <b>Resources</b> inside the <b>Library</b> window.</p>
<p>Similarly for the <b>Open</b> tool button, the margins are set to <code>0</code> but the left anchor is set to the <b>New</b> tool button.</p>
<p class="centerAlign"><img src="images/controlstexteditor_openproperties.png" alt="" /></p><p><b>Note: </b>Dragging and dropping the images from the <b>Resources</b> onto the scene adds the image into the scene as an Image object, instead of setting the iconSource property.</p><a name="setting-up-the-text-area"></a>
<h2 id="setting-up-the-text-area">Setting Up the Text Area</h2>
<p>Next, add a <b>Text Area</b> onto the scene as a child of the application window and a sibling of <code>toolBar</code>. The tool bar should be above the text area. Similarly, set the following text area properties:</p>
<ul>
<li><b>id</b> - set it to <code>textArea</code></li>
<li>set the left, right, and bottom margin to the parent and the top margin to <code>toolBar.bottom</code> and set the margins to <code>0</code>.<pre class="qml">
anchors.top: toolBar.bottom
anchors.right: parent.right
anchors.bottom: parent.bottom
anchors.left: parent.left
</pre>
</li>
</ul>
<p>Verify that you have the parent, margins, and icons set up. Your <b>Navigator</b> should look similar to:</p>
<p class="centerAlign"><img src="images/controlstexteditor_navigator.png" alt="" /></p><p>Running the application should result in this layout:</p>
<p class="centerAlign"><img src="images/controlstexteditor_main.png" alt="" /></p><p>We are now ready to go back to <b>Edit</b> and set the handlers and actions. A QML <i>handler</i> is called when the buttons are pressed and triggers the necessary action associated with the tool buttons. An <i>action</i> collects various QML logic into one code block so it may be reused by several handlers. For more information, visit the Action QML type and Signal and Handler Event System.</p>
<a name="example-files"></a>
<h2 id="example-files">Example Files</h2>
<p>The accompanying examples files are found in the following page:</p>
<ul>
<li>Qt Quick Controls - Text Editor Example</li>
</ul>
</div>
<!-- @@@qtquickcontrols-texteditor-ui.html -->
<p class="naviNextPrevious footerNavi">
<a class="prevPage" href="qtquickcontrols-texteditor.html">Qt Quick Text Editor Guide</a>
<span class="naviSeparator"> ◦ </span>
<a class="nextPage" href="qtquickcontrols-texteditor-logic.html">Qt Quick Text Editor Guide - Logic</a>
</p>
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
