Initial commit.
[pdfium.git] / fpdfsdk / include / fpdftext.h
1 // Copyright 2014 PDFium Authors. All rights reserved.\r
2 // Use of this source code is governed by a BSD-style license that can be\r
3 // found in the LICENSE file.\r
4  \r
5 // Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com\r
6 \r
7 #ifndef _FPDFTEXT_H_\r
8 #define _FPDFTEXT_H_\r
9 \r
10 #include "fpdfview.h"\r
11 \r
12 // Exported Functions\r
13 #ifdef __cplusplus\r
14 extern "C" {\r
15 #endif\r
16 \r
17 // Function: FPDFText_LoadPage\r
18 //                      Prepare information about all characters in a page.\r
19 // Parameters: \r
20 //                      page    -       Handle to the page. Returned by FPDF_LoadPage function (in FPDFVIEW module).    \r
21 // Return value:\r
22 //                      A handle to the text page information structure.\r
23 //                      NULL if something goes wrong.\r
24 // Comments:\r
25 //                      Application must call FPDFText_ClosePage to release the text page information.\r
26 //                      If you don't purchase Text Module , this function will return NULL.\r
27 //      \r
28 DLLEXPORT FPDF_TEXTPAGE STDCALL FPDFText_LoadPage(FPDF_PAGE page);\r
29 \r
30 // Function: FPDFText_ClosePage\r
31 //                      Release all resources allocated for a text page information structure.\r
32 // Parameters: \r
33 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
34 // Return Value:\r
35 //                      None.\r
36 //\r
37 DLLEXPORT void STDCALL FPDFText_ClosePage(FPDF_TEXTPAGE text_page);\r
38         \r
39 // Function: FPDFText_CountChars\r
40 //                      Get number of characters in a page.\r
41 // Parameters: \r
42 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
43 // Return value:\r
44 //                      Number of characters in the page. Return -1 for error. \r
45 //                      Generated characters, like additional space characters, new line characters, are also counted.\r
46 // Comments:\r
47 //                      Characters in a page form a "stream", inside the stream, each character has an index.\r
48 //                      We will use the index parameters in many of FPDFTEXT functions. The first character in the page\r
49 //                      has an index value of zero.\r
50 //\r
51 DLLEXPORT int STDCALL FPDFText_CountChars(FPDF_TEXTPAGE text_page);\r
52 \r
53 // Function: FPDFText_GetUnicode\r
54 //                      Get Unicode of a character in a page.\r
55 // Parameters: \r
56 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
57 //                      index           -       Zero-based index of the character.\r
58 // Return value:\r
59 //                      The Unicode of the particular character.\r
60 //                      If a character is not encoded in Unicode and Foxit engine can't convert to Unicode,\r
61 //                      the return value will be zero.\r
62 //\r
63 DLLEXPORT unsigned int STDCALL FPDFText_GetUnicode(FPDF_TEXTPAGE text_page, int index);\r
64 \r
65 // Function: FPDFText_GetFontSize\r
66 //                      Get the font size of a particular character.\r
67 // Parameters: \r
68 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
69 //                      index           -       Zero-based index of the character.\r
70 // Return value:\r
71 //                      The font size of the particular character, measured in points (about 1/72 inch).\r
72 //                      This is the typographic size of the font (so called "em size").\r
73 //\r
74 DLLEXPORT double STDCALL FPDFText_GetFontSize(FPDF_TEXTPAGE text_page, int index);\r
75 \r
76 // Function: FPDFText_GetCharBox\r
77 //                      Get bounding box of a particular character.\r
78 // Parameters: \r
79 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
80 //                      index           -       Zero-based index of the character.\r
81 //                      left            -       Pointer to a double number receiving left position of the character box.\r
82 //                      right           -       Pointer to a double number receiving right position of the character box.\r
83 //                      bottom          -       Pointer to a double number receiving bottom position of the character box.\r
84 //                      top                     -       Pointer to a double number receiving top position of the character box.\r
85 // Return Value:\r
86 //                      None.\r
87 // Comments:\r
88 //                      All positions are measured in PDF "user space".\r
89 //\r
90 DLLEXPORT void STDCALL FPDFText_GetCharBox(FPDF_TEXTPAGE text_page, int index, double* left,\r
91                                                                                                         double* right, double* bottom, double* top);\r
92 \r
93 // Function: FPDFText_GetCharIndexAtPos\r
94 //                      Get the index of a character at or nearby a certain position on the page.\r
95 // Parameters:\r
96 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
97 //                      x                       -       X position in PDF "user space".\r
98 //                      y                       -       Y position in PDF "user space".\r
99 //                      xTolerance      -       An x-axis tolerance value for character hit detection, in point unit.\r
100 //                      yTolerance      -       A y-axis tolerance value for character hit detection, in point unit.\r
101 // Return Value:\r
102 //                      The zero-based index of the character at, or nearby the point (x,y).\r
103 //                      If there is no character at or nearby the point, return value will be -1.\r
104 //                      If an error occurs, -3 will be returned.\r
105 //\r
106 DLLEXPORT int STDCALL FPDFText_GetCharIndexAtPos(FPDF_TEXTPAGE text_page,\r
107                                                                                                  double x, double y, double xTorelance, double yTolerance);\r
108 \r
109 // Function: FPDFText_GetText\r
110 //                      Extract unicode text string from the page.\r
111 // Parameters:\r
112 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
113 //                      start_index     -       Index for the start characters.\r
114 //                      count           -       Number of characters to be extracted.\r
115 //                      result          -       A buffer (allocated by application) receiving the extracted unicodes.\r
116 //                                                      The size of the buffer must be able to hold the number of characters plus a terminator.\r
117 // Return Value:\r
118 //                      Number of characters written into the result buffer, including the trailing terminator.\r
119 // Comments:\r
120 //                      This function ignores characters without unicode information.\r
121 //                      \r
122 DLLEXPORT int STDCALL FPDFText_GetText(FPDF_TEXTPAGE text_page, int start_index, int count, unsigned short* result);\r
123 \r
124 // Function: FPDFText_CountRects\r
125 //                      Count number of rectangular areas occupied by a segment of texts.\r
126 // Parameters:\r
127 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
128 //                      start_index     -       Index for the start characters.\r
129 //                      count           -       Number of characters.\r
130 // Return value:\r
131 //                      Number of rectangles. Zero for error.\r
132 // Comments:\r
133 //                      This function, along with FPDFText_GetRect can be used by applications to detect the position\r
134 //                      on the page for a text segment, so proper areas can be highlighted or something.\r
135 //                      FPDFTEXT will automatically merge small character boxes into bigger one if those characters\r
136 //                      are on the same line and use same font settings.\r
137 //\r
138 DLLEXPORT int STDCALL FPDFText_CountRects(FPDF_TEXTPAGE text_page, int start_index, int count);\r
139 \r
140 // Function: FPDFText_GetRect\r
141 //                      Get a rectangular area from the result generated by FPDFText_CountRects.\r
142 // Parameters:\r
143 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
144 //                      rect_index      -       Zero-based index for the rectangle.\r
145 //                      left            -       Pointer to a double value receiving the rectangle left boundary.\r
146 //                      top                     -       Pointer to a double value receiving the rectangle top boundary.\r
147 //                      right           -       Pointer to a double value receiving the rectangle right boundary.\r
148 //                      bottom          -       Pointer to a double value receiving the rectangle bottom boundary.\r
149 // Return Value:\r
150 //                      None.\r
151 //\r
152 DLLEXPORT void STDCALL FPDFText_GetRect(FPDF_TEXTPAGE text_page, int rect_index, double* left, double* top,\r
153                                                                                         double* right, double* bottom);\r
154 \r
155 // Function: FPDFText_GetBoundedText\r
156 //                      Extract unicode text within a rectangular boundary on the page.\r
157 // Parameters:\r
158 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
159 //                      left            -       Left boundary.\r
160 //                      top                     -       Top boundary.\r
161 //                      right           -       Right boundary.\r
162 //                      bottom          -       Bottom boundary.\r
163 //                      buffer          -       A unicode buffer.\r
164 //                      buflen          -       Number of characters (not bytes) for the buffer, excluding an additional terminator.\r
165 // Return Value:\r
166 //                      If buffer is NULL or buflen is zero, return number of characters (not bytes) needed,\r
167 //                      otherwise, return number of characters copied into the buffer.\r
168 //\r
169 DLLEXPORT int STDCALL FPDFText_GetBoundedText(FPDF_TEXTPAGE text_page,double left, double top, \r
170                                                                                           double right, double bottom,unsigned short* buffer,int buflen);\r
171 \r
172 \r
173 // Flags used by FPDFText_FindStart function.\r
174 #define FPDF_MATCHCASE      0x00000001          //If not set, it will not match case by default.\r
175 #define FPDF_MATCHWHOLEWORD 0x00000002          //If not set, it will not match the whole word by default.\r
176 \r
177 // Function: FPDFText_FindStart\r
178 //                      Start a search.\r
179 // Parameters:\r
180 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
181 //                      findwhat        -       A unicode match pattern.\r
182 //                      flags           -       Option flags.\r
183 //                      start_index     -       Start from this character. -1 for end of the page.\r
184 // Return Value:\r
185 //                      A handle for the search context. FPDFText_FindClose must be called to release this handle.\r
186 //\r
187 DLLEXPORT FPDF_SCHHANDLE STDCALL FPDFText_FindStart(FPDF_TEXTPAGE text_page, FPDF_WIDESTRING findwhat,\r
188                                                                                                         unsigned long flags, int start_index);\r
189 \r
190 // Function: FPDFText_FindNext\r
191 //                      Search in the direction from page start to end.\r
192 // Parameters:\r
193 //                      handle          -       A search context handle returned by FPDFText_FindStart.\r
194 // Return Value:\r
195 //                      Whether a match is found.\r
196 //\r
197 DLLEXPORT FPDF_BOOL STDCALL FPDFText_FindNext(FPDF_SCHHANDLE handle);\r
198 \r
199 // Function: FPDFText_FindPrev\r
200 //                      Search in the direction from page end to start.\r
201 // Parameters:\r
202 //                      handle          -       A search context handle returned by FPDFText_FindStart.\r
203 // Return Value:\r
204 //                      Whether a match is found.\r
205 //\r
206 DLLEXPORT FPDF_BOOL STDCALL FPDFText_FindPrev(FPDF_SCHHANDLE handle);\r
207 \r
208 // Function: FPDFText_GetSchResultIndex\r
209 //                      Get the starting character index of the search result.\r
210 // Parameters:\r
211 //                      handle          -       A search context handle returned by FPDFText_FindStart.\r
212 // Return Value:\r
213 //                      Index for the starting character.\r
214 //\r
215 DLLEXPORT int STDCALL FPDFText_GetSchResultIndex(FPDF_SCHHANDLE handle);\r
216 \r
217 // Function: FPDFText_GetSchCount\r
218 //                      Get the number of matched characters in the search result.\r
219 // Parameters:\r
220 //                      handle          -       A search context handle returned by FPDFText_FindStart.\r
221 // Return Value:\r
222 //                      Number of matched characters.\r
223 //\r
224 DLLEXPORT int STDCALL FPDFText_GetSchCount(FPDF_SCHHANDLE handle);\r
225 \r
226 // Function: FPDFText_FindClose\r
227 //                      Release a search context.\r
228 // Parameters:\r
229 //                      handle          -       A search context handle returned by FPDFText_FindStart.\r
230 // Return Value:\r
231 //                      None.\r
232 //\r
233 DLLEXPORT void STDCALL FPDFText_FindClose(FPDF_SCHHANDLE handle);\r
234 \r
235 // Function: FPDFLink_LoadWebLinks\r
236 //                      Prepare information about weblinks in a page.\r
237 // Parameters:\r
238 //                      text_page       -       Handle to a text page information structure. Returned by FPDFText_LoadPage function.\r
239 // Return Value:        \r
240 //                      A handle to the page's links information structure.\r
241 //                      NULL if something goes wrong.\r
242 // Comments:\r
243 //                      Weblinks are those links implicitly embedded in PDF pages. PDF also has a type of\r
244 //                      annotation called "link", FPDFTEXT doesn't deal with that kind of link.\r
245 //                      FPDFTEXT weblink feature is useful for automatically detecting links in the page\r
246 //                      contents. For example, things like "http://www.foxitsoftware.com" will be detected,\r
247 //                      so applications can allow user to click on those characters to activate the link,\r
248 //                      even the PDF doesn't come with link annotations.\r
249 //\r
250 //                      FPDFLink_CloseWebLinks must be called to release resources.\r
251 //\r
252 DLLEXPORT FPDF_PAGELINK STDCALL FPDFLink_LoadWebLinks(FPDF_TEXTPAGE text_page);\r
253 \r
254 // Function: FPDFLink_CountWebLinks\r
255 //                      Count number of detected web links.\r
256 // Parameters:\r
257 //                      link_page       -       Handle returned by FPDFLink_LoadWebLinks.\r
258 // Return Value:\r
259 //                      Number of detected web links.\r
260 //\r
261 DLLEXPORT int STDCALL FPDFLink_CountWebLinks(FPDF_PAGELINK link_page);\r
262 \r
263 // Function: FPDFLink_GetURL\r
264 //                      Fetch the URL information for a detected web link.\r
265 // Parameters:\r
266 //                      link_page       -       Handle returned by FPDFLink_LoadWebLinks.\r
267 //                      link_index      -       Zero-based index for the link.\r
268 //                      buffer          -       A unicode buffer.\r
269 //                      buflen          -       Number of characters (not bytes) for the buffer, including an additional terminator.\r
270 // Return Value:\r
271 //                      If buffer is NULL or buflen is zero, return number of characters (not bytes and an additional terminator is also counted) needed,\r
272 //                      otherwise, return number of characters copied into the buffer.\r
273 //\r
274 DLLEXPORT int STDCALL FPDFLink_GetURL(FPDF_PAGELINK link_page, int link_index, unsigned short* buffer,int buflen);\r
275 \r
276 // Function: FPDFLink_CountRects\r
277 //                      Count number of rectangular areas for the link.\r
278 // Parameters:\r
279 //                      link_page       -       Handle returned by FPDFLink_LoadWebLinks.\r
280 //                      link_index      -       Zero-based index for the link.\r
281 // Return Value:\r
282 //                      Number of rectangular areas for the link.\r
283 //\r
284 DLLEXPORT int STDCALL FPDFLink_CountRects(FPDF_PAGELINK link_page, int link_index);\r
285 \r
286 // Function: FPDFLink_GetRect\r
287 //                      Fetch the boundaries of a rectangle for a link.\r
288 // Parameters:\r
289 //                      link_page       -       Handle returned by FPDFLink_LoadWebLinks.\r
290 //                      link_index      -       Zero-based index for the link.\r
291 //                      rect_index      -       Zero-based index for a rectangle.\r
292 //                      left            -       Pointer to a double value receiving the rectangle left boundary.\r
293 //                      top                     -       Pointer to a double value receiving the rectangle top boundary.\r
294 //                      right           -       Pointer to a double value receiving the rectangle right boundary.\r
295 //                      bottom          -       Pointer to a double value receiving the rectangle bottom boundary.\r
296 // Return Value:\r
297 //                      None.\r
298 //\r
299 DLLEXPORT void STDCALL FPDFLink_GetRect(FPDF_PAGELINK link_page, int link_index, int rect_index, \r
300                                                                                 double* left, double* top,double* right, double* bottom);\r
301 \r
302 // Function: FPDFLink_CloseWebLinks\r
303 //                      Release resources used by weblink feature.\r
304 // Parameters:\r
305 //                      link_page       -       Handle returned by FPDFLink_LoadWebLinks.\r
306 // Return Value:\r
307 //                      None.\r
308 //\r
309 DLLEXPORT void STDCALL FPDFLink_CloseWebLinks(FPDF_PAGELINK link_page);\r
310 \r
311 \r
312 #ifdef __cplusplus\r
313 };\r
314 #endif\r
315 \r
316 #endif//_FPDFTEXT_H_\r