'\" te
.\"  Copyright 1989 AT&T
.\" Portions Copyright (c) 1996, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH FORMS 3CURSES "Dec 31, 1996"
.SH NAME
forms \- character based forms package
.SH SYNOPSIS
.LP
.nf
\fB#include <form.h>\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBform\fR library is built using the \fBcurses\fR library, and any program
using \fBforms\fR routines must call one of the \fBcurses\fR initialization
routines such as \fBinitscr\fR. A program using these routines must be compiled
with \fB-lform\fR and \fB-lcurses\fR on the \fBcc\fR command line.
.sp
.LP
The \fBforms\fR package gives the applications programmer a
terminal-independent method of creating and customizing forms for
user-interaction. The \fBforms\fR package includes: field routines, which are
used to create and customize fields, link fields and assign field types;
fieldtype routines, which are used to create new field types for validating
fields; and form routines, which are used to create and customize forms, assign
pre/post processing functions, and display and interact with forms.
.SS "Current Default Values for Field Attributes"
.sp
.LP
The \fBforms\fR package establishes initial current default values for field
attributes. During field initialization, each field attribute is assigned the
current default value for that attribute. An application can change or retrieve
a current default attribute value by calling the appropriate set or retrieve
routine with a \fINULL\fR field pointer. If an application changes a current
default field attribute value, subsequent fields created using
\fBnew_field()\fR will have the new default attribute value. (The attributes of
previously created fields are not changed if a current default attribute value
is changed.)
.SS "Routine Name Index"
.sp
.LP
The following table lists each \fBforms\fR routine and the name of the manual
page on which it is described.
.sp
.ne 2
.na
\fBforms Routine Name\fR
.ad
.RS 25n
\fBManual Page Name\fR
.RE

.sp
.ne 2
.na
\fBcurrent_field\fR
.ad
.RS 25n
form_page(3X)
.RE

.sp
.ne 2
.na
\fBdata_ahead\fR
.ad
.RS 25n
form_data(3X)
.RE

.sp
.ne 2
.na
\fBdata_behind\fR
.ad
.RS 25n
form_data(3X)
.RE

.sp
.ne 2
.na
\fBdup_field\fR
.ad
.RS 25n
form_field_new(3X)
.RE

.sp
.ne 2
.na
\fBdynamic_field_info\fR
.ad
.RS 25n
form_field_info(3X)
.RE

.sp
.ne 2
.na
\fBfield_arg\fR
.ad
.RS 25n
form_field_validation(3X)
.RE

.sp
.ne 2
.na
\fBfield_back\fR
.ad
.RS 25n
form_field_attributes(3X)
.RE

.sp
.ne 2
.na
\fBfield_buffer\fR
.ad
.RS 25n
form_field_buffer(3X)
.RE

.sp
.ne 2
.na
\fBfield_count\fR
.ad
.RS 25n
form_field(3X)
.RE

.sp
.ne 2
.na
\fBfield_fore\fR
.ad
.RS 25n
form_field_attributes(3X)
.RE

.sp
.ne 2
.na
\fBfield_index\fR
.ad
.RS 25n
form_page(3X)
.RE

.sp
.ne 2
.na
\fBfield_info\fR
.ad
.RS 25n
form_field_info(3X)
.RE

.sp
.ne 2
.na
\fBfield_init\fR
.ad
.RS 25n
form_hook(3X)
.RE

.sp
.ne 2
.na
\fBfield_just\fR
.ad
.RS 25n
form_field_just(3X)
.RE

.sp
.ne 2
.na
\fBfield_opts\fR
.ad
.RS 25n
form_field_opts(3X)
.RE

.sp
.ne 2
.na
\fBfield_opts_off\fR
.ad
.RS 25n
form_field_opts(3X)
.RE

.sp
.ne 2
.na
\fBfield_opts_on\fR
.ad
.RS 25n
form_field_opts(3X)
.RE

.sp
.ne 2
.na
\fBfield_pad\fR
.ad
.RS 25n
form_field_attributes(3X)
.RE

.sp
.ne 2
.na
\fBfield_status\fR
.ad
.RS 25n
form_field_buffer(3X)
.RE

.sp
.ne 2
.na
\fBfield_term\fR
.ad
.RS 25n
form_hook(3X)
.RE

.sp
.ne 2
.na
\fBfield_type\fR
.ad
.RS 25n
form_field_validation(3X)
.RE

