1'\" t 2 .\" $OpenBSD: form_field_buffer.3,v 1.14 2023年10月17日 09:52:10 nicm Exp $ 3 .\" 4 .\"*************************************************************************** 5 .\" Copyright 2018-2022,2023 Thomas E. Dickey * 6 .\" Copyright 1998-2010,2017 Free Software Foundation, Inc. * 7 .\" * 8 .\" Permission is hereby granted, free of charge, to any person obtaining a * 9 .\" copy of this software and associated documentation files (the * 10 .\" "Software"), to deal in the Software without restriction, including * 11 .\" without limitation the rights to use, copy, modify, merge, publish, * 12 .\" distribute, distribute with modifications, sublicense, and/or sell * 13 .\" copies of the Software, and to permit persons to whom the Software is * 14 .\" furnished to do so, subject to the following conditions: * 15 .\" * 16 .\" The above copyright notice and this permission notice shall be included * 17 .\" in all copies or substantial portions of the Software. * 18 .\" * 19 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS * 20 .\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF * 21 .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. * 22 .\" IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, * 23 .\" DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR * 24 .\" OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR * 25 .\" THE USE OR OTHER DEALINGS IN THE SOFTWARE. * 26 .\" * 27 .\" Except as contained in this notice, the name(s) of the above copyright * 28 .\" holders shall not be used in advertising or otherwise to promote the * 29 .\" sale, use or other dealings in this Software without prior written * 30 .\" authorization. * 31 .\"*************************************************************************** 32 .\" 33 .\" $Id: form_field_buffer.3,v 1.14 2023年10月17日 09:52:10 nicm Exp $ 34 .TH form_field_buffer 3 2023年07月01日 "ncurses 6.4" "Library calls" 35 .ie \n(.g .ds `` \(lq 36 .el .ds `` `` 37 .ie \n(.g .ds '' \(rq 38 .el .ds '' '' 39 .de bP 40 .ie n .IP \(bu 4 41 .el .IP \(bu 2 42.. 43 .SH NAME 44\fBform_field_buffer\fP \- field buffer control 45 .SH SYNOPSIS 46\fB#include <form.h>\fP 47 .sp 48\fBint set_field_buffer(FIELD *\fIfield\fB, int \fIbuf\fB, const char *\fIvalue\fB);\fR 49 .br 50\fBchar *field_buffer(const FIELD *\fIfield\fB, int \fIbuffer\fB);\fR 51 .sp 52\fBint set_field_status(FIELD *\fIfield\fB, bool \fIstatus\fB);\fR 53 .br 54\fBbool field_status(const FIELD *\fIfield\fB);\fR 55 .sp 56\fBint set_max_field(FIELD *\fIfield\fB, int \fImax\fB);\fR 57 .SH DESCRIPTION 58The function \fBset_field_buffer\fP sets the numbered buffer of the given field 59to contain a given string: 60 .RS 3 61 .bP 62Buffer 0 is the displayed value of the field. 63 .bP 64Other numbered buffers may be allocated by applications through the \fBnbuf\fP 65argument of (see \fBform_field_new\fP(3)) 66but are not manipulated by the forms library. 67 .RE 68 .PP 69The function \fBfield_buffer\fP returns a pointer to 70the contents of the given numbered buffer: 71 .RS 3 72 .bP 73The buffer contents always have the same length, 74and are padded with trailing spaces 75as needed to ensure this length is the same. 76 .bP 77The buffer may contain leading spaces, depending on how it was set. 78 .bP 79The buffer contents are set with \fBset_field_buffer\fP, 80or as a side effect of any editing operations on the corresponding field. 81 .bP 82Editing operations are based on the \fIwindow\fP which displays the field, 83rather than a \fIstring\fP. 84The window contains only printable characters, and is filled with blanks. 85If you want the raw data, you must write your 86own routine that copies the value out of the buffer and removes the leading 87and trailing spaces. 88 .bP 89Because editing operations change the content of the buffer to 90correspond to the window, you should not rely on using buffers 91for long-term storage of form data. 92 .RE 93 .PP 94The function \fBset_field_status\fP sets the associated status flag of 95\fIfield\fP; \fBfield_status\fP gets the current value. 96The status flag 97is set to a nonzero value whenever the field changes. 98 .PP 99The function \fBset_max_field\fP sets the maximum size for a dynamic field. 100An argument of 0 turns off any maximum size threshold for that field. 101 .SH RETURN VALUE 102The \fBfield_buffer\fP function returns NULL on error. 103It sets \fBerrno\fP according to their success: 104 .TP 5 105 .B E_OK 106The routine succeeded. 107 .TP 5 108 .B E_BAD_ARGUMENT 109Routine detected an incorrect or out-of-range argument. 110 .PP 111The \fBfield_status\fP function returns \fBTRUE\fP or \fBFALSE\fP. 112 .PP 113The remaining routines return one of the following: 114 .TP 5 115 .B E_OK 116The routine succeeded. 117 .TP 5 118 .B E_SYSTEM_ERROR 119System error occurred (see \fBerrno\fP(3)). 120 .TP 5 121 .B E_BAD_ARGUMENT 122Routine detected an incorrect or out-of-range argument. 123 .SH SEE ALSO 124\fBcurses\fP(3) and related pages whose names begin \*(``form_\*('' for detailed 125descriptions of the entry points. 126 .SH NOTES 127The header file \fB<form.h>\fP automatically includes the header file 128 .PP 129When configured for wide characters, \fBfield_buffer\fP returns a pointer 130to temporary storage (allocated and freed by the library). 131The application should not attempt to modify the data. 132It will be freed on the next call to \fBfield_buffer\fP to return the 133same buffer. 134\fB<curses.h>\fP. 135 .SH PORTABILITY 136These routines emulate the System V forms library. 137They were not supported on 138Version 7 or BSD versions. 139 .PP 140The \fBset_max_field\fP function checks for an ncurses extension 141\fBO_INPUT_FIELD\fP which allows a dynamic field to shrink if the new 142limit is smaller than the current field size. 143 .SH AUTHORS 144Juergen Pfeifer. 145Manual pages and adaptation for new curses by Eric S. Raymond. 146