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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.8"/>
<title>Dillo: Dillo Widget Usage</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="https://www.dillo.org/dw/html/jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">Dillo
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.8 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Dillo Widget Usage </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This document describes the usage of Dw, without going too much into detail.</p>
<h2>Getting Started</h2>
<p>In this section, a small runnable example is described, based on the FLTK implementation.</p>
<p>As described in <a class="el" href="dw-overview.html">Dillo Widget Overview</a>, the following objects are needed:</p>
<ul>
<li>
<a class="el" href="classdw_1_1core_1_1Layout.html" title="The central class for managing and drawing a widget tree. ">dw::core::Layout</a>, </li>
<li>
an implementation of <a class="el" href="classdw_1_1core_1_1Platform.html" title="An interface to encapsulate some platform dependencies. ">dw::core::Platform</a> (we will use <a class="el" href="classdw_1_1fltk_1_1FltkPlatform.html">dw::fltk::FltkPlatform</a>), </li>
<li>
at least one implementation of <a class="el" href="classdw_1_1core_1_1View.html" title="An interface to encapsulate platform dependent drawing. ">dw::core::View</a> (<a class="el" href="classdw_1_1fltk_1_1FltkViewport.html">dw::fltk::FltkViewport</a>), and </li>
<li>
some widgets (for this example, only a simple <a class="el" href="classdw_1_1Textblock.html" title="A Widget for rendering text blocks, i.e. paragraphs or sequences of paragraphs. ">dw::Textblock</a>). </li>
</ul>
<p>First of all, the necessary #include's:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include <FL/Fl_Window.H></span></div>
<div class="line"><span class="preprocessor">#include <FL/Fl.H></span></div>
<div class="line"></div>
<div class="line"><span class="preprocessor">#include "<a class="code" href="core_8hh.html">dw/core.hh</a>"</span></div>
<div class="line"><span class="preprocessor">#include "<a class="code" href="fltkcore_8hh.html">dw/fltkcore.hh</a>"</span></div>
<div class="line"><span class="preprocessor">#include "<a class="code" href="fltkviewport_8hh.html">dw/fltkviewport.hh</a>"</span></div>
<div class="line"><span class="preprocessor">#include "<a class="code" href="textblock_8hh.html">dw/textblock.hh</a>"</span></div>
</div><!-- fragment --><p>Everything is put into one function:</p>
<div class="fragment"><div class="line"><span class="keywordtype">int</span> <a class="code" href="containers_8cc.html#a0ddf1224851353fc92bfbff6f499fa97">main</a>(<span class="keywordtype">int</span> argc, <span class="keywordtype">char</span> **argv)</div>
<div class="line">{</div>
</div><!-- fragment --><p>As the first object, the platform is instantiated:</p>
<div class="fragment"><div class="line"><a class="code" href="classdw_1_1fltk_1_1FltkPlatform.html">dw::fltk::FltkPlatform</a> *<a class="code" href="dw__anchors__test_8cc.html#abf91980ed932e38752517cf0b563adf7">platform</a> = <span class="keyword">new</span> <a class="code" href="classdw_1_1fltk_1_1FltkPlatform.html">dw::fltk::FltkPlatform</a> ();</div>
</div><!-- fragment --><p>Then, the layout is created, with the platform attached:</p>
<div class="fragment"><div class="line"><a class="code" href="classdw_1_1core_1_1Layout.html">dw::core::Layout</a> *<a class="code" href="dw__anchors__test_8cc.html#aa9b7b9846e3f42cc43273337240c6a8a">layout</a> = <span class="keyword">new</span> <a class="code" href="classdw_1_1core_1_1Layout.html">dw::core::Layout</a> (platform);</div>
</div><!-- fragment --><p>For the view, we first need a FLTK window:</p>
<div class="fragment"><div class="line">Fl_Window *<a class="code" href="dw__anchors__test_8cc.html#a7603ca0f96eedf7d1e56645563c177b8">window</a> = <span class="keyword">new</span> Fl_Window(200, 300, <span class="stringliteral">"Dw Example"</span>);</div>
<div class="line">window->begin();</div>
</div><!-- fragment --><p>After this, we can create a viewport, and attach it to the layout:</p>
<div class="fragment"><div class="line"><a class="code" href="classdw_1_1fltk_1_1FltkViewport.html">dw::fltk::FltkViewport</a> *<a class="code" href="dw__anchors__test_8cc.html#ae42433834f424bb1bb4982fa193b5b18">viewport</a> =</div>
<div class="line"> <span class="keyword">new</span> <a class="code" href="classdw_1_1fltk_1_1FltkViewport.html">dw::fltk::FltkViewport</a> (0, 0, 200, 300);</div>
<div class="line">layout-><a class="code" href="classdw_1_1core_1_1Layout.html#a023b6cccd2f0eb157b048cdb92e2b2dc">attachView</a> (viewport);</div>
</div><!-- fragment --><p>Each widget needs a style (<a class="el" href="classdw_1_1core_1_1style_1_1Style.html">dw::core::style::Style</a>, see <a class="el" href="namespacedw_1_1core_1_1style.html" title="Anything related to Dillo Widget styles is defined here. ">dw::core::style</a>), so we construct it here. For this, we need to fill a <a class="el" href="classdw_1_1core_1_1style_1_1StyleAttrs.html">dw::core::style::StyleAttrs</a> structure with values, and call <a class="el" href="classdw_1_1core_1_1style_1_1Style.html#a4f7ad592fb8dc769ca1c1541ca3d9a09">dw::core::style::Style::create</a> (latter is done further below):</p>
<div class="fragment"><div class="line"><a class="code" href="classdw_1_1core_1_1style_1_1StyleAttrs.html">dw::core::style::StyleAttrs</a> styleAttrs;</div>
<div class="line">styleAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1StyleAttrs.html#a9e8cb97375c9a36a844d3ed8794a18cf">initValues</a> ();</div>
<div class="line">styleAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1StyleAttrs.html#a4f03d43808ca357266a2e4dfb027f95b">margin</a>.<a class="code" href="classdw_1_1core_1_1style_1_1Box.html#aeff7d58d53ecffd76bee131255f60d6d">setVal</a> (5);</div>
</div><!-- fragment --><p><a class="el" href="classdw_1_1core_1_1style_1_1StyleAttrs.html#a9e8cb97375c9a36a844d3ed8794a18cf">dw::core::style::StyleAttrs::initValues</a> sets several default values. The last line sets a margin of 5 pixels. Next, we need a font. Fonts are created in a similar way, first, the attributes are defined:</p>
<div class="fragment"><div class="line"><a class="code" href="classdw_1_1core_1_1style_1_1FontAttrs.html">dw::core::style::FontAttrs</a> fontAttrs;</div>
<div class="line">fontAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1FontAttrs.html#adfe48000b2bdb8141edbe0b512a5d091">name</a> = <span class="stringliteral">"Bitstream Charter"</span>;</div>
<div class="line">fontAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1FontAttrs.html#a1186767207d23db2282a48308ccdd7ef">size</a> = 14;</div>
<div class="line">fontAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1FontAttrs.html#aba64ddf7a1ad8c2c932bd66c3f9e3ef2">weight</a> = 400;</div>
<div class="line">fontAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1FontAttrs.html#a36579683bc88a02c462fcffe3aea9900">style</a> = <a class="code" href="namespacedw_1_1core_1_1style.html#a46d4546bc0546c3f4aec520bafe61fe7a7592e279e6940d6c5455ce147ea5e956">dw::core::style::FONT_STYLE_NORMAL</a>;</div>
<div class="line">fontAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1FontAttrs.html#ae305eaad00679476f36478e91360985d">letterSpacing</a> = 0;</div>
<div class="line">fontAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1FontAttrs.html#a1168c4e3713735d5ba08435a5330ed20">fontVariant</a> = <a class="code" href="namespacedw_1_1core_1_1style.html#a917bca73503e44dd74f67b312eb50efda29e7649efb0f72eef23e30b61b6cb7af">dw::core::style::FONT_VARIANT_NORMAL</a>;</div>
</div><!-- fragment --><p>Now, the font can be created:</p>
<div class="fragment"><div class="line">styleAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1StyleAttrs.html#a6b3ee39ab9a4b80531c70db9ef580e73">font</a> = <a class="code" href="classdw_1_1core_1_1style_1_1Font.html#a3cdcc045933dd4bc57654b94160274d6">dw::core::style::Font::create</a> (layout, &fontAttrs);</div>
</div><!-- fragment --><p>As the last attributes, the background and forground colors are defined, here dw::core::style::Color::createSimple must be called:</p>
<div class="fragment"><div class="line">styleAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1StyleAttrs.html#a093f7bf962fad813dfbf36d9cea06823">color</a> =</div>
<div class="line"> <a class="code" href="classdw_1_1core_1_1style_1_1Color.html#adcb58532b417eb55d8ce1b4c9be36919">dw::core::style::Color::create</a> (layout, 0x000000);</div>
<div class="line">styleAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1StyleAttrs.html#aeb27b877af330de69ab7f03a2015d5ea">backgroundColor</a> =</div>
<div class="line"> <a class="code" href="classdw_1_1core_1_1style_1_1Color.html#adcb58532b417eb55d8ce1b4c9be36919">dw::core::style::Color::create</a> (layout, 0xffffff);</div>
</div><!-- fragment --><p>Finally, the style for the widget is created:</p>
<div class="fragment"><div class="line"><a class="code" href="classdw_1_1core_1_1style_1_1Style.html">dw::core::style::Style</a> *<a class="code" href="dw__anchors__test_8cc.html#a65262d503c69b51b1c0814c6ec8058cf">widgetStyle</a> =</div>
<div class="line"> <a class="code" href="classdw_1_1core_1_1style_1_1Style.html#a4f7ad592fb8dc769ca1c1541ca3d9a09">dw::core::style::Style::create</a> (layout, &styleAttrs);</div>
</div><!-- fragment --><p>Now, we create a widget, assign a style to it, and set it as the toplevel widget of the layout:</p>
<div class="fragment"><div class="line"><a class="code" href="classdw_1_1Textblock.html">dw::Textblock</a> *textblock = <span class="keyword">new</span> <a class="code" href="classdw_1_1Textblock.html">dw::Textblock</a> (<span class="keyword">false</span>);</div>
<div class="line">textblock-><a class="code" href="classdw_1_1core_1_1Widget.html#a04ccf6979d3289a6ba8298ce5a1f570b">setStyle</a> (widgetStyle);</div>
<div class="line">layout-><a class="code" href="classdw_1_1core_1_1Layout.html#a2b9a0b1fb8452b62b05fe0b1c17ab58a">setWidget</a> (textblock);</div>
</div><!-- fragment --><p>The style is not needed anymore (a reference is added in <a class="el" href="classdw_1_1core_1_1Widget.html#a04ccf6979d3289a6ba8298ce5a1f570b" title="Change the style of a widget. ">dw::core::Widget::setStyle</a>), so it should be unreferred:</p>
<div class="fragment"><div class="line">widgetStyle-><a class="code" href="classdw_1_1core_1_1style_1_1Style.html#a1a2ddfd13024b7b51aae7f727be34b68">unref</a>();</div>
</div><!-- fragment --><p>Now, some text should be added to the textblock. For this, we first need another style. <em>styleAttrs</em> can still be used for this. We set the margin to 0, and the background color to "transparent":</p>
<div class="fragment"><div class="line">styleAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1StyleAttrs.html#a4f03d43808ca357266a2e4dfb027f95b">margin</a>.<a class="code" href="classdw_1_1core_1_1style_1_1Box.html#aeff7d58d53ecffd76bee131255f60d6d">setVal</a> (0);</div>
<div class="line">styleAttrs.<a class="code" href="classdw_1_1core_1_1style_1_1StyleAttrs.html#aeb27b877af330de69ab7f03a2015d5ea">backgroundColor</a> = NULL;</div>
<div class="line"></div>
<div class="line"><a class="code" href="classdw_1_1core_1_1style_1_1Style.html">dw::core::style::Style</a> *<a class="code" href="dw__anchors__test_8cc.html#a10a9455d0bee7eeaabc9c394d3eb2688">wordStyle</a> =</div>
<div class="line"> <a class="code" href="classdw_1_1core_1_1style_1_1Style.html#a4f7ad592fb8dc769ca1c1541ca3d9a09">dw::core::style::Style::create</a> (layout, &styleAttrs);</div>
</div><!-- fragment --><p>This loop adds some paragraphs:</p>
<div class="fragment"><div class="line"><span class="keywordflow">for</span>(<span class="keywordtype">int</span> i = 1; i <= 10; i++) {</div>
<div class="line"> <span class="keywordtype">char</span> buf[4];</div>
<div class="line"> sprintf(buf, <span class="stringliteral">"%d."</span>, i);</div>
<div class="line"></div>
<div class="line"> <span class="keywordtype">char</span> *words[] = { <span class="stringliteral">"This"</span>, <span class="stringliteral">"is"</span>, <span class="stringliteral">"the"</span>, buf, <span class="stringliteral">"paragraph."</span>,</div>
<div class="line"> <span class="stringliteral">"Here"</span>, <span class="stringliteral">"comes"</span>, <span class="stringliteral">"some"</span>, <span class="stringliteral">"more"</span>, <span class="stringliteral">"text"</span>,</div>
<div class="line"> <span class="stringliteral">"to"</span>, <span class="stringliteral">"demonstrate"</span>, <span class="stringliteral">"word"</span>, <span class="stringliteral">"wrapping."</span>,</div>
<div class="line"> NULL };</div>
<div class="line"></div>
<div class="line"> <span class="keywordflow">for</span>(<span class="keywordtype">int</span> j = 0; words[j]; j++) {</div>
<div class="line"> textblock-><a class="code" href="classdw_1_1Textblock.html#a7a4c5d306e62cd51e2279bcb652340ad">addText</a>(strdup(words[j]), wordStyle);</div>
</div><!-- fragment --><p>Notice the <em>strdup</em>, <a class="el" href="classdw_1_1Textblock.html#a7a4c5d306e62cd51e2279bcb652340ad">dw::Textblock::addText</a> will feel responsible for the string, and free the text at the end. (This has been done to avoid some overhead in the HTML parser.)</p>
<p>The rest is simple, it also includes spaces (which also have styles):</p>
<div class="fragment"><div class="line"> textblock-><a class="code" href="classdw_1_1Textblock.html#a1f2b341f34d9570c3082dc743a9c9441">addSpace</a>(wordStyle);</div>
<div class="line">}</div>
</div><!-- fragment --><p>Finally, a paragraph break is added, which is 10 pixels high:</p>
<div class="fragment"><div class="line"> textblock-><a class="code" href="classdw_1_1Textblock.html#ab5fcd55f8a679c898f77b1cb864d8889">addParbreak</a>(10, wordStyle);</div>
<div class="line">}</div>
</div><!-- fragment --><p>Again, this style should be unreferred:</p>
<div class="fragment"><div class="line">wordStyle-><a class="code" href="classdw_1_1core_1_1style_1_1Style.html#a1a2ddfd13024b7b51aae7f727be34b68">unref</a>();</div>
</div><!-- fragment --><p>After adding text, this method should always be called (for faster adding large text blocks):</p>
<div class="fragment"><div class="line">textblock-><a class="code" href="classdw_1_1Textblock.html#afc99db3161e3d97ba05c9334a3ae4a13">flush</a> ();</div>
</div><!-- fragment --><p>Some FLTK stuff to finally show the window:</p>
<div class="fragment"><div class="line">window->resizable(viewport);</div>
<div class="line">window->show();</div>
<div class="line"><span class="keywordtype">int</span> errorCode = Fl::run();</div>
</div><!-- fragment --><p>For cleaning up, it is sufficient to destroy the layout:</p>
<div class="fragment"><div class="line"><span class="keyword">delete</span> <a class="code" href="dw__anchors__test_8cc.html#aa9b7b9846e3f42cc43273337240c6a8a">layout</a>;</div>
</div><!-- fragment --><p>And the rest</p>
<div class="fragment"><div class="line"> <span class="keywordflow">return</span> errorCode;</div>
<div class="line">}</div>
</div><!-- fragment --><p>If you compile and start the program, you should see the following:</p>
<div class="image">
<img src="dw-example-screenshot.png" alt="dw-example-screenshot.png"/>
</div>
<p>Try to scroll, or to resize the window, you will see, that everything is done automatically.</p>
<p>Of course, creating new widgets, adding text to widgets etc. can also be done while the program is running, i.e. after fltk::run has been called, within timeouts, idles, I/O functions etc. Notice that Dw is not thread safe, so that everything should be done within one thread.</p>
<p>With the exception, that you have to call <a class="el" href="classdw_1_1Textblock.html#afc99db3161e3d97ba05c9334a3ae4a13">dw::Textblock::flush</a>, everything gets immediately visible, within reasonable times; Dw has been optimized for frequent updates.</p>
<h2>List of all Widgets</h2>
<p>These widgets are used within dillo:</p>
<ul>
<li>
<a class="el" href="classdw_1_1core_1_1ui_1_1Embed.html" title="A widget for embedding UI widgets. ">dw::core::ui::Embed</a> </li>
<li>
<a class="el" href="classdw_1_1AlignedTextblock.html" title="Base widget for all textblocks (sub classes of dw::Textblock), which are positioned vertically and al...">dw::AlignedTextblock</a> </li>
<li>
<a class="el" href="classdw_1_1Bullet.html" title="Displays different kind of bullets. ">dw::Bullet</a> </li>
<li>
<a class="el" href="classdw_1_1Ruler.html" title="Widget for drawing (horizontal) rules. ">dw::Ruler</a> </li>
<li>
<a class="el" href="classdw_1_1Image.html" title="Displays an instance of dw::core::Imgbuf. ">dw::Image</a> </li>
<li>
<a class="el" href="classdw_1_1ListItem.html">dw::ListItem</a> </li>
<li>
<a class="el" href="classdw_1_1Table.html" title="A Widget for rendering tables. ">dw::Table</a> </li>
<li>
dw::TableCell </li>
<li>
<a class="el" href="classdw_1_1Textblock.html" title="A Widget for rendering text blocks, i.e. paragraphs or sequences of paragraphs. ">dw::Textblock</a> </li>
</ul>
<p>If you want to create a new widget, refer to <a class="el" href="dw-layout-widgets.html">Layout and Widgets</a>.</p>
<h2>List of Views</h2>
<p>There are three <a class="el" href="classdw_1_1core_1_1View.html" title="An interface to encapsulate platform dependent drawing. ">dw::core::View</a> implementations for FLTK:</p>
<ul>
<li>
<p class="startli"><a class="el" href="classdw_1_1fltk_1_1FltkViewport.html">dw::fltk::FltkViewport</a> implements a viewport, which is used in the example above.</p>
<p class="endli"></p>
</li>
<li>
<p class="startli"><a class="el" href="classdw_1_1fltk_1_1FltkPreview.html">dw::fltk::FltkPreview</a> implements a preview window, together with <a class="el" href="classdw_1_1fltk_1_1FltkPreviewButton.html">dw::fltk::FltkPreviewButton</a>, it is possible to have a scaled down overview of the whole canvas.</p>
<p class="endli"></p>
</li>
<li>
<a class="el" href="classdw_1_1fltk_1_1FltkFlatView.html">dw::fltk::FltkFlatView</a> is a "flat" view, i.e. it does not support scrolling. It is used for HTML buttons, see <a class="el" href="classdw_1_1fltk_1_1ui_1_1FltkComplexButtonResource.html">dw::fltk::ui::FltkComplexButtonResource</a> and especially <a class="el" href="classdw_1_1fltk_1_1ui_1_1FltkComplexButtonResource.html#a7cea802ac2524b6664e75624b6f507dd">dw::fltk::ui::FltkComplexButtonResource::createNewWidget</a> for details. </li>
</ul>
<p>More informations about views in general can be found in <a class="el" href="dw-layout-views.html">Layout and Views</a>.</p>
<h2>Iterators</h2>
<p>For examining generally the contents of widgets, there are iterators (<a class="el" href="classdw_1_1core_1_1Iterator.html" title="Iterators are used to iterate through the contents of a widget. ">dw::core::Iterator</a>), created by the method <a class="el" href="classdw_1_1core_1_1Widget.html#ab66387121a56322ea6e4168db857e013" title="Return an iterator for this widget. ">dw::core::Widget::iterator</a> (see there for more details).</p>
<p>These simple iterators only iterate through one widget, and return child widgets as dw::core::Content::WIDGET. The next call of <a class="el" href="classdw_1_1core_1_1Iterator.html#a72f475e2c830ed8ef3b437f23a37c976" title="Move iterator forward and store content it. ">dw::core::Iterator::next</a> will return the piece of contents <em>after</em> (not within) this child widget.</p>
<p>If you want to iterate through the whole widget trees, there are two possibilities:</p>
<ol>
<li>
<p class="startli">Use a recursive function. Of course, with this approach, you are limited by the program flow.</p>
<p class="endli"></p>
</li>
<li>
Maintain a stack of iterators, so you can freely pass this stack around. This is already implemented, as <a class="el" href="classdw_1_1core_1_1DeepIterator.html" title="A stack of iterators, to iterate recursively through a widget tree. ">dw::core::DeepIterator</a>. </li>
</ol>
<p>As an example, <a class="el" href="classdw_1_1core_1_1SelectionState.html" title="This class handles selections, as well as activation of links, which is closely related. ">dw::core::SelectionState</a> represents the selected region as two instances of <a class="el" href="classdw_1_1core_1_1DeepIterator.html" title="A stack of iterators, to iterate recursively through a widget tree. ">dw::core::DeepIterator</a>.</p>
<h2>Finding Text</h2>
<p>See <a class="el" href="classdw_1_1core_1_1Layout.html#a9dea4f08a7686e55852131a4027f5bf6">dw::core::Layout::findtextState</a> and <a class="el" href="classdw_1_1core_1_1FindtextState.html">dw::core::FindtextState</a> (details in the latter). There are delegation methods:</p>
<ul>
<li>
<a class="el" href="classdw_1_1core_1_1Layout.html#a1758770678d57e0250e8710b5d09bcf7" title="See dw::core::FindtextState::search. ">dw::core::Layout::search</a> and </li>
<li>
<a class="el" href="classdw_1_1core_1_1Layout.html#a1c4ca1ee13bcf2e35c02c5296104d6f4" title="See dw::core::FindtextState::resetSearch. ">dw::core::Layout::resetSearch</a>. </li>
</ul>
<h2>Anchors and Scrolling</h2>
<p>In some cases, it is necessary to scroll to a given position, or to an anchor, programmatically.</p>
<h3>Anchors</h3>
<p>Anchors are defined by widgets, e.g. <a class="el" href="classdw_1_1Textblock.html" title="A Widget for rendering text blocks, i.e. paragraphs or sequences of paragraphs. ">dw::Textblock</a> defines them, when <a class="el" href="classdw_1_1Textblock.html#a773ae4c773fee751945c78c67e10caac">dw::Textblock::addAnchor</a> is called. To jump to a specific anchor within the current widget tree, use <a class="el" href="classdw_1_1core_1_1Layout.html#afb5ea85bbc268f81119a8395c7324109">dw::core::Layout::setAnchor</a>.</p>
<p>This can be done immediately after assignig a toplevel widget, even when the anchor has not yet been defined. The layout will remember the anchor, and jump to the respective position, as soon as possible. Even if the anchor position changes (e.g., when an anchor is moved downwards, since some space is needed for an image in the text above), the position is corrected.</p>
<p>As soon as the user scrolls the viewport, this correction is not done anymore. If in dillo, the user request a page with an anchor, which is quite at the bottom of the page, he may be get interested in the text at the beginning of the page, and so scrolling down. If then, after the anchor has been read and added to the <a class="el" href="classdw_1_1Textblock.html" title="A Widget for rendering text blocks, i.e. paragraphs or sequences of paragraphs. ">dw::Textblock</a>, this anchor would be jumped at, the user would become confused.</p>
<p>The anchor is dismissed, too, when the toplevel widget is removed again.</p>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000002">Todo:</a></b></dt><dd>Currently, anchors only define vertical positions.</dd></dl>
<h3>Scrolling</h3>
<p>To scroll to a given position, use the method <a class="el" href="classdw_1_1core_1_1Layout.html#ada40fec705a7657d30023ef5e280a8b7" title="Scrolls all viewports, so that the region [x, y, width, height] is seen, according to hpos and vpos...">dw::core::Layout::scrollTo</a>. It expects several parameters:</p>
<ul>
<li>
a horizontal adjustment parameter, defined by <a class="el" href="namespacedw_1_1core.html#adcc37c8d91f2adaaa594858f052aa1bf">dw::core::HPosition</a>, </li>
<li>
a vertical adjustment parameter, defined by <a class="el" href="namespacedw_1_1core.html#ac4eb3a2c80b4b3ce37c6908623efa2ab">dw::core::VPosition</a>, and </li>
<li>
a rectangle (<em>x</em>, <em>y</em>, <em>width</em> and <em>heigh</em>) of the region to be adjusted. </li>
</ul>
<p>If you just want to move the canvas coordinate (<em>x</em>, <em>y</em>) into the upper left corner of the viewport, you can call:</p>
<div class="fragment"><div class="line"><a class="code" href="classdw_1_1core_1_1Layout.html">dw::core::Layout</a> *<a class="code" href="dw__anchors__test_8cc.html#aa9b7b9846e3f42cc43273337240c6a8a">layout</a>;</div>
<div class="line"><span class="comment">// ...</span></div>
<div class="line">layout-><a class="code" href="classdw_1_1core_1_1Layout.html#ada40fec705a7657d30023ef5e280a8b7">scrollTo</a>(<a class="code" href="namespacedw_1_1core.html#adcc37c8d91f2adaaa594858f052aa1bfa3157a48ad8c6b27ece5906a88ab15b11">dw::core::HPOS_LEFT</a>, <a class="code" href="namespacedw_1_1core.html#ac4eb3a2c80b4b3ce37c6908623efa2aba715512b385667f413a9e6c1663907992">dw::core::VPOS_TOP</a>, 0, 0, 0, 0);</div>
</div><!-- fragment --><p>By using <a class="el" href="namespacedw_1_1core.html#adcc37c8d91f2adaaa594858f052aa1bfa54c2a386a976da4a03e6c39581444699">dw::core::HPOS_NO_CHANGE</a> or <a class="el" href="namespacedw_1_1core.html#ac4eb3a2c80b4b3ce37c6908623efa2abacd06d042b1254601b6b9e8ae82365db9">dw::core::VPOS_NO_CHANGE</a>, you can change only one dimension. <a class="el" href="namespacedw_1_1core.html#adcc37c8d91f2adaaa594858f052aa1bfa2eee145d3e5950fc01bb99e71e7ecd30">dw::core::HPOS_INTO_VIEW</a> and <a class="el" href="namespacedw_1_1core.html#ac4eb3a2c80b4b3ce37c6908623efa2aba956eade32fd49965003daa2a7be04625">dw::core::VPOS_INTO_VIEW</a> will cause the viewport to move as much as necessary, that the region is visible in the viewport (this is e.g. used for finding text).</p>
<h2>Further Documentations</h2>
<ul>
<li>
<a class="el" href="namespacedw_1_1core_1_1style.html" title="Anything related to Dillo Widget styles is defined here. ">dw::core::style</a> </li>
<li>
<a class="el" href="namespacedw_1_1core_1_1ui.html" title="Anything related to embedded UI widgets is defined here. ">dw::core::ui</a> </li>
<li>
<a class="el" href="dw-images-and-backgrounds.html">Images and Backgrounds in Dw</a> </li>
</ul>
</div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Sat May 28 2016 11:47:43 for Dillo by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.8
</small></address>
</body>
</html>
|
