diff options
Diffstat (limited to 'doc/public/xml/cairo-ps.xml')
-rw-r--r-- | doc/public/xml/cairo-ps.xml | 533 |
1 files changed, 533 insertions, 0 deletions
diff --git a/doc/public/xml/cairo-ps.xml b/doc/public/xml/cairo-ps.xml new file mode 100644 index 000000000..11565810f --- /dev/null +++ b/doc/public/xml/cairo-ps.xml @@ -0,0 +1,533 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ +<!ENTITY version SYSTEM "version.xml"> +]> +<refentry id="cairo-PostScript-Surfaces"> +<refmeta> +<refentrytitle role="top_of_page" id="cairo-PostScript-Surfaces.top_of_page">PostScript Surfaces</refentrytitle> +<manvolnum>3</manvolnum> +<refmiscinfo> + CAIRO Library +</refmiscinfo> +</refmeta> +<refnamediv> +<refname>PostScript Surfaces</refname> +<refpurpose>Rendering PostScript documents</refpurpose> +</refnamediv> + +<refsect1 id="cairo-PostScript-Surfaces.functions" role="functions_proto"> +<title role="functions_proto.title">Functions</title> +<informaltable pgwide="1" frame="none"> +<tgroup cols="2"> +<colspec colname="functions_return" colwidth="150px"/> +<colspec colname="functions_name"/> +<tbody> +<row><entry role="function_type"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * +</entry><entry role="function_name"><link linkend="cairo-ps-surface-create">cairo_ps_surface_create</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * +</entry><entry role="function_name"><link linkend="cairo-ps-surface-create-for-stream">cairo_ps_surface_create_for_stream</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link> +</entry><entry role="function_name"><link linkend="cairo-ps-surface-restrict-to-level">cairo_ps_surface_restrict_to_level</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link> +</entry><entry role="function_name"><link linkend="cairo-ps-get-levels">cairo_ps_get_levels</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type">const <link linkend="char"><returnvalue>char</returnvalue></link> * +</entry><entry role="function_name"><link linkend="cairo-ps-level-to-string">cairo_ps_level_to_string</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link> +</entry><entry role="function_name"><link linkend="cairo-ps-surface-set-eps">cairo_ps_surface_set_eps</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="cairo-bool-t"><returnvalue>cairo_bool_t</returnvalue></link> +</entry><entry role="function_name"><link linkend="cairo-ps-surface-get-eps">cairo_ps_surface_get_eps</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link> +</entry><entry role="function_name"><link linkend="cairo-ps-surface-set-size">cairo_ps_surface_set_size</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link> +</entry><entry role="function_name"><link linkend="cairo-ps-surface-dsc-begin-setup">cairo_ps_surface_dsc_begin_setup</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link> +</entry><entry role="function_name"><link linkend="cairo-ps-surface-dsc-begin-page-setup">cairo_ps_surface_dsc_begin_page_setup</link> <phrase role="c_punctuation">()</phrase></entry></row> +<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link> +</entry><entry role="function_name"><link linkend="cairo-ps-surface-dsc-comment">cairo_ps_surface_dsc_comment</link> <phrase role="c_punctuation">()</phrase></entry></row> + +</tbody> +</tgroup> +</informaltable> +</refsect1> +<refsect1 id="cairo-PostScript-Surfaces.other" role="other_proto"> +<title role="other_proto.title">Types and Values</title> +<informaltable role="enum_members_table" pgwide="1" frame="none"> +<tgroup cols="2"> +<colspec colname="name" colwidth="150px"/> +<colspec colname="description"/> +<tbody> +<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="CAIRO-HAS-PS-SURFACE:CAPS">CAIRO_HAS_PS_SURFACE</link></entry></row> +<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="cairo-ps-level-t">cairo_ps_level_t</link></entry></row> + +</tbody> +</tgroup> +</informaltable> +</refsect1> +<refsect1 id="cairo-PostScript-Surfaces.object-hierarchy" role="object_hierarchy"> +<title role="object_hierarchy.title">Object Hierarchy</title> +<screen> +</screen> +</refsect1> + + +<refsect1 id="cairo-PostScript-Surfaces.description" role="desc"> +<title role="desc.title">Description</title> +<para>The PostScript surface is used to render cairo graphics to Adobe +PostScript files and is a multi-page vector surface backend.</para> + +</refsect1> +<refsect1 id="cairo-PostScript-Surfaces.functions_details" role="details"> +<title role="details.title">Functions</title> +<refsect2 id="cairo-ps-surface-create" role="function" condition="since:1.2"> +<title>cairo_ps_surface_create ()</title> +<indexterm zone="cairo-ps-surface-create" role="1.2"><primary sortas="ps_surface_create">cairo_ps_surface_create</primary></indexterm> +<programlisting language="C"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * +cairo_ps_surface_create (<parameter>const <link linkend="char"><type>char</type></link> *filename</parameter>, + <parameter><link linkend="double"><type>double</type></link> width_in_points</parameter>, + <parameter><link linkend="double"><type>double</type></link> height_in_points</parameter>);</programlisting> +<para>Creates a PostScript surface of the specified size in points to be +written to <parameter>filename</parameter> +. See <link linkend="cairo-ps-surface-create-for-stream"><function>cairo_ps_surface_create_for_stream()</function></link> for +a more flexible mechanism for handling the PostScript output than +simply writing it to a named file.</para> +<para>Note that the size of individual pages of the PostScript output can +vary. See <link linkend="cairo-ps-surface-set-size"><function>cairo_ps_surface_set_size()</function></link>.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>filename</para></entry> +<entry role="parameter_description"><para>a filename for the PS output (must be writable), <link linkend="NULL:CAPS"><literal>NULL</literal></link> may be +used to specify no output. This will generate a PS surface that +may be queried and used as a source, without generating a +temporary file.</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>width_in_points</para></entry> +<entry role="parameter_description"><para>width of the surface, in points (1 point == 1/72.0 inch)</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>height_in_points</para></entry> +<entry role="parameter_description"><para>height of the surface, in points (1 point == 1/72.0 inch)</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><refsect3 role="returns"> +<title>Returns</title> +<para> a pointer to the newly created surface. The caller +owns the surface and should call <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> when done +with it.</para> +<para>This function always returns a valid pointer, but it will return a +pointer to a "nil" surface if an error such as out of memory +occurs. You can use <link linkend="cairo-surface-status"><function>cairo_surface_status()</function></link> to check for this.</para> +<para></para> +</refsect3><para role="since">Since 1.2</para></refsect2> +<refsect2 id="cairo-ps-surface-create-for-stream" role="function" condition="since:1.2"> +<title>cairo_ps_surface_create_for_stream ()</title> +<indexterm zone="cairo-ps-surface-create-for-stream" role="1.2"><primary sortas="ps_surface_create_for_stream">cairo_ps_surface_create_for_stream</primary></indexterm> +<programlisting language="C"><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> * +cairo_ps_surface_create_for_stream (<parameter><link linkend="cairo-write-func-t"><type>cairo_write_func_t</type></link> write_func</parameter>, + <parameter><link linkend="void"><type>void</type></link> *closure</parameter>, + <parameter><link linkend="double"><type>double</type></link> width_in_points</parameter>, + <parameter><link linkend="double"><type>double</type></link> height_in_points</parameter>);</programlisting> +<para>Creates a PostScript surface of the specified size in points to be +written incrementally to the stream represented by <parameter>write_func</parameter> + and +<parameter>closure</parameter> +. See <link linkend="cairo-ps-surface-create"><function>cairo_ps_surface_create()</function></link> for a more convenient way +to simply direct the PostScript output to a named file.</para> +<para>Note that the size of individual pages of the PostScript +output can vary. See <link linkend="cairo-ps-surface-set-size"><function>cairo_ps_surface_set_size()</function></link>.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>write_func</para></entry> +<entry role="parameter_description"><para>a <link linkend="cairo-write-func-t"><type>cairo_write_func_t</type></link> to accept the output data, may be <link linkend="NULL:CAPS"><literal>NULL</literal></link> +to indicate a no-op <parameter>write_func</parameter> +. With a no-op <parameter>write_func</parameter> +, +the surface may be queried or used as a source without +generating any temporary files.</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>closure</para></entry> +<entry role="parameter_description"><para>the closure argument for <parameter>write_func</parameter> +</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>width_in_points</para></entry> +<entry role="parameter_description"><para>width of the surface, in points (1 point == 1/72.0 inch)</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>height_in_points</para></entry> +<entry role="parameter_description"><para>height of the surface, in points (1 point == 1/72.0 inch)</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><refsect3 role="returns"> +<title>Returns</title> +<para> a pointer to the newly created surface. The caller +owns the surface and should call <link linkend="cairo-surface-destroy"><function>cairo_surface_destroy()</function></link> when done +with it.</para> +<para>This function always returns a valid pointer, but it will return a +pointer to a "nil" surface if an error such as out of memory +occurs. You can use <link linkend="cairo-surface-status"><function>cairo_surface_status()</function></link> to check for this.</para> +<para></para> +</refsect3><para role="since">Since 1.2</para></refsect2> +<refsect2 id="cairo-ps-surface-restrict-to-level" role="function" condition="since:1.6"> +<title>cairo_ps_surface_restrict_to_level ()</title> +<indexterm zone="cairo-ps-surface-restrict-to-level" role="1.6"><primary sortas="ps_surface_restrict_to_level">cairo_ps_surface_restrict_to_level</primary></indexterm> +<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> +cairo_ps_surface_restrict_to_level (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, + <parameter><link linkend="cairo-ps-level-t"><type>cairo_ps_level_t</type></link> level</parameter>);</programlisting> +<para>Restricts the generated PostSript file to <parameter>level</parameter> +. See +<link linkend="cairo-ps-get-levels"><function>cairo_ps_get_levels()</function></link> for a list of available level values that +can be used here.</para> +<para>This function should only be called before any drawing operations +have been performed on the given surface. The simplest way to do +this is to call this function immediately after creating the +surface.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>surface</para></entry> +<entry role="parameter_description"><para>a PostScript <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>level</para></entry> +<entry role="parameter_description"><para>PostScript level</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><para role="since">Since 1.6</para></refsect2> +<refsect2 id="cairo-ps-get-levels" role="function" condition="since:1.6"> +<title>cairo_ps_get_levels ()</title> +<indexterm zone="cairo-ps-get-levels" role="1.6"><primary sortas="ps_get_levels">cairo_ps_get_levels</primary></indexterm> +<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> +cairo_ps_get_levels (<parameter><link linkend="cairo-ps-level-t"><type>cairo_ps_level_t</type></link> const **levels</parameter>, + <parameter><link linkend="int"><type>int</type></link> *num_levels</parameter>);</programlisting> +<para>Used to retrieve the list of supported levels. See +<link linkend="cairo-ps-surface-restrict-to-level"><function>cairo_ps_surface_restrict_to_level()</function></link>.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>levels</para></entry> +<entry role="parameter_description"><para>supported level list</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>num_levels</para></entry> +<entry role="parameter_description"><para>list length</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><para role="since">Since 1.6</para></refsect2> +<refsect2 id="cairo-ps-level-to-string" role="function" condition="since:1.6"> +<title>cairo_ps_level_to_string ()</title> +<indexterm zone="cairo-ps-level-to-string" role="1.6"><primary sortas="ps_level_to_string">cairo_ps_level_to_string</primary></indexterm> +<programlisting language="C">const <link linkend="char"><returnvalue>char</returnvalue></link> * +cairo_ps_level_to_string (<parameter><link linkend="cairo-ps-level-t"><type>cairo_ps_level_t</type></link> level</parameter>);</programlisting> +<para>Get the string representation of the given <parameter>level</parameter> + id. This function +will return <link linkend="NULL:CAPS"><literal>NULL</literal></link> if <parameter>level</parameter> + id isn't valid. See <link linkend="cairo-ps-get-levels"><function>cairo_ps_get_levels()</function></link> +for a way to get the list of valid level ids.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>level</para></entry> +<entry role="parameter_description"><para>a level id</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><refsect3 role="returns"> +<title>Returns</title> +<para> the string associated to given level.</para> +<para></para> +</refsect3><para role="since">Since 1.6</para></refsect2> +<refsect2 id="cairo-ps-surface-set-eps" role="function" condition="since:1.6"> +<title>cairo_ps_surface_set_eps ()</title> +<indexterm zone="cairo-ps-surface-set-eps" role="1.6"><primary sortas="ps_surface_set_eps">cairo_ps_surface_set_eps</primary></indexterm> +<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> +cairo_ps_surface_set_eps (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, + <parameter><link linkend="cairo-bool-t"><type>cairo_bool_t</type></link> eps</parameter>);</programlisting> +<para>If <parameter>eps</parameter> + is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>, the PostScript surface will output Encapsulated +PostScript.</para> +<para>This function should only be called before any drawing operations +have been performed on the current page. The simplest way to do +this is to call this function immediately after creating the +surface. An Encapsulated PostScript file should never contain more +than one page.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>surface</para></entry> +<entry role="parameter_description"><para>a PostScript <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>eps</para></entry> +<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to output EPS format PostScript</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><para role="since">Since 1.6</para></refsect2> +<refsect2 id="cairo-ps-surface-get-eps" role="function" condition="since:1.6"> +<title>cairo_ps_surface_get_eps ()</title> +<indexterm zone="cairo-ps-surface-get-eps" role="1.6"><primary sortas="ps_surface_get_eps">cairo_ps_surface_get_eps</primary></indexterm> +<programlisting language="C"><link linkend="cairo-bool-t"><returnvalue>cairo_bool_t</returnvalue></link> +cairo_ps_surface_get_eps (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> +<para>Check whether the PostScript surface will output Encapsulated PostScript.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>surface</para></entry> +<entry role="parameter_description"><para>a PostScript <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><refsect3 role="returns"> +<title>Returns</title> +<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the surface will output Encapsulated PostScript.</para> +<para></para> +</refsect3><para role="since">Since 1.6</para></refsect2> +<refsect2 id="cairo-ps-surface-set-size" role="function" condition="since:1.2"> +<title>cairo_ps_surface_set_size ()</title> +<indexterm zone="cairo-ps-surface-set-size" role="1.2"><primary sortas="ps_surface_set_size">cairo_ps_surface_set_size</primary></indexterm> +<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> +cairo_ps_surface_set_size (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, + <parameter><link linkend="double"><type>double</type></link> width_in_points</parameter>, + <parameter><link linkend="double"><type>double</type></link> height_in_points</parameter>);</programlisting> +<para>Changes the size of a PostScript surface for the current (and +subsequent) pages.</para> +<para>This function should only be called before any drawing operations +have been performed on the current page. The simplest way to do +this is to call this function immediately after creating the +surface or immediately after completing a page with either +<link linkend="cairo-show-page"><function>cairo_show_page()</function></link> or <link linkend="cairo-copy-page"><function>cairo_copy_page()</function></link>.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>surface</para></entry> +<entry role="parameter_description"><para>a PostScript <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>width_in_points</para></entry> +<entry role="parameter_description"><para>new surface width, in points (1 point == 1/72.0 inch)</para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>height_in_points</para></entry> +<entry role="parameter_description"><para>new surface height, in points (1 point == 1/72.0 inch)</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><para role="since">Since 1.2</para></refsect2> +<refsect2 id="cairo-ps-surface-dsc-begin-setup" role="function" condition="since:1.2"> +<title>cairo_ps_surface_dsc_begin_setup ()</title> +<indexterm zone="cairo-ps-surface-dsc-begin-setup" role="1.2"><primary sortas="ps_surface_dsc_begin_setup">cairo_ps_surface_dsc_begin_setup</primary></indexterm> +<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> +cairo_ps_surface_dsc_begin_setup (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> +<para>This function indicates that subsequent calls to +<link linkend="cairo-ps-surface-dsc-comment"><function>cairo_ps_surface_dsc_comment()</function></link> should direct comments to the Setup +section of the PostScript output.</para> +<para>This function should be called at most once per surface, and must +be called before any call to <link linkend="cairo-ps-surface-dsc-begin-page-setup"><function>cairo_ps_surface_dsc_begin_page_setup()</function></link> +and before any drawing is performed to the surface.</para> +<para>See <link linkend="cairo-ps-surface-dsc-comment"><function>cairo_ps_surface_dsc_comment()</function></link> for more details.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>surface</para></entry> +<entry role="parameter_description"><para>a PostScript <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><para role="since">Since 1.2</para></refsect2> +<refsect2 id="cairo-ps-surface-dsc-begin-page-setup" role="function" condition="since:1.2"> +<title>cairo_ps_surface_dsc_begin_page_setup ()</title> +<indexterm zone="cairo-ps-surface-dsc-begin-page-setup" role="1.2"><primary sortas="ps_surface_dsc_begin_page_setup">cairo_ps_surface_dsc_begin_page_setup</primary></indexterm> +<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> +cairo_ps_surface_dsc_begin_page_setup (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting> +<para>This function indicates that subsequent calls to +<link linkend="cairo-ps-surface-dsc-comment"><function>cairo_ps_surface_dsc_comment()</function></link> should direct comments to the +PageSetup section of the PostScript output.</para> +<para>This function call is only needed for the first page of a +surface. It should be called after any call to +<link linkend="cairo-ps-surface-dsc-begin-setup"><function>cairo_ps_surface_dsc_begin_setup()</function></link> and before any drawing is +performed to the surface.</para> +<para>See <link linkend="cairo-ps-surface-dsc-comment"><function>cairo_ps_surface_dsc_comment()</function></link> for more details.</para> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>surface</para></entry> +<entry role="parameter_description"><para>a PostScript <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><para role="since">Since 1.2</para></refsect2> +<refsect2 id="cairo-ps-surface-dsc-comment" role="function" condition="since:1.2"> +<title>cairo_ps_surface_dsc_comment ()</title> +<indexterm zone="cairo-ps-surface-dsc-comment" role="1.2"><primary sortas="ps_surface_dsc_comment">cairo_ps_surface_dsc_comment</primary></indexterm> +<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link> +cairo_ps_surface_dsc_comment (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>, + <parameter>const <link linkend="char"><type>char</type></link> *comment</parameter>);</programlisting> +<para>Emit a comment into the PostScript output for the given surface.</para> +<para>The comment is expected to conform to the PostScript Language +Document Structuring Conventions (DSC). Please see that manual for +details on the available comments and their meanings. In +particular, the %%IncludeFeature comment allows a +device-independent means of controlling printer device features. So +the PostScript Printer Description Files Specification will also be +a useful reference.</para> +<para>The comment string must begin with a percent character (%) and the +total length of the string (including any initial percent +characters) must not exceed 255 characters. Violating either of +these conditions will place <parameter>surface</parameter> + into an error state. But +beyond these two conditions, this function will not enforce +conformance of the comment with any particular specification.</para> +<para>The comment string should not have a trailing newline.</para> +<para>The DSC specifies different sections in which particular comments +can appear. This function provides for comments to be emitted +within three sections: the header, the Setup section, and the +PageSetup section. Comments appearing in the first two sections +apply to the entire document while comments in the BeginPageSetup +section apply only to a single page.</para> +<para>For comments to appear in the header section, this function should +be called after the surface is created, but before a call to +<link linkend="cairo-ps-surface-dsc-begin-setup"><function>cairo_ps_surface_dsc_begin_setup()</function></link>.</para> +<para>For comments to appear in the Setup section, this function should +be called after a call to <link linkend="cairo-ps-surface-dsc-begin-setup"><function>cairo_ps_surface_dsc_begin_setup()</function></link> but +before a call to <link linkend="cairo-ps-surface-dsc-begin-page-setup"><function>cairo_ps_surface_dsc_begin_page_setup()</function></link>.</para> +<para>For comments to appear in the PageSetup section, this function +should be called after a call to +<link linkend="cairo-ps-surface-dsc-begin-page-setup"><function>cairo_ps_surface_dsc_begin_page_setup()</function></link>.</para> +<para>Note that it is only necessary to call +<link linkend="cairo-ps-surface-dsc-begin-page-setup"><function>cairo_ps_surface_dsc_begin_page_setup()</function></link> for the first page of any +surface. After a call to <link linkend="cairo-show-page"><function>cairo_show_page()</function></link> or <link linkend="cairo-copy-page"><function>cairo_copy_page()</function></link> +comments are unambiguously directed to the PageSetup section of the +current page. But it doesn't hurt to call this function at the +beginning of every page as that consistency may make the calling +code simpler.</para> +<para>As a final note, cairo automatically generates several comments on +its own. As such, applications must not manually generate any of +the following comments:</para> +<para>Header section: %!PS-Adobe-3.0, %%Creator, %%CreationDate, %%Pages, +%%BoundingBox, %%DocumentData, %%LanguageLevel, %%EndComments.</para> +<para>Setup section: %%BeginSetup, %%EndSetup</para> +<para>PageSetup section: %%BeginPageSetup, %%PageBoundingBox, %%EndPageSetup.</para> +<para>Other sections: %%BeginProlog, %%EndProlog, %%Page, %%Trailer, %%EOF</para> +<para>Here is an example sequence showing how this function might be used:</para> +<informalexample><programlisting> +cairo_surface_t *surface = cairo_ps_surface_create (filename, width, height); +... +cairo_ps_surface_dsc_comment (surface, "%%Title: My excellent document"); +cairo_ps_surface_dsc_comment (surface, "%%Copyright: Copyright (C) 2006 Cairo Lover") +... +cairo_ps_surface_dsc_begin_setup (surface); +cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor White"); +... +cairo_ps_surface_dsc_begin_page_setup (surface); +cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A3"); +cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *InputSlot LargeCapacity"); +cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaType Glossy"); +cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *MediaColor Blue"); +... draw to first page here .. +cairo_show_page (cr); +... +cairo_ps_surface_dsc_comment (surface, "%%IncludeFeature: *PageSize A5"); +... +</programlisting></informalexample> +<refsect3 role="parameters"> +<title>Parameters</title> +<informaltable role="parameters_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="parameters_name" colwidth="150px"/> +<colspec colname="parameters_description"/> +<colspec colname="parameters_annotations" colwidth="200px"/> +<tbody> +<row><entry role="parameter_name"><para>surface</para></entry> +<entry role="parameter_description"><para>a PostScript <link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para></entry> +<entry role="parameter_annotations"></entry></row> +<row><entry role="parameter_name"><para>comment</para></entry> +<entry role="parameter_description"><para>a comment string to be emitted into the PostScript output</para></entry> +<entry role="parameter_annotations"></entry></row> +</tbody></tgroup></informaltable> +</refsect3><para role="since">Since 1.2</para></refsect2> + +</refsect1> +<refsect1 id="cairo-PostScript-Surfaces.other_details" role="details"> +<title role="details.title">Types and Values</title> +<refsect2 id="CAIRO-HAS-PS-SURFACE:CAPS" role="macro" condition="since:1.2"> +<title>CAIRO_HAS_PS_SURFACE</title> +<indexterm zone="CAIRO-HAS-PS-SURFACE:CAPS" role="1.2"><primary sortas="HAS_PS_SURFACE">CAIRO_HAS_PS_SURFACE</primary></indexterm> +<programlisting language="C">#define CAIRO_HAS_PS_SURFACE 1 +</programlisting> +<para>Defined if the PostScript surface backend is available. +This macro can be used to conditionally compile backend-specific code.</para> +<para role="since">Since 1.2</para></refsect2> +<refsect2 id="cairo-ps-level-t" role="enum" condition="since:1.6"> +<title>enum cairo_ps_level_t</title> +<indexterm zone="cairo-ps-level-t" role="1.6"><primary sortas="ps_level_t">cairo_ps_level_t</primary></indexterm> +<para><link linkend="cairo-ps-level-t"><type>cairo_ps_level_t</type></link> is used to describe the language level of the +PostScript Language Reference that a generated PostScript file will +conform to.</para> +<refsect3 role="enum_members"> +<title>Members</title> +<informaltable role="enum_members_table" pgwide="1" frame="none"> +<tgroup cols="3"> +<colspec colname="enum_members_name" colwidth="300px"/> +<colspec colname="enum_members_description"/> +<colspec colname="enum_members_annotations" colwidth="200px"/> +<tbody> +<row role="constant"><entry role="enum_member_name"><para id="CAIRO-PS-LEVEL-2:CAPS">CAIRO_PS_LEVEL_2</para></entry> +<entry role="enum_member_description"><para>The language level 2 of the PostScript specification. (Since 1.6)</para> +</entry> +<entry role="enum_member_annotations"></entry> +</row> +<row role="constant"><entry role="enum_member_name"><para id="CAIRO-PS-LEVEL-3:CAPS">CAIRO_PS_LEVEL_3</para></entry> +<entry role="enum_member_description"><para>The language level 3 of the PostScript specification. (Since 1.6)</para> +</entry> +<entry role="enum_member_annotations"></entry> +</row> +</tbody></tgroup></informaltable> +</refsect3><para role="since">Since 1.6</para></refsect2> + +</refsect1> +<refsect1 id="cairo-PostScript-Surfaces.see-also"> +<title>See Also</title> +<para><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link></para> + +</refsect1> + +</refentry> |