lib/libform/form_field.3

   1 .\"     $NetBSD: form_field.3,v 1.9 2004/11/24 12:26:23 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 field_count ,
  37 .Nm form_fields ,
  38 .Nm move_field ,
  39 .Nm set_form_fields
  40 .Nd form library
  41 .Sh LIBRARY
  42 .Lb libform
  43 .Sh SYNOPSIS
  44 .In form.h
  45 .Ft int
  46 .Fn field_count "FORM *form"
  47 .Ft FIELD **
  48 .Fn form_fields "FORM *form"
  49 .Ft int
  50 .Fn move_field "FIELD *field" "int frow" "int fcol"
  51 .Ft int
  52 .Fn set_form_fields "FORM *form" " FIELD **fields"
  53 .Sh DESCRIPTION
  54 The
  55 .Fn field_count
  56 function returns the number of fields that are attached to the given
  57 form, if the form argument passed is
  58 .Dv NULL
  59 then
  60 .Fn field_count
  61 will return \-1.
  62 The function
  63 .Fn form_fields
  64 will return a pointer to array of attach fields for the given form,
  65 this array is not
  66 .Dv NULL
  67 terminated, fields may be attached to the given
  68 form by calling
  69 .Fn set_form_fields .
  70 The
  71 .Fa fields
  72 argument in this function is a pointer to a
  73 .Dv NULL
  74 terminated array of
  75 fields that will be attached to the form.
  76 If there are already fields attached to the form then they will be
  77 detached before the new fields are attached.
  78 The new fields given must not be attached to any other form.
  79 The
  80 .Fn move_field
  81 function will move the given field to the location specified by
  82 .Fa frow
  83 and
  84 .Fa fcol .
  85 .Sh RETURN VALUES
  86 Functions returning pointers will return
  87 .Dv NULL
  88 if an error is detected.
  89 The functions that return an int will return one of the following error
  90 values:
  91 .Pp
  92 .Bl -tag -width E_UNKNOWN_COMMAND -compact
  93 .It Er E_OK
  94 The function was successful.
  95 .It Er E_CONNECTED
  96 The field is connected to a form.
  97 .It Er E_POSTED
  98 The form is currently posted to the screen.
  99 .It Er E_BAD_ARGUMENT
 100 The function was passed a bad argument.
 101 .El
 102 .Sh SEE ALSO
 103 .Xr curses 3 ,
 104 .Xr forms 3
 105 .Sh NOTES
 106 The header
 107 .Aq Pa form.h
 108 automatically includes both
 109 .Aq Pa curses.h
 110 and
 111 .Aq Pa eti.h .