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