lib/libform/form_field_opts.3

   1 .\"     $NetBSD: form_field_opts.3,v 1.9 2004/11/24 11:57:09 blymn 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 November 24, 2004
  33 .Dt FORMS 3
  34 .Os
  35 .Sh NAME
  36 .Nm field_opts ,
  37 .Nm field_opts_off ,
  38 .Nm field_opts_on ,
  39 .Nm set_field_opts
  40 .Nd form library
  41 .Sh LIBRARY
  42 .Lb libform
  43 .Sh SYNOPSIS
  44 .In form.h
  45 .Ft Form_Options
  46 .Fn field_opts "FIELD *field"
  47 .Ft int
  48 .Fn field_opts_off "FIELD *field" "Form_Options options"
  49 .Ft int
  50 .Fn field_opts_on "FIELD *field" "Form_Options options"
  51 .Ft int
  52 .Fn set_field_opts "FIELD *field" "Form_Options options"
  53 .Sh DESCRIPTION
  54 The function
  55 .Fn field_opts
  56 returns the current options settings for the given field.
  57 The
  58 .Fn field_opts_off
  59 will turn the options given in
  60 .Fa options
  61 off for the given field, options not specified in
  62 .Fa options
  63 will remain unchanged.
  64 Conversely, the function
  65 .Fn field_opts_on
  66 will turn on the options given in
  67 .Fa options
  68 for the specified field, again, any options not specified will remain
  69 unchanged.
  70 The options for a field may be set to a specific set of
  71 options by calling the
  72 .Fn set_field_opts
  73 function.
  74 Options may only be changed if the field given is not the
  75 currently active one.
  76 .Sh PARAMETERS
  77 The following options are available for a field:
  78 .Pp
  79 .Bl -tag -width O_REFORMAT -compact
  80 .It Dv O_VISIBLE
  81 The field is visible, hence is displayed when the form is posted.
  82 .It Dv O_ACTIVE
  83 The field is active in the form, meaning that it can be visited during
  84 form processing.
  85 .It Dv O_PUBLIC
  86 The contents of the field are echoed to the screen.
  87 .It Dv O_EDIT
  88 The contents of the field can be modified
  89 .It Dv O_WRAP
  90 The contents of the field are wrapped on a word boundary, if this
  91 option is off then the field will be wrapped on a character boundary.
  92 .It Dv O_BLANK
  93 Blank the field on new data being entered if and only if the field
  94 cursor is at the left hand side of the field.
  95 .It Dv O_AUTOSKIP
  96 Skip to the next field when the current field reaches its maximum
  97 size.
  98 .It Dv O_NULLOK
  99 The field is allowed to contain no data
 100 .It Dv O_STATIC
 101 The field is not dynamic, it has a fixed size.
 102 .It Dv O_PASSOK
 103 An unmodified field is allowed.
 104 .It Dv O_REFORMAT
 105 Retain the formatting of a field when the buffer is retrieved.
 106 If this option is not set then the buffer returned will be a single string
 107 with no line breaks.
 108 When this option is set newline characters will be inserted at the point
 109 where the string has been wrapped in a multiline field.
 110 This option is an extension to the forms library and must not be used
 111 in portable code.
 112 See the
 113 .Xr field_buffer 3
 114 man page for how this option modifies the behaviour of
 115 .Fn field_buffer .
 116 .El
 117 .Pp
 118 The following options are on by default for a field:
 119 .Dv O_VISIBLE ,
 120 .Dv O_ACTIVE ,
 121 .Dv O_PUBLIC ,
 122 .Dv O_EDIT ,
 123 .Dv O_WRAP ,
 124 .Dv O_BLANK ,
 125 .Dv O_AUTOSKIP ,
 126 .Dv O_NULLOK ,
 127 .Dv O_PASSOK ,
 128 and
 129 .Dv O_STATIC .
 130 .Sh RETURN VALUES
 131 Functions returning pointers will return
 132 .Dv NULL
 133 if an error is detected.
 134 The functions that return an int will return one of the following error
 135 values:
 136 .Pp
 137 .Bl -tag -width E_UNKNOWN_COMMAND -compact
 138 .It Er E_OK
 139 The function was successful.
 140 .It Er E_CURRENT
 141 The field specified is the currently active one in the form.
 142 .El
 143 .Sh SEE ALSO
 144 .Xr curses 3 ,
 145 .Xr forms 3
 146 .Sh NOTES
 147 The header
 148 .Aq Pa form.h
 149 automatically includes both
 150 .Aq Pa curses.h
 151 and
 152 .Aq Pa eti.h .
 153 The option
 154 .Dv O_REFORMAT
 155 is a
 156 .Nx
 157  extension and must not be used in portable code.