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_modecontroller">
<title>ModeController</title>
<para>
Mode controller is class which provides us with property mode
configuration. Each property keeps its mode. This is just
information (kind of tag) which can be used by property user to
determine how he should present it to application user. This is not
any kind of restriction how property can be used.
</para>
<para>
The reason why to create such mode is that Pdf has many objects
which are good for changes and some of them are just technical
or more they contain meta data. Changes made to meta data or
technical objects may lead to total corruption of whole document
with very less effort (e. g. change of reference to page tree root
leads to all pages lost). We didn't want to have what is possible
and what not logic hardcoded in kernel. So we have defined mode for
property and GUI which displays objects in property editor may look
at property mode and decide whether it provides read only, visible
or warning throwing access (GUI can also provide configuration how
each mode should be treated).
</para>
<para>
<classname>ModeController</classname> class is responsible to provide
mode to property according property name (id) and the type of parent
type. All pdf properties are part of certain context (parent data).
This context may be dictionary or array or object can be indirect
and in so it is its own context. ModeController is based on
<classname>RulesManager</classname> (see <xref linkend="general_utils_rulesmanager"/>).
As a rule data type, we use
<programlisting>
<code>
<![CDATA[
struct ModeRule
{
std::string type;
std::string name;
bool operator==(const ModeRule & rule)const
{
return type==rule.type && name==rule.name;
}
};
]]>
</code>
</programlisting>
structure. Type stands for context type (Type field value of parent data
type or itself if object is indirect and so it has no parent) and name
stands for name of property in context.
</para>
<para>
Property matcher implemented for ModeController defines 3 priorities of
matching with following logic:
<itemizedlist>
<listitem>original={"", ""} - rule allways matches with PRIO0 priority.
</listitem>
<listitem>original={type, ""} - rule matches if rule.type==original.type with
PRIO1 priority.
</listitem>
<listitem>original={"", name} - rule matches if rule.name==original.name with
PRIO2 priority.
</listitem>
<listitem>original={type, name} - rule matches if original==rule with
PRIO3 priority.
</listitem>
<listitem> PRIO0 < PRIO1 < PRIO2 < PRIO3
</listitem>
</itemizedlist>
This enables to define rules with more or less general meaning and
explicit setting for one property.
</para>
<para>
Inherited RulesManager enables configuration loading from stream by
default. We have additionally implemented
<classname>ModeConfigurationParser</classname> which is able to parse
strings from configuration file. To be less dependant on particular
configuration file format, we have built it upon
<classname>StringConfigurationParser</classname> which simply reads
key value pairs. from file and ModeConfigurationParser transforms this
values to its internals data types for rule and target (ModeRule and
Mode types). This is example of <xref linkend="adapter"/> implementation.
</para>
<para>
We have written also example configuration file (this file is stored in
data directory - by default /usr/share/pdfedit, but depends on
<emphasis>prefix</emphasis> parameter during installation)
with quite reasonablerestrictions. For more inforamtion about file
format and mode types, please see project doxygen documentation for
ModeController.
</para>
<mediaobject>
<imageobject align="center">
<imagedata fileref="kernel/images/modecontroller.png" format="PNG"/>
</imageobject>
<caption><para>Mode controller and related classes.</para></caption>
</mediaobject>
</sect1>
|