.sp
.ne 2
.na
\fBfield_userptr\fR
.ad
.RS 25n
form_field_userptr(3X)
.RE

.sp
.ne 2
.na
\fBform_driver\fR
.ad
.RS 25n
form_driver(3X)
.RE

.sp
.ne 2
.na
\fBform_fields\fR
.ad
.RS 25n
form_field(3X)
.RE

.sp
.ne 2
.na
\fBform_init\fR
.ad
.RS 25n
form_hook(3X)
.RE

.sp
.ne 2
.na
\fBform_opts\fR
.ad
.RS 25n
form_opts(3X)
.RE

.sp
.ne 2
.na
\fBform_opts_off\fR
.ad
.RS 25n
form_opts(3X)
.RE

.sp
.ne 2
.na
\fBform_opts_on\fR
.ad
.RS 25n
form_opts(3X)
.RE

.sp
.ne 2
.na
\fBform_page\fR
.ad
.RS 25n
form_page(3X)
.RE

.sp
.ne 2
.na
\fBform_sub\fR
.ad
.RS 25n
form_win(3X)
.RE

.sp
.ne 2
.na
\fBform_term\fR
.ad
.RS 25n
form_hook(3X)
.RE

.sp
.ne 2
.na
\fBform_userptr\fR
.ad
.RS 25n
form_userptr(3X)
.RE

.sp
.ne 2
.na
\fBform_win\fR
.ad
.RS 25n
form_win(3X)
.RE

.sp
.ne 2
.na
\fBfree_field\fR
.ad
.RS 25n
form_field_new(3X)
.RE

.sp
.ne 2
.na
\fBfree_fieldtype\fR
.ad
.RS 25n
form_fieldtype(3X)
.RE

.sp
.ne 2
.na
\fBfree_form\fR
.ad
.RS 25n
form_new(3X)
.RE

.sp
.ne 2
.na
\fBlink_field\fR
.ad
.RS 25n
form_field_new(3X)
.RE

.sp
.ne 2
.na
\fBlink_fieldtype\fR
.ad
.RS 25n
form_fieldtype(3X)
.RE

.sp
.ne 2
.na
\fBmove_field\fR
.ad
.RS 25n
form_field(3X)
.RE

.sp
.ne 2
.na
\fBnew_field\fR
.ad
.RS 25n
form_field_new(3X)
.RE

.sp
.ne 2
.na
\fBnew_fieldtype\fR
.ad
.RS 25n
form_fieldtype(3X)
.RE

.sp
.ne 2
.na
\fBnew_form\fR
.ad
.RS 25n
form_new(3X)
.RE

.sp
.ne 2
.na
\fBnew_page\fR
.ad
.RS 25n
form_new_page(3X)
.RE

.sp
.ne 2
.na
\fBpos_form_cursor\fR
.ad
.RS 25n
form_cursor(3X)
.RE

.sp
.ne 2
.na
\fBpost_form\fR
.ad
.RS 25n
form_post(3X)
.RE

.sp
.ne 2
.na
\fBscale_form\fR
.ad
.RS 25n
form_win(3X)
.RE

.sp
.ne 2
.na
\fBset_current_field\fR
.ad
.RS 25n
form_page(3X)
.RE

.sp
.ne 2
.na
\fBset_field_back\fR
.ad
.RS 25n
form_field_attributes(3X)
.RE

.sp
.ne 2
.na
\fBset_field_buffer\fR
.ad
.RS 25n
form_field_buffer(3X)
.RE

.sp
.ne 2
.na
\fBset_field_fore\fR
.ad
.RS 25n
form_field_attributes(3X)
.RE

.sp
.ne 2
.na
\fBset_field_init\fR
.ad
.RS 25n
form_hook(3X)
.RE

.sp
.ne 2
.na
\fB set_field_just\fR
.ad
.RS 25n
form_field_just(3X)
.RE

.sp
.ne 2
.na
\fBset_field_opts\fR
.ad
.RS 25n
form_field_opts(3X)
.RE

.sp
.ne 2
.na
\fBset_field_pad\fR
.ad
.RS 25n
form_field_attributes(3X)
.RE

.sp
.ne 2
.na
\fBset_field_status\fR
.ad
.RS 25n
form_field_buffer(3X)
.RE

.sp
.ne 2
.na
\fBset_field_term\fR
.ad
.RS 25n
form_hook(3X)
.RE

