cvs: peardoc / manual.xml.in /en/pecl ps.xml

From:	Uwe Steinmann	Date:	Wed, 21 Apr 2004 18:04:54 +0000
Subject:	cvs: peardoc / manual.xml.in /en/pecl ps.xml
Groups:	php.pear.doc
Request:	Send a blank email to pear-doc+get-3688@lists.php.net to get a copy of this message

steinm Wed Apr 21 14:04:54 2004 EDT Added files: /peardoc/en/pecl ps.xml Modified files: /peardoc manual.xml.in Log: - added documentation for ps extension

http://cvs.php.net/diff.php/peardoc/manual.xml.in?r1=1.29&r2=1.30&ty=u Index: peardoc/manual.xml.in diff -u peardoc/manual.xml.in:1.29 peardoc/manual.xml.in:1.30 --- peardoc/manual.xml.in:1.29 Mon Apr 12 06:06:43 2004 +++ peardoc/manual.xml.in Wed Apr 21 14:04:53 2004 @@ -99,6 +99,7 @@ &pecl.kadm5; &pecl.radius; &pecl.paradox; + &pecl.ps; &pecl.satellite; &pecl.session-pgsql; &pecl.soap; http://cvs.php.net/co.php/peardoc/en/pecl/ps.xml?r=1.1&p=1 Index: peardoc/en/pecl/ps.xml +++ peardoc/en/pecl/ps.xml <?xml version="1.0" encoding="iso-8859-1"?>   <reference id="pecl.ps"> <title>PostScript document creation</title> <titleabbrev>PS</titleabbrev> <partintro> <sect1 id="pecl.ps.partintro"> <title>Introduction</title> <sect2 id="pecl.ps.intro"> <title>About PostScript document creation</title> <para> This module allows to create PostScript documents. It has many similarities with the pdf extension. Actually the API is almost identical and one can in many cases just replace the prefix of each function from pdf_ to ps_. This also works for functions which has no meaning in the PostScript document (like adding hyperlinks) but will have an effect if the document is converted to PDF. </para> <para>Documents created by this extension are sometimes even superior to documents created with the pdf extension, because pslib's text rendering functions can handle kerning, hyphenation and ligatures which results in much better output of boxed text. </para> <note> <para> You will need to get the ps library (pslib) available at <ulink url="http://pslib.sourceforge.net">http://pslib.sourceforge.net</ulink>. </para> </note> </sect2> <sect2 id="pecl.ps.constants"> <title>Constants</title> <para> The following two tables lists all constants defined by the ps extension. <table id="pecl.ps.table-linecap"> <title>Contants for line caps</title> <tgroup cols="2"> <thead> <row> <entry>Name</entry> <entry>Meaning</entry> </row> </thead> <tbody> <row> <entry>ps_LINECAP_BUTT</entry> <entry></entry> </row> <row> <entry>ps_LINECAP_ROUND</entry> <entry></entry> </row> <row> <entry>ps_LINECAP_SQUARED</entry> <entry></entry> </row> </tbody> </tgroup> </table> <table id="pecl.paradox.table-linejoin"> <title>Contants for line joins</title> <tgroup cols="2"> <thead> <row> <entry>Name</entry> <entry>Meaning</entry> </row> </thead> <tbody> <row> <entry>ps_LINEJOIN_MITER</entry> <entry></entry> </row> <row> <entry>ps_LINEJOIN_ROUND</entry> <entry></entry> </row> <row> <entry>ps_LINEJOIN_BEVEL</entry> <entry></entry> </row> </tbody> </tgroup> </table> </para> </sect2> <sect2 id="pecl.ps.install"> <title>Installation</title> <para> A short installation note: <itemizedlist> <listitem> <simpara> You need at least PHP 5.0.0 and pslib >= 0.1.12 </simpara> </listitem> <listitem> <simpara> Just type 'pear install ps' in your console. </simpara> </listitem> </itemizedlist> </para> </sect2> <sect2 id="pecl.ps.configuration"> <title>Configuration</title> <para> </para> </sect2> </sect1> </partintro> <refentry> <refnamediv> <refname>ps_add_bookmark</refname> <refpurpose>Add bookmark to current page</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_add_bookmark</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>text</parameter></paramdef> <paramdef>int <parameter>parent</parameter></paramdef> <paramdef>int <parameter>open</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Adds a bookmark for the current page. Bookmarks usually appear in PDF-Viewers left of the page in hierachical tree. Clicking on a bookmark will jump to the given page.</para> <para>The bookmark has no meaning if the document is printed or viewed but it will be used if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_add_launchlink</function>, <function>ps_add_pdflink</function>, <function>ps_add_weblink</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_add_launchlink</refname> <refpurpose>Adds link which launches file</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_add_launchlink</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>llx</parameter></paramdef> <paramdef>float <parameter>lly</parameter></paramdef> <paramdef>float <parameter>urx</parameter></paramdef> <paramdef>float <parameter>ury</parameter></paramdef> <paramdef>string <parameter>filename</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Places a hyperlink at the given position pointing to a file program which is being started when click on. The hyperlink start is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border. </para> <para>The hyperlink will not be visible if the document is printed or viewed but it will show up if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_add_launchlink</function>, <function>ps_add_pdflink</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_add_locallink</refname> <refpurpose>Adds link to a page in the same document</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_add_locallink</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>llx</parameter></paramdef> <paramdef>float <parameter>lly</parameter></paramdef> <paramdef>float <parameter>urx</parameter></paramdef> <paramdef>float <parameter>ury</parameter></paramdef> <paramdef>int <parameter>page</parameter></paramdef> <paramdef>string <parameter>dest</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Places a hyperlink at the given position pointing to a page in the same document. Clicking on the link will jump to the given page. The first page in a document has number 1. The parameter <parameter>dest</parameter> determines how the document is being viewed. It can be 'fitpage', 'fitwidth', 'fitheight', or 'fitbbox'.</para> <para>The hyperlink start is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border. </para> <para>The hyperlink will not be visible if the document is printed or viewed but it will show up if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_add_launchlink</function>, <function>ps_add_pdflink</function>, <function>ps_add_weblink</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_add_note</refname> <refpurpose>Adds note to current page</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_add_note</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>text</parameter></paramdef> <paramdef>int <parameter>parent</parameter></paramdef> <paramdef>int <parameter>open</parameter></paramdef> </funcprototype> </funcsynopsis> <para></para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_add_pdflink</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_add_pdflink</refname> <refpurpose>Adds link to a page in a second pdf document</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_add_pdflink</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>llx</parameter></paramdef> <paramdef>float <parameter>lly</parameter></paramdef> <paramdef>float <parameter>urx</parameter></paramdef> <paramdef>float <parameter>ury</parameter></paramdef> <paramdef>string <parameter>filename</parameter></paramdef> <paramdef>int <parameter>page</parameter></paramdef> <paramdef>string <parameter>dest</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Places a hyperlink at the given position pointing to a second pdf document. Clicking on the link will branch to the document at the given page. The first page in a document has number 1. The parameter <parameter>dest</parameter> determines how the document is being viewed. It can be 'fitpage', 'fitwidth', 'fitheight', or 'fitbbox'.</para> <para>The hyperlink start is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border. </para> <para>The hyperlink will not be visible if the document is printed or viewed but it will show up if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_add_launchlink</function>, <function>ps_add_locallink</function>, <function>ps_add_weblink</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_add_weblink</refname> <refpurpose>Adds link to a web location</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_add_weblink</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>llx</parameter></paramdef> <paramdef>float <parameter>lly</parameter></paramdef> <paramdef>float <parameter>urx</parameter></paramdef> <paramdef>float <parameter>ury</parameter></paramdef> <paramdef>string <parameter>url</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Places a hyperlink at the given position pointing to a web page. The hyperlink start is a rectangle with its lower left corner at (llx, lly) and its upper right corner at (urx, ury). The rectangle has by default a thin blue border. </para> <para>The hyperlink will not be visible if the document is printed or viewed but it will show up if the document is converted to pdf by either Acrobat Distiller™ or Ghostview.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_add_launchlink</function>, <function>ps_add_pdflink</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_arcn</refname> <refpurpose>Draws an arc clockwise</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_arcn</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> <paramdef>float <parameter>radius</parameter></paramdef> <paramdef>float <parameter>alpha</parameter></paramdef> <paramdef>float <parameter>beta</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Draws a portion of a circle with at middle point at (<parameter>x</parameter>, <parameter>y</parameter>). The arc starts at an angle of <parameter>alpha</parameter> and ends at an angle of <parameter>beta</parameter>. It it draws clockwise. The subpath added to the current path starts on the arc at angle <parameter>beta</parameter> and ends on the arc at angle <parameter>alpha</parameter>.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_arc</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_arc</refname> <refpurpose>Draws an arc counterclockwise</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_arc</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> <paramdef>float <parameter>radius</parameter></paramdef> <paramdef>float <parameter>alpha</parameter></paramdef> <paramdef>float <parameter>beta</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Draws a portion of a circle with at middle point at (<parameter>x</parameter>, <parameter>y</parameter>). The arc starts at an angle of <parameter>alpha</parameter> and ends at an angle of <parameter>beta</parameter>. It is draw counterclockwise. The subpath added to the current path starts on the arc at angle <parameter>alpha</parameter> and ends on the arc at angle <parameter>beta</parameter>. </para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_arcn</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_begin_page</refname> <refpurpose>Start a new page</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_begin_page</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>width</parameter></paramdef> <paramdef>float <parameter>height</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Starts a new page. Though the parameters <parameter>width</parameter> and <parameter>height</parameter> imply a different page size for each page, this is not possible in PostScript. The first call of <function>ps_</function> will set the page size for the whole document. Consecutive calls will have no effect, except for creating a new page. The situation is different if you indent to convert the PostScript document into PDF. This function places pdfmarks into the document which can set the size for each page indiviually. The resulting PDF document will have different page sizes. </para> <para>Each page is encapsulated into save/restore. This means, that most of the settings made on one page will not be retained on the next page. This affects font loading. A font loaded within a page will not be available on other pages. Instead of reloading the font with ps_findfont() on any page, one should rather call ps_findfont() before the first page is begun; especially if the font is to be embedded.</para> <para>If there is up to the first call of <function>ps_</function> no call of <function>ps_findfont</function>, then the header of the PostScript document will be output and the bounding box will be set to the size of the first page. If <function>ps_findfont</function> was called before the header has been output already, the document will not have a valid bounding box. In order to prevent this, one should set the info field 'BoundingBox' and possibly `Orientation' before any <function>ps_findfont</function> or <function>ps_begin_page</function> calls.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_end_page</function>, <function>ps_findfont</function>, <function>ps_set_info</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_boot</refname> <refpurpose>Initialize library</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_boot</function></funcdef> <paramdef>void <parameter></parameter></paramdef> </funcprototype> </funcsynopsis> <para>Does some initialization. Currently it only binds to a textdomain for gettext and sets locale for LC_CTYPE. Setting LC_CTYPE is needed for propper hyphenation.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_shutdown</function>, setlocale(3)</para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_circle</refname> <refpurpose>Draws a circle</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_circle</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> <paramdef>float <parameter>radius</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Draws a circle with its middle point at (<parameter>x</parameter>, <parameter>y</parameter>). The circle starts and ends at position (x+radius, y). If this function is called outside a path it will start a new path. If it is called within a path it will add the circle as a subpath. If the last drawing operation does not end in point (x+radius, y) then there will be a gab in the path.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_arc</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_clip</refname> <refpurpose>Clips drawing to current path</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_clip</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Takes the current path and uses it define the border of clipping area.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_closepath</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_close_image</refname> <refpurpose>Closes image and frees memory</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_close_image</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>int <parameter>imageid</parameter></paramdef> </funcprototype> </funcsynopsis> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_open_image</function>, <function>ps_open_image_file</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_closepath</refname> <refpurpose>Closes path</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_closepath</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Connects the last point with first point of a path.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_closepath_stoke</function>, <function>ps_clip</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_closepath_stroke</refname> <refpurpose>Closes and strokes path</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_closepath_stroke</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Connects the last point with first point of a path and draws the resulting closed line.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_closepath</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_close</refname> <refpurpose>Closes a PostScript document</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_close</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Closes the PostScript document. </para> <para>This function outputs a last line into the PostScript document, which is a PostScript comment containing the number of pages.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_open_file</function>, <function>ps_delete</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_continue_text</refname> <refpurpose>Continue text in next line</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_continue_text</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>text</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Output a text one line below the last outputed line. The text must be null terminated. The line spacing is taken from the value "leading" which must be set with <function><function>ps_set_value</function></function> in points. The actual position of the text is determined by the values "textx" and "texty" which can be requested with <function><function>ps_get_value</function></function></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_show</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_curveto</refname> <refpurpose>Draws a curve</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_curveto</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>x1</parameter></paramdef> <paramdef>float <parameter>y1</parameter></paramdef> <paramdef>float <parameter>x2</parameter></paramdef> <paramdef>float <parameter>y2</parameter></paramdef> <paramdef>float <parameter>x3</parameter></paramdef> <paramdef>float <parameter>y3</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Draws a curve described by the three given points.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_line</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_delete</refname> <refpurpose>Deletes all resources of a PostScript document</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_delete</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Mainly frees memory used by the document. Also closes a file, if it was not closed before with <function>ps_close</function>. You should in any case close the file with <function>ps_close</function> before, because <function>ps_close</function> not just closes the file but also outputs a last line containing the PostScript comment with the number of pages in the document. Without this comment, a PostScript viewer may not show the number of pages propperly.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_close</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_end_page</refname> <refpurpose>End a page</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_end_page</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Ends a page which was started with <function>ps_begin_page</function>.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_begin_page</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_fill</refname> <refpurpose>Fill the current path</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_fill</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Fills the path constructed with previously called drawing functions like <function>ps_lineto</function>.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_stroke</function>, <function>ps_fill_stroke</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_fill_stroke</refname> <refpurpose>Fills and strokes the current path</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_fill_stroke</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Fills and draws the path constructed with previously called drawing functions like <function>ps_lineto</function>.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_stroke</function>, <function>ps_fill</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_findfont</refname> <refpurpose>Loads a font</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_findfont</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>fontname</parameter></paramdef> <paramdef>string <parameter>encoding</parameter></paramdef> <paramdef>int <parameter>embed</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Loads a font for later use. Before text is output with a loaded font it must be set with <function>ps_setfont</function>. This function needs the adobe font metric file in order to calculate the space used up by the characters. A font which is loaded within a page will only be available on that page. Fonts which are to be used in the complete document has to be loaded before the first call of <function>ps_begin_page</function>. Calling <function>ps_</function> between pages will make that font available for all following pages.</para> <para>ps_ will try to load the file passed in the parameter <parameter>encoding</parameter>. Encoding files are of the same syntax as those used by <command>dvips(1)</command>. The contain a font encoding vector (which is currently not used but must be present) and a list of extra ligatures to extend the list of ligatures derived from the afm file.</para> <para><parameter>encoding</parameter> can be NULL or the empty string if the default encoding (TeXBase1) schall be used.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Returns the identifier of the font or zero in case of an error. The identifier is positiv number.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_setfont</function>, <function>ps_begin_page</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_get_buffer</refname> <refpurpose></refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>string <function>ps_get_buffer</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Not yet implemented</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_open_file</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_get_majorversion</refname> <refpurpose>returns the major version number of the PostScript library</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_get_majorversion</function></funcdef> <paramdef>void <parameter></parameter></paramdef> </funcprototype> </funcsynopsis> <para>This function can be used to retrieve the major version number of the PostScript library.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Returns major version as integer.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_get_minorversion</function>, <function>ps_get_subminorversion</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_get_minorversion</refname> <refpurpose>returns the minor version number of the PostScript library</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_get_minorversion</function></funcdef> <paramdef>void <parameter></parameter></paramdef> </funcprototype> </funcsynopsis> <para>This function can be used to retrieve the minor version number of the PostScript library.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Returns minor version as integer.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_get_majorversion</function>, <function>ps_get_subminorversion</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_get_parameter</refname> <refpurpose>Gets certain parameters</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>string <function>ps_get_parameter</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string<parameter>name</parameter></paramdef> <paramdef>float <parameter>modifier</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Gets several parameters which were set by <function>ps_set_parameters</function>. Parameters are by definition string values. This function cannot be used to retrieve resources which were also set by <function>ps_set_parameters</function>.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_set_parameters</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_get_subminorversion</refname> <refpurpose>returns the subminor version number of the PostScript library</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_get_subminorversion</function></funcdef> <paramdef>void <parameter></parameter></paramdef> </funcprototype> </funcsynopsis> <para>This function can be used to retrieve the subminor version number of the PostScript library.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Returns subminor version as integer.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_get_minorversion</function>, <function>ps_get_majorversion</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_get_value</refname> <refpurpose>Gets certain values</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>float <function>ps_get_value</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>name</parameter></paramdef> <paramdef>float <parameter>modifier</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Gets several valus which were set by <function>ps_set_value</function>. Parameters are by definition float values.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_set_value</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_hyphenate</refname> <refpurpose>Hyphenates a word</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_hyphenate</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>text</parameter></paramdef> <paramdef>string <parameter>*hyphens</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Hyphenates the passed word. <parameter>text</parameter> should not contain any non alpha characters. Possible positions for breaks are returned in <parameter>hyphens</parameter>.</para> <para>This function requires the locale category LC_CTYPE to be set propperly. ps_boot() usually does it by using the enviroment variables. </para> <para>ps_hyphenate() evaluates the value hyphenminchars and the parameter hyphendict.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Returns -1 in case of an error, and otherwise 0.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_boot</function>, <function>ps_show_boxed</function>, locale(1)</para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_lineto</refname> <refpurpose>Draws a line</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_lineto</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Draws a line from the current point to the given coordinates. Use <function>ps_moveto</function> to set the starting point of the line.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_moveto</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_moveto</refname> <refpurpose>Sets current point</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_moveto</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets the current point to new coordinates. If this is the first call of <function>ps_moveto</function> after a previous path has been ended then it will start a new path. If this function is called in the middle of a path it will just set the current point and start a subpath.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_lineto</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_new</refname> <refpurpose>Creates a new PostScript document object</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>resource <function>ps_new</function></funcdef> <paramdef>void <parameter></parameter></paramdef> </funcprototype> </funcsynopsis> <para>Creates a new document instance. It does not create the file on disk or in memory. It just sets up everything. You may pass your own error handler and memory management functions. If you pass NULL values the internal default handler and functions will be used. In such case you may as well call <function>ps_new</function>.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Pointer to new instance of PostScript document or NULL on failure.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_delete</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_open_file</refname> <refpurpose>Opens a file for output</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_open_file</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>filename</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Creates a new file on disk and writes the PostScript document into it. The file will be closed when <function>ps_close</function> is called. If filename is not passed the document will be created in memory and all output will go straight to the browser.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Returns -1 in case of an error and 0 otherwise.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_close</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_open_image_file</refname> <refpurpose>Opens image from file</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_open_image_file</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>type</parameter></paramdef> <paramdef>string <parameter>filename</parameter></paramdef> <paramdef>string <parameter>stringparam</parameter></paramdef> <paramdef>int <parameter>intparam</parameter></paramdef> </funcprototype> </funcsynopsis> <para></para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Returns identifier of image or zero in case of an error. The identifier is a positiv number greater 0.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_open_image</function>, <function>ps_place_image</function>, <function>ps_close_image</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_open_image</refname> <refpurpose>Reads an image for later placement</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_open_image</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>type</parameter></paramdef> <paramdef>string <parameter>source</parameter></paramdef> <paramdef>string <parameter>data</parameter></paramdef> <paramdef>int <parameter>lenght</parameter></paramdef> <paramdef>int <parameter>width</parameter></paramdef> <paramdef>int <parameter>height</parameter></paramdef> <paramdef>int <parameter>components</parameter></paramdef> <paramdef>int <parameter>bpc</parameter></paramdef> <paramdef>string <parameter>params</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Reads an image which is already available in memory. The parameter <parameter>source</parameter> is currently not evaluated and assumed to be `memory'.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Returns identifier of image or zero in case of an error. The identifier is a positiv number greater 0.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_open_image_file</function>, <function>ps_place_image</function>, <function>ps_close_image</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_place_image</refname> <refpurpose>Places image on the page</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_place_image</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>int <parameter>imageid</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> <paramdef>float <parameter>scale</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Places a formerly loaded image on the page. The image can be scaled. </para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_open_image</function>, <function>ps_open_image_file</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_rect</refname> <refpurpose>Draws a rectangle</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_rect</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> <paramdef>float <parameter>width</parameter></paramdef> <paramdef>float <parameter>height</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Draws a rectangle with its lower left corner at (<parameter>x</parameter>, <parameter>y</parameter>). The rectangle starts and ends in its lower left corner. If this function is called outside a path it will start a new path. If it is called within a path it will add the rectangle as a subpath. If the last drawing operation does not end in the lower left corner then there will be a gab in the path.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_cirle</function>, <function>ps_arc</function>, <function>ps_lineto</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_restore</refname> <refpurpose>Restore previously save context</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_restore</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Restores a previously saved graphics context. Any call of <function>ps_save</function> must be accompanied by a call to <function>ps_restore</function>.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_save</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_rotate</refname> <refpurpose>Sets rotation factor</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_rotate</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>rot</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets the rotation of the coordinate system.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_scale</function>, <function>ps_translate</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_save</refname> <refpurpose>Save current context</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_save</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Saves the current graphics context, containing colors, translation and rotation settings and some more. A save context be restored with <function>ps_restore</function>.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_restore</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_scale</refname> <refpurpose>Sets scaling factor</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_scale</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets horizontal and vertical scaling of the coordinate system.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_rotate</function>, <function>ps_translate</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_set_border_color</refname> <refpurpose>Sets color of border for annotations</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_set_border_color</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>red</parameter></paramdef> <paramdef>float <parameter>green</parameter></paramdef> <paramdef>float <parameter>blue</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Annotations like the starting points of links are surounded by a rectancle. This function sets the color of the border line.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_set_border_style</function>, <function>ps_set_border_dash</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_set_border_dash</refname> <refpurpose>Sets length of dashes for border of annotations</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_set_border_dash</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>black</parameter></paramdef> <paramdef>float <parameter>white</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Annotations like the starting points of links are surounded by a rectancle. This function sets the black and white portion of a dashed border line.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_set_border_style</function>, <function>ps_set_border_color</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_set_border_style</refname> <refpurpose>Sets border style of annotations</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_set_border_style</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>style</parameter></paramdef> <paramdef>float <parameter>width</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Annotations like the starting points of links are surounded by a rectancle. This function sets the appearance and width of the border line. <parameter>style</parameter> can be 'solid' or 'dashed'.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_set_border_color</function>, <function>ps_set_border_dash</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setcolor</refname> <refpurpose>Sets current color</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_setcolor</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>type</parameter></paramdef> <paramdef>string <parameter>colorspace</parameter></paramdef> <paramdef>float <parameter>c1</parameter></paramdef> <paramdef>float <parameter>c2</parameter></paramdef> <paramdef>float <parameter>c3</parameter></paramdef> <paramdef>float <parameter>c4</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets the color for drawing, filling, or both. The colorspace should be one of 'gray', 'rgb, 'cmyk'. Depending on the colorspace either only the first, the first three all or remaining parameters will be used.</para> <para>The parameter <parameter>type</parameter> can be 'both', 'fill', or 'stroke'.</para> </refsect1> <refsect1> <title>BUG</title> <para>The second parameter is currently not evaluated. The color is always set for filling and drawing just as if 'both' where passed.</para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setdash</refname> <refpurpose>Sets appearance of a dashed line</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_setdash</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>on</parameter></paramdef> <paramdef>float <parameter>off</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets the length of the black and white portions of a dashed line.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_setpolydash</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setflat</refname> <refpurpose>Sets flatness</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_setflat</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>value</parameter></paramdef> </funcprototype> </funcsynopsis> <para><parameter>value</parameter> must be between 0.2 and 1.</para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setfont</refname> <refpurpose>Sets font to use for following output</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_setfont</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>int <parameter>fontid</parameter></paramdef> <paramdef>float <parameter>size</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets a font, which has to be loaded before with <function>ps_findfont</function>. Outputting text without setting a font before results in an error.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_findfont</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setgray</refname> <refpurpose>Sets gray value</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_setgray</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>gray</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets the gray value for all following drawing operations. The value must be between 0 (white) and 1 (black).</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_setcolor</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_set_info</refname> <refpurpose>Sets information fields of document</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_set_info</function></funcdef> <paramdef>resource <parameter>p</parameter></paramdef> <paramdef>string <parameter>key</parameter></paramdef> <paramdef>string <parameter>val</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets certain information fields of the document. This fields will be shown as a comment in the header of the PostScript file. The values which can be set are Keywords, Subject, Title, Creator, Author, BoundingBox, Orientation. Be aware that some of them has a meaning to PostScript viewers.</para> <para>The BoundingBox is usually set to the value given to the first page. This only works if <function>ps_findfont</function> has not been called before. In such cases the BoundingBox would be left unset unless you set it explicitly with this function.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_findfont</function>, <function>ps_begin_page</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setlinecap</refname> <refpurpose>Sets appearance of line ends</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>int <parameter>type</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets how line ends look like.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_setlinewidth</function>, <function>ps_setlinejoin</function>, <function>ps_setmiterlimit</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setlinejoin</refname> <refpurpose>Sets how contected lines are joined</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_setlinejoin</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>int <parameter>type</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets how lines are joined.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_setlinewidth</function>, <function>ps_setlinecap</function>, <function>ps_setmiterlimit</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setlinewidth</refname> <refpurpose>Sets width of a line</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_setlinewidth</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>width</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets the line width for all following drawing operations.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_setlinecap</function>, <function>ps_setlinejoin</function>, <function>ps_setmiterlimit</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setmiterlimit</refname> <refpurpose>Sets the miter limit</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_setmiterlimit</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>value</parameter></paramdef> </funcprototype> </funcsynopsis> <para>If two lines join in small angle and the line join is set to miter, then the resulting spike will be very long. The miter limit is the maximum ratio of the miter length (the length of the spike) and the line width.</para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_set_parameter</refname> <refpurpose>Sets certain parameters</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_set_parameter</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>name</parameter></paramdef> <paramdef>string <parameter>value</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets several parameters which are used by many functions. Parameters are by definition string values.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_get_parameters</function>, <function>ps_set_value</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_setpolydash</refname> <refpurpose>Sets appearance of a dashed line</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_setpolydash</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>*arr</parameter></paramdef> <paramdef>int <parameter>length</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets the length of the black and white portions of a dashed line. <parameter>arr</parameter> is a list of <parameter>length</parameter> elements alternately for the black and white portion.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_setdash</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_set_value</refname> <refpurpose>Sets certain values</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_set_value</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>name</parameter></paramdef> <paramdef>float <parameter>value</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets several values which are used by many functions. Parameters are by definition float values.</para> <variablelist> <varlistentry> <term>textrendering</term> <listitem> <para>The way how text is shown. </para> </listitem> </varlistentry> <varlistentry> <term>wordspacing</term> <listitem> <para>The distance between words relativ to the width of a space. </para> </listitem> </varlistentry> <varlistentry> <term>leading</term> <listitem> <para>The distance between lines in pixels. </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>RETURN VALUE</title> <para></para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_get_value</function>, <function>ps_set_parameter</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_show</refname> <refpurpose>Output text</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_show</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>text</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Output a text at the current text position. The function will issue an error if no font was set before with <function>ps_setfont</function>.</para> <para>ps_() evaluates the following parameters and values as as set by <function>ps_set_parameter</function> and <function>ps_set_value</function>.</para> <variablelist> <varlistentry> <term>charspacing (value)</term> <listitem> <para>Distance between two consecutive glyphs. If this value is unequal to zero then all ligatures will be resolved. Values less than zero are allowed. </para> </listitem> </varlistentry> <varlistentry> <term>kerning (parameter)</term> <listitem> <para>Setting this parameter to `false' will turn off kerning. Kerning is turned on by default. </para> </listitem> </varlistentry> <varlistentry> <term>ligatures (parameter)</term> <listitem> <para>Setting this parameter to `false' will turn off the use of ligatures. Ligatures are turned on by default. </para> </listitem> </varlistentry> <varlistentry> <term>underline (parameter)</term> <listitem> <para>Setting this parameter to `true' will turn on underlining. Underlining is turned off by default. </para> </listitem> </varlistentry> <varlistentry> <term>overline (parameter)</term> <listitem> <para>Setting this parameter to `true' will turn on overlining. Overlining is turned off by default. </para> </listitem> </varlistentry> <varlistentry> <term>strikeout (parameter)</term> <listitem> <para>Setting this parameter to `true' will turn on striking out. Striking out is turned off by default. </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>See also</title> <para><function>ps_show</function>, <function>ps_continue_text2</function>, <function>ps_setfont</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_show_boxed</refname> <refpurpose>Output text in a box</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>int <function>ps_show_boxed</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>text</parameter></paramdef> <paramdef>float <parameter>left</parameter></paramdef> <paramdef>float <parameter>bottom</parameter></paramdef> <paramdef>float <parameter>width</parameter></paramdef> <paramdef>float <parameter>height</parameter></paramdef> <paramdef>string <parameter>hmode</parameter></paramdef> <paramdef>string <parameter>feature</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Outputs a text in a given box. The lower left corner of the box is at (<parameter>left</parameter>, <parameter>bottom</parameter>). Line breaks will be inserted where needed. Multiple spaces are treated as one. Tabulators are treated as spaces. The parameter <parameter>hmode</parameter> can be "justify", "fulljustify", "right", "left", or "center". The difference of "justify" and "fulljustify" just affects the last line of the box. In fulljustify mode the last line will be left and right justified unless this is also the last line of paragraph. In justify mode it will always be left justified.</para> <para>The text will be hyphenated if the parameter "hyphenation" is set to "true" and the parameter "hyphendict" contains a valid filename for a hyphenation file. The line spacing is taken from the value "leading". Paragraphs can be separated by an empty line just like in TeX. If the value "parindent" is set to value > 0.0 then the first n lines will be indented. The number n of lines is set by the parameter "numindentlines". In order to prevent indenting of the first m paragraphs set the value "parindentskip" to a positive number.</para> </refsect1> <refsect1> <title>USED PARAMETERS</title> <para>The output of <function>ps_</function> can be configured with several parameters and values which must be set with either <function><function>ps_set_parameter</function></function> or <function><function>ps_set_value</function></function>. Beside the parameters and values which affect text output the following parameters and values are evaluated.</para> <variablelist> <varlistentry> <term>leading (value)</term> <listitem> <para>Distance between baselines of two consecutive lines. </para> </listitem> </varlistentry> <varlistentry> <term>linebreak (parameter)</term> <listitem> <para>Set to "true" if you want a carrige return to start a new line instead of treating it as a space. Defaults to "false". </para> </listitem> </varlistentry> <varlistentry> <term>parbreak (parameter)</term> <listitem> <para>Set to "true" if you want a carrige return on a single line to start a new paragraph instead of treating it as a space. Defaults to "true". </para> </listitem> </varlistentry> <varlistentry> <term>hyphenation (parameter)</term> <listitem> <para>Set to "true" in order to turn hyphenation on. This requires a dictionary to be set with the parameter "hyphendict". Defaults to "false". </para> </listitem> </varlistentry> <varlistentry> <term>hyphendict (parameter)</term> <listitem> <para>Filename of the dictionary used for hyphenation pattern (see below). </para> </listitem> </varlistentry> <varlistentry> <term>hyphenminchar (value)</term> <listitem> <para>The number of chars which must at least be left over before or after the hyphen. This implies that only words of at least two times this value will be hyphenated. The default value is three. Setting a value of zero will result in the default value. </para> </listitem> </varlistentry> <varlistentry> <term>parindent (value)</term> <listitem> <para>Set the amount of space in pixel for indenting the first m lines of a paragraph. m can be set with the value "numindentlines". </para> </listitem> </varlistentry> <varlistentry> <term>parskip (value)</term> <listitem> <para>Set the amount of extra space in pixel between paragraphs. Defaults to 0 which will result in a normal line distance. </para> </listitem> </varlistentry> <varlistentry> <term>numindentlines (value)</term> <listitem> <para>Number of lines from the start of the paragraph which will be indented. Defaults to 1. </para> </listitem> </varlistentry> <varlistentry> <term>parindentskip (value)</term> <listitem> <para>Number of paragraphs in the box whose first lines will not be indented. This defaults to 0. This is useful for paragraphs right after a section heading or text being continued in a second box. In both case one would set this to 1. </para> </listitem> </varlistentry> <varlistentry> <term>linenumbermode (parameter)</term> <listitem> <para>Set how lines are to be numbered. Possible values are "box" for numbering lines in the whole box or "paragraph" to number lines within each paragraph. </para> </listitem> </varlistentry> <varlistentry> <term>linenumberspace (value)</term> <listitem> <para>The space for the column left of the numbered line containing the line number. The line number will be right justified into this column. Defaults to 20. </para> </listitem> </varlistentry> <varlistentry> <term>linenumbersep (value)</term> <listitem> <para>The space between the column with line numbers and the line itself. Defaults to 5. </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1> <title>HYPHENATION</title> <para>Text is hyphenated if the parameter "hyphenation" is set to true and a valid hyphenation dictory is set. pslib does not ship its own hyphenation dictionary but uses one from openoffice, scribus or koffice. You can find their dictionaries for different languages in one of the following directories if the software installed: /usr/share/apps/koffice/hyphdicts/, /usr/lib/scribus/dicts/, or /usr/lib/openoffice/share/dict/ooo. Currently scribus appears to have the most complete hyphenation dictionaries.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Number of charactes that could not be written.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_continue_text</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_show_xy</refname> <refpurpose>Output text at given position</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_show_xy</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>text</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Output a text at the given text position. </para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_continue_text</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_stringwidth</refname> <refpurpose>Gets width of a string</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>float <function>ps_</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>text</parameter></paramdef> <paramdef>int <parameter>fontid</parameter></paramdef> <paramdef>float <parameter>size</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Calculates the width of a string in points if it was output in the given font and font size. This function needs an Adobe font metrics file to calculate the precise width. If kerning is turned on, it will be taken into account.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Width of a string in points.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_stringwidth3</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_stringwidth3</refname> <refpurpose>Gets geometry of a string</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>float <function>ps_stringwidth3</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>string <parameter>text</parameter></paramdef> <paramdef>int <parameter>fontid</parameter></paramdef> <paramdef>float <parameter>size</parameter></paramdef> <paramdef>float <parameter>*dimension</parameter></paramdef> </funcprototype> </funcsynopsis> <para>This function is identical to <function><function>ps_stringwidth2</function></function> but has an extra parameter <parameter>dimension</parameter> which, if not NULL, will be used to return further dimensions of the string.</para> <para>dimension[0] contains the width as returned by the function. dimension[1] contains the maximum descender and dimension[2] the maximum ascender of the string.</para> </refsect1> <refsect1> <title>RETURN VALUE</title> <para>Width of a string in points.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_stringwidth</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_stroke</refname> <refpurpose>Draws the current path</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_stroke</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Draws the path constructed with previously called drawing functions like <function>ps_lineto</function>.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_closepath_stroke</function>, <function>ps_fill</function>, <function>ps_fill_stroke</function></para> </refsect1> </refentry> <refentry> <refnamediv> <refname>ps_translate</refname> <refpurpose>Sets translation</refpurpose> </refnamediv> <refsect1> <title>Description</title> <funcsynopsis> <funcprototype> <funcdef>bool <function>ps_translate</function></funcdef> <paramdef>resource <parameter>psdoc</parameter></paramdef> <paramdef>float <parameter>x</parameter></paramdef> <paramdef>float <parameter>y</parameter></paramdef> </funcprototype> </funcsynopsis> <para>Sets a new initial point of the coordinate system.</para> </refsect1> <refsect1> <title>See also</title> <para><function>ps_rotate</function>, <function>ps_scale</function></para> </refsect1> </refentry> </reference>