Home Explore contacts
Sign In
AMGladtsin
/
STM32_Devel
Watch 1
Star 0
Fork 1
Files Issues 0 Pull Requests 1 Wiki
Branch: master
Branches Tags
STM32_Devel
/
QTDevel
/
Test001
/
documentation
/
html
/
thelayoutsystem.html

thelayoutsystem.html 13 KB
Permalink History Raw

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091 
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
    2. 

  2. <html xmlns="http://www.w3.org/1999/xhtml">
    3. 

  3. <head>
    4. 

  4. <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
    5. 

  5. <meta name="author" content="Emanuel Eichhammer" />
    6. 

  6. <meta name="copyright" content="(C) 2013-2015 Emanuel Eichhammer" />
    7. 

  7. <title>The Layout System</title>
    8. 

  8. <link href="qt.css" rel="stylesheet" type="text/css"/>
    9. 

  9. </head>
    10. 

  10. <body>
    11. 

  11. <div id="top">
    12. 

  12. <a class="headerLink"  href="index.html">Main Page</a> &middot;
    13. 

  13. <a class="headerLink"  href="classoverview.html">Class Overview</a> &middot;
    14. 

  14. <a class="headerLink"  href="hierarchy.html">Hierarchy</a> &middot;
    15. 

  15. <a class="headerLink"  href="annotated.html">All Classes</a> &middot;
    16. 

  16. <a class="headerLink"  href="pages.html">Special Pages</a>
    17. 

  17. <!-- Generated by Doxygen 1.8.6 -->
    18. 

  18. </div><!-- top -->
    19. 

  19. <div class="header">
    20. 

  20.   <div class="headertitle">
    21. 

  21. <div class="title">The Layout System </div>  </div>
    22. 

  22. </div><!--header-->
    23. 

  23. <div class="contents">
    24. 

  24. <div class="textblock"><p>The layout system is responsible for positioning and scaling layout elements such as axis rects, legends and plot titles in a <a class="el" href="classQCustomPlot.html" title="The central class of the library. This is the QWidget which displays the plot and interacts with the ...">QCustomPlot</a>.</p>
    25. 

  25. <h1><a class="anchor" id="layoutsystem-classesandmechanisms"></a>
    26. 

  26. Classes and mechanisms</h1>
    27. 

  27. <p>The layout system is based on the abstract base class <a class="el" href="classQCPLayoutElement.html">QCPLayoutElement</a>. All objects that take part in the layout system derive from this class, either directly or indirectly.</p>
    28. 

  28. <p>Since <a class="el" href="classQCPLayoutElement.html" title="The abstract base class for all objects that form the layout system. ">QCPLayoutElement</a> itself derives from <a class="el" href="classQCPLayerable.html">QCPLayerable</a>, a layout element may draw its own content. However, it is perfectly possible for a layout element to only serve as a structuring and/or positioning element, not drawing anything on its own.</p>
    29. 

  29. <h2><a class="anchor" id="layoutsystem-rects"></a>
    30. 

  30. Rects of a layout element</h2>
    31. 

  31. <p>A layout element is a rectangular object described by two rects: the inner rect (<a class="el" href="classQCPLayoutElement.html#affdfea003469aac3d0fac5f4e06171bc">QCPLayoutElement::rect</a>) and the outer rect (<a class="el" href="classQCPLayoutElement.html#a38975ea13e36de8e53391ce41d94bc0f">QCPLayoutElement::setOuterRect</a>). The inner rect is calculated automatically by applying the margin (<a class="el" href="classQCPLayoutElement.html#a8f450b1f3f992ad576fce2c63d8b79cf">QCPLayoutElement::setMargins</a>) inward from the outer rect. The inner rect is meant for main content while the margin area may either be left blank or serve for displaying peripheral graphics. For example, <a class="el" href="classQCPAxisRect.html">QCPAxisRect</a> positions the four main axes at the sides of the inner rect, so graphs end up inside it and the axis labels and tick labels are in the margin area.</p>
    32. 

  32. <h2><a class="anchor" id="layoutsystem-margins"></a>
    33. 

  33. Margins</h2>
    34. 

  34. <p>Each layout element may provide a mechanism to automatically determine its margins. Internally, this is realized with the <a class="el" href="classQCPLayoutElement.html#a005c9f0fe84bc1591a2cf2c46fd477b4">QCPLayoutElement::calculateAutoMargin</a> function which takes a <a class="el" href="namespaceQCP.html#a7e487e3e2ccb62ab7771065bab7cae54">QCP::MarginSide</a> and returns an integer value which represents the ideal margin for the specified side. The automatic margin will be used on the sides specified in <a class="el" href="classQCPLayoutElement.html#accfda49994e3e6d51ed14504abf9d27d">QCPLayoutElement::setAutoMargins</a>. By default, it is set to <a class="el" href="namespaceQCP.html#a7e487e3e2ccb62ab7771065bab7cae54a43d7361cb0c5244eabdc962021bffebc">QCP::msAll</a> meaning automatic margin calculation is enabled for all four sides. In this case, a minimum margin may be set with <a class="el" href="classQCPLayoutElement.html#a0a8a17abc16b7923159fcc7608f94673">QCPLayoutElement::setMinimumMargins</a>, to prevent the automatic margin mechanism from setting margins smaller than desired for a specific situation. If automatic margin calculation is unset for a specific side, the margin of that side can be controlled directy via <a class="el" href="classQCPLayoutElement.html#a8f450b1f3f992ad576fce2c63d8b79cf">QCPLayoutElement::setMargins</a>.</p>
    35. 

  35. <p>If multiple layout ements are arranged next to or beneath each other, it may be desirable to align their inner rects on certain sides. Since they all might have different automatic margins, this usually isn't the case. The class <a class="el" href="classQCPMarginGroup.html">QCPMarginGroup</a> and <a class="el" href="classQCPLayoutElement.html#a516e56f76b6bc100e8e71d329866847d">QCPLayoutElement::setMarginGroup</a> fix this by allowing to synchronize multiple margins. See the documentation there for details.</p>
    36. 

  36. <h2><a class="anchor" id="layoutsystem-layout"></a>
    37. 

  37. Layouts</h2>
    38. 

  38. <p>As mentioned, a <a class="el" href="classQCPLayoutElement.html" title="The abstract base class for all objects that form the layout system. ">QCPLayoutElement</a> may have an arbitrary number of child layout elements and in princple can have the only purpose to manage/arrange those child elements. This is what the subclass <a class="el" href="classQCPLayout.html">QCPLayout</a> specializes on. It is a <a class="el" href="classQCPLayoutElement.html" title="The abstract base class for all objects that form the layout system. ">QCPLayoutElement</a> itself but has no visual representation. It defines an interface to add, remove and manage child layout elements. <a class="el" href="classQCPLayout.html" title="The abstract base class for layouts. ">QCPLayout</a> isn't a usable layout though, it's an abstract base class that concrete layouts derive from, like <a class="el" href="classQCPLayoutGrid.html">QCPLayoutGrid</a> which arranges its child elements in a grid and <a class="el" href="classQCPLayoutInset.html">QCPLayoutInset</a> which allows placing child elements freely inside its rect.</p>
    39. 

  39. <p>Since a <a class="el" href="classQCPLayout.html" title="The abstract base class for layouts. ">QCPLayout</a> is a layout element itself, it may be placed inside other layouts. This way, complex hierarchies may be created, offering very flexible arrangements.</p>
    40. 

  40. <p>Below is a sketch of the default <a class="el" href="classQCPLayoutGrid.html">QCPLayoutGrid</a> accessible via <a class="el" href="classQCustomPlot.html#afd280d4d621ae64a106543a545c508d7">QCustomPlot::plotLayout</a>. It shows how two child layout elements are placed inside the grid layout next to each other in cells (0, 0) and (0, 1).</p>
    41. 

  41. <div class="image">
    42. 

  42. <img src="LayoutsystemSketch.png" alt="LayoutsystemSketch.png"/>
    43. 

  43. </div>
    44. 

  44. <h2><a class="anchor" id="layoutsystem-plotlayout"></a>
    45. 

  45. The top level plot layout</h2>
    46. 

  46. <p>Every <a class="el" href="classQCustomPlot.html" title="The central class of the library. This is the QWidget which displays the plot and interacts with the ...">QCustomPlot</a> has one top level layout of type <a class="el" href="classQCPLayoutGrid.html">QCPLayoutGrid</a>. It is accessible via <a class="el" href="classQCustomPlot.html#afd280d4d621ae64a106543a545c508d7">QCustomPlot::plotLayout</a> and contains (directly or indirectly via other sub-layouts) all layout elements in the <a class="el" href="classQCustomPlot.html" title="The central class of the library. This is the QWidget which displays the plot and interacts with the ...">QCustomPlot</a>. By default, this top level grid layout contains a single cell which holds the main axis rect.</p>
    47. 

  47. <h2><a class="anchor" id="layoutsystem-examples"></a>
    48. 

  48. Examples</h2>
    49. 

  49. <p><b>Adding a plot title</b> is a typical and simple case to demonstrate basic workings of the layout system. </p>
    50. 

  50. <div class="fragment"><div class="line">  <span class="comment">// first we create and prepare a plot title layout element:</span></div>
    51. 

  51. <div class="line">  <a class="code" href="classQCPPlotTitle.html">QCPPlotTitle</a> *title = <span class="keyword">new</span> <a class="code" href="classQCPPlotTitle.html">QCPPlotTitle</a>(customPlot);</div>
    52. 

  52. <div class="line">  title-&gt;<a class="code" href="classQCPPlotTitle.html#aae5a93e88050dfb2cbf6adc087516821">setText</a>(<span class="stringliteral">&quot;Plot Title Example&quot;</span>);</div>
    53. 

  53. <div class="line">  title-&gt;<a class="code" href="classQCPPlotTitle.html#a199fc7170802ea65006c371875349e37">setFont</a>(QFont(<span class="stringliteral">&quot;sans&quot;</span>, 12, QFont::Bold));</div>
    54. 

  54. <div class="line">  <span class="comment">// then we add it to the main plot layout:</span></div>
    55. 

  55. <div class="line">  customPlot-&gt;plotLayout()-&gt;insertRow(0); <span class="comment">// insert an empty row above the axis rect</span></div>
    56. 

  56. <div class="line">  customPlot-&gt;plotLayout()-&gt;addElement(0, 0, title); <span class="comment">// place the title in the empty cell we&#39;ve just created</span></div>
    57. 

  57. </div><!-- fragment --><div class="image">
    58. 

  58. <img src="layoutsystem-addingplottitle.png" alt="layoutsystem-addingplottitle.png"/>
    59. 

  59. </div>
    60. 

  60. <p><b>Arranging multiple axis rects</b> actually is the central purpose of the layout system. </p>
    61. 

  61. <div class="fragment"><div class="line">  customPlot-&gt;plotLayout()-&gt;clear(); <span class="comment">// let&#39;s start from scratch and remove the default axis rect</span></div>
    62. 

  62. <div class="line">  <span class="comment">// add the first axis rect in second row (row index 1):</span></div>
    63. 

  63. <div class="line">  <a class="code" href="classQCPAxisRect.html">QCPAxisRect</a> *bottomAxisRect = <span class="keyword">new</span> <a class="code" href="classQCPAxisRect.html">QCPAxisRect</a>(customPlot);</div>
    64. 

  64. <div class="line">  customPlot-&gt;plotLayout()-&gt;addElement(1, 0, bottomAxisRect);</div>
    65. 

  65. <div class="line">  <span class="comment">// create a sub layout that we&#39;ll place in first row:</span></div>
    66. 

  66. <div class="line">  <a class="code" href="classQCPLayoutGrid.html">QCPLayoutGrid</a> *subLayout = <span class="keyword">new</span> <a class="code" href="classQCPLayoutGrid.html">QCPLayoutGrid</a>;</div>
    67. 

  67. <div class="line">  customPlot-&gt;plotLayout()-&gt;<a class="code" href="classQCPLayoutGrid.html#adff1a2ca691ed83d2d24a4cd1fe17012">addElement</a>(0, 0, subLayout);</div>
    68. 

  68. <div class="line">  <span class="comment">// add two axis rects in the sub layout next to each other:</span></div>
    69. 

  69. <div class="line">  <a class="code" href="classQCPAxisRect.html">QCPAxisRect</a> *leftAxisRect = <span class="keyword">new</span> <a class="code" href="classQCPAxisRect.html">QCPAxisRect</a>(customPlot);</div>
    70. 

  70. <div class="line">  <a class="code" href="classQCPAxisRect.html">QCPAxisRect</a> *rightAxisRect = <span class="keyword">new</span> <a class="code" href="classQCPAxisRect.html">QCPAxisRect</a>(customPlot);</div>
    71. 

  71. <div class="line">  subLayout-&gt;<a class="code" href="classQCPLayoutGrid.html#adff1a2ca691ed83d2d24a4cd1fe17012">addElement</a>(0, 0, leftAxisRect);</div>
    72. 

  72. <div class="line">  subLayout-&gt;<a class="code" href="classQCPLayoutGrid.html#adff1a2ca691ed83d2d24a4cd1fe17012">addElement</a>(0, 1, rightAxisRect);</div>
    73. 

  73. <div class="line">  subLayout-&gt;<a class="code" href="classQCPLayoutGrid.html#ae38f31a71687b9d7ee3104852528fb50">setColumnStretchFactor</a>(0, 3); <span class="comment">// left axis rect shall have 60% of width</span></div>
    74. 

  74. <div class="line">  subLayout-&gt;<a class="code" href="classQCPLayoutGrid.html#ae38f31a71687b9d7ee3104852528fb50">setColumnStretchFactor</a>(1, 2); <span class="comment">// right one only 40% (3:2 = 60:40)</span></div>
    75. 

  75. <div class="line">  <span class="comment">// since we&#39;ve created the axis rects and axes from scratch, we need to place them on</span></div>
    76. 

  76. <div class="line">  <span class="comment">// according layers, if we don&#39;t want the grid to be drawn above the axes etc.</span></div>
    77. 

  77. <div class="line">  <span class="comment">// place the axis on &quot;axes&quot; layer and grids on the &quot;grid&quot; layer, which is below &quot;axes&quot;:</span></div>
    78. 

  78. <div class="line">  QList&lt;QCPAxis*&gt; allAxes;</div>
    79. 

  79. <div class="line">  allAxes &lt;&lt; bottomAxisRect-&gt;<a class="code" href="classQCPAxisRect.html#a66654d51ca611ef036ded36250cd2518">axes</a>() &lt;&lt; leftAxisRect-&gt;<a class="code" href="classQCPAxisRect.html#a66654d51ca611ef036ded36250cd2518">axes</a>() &lt;&lt; rightAxisRect-&gt;<a class="code" href="classQCPAxisRect.html#a66654d51ca611ef036ded36250cd2518">axes</a>();</div>
    80. 

  80. <div class="line">  <span class="keywordflow">foreach</span> (<a class="code" href="classQCPAxis.html">QCPAxis</a> *axis, allAxes)</div>
    81. 

  81. <div class="line">  {</div>
    82. 

  82. <div class="line">    axis-&gt;<a class="code" href="classQCPLayerable.html#ab0d0da6d2de45a118886d2c8e16d5a54">setLayer</a>(<span class="stringliteral">&quot;axes&quot;</span>);</div>
    83. 

  83. <div class="line">    axis-&gt;<a class="code" href="classQCPAxis.html#ac4fb913cce3072b5e75a4635e0f6cd04">grid</a>()-&gt;<a class="code" href="classQCPLayerable.html#ab0d0da6d2de45a118886d2c8e16d5a54">setLayer</a>(<span class="stringliteral">&quot;grid&quot;</span>);</div>
    84. 

  84. <div class="line">  }</div>
    85. 

  85. </div><!-- fragment --><div class="image">
    86. 

  86. <img src="layoutsystem-multipleaxisrects.png" alt="layoutsystem-multipleaxisrects.png"/>
    87. 

  87. </div>
    88. 

  88.  </div></div><!-- contents -->
    89. 

  89. </body>
    90. 

  90. </html>
    91. 

  91.