.sp
.ne 2
.na
\fBset_field_type\fR
.ad
.RS 25n
form_field_validation(3X)
.RE

.sp
.ne 2
.na
\fBset_field_userptr\fR
.ad
.RS 25n
form_field_userptr(3X)
.RE

.sp
.ne 2
.na
\fBset_fieldtype_arg\fR
.ad
.RS 25n
form_fieldtype(3X)
.RE

.sp
.ne 2
.na
\fBset_fieldtype_choice\fR
.ad
.RS 25n
form_fieldtype(3X)
.RE

.sp
.ne 2
.na
\fBset_form_fields\fR
.ad
.RS 25n
form_field(3X)
.RE

.sp
.ne 2
.na
\fBset_form_init\fR
.ad
.RS 25n
form_hook(3X)
.RE

.sp
.ne 2
.na
\fBset_form_opts\fR
.ad
.RS 25n
form_opts(3X)
.RE

.sp
.ne 2
.na
\fBset_form_page\fR
.ad
.RS 25n
form_page(3X)
.RE

.sp
.ne 2
.na
\fBset_form_sub\fR
.ad
.RS 25n
form_win(3X)
.RE

.sp
.ne 2
.na
\fBset_form_term\fR
.ad
.RS 25n
form_hook(3X)
.RE

.sp
.ne 2
.na
\fBset_form_userptr\fR
.ad
.RS 25n
form_userptr(3X)
.RE

.sp
.ne 2
.na
\fBset_form_win\fR
.ad
.RS 25n
form_win(3X)
.RE

.sp
.ne 2
.na
\fBset_max_field\fR
.ad
.RS 25n
form_field_buffer(3X)
.RE

.sp
.ne 2
.na
\fBset_new_page\fR
.ad
.RS 25n
form_new_page(3X)
.RE

.sp
.ne 2
.na
\fBunpost_form\fR
.ad
.RS 25n
form_post(3X)
.RE

.SH RETURN VALUES
.sp
.LP
Routines that return a pointer always return \fINULL\fR on error. Routines that
return an integer return one of the following:
.sp
.ne 2
.na
\fB\fBE_OK\fR\fR
.ad
.RS 21n
The function returned successfully.
.RE

.sp
.ne 2
.na
\fB\fBE_CONNECTED\fR\fR
.ad
.RS 21n
The field is already connected to a form.
.RE

.sp
.ne 2
.na
\fB\fBE_SYSTEM_ERROR\fR\fR
.ad
.RS 21n
System error.
.RE

.sp
.ne 2
.na
\fB\fBE_BAD_ARGUMENT\fR\fR
.ad
.RS 21n
An argument is incorrect.
.RE

.sp
.ne 2
.na
\fB\fBE_CURRENT\fR\fR
.ad
.RS 21n
The field is the current field.
.RE

.sp
.ne 2
.na
\fB\fBE_POSTED\fR\fR
.ad
.RS 21n
The form is posted.
.RE

.sp
.ne 2
.na
\fB\fBE_NOT_POSTED\fR\fR
.ad
.RS 21n
The form is not posted.
.RE

.sp
.ne 2
.na
\fB\fBE_INVALID_FIELD\fR\fR
.ad
.RS 21n
The field contents are invalid.
.RE

.sp
.ne 2
.na
\fB\fBE_NOT_CONNECTED\fR\fR
.ad
.RS 21n
The field is not connected to a form.
.RE

.sp
.ne 2
.na
\fB\fBE_NO_ROOM\fR\fR
.ad
.RS 21n
The form does not fit in the subwindow.
.RE

.sp
.ne 2
.na
\fB\fBE_BAD_STATE\fR\fR
.ad
.RS 21n
The routine was called from an initialization or termination function.
.RE

.sp
.ne 2
.na
\fB\fBE_REQUEST_DENIED\fR\fR
.ad
.RS 21n
The form driver request failed.
.RE

.sp
.ne 2
.na
\fB\fBE_UNKNOWN_COMMAND\fR\fR
.ad
.RS 21n
An unknown request was passed to the form driver.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
MT-Level	Unsafe
.TE

.SH SEE ALSO
.sp
.LP
\fBcurses\fR(3CURSES), \fBattributes\fR(5)
.SH NOTES
.sp
.LP
The header \fB<form.h>\fR automatically includes the headers  \fB<eti.h>\fR and
\fB<curses.h>\fR\&.