Man Linux: Main Page and Category List

NAME

       PS_show_boxed — Output text in a box

SYNOPSIS

       #include <pslib.h>

       int  PS_show_boxed(PSDoc  *psdoc, char *text, float left, float bottom,
       float width, float height, const char *hmode, const char *feature)

DESCRIPTION

       Outputs a text in a given box. The lower left corner of the box  is  at
       (left,  bottom).   If  the  height is set to 0.0 the box will become as
       tall as needed to contain all the text. If feature is set to  blind  no
       text  will  be  output but the is set as usual. This can for example be
       used to calculate the box height needed to  comprise  all  text  or  in
       order to determine how much text fits into a box.

       Line  breaks will be inserted where needed. Multiple spaces are treated
       as one. Tabulators are treated as spaces. The parameter  hmode  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.

       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  of  indented  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.

USED PARAMETERS

       The output of PS_show_boxed can be configured with  several  parameters
       and  values  which  must  be  set  with  either  PS_set_parameter(3) or
       PS_set_value(3). Beside the parameters and  values  which  affect  text
       output the following parameters and values are evaluated.

       leading (value)
                 Distance between baselines of two consecutive lines.

       linebreak (parameter)
                 Set  to  "true"  if  you want a carrige return to start a new
                 line instead of treating it as a space. Defaults to  "false".

       parbreak (parameter)
                 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".

       hyphenation (parameter)
                 Set  to "true" in order to turn hyphenation on. This requires
                 a dictionary to  be  set  with  the  parameter  "hyphendict".
                 Defaults to "false".

       hyphendict (parameter)
                 Filename  of the dictionary used for hyphenation pattern (see
                 below).

       hyphenminchar (value)
                 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.

       parindent (value)
                 Set the amount of space in pixel for indenting  the  first  m
                 lines   of   a  paragraph.  m  can  be  set  with  the  value
                 "numindentlines".

       parskip (value)
                 Set the amount of extra space in  pixel  between  paragraphs.
                 Defaults to 0 which will result in a normal line distance.

       numindentlines (value)
                 Number of lines from the start of the paragraph which will be
                 indented. Defaults to 1.

       parindentskip (value)
                 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.

       linenumbermode (parameter)
                 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.

       linenumberspace (value)
                 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.

       linenumbersep (value)
                 The  space  between the column with line numbers and the line
                 itself. Defaults to 5.

HYPHENATION

       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  is  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.

RETURN VALUE

       Number  of charactes that could not be written. This function will also
       set the value "boxheight" to the actual height of the box. This enables
       you  to  put several boxed beneath each other and keep the propper line
       spacing.

SEE ALSO

       PS_continue_text(3)

AUTHOR

       This manual page was written by Uwe Steinmann <uwe@steinmann.cx>.