mirror of
https://github.com/michaelrsweet/pdfio.git
synced 2024-11-08 06:28:27 +01:00
Doco updates.
This commit is contained in:
Michael R Sweet
parent
a698b9c1a2
commit
b005175003
@ -105,7 +105,7 @@ Visual Studio Project
|
||||
|
||||
> Note: I haven't yet added this...
|
||||
|
||||
The Visual Studio solution ("pdfio.sln") is provided for Windows developers
|
||||
The Visual Studio solution ("pdfio.sln") is provided for Windows developers and
|
||||
generates both a static library and DLL.
|
||||
|
||||
|
||||
|
||||
111
doc/pdfio.3
111
doc/pdfio.3
@ -140,10 +140,7 @@ prefix: specifies the installation directory (default "/usr/local")
|
||||
|
||||
.SS Visual Studio Project
|
||||
.PP
|
||||
Note: I haven't yet added this...
|
||||
|
||||
.PP
|
||||
The Visual Studio solution ("pdfio.sln") is provided for Windows developers generates both a static library and DLL.
|
||||
The Visual Studio solution ("pdfio.sln") is provided for Windows developers and generates both a static library and DLL.
|
||||
.SS Xcode Project
|
||||
.PP
|
||||
There is also an Xcode project ("pdfio.xcodeproj") you can use on macOS which generates a static library that will be installed under "/usr/local" with:
|
||||
@ -173,6 +170,8 @@ In a makefile you can add the necessary compiler and linker options with:
|
||||
CFLAGS += `pkg\-config \-\-cflags pdfio`
|
||||
LIBS += `pkg\-config \-\-libs pdfio`
|
||||
.fi
|
||||
.PP
|
||||
On Windows, you need to link to the PDFIO.LIB (static) or PDFIO1.LIB (DLL) libraries and include the "zlib" NuGet package dependency.
|
||||
.SS Header Files
|
||||
.PP
|
||||
PDFio provides a primary header file that is always used:
|
||||
@ -181,7 +180,7 @@ PDFio provides a primary header file that is always used:
|
||||
#include <pdfio.h>
|
||||
.fi
|
||||
.PP
|
||||
PDFio also provides content helper functions that are defined in a separate header file:
|
||||
PDFio also provides helper functions for producing PDF content that are defined in a separate header file:
|
||||
.nf
|
||||
|
||||
#include <pdfio\-content.h>
|
||||
@ -210,10 +209,98 @@ pdfio_obj_t: An object in a PDF file
|
||||
pdfio_stream_t: An object stream
|
||||
|
||||
|
||||
.SS PDF Files
|
||||
.SS PDF Values
|
||||
.SS Reading PDF Files
|
||||
.PP
|
||||
You open an existing PDF file using the pdfioFileOpen function:
|
||||
.nf
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", error_cb, error_data);
|
||||
.fi
|
||||
.PP
|
||||
where the three arguments to the function are the filename ("myinputfile.pdf"), an optional error callback function (error_cb), and an optional pointer value for the error callback function (error_data). The error callback is called for both errors and warnings and accepts the pdfio_file_t pointer, a message string, and the callback pointer value, for example:
|
||||
.nf
|
||||
|
||||
bool
|
||||
error_cb(pdfio_file_t *pdf, const char *message, void *data)
|
||||
{
|
||||
(void)data; // This callback does not use the data pointer
|
||||
|
||||
fprintf(stderr, "%s: %s\\n", pdfioFileGetName(pdf), message);
|
||||
|
||||
// Return false to treat warnings as errors
|
||||
return (false);
|
||||
}
|
||||
.fi
|
||||
.PP
|
||||
The default error callback (NULL) does the equivalent of the above.
|
||||
.PP
|
||||
Each PDF file contains one or more pages. The pdfioFileGetNumPages function returns the number of pages in the file while the pdfioFileGetPage function gets the specified page in the PDF file:
|
||||
.nf
|
||||
|
||||
pdfio_file_t *pdf; // PDF file
|
||||
size_t i; // Looping var
|
||||
size_t count; // Number of pages
|
||||
pdfio_obj_t *page; // Current page
|
||||
|
||||
// Iterate the pages in the PDF file
|
||||
for (i = 0, count = pdfioFileGetNumPages(pdf); i < count; i ++)
|
||||
{
|
||||
page = pdfioFileGetPage(pdf, i);
|
||||
// do something with page
|
||||
}
|
||||
.fi
|
||||
.PP
|
||||
Each page is represented by a "page tree" object (what pdfioFileGetPage returns) that specifies information about the page and one or more "content" objects that contain the images, fonts, text, and graphics that appear on the page.
|
||||
.PP
|
||||
The pdfioFileClose function closes a PDF file and frees all memory that was used for it:
|
||||
.nf
|
||||
|
||||
pdfioFileClose(pdf);
|
||||
.fi
|
||||
.SS Writing PDF Files
|
||||
.PP
|
||||
You create a new PDF file using the pdfioFileCreate function:
|
||||
.nf
|
||||
|
||||
pdfio_rect_t media_box = { 0.0, 0.0, 612.0, 792.0 }; // US Letter
|
||||
pdfio_rect_t crop_box = { 36.0, 36.0, 576.0, 756.0 }; // 0.5" margins
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate("myoutputfile.pdf", "2.0", &media_box, &crop_box, error_cb, error_data);
|
||||
.fi
|
||||
.PP
|
||||
where the six arguments to the function are the filename ("myoutputfile.pdf"), PDF version ("2.0"), media box (media_box), crop box (crop_box), an optional error callback function (error_cb), and an optional pointer value for the error callback function (error_data).
|
||||
.PP
|
||||
Once the file is created, use the pdfioFileCreateObj, pdfioFileCreatePage, and pdfioPageCopy functions to create objects and pages in the file.
|
||||
.PP
|
||||
Finally, the pdfioFileClose function writes the PDF cross\-reference and "trailer" information, closes the file, and frees all memory that was used for it.
|
||||
.SS PDF Objects
|
||||
.PP
|
||||
PDF objects are identified using two numbers \- the object number (1 to N) and the object generation (0 to 65535) that specifies a particular version of an object. An object's numbers are returned by the pdfioObjGetNumber and pdfioObjGetGeneration functions. You can find a numbered object using the pdfioFileFindObj function.
|
||||
.PP
|
||||
Objects contain values (typically dictionaries) and usually an associated data stream containing images, fonts, ICC profiles, and page content. PDFio provides several accessor functions to get the value(s) associated with an object:
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioObjGetArray returns an object's array value, if any
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioObjGetDict returns an object's dictionary value, if any
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioObjGetLength returns the length of the data stream, if any
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioObjGetSubtype returns the sub\-type name of the object, for example "Image" for an image object.
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioObjGetType returns the type name of the object, for example "XObject" for an image object.
|
||||
|
||||
|
||||
.SS PDF Streams
|
||||
.SS PDF Content Helper Functions
|
||||
|
||||
.SH ENUMERATIONS
|
||||
.SS pdfio_filter_e
|
||||
@ -1718,7 +1805,7 @@ char * pdfioStringCreate (
|
||||
.fi
|
||||
.PP
|
||||
This function creates a literal string associated with the PDF file
|
||||
"pwg". The "s" string points to a nul-terminated C string.
|
||||
"pdf". The "s" string points to a nul-terminated C string.
|
||||
.PP
|
||||
\fBNULL\fR is returned on error, otherwise a \fBchar *\fR that is valid until
|
||||
\fBpdfioFileClose\fR is called.
|
||||
@ -1734,7 +1821,7 @@ char * pdfioStringCreatef (
|
||||
.fi
|
||||
.PP
|
||||
This function creates a formatted string associated with the PDF file
|
||||
"pwg". The "format" string contains \fBprintf\fR-style format characters.
|
||||
"pdf". The "format" string contains \fBprintf\fR-style format characters.
|
||||
.PP
|
||||
\fBNULL\fR is returned on error, otherwise a \fBchar *\fR that is valid until
|
||||
\fBpdfioFileClose\fR is called.
|
||||
@ -1752,12 +1839,6 @@ struct pdfio_rect_s
|
||||
};
|
||||
.fi
|
||||
.SH TYPES
|
||||
.SS pdf_value_t
|
||||
PDF value of any type
|
||||
.PP
|
||||
.nf
|
||||
typedef struct _pdfio_value_s pdf_value_t;
|
||||
.fi
|
||||
.SS pdfio_array_t
|
||||
Array of PDF values
|
||||
.PP
|
||||
|
||||
@ -261,10 +261,11 @@ span.string {
|
||||
<li><a href="#header-files">Header Files</a></li>
|
||||
</ul></li>
|
||||
<li><a href="#api-overview">API Overview</a><ul class="subcontents">
|
||||
<li><a href="#pdf-files">PDF Files</a></li>
|
||||
<li><a href="#pdf-values">PDF Values</a></li>
|
||||
<li><a href="#reading-pdf-files">Reading PDF Files</a></li>
|
||||
<li><a href="#writing-pdf-files">Writing PDF Files</a></li>
|
||||
<li><a href="#pdf-objects">PDF Objects</a></li>
|
||||
<li><a href="#pdf-streams">PDF Streams</a></li>
|
||||
<li><a href="#pdf-content-helper-functions">PDF Content Helper Functions</a></li>
|
||||
</ul></li>
|
||||
<li><a href="#FUNCTIONS">Functions</a><ul class="subcontents">
|
||||
<li><a href="#pdfioArrayAppendArray">pdfioArrayAppendArray</a></li>
|
||||
@ -413,7 +414,6 @@ span.string {
|
||||
<li><a href="#pdfioStringCreatef">pdfioStringCreatef</a></li>
|
||||
</ul></li>
|
||||
<li><a href="#TYPES">Data Types</a><ul class="subcontents">
|
||||
<li><a href="#pdf_value_t">pdf_value_t</a></li>
|
||||
<li><a href="#pdfio_array_t">pdfio_array_t</a></li>
|
||||
<li><a href="#pdfio_dict_t">pdfio_dict_t</a></li>
|
||||
<li><a href="#pdfio_error_cb_t">pdfio_error_cb_t</a></li>
|
||||
@ -509,10 +509,7 @@ make install-shared
|
||||
</li>
|
||||
</ul>
|
||||
<h3 class="title" id="visual-studio-project">Visual Studio Project</h3>
|
||||
<blockquote>
|
||||
<p>Note: I haven't yet added this...</p>
|
||||
</blockquote>
|
||||
<p>The Visual Studio solution ("pdfio.sln") is provided for Windows developers generates both a static library and DLL.</p>
|
||||
<p>The Visual Studio solution ("pdfio.sln") is provided for Windows developers and generates both a static library and DLL.</p>
|
||||
<h3 class="title" id="xcode-project">Xcode Project</h3>
|
||||
<p>There is also an Xcode project ("pdfio.xcodeproj") you can use on macOS which generates a static library that will be installed under "/usr/local" with:</p>
|
||||
<pre><code>sudo xcodebuild install
|
||||
@ -530,11 +527,12 @@ fi
|
||||
<pre><code class="language-make">CFLAGS += `pkg-config --cflags pdfio`
|
||||
LIBS += `pkg-config --libs pdfio`
|
||||
</code></pre>
|
||||
<p>On Windows, you need to link to the <code>PDFIO.LIB</code> (static) or <code>PDFIO1.LIB</code> (DLL) libraries and include the "zlib" NuGet package dependency.</p>
|
||||
<h3 class="title" id="header-files">Header Files</h3>
|
||||
<p>PDFio provides a primary header file that is always used:</p>
|
||||
<pre><code class="language-c"><span class="directive">#include <pdfio.h></span>
|
||||
</code></pre>
|
||||
<p>PDFio also provides content helper functions that are defined in a separate header file:</p>
|
||||
<p>PDFio also provides helper functions for producing PDF content that are defined in a separate header file:</p>
|
||||
<pre><code class="language-c"><span class="directive">#include <pdfio-content.h></span>
|
||||
</code></pre>
|
||||
<h2 class="title" id="api-overview">API Overview</h2>
|
||||
@ -551,10 +549,67 @@ LIBS += `pkg-config --libs pdfio`
|
||||
<li><p><code>pdfio_stream_t</code>: An object stream</p>
|
||||
</li>
|
||||
</ul>
|
||||
<h3 class="title" id="pdf-files">PDF Files</h3>
|
||||
<h3 class="title" id="pdf-values">PDF Values</h3>
|
||||
<h3 class="title" id="reading-pdf-files">Reading PDF Files</h3>
|
||||
<p>You open an existing PDF file using the <code>pdfioFileOpen</code> function:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileOpen(<span class="string">"myinputfile.pdf"</span>, error_cb, error_data);
|
||||
</code></pre>
|
||||
<p>where the three arguments to the function are the filename ("myinputfile.pdf"), an optional error callback function (<code>error_cb</code>), and an optional pointer value for the error callback function (<code>error_data</code>). The error callback is called for both errors and warnings and accepts the <code>pdfio_file_t</code> pointer, a message string, and the callback pointer value, for example:</p>
|
||||
<pre><code class="language-c"><span class="reserved">bool</span>
|
||||
error_cb(pdfio_file_t *pdf, <span class="reserved">const</span> <span class="reserved">char</span> *message, <span class="reserved">void</span> *data)
|
||||
{
|
||||
(<span class="reserved">void</span>)data; <span class="comment">// This callback does not use the data pointer</span>
|
||||
|
||||
fprintf(stderr, <span class="string">"%s: %s\n"</span>, pdfioFileGetName(pdf), message);
|
||||
|
||||
<span class="comment">// Return false to treat warnings as errors</span>
|
||||
<span class="reserved">return</span> (<span class="reserved">false</span>);
|
||||
}
|
||||
</code></pre>
|
||||
<p>The default error callback (<code>NULL</code>) does the equivalent of the above.</p>
|
||||
<p>Each PDF file contains one or more pages. The <code>pdfioFileGetNumPages</code> function returns the number of pages in the file while the <code>pdfioFileGetPage</code> function gets the specified page in the PDF file:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf; <span class="comment">// PDF file</span>
|
||||
size_t i; <span class="comment">// Looping var</span>
|
||||
size_t count; <span class="comment">// Number of pages</span>
|
||||
pdfio_obj_t *page; <span class="comment">// Current page</span>
|
||||
|
||||
<span class="comment">// Iterate the pages in the PDF file</span>
|
||||
<span class="reserved">for</span> (i = <span class="number">0</span>, count = pdfioFileGetNumPages(pdf); i < count; i ++)
|
||||
{
|
||||
page = pdfioFileGetPage(pdf, i);
|
||||
<span class="comment">// do something with page</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>Each page is represented by a "page tree" object (what <code>pdfioFileGetPage</code> returns) that specifies information about the page and one or more "content" objects that contain the images, fonts, text, and graphics that appear on the page.</p>
|
||||
<p>The <code>pdfioFileClose</code> function closes a PDF file and frees all memory that was used for it:</p>
|
||||
<pre><code class="language-c">pdfioFileClose(pdf);
|
||||
</code></pre>
|
||||
<h3 class="title" id="writing-pdf-files">Writing PDF Files</h3>
|
||||
<p>You create a new PDF file using the <code>pdfioFileCreate</code> function:</p>
|
||||
<pre><code class="language-c">pdfio_rect_t media_box = { <span class="number">0.0</span>, <span class="number">0.0</span>, <span class="number">612.0</span>, <span class="number">792.0</span> }; <span class="comment">// US Letter</span>
|
||||
pdfio_rect_t crop_box = { <span class="number">36.0</span>, <span class="number">36.0</span>, <span class="number">576.0</span>, <span class="number">756.0</span> }; <span class="comment">// 0.5" margins</span>
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate(<span class="string">"myoutputfile.pdf"</span>, <span class="string">"2.0"</span>, &media_box, &crop_box, error_cb, error_data);
|
||||
</code></pre>
|
||||
<p>where the six arguments to the function are the filename ("myoutputfile.pdf"), PDF version ("2.0"), media box (<code>media_box</code>), crop box (<code>crop_box</code>), an optional error callback function (<code>error_cb</code>), and an optional pointer value for the error callback function (<code>error_data</code>).</p>
|
||||
<p>Once the file is created, use the <code>pdfioFileCreateObj</code>, <code>pdfioFileCreatePage</code>, and <code>pdfioPageCopy</code> functions to create objects and pages in the file.</p>
|
||||
<p>Finally, the <code>pdfioFileClose</code> function writes the PDF cross-reference and "trailer" information, closes the file, and frees all memory that was used for it.</p>
|
||||
<h3 class="title" id="pdf-objects">PDF Objects</h3>
|
||||
<p>PDF objects are identified using two numbers - the object number (1 to N) and the object generation (0 to 65535) that specifies a particular version of an object. An object's numbers are returned by the <code>pdfioObjGetNumber</code> and <code>pdfioObjGetGeneration</code> functions. You can find a numbered object using the <code>pdfioFileFindObj</code> function.</p>
|
||||
<p>Objects contain values (typically dictionaries) and usually an associated data stream containing images, fonts, ICC profiles, and page content. PDFio provides several accessor functions to get the value(s) associated with an object:</p>
|
||||
<ul>
|
||||
<li><p><code>pdfioObjGetArray</code> returns an object's array value, if any</p>
|
||||
</li>
|
||||
<li><p><code>pdfioObjGetDict</code> returns an object's dictionary value, if any</p>
|
||||
</li>
|
||||
<li><p><code>pdfioObjGetLength</code> returns the length of the data stream, if any</p>
|
||||
</li>
|
||||
<li><p><code>pdfioObjGetSubtype</code> returns the sub-type name of the object, for example "Image" for an image object.</p>
|
||||
</li>
|
||||
<li><p><code>pdfioObjGetType</code> returns the type name of the object, for example "XObject" for an image object.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<h3 class="title" id="pdf-streams">PDF Streams</h3>
|
||||
<h3 class="title" id="pdf-content-helper-functions">PDF Content Helper Functions</h3>
|
||||
<h2 class="title"><a id="FUNCTIONS">Functions</a></h2>
|
||||
<h3 class="function"><a id="pdfioArrayAppendArray">pdfioArrayAppendArray</a></h3>
|
||||
<p class="description">Add an array value to an array.</p>
|
||||
@ -2597,7 +2652,7 @@ char *pdfioStringCreate(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf, const cha
|
||||
<p class="description">Durable string pointer or <code>NULL</code> on error</p>
|
||||
<h4 class="discussion">Discussion</h4>
|
||||
<p class="discussion">This function creates a literal string associated with the PDF file
|
||||
"pwg". The "s" string points to a nul-terminated C string.<br>
|
||||
"pdf". The "s" string points to a nul-terminated C string.<br>
|
||||
<br>
|
||||
<code>NULL</code> is returned on error, otherwise a <code>char *</code> that is valid until
|
||||
<code>pdfioFileClose</code> is called.</p>
|
||||
@ -2618,16 +2673,11 @@ char *pdfioStringCreatef(<a href="#pdfio_file_t">pdfio_file_t</a> *pdf, const ch
|
||||
<p class="description">Durable string pointer or <code>NULL</code> on error</p>
|
||||
<h4 class="discussion">Discussion</h4>
|
||||
<p class="discussion">This function creates a formatted string associated with the PDF file
|
||||
"pwg". The "format" string contains <code>printf</code>-style format characters.<br>
|
||||
"pdf". The "format" string contains <code>printf</code>-style format characters.<br>
|
||||
<br>
|
||||
<code>NULL</code> is returned on error, otherwise a <code>char *</code> that is valid until
|
||||
<code>pdfioFileClose</code> is called.</p>
|
||||
<h2 class="title"><a id="TYPES">Data Types</a></h2>
|
||||
<h3 class="typedef"><a id="pdf_value_t">pdf_value_t</a></h3>
|
||||
<p class="description">PDF value of any type</p>
|
||||
<p class="code">
|
||||
typedef struct _pdfio_value_s pdf_value_t;
|
||||
</p>
|
||||
<h3 class="typedef"><a id="pdfio_array_t">pdfio_array_t</a></h3>
|
||||
<p class="description">Array of PDF values</p>
|
||||
<p class="code">
|
||||
|
||||
119
doc/pdfio.md
119
doc/pdfio.md
@ -89,9 +89,7 @@ command or as environment variables:
|
||||
Visual Studio Project
|
||||
---------------------
|
||||
|
||||
> Note: I haven't yet added this...
|
||||
|
||||
The Visual Studio solution ("pdfio.sln") is provided for Windows developers
|
||||
The Visual Studio solution ("pdfio.sln") is provided for Windows developers and
|
||||
generates both a static library and DLL.
|
||||
|
||||
|
||||
@ -124,6 +122,9 @@ CFLAGS += `pkg-config --cflags pdfio`
|
||||
LIBS += `pkg-config --libs pdfio`
|
||||
```
|
||||
|
||||
On Windows, you need to link to the `PDFIO.LIB` (static) or `PDFIO1.LIB` (DLL)
|
||||
libraries and include the "zlib" NuGet package dependency.
|
||||
|
||||
|
||||
Header Files
|
||||
------------
|
||||
@ -134,8 +135,8 @@ PDFio provides a primary header file that is always used:
|
||||
#include <pdfio.h>
|
||||
```
|
||||
|
||||
PDFio also provides content helper functions that are defined in a separate
|
||||
header file:
|
||||
PDFio also provides helper functions for producing PDF content that are defined
|
||||
in a separate header file:
|
||||
|
||||
```c
|
||||
#include <pdfio-content.h>
|
||||
@ -154,17 +155,117 @@ PDFio exposes several types:
|
||||
- `pdfio_stream_t`: An object stream
|
||||
|
||||
|
||||
PDF Files
|
||||
---------
|
||||
Reading PDF Files
|
||||
-----------------
|
||||
|
||||
You open an existing PDF file using the `pdfioFileOpen` function:
|
||||
|
||||
PDF Values
|
||||
----------
|
||||
```c
|
||||
pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", error_cb, error_data);
|
||||
|
||||
```
|
||||
|
||||
where the three arguments to the function are the filename ("myinputfile.pdf"),
|
||||
an optional error callback function (`error_cb`), and an optional pointer value
|
||||
for the error callback function (`error_data`). The error callback is called
|
||||
for both errors and warnings and accepts the `pdfio_file_t` pointer, a message
|
||||
string, and the callback pointer value, for example:
|
||||
|
||||
```c
|
||||
bool
|
||||
error_cb(pdfio_file_t *pdf, const char *message, void *data)
|
||||
{
|
||||
(void)data; // This callback does not use the data pointer
|
||||
|
||||
fprintf(stderr, "%s: %s\n", pdfioFileGetName(pdf), message);
|
||||
|
||||
// Return false to treat warnings as errors
|
||||
return (false);
|
||||
}
|
||||
```
|
||||
|
||||
The default error callback (`NULL`) does the equivalent of the above.
|
||||
|
||||
Each PDF file contains one or more pages. The `pdfioFileGetNumPages` function
|
||||
returns the number of pages in the file while the `pdfioFileGetPage` function
|
||||
gets the specified page in the PDF file:
|
||||
|
||||
```c
|
||||
pdfio_file_t *pdf; // PDF file
|
||||
size_t i; // Looping var
|
||||
size_t count; // Number of pages
|
||||
pdfio_obj_t *page; // Current page
|
||||
|
||||
// Iterate the pages in the PDF file
|
||||
for (i = 0, count = pdfioFileGetNumPages(pdf); i < count; i ++)
|
||||
{
|
||||
page = pdfioFileGetPage(pdf, i);
|
||||
// do something with page
|
||||
}
|
||||
```
|
||||
|
||||
Each page is represented by a "page tree" object (what `pdfioFileGetPage`
|
||||
returns) that specifies information about the page and one or more "content"
|
||||
objects that contain the images, fonts, text, and graphics that appear on the
|
||||
page.
|
||||
|
||||
The `pdfioFileClose` function closes a PDF file and frees all memory that was
|
||||
used for it:
|
||||
|
||||
```c
|
||||
pdfioFileClose(pdf);
|
||||
```
|
||||
|
||||
Writing PDF Files
|
||||
-----------------
|
||||
|
||||
You create a new PDF file using the `pdfioFileCreate` function:
|
||||
|
||||
```c
|
||||
pdfio_rect_t media_box = { 0.0, 0.0, 612.0, 792.0 }; // US Letter
|
||||
pdfio_rect_t crop_box = { 36.0, 36.0, 576.0, 756.0 }; // 0.5" margins
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate("myoutputfile.pdf", "2.0", &media_box, &crop_box, error_cb, error_data);
|
||||
```
|
||||
|
||||
where the six arguments to the function are the filename ("myoutputfile.pdf"),
|
||||
PDF version ("2.0"), media box (`media_box`), crop box (`crop_box`), an optional
|
||||
error callback function (`error_cb`), and an optional pointer value for the
|
||||
error callback function (`error_data`).
|
||||
|
||||
Once the file is created, use the `pdfioFileCreateObj`, `pdfioFileCreatePage`,
|
||||
and `pdfioPageCopy` functions to create objects and pages in the file.
|
||||
|
||||
Finally, the `pdfioFileClose` function writes the PDF cross-reference and
|
||||
"trailer" information, closes the file, and frees all memory that was used for
|
||||
it.
|
||||
|
||||
|
||||
PDF Objects
|
||||
-----------
|
||||
|
||||
PDF objects are identified using two numbers - the object number (1 to N) and
|
||||
the object generation (0 to 65535) that specifies a particular version of an
|
||||
object. An object's numbers are returned by the `pdfioObjGetNumber` and
|
||||
`pdfioObjGetGeneration` functions. You can find a numbered object using the
|
||||
`pdfioFileFindObj` function.
|
||||
|
||||
Objects contain values (typically dictionaries) and usually an associated data
|
||||
stream containing images, fonts, ICC profiles, and page content. PDFio provides several accessor functions to get the value(s) associated with an object:
|
||||
|
||||
- `pdfioObjGetArray` returns an object's array value, if any
|
||||
- `pdfioObjGetDict` returns an object's dictionary value, if any
|
||||
- `pdfioObjGetLength` returns the length of the data stream, if any
|
||||
- `pdfioObjGetSubtype` returns the sub-type name of the object, for example
|
||||
"Image" for an image object.
|
||||
- `pdfioObjGetType` returns the type name of the object, for example "XObject"
|
||||
for an image object.
|
||||
|
||||
|
||||
PDF Streams
|
||||
-----------
|
||||
|
||||
|
||||
PDF Content Helper Functions
|
||||
----------------------------
|
||||
|
||||
|
||||
@ -25,7 +25,7 @@ static int compare_strings(char **a, char **b);
|
||||
// 'pdfioStringCreate()' - Create a durable literal string.
|
||||
//
|
||||
// This function creates a literal string associated with the PDF file
|
||||
// "pwg". The "s" string points to a nul-terminated C string.
|
||||
// "pdf". The "s" string points to a nul-terminated C string.
|
||||
//
|
||||
// `NULL` is returned on error, otherwise a `char *` that is valid until
|
||||
// `pdfioFileClose` is called.
|
||||
@ -85,7 +85,7 @@ pdfioStringCreate(
|
||||
// 'pdfioStringCreatef()' - Create a durable formatted string.
|
||||
//
|
||||
// This function creates a formatted string associated with the PDF file
|
||||
// "pwg". The "format" string contains `printf`-style format characters.
|
||||
// "pdf". The "format" string contains `printf`-style format characters.
|
||||
//
|
||||
// `NULL` is returned on error, otherwise a `char *` that is valid until
|
||||
// `pdfioFileClose` is called.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user