home *** CD-ROM | disk | FTP | other *** search
/ PC World 2002 February / PCWorld_2002-02_cd.bin / Software / Vyzkuste / pdflib / pdflib-4.0.1.sit / pdflib-4.0.1 / doc / compatibility.txt < prev    next >
Encoding:
Text File  |  2001-07-04  |  9.8 KB  |  360 lines  |  [TEXT/ttxt]
  1. API changes
  2. ===========
  3.  
  4. This file documents those API changes which affect
  5. existing PDFlib client programs. Although we go to
  6. some efforts in maintaining the existing API functions,
  7. it is sometimes necessary to incorporate a few non-backward
  8. compatible changes in order to streamline the API and
  9. incorporate new or extended functions.
  10.  
  11.  
  12. PDFlib 4.0
  13. ==========
  14.  
  15. - The following functions have been added to the PDFlib API:
  16.  
  17.   PDF_open_pdi()
  18.   PDF_close_pdi()
  19.   PDF_open_pdi_page()
  20.   PDF_close_pdi_page()
  21.   PDF_get_pdi_parameter()
  22.   PDF_get_pdi_value()
  23.  
  24.   PDF_begin_pattern()
  25.   PDF_end_pattern()
  26.  
  27.   PDF_begin_template()
  28.   PDF_end_template()
  29.  
  30.   PDF_setcolor()
  31.   PDF_makespotcolor()
  32.  
  33.   PDF_arcn()
  34.   PDF_add_thumbnail()
  35.  
  36.   PDF_initgraphics()
  37.   PDF_setmatrix()
  38.  
  39. - The following functions are now deprecated (use PDF_setcolor() instead):
  40.     PDF_setgray_fill
  41.     PDF_setgray_stroke
  42.     PDF_setgray
  43.     PDF_setrgbcolor_fill
  44.     PDF_setrgbcolor_stroke
  45.     PDF_setrgbcolor
  46.  
  47. - PDF_endpath() has been re-implemented with slightly different semantics.
  48.  
  49. - The FontTT resource category has been removed. TrueType fonts can now be
  50.   listed along with PostScript fonts in the FontOutline category. This
  51.   change affects only a few customers who had access to the TrueType
  52.   feature before PDFlib 4.0 was released.
  53.  
  54.  
  55. PDFlib 3.03
  56. ===========
  57.  
  58. - This release doesn't add nor remove any function, but introduces a
  59.   new parameter: "fontwarning"
  60.  
  61. - The deprecated function PDF_endpath() raises a non-fatal exception
  62.   (which can be suppressed).
  63.  
  64.  
  65. PDFlib 3.02
  66. ===========
  67.  
  68. This release doesn't add nor remove any function. However, since PDFlib 3.01
  69. removed some obsolete and undocumented functions, 3.02 can be considered
  70. incompatible to 3.0. For this reason, the libtool version number has
  71. been increased such that PDFlib 3.02 is not binary compatible, although
  72. for users of the documented PDFlib 3.0 API it is completely backward
  73. compatible.
  74.  
  75.  
  76. Changes in PDFlib 3.01
  77. ======================
  78.  
  79. This is a maintenance release which is binary compatible with 3.0.
  80. However, a few bug fixes may result in different behaviour when
  81. compared to 3.0. These are not incompatibilities, rather 3.0 behaved
  82. in the wrong way which is now fixed. See the change log for details.
  83.  
  84. - The following functions, which were no longer supported nor documented in
  85.   PDFlib 3.0 (but were still available), have been removed from all language
  86.   bindings which still included them. Use the appropriate substitute functions
  87.   as outlined below:
  88.  
  89.   PDF_open_TIFF      use PDF_open_image_file(p, "tiff", filename, "", 0) instead
  90.   PDF_open_JPEG      use PDF_open_image_file(p, "jpeg", filename, "", 0) instead
  91.   PDF_open_GIF      use PDF_open_image_file(p, "gif", filename, "", 0) instead
  92.  
  93.   PDF_get_font        use PDF_get_value(p, "font", 0) instead
  94.   PDF_get_fontsize    use PDF_get_value(p, "fontsize", 0) instead
  95.   PDF_get_fontname    use PDF_get_parameter(p, "fontname", 0) instead
  96.   PDF_get_image_height    use PDF_get_value(p, "imageheight", image) instead
  97.   PDF_get_image_width    use PDF_get_value(p, "imagewidth", image) instead
  98.  
  99.   PDF_set_fillrule    use PDF_set_parameter(p, "fillrule", fillrule) instead
  100.   PDF_set_leading    use PDF_set_value(p, "leading", leading) instead
  101.   PDF_set_text_rise    use PDF_set_value(p, "textrise", rise) instead
  102.   PDF_set_horiz_scaling    use PDF_set_value(p, "horizscaling", scale) instead
  103.   PDF_set_text_rendering use PDF_set_value(p, "textrendering", mode) instead
  104.   PDF_set_char_spacing    use PDF_set_value(p, "charspacing", spacing) instead
  105.   PDF_set_word_spacing    use PDF_set_value(p, "wordspacing", spacing) instead
  106.   PDF_set_duration    use PDF_set_value(p, "duration", t) instead
  107.   PDF_set_transition    use PDF_set_value(p, "duration", t) instead
  108.  
  109.  
  110. API changes for PDFlib 3.0
  111. ==========================
  112.  
  113. - PDF_set_text_matrix() is no longer supported. Use PDF_scale(),
  114.   PDF_translate(), PDF_rotate(), and PDF_skew() instead, or PDF_concat()
  115.   if you actually have to deal with matrices.
  116.  
  117. - PDF_findfont() no longer returns -1 on error, but raises an exception
  118.   which seems more appropriate to font misconfigurations (or spelling
  119.   errors in the font or encoding names). Although existing code need
  120.   not necessarily be changed (assuming an error handler is already in
  121.   place), the following change is suggested:
  122.   Change
  123.     font = PDF_findfont(p, fontname, encoding, embed);
  124.     if (font == -1) {
  125.     ...
  126.     }
  127.  
  128.     -- to --
  129.  
  130.     font = PDF_findfont(p, fontname, encoding, embed);
  131.  
  132. - The name of the pseudo encoding for the platform character set changed:
  133.   Change
  134.     PDF_findfont(p, fontname, "default", embed);
  135.     -- to --
  136.     PDF_findfont(p, fontname, "host", embed);
  137.  
  138. - The image functions have been consolidated into a single API function; use
  139.   PDF_open_image_file() instead of PDF_open_*():
  140.   Change
  141.     PDF_open_GIF(p, filename)
  142.     -- to --
  143.     PDF_open_image_file(p, "gif", filename, "", 0)
  144.  
  145.     PDF_open_TIFF(p, filename)
  146.     -- to --
  147.     PDF_open_image_file(p, "tiff", filename, "", 0)
  148.  
  149.     PDF_open_JPEG(p, filename)
  150.     -- to --
  151.     PDF_open_image_file(p, "jpeg", filename, "", 0)
  152.  
  153.   The old image functions are still available, though.
  154.  
  155.  
  156. Java binding:
  157.  
  158. - In the course of reworking the Java API all functions marked as obsolete
  159.   in the manual have been removed. Use the appropriate substitutes instead:
  160.  
  161.   open_TIFF
  162.   open_JPEG
  163.   open_GIF
  164.  
  165.   get_font
  166.   get_fontsize
  167.   get_fontname
  168.   get_image_height
  169.   get_image_width
  170.  
  171.   set_fillrule
  172.   set_leading
  173.   set_text_rise
  174.   set_horiz_scaling
  175.   set_text_rendering
  176.   set_char_spacing
  177.   set_word_spacing
  178.   set_duration
  179.   set_transition
  180.  
  181. - Implements package support. Add the following line at the beginning of
  182.   all PDFlib client programs:
  183.  
  184.   import com.PDFlib.pdflib;
  185.  
  186. - Switch to an object-oriented approach, and dropped the PDF_ prefix
  187.   from all method names: Change
  188.  
  189.   long p;
  190.   int font;
  191.   p = pdflib.PDF_new();
  192.   if (pdflib.PDF_open_file(p, "hello_java.pdf") == -1) {
  193.  
  194.   -- to --
  195.  
  196.   pdflib p;
  197.   p = new pdflib();
  198.   if (p.open_file("hello_java.pdf") == -1) {
  199.  
  200. - PDF_boot() and PDF_shutdown are no longer available, but shouldn't
  201.   have been used anyway.
  202.  
  203.  
  204. Perl binding:
  205.  
  206. - The name of the shared library changed, requiring a small change in scripts:
  207.   Change
  208.     use pdflib 2.10
  209.     -- to --
  210.     use pdflib_pl 2.10
  211.  
  212. - "package pdflib" is no longer necessary at the beginning of the Perl script.
  213.  
  214. - PDF_boot() and PDF_shutdown are no longer available, but shouldn't
  215.   have been used anyway.
  216.  
  217.  
  218. Python binding:
  219.  
  220. - The name of the shared library changed, requiring a small change in scripts:
  221.   Change
  222.     from pdflib import *
  223.     -- to --
  224.     from pdflib_py import *
  225.  
  226. - PDF_boot() and PDF_shutdown are no longer available, but shouldn't
  227.   have been used anyway.
  228.  
  229.  
  230. Tcl binding:
  231.  
  232. - PDF_boot() and PDF_shutdown are no longer available, but shouldn't
  233.   have been used anyway.
  234.  
  235.  
  236. Visual Basic binding:
  237.  
  238. - There is no longer a dedicated VB binding; it is replaced by the
  239.   much more versatile ActiveX binding. This requires VB clients to
  240.   adapt their syntax to the ActiveX component.
  241.  
  242.  
  243. API changes in PDFlib V2.01
  244. ===========================
  245. - PDF_place_inline_image() is no longer supported; use PDF_place_image()
  246.   instead (same interface):
  247.   Change
  248.     PDF_place_inline_image()
  249.     -- to --
  250.     PDF_place_image()
  251.  
  252. - PDF_put_image() is no longer required. Instead, the image data is
  253.   "parked" immediately on PDF_open_*():
  254.   Delete
  255.     PDF_put_image()
  256.  
  257. - PDF_execute_image() is no longer required. Instead, PDF_place_image()
  258.   can be called multiple times for a given PDF:
  259.   Change
  260.     PDF_execute_image()
  261.     -- to --
  262.     PDF_place_image()
  263.  
  264. - The interface and functionality of PDF_open_memory_image() changed:
  265.   Change
  266.     int PDF_open_memory_image(PDF *p, unsigned char *buffer,
  267.         int width, int height, int components, int bpc);
  268.     -- to --
  269.     int PDF_open_image(PDF *p, "raw", "memory", const char *data, long len,
  270.         int width, int height, int components, int bpc, NULL);
  271.  
  272.  
  273. API changes in PDFlib V2.0
  274. ==========================
  275.  
  276. - All API functions with parameters of type "char *" changed to "const char *".
  277.  
  278. - change
  279.     PDF_data_source_from_buf()
  280.     -- to --
  281.     int PDF_open_memory_image(PDF *p, unsigned char *buffer,
  282.         int width, int height, int components, int bpc)
  283. - change
  284.     PDF_set_text_matrix(PDF *p, PDF_matrix m);
  285.     -- to --
  286.     void PDF_set_text_matrix(PDF *p,
  287.         float a, float b, float c, float d, float e, float f);
  288.  
  289. - change
  290.     PDF_add_outline(p, text);
  291.     -- to --
  292.     PDF_add_bookmark(p, text, -1, 0);
  293.  
  294. - change
  295.     PDF_info *PDF_get_info(void);
  296.     -- to --
  297.     PDF_set_info(PDF *p, char *key, char *value);
  298.     (after PDF_new() and PDF_open_*())
  299.  
  300. - change
  301.     PDF_image->width and PDF_image->height
  302.     -- to --
  303.     PDF_get_image_width(PDF *p, PDF_image *image)
  304.     -- and --
  305.     PDF_get_image_height(PDF *p, PDF_image *image);
  306.  
  307. - change
  308.     PDF_info->error_handler = handler;
  309.     -- to --
  310.     PDF_new2(handler, ...);
  311.     Watch out for the changed signature of the error handler.
  312.  
  313. - change
  314.     void PDF_data_source_from_buf(*p, *src, buffer, len);
  315.     -- to --
  316.     PDF_image *PDF_open_memory_image(p, buffer, width, height, components, bpc);
  317.     void PDF_close_image(p, image);
  318.  
  319. - change
  320.     a4.width to a4_width etc.
  321.  
  322. - change
  323.     PDF_image image; /* for PDF_open_[GIF|JPEG|TIFF|memory_image] */
  324.     -- to --
  325.     int image;
  326.  
  327. - change
  328.     PDF_close_[GIF|JPEG|TIFF|memory_image];
  329.     -- to --
  330.     PDF_close_image();
  331.  
  332. - change
  333.     PDF_transition(p, type);
  334.     -- to --
  335.     PDF_transition(p, "type");
  336.  
  337. - change
  338.     PDF_set_font(p, fontname, size, encoding);
  339.     -- to  --
  340.     int PDF_findfont(p, fontname, encoding, embed);
  341.     if (font == -1)
  342.     /* handle unavailable font */
  343.     PDF_setfont(p, font, size);
  344.  
  345.     Note: the old PDF_set_font() is still available for compatibility.
  346.  
  347. - change
  348.     PDF_stringwidth(char *text);
  349.     -- to --
  350.     PDF_stringwidth(text, PDF_get_font(p), PDF_get_fontsize(p));
  351.  
  352. - change
  353.     PDF_open(filename);
  354.     -- to --
  355.     p = PDF_new();
  356.     if (PDF_open_file(filename) == -1) { ... }
  357.     -- or --
  358.     p = PDF_new();
  359.     if (PDF_open_fp(fp) == -1) { ... }
  360.