2 <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
6 <title>Planned features</title>
7 <subtitle>Indicative roadmap of ADG features implementation</subtitle>
9 <para>The following list is roughly in reversed implementation order. All the
10 improvements must be reflected in the demo programs, where applicable.</para>
12 <simplesect id="TODO.unknown">
13 <title>Road to unknown</title>
15 <para>This is the collection of TODOs that could be applied also after the
16 1.0.0 version has been released. They are usually non-blocking and hard
19 <itemizedlist mark="circle">
20 <listitem>Actually the AdgPath code is simplified to execute binary actions
21 only when the two operands are properly defined primitives. Anyway
22 those actions could be chained up in a lot of situations. For example,
23 it is quite common to have a chamfer followed by a fillet.</listitem>
24 <listitem>Add support for DXF format. Although the easiest approach would be to
25 implement a new surface type directly into cairo, this would loose
26 too much information (e.g. dimension grouping and association) so
27 an ADG backend seems to be the only viable way. Look hard to see if
28 <ulink url="https://github.com/bert/libdxf">libdxf</ulink> can be used.</listitem>
29 <listitem>A binary action after a close-path primitive leaves the shape opened:
30 closing and filleting results in a non-closed original shape.</listitem>
31 <listitem override="disc">Hide the CPML APIs accessible from the CpmlPrimitive interface: use
32 a private struct of function pointers to delegate the job to the
33 different primitives.</listitem>
34 <listitem>Check if the decentralization of the quote is applicable to the
35 angular dimensions too and if it is worth the effort.</listitem>
36 <listitem>The ARROW and TRIANGLE markers should follow the director path that
37 could be a curve. Use the METAPOST solution suggested by John Hobby
38 in its METAPOST manual, that is given <parameter>angle</parameter> and <parameter>size</parameter>, rotate the
39 path by half <parameter>angle</parameter> in both directions, cut it with a circle centered
40 at the end of the director path with radius <parameter>size</parameter> and close the
41 resulting path (eventually filling it).</listitem>
42 <listitem override="disc">Implement AdgText, a generic text management, using pango.</listitem>
43 <listitem>Add a specialized GTK+ widget that allows the customization of the
44 rendering process. This should be a tree widget that provides
45 hierarchical access to AdgStyle and derived <emphasis>instances</emphasis> by
46 inspecting an AdgCanvas object, in a way similar to what
47 <ulink url="http://glade.gnome.org">glade</ulink> does with a GtkWindow. Add this
48 widget to a new tab in the edit dialog of adg-demo to expose and
49 test this new feature.</listitem>
50 <listitem>Add self-intersection API for CPML segments.</listitem>
51 <listitem>Add datum support: for implementation ideas checkout this
52 <ulink url="http://nvlpubs.nist.gov/nistpubs/jres/104/4/html/j44mac.htm">draft</ulink>.</listitem>
53 <listitem>The cairo library does not handle arcs natively. Actually the CPML
54 library is able to transparently convert them to Bézier curves
55 when needed. Add more logic to do the same in the reverse side,
56 that is to automatically convert curves to arcs when a curve is
57 close enough to an arc approximation. This will bring in a new
58 information that can be used in some operation, such as getting
59 the value to put in the quote of a radial dimension or offsetting
60 a curved segment in a precise way.</listitem>
61 <listitem>Improve Bézier offset approximation algorithm, possibly enabling
62 the feature of splitting the offset curve in more than one Bézier
63 arc when the error is not acceptable.</listitem>
64 <listitem>Include a Lua shell in the Windows installer for interactively
65 playing with the ADG canvas on that platform.</listitem>
70 <simplesect id="TODO.1.0.0">
71 <title>Road to adg-1.0.0</title>
73 <para>The commits to the 0.9 branch should be considered beta releases and are
74 supposed to solely improve stability. Addition to the API is still
75 possible though.</para>
77 <para>These releases should reach the wider audience, according to a niche
78 project such as the ADG canvas. This means each release should build
79 cleanly on different platforms such as FreeBSD and must be cross
80 compilable for Windows with MinGW.</para>
82 <itemizedlist mark="circle">
83 <listitem override="disc">Ensure at least one big project is used successfully in production.</listitem>
84 <listitem override="disc">Allow to phase out specific entities from extents computation. This
85 is required in order to make tables and title blocks that should
86 be fixed in global space.</listitem>
87 <listitem override="disc">Improve the text generation for quotes, allowing
88 different formatting, e.g. specific number of decimals and sexagesimal
89 representation of angles.</listitem>
90 <listitem override="disc">Remove all warnings generated by newer tools, specifically the ones
91 generated by gtk-doc and by clang.</listitem>
92 <listitem>Ensure no regressions have been introduced by the last commits.</listitem>
97 <simplesect id="TODO.0.9.0">
98 <title>Road to adg-0.9.0</title>
100 <para>The 0.8 branch should focus on improving the testing units and the
101 coverage report.</para>
103 <itemizedlist mark="disc">
104 <listitem>Add full sanity checks, that is on every API that must supports it
105 (all the GObject based APIs) ensure that feeding weird parameters
106 does not make the library crash.</listitem>
107 <listitem>Add support for test coverage, for example by leveraging the
108 Coveralls service provided freely by GitHub.</listitem>
109 <listitem>Instead of just providing a bunch of HTML file as documentation,
110 include a single PDF file inside the Windows installer. This is
111 also a more common convention in the Windows world.</listitem>
112 <listitem>The Windows installer needs to include a minimum set of icons to
113 let adg-demo run without warnings (e.g. the the + and - icons of
114 a GtkSpinButton widget).</listitem>
119 <simplesect id="TODO.0.8.0">
120 <title>Road to adg-0.8.0</title>
122 <para>The commits in the 0.7 branch should be atomics, that is a successful
123 build will be added as a prerequisite for each commit, so bisecting
124 with "git bisect" should be usable. The API should be considered almost
125 frozen. This is a testing branch: the target is to reach a sufficient
126 quality level to make beta releases.</para>
128 <itemizedlist mark="disc">
129 <listitem>Add a compilation prerequisite triggered by the commit hook, e.g.
130 leverage the TravisCI service provided by GitHub.</listitem>
131 <listitem>Check the test coverage by using gcov and eventually raise it to
132 at least 90%.</listitem>
133 <listitem>Add internationalization support to the installer: this includes also
134 the possibility to select the installation of language packs.</listitem>
135 <listitem>Improve the current internationalization support of the ADG: merge
136 po-properties/ into po/ and get rid of glib-gettext. Check the gleak
137 project for suggestions.</listitem>
138 <listitem>Provide a complete set of bindings based on GObject introspection and
139 develop a full-fledged adg-demo application with those bindings that
140 does the same job of adg-demo.c, in the same way.</listitem>
141 <listitem>Include a set of custom icons to visually differentiate the different
142 actions triggered by the cpml-demo program.</listitem>
147 <simplesect id="TODO.0.7.0">
148 <title>Road to adg-0.7.0</title>
150 <para>The target of the 0.6 branch is to clean up the code and stabilize the
151 API: the 0.7.0 release will probably be a beta release.</para>
153 <itemizedlist mark="disc">
154 <listitem>Add autoscaling to AdgCanvas. In other words, there must be a way
155 to select a specific scale from a finite set of predefined factors
156 depending on the current extents of the canvas.</listitem>
157 <listitem>Actually AdgLineStyle can change color, width, cap, join, miter
158 limit and antialiasing of a line. The only thing remaining is
159 the possibility to customize the dashing of a dashed line.</listitem>
160 <listitem>Provide a Windows installer (32 and 64 platforms) for the demo
161 program to show what can be accomplished with the ADG canvas.</listitem>
162 <listitem>Provide a document with API guidelines take it as the holy bible!
163 All the APIs must comply with the rules of this document.</listitem>
164 <listitem>Try to cross compile and build a windows binary package. Check out
165 <ulink url="http://ricardo.ecn.wfu.edu/~cottrell/cross-gtk/">Allin suggestions</ulink>
166 for hints.</listitem>
167 <listitem>Add printing support with page setup based on GtkPrintOperation provided
168 by GTK+ 2.10 (hence, always available if GTK+ support is enable).</listitem>
169 <listitem>Uncomplete entities should fail gracefully instead of complaining for
170 insufficient data. For example, a linear dimension without the
171 needed pairs should simply not be rendered without warnings.
172 This provides an easy way to implement optional machinings.</listitem>
173 <listitem>Expose conventions used by ADG APIs: this is mainly needed to make clear
174 getters must be considered read-only, also when returning non-const
175 values (because object referencing is always allowed).</listitem>
176 <listitem>Add italian localization.</listitem>
177 <listitem>Implement AdgGtkLayout, a new GTK+ widget that adds scrolling
178 capabilities to AdgGtkArea.</listitem>
179 <listitem>Add a new tab to the edit dialog of adg-demo to change the content
180 of the title block with custom labels.</listitem>
181 <listitem>Implement a decent "make check" target, basing the check programs on
182 the test framework of glib. Make this an optional feature, as this
183 framework is based on the too young glib-2.16.0.</listitem>
184 <listitem>Resolve the TODOs in the adg/ directory: the only missing logic
185 should come from the CPML library (and there the TODO items are
186 bound to the less common use cases).</listitem>
187 <listitem>Add support for GTK+3, possibly adding an optional check at configure
188 time and trying to keep the same codebase.</listitem>
189 <listitem>Enhance the AdgRDim class by adding an alternative rendering when the
190 "outside" property is enabled.</listitem>
191 <listitem>Create a separate project called adg-lua to host the lua bindings for
192 the ADG project. Provide a demo similar to adg-demo in lua.</listitem>
197 <simplesect id="TODO.0.6.0">
198 <title>Road to adg-0.6.0</title>
200 <para>The target of the 0.5 branch is to provide a usable canvas: with usable
201 it is meant a canvas that can generate fairly completed drawings. The
202 0.5.x releases leading up to 0.6.0 should add all the missing features
203 needed to generate this drawing.</para>
205 <itemizedlist mark="disc">
206 <listitem>Implement adg_matrix_normalize() to get rid of the scaling component
207 of a matrix: consider the point (0,0) and (1,1) on the identity matrix
208 and force on the matrix to normalize a distance of 1.4142... between
209 the same points by modifying only the xx and yy components.</listitem>
210 <listitem>Move the custom get_local_matrix() inside AdgEntity and implement a
211 common way to manage local matrix - entity interaction: for instance,
212 if the model is rotated an AdgToyText should rotate accordling but not
213 scale (usually, at least if it is not a text written on the model).</listitem>
214 <listitem>Implement AdgMarker as an abstract entity: it will be the base class
215 for arrows, ticks, squares, dots and so on.</listitem>
216 <listitem>Implement AdgArrow as AdgMarker derived entity.</listitem>
217 <listitem>Implement AdgArrowStyle directly inside the AdgDimStyle class and
218 provides a way to customize the markers.</listitem>
219 <listitem>Rework the style approach by detaching the slot and type concepts:
220 rename slot to dress and let the door opened to future expansion by
221 breaking the one style = one dress equation.</listitem>
222 <listitem>Rewrite AdgLDim to use the new marker APIs instead of hardcoding the
223 arrows and calling the deprecated rendering callbacks.</listitem>
224 <listitem>Implement the extents infrastructure that computes the bounding box
225 of the entities without rendering them.</listitem>
226 <listitem>Implement the outside arrows in AdgLDim.</listitem>
227 <listitem>Add AdgADim, the angular dimension.</listitem>
228 <listitem>Implement AdgEdges, a model that computes the edges of an AdgTrail
229 model and build a CpmlPath containing all the vertical edges.</listitem>
230 <listitem>Add AdgRDim, the radial dimension.</listitem>
231 <listitem>Rework styles by using GObject and properties.</listitem>
232 <listitem>Implement an abstract AdgFillStyle, abstracting the cairo_pattern_t
233 APIs and providing a way to customize filling, similar to what
234 AdgLineStyle does for stroking.</listitem>
235 <listitem>Add AdgRuledFill, an AdgFillStyle implementation that allows to fill
236 with a serie of parallel lines with customizable angle and distance.</listitem>
237 <listitem>Add AdgHatch, an entity very similar to AdgStroke but that uses
238 cairo_fill() instead of cairo_stroke().</listitem>
239 <listitem>Implement the extents also for the path so the AdgHatch entity can work
240 reliable: check if it is better to add new code in CPML or to directly
241 use the functions provided by cairo. (Implemented in CPML as the arc
242 primitive is not native in cairo and it is the only one with some quirks
243 in the extents computation)</listitem>
244 <listitem>Add labeling feature to the models and let AdgDim and children points
245 be expressed as references to those labeled points instead of using
246 explicit coordinates.</listitem>
247 <listitem>Add AdgTable, a container for AdgToyText in a framed environment.</listitem>
248 <listitem>Add AdgTitleBlock, a complex entity in global space used to frame the
249 sheet and show the general drawing data (title, scale, date and so on).</listitem>
250 <listitem>The dressing feature needs more attention: they are still not well
251 polished and always using the "dress" property will likely give name
252 conflicts: a basic mangling is required.</listitem>
253 <listitem>Allow the linear dimension to be decentralized by using the pos point
254 as reference and using a dedicated enum instead of a three-state.</listitem>
255 <listitem>Sanitize the ADG APIs: the public functions must cope with invalid
256 arguments without segmentation faults (without crossing the limits of
257 the C language and of the common sense).</listitem>
258 <listitem>Provide a decent demo program to show the progress so far, including
259 title block, hatches and various dimensions types: update the website
260 with new (and hopefully more impressive) screenshots.</listitem>
265 <simplesect id="TODO.0.5.0">
266 <title>Road to adg-0.5.0</title>
268 <para>The target of the 0.4 branch is to build the base of the canvas:
269 few user visible changes but a quite stable base code. All the
270 main infrastructures should be in place.</para>
272 <itemizedlist mark="disc">
273 <listitem>Develop a basic demo CPML program to visually check the results.</listitem>
274 <listitem>Provide CPML APIs for accessing cairo paths and browse their segments
275 (a contiguous line segment).</listitem>
276 <listitem>Provide CPML APIs for accessing segments and browse their primitives
277 (a single line / curve / close path).</listitem>
278 <listitem>CPML APIs to offset cairo paths: specifically, a decent
279 approximation for single Bézier curves must be implemented.</listitem>
280 <listitem>Implement APIs to get intersection points between different primitives.</listitem>
281 <listitem>Provide an abstract API (cpml_segment_intersection?) to compute the
282 intersection points between two segments. To be evaluated the way to
283 return the results (maybe using an argument to specify the maximum
284 number of intersections to return).</listitem>
285 <listitem>Generate documentation for CPML.</listitem>
286 <listitem>Merge ldim and adg-demo into a single demo program, basing the user
287 interface on GtkBuilder.</listitem>
288 <listitem>Implement AdgModel as a bare empty class. Move the actual stuff in
289 AdgTitleBlock.</listitem>
290 <listitem>Add model-view interaction by providing signal propagation from AdgModel
291 to the dependent entities, so when a data changes the entities will be
292 automatically updated.</listitem>
293 <listitem>Rename AdgPath to AdgStroke, being the latter a stroke representation
294 of a single AdgPath.</listitem>
295 <listitem>Implement AdgPath as an AdgModel derived class of a conceptual path.
296 Any AdgPath instance could be referenced by one or more entities.</listitem>
297 <listitem>Add arcs in CPML to transparently support, whenever possible, the
298 conversion between arcs and Bézier curves.</listitem>
299 <listitem>Add to AdgPath the basic functionality to build a path: basically a
300 bunch of methods emulating the cairo path API but without the need of
301 a yet instantiated cairo context.</listitem>
302 <listitem>Add support for the CPML arc feature in AdgPath.</listitem>
303 <listitem>Update the demo using the newly implemented AdgPath to deeply test the
304 model/entity interaction.</listitem>
305 <listitem>Add a chamfer operation to AdgPath.</listitem>
306 <listitem>Add a fillet operation to AdgPath.</listitem>
307 <listitem>Change the matrix entity API, using a cleaner approach.</listitem>
308 <listitem>Move AdgTranslatable and AdgRotable directly inside AdgEntity.</listitem>
309 <listitem>Ensure there are no bitfield flags, as they are not binding friendly.</listitem>
310 <listitem>Change building scripts to get the GTK+ dependency optional.</listitem>
311 <listitem>Add AdgGtkArea, a GtkDrawingArea that can accept an AdgCanvas.</listitem>
312 <listitem>Optimize the implemented entities applying the 0.4 ADG infractrusture
313 and enable caching where applicable.</listitem>
314 <listitem>Use AdgToyText to draw dimenstion quote where applicable.</listitem>
315 <listitem>Add a "beyond" property to AdgDimStyle to be used when extending the
316 baseline beyond the extension lines. If not specified, it must default
317 to 3 x arrow size.</listitem>
318 <listitem>Add a three-state enum to adg-enums.h: ADG_THREE_STATE_OFF,
319 ADG_THREE_STATE_ON and ADG_THREE_STATE_UNKNOWN.</listitem>
320 <listitem>Add the three-state "outside" property to allow forcing an outside quote.
321 In the default state, the outside must be decided by the space between
322 the extension lines: if greather than 3 x arrow size => inside arrows.</listitem>
327 <simplesect id="TODO.0.4.0">
328 <title>Road to adg-0.4.0</title>
330 <para>The target for the 0.3 branch is to give a shape to the project: build
331 system, docs and a bunch of (probably temporary) basic classes should
332 be enough to give a direction.</para>
334 <itemizedlist mark="disc">
335 <listitem>Split mathematic stuff in its own library. It will be called CPML,
336 that is Cairo Path Manipulation Library.</listitem>
337 <listitem>Avoid wrapping of cairo APIs in AdgPath.</listitem>
338 <listitem>Implement AdgToyText, a basic text entity using the cairo "toy" text API.</listitem>
339 <listitem>Implement AdgTranslatable, a shared interface for entities that
340 can be translated.</listitem>
341 <listitem>Implement AdgRotable, a shared interface for entities that can be rotated.</listitem>