Skip to content

Commit

Permalink
Update documentation for branch developing
Browse files Browse the repository at this point in the history
  • Loading branch information
github-actions committed Feb 11, 2025
1 parent dce4e10 commit dcc2107
Show file tree
Hide file tree
Showing 3 changed files with 34 additions and 25 deletions.
4 changes: 2 additions & 2 deletions developing/footer.js
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
function writeHeader() {
document.write('Version 1.2.2-dev48');
document.write('Version 1.2.2-dev49');
};

function writeFooter() {
document.write('Generated on Tue Feb 11 2025 11:58:52 for Arm-2D 1.2.2-dev48+gc630175. Copyright © 2022-2025 Arm Limited (or its affiliates). All rights reserved.');
document.write('Generated on Tue Feb 11 2025 12:09:28 for Arm-2D 1.2.2-dev49+gf910897. Copyright © 2022-2025 Arm Limited (or its affiliates). All rights reserved.');
};
53 changes: 31 additions & 22 deletions developing/md_how_to_use_layout_assistant.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -911,13 +911,12 @@ <h3><a class="anchor" id="autotoc_md136"></a>
<p >Arm-2D provides several <code>dock</code> macros that allow elements to be positioned at the <b>top, bottom, left, right</b>, or <b>center (horizontally or vertically)</b> of a container.</p>
<h4><a class="anchor" id="autotoc_md137"></a>
&lt;strong&gt;Syntax&lt;/strong&gt;</h4>
<p >Each <code>dock</code> macro follows a similar syntax:</p>
<div class="fragment"><div class="line">arm_2d_dock_&lt;position&gt;(&lt;target region&gt;, &lt;size&gt;, [optional margins]) {</div>
<p >Each <code>dock</code> macro follows a similar syntax: </p><div class="fragment"><div class="line">arm_2d_dock_&lt;position&gt;(&lt;target region&gt;, &lt;size&gt;, [optional margins]) {</div>
<div class="line"> <span class="comment">/* Use the generated __&lt;position&gt;_region within this block */</span></div>
<div class="line">}</div>
</div><!-- fragment --><ul>
<li><code>&lt;position&gt;</code>: Specifies the docking position (<code>top</code>, <code>bottom</code>, <code>left</code>, <code>right</code>, <code>horizontal</code>, <code>vertical</code>)</li>
<li><code>&lt;target region&gt;</code>: The region where the docking occurs (e.g., a parent container)</li>
<li><code>&lt;target region&gt;</code>: The region where the docking occurs (e.g., a parent canvas)</li>
<li><code>&lt;size&gt;</code>: The height (for <code>top</code>, <code>bottom</code>, <code>vertical</code>) or width (for <code>left</code>, <code>right</code>, <code>horizontal</code>) of the docked region</li>
<li><code>[optional margins]</code>: Defines margins from adjacent edges</li>
</ul>
Expand All @@ -931,90 +930,100 @@ <h4><a class="anchor" id="autotoc_md140"></a>
<div class="fragment"><div class="line">arm_2d_dock_top(parent_region, 50) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__top_region, GLCD_COLOR_BLUE);</div>
<div class="line">}</div>
</div><!-- fragment --><p ><b>Effect</b>: Positions a 50-pixel-high region at the top of <code>parent_region</code>.</p>
<p >Additional variations:</p>
<div class="fragment"><div class="line">arm_2d_dock_top(parent_region, 50, 10, 10); <span class="comment">// Adds left and right margins</span></div>
</div><!-- fragment --><p> <b>Effect</b>: Positions a 50-pixel-high region at the top of <code>parent_region</code>.</p>
<p >Additional variations: </p><div class="fragment"><div class="line">arm_2d_dock_top(parent_region, 50, 10, 10); <span class="comment">// Adds left and right margins</span></div>
</div><!-- fragment --><h4><a class="anchor" id="autotoc_md141"></a>
&lt;strong&gt;Docking to the Bottom&lt;/strong&gt;</h4>
<div class="fragment"><div class="line">arm_2d_dock_bottom(parent_region, 30) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__bottom_region, GLCD_COLOR_RED);</div>
<div class="line">}</div>
</div><!-- fragment --><p ><b>Effect</b>: Positions a 30-pixel-high region at the bottom of <code>parent_region</code>.</p>
</div><!-- fragment --><p> <b>Effect</b>: Positions a 30-pixel-high region at the bottom of <code>parent_region</code>.</p>
<h4><a class="anchor" id="autotoc_md142"></a>
&lt;strong&gt;Docking to the Left&lt;/strong&gt;</h4>
<div class="fragment"><div class="line">arm_2d_dock_left(parent_region, 40) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__left_region, GLCD_COLOR_GREEN);</div>
<div class="line">}</div>
</div><!-- fragment --><p ><b>Effect</b>: Positions a 40-pixel-wide region at the left of <code>parent_region</code>.</p>
</div><!-- fragment --><p> <b>Effect</b>: Positions a 40-pixel-wide region at the left of <code>parent_region</code>.</p>
<h4><a class="anchor" id="autotoc_md143"></a>
&lt;strong&gt;Docking to the Right&lt;/strong&gt;</h4>
<div class="fragment"><div class="line">arm_2d_dock_right(parent_region, 40) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__right_region, GLCD_COLOR_YELLOW);</div>
<div class="line">}</div>
</div><!-- fragment --><p ><b>Effect</b>: Positions a 40-pixel-wide region at the right of <code>parent_region</code>.</p>
</div><!-- fragment --><p> <b>Effect</b>: Positions a 40-pixel-wide region at the right of <code>parent_region</code>.</p>
<h4><a class="anchor" id="autotoc_md144"></a>
&lt;strong&gt;Docking Vertically (Center-aligned)&lt;/strong&gt;</h4>
<div class="fragment"><div class="line">arm_2d_dock_vertical(parent_region, 50) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__vertical_region, GLCD_COLOR_PURPLE);</div>
<div class="line">}</div>
</div><!-- fragment --><p ><b>Effect</b>: Positions a 50-pixel-high region centered within <code>parent_region</code>.</p>
</div><!-- fragment --><p> <b>Effect</b>: Positions a 50-pixel-high region centered within <code>parent_region</code>.</p>
<h4><a class="anchor" id="autotoc_md145"></a>
&lt;strong&gt;Docking Horizontally (Center-aligned)&lt;/strong&gt;</h4>
<div class="fragment"><div class="line">arm_2d_dock_horizontal(parent_region, 100) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__horizontal_region, GLCD_COLOR_CYAN);</div>
<div class="line">}</div>
</div><!-- fragment --><p ><b>Effect</b>: Positions a 100-pixel-wide region centered within <code>parent_region</code>.</p>
</div><!-- fragment --><p> <b>Effect</b>: Positions a 100-pixel-wide region centered within <code>parent_region</code>.</p>
<h3><a class="anchor" id="autotoc_md146"></a>
3.3.3 Docking Inside &lt;tt&gt;arm_2d_layout()&lt;/tt&gt;</h3>
<p >In addition to standalone docking macros, <b>Arm-2D Layout Assistant</b> provides inline docking macros that work inside <code>arm_2d_layout()</code>. These macros allow elements to be positioned dynamically within a layout stream, ensuring flexible and adaptive UI design.</p>
<h4><a class="anchor" id="autotoc_md147"></a>
&lt;strong&gt;Syntax&lt;/strong&gt;</h4>
<div class="fragment"><div class="line">__item_line_dock_&lt;direction&gt;(&lt;size&gt; [, &lt;left&gt;, &lt;right&gt;, &lt;top&gt;, &lt;bottom&gt;]) {</div>
<div class="fragment"><div class="line">__item_line_dock_&lt;direction&gt;([&lt;size&gt;] [, &lt;left&gt;, &lt;right&gt;, &lt;top&gt;, &lt;bottom&gt;]) {</div>
<div class="line"> <span class="comment">/* Use the generated __item_region within this block */</span></div>
<div class="line">}</div>
</div><!-- fragment --><ul>
<li><code>&lt;direction&gt;</code>: Specifies the layout direction (<code>horizontal</code>, <code>vertical</code>)</li>
<li><code>&lt;size&gt;</code>: The size of the docked item along the layout axis</li>
<li><code>[&lt;size&gt;]</code>: The size of the docked item along the layout axis (optional for automatic adjustment)</li>
<li><code>[optional margins]</code>: Defines padding around the item (left, right, top, bottom)</li>
</ul>
<h4><a class="anchor" id="autotoc_md148"></a>
&lt;strong&gt;Docking in a Horizontal Stream&lt;/strong&gt;</h4>
<div class="fragment"><div class="line">arm_2d_layout(parent_region) {</div>
<div class="line"> __item_line_dock_horizontal(60) {</div>
<div class="line"> __item_line_dock_horizontal() {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__item_region, GLCD_COLOR_BLUE);</div>
<div class="line"> }</div>
<div class="line"> __item_line_dock_horizontal(5, 5, 5, 5) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__item_region, GLCD_COLOR_YELLOW);</div>
<div class="line"> }</div>
<div class="line"> __item_line_dock_horizontal(50) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__item_region, GLCD_COLOR_RED);</div>
<div class="line"> }</div>
<div class="line"> __item_line_dock_horizontal(80, 5, 5, 10, 10) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__item_region, GLCD_COLOR_GREEN);</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --><p ><b>Effect</b>: Places items in a horizontal layout with automatic docking, allowing for margins and spacing adjustments.</p>
</div><!-- fragment --><p> <b>Effect</b>: Places items in a horizontal layout with automatic docking, allowing for margins and spacing adjustments.</p>
<h4><a class="anchor" id="autotoc_md149"></a>
&lt;strong&gt;Docking in a Vertical Stream&lt;/strong&gt;</h4>
<div class="fragment"><div class="line">arm_2d_layout(parent_region) {</div>
<div class="line"> __item_line_dock_vertical(50) {</div>
<div class="line"> __item_line_dock_vertical() {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__item_region, GLCD_COLOR_RED);</div>
<div class="line"> }</div>
<div class="line"> __item_line_dock_vertical(4, 4, 4, 4) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__item_region, GLCD_COLOR_BLACK);</div>
<div class="line"> }</div>
<div class="line"> __item_line_dock_vertical(32) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__item_region, GLCD_COLOR_GREEN);</div>
<div class="line"> }</div>
<div class="line"> __item_line_dock_vertical(70, 10, 10, 5, 5) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__item_region, GLCD_COLOR_YELLOW);</div>
<div class="line"> }</div>
<div class="line">}</div>
</div><!-- fragment --><p ><b>Effect</b>: Places items in a vertical layout with automatic docking, aligning them properly within the available space.</p>
</div><!-- fragment --><p> <b>Effect</b>: Places items in a vertical layout with automatic docking, aligning them properly within the available space.</p>
<h3><a class="anchor" id="autotoc_md150"></a>
3.3.4 Advanced Docking with Margins</h3>
<p >To add space around docked elements, you can specify margin values:</p>
<div class="fragment"><div class="line">arm_2d_dock_with_margin(parent_region, 10, 10, 20, 20) {</div>
<p >To add space around docked elements, you can specify margin values: </p><div class="fragment"><div class="line">arm_2d_dock_with_margin(parent_region, 10, 10, 20, 20) {</div>
<div class="line"> arm_2d_fill_colour(ptTile, &amp;__dock_region, GLCD_COLOR_WHITE);</div>
<div class="line">}</div>
</div><!-- fragment --><p ><b>Effect</b>: Creates a docked region with 10-pixel margins on the left and right, and 20-pixel margins on the top and bottom.</p>
</div><!-- fragment --><p> <b>Effect</b>: Creates a docked region with 10-pixel margins on the left and right, and 20-pixel margins on the top and bottom.</p>
<p ><b>Note</b>: <code>arm_2d_dock_with_margin()</code> also has a simplified alias, <code>arm_2d_dock()</code>.</p>
<h3><a class="anchor" id="autotoc_md151"></a>
3.3.5 Summary</h3>
<ul>
<li>Docking provides an <b>efficient</b> way to position UI elements within containers.</li>
<li>Macros automatically generate usable regions (<b>e.g., ********<code>__top_region</code>********, ********<code>__left_region</code></b>).</li>
<li>Macros automatically generate usable regions (<b>e.g., <code>__top_region</code>, <code>__left_region</code></b>).</li>
<li>Supports <b>margins</b>, <b>horizontal/vertical centering</b>, and <b>nested layouts</b>.</li>
<li><b>Combine with alignment macros</b> for fine-tuned positioning.</li>
<li><b>Use inside ********<code>arm_2d_layout()</code>******** for flexible, adaptive UI structures.</b></li>
<li><b>Use inside <code>arm_2d_layout()</code> for flexible, adaptive UI structures.</b></li>
</ul>
<p >By leveraging <code>dock</code> macros, you can structure UI elements <b>dynamically</b> without manually calculating positions, improving both <b>code readability</b> and <b>layout consistency</b>. </p>
</div></div><!-- contents -->
Expand Down
2 changes: 1 addition & 1 deletion version.js
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
//--- list of versions ---
const versions = {
"developing": "1.2.2-dev48",
"developing": "1.2.2-dev49",
"latest": "1.2.1",
"main": "1.2.1-dev272",
"v1.2.0": "1.2.0",
Expand Down

0 comments on commit dcc2107

Please sign in to comment.