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
|
<!-- vim:tabstop=4:shiftwidth=4:noexpandtab:textwidth=80
-->
<sect1 id="kernel_part_cannotation">
<title>CAnnotation</title>
<para>
Annotation is interactive entity which is associated with rectangle
on page. They are organized in <emphasis>Annots</emphasis> array
entry in page dictionary and so <classname>CPage</classname> is responsible for returning of
all available annotations and also to provide interface to add new
annotation.
</para>
<para>
Each annotations is described by dictionary, which has to contain at
least <emphasis>Type</emphasis> element with <emphasis>Annot</emphasis>
and <emphasis>Subtype</emphasis> element with concrete annotation type.
Pdf specification describes several types of annotation types (e. g.
text annotation - which describes text box floating upon normal page
text, link annotation - which enables to jump to the target within document
or to perform certain action when link is activated by mouse click).
<emphasis>Rect</emphasis> element should be present as well, because it
specifies where annotation should be spreaded.
</para>
<para>
CAnnotation represents such annotation and provides simple interface to
manipulate elements in annotation dictionary. It implements
<classname>ObserverHandler</classname> (see <xref linkend="general_utils_observers"/>) to anable user
to be informed about changes inside annotation dictionary. This class
provides just simple interface for internal manipulation and it is
intended to be base class for specific annotation types (no such
specialized class are available yet, because they are not required by
project in this moment).
</para>
<sect2 id="instance_creation">
<title>Instance creation</title>
<para>
Instance can be created in 2 different ways.
</para>
<para>
First possibility is to use existing annotation dictionary (e. g.
fetched from document). This way is used in <xref linkend="kernel_part_cpage"/>
class where already existing annotations are fetched and used for
CAnnotation instance.
</para>
<para>
Second way is to use factory
<programlisting>
<code>
<![CDATA[
static boost::shared_ptr<CAnnotation>
createAnnotation(Rectangle rect, std::string annotType);
]]>
</code>
</programlisting>
method (see <xref linkend="factory_method"/>). This method uses
internal <classname>annotInit</classname> static <xref linkend="kernel_part_annot_initializator"/>.
Intializator is responsible for correct annotation dictionary
initialization according given type and for given rectangle.
This is safe way how to create new annotation instances.
</para>
</sect2>
<sect2 id="kernel_part_annot_initializator">
<title>Annotation initializator</title>
<para>
Annotation initializator represented by <classname>IAnnotInitializator</classname>
abstract class. It provides <xref linkend="functor"/> which
intialize given dictionary with correct data according given type.
Initializator is designed as <xref linkend="composite"/> and so one
initializator class can support initialization of several annotation
types (getSupportedList returns annotation types which are supported
by this initializator).
</para>
<para>
We have implemented <classname>UniversalAnnotInitializer</classname>
which adds
<programlisting>
<code>
<![CDATA[
bool registerInitializer(std::string annotType, boost::shared_ptr<IAnnotInitializator> impl, bool forceNew=false);
]]>
</code>
</programlisting>
method responsible for registration of other initializator to
composite of initializators. When
<classname>createAnnotation</classname> is called,
<classname>UniversalAnnotInitializer</classname> choose registered
implementetator which supports such annotation type.
UniversalAnnotInitializer itself just initializes common elements
for all annotations (such as Type, Subtype, Rect elements).
</para>
</sect2>
<mediaobject>
<imageobject>
<imagedata fileref="kernel/images/cannotation.png" format="PNG"/>
</imageobject>
<caption><para>CAnnotation class hierarchy</para></caption>
</mediaobject>
</sect1>
|
