1 /***************************************************************************
2 * Copyright (C) 2006 by Dominik Seichter *
3 * domseichter@web.de *
4 * *
5 * This program is free software; you can redistribute it and/or modify *
6 * it under the terms of the GNU Library General Public License as *
7 * published by the Free Software Foundation; either version 2 of the *
8 * License, or (at your option) any later version. *
9 * *
10 * This program is distributed in the hope that it will be useful, *
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
13 * GNU General Public License for more details. *
14 * *
15 * You should have received a copy of the GNU Library General Public *
16 * License along with this program; if not, write to the *
17 * Free Software Foundation, Inc., *
18 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. *
19 * *
20 * In addition, as a special exception, the copyright holders give *
21 * permission to link the code of portions of this program with the *
22 * OpenSSL library under certain conditions as described in each *
23 * individual source file, and distribute linked combinations *
24 * including the two. *
25 * You must obey the GNU General Public License in all respects *
26 * for all of the code used other than OpenSSL. If you modify *
27 * file(s) with this exception, you may extend this exception to your *
28 * version of the file(s), but you are not obligated to do so. If you *
29 * do not wish to do so, delete this exception statement from your *
30 * version. If you delete this exception statement from all source *
31 * files in the program, then also delete it here. *
32 ***************************************************************************/
33
34 #ifndef _PDF_ELEMENT_H_
35 #define _PDF_ELEMENT_H_
36
37 #include "podofo/base/PdfDefines.h"
38 #include "podofo/base/PdfObject.h"
39
40 namespace PoDoFo {
41
42 class PdfStreamedDocument;
43 class PdfVecObjects;
44
45 /** PdfElement is a common base class for all elements
46 * in a PDF file. For example pages, action and annotations.
47 *
48 * Every PDF element has one PdfObject and provides an easier
49 * interface to modify the contents of the dictionary.
50 *
51 * A PdfElement base class can be created from an existing PdfObject
52 * or created from scratch. In the later case, the PdfElement creates
53 * a PdfObject and adds it to a vector of objects.
54 *
55 * A PdfElement cannot be created directly. Use one
56 * of the subclasses which implement real functionallity.
57 *
58 * \see PdfPage \see PdfAction \see PdfAnnotation
59 */
60 class PODOFO_DOC_API PdfElement {
61
62 public:
63
64 virtual ~PdfElement();
65
66 /** Get access to the internal object
67 * \returns the internal PdfObject
68 */
69 inline PdfObject* GetObject();
70
71 /** Get access to the internal object
72 * This is an overloaded member function.
73 *
74 * \returns the internal PdfObject
75 */
76 inline const PdfObject* GetObject() const;
77
78 protected:
79 /** Creates a new PdfElement
80 * \param pszType type entry of the elements object
81 * \param pParent parent vector of objects.
82 * Add a newly created object to this vector.
83 */
84 PdfElement( const char* pszType, PdfVecObjects* pParent );
85
86 /** Creates a new PdfElement
87 * \param pszType type entry of the elements object
88 * \param pParent parent PdfDocument.
89 * Add a newly created object to this vector.
90 */
91 PdfElement( const char* pszType, PdfDocument* pParent );
92
93 /** Create a PdfElement from an existing PdfObject
94 * The object must be a dictionary.
95 *
96 * \param pszType type entry of the elements object.
97 * Throws an exception if the type in the
98 * PdfObject differs from pszType.
99 * \param pObject pointer to the PdfObject that is modified
100 * by this PdfElement
101 */
102 PdfElement( const char* pszType, PdfObject* pObject );
103
104 /** Create a PdfElement from an existing PdfObject
105 * The object might be of any data type,
106 * PdfElement will throw an exception if the PdfObject
107 * if not of the same datatype as the expected one.
108 * This is necessary in rare cases. E.g. in PdfContents.
109 *
110 * \param eExpectedDataType the expected datatype of this object
111 * \param pObject pointer to the PdfObject that is modified
112 * by this PdfElement
113 */
114 PdfElement( EPdfDataType eExpectedDataType, PdfObject* pObject );
115
116
117 /** Convert an enum or index to its string representation
118 * which can be written to the PDF file.
119 *
120 * This is a helper function for various PdfElement
121 * subclasses that need strings and enums for their
122 * SubTypes keys.
123 *
124 * \param i the index or enum value
125 * \param ppTypes an array of strings containing
126 * the string mapping of the index
127 * \param lLen the length of the string array
128 *
129 * \returns the string representation or NULL for
130 * values out of range
131 */
132 const char* TypeNameForIndex( int i, const char** ppTypes, long lLen ) const;
133
134 /** Convert a string type to an array index or enum.
135 *
136 * This is a helper function for various PdfElement
137 * subclasses that need strings and enums for their
138 * SubTypes keys.
139 *
140 * \param pszType the type as string
141 * \param ppTypes an array of strings containing
142 * the string mapping of the index
143 * \param lLen the length of the string array
144 * \param nUnknownValue the value that is returned when the type is unknown
145 *
146 * \returns the index of the string in the array
147 */
148 int TypeNameToIndex( const char* pszType, const char** ppTypes, long lLen, int nUnknownValue ) const;
149
150 /** Create a PdfObject in the parent of this PdfElement which
151 * might either be a PdfStreamedDocument, a PdfDocument or
152 * a PdfVecObjects
153 *
154 * Use this function in an own subclass of PdfElement to create new
155 * PdfObjects.
156 *
157 * \param pszType an optional /Type key of the created object
158 *
159 * \returns a PdfObject which is owned by the parent
160 */
161 PdfObject* CreateObject( const char* pszType = NULL );
162
163 /** Get access to the internal object.
164 * Use this method if you need access to the internal
165 * object in a const-method without having to do a const cast.
166 *
167 * \returns the internal PdfObject
168 */
169 inline PdfObject* GetNonConstObject() const;
170
171 private:
172 PdfObject* m_pObject;
173 };
174
175 // -----------------------------------------------------
176 //
177 // -----------------------------------------------------
GetObject()178 inline PdfObject* PdfElement::GetObject()
179 {
180 return m_pObject;
181 }
182
183 // -----------------------------------------------------
184 //
185 // -----------------------------------------------------
GetObject()186 inline const PdfObject* PdfElement::GetObject() const
187 {
188 return m_pObject;
189 }
190
191 // -----------------------------------------------------
192 //
193 // -----------------------------------------------------
GetNonConstObject()194 inline PdfObject* PdfElement::GetNonConstObject() const
195 {
196 return const_cast<PdfElement*>(this)->m_pObject;
197 }
198
199 };
200
201 #endif // PDF_ELEMENT_H_
202