diff options
Diffstat (limited to 'cut-n-paste/synctex/synctex_parser.h')
| -rw-r--r-- | cut-n-paste/synctex/synctex_parser.h | 762 |
1 files changed, 414 insertions, 348 deletions
diff --git a/cut-n-paste/synctex/synctex_parser.h b/cut-n-paste/synctex/synctex_parser.h index fd74bd3d..e54a0176 100644 --- a/cut-n-paste/synctex/synctex_parser.h +++ b/cut-n-paste/synctex/synctex_parser.h @@ -1,360 +1,426 @@ /* -Copyright (c) 2008, 2009, 2010 , 2011 jerome DOT laurens AT u-bourgogne DOT fr - -This file is part of the SyncTeX package. - -Latest Revision: Tue Jun 14 08:23:30 UTC 2011 - -Version: 1.18 - -See synctex_parser_readme.txt for more details - -License: --------- -Permission is hereby granted, free of charge, to any person -obtaining a copy of this software and associated documentation -files (the "Software"), to deal in the Software without -restriction, including without limitation the rights to use, -copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the -Software is furnished to do so, subject to the following -conditions: - -The above copyright notice and this permission notice shall be -included in all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES -OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND -NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT -HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, -WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING -FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE - -Except as contained in this notice, the name of the copyright holder -shall not be used in advertising or otherwise to promote the sale, -use or other dealings in this Software without prior written -authorization from the copyright holder. - -Acknowledgments: ----------------- -The author received useful remarks from the pdfTeX developers, especially Hahn The Thanh, -and significant help from XeTeX developer Jonathan Kew - -Nota Bene: ----------- -If you include or use a significant part of the synctex package into a software, -I would appreciate to be listed as contributor and see "SyncTeX" highlighted. - -Version 1 -Thu Jun 19 09:39:21 UTC 2008 - + Copyright (c) 2008-2017 jerome DOT laurens AT u-bourgogne DOT fr + + This file is part of the __SyncTeX__ package. + + [//]: # (Latest Revision: Fri Jul 14 16:20:41 UTC 2017) + [//]: # (Version: 1.21) + + See `synctex_parser_readme.md` for more details + + ## License + + Permission is hereby granted, free of charge, to any person + obtaining a copy of this software and associated documentation + files (the "Software"), to deal in the Software without + restriction, including without limitation the rights to use, + copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following + conditions: + + The above copyright notice and this permission notice shall be + included in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES + OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT + HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, + WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING + FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR + OTHER DEALINGS IN THE SOFTWARE + + Except as contained in this notice, the name of the copyright holder + shall not be used in advertising or otherwise to promote the sale, + use or other dealings in this Software without prior written + authorization from the copyright holder. + + ## Acknowledgments: + + The author received useful remarks from the __pdfTeX__ developers, especially Hahn The Thanh, + and significant help from __XeTeX__ developer Jonathan Kew. + + ## Nota Bene: + + If you include or use a significant part of the __SyncTeX__ package into a software, + I would appreciate to be listed as contributor and see "__SyncTeX__" highlighted. */ #ifndef __SYNCTEX_PARSER__ # define __SYNCTEX_PARSER__ +#include "synctex_version.h" + #ifdef __cplusplus extern "C" { #endif - -# define SYNCTEX_VERSION_STRING "1.18" - -/* synctex_node_t is the type for all synctex nodes. - * The synctex file is parsed into a tree of nodes, either sheet, boxes, math nodes... */ -typedef struct _synctex_node * synctex_node_t; - -/* The main synctex object is a scanner - * Its implementation is considered private. - * The basic workflow is - * - create a "synctex scanner" with the contents of a file - * - perform actions on that scanner like display or edit queries - * - free the scanner when the work is done - */ -typedef struct __synctex_scanner_t _synctex_scanner_t; -typedef _synctex_scanner_t * synctex_scanner_t; - -/* This is the designated method to create a new synctex scanner object. - * output is the pdf/dvi/xdv file associated to the synctex file. - * If necessary, it can be the tex file that originated the synctex file - * but this might cause problems if the \jobname has a custom value. - * Despite this method can accept a relative path in practice, - * you should only pass a full path name. - * The path should be encoded by the underlying file system, - * assuming that it is based on 8 bits characters, including UTF8, - * not 16 bits nor 32 bits. - * The last file extension is removed and replaced by the proper extension. - * Then the private method _synctex_scanner_new_with_contents_of_file is called. - * NULL is returned in case of an error or non existent file. - * Once you have a scanner, use the synctex_display_query and synctex_edit_query below. - * The new "build_directory" argument is available since version 1.5. - * It is the directory where all the auxiliary stuff is created. - * Sometimes, the synctex output file and the pdf, dvi or xdv files are not created in the same directory. - * This is the case in MikTeX (I will include this into TeX Live). - * This directory path can be nil, it will be ignored then. - * It can be either absolute or relative to the directory of the output pdf (dvi or xdv) file. - * If no synctex file is found in the same directory as the output file, then we try to find one in the build directory. - * Please note that this new "build_directory" is provided as a convenient argument but should not be used. - * In fact, this is implempented as a work around of a bug in MikTeX where the synctex file does not follow the pdf file. - * The new "parse" argument is available since version 1.5. In general, use 1. - * Use 0 only if you do not want to parse the content but just check the existence. - */ -synctex_scanner_t synctex_scanner_new_with_output_file(const char * output, const char * build_directory, int parse); - -/* This is the designated method to delete a synctex scanner object. - * Frees all the memory, you must call it when you are finished with the scanner. - */ -void synctex_scanner_free(synctex_scanner_t scanner); - -/* Send this message to force the scanner to parse the contents of the synctex output file. - * Nothing is performed if the file was already parsed. - * In each query below, this message is sent, but if you need to access information more directly, - * you must be sure that the parsing did occur. - * Usage: - * if((my_scanner = synctex_scanner_parse(my_scanner))) { - * continue with my_scanner... - * } else { - * there was a problem - * } - */ -synctex_scanner_t synctex_scanner_parse(synctex_scanner_t scanner); - -/* The main entry points. - * Given the file name, a line and a column number, synctex_display_query returns the number of nodes - * satisfying the contrain. Use code like - * - * if(synctex_display_query(scanner,name,line,column)>0) { - * synctex_node_t node; - * while((node = synctex_next_result(scanner))) { - * // do something with node - * ... - * } - * } - * - * For example, one can - * - highlight each resulting node in the output, using synctex_node_h and synctex_node_v - * - highlight all the rectangles enclosing those nodes, using synctex_box_... functions - * - highlight just the character using that information - * - * Given the page and the position in the page, synctex_edit_query returns the number of nodes - * satisfying the contrain. Use code like - * - * if(synctex_edit_query(scanner,page,h,v)>0) { - * synctex_node_t node; - * while(node = synctex_next_result(scanner)) { - * // do something with node - * ... - * } - * } - * - * For example, one can - * - highlight each resulting line in the input, - * - highlight just the character using that information - * - * page is 1 based - * h and v are coordinates in 72 dpi unit, relative to the top left corner of the page. - * If you make a new query, the result of the previous one is discarded. - * If one of this function returns a non positive integer, - * it means that an error occurred. - * - * Both methods are conservative, in the sense that matching is weak. - * If the exact column number is not found, there will be an answer with the whole line. - * - * Sumatra-PDF, Skim, iTeXMac2 and Texworks are examples of open source software that use this library. - * You can browse their code for a concrete implementation. - */ -typedef long synctex_status_t; -synctex_status_t synctex_display_query(synctex_scanner_t scanner,const char * name,int line,int column); -synctex_status_t synctex_edit_query(synctex_scanner_t scanner,int page,float h,float v); -synctex_node_t synctex_next_result(synctex_scanner_t scanner); - -/* Display all the information contained in the scanner object. - * If the records are too numerous, only the first ones are displayed. - * This is mainly for informatinal purpose to help developers. - */ -void synctex_scanner_display(synctex_scanner_t scanner); - -/* The x and y offset of the origin in TeX coordinates. The magnification - These are used by pdf viewers that want to display the real box size. - For example, getting the horizontal coordinates of a node would require - synctex_node_box_h(node)*synctex_scanner_magnification(scanner)+synctex_scanner_x_offset(scanner) - Getting its TeX width would simply require - synctex_node_box_width(node)*synctex_scanner_magnification(scanner) - but direct methods are available for that below. - */ -int synctex_scanner_x_offset(synctex_scanner_t scanner); -int synctex_scanner_y_offset(synctex_scanner_t scanner); -float synctex_scanner_magnification(synctex_scanner_t scanner); - -/* Managing the input file names. - * Given a tag, synctex_scanner_get_name will return the corresponding file name. - * Conversely, given a file name, synctex_scanner_get_tag will retur, the corresponding tag. - * The file name must be the very same as understood by TeX. - * For example, if you \input myDir/foo.tex, the file name is myDir/foo.tex. - * No automatic path expansion is performed. - * Finally, synctex_scanner_input is the first input node of the scanner. - * To browse all the input node, use a loop like - * - * if((input_node = synctex_scanner_input(scanner))){ - * do { - * blah - * } while((input_node=synctex_node_sibling(input_node))); - * } - * - * The output is the name that was used to create the scanner. - * The synctex is the real name of the synctex file, - * it was obtained from output by setting the proper file extension. - */ -const char * synctex_scanner_get_name(synctex_scanner_t scanner,int tag); -int synctex_scanner_get_tag(synctex_scanner_t scanner,const char * name); -synctex_node_t synctex_scanner_input(synctex_scanner_t scanner); -const char * synctex_scanner_get_output(synctex_scanner_t scanner); -const char * synctex_scanner_get_synctex(synctex_scanner_t scanner); - -/* Browsing the nodes - * parent, child and sibling are standard names for tree nodes. - * The parent is one level higher, the child is one level deeper, - * and the sibling is at the same level. - * The sheet of a node is the first ancestor, it is of type sheet. - * A node and its sibling have the same parent. - * A node is the parent of its child. - * A node is either the child of its parent, - * or belongs to the sibling chain of its parent's child. - * The next node is either the child, the sibling or the parent's sibling, - * unless the parent is a sheet. - * This allows to navigate through all the nodes of a given sheet node: - * - * synctex_node_t node = sheet; - * while((node = synctex_node_next(node))) { - * // do something with node - * } - * - * With synctex_sheet_content, you can retrieve the sheet node given the page. - * The page is 1 based, according to TeX standards. - * Conversely synctex_node_sheet allows to retrieve the sheet containing a given node. - */ -synctex_node_t synctex_node_parent(synctex_node_t node); -synctex_node_t synctex_node_sheet(synctex_node_t node); -synctex_node_t synctex_node_child(synctex_node_t node); -synctex_node_t synctex_node_sibling(synctex_node_t node); -synctex_node_t synctex_node_next(synctex_node_t node); -synctex_node_t synctex_sheet(synctex_scanner_t scanner,int page); -synctex_node_t synctex_sheet_content(synctex_scanner_t scanner,int page); - -/* These are the types of the synctex nodes */ -typedef enum { - synctex_node_type_error = 0, - synctex_node_type_input, - synctex_node_type_sheet, - synctex_node_type_vbox, - synctex_node_type_void_vbox, - synctex_node_type_hbox, - synctex_node_type_void_hbox, - synctex_node_type_kern, - synctex_node_type_glue, - synctex_node_type_math, - synctex_node_type_boundary, - synctex_node_number_of_types -} synctex_node_type_t; - -/* synctex_node_type gives the type of a given node, - * synctex_node_isa gives the same information as a human readable text. */ -synctex_node_type_t synctex_node_type(synctex_node_t node); -const char * synctex_node_isa(synctex_node_t node); - -/* This is primarily used for debugging purpose. - * The second one logs information for the node and recursively displays information for its next node */ -void synctex_node_log(synctex_node_t node); -void synctex_node_display(synctex_node_t node); - -/* Given a node, access to the location in the synctex file where it is defined. - */ -typedef unsigned int synctex_charindex_t; -synctex_charindex_t synctex_node_charindex(synctex_node_t node); - -/* Given a node, access to its tag, line and column. - * The line and column numbers are 1 based. - * The latter is not yet fully supported in TeX, the default implementation returns 0 which means the whole line. - * When the tag is known, the scanner of the node will give the corresponding file name. - * When the tag is known, the scanner of the node will give the name. - */ -int synctex_node_tag(synctex_node_t node); -int synctex_node_line(synctex_node_t node); -int synctex_node_column(synctex_node_t node); - -/* In order to enhance forward synchronization, - * non void horizontal boxes have supplemental cached information. - * The mean line is the average of the line numbers of the included nodes. - * The child count is the number of chidren. - */ -int synctex_node_mean_line(synctex_node_t node); -int synctex_node_child_count(synctex_node_t node); - -/* This is the page where the node appears. - * This is a 1 based index as given by TeX. - */ -int synctex_node_page(synctex_node_t node); - -/* For quite all nodes, horizontal, vertical coordinates, and width. - * These are expressed in TeX small points coordinates, with origin at the top left corner. - */ -int synctex_node_h(synctex_node_t node); -int synctex_node_v(synctex_node_t node); -int synctex_node_width(synctex_node_t node); - -/* For all nodes, dimensions of the enclosing box. - * These are expressed in TeX small points coordinates, with origin at the top left corner. - * A box is enclosing itself. - */ -int synctex_node_box_h(synctex_node_t node); -int synctex_node_box_v(synctex_node_t node); -int synctex_node_box_width(synctex_node_t node); -int synctex_node_box_height(synctex_node_t node); -int synctex_node_box_depth(synctex_node_t node); - -/* For quite all nodes, horizontal, vertical coordinates, and width. - * The visible dimensions are bigger than real ones to compensate 0 width boxes - * that do contain nodes. - * These are expressed in page coordinates, with origin at the top left corner. - * A box is enclosing itself. - */ -float synctex_node_visible_h(synctex_node_t node); -float synctex_node_visible_v(synctex_node_t node); -float synctex_node_visible_width(synctex_node_t node); -/* For all nodes, visible dimensions of the enclosing box. - * A box is enclosing itself. - * The visible dimensions are bigger than real ones to compensate 0 width boxes - * that do contain nodes. - */ -float synctex_node_box_visible_h(synctex_node_t node); -float synctex_node_box_visible_v(synctex_node_t node); -float synctex_node_box_visible_width(synctex_node_t node); -float synctex_node_box_visible_height(synctex_node_t node); -float synctex_node_box_visible_depth(synctex_node_t node); - -/* The main synctex updater object. - * This object is used to append information to the synctex file. - * Its implementation is considered private. - * It is used by the synctex command line tool to take into account modifications - * that could occur while postprocessing files by dvipdf like filters. - */ -typedef struct __synctex_updater_t _synctex_updater_t; -typedef _synctex_updater_t * synctex_updater_t; - -/* Designated initializer. - * Once you are done with your whole job, - * free the updater */ -synctex_updater_t synctex_updater_new_with_output_file(const char * output, const char * directory); - -/* Use the next functions to append records to the synctex file, - * no consistency tests made on the arguments */ -void synctex_updater_append_magnification(synctex_updater_t updater, char * magnification); -void synctex_updater_append_x_offset(synctex_updater_t updater, char * x_offset); -void synctex_updater_append_y_offset(synctex_updater_t updater, char * y_offset); - -/* You MUST free the updater, once everything is properly appended */ -void synctex_updater_free(synctex_updater_t updater); + + /* The main synctex object is a scanner. + * Its implementation is considered private. + * The basic workflow is + * - create a "synctex scanner" with the contents of a file + * - perform actions on that scanner like + synctex_display_query or synctex_edit_query below. + * - perform actions on nodes returned by the scanner + * - free the scanner when the work is done + */ + typedef struct synctex_scanner_t synctex_scanner_s; + typedef synctex_scanner_s * synctex_scanner_p; + + /** + * This is the designated method to create + * a new synctex scanner object. + * - argument output: the pdf/dvi/xdv file associated + * to the synctex file. + * If necessary, it can be the tex file that + * originated the synctex file but this might cause + * problems if the \jobname has a custom value. + * Despite this method can accept a relative path + * in practice, you should only pass full paths. + * The path should be encoded by the underlying + * file system, assuming that it is based on + * 8 bits characters, including UTF8, + * not 16 bits nor 32 bits. + * The last file extension is removed and + * replaced by the proper extension, + * either synctex or synctex.gz. + * - argument build_directory: It is the directory where + * all the auxiliary stuff is created. + * If no synctex file is found in the same directory + * as the output file, then we try to find one in + * this build directory. + * It is the directory where all the auxiliary + * stuff is created. Sometimes, the synctex output + * file and the pdf, dvi or xdv files are not + * created in the same location. See MikTeX. + * This directory path can be NULL, + * it will be ignored then. + * It can be either absolute or relative to the + * directory of the output pdf (dvi or xdv) file. + * Please note that this new argument is provided + * as a convenience but should not be used. + * Available since version 1.5. + * - argument parse: In general, use 1. + * Use 0 only if you do not want to parse the + * content but just check for existence. + * Available since version 1.5 + * - resturn: a scanner. NULL is returned in case + * of an error or non existent file. + */ + synctex_scanner_p synctex_scanner_new_with_output_file(const char * output, const char * build_directory, int parse); + + /** + * Designated method to delete a synctex scanner object, + * including all its internal resources. + * Frees all the memory, you must call it when you are finished with the scanner. + * - argument scanner: a scanner. + * - returns: an integer used for testing purposes. + */ + int synctex_scanner_free(synctex_scanner_p scanner); + + /** + * Send this message to force the scanner to + * parse the contents of the synctex output file. + * Nothing is performed if the file was already parsed. + * In each query below, this message is sent, + * but if you need to access information more directly, + * you must ensure that the parsing did occur. + * Usage: + * if((my_scanner = synctex_scanner_parse(my_scanner))) { + * continue with my_scanner... + * } else { + * there was a problem + * } + * - returns: the argument on success. + * On failure, frees scanner and returns NULL. + */ + synctex_scanner_p synctex_scanner_parse(synctex_scanner_p scanner); + + /* synctex_node_p is the type for all synctex nodes. + * Its implementation is considered private. + * The synctex file is parsed into a tree of nodes, either sheet, form, boxes, math nodes... */ + + typedef struct synctex_node_t synctex_node_s; + typedef synctex_node_s * synctex_node_p; + + /* The main entry points. + * Given the file name, a line and a column number, synctex_display_query returns the number of nodes + * satisfying the contrain. Use code like + * + * if(synctex_display_query(scanner,name,line,column,page_hint)>0) { + * synctex_node_p node; + * while((node = synctex_scanner_next_result(scanner))) { + * // do something with node + * ... + * } + * } + * + * Please notice that since version 1.19, + * there is a new argument page_hint. + * The results in pages closer to page_hint are given first. + * For example, one can + * - highlight each resulting node in the output, using synctex_node_visible_h and synctex_node_visible_v + * - highlight all the rectangles enclosing those nodes, using synctex_node_box_visible_... functions + * - highlight just the character using that information + * + * Given the page and the position in the page, synctex_edit_query returns the number of nodes + * satisfying the contrain. Use code like + * + * if(synctex_edit_query(scanner,page,h,v)>0) { + * synctex_node_p node; + * while(node = synctex_scanner_next_result(scanner)) { + * // do something with node + * ... + * } + * } + * + * For example, one can + * - highlight each resulting line in the input, + * - highlight just the character using that information + * + * page is 1 based + * h and v are coordinates in 72 dpi unit, relative to the top left corner of the page. + * If you make a new query, the result of the previous one is discarded. If you need to make more than one query + * in parallel, use the iterator API exposed in + * the synctex_parser_private.h header. + * If one of this function returns a negative integer, + * it means that an error occurred. + * + * Both methods are conservative, in the sense that matching is weak. + * If the exact column number is not found, there will be an answer with the whole line. + * + * Sumatra-PDF, Skim, iTeXMac2, TeXShop and Texworks are examples of open source software that use this library. + * You can browse their code for a concrete implementation. + */ + typedef long synctex_status_t; + /* The page_hint argument is used to resolve ambiguities. + * Whenever, different matches occur, the ones closest + * to the page will be given first. Pass a negative number + * when in doubt. Using pdf forms may lead to ambiguities. + */ + synctex_status_t synctex_display_query(synctex_scanner_p scanner,const char * name,int line,int column, int page_hint); + synctex_status_t synctex_edit_query(synctex_scanner_p scanner,int page,float h,float v); + synctex_node_p synctex_scanner_next_result(synctex_scanner_p scanner); + synctex_status_t synctex_scanner_reset_result(synctex_scanner_p scanner); + + /** + * The horizontal and vertical location, + * the width, height and depth of a box enclosing node. + * All dimensions are given in page coordinates + * as opposite to TeX coordinates. + * The origin is at the top left corner of the page. + * Code example for Qt5: + * (from TeXworks source TWSynchronize.cpp) + * QRectF nodeRect(synctex_node_box_visible_h(node), + * synctex_node_box_visible_v(node) - + * synctex_node_box_visible_height(node), + * synctex_node_box_visible_width(node), + * synctex_node_box_visible_height(node) + + * synctex_node_box_visible_depth(node)); + * Code example for Cocoa: + * NSRect bounds = [pdfPage + * boundsForBox:kPDFDisplayBoxMediaBox]; + * NSRect nodeRect = NSMakeRect( + * synctex_node_box_visible_h(node), + * NSMaxY(bounds)-synctex_node_box_visible_v(node) + + * synctex_node_box_visible_height(node), + * synctex_node_box_visible_width(node), + * synctex_node_box_visible_height(node) + + * synctex_node_box_visible_depth(node) + * ); + * The visible dimensions are bigger than real ones + * to compensate 0 width boxes or nodes intentionnaly + * put outside the box (using \kern for example). + * - parameter node: a node. + * - returns: a float. + * - author: JL + */ + float synctex_node_box_visible_h(synctex_node_p node); + float synctex_node_box_visible_v(synctex_node_p node); + float synctex_node_box_visible_width(synctex_node_p node); + float synctex_node_box_visible_height(synctex_node_p node); + float synctex_node_box_visible_depth(synctex_node_p node); + + /** + * For quite all nodes, horizontal and vertical coordinates, and width. + * All dimensions are given in page coordinates + * as opposite to TeX coordinates. + * The origin is at the top left corner of the page. + * The visible dimensions are bigger than real ones + * to compensate 0 width boxes or nodes intentionnaly + * put outside the box (using \kern for example). + * All nodes have coordinates, but all nodes don't + * have non null size. For example, math nodes + * have no width according to TeX, and in that case + * synctex_node_visible_width simply returns 0. + * The same holds for kern nodes that do not have + * height nor depth, etc... + */ + float synctex_node_visible_h(synctex_node_p node); + float synctex_node_visible_v(synctex_node_p node); + float synctex_node_visible_width(synctex_node_p node); + float synctex_node_visible_height(synctex_node_p node); + float synctex_node_visible_depth(synctex_node_p node); + + /** + * Given a node, access to its tag, line and column. + * The line and column numbers are 1 based. + * The latter is not yet fully supported in TeX, + * the default implementation returns 0 + * which means the whole line. + * synctex_node_get_name returns the path of the + * TeX source file that was used to create the node. + * When the tag is known, the scanner of the node + * will also give that same file name, see + * synctex_scanner_get_name below. + * For an hbox node, the mean line is the mean + * of all the lines of the child nodes. + * Sometimes, when synchronization form pdf to source + * fails with the line, one should try with the + * mean line. + */ + int synctex_node_tag(synctex_node_p node); + int synctex_node_line(synctex_node_p node); + int synctex_node_mean_line(synctex_node_p node); + int synctex_node_column(synctex_node_p node); + const char * synctex_node_get_name(synctex_node_p node); + + /** + This is the page where the node appears. + * This is a 1 based index as given by TeX. + */ + int synctex_node_page(synctex_node_p node); + + /** + * Display all the information contained in the scanner. + * If the records are too numerous, only the first ones are displayed. + * This is mainly for informational purpose to help developers. + */ + void synctex_scanner_display(synctex_scanner_p scanner); + + /* Managing the input file names. + * Given a tag, synctex_scanner_get_name will return the corresponding file name. + * Conversely, given a file name, synctex_scanner_get_tag will return, the corresponding tag. + * The file name must be the very same as understood by TeX. + * For example, if you \input myDir/foo.tex, the file name is myDir/foo.tex. + * No automatic path expansion is performed. + * Finally, synctex_scanner_input is the first input node of the scanner. + * To browse all the input node, use a loop like + * ... + * synctex_node_p = input_node; + * ... + * if((input_node = synctex_scanner_input(scanner))) { + * do { + * blah + * } while((input_node=synctex_node_sibling(input_node))); + * } + * + * The output is the name that was used to create the scanner. + * The synctex is the real name of the synctex file, + * it was obtained from output by setting the proper file extension. + */ + const char * synctex_scanner_get_name(synctex_scanner_p scanner,int tag); + + int synctex_scanner_get_tag(synctex_scanner_p scanner,const char * name); + + synctex_node_p synctex_scanner_input(synctex_scanner_p scanner); + synctex_node_p synctex_scanner_input_with_tag(synctex_scanner_p scanner,int tag); + const char * synctex_scanner_get_output(synctex_scanner_p scanner); + const char * synctex_scanner_get_synctex(synctex_scanner_p scanner); + + /* The x and y offset of the origin in TeX coordinates. The magnification + These are used by pdf viewers that want to display the real box size. + For example, getting the horizontal coordinates of a node would require + synctex_node_box_h(node)*synctex_scanner_magnification(scanner)+synctex_scanner_x_offset(scanner) + Getting its TeX width would simply require + synctex_node_box_width(node)*synctex_scanner_magnification(scanner) + but direct methods are available for that below. + */ + int synctex_scanner_x_offset(synctex_scanner_p scanner); + int synctex_scanner_y_offset(synctex_scanner_p scanner); + float synctex_scanner_magnification(synctex_scanner_p scanner); + + /** + * ## Browsing the nodes + * parent, child and sibling are standard names for tree nodes. + * The parent is one level higher, + * the child is one level deeper, + * and the sibling is at the same level. + * A node and its sibling have the same parent. + * A node is the parent of its children. + * A node is either the child of its parent, + * or belongs to the sibling chain of its parent's child. + * The sheet or form of a node is the topmost ancestor, + * it is of type sheet or form. + * The next node is either the child, the sibling or the parent's sibling, + * unless the parent is a sheet, a form or NULL. + * This allows to navigate through all the nodes of a given sheet node: + * + * synctex_node_p node = sheet; + * while((node = synctex_node_next(node))) { + * // do something with node + * } + * + * With synctex_sheet_content and synctex_form_content, + * you can retrieve the sheet node given the page + * or form tag. + * The page is 1 based, according to TeX standards. + * Conversely synctex_node_parent_sheet or + * synctex_node_parent_form allows to retrieve + * the sheet or the form containing a given node. + * Notice that a node is not contained in a sheet + * and a form at the same time. + * Some nodes are not contained in either (handles). + */ + + synctex_node_p synctex_node_parent(synctex_node_p node); + synctex_node_p synctex_node_parent_sheet(synctex_node_p node); + synctex_node_p synctex_node_parent_form(synctex_node_p node); + synctex_node_p synctex_node_child(synctex_node_p node); + synctex_node_p synctex_node_last_child(synctex_node_p node); + synctex_node_p synctex_node_sibling(synctex_node_p node); + synctex_node_p synctex_node_last_sibling(synctex_node_p node); + synctex_node_p synctex_node_arg_sibling(synctex_node_p node); + synctex_node_p synctex_node_next(synctex_node_p node); + + /** + * Top level entry points. + * The scanner owns a list of sheet siblings and + * a list of form siblings. + * Sheets or forms have one child which is a box: + * theie contents. + * - argument page: 1 based sheet page number. + * - argument tag: 1 based form tag number. + */ + synctex_node_p synctex_sheet(synctex_scanner_p scanner,int page); + synctex_node_p synctex_sheet_content(synctex_scanner_p scanner,int page); + synctex_node_p synctex_form(synctex_scanner_p scanner,int tag); + synctex_node_p synctex_form_content(synctex_scanner_p scanner,int tag); + + /* This is primarily used for debugging purpose. + * The second one logs information for the node and recursively displays information for its next node */ + void synctex_node_log(synctex_node_p node); + void synctex_node_display(synctex_node_p node); + + /* For quite all nodes, horizontal, vertical coordinates, and width. + * These are expressed in TeX small points coordinates, with origin at the top left corner. + */ + int synctex_node_h(synctex_node_p node); + int synctex_node_v(synctex_node_p node); + int synctex_node_width(synctex_node_p node); + int synctex_node_height(synctex_node_p node); + int synctex_node_depth(synctex_node_p node); + + /* For all nodes, dimensions of the enclosing box. + * These are expressed in TeX small points coordinates, with origin at the top left corner. + * A box is enclosing itself. + */ + int synctex_node_box_h(synctex_node_p node); + int synctex_node_box_v(synctex_node_p node); + int synctex_node_box_width(synctex_node_p node); + int synctex_node_box_height(synctex_node_p node); + int synctex_node_box_depth(synctex_node_p node); #ifdef __cplusplus } |