.. highlightlang:: us

.. index:: Overview Field Functions, Field Functions 

.. _overview-field-functions:

Overview Field Functions
========================

.. us.makeindex   fieldfunction, Field Functions

.. include:: ../ftab/fieldfunction.ftab

Writing user-defined Field Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You can write your own field functions. The following example
shows the definition of the field function ``@f{pagename}``. The
name of a field function starts with the prefix **__ff_**
(2 underscores followed by **ff** followed by one underscore) (The
prefix will be added by UniScript to the field function call). 
The function name must be specified in small letters. Every
field function has 6 parameters. The call parameters which are used in
the text element are passed to the field function in the parameter 
*svParameter*. The function must return the field result as a scalar
string. In case of an error, an empty string (``""``) should be
returned.

User defined field functions should be saved in a file with the extension
:file:`.ic` in the autoload directory. (:file:`uniplot/autoload`). All :file:`ic`
files in this directory are loaded at startup.

The parameter *hText* is the handle of the text object which contains the
field function. The parameters *hLayer*, *hPage* and *hDoc* are the handles
of the parent diagram, parent page and parent document of the text object.

**Example**:

::

   def __ff_pagename(hDoc, hPage, hLayer, hText, nAction, svParameter)
   {
       if (hPage != 0) {
           return PageGetTitle(hPage);
       }
       return "";
   }

You can find more field function examples in directory 
:file:`uniplot\\script\\field`.

.. seealso::
   :ref:`functions-by-categories`

:sub:`id-1133232`