« back to all changes in this revision
Viewing changes to synctex/synctex_parser.h
- browse files at revision 2142
- compare with another revision
- compare with revision 2149
- download diff
- download tarball
- view history from revision 2142
- Committer: Adam Reichold
- Date: 2022-07-23 15:52:13 UTC
- Revision ID: adam.reichold@t-online.de-20220723155213-fxl4qnc2o1zj7ivc
Update vendored SyncTeX sources to version 1.21.
- files added:
- synctex/synctex_parser_advanced.h
- files modified:
- application.pro
added
removed
synctex/synctex_parser.h
1
/*
2
Copyright (c) 2008, 2009, 2010 , 2011 jerome DOT laurens AT u-bourgogne DOT fr
3
4
This file is part of the SyncTeX package.
5
6
Latest Revision: Tue Jun 14 08:23:30 UTC 2011
7
8
Version: 1.18
9
10
See synctex_parser_readme.txt for more details
11
12
License:
13
--------
14
Permission is hereby granted, free of charge, to any person
15
obtaining a copy of this software and associated documentation
16
files (the "Software"), to deal in the Software without
17
restriction, including without limitation the rights to use,
18
copy, modify, merge, publish, distribute, sublicense, and/or sell
19
copies of the Software, and to permit persons to whom the
20
Software is furnished to do so, subject to the following
21
conditions:
22
23
The above copyright notice and this permission notice shall be
24
included in all copies or substantial portions of the Software.
25
26
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
27
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
28
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
29
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
30
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
31
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
32
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
33
OTHER DEALINGS IN THE SOFTWARE
34
35
Except as contained in this notice, the name of the copyright holder
36
shall not be used in advertising or otherwise to promote the sale,
37
use or other dealings in this Software without prior written
38
authorization from the copyright holder.
39
40
Acknowledgments:
41
----------------
42
The author received useful remarks from the pdfTeX developers, especially Hahn The Thanh,
43
and significant help from XeTeX developer Jonathan Kew
44
45
Nota Bene:
46
----------
47
If you include or use a significant part of the synctex package into a software,
48
I would appreciate to be listed as contributor and see "SyncTeX" highlighted.
49
50
Version 1
51
Thu Jun 19 09:39:21 UTC 2008
52
1
/*
2
Copyright (c) 2008-2017 jerome DOT laurens AT u-bourgogne DOT fr
3
4
This file is part of the __SyncTeX__ package.
5
6
[//]: # (Latest Revision: Fri Jul 14 16:20:41 UTC 2017)
7
[//]: # (Version: 1.21)
8
9
See `synctex_parser_readme.md` for more details
10
11
## License
12
13
Permission is hereby granted, free of charge, to any person
14
obtaining a copy of this software and associated documentation
15
files (the "Software"), to deal in the Software without
16
restriction, including without limitation the rights to use,
17
copy, modify, merge, publish, distribute, sublicense, and/or sell
18
copies of the Software, and to permit persons to whom the
19
Software is furnished to do so, subject to the following
20
conditions:
21
22
The above copyright notice and this permission notice shall be
23
included in all copies or substantial portions of the Software.
24
25
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
26
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
27
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
28
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
29
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
30
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
31
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
32
OTHER DEALINGS IN THE SOFTWARE
33
34
Except as contained in this notice, the name of the copyright holder
35
shall not be used in advertising or otherwise to promote the sale,
36
use or other dealings in this Software without prior written
37
authorization from the copyright holder.
38
39
## Acknowledgments:
40
41
The author received useful remarks from the __pdfTeX__ developers, especially Hahn The Thanh,
42
and significant help from __XeTeX__ developer Jonathan Kew.
43
44
## Nota Bene:
45
46
If you include or use a significant part of the __SyncTeX__ package into a software,
47
I would appreciate to be listed as contributor and see "__SyncTeX__" highlighted.
53
48
*/
54
49
55
50
#ifndef __SYNCTEX_PARSER__
56
51
# define __SYNCTEX_PARSER__
57
52
53
#include "synctex_version.h"
54
58
55
#ifdef __cplusplus
59
56
extern "C" {
60
57
#endif
61
62
# define SYNCTEX_VERSION_STRING "1.18"
63
64
/* synctex_node_t is the type for all synctex nodes.
65
* The synctex file is parsed into a tree of nodes, either sheet, boxes, math nodes... */
66
typedef struct _synctex_node * synctex_node_t;
67
68
/* The main synctex object is a scanner
69
* Its implementation is considered private.
70
* The basic workflow is
71
* - create a "synctex scanner" with the contents of a file
72
* - perform actions on that scanner like display or edit queries
73
* - free the scanner when the work is done
74
*/
75
typedef struct __synctex_scanner_t _synctex_scanner_t;
76
typedef _synctex_scanner_t * synctex_scanner_t;
77
78
/* This is the designated method to create a new synctex scanner object.
79
* output is the pdf/dvi/xdv file associated to the synctex file.
80
* If necessary, it can be the tex file that originated the synctex file
81
* but this might cause problems if the \jobname has a custom value.
82
* Despite this method can accept a relative path in practice,
83
* you should only pass a full path name.
84
* The path should be encoded by the underlying file system,
85
* assuming that it is based on 8 bits characters, including UTF8,
86
* not 16 bits nor 32 bits.
87
* The last file extension is removed and replaced by the proper extension.
88
* Then the private method _synctex_scanner_new_with_contents_of_file is called.
89
* NULL is returned in case of an error or non existent file.
90
* Once you have a scanner, use the synctex_display_query and synctex_edit_query below.
91
* The new "build_directory" argument is available since version 1.5.
92
* It is the directory where all the auxiliary stuff is created.
93
* Sometimes, the synctex output file and the pdf, dvi or xdv files are not created in the same directory.
94
* This is the case in MikTeX (I will include this into TeX Live).
95
* This directory path can be nil, it will be ignored then.
96
* It can be either absolute or relative to the directory of the output pdf (dvi or xdv) file.
97
* If no synctex file is found in the same directory as the output file, then we try to find one in the build directory.
98
* Please note that this new "build_directory" is provided as a convenient argument but should not be used.
99
* In fact, this is implempented as a work around of a bug in MikTeX where the synctex file does not follow the pdf file.
100
* The new "parse" argument is available since version 1.5. In general, use 1.
101
* Use 0 only if you do not want to parse the content but just check the existence.
102
*/
103
synctex_scanner_t synctex_scanner_new_with_output_file(const char * output, const char * build_directory, int parse);
104
105
/* This is the designated method to delete a synctex scanner object.
106
* Frees all the memory, you must call it when you are finished with the scanner.
107
*/
108
void synctex_scanner_free(synctex_scanner_t scanner);
109
110
/* Send this message to force the scanner to parse the contents of the synctex output file.
111
* Nothing is performed if the file was already parsed.
112
* In each query below, this message is sent, but if you need to access information more directly,
113
* you must be sure that the parsing did occur.
114
* Usage:
115
* if((my_scanner = synctex_scanner_parse(my_scanner))) {
116
* continue with my_scanner...
117
* } else {
118
* there was a problem
119
* }
120
*/
121
synctex_scanner_t synctex_scanner_parse(synctex_scanner_t scanner);
122
123
/* The main entry points.
124
* Given the file name, a line and a column number, synctex_display_query returns the number of nodes
125
* satisfying the contrain. Use code like
126
*
127
* if(synctex_display_query(scanner,name,line,column)>0) {
128
* synctex_node_t node;
129
* while((node = synctex_next_result(scanner))) {
130
* // do something with node
131
* ...
132
* }
133
* }
134
*
135
* For example, one can
136
* - highlight each resulting node in the output, using synctex_node_h and synctex_node_v
137
* - highlight all the rectangles enclosing those nodes, using synctex_box_... functions
138
* - highlight just the character using that information
139
*
140
* Given the page and the position in the page, synctex_edit_query returns the number of nodes
141
* satisfying the contrain. Use code like
142
*
143
* if(synctex_edit_query(scanner,page,h,v)>0) {
144
* synctex_node_t node;
145
* while(node = synctex_next_result(scanner)) {
146
* // do something with node
147
* ...
148
* }
149
* }
150
*
151
* For example, one can
152
* - highlight each resulting line in the input,
153
* - highlight just the character using that information
154
*
155
* page is 1 based
156
* h and v are coordinates in 72 dpi unit, relative to the top left corner of the page.
157
* If you make a new query, the result of the previous one is discarded.
158
* If one of this function returns a non positive integer,
159
* it means that an error occurred.
160
*
161
* Both methods are conservative, in the sense that matching is weak.
162
* If the exact column number is not found, there will be an answer with the whole line.
163
*
164
* Sumatra-PDF, Skim, iTeXMac2 and Texworks are examples of open source software that use this library.
165
* You can browse their code for a concrete implementation.
166
*/
167
typedef long synctex_status_t;
168
synctex_status_t synctex_display_query(synctex_scanner_t scanner,const char * name,int line,int column);
169
synctex_status_t synctex_edit_query(synctex_scanner_t scanner,int page,float h,float v);
170
synctex_node_t synctex_next_result(synctex_scanner_t scanner);
171
172
/* Display all the information contained in the scanner object.
173
* If the records are too numerous, only the first ones are displayed.
174
* This is mainly for informatinal purpose to help developers.
175
*/
176
void synctex_scanner_display(synctex_scanner_t scanner);
177
178
/* The x and y offset of the origin in TeX coordinates. The magnification
179
These are used by pdf viewers that want to display the real box size.
180
For example, getting the horizontal coordinates of a node would require
181
synctex_node_box_h(node)*synctex_scanner_magnification(scanner)+synctex_scanner_x_offset(scanner)
182
Getting its TeX width would simply require
183
synctex_node_box_width(node)*synctex_scanner_magnification(scanner)
184
but direct methods are available for that below.
185
*/
186
int synctex_scanner_x_offset(synctex_scanner_t scanner);
187
int synctex_scanner_y_offset(synctex_scanner_t scanner);
188
float synctex_scanner_magnification(synctex_scanner_t scanner);
189
190
/* Managing the input file names.
191
* Given a tag, synctex_scanner_get_name will return the corresponding file name.
192
* Conversely, given a file name, synctex_scanner_get_tag will retur, the corresponding tag.
193
* The file name must be the very same as understood by TeX.
194
* For example, if you \input myDir/foo.tex, the file name is myDir/foo.tex.
195
* No automatic path expansion is performed.
196
* Finally, synctex_scanner_input is the first input node of the scanner.
197
* To browse all the input node, use a loop like
198
*
199
* if((input_node = synctex_scanner_input(scanner))){
200
* do {
201
* blah
202
* } while((input_node=synctex_node_sibling(input_node)));
203
* }
204
*
205
* The output is the name that was used to create the scanner.
206
* The synctex is the real name of the synctex file,
207
* it was obtained from output by setting the proper file extension.
208
*/
209
const char * synctex_scanner_get_name(synctex_scanner_t scanner,int tag);
210
int synctex_scanner_get_tag(synctex_scanner_t scanner,const char * name);
211
synctex_node_t synctex_scanner_input(synctex_scanner_t scanner);
212
const char * synctex_scanner_get_output(synctex_scanner_t scanner);
213
const char * synctex_scanner_get_synctex(synctex_scanner_t scanner);
214
215
/* Browsing the nodes
216
* parent, child and sibling are standard names for tree nodes.
217
* The parent is one level higher, the child is one level deeper,
218
* and the sibling is at the same level.
219
* The sheet of a node is the first ancestor, it is of type sheet.
220
* A node and its sibling have the same parent.
221
* A node is the parent of its child.
222
* A node is either the child of its parent,
223
* or belongs to the sibling chain of its parent's child.
224
* The next node is either the child, the sibling or the parent's sibling,
225
* unless the parent is a sheet.
226
* This allows to navigate through all the nodes of a given sheet node:
227
*
228
* synctex_node_t node = sheet;
229
* while((node = synctex_node_next(node))) {
230
* // do something with node
231
* }
232
*
233
* With synctex_sheet_content, you can retrieve the sheet node given the page.
234
* The page is 1 based, according to TeX standards.
235
* Conversely synctex_node_sheet allows to retrieve the sheet containing a given node.
236
*/
237
synctex_node_t synctex_node_parent(synctex_node_t node);
238
synctex_node_t synctex_node_sheet(synctex_node_t node);
239
synctex_node_t synctex_node_child(synctex_node_t node);
240
synctex_node_t synctex_node_sibling(synctex_node_t node);
241
synctex_node_t synctex_node_next(synctex_node_t node);
242
synctex_node_t synctex_sheet(synctex_scanner_t scanner,int page);
243
synctex_node_t synctex_sheet_content(synctex_scanner_t scanner,int page);
244
245
/* These are the types of the synctex nodes */
246
typedef enum {
247
synctex_node_type_error = 0,
248
synctex_node_type_input,
249
synctex_node_type_sheet,
250
synctex_node_type_vbox,
251
synctex_node_type_void_vbox,
252
synctex_node_type_hbox,
253
synctex_node_type_void_hbox,
254
synctex_node_type_kern,
255
synctex_node_type_glue,
256
synctex_node_type_math,
257
synctex_node_type_boundary,
258
synctex_node_number_of_types
259
} synctex_node_type_t;
260
261
/* synctex_node_type gives the type of a given node,
262
* synctex_node_isa gives the same information as a human readable text. */
263
synctex_node_type_t synctex_node_type(synctex_node_t node);
264
const char * synctex_node_isa(synctex_node_t node);
265
266
/* This is primarily used for debugging purpose.
267
* The second one logs information for the node and recursively displays information for its next node */
268
void synctex_node_log(synctex_node_t node);
269
void synctex_node_display(synctex_node_t node);
270
271
/* Given a node, access to the location in the synctex file where it is defined.
272
*/
273
typedef unsigned int synctex_charindex_t;
274
synctex_charindex_t synctex_node_charindex(synctex_node_t node);
275
276
/* Given a node, access to its tag, line and column.
277
* The line and column numbers are 1 based.
278
* The latter is not yet fully supported in TeX, the default implementation returns 0 which means the whole line.
279
* When the tag is known, the scanner of the node will give the corresponding file name.
280
* When the tag is known, the scanner of the node will give the name.
281
*/
282
int synctex_node_tag(synctex_node_t node);
283
int synctex_node_line(synctex_node_t node);
284
int synctex_node_column(synctex_node_t node);
285
286
/* In order to enhance forward synchronization,
287
* non void horizontal boxes have supplemental cached information.
288
* The mean line is the average of the line numbers of the included nodes.
289
* The child count is the number of chidren.
290
*/
291
int synctex_node_mean_line(synctex_node_t node);
292
int synctex_node_child_count(synctex_node_t node);
293
294
/* This is the page where the node appears.
295
* This is a 1 based index as given by TeX.
296
*/
297
int synctex_node_page(synctex_node_t node);
298
299
/* For quite all nodes, horizontal, vertical coordinates, and width.
300
* These are expressed in TeX small points coordinates, with origin at the top left corner.
301
*/
302
int synctex_node_h(synctex_node_t node);
303
int synctex_node_v(synctex_node_t node);
304
int synctex_node_width(synctex_node_t node);
305
306
/* For all nodes, dimensions of the enclosing box.
307
* These are expressed in TeX small points coordinates, with origin at the top left corner.
308
* A box is enclosing itself.
309
*/
310
int synctex_node_box_h(synctex_node_t node);
311
int synctex_node_box_v(synctex_node_t node);
312
int synctex_node_box_width(synctex_node_t node);
313
int synctex_node_box_height(synctex_node_t node);
314
int synctex_node_box_depth(synctex_node_t node);
315
316
/* For quite all nodes, horizontal, vertical coordinates, and width.
317
* The visible dimensions are bigger than real ones to compensate 0 width boxes
318
* that do contain nodes.
319
* These are expressed in page coordinates, with origin at the top left corner.
320
* A box is enclosing itself.
321
*/
322
float synctex_node_visible_h(synctex_node_t node);
323
float synctex_node_visible_v(synctex_node_t node);
324
float synctex_node_visible_width(synctex_node_t node);
325
/* For all nodes, visible dimensions of the enclosing box.
326
* A box is enclosing itself.
327
* The visible dimensions are bigger than real ones to compensate 0 width boxes
328
* that do contain nodes.
329
*/
330
float synctex_node_box_visible_h(synctex_node_t node);
331
float synctex_node_box_visible_v(synctex_node_t node);
332
float synctex_node_box_visible_width(synctex_node_t node);
333
float synctex_node_box_visible_height(synctex_node_t node);
334
float synctex_node_box_visible_depth(synctex_node_t node);
335
336
/* The main synctex updater object.
337
* This object is used to append information to the synctex file.
338
* Its implementation is considered private.
339
* It is used by the synctex command line tool to take into account modifications
340
* that could occur while postprocessing files by dvipdf like filters.
341
*/
342
typedef struct __synctex_updater_t _synctex_updater_t;
343
typedef _synctex_updater_t * synctex_updater_t;
344
345
/* Designated initializer.
346
* Once you are done with your whole job,
347
* free the updater */
348
synctex_updater_t synctex_updater_new_with_output_file(const char * output, const char * directory);
349
350
/* Use the next functions to append records to the synctex file,
351
* no consistency tests made on the arguments */
352
void synctex_updater_append_magnification(synctex_updater_t updater, char * magnification);
353
void synctex_updater_append_x_offset(synctex_updater_t updater, char * x_offset);
354
void synctex_updater_append_y_offset(synctex_updater_t updater, char * y_offset);
355
356
/* You MUST free the updater, once everything is properly appended */
357
void synctex_updater_free(synctex_updater_t updater);
58
59
/* The main synctex object is a scanner.
60
* Its implementation is considered private.
61
* The basic workflow is
62
* - create a "synctex scanner" with the contents of a file
63
* - perform actions on that scanner like
64
synctex_display_query or synctex_edit_query below.
65
* - perform actions on nodes returned by the scanner
66
* - free the scanner when the work is done
67
*/
68
typedef struct synctex_scanner_t synctex_scanner_s;
69
typedef synctex_scanner_s * synctex_scanner_p;
70
71
/**
72
* This is the designated method to create
73
* a new synctex scanner object.
74
* - argument output: the pdf/dvi/xdv file associated
75
* to the synctex file.
76
* If necessary, it can be the tex file that
77
* originated the synctex file but this might cause
78
* problems if the \jobname has a custom value.
79
* Despite this method can accept a relative path
80
* in practice, you should only pass full paths.
81
* The path should be encoded by the underlying
82
* file system, assuming that it is based on
83
* 8 bits characters, including UTF8,
84
* not 16 bits nor 32 bits.
85
* The last file extension is removed and
86
* replaced by the proper extension,
87
* either synctex or synctex.gz.
88
* - argument build_directory: It is the directory where
89
* all the auxiliary stuff is created.
90
* If no synctex file is found in the same directory
91
* as the output file, then we try to find one in
92
* this build directory.
93
* It is the directory where all the auxiliary
94
* stuff is created. Sometimes, the synctex output
95
* file and the pdf, dvi or xdv files are not
96
* created in the same location. See MikTeX.
97
* This directory path can be NULL,
98
* it will be ignored then.
99
* It can be either absolute or relative to the
100
* directory of the output pdf (dvi or xdv) file.
101
* Please note that this new argument is provided
102
* as a convenience but should not be used.
103
* Available since version 1.5.
104
* - argument parse: In general, use 1.
105
* Use 0 only if you do not want to parse the
106
* content but just check for existence.
107
* Available since version 1.5
108
* - resturn: a scanner. NULL is returned in case
109
* of an error or non existent file.
110
*/
111
synctex_scanner_p synctex_scanner_new_with_output_file(const char * output, const char * build_directory, int parse);
112
113
/**
114
* Designated method to delete a synctex scanner object,
115
* including all its internal resources.
116
* Frees all the memory, you must call it when you are finished with the scanner.
117
* - argument scanner: a scanner.
118
* - returns: an integer used for testing purposes.
119
*/
120
int synctex_scanner_free(synctex_scanner_p scanner);
121
122
/**
123
* Send this message to force the scanner to
124
* parse the contents of the synctex output file.
125
* Nothing is performed if the file was already parsed.
126
* In each query below, this message is sent,
127
* but if you need to access information more directly,
128
* you must ensure that the parsing did occur.
129
* Usage:
130
* if((my_scanner = synctex_scanner_parse(my_scanner))) {
131
* continue with my_scanner...
132
* } else {
133
* there was a problem
134
* }
135
* - returns: the argument on success.
136
* On failure, frees scanner and returns NULL.
137
*/
138
synctex_scanner_p synctex_scanner_parse(synctex_scanner_p scanner);
139
140
/* synctex_node_p is the type for all synctex nodes.
141
* Its implementation is considered private.
142
* The synctex file is parsed into a tree of nodes, either sheet, form, boxes, math nodes... */
143
144
typedef struct synctex_node_t synctex_node_s;
145
typedef synctex_node_s * synctex_node_p;
146
147
/* The main entry points.
148
* Given the file name, a line and a column number, synctex_display_query returns the number of nodes
149
* satisfying the constrain. Use code like
150
*
151
* if(synctex_display_query(scanner,name,line,column,page_hint)>0) {
152
* synctex_node_p node;
153
* while((node = synctex_scanner_next_result(scanner))) {
154
* // do something with node
155
* ...
156
* }
157
* }
158
*
159
* Please notice that since version 1.19,
160
* there is a new argument page_hint.
161
* The results in pages closer to page_hint are given first.
162
* For example, one can
163
* - highlight each resulting node in the output, using synctex_node_visible_h and synctex_node_visible_v
164
* - highlight all the rectangles enclosing those nodes, using synctex_node_box_visible_... functions
165
* - highlight just the character using that information
166
*
167
* Given the page and the position in the page, synctex_edit_query returns the number of nodes
168
* satisfying the constrain. Use code like
169
*
170
* if(synctex_edit_query(scanner,page,h,v)>0) {
171
* synctex_node_p node;
172
* while(node = synctex_scanner_next_result(scanner)) {
173
* // do something with node
174
* ...
175
* }
176
* }
177
*
178
* For example, one can
179
* - highlight each resulting line in the input,
180
* - highlight just the character using that information
181
*
182
* page is 1 based
183
* h and v are coordinates in 72 dpi unit, relative to the top left corner of the page.
184
* If you make a new query, the result of the previous one is discarded. If you need to make more than one query
185
* in parallel, use the iterator API exposed in
186
* the synctex_parser_private.h header.
187
* If one of this function returns a negative integer,
188
* it means that an error occurred.
189
*
190
* Both methods are conservative, in the sense that matching is weak.
191
* If the exact column number is not found, there will be an answer with the whole line.
192
*
193
* Sumatra-PDF, Skim, iTeXMac2, TeXShop and Texworks are examples of open source software that use this library.
194
* You can browse their code for a concrete implementation.
195
*/
196
typedef long synctex_status_t;
197
/* The page_hint argument is used to resolve ambiguities.
198
* Whenever, different matches occur, the ones closest
199
* to the page will be given first. Pass a negative number
200
* when in doubt. Using pdf forms may lead to ambiguities.
201
*/
202
synctex_status_t synctex_display_query(synctex_scanner_p scanner,const char * name,int line,int column, int page_hint);
203
synctex_status_t synctex_edit_query(synctex_scanner_p scanner,int page,float h,float v);
204
synctex_node_p synctex_scanner_next_result(synctex_scanner_p scanner);
205
synctex_status_t synctex_scanner_reset_result(synctex_scanner_p scanner);
206
207
/**
208
* The horizontal and vertical location,
209
* the width, height and depth of a box enclosing node.
210
* All dimensions are given in page coordinates
211
* as opposite to TeX coordinates.
212
* The origin is at the top left corner of the page.
213
* Code example for Qt5:
214
* (from TeXworks source TWSynchronize.cpp)
215
* QRectF nodeRect(synctex_node_box_visible_h(node),
216
* synctex_node_box_visible_v(node) -
217
* synctex_node_box_visible_height(node),
218
* synctex_node_box_visible_width(node),
219
* synctex_node_box_visible_height(node) +
220
* synctex_node_box_visible_depth(node));
221
* Code example for Cocoa:
222
* NSRect bounds = [pdfPage
223
* boundsForBox:kPDFDisplayBoxMediaBox];
224
* NSRect nodeRect = NSMakeRect(
225
* synctex_node_box_visible_h(node),
226
* NSMaxY(bounds)-synctex_node_box_visible_v(node) +
227
* synctex_node_box_visible_height(node),
228
* synctex_node_box_visible_width(node),
229
* synctex_node_box_visible_height(node) +
230
* synctex_node_box_visible_depth(node)
231
* );
232
* The visible dimensions are bigger than real ones
233
* to compensate 0 width boxes or nodes intentionally
234
* put outside the box (using \kern for example).
235
* - parameter node: a node.
236
* - returns: a float.
237
* - author: JL
238
*/
239
float synctex_node_box_visible_h(synctex_node_p node);
240
float synctex_node_box_visible_v(synctex_node_p node);
241
float synctex_node_box_visible_width(synctex_node_p node);
242
float synctex_node_box_visible_height(synctex_node_p node);
243
float synctex_node_box_visible_depth(synctex_node_p node);
244
245
/**
246
* For quite all nodes, horizontal and vertical coordinates, and width.
247
* All dimensions are given in page coordinates
248
* as opposite to TeX coordinates.
249
* The origin is at the top left corner of the page.
250
* The visible dimensions are bigger than real ones
251
* to compensate 0 width boxes or nodes intentionally
252
* put outside the box (using \kern for example).
253
* All nodes have coordinates, but all nodes don't
254
* have non null size. For example, math nodes
255
* have no width according to TeX, and in that case
256
* synctex_node_visible_width simply returns 0.
257
* The same holds for kern nodes that do not have
258
* height nor depth, etc...
259
*/
260
float synctex_node_visible_h(synctex_node_p node);
261
float synctex_node_visible_v(synctex_node_p node);
262
float synctex_node_visible_width(synctex_node_p node);
263
float synctex_node_visible_height(synctex_node_p node);
264
float synctex_node_visible_depth(synctex_node_p node);
265
266
/**
267
* Given a node, access to its tag, line and column.
268
* The line and column numbers are 1 based.
269
* The latter is not yet fully supported in TeX,
270
* the default implementation returns 0
271
* which means the whole line.
272
* synctex_node_get_name returns the path of the
273
* TeX source file that was used to create the node.
274
* When the tag is known, the scanner of the node
275
* will also give that same file name, see
276
* synctex_scanner_get_name below.
277
* For an hbox node, the mean line is the mean
278
* of all the lines of the child nodes.
279
* Sometimes, when synchronization form pdf to source
280
* fails with the line, one should try with the
281
* mean line.
282
*/
283
int synctex_node_tag(synctex_node_p node);
284
int synctex_node_line(synctex_node_p node);
285
int synctex_node_mean_line(synctex_node_p node);
286
int synctex_node_column(synctex_node_p node);
287
const char * synctex_node_get_name(synctex_node_p node);
288
289
/**
290
This is the page where the node appears.
291
* This is a 1 based index as given by TeX.
292
*/
293
int synctex_node_page(synctex_node_p node);
294
295
/**
296
* Display all the information contained in the scanner.
297
* If the records are too numerous, only the first ones are displayed.
298
* This is mainly for informational purpose to help developers.
299
*/
300
void synctex_scanner_display(synctex_scanner_p scanner);
301
302
/* Managing the input file names.
303
* Given a tag, synctex_scanner_get_name will return the corresponding file name.
304
* Conversely, given a file name, synctex_scanner_get_tag will return, the corresponding tag.
305
* The file name must be the very same as understood by TeX.
306
* For example, if you \input myDir/foo.tex, the file name is myDir/foo.tex.
307
* No automatic path expansion is performed.
308
* Finally, synctex_scanner_input is the first input node of the scanner.
309
* To browse all the input node, use a loop like
310
* ...
311
* synctex_node_p = input_node;
312
* ...
313
* if((input_node = synctex_scanner_input(scanner))) {
314
* do {
315
* blah
316
* } while((input_node=synctex_node_sibling(input_node)));
317
* }
318
*
319
* The output is the name that was used to create the scanner.
320
* The synctex is the real name of the synctex file,
321
* it was obtained from output by setting the proper file extension.
322
*/
323
const char * synctex_scanner_get_name(synctex_scanner_p scanner,int tag);
324
325
int synctex_scanner_get_tag(synctex_scanner_p scanner,const char * name);
326
327
synctex_node_p synctex_scanner_input(synctex_scanner_p scanner);
328
synctex_node_p synctex_scanner_input_with_tag(synctex_scanner_p scanner,int tag);
329
const char * synctex_scanner_get_output(synctex_scanner_p scanner);
330
const char * synctex_scanner_get_synctex(synctex_scanner_p scanner);
331
332
/* The x and y offset of the origin in TeX coordinates. The magnification
333
These are used by pdf viewers that want to display the real box size.
334
For example, getting the horizontal coordinates of a node would require
335
synctex_node_box_h(node)*synctex_scanner_magnification(scanner)+synctex_scanner_x_offset(scanner)
336
Getting its TeX width would simply require
337
synctex_node_box_width(node)*synctex_scanner_magnification(scanner)
338
but direct methods are available for that below.
339
*/
340
int synctex_scanner_x_offset(synctex_scanner_p scanner);
341
int synctex_scanner_y_offset(synctex_scanner_p scanner);
342
float synctex_scanner_magnification(synctex_scanner_p scanner);
343
344
/**
345
* ## Browsing the nodes
346
* parent, child and sibling are standard names for tree nodes.
347
* The parent is one level higher,
348
* the child is one level deeper,
349
* and the sibling is at the same level.
350
* A node and its sibling have the same parent.
351
* A node is the parent of its children.
352
* A node is either the child of its parent,
353
* or belongs to the sibling chain of its parent's child.
354
* The sheet or form of a node is the topmost ancestor,
355
* it is of type sheet or form.
356
* The next node is either the child, the sibling or the parent's sibling,
357
* unless the parent is a sheet, a form or NULL.
358
* This allows to navigate through all the nodes of a given sheet node:
359
*
360
* synctex_node_p node = sheet;
361
* while((node = synctex_node_next(node))) {
362
* // do something with node
363
* }
364
*
365
* With synctex_sheet_content and synctex_form_content,
366
* you can retrieve the sheet node given the page
367
* or form tag.
368
* The page is 1 based, according to TeX standards.
369
* Conversely synctex_node_parent_sheet or
370
* synctex_node_parent_form allows to retrieve
371
* the sheet or the form containing a given node.
372
* Notice that a node is not contained in a sheet
373
* and a form at the same time.
374
* Some nodes are not contained in either (handles).
375
*/
376
377
synctex_node_p synctex_node_parent(synctex_node_p node);
378
synctex_node_p synctex_node_parent_sheet(synctex_node_p node);
379
synctex_node_p synctex_node_parent_form(synctex_node_p node);
380
synctex_node_p synctex_node_child(synctex_node_p node);
381
synctex_node_p synctex_node_last_child(synctex_node_p node);
382
synctex_node_p synctex_node_sibling(synctex_node_p node);
383
synctex_node_p synctex_node_last_sibling(synctex_node_p node);
384
synctex_node_p synctex_node_arg_sibling(synctex_node_p node);
385
synctex_node_p synctex_node_next(synctex_node_p node);
386
387
/**
388
* Top level entry points.
389
* The scanner owns a list of sheet siblings and
390
* a list of form siblings.
391
* Sheets or forms have one child which is a box:
392
* their contents.
393
* - argument page: 1 based sheet page number.
394
* - argument tag: 1 based form tag number.
395
*/
396
synctex_node_p synctex_sheet(synctex_scanner_p scanner,int page);
397
synctex_node_p synctex_sheet_content(synctex_scanner_p scanner,int page);
398
synctex_node_p synctex_form(synctex_scanner_p scanner,int tag);
399
synctex_node_p synctex_form_content(synctex_scanner_p scanner,int tag);
400
401
/* This is primarily used for debugging purpose.
402
* The second one logs information for the node and recursively displays information for its next node */
403
void synctex_node_log(synctex_node_p node);
404
void synctex_node_display(synctex_node_p node);
405
406
/* For quite all nodes, horizontal, vertical coordinates, and width.
407
* These are expressed in TeX small points coordinates, with origin at the top left corner.
408
*/
409
int synctex_node_h(synctex_node_p node);
410
int synctex_node_v(synctex_node_p node);
411
int synctex_node_width(synctex_node_p node);
412
int synctex_node_height(synctex_node_p node);
413
int synctex_node_depth(synctex_node_p node);
414
415
/* For all nodes, dimensions of the enclosing box.
416
* These are expressed in TeX small points coordinates, with origin at the top left corner.
417
* A box is enclosing itself.
418
*/
419
int synctex_node_box_h(synctex_node_p node);
420
int synctex_node_box_v(synctex_node_p node);
421
int synctex_node_box_width(synctex_node_p node);
422
int synctex_node_box_height(synctex_node_p node);
423
int synctex_node_box_depth(synctex_node_p node);
358
424
359
425
#ifdef __cplusplus
360
426
}
Loggerhead is a web-based interface for Breezy
Version: 2.0.1