lib/libform/form_field_new.3

   1 .\"     $NetBSD: form_field_new.3,v 1.9 2004/11/24 12:12:19 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2001
   4 .\"     Brett Lymn - blymn@baea.com.au, brett_lymn@yahoo.com.au
   5 .\"
   6 .\" This code is donated to The NetBSD Foundation by the author.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. The name of the Author may not be used to endorse or promote
  17 .\"    products derived from this software without specific prior written
  18 .\"    permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd January 1, 2001
  33 .Dt FORMS 3
  34 .Os
  35 .Sh NAME
  36 .Nm dup_field ,
  37 .Nm free_field ,
  38 .Nm link_field ,
  39 .Nm new_field
  40 .Nd form library
  41 .Sh LIBRARY
  42 .Lb libform
  43 .Sh SYNOPSIS
  44 .In form.h
  45 .Ft FIELD *
  46 .Fn dup_field "FIELD *field" "int frow" "int fcol"
  47 .Ft int
  48 .Fn free_field "FIELD *field"
  49 .Ft FIELD *
  50 .Fn link_field "FIELD *field" "int frow" "int fcol"
  51 .Ft FIELD *
  52 .Fo new_field
  53 .Fa "int rows"
  54 .Fa "int cols"
  55 .Fa "int frow"
  56 .Fa "int fcol"
  57 .Fa "int nrows"
  58 .Fa "int nbuf"
  59 .Fc
  60 .Sh DESCRIPTION
  61 The
  62 .Fn dup_field
  63 function duplicates the given field, including any buffers associated
  64 with the field and returns the pointer to the newly created field.
  65 .Fn free_field
  66 destroys the field and frees any allocated resources associated with
  67 the field.
  68 The function
  69 .Fn link_field
  70 copies the given field to a new field at the location
  71 .Fa frow
  72 and
  73 .Fa fcol
  74 but shares the buffers with the original field.
  75 .Fn new_field
  76 creates a new field of size
  77 .Fa rows
  78 by
  79 .Fa cols
  80 at location
  81 .Fa frow ,
  82 .Fa fcol
  83 on the page, the argument
  84 .Fa nrows
  85 specified the number of off screen rows the field has and the
  86 .Fa nbuf
  87 parameter specifies the number of extra buffers attached to the
  88 field.
  89 There will always be one buffer associated with a field.
  90 .Sh RETURN VALUES
  91 On error
  92 .Fn dup_field
  93 and
  94 .Fn new_field
  95 will return
  96 .Dv NULL .
  97 The functions will one of the following error
  98 values:
  99 .Pp
 100 .Bl -tag -width E_UNKNOWN_COMMAND -compact
 101 .It Er E_OK
 102 The function was successful.
 103 .It Er E_BAD_ARGUMENT
 104 A bad argument was passed to the function.
 105 .It Er E_CONNECTED
 106 The field is connected to a form.
 107 .El
 108 .Sh SEE ALSO
 109 .Xr curses 3 ,
 110 .Xr forms 3
 111 .Sh NOTES
 112 The header
 113 .Aq Pa form.h
 114 automatically includes both
 115 .Aq Pa curses.h
 116 and
 117 .Aq Pa eti.h .