qtquickcontrols-texteditor-ui.html 12 KB
Newer Older
xuebingbing's avatar
xuebingbing committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180
<?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.11</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.11</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.11.2 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">  &#9702;  </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(&quot;Button 1 pressed&quot;))
      button2.onClicked: messageDialog.show(qsTr(&quot;Button 2 pressed&quot;))
      button3.onClicked: messageDialog.show(qsTr(&quot;Button 3 pressed&quot;))
  }

  MessageDialog {
      id: messageDialog
      title: qsTr(&quot;May I have your attention, please?&quot;)

      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(&quot;Text Editor Example&quot;)

</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 <a href="../qtquickcontrols/qml-qtquick-controls-toolbar.html">ToolBar</a> type inside the <a href="../qtquickcontrols/qml-qtquick-controls-applicationwindow.html">ApplicationWindow</a> type. This configures the <a href="../qtquickcontrols/qml-qtquick-controls-applicationwindow.html">ApplicationWindow</a> 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 <a href="../qdoc/09-qdoc-commands-includingimages.html#image">Image</a> 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 <a href="../qtquickcontrols/qml-qtquick-controls-action.html">Action</a> QML type and <a href="../qtqml/qtqml-syntax-signals.html">Signal and Handler Event System</a>.</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><a href="../qtquickcontrols/qtquickcontrols-texteditor-example.html">Qt Quick Controls - Text Editor Example</a></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">  &#9702;  </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">&copy;</acronym> 2018 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>