<article>

<artheader>

<title>Writing Programs Using <literal remap="tt">newt</literal></title>

<author> 

<firstname>Erik Troan, <ewt@redhat.com></firstname>

</author>

<pubdate>v0.31, 2003-Jan-06</pubdate>

<abstract>

<para>

The <literal remap="tt">newt</literal> windowing system is a terminal-based window and widget

library designed for writing applications with a simple, but user-friendly,

interface. While <literal remap="tt">newt</literal> is not intended to provide the rich feature

set advanced applications may require, it has proven to be flexible enough

for a wide range of applications (most notably, Red Hat's installation

process). This tutorial explains the design philosophy behind <literal remap="tt">newt</literal> and

how to use <literal remap="tt">newt</literal> from your programs.

</para>

</abstract>

</artheader>

<sect1><title>Introduction</title>

<para>

<literal remap="tt">Newt</literal> has a definite design philosophy behind it, and knowing that design

makes it significantly easier to craft robust <literal remap="tt">newt</literal> applications. This

tutorial documents <literal remap="tt">newt</literal> 0.30 --- older versions of <literal remap="tt">newt</literal> had

annoying inconsistencies in it (which writing this tutorial pointed out),

which were removed while this tutorial was written. The latest version of

<literal remap="tt">newt</literal> is always available from Red Hat.</para>

<sect2><title>Background</title>

<para>

<literal remap="tt">Newt</literal> was originally designed for use in the install code for

Red Hat Linux. As this install code runs in an environment with limited

resources (most importantly limited filesystem space), <literal remap="tt">newt</literal>'s size

was immediately an issue. To help minimize its size, the following design

decisions were made early in its implementation:

</para>

<itemizedlist>

<listitem>

<para>

 <literal remap="tt">newt</literal> does not use an event-driven architecture.

</para>

</listitem>

<listitem>

<para>

 <literal remap="tt">newt</literal> is written in C, not C++. While there has been interest

in constructing C++ wrapper classes around the <literal remap="tt">newt</literal> API, nothing has

yet come of those ideas.</para>

</listitem>

<listitem>

<para>

 Windows must be created and destroyed as a stack (in other words, all

<literal remap="tt">newt</literal> windows behave as modal dialogs). This is probably

the greatest functionality restriction of <literal remap="tt">newt</literal>.</para>

</listitem>

<listitem>

<para>

 The tty keyboard is the only supported input device.</para>

</listitem>

<listitem>

<para>

 Many behaviours, such as widget traversal order, are difficult

or impossible to change.

</para>

</listitem>

</itemizedlist>

<para>

While <literal remap="tt">newt</literal> provides a complete API, it does not handle the low-level

screen drawing itself. Instead, <literal remap="tt">newt</literal> is layered on top of the screen

management capabilities of John E. Davis's 

<ulink url="ftp://space.mit.edu/pub/davis/slang/">S-Lang</ulink> library.</para></sect2>

<sect2><title>Designing <literal remap="tt">newt</literal> applications</title>

<para>

As <literal remap="tt">newt</literal> is not event driven and forces modal windows (forcing window

order to behave like a stack), newt applications tend to look quite like

other text-mode programs. It is quite straightforward to convert a command

line program which uses simple user prompts into a <literal remap="tt">newt</literal> application.

Some of the programs run as part of the Red Hat installation process

(such as <literal remap="tt">Xconfigurator</literal> and <literal remap="tt">mouseconfig</literal>) were originally written

as simple terminal mode programs which used line-oriented menus to get

input from the user and were later converted into <literal remap="tt">newt</literal> applications

(through a process affectionately known as newtering). Such a conversion

does not require changes to the control flow of most applications.

Programming <literal remap="tt">newt</literal> is dramatically different from writing programs for

most other windowing systems as <literal remap="tt">newt</literal>'s API is not event driven. This

means that <literal remap="tt">newt</literal> applications look dramatically different from programs

written for event-driven architectures such as Motif, <literal remap="tt">gtk</literal>, or even

Borland's old TurboVision libraries.

When you're designing your <literal remap="tt">newt</literal> program, keep this differentiation

in mind. As long as you plan your application to call a function to

get input and then continue (rather then having your program called

when input is ready), programming with the newt libraries should be

simple.</para></sect2>

<sect2><title>Components</title>

<para>

Displayable items in <literal remap="tt">newt</literal> are known as <emphasis remap="bf">components</emphasis>, which are

analogous to the widgets provided by most Unix widget sets. There are

two main types of components in <literal remap="tt">newt</literal>, forms and everything else.

Forms logically group components into functional sets. When an application

is ready to get input from a user, it ``runs a form'', which makes the

form active and lets the user enter information into the components the

form contains. A form may contain any other component, including other

forms. Using subforms in this manner lets the application change the details

of how the user tabs between components on the form, scroll regions of the

screen, and control background colors for portions of windows.

Every component is of type <literal remap="tt">newtComponent</literal>, which is an opaque type. It's

guaranteed to be a pointer though, which lets applications move it through

void pointers if the need arises. Variables of type <literal remap="tt">newtComponent</literal> should

never be directly manipulated -- they should only be passed to <literal remap="tt">newt</literal>

functions. As <literal remap="tt">newtComponent</literal> variables are pointers, remember that

they are always passed by value -- if you pass a <literal remap="tt">newtComponent</literal> to

a function which manipulates it, that component is manipulated everywhere,

not just inside of that function (which is nearly always the behaviour

you want).</para></sect2>

<sect2><title>Conventions</title>

<para>

<literal remap="tt">Newt</literal> uses a number of conventions to make it easier for programmers

to use. 

<itemizedlist>

<listitem>

<para>

 All functions which manipulate data structures take the data

structure being modified as their first parameter. For example, all

of the functions which manipulate forms expect the <literal remap="tt">newtComponent</literal>

for that form to be the first parameter.</para></listitem>

<listitem>

<para>

 As <literal remap="tt">newt</literal> is loosely typed (forcing all of the components into

a single variable makes coding easier, but nullifies the value of type

checking), <literal remap="tt">newt</literal> functions include the name of the type they are

manipulating. An example of this is <literal remap="tt">newtFormAddComponent()</literal>, which

adds a component to a form. Note that the first parameter to this function

is a form, as the name would suggest.</para></listitem>

<listitem>

<para>

 When screen coordinates are passed into a function, the 

x location precedes the y location. To help keep this clear,

we'll use the words ``left'' and ``top'' to describe those indicators (with

left corresponding to the x position).</para></listitem>

<listitem>

<para>

 When box sizes are passed, the horizontal width precedes the vertical

width.</para></listitem>

<listitem>

<para>

 When both a screen location and a box size are being passed, the

screen location precedes the box size.</para></listitem>

<listitem>

<para>

 When any component other then a form is created, the first two

parameters are always the (left, right) location.</para></listitem>

<listitem>

<para>

 Many functions take a set of flags as the final parameter. These

flags may be logically ORed together to pass more then one flag at a time.</para></listitem>

<listitem>

<para>

 <literal remap="tt">Newt</literal> uses <emphasis remap="bf">callback</emphasis> functions to convey certain events to

the application. While callbacks differ slightly in their parameters, most

of them allow the application to specify an arbitrary argument to be passed

to the callback when the callback is invoked. This argument is always a 

<literal remap="tt">void *</literal>, which allows the application great flexibility.

</para>

</listitem>

</itemizedlist>

</para></sect2></sect1>

<sect1><title>Basic <literal remap="tt">Newt</literal> Functions</title>

<para>

While most <literal remap="tt">newt</literal> functions are concerned with widgets or groups

of widgets (called grids and forms), some parts of the <literal remap="tt">newt</literal> API

deal with more global issues, such as initializing <literal remap="tt">newt</literal> or writing

to the root window.</para>

<sect2><title>Starting and Ending <literal remap="tt">newt</literal> Services</title>

<para>

There are three functions which nearly every <literal remap="tt">newt</literal> application use. The

first two are used to initialize the system.

<screen>

int newtInit(void);

void newtCls(void);

</screen>

<literal remap="tt">newtInit()</literal> should be the first function called by every <literal remap="tt">newt</literal>

program. It initializes internal data structures and places the terminal

in raw mode. Most applications invoke <literal remap="tt">newtCls()</literal> immediately after

<literal remap="tt">newtInit()</literal>, which causes the screen to be cleared. It's not

necessary to call <literal remap="tt">newtCls()</literal> to use any of <literal remap="tt">newt</literal>'s features, but

doing so will normally give a much neater appearance.

When a <literal remap="tt">newt</literal> program is ready to exit, it should call <literal remap="tt">newtFinished()</literal>.

<screen>

int newtFinished(void);

</screen>

<literal remap="tt">newtFinished()</literal> restores the terminal to its appearance when

<literal remap="tt">newtInit()</literal> was called (if possible -- on some terminals the cursor will

be moved to the bottom, but it won't be possible to remember the original

terminal contents) and places the terminal in its original input state.

If this function isn't called, the terminal will probably need to be

reset with the <literal remap="tt">reset</literal> command before it can be used easily.</para></sect2>

<sect2><title>Handling Keyboard Input</title>

<para>

Normally, <literal remap="tt">newt</literal> programs don't read input directly from the

user. Instead, they let <literal remap="tt">newt</literal> read the input and hand it to the

program in a semi-digested form. <literal remap="tt">Newt</literal> does provide a couple of simple

functions which give programs (a bit of) control over the terminal.

<screen>

void newtWaitForKey(void);

void newtClearKeyBuffer(void);

</screen></para>

<para>

The first of these, <literal remap="tt">newtWaitForKey()</literal>, doesn't return until a key

has been pressed. The keystroke is then ignored. If a key is already in

the terminal's buffer, <literal remap="tt">newtWaitForKey()</literal> discards a keystroke and

returns immediately.

<literal remap="tt">newtClearKeyBuffer()</literal> discards the contents of the terminal's input

buffer without waiting for additional input.</para></sect2> 

<sect2><title>Drawing on the Root Window</title>

<para>

The background of the terminal's display (the part without any windows 

covering it) is known as the <emphasis remap="bf">root window</emphasis> (it's the parent of all

windows, just like the system's root directory is the parent of all 

subdirectories). Normally, applications don't use the root window, instead

drawing all of their text inside of windows (<literal remap="tt">newt</literal> doesn't require

this though -- widgets may be placed directly on the root window without

difficulty). It is often desirable to display some text, such as a

program's name or copyright information, on the root window, however.

<literal remap="tt">Newt</literal> provides two ways of displaying text on the root window. These

functions may be called at any time. They are the only <literal remap="tt">newt</literal> functions

which are meant to write outside of the current window.

<screen>

void newtDrawRootText(int left, int top, const char * text);

</screen></para>

<para>

This function is straightforward. It displays the string <literal remap="tt">text</literal> at

the position indicated. If either the <literal remap="tt">left</literal> or <literal remap="tt">top</literal> is

negative, the position is measured from the opposite side of the

screen. The final measurement will seem to be off by one though. For

example, a <literal remap="tt">top</literal> of -1 indicates the last line on the screen, and

one of -2 is the line above that.

As it's common to use the last line on the screen to display help information,

<literal remap="tt">newt</literal> includes special support for doing exactly that. The last

line on the display is known as the <emphasis remap="bf">help line</emphasis>, and is treated as a

stack. As the value of the help line normally relates to the window

currently displayed, using the same structure for window order and the

help line is very natural. Two functions are provided to manipulate the

help line.

<screen>

void newtPushHelpLine(const char * text);

void newtPopHelpLine(void);

</screen>

The first function, <literal remap="tt">newtPushHelpLine()</literal>, saves the current help line

on a stack (which is independent of the window stack) and displays the

new line. If <literal remap="tt">text</literal> is <literal remap="tt">NULL</literal>, <literal remap="tt">newt</literal>'s default help line is

displayed (which provides basic instructions on using <literal remap="tt">newt</literal>). If

<literal remap="tt">text</literal> is a string of length 0, the help line is cleared. For all

other values of <literal remap="tt">text</literal>, the passed string is displayed at the bottom,

left-hand corner of the display. The space between the end of the displayed

string the the right-hand edge of the terminal is cleared.

<literal remap="tt">newtPopHelpLine()</literal> replaces the current help line with the one it

replaced. It's important not to call tt/newtPopHelpLine()/ more then

<literal remap="tt">newtPushHelpLine()</literal>!

<literal remap="tt">Suspending Newt Applications</literal>

By default, <literal remap="tt">newt</literal> programs cannot be suspended by the user (compare

this to most Unix programs which can be suspended by pressing the suspend

key (normally <literal remap="tt">^Z</literal>).  Instead, programs can specify a <emphasis remap="bf">callback</emphasis>

function which gets invoked when the user presses the suspend key. 

<screen>

typedef void (*newtSuspendCallback)(void);

void newtSetSuspendCallback(newtSuspendCallback cb);

</screen>

The suspend function neither expects nor returns any value, and can

do whatever it likes to when it is invoked. If no suspend callback

is registered, the suspend keystroke is ignored.

If the application should suspend and continue like most user applications,

the suspend callback needs two other <literal remap="tt">newt</literal> functions.

<screen>

void newtSuspend(void);

void newtResume(void);

</screen>

<literal remap="tt">newtSuspend()</literal> tells <literal remap="tt">newt</literal> to return the terminal to its initial

state. Once this is done, the application can suspend itself (by

sending itself a <literal remap="tt">SIGTSTP</literal>, fork a child program, or do whatever

else it likes. When it wants to resume using the <literal remap="tt">newt</literal> interface,

it must call <literal remap="tt">newtResume</literal> before doing so. 

Note that suspend callbacks are not signal handlers. When <literal remap="tt">newtInit()</literal>

takes over the terminal, it disables the part of the terminal interface

which sends the suspend signal. Instead, if <literal remap="tt">newt</literal> sees the suspend

keystroke during normal input processing, it immediately calls the suspend

callback if one has been set. This means that suspending newt applications

is not asynchronous.</para></sect2>

<sect2><title>Refreshing the Screen</title>

<para>

To increase performance, S-Lang only updates the display when it needs

to, not when the program tells S-Lang to write to the terminal. ``When it

needs to'' is implemented as ``right before the we wait for the user to

press a key''. While this allows for optimized screen displays most of

the time, this optimization makes things difficult for programs which

want to display progress messages without forcing the user to input 

characters. Applications can force S-Lang to immediately update modified

portions of the screen by calling <literal remap="tt">newtRefresh</literal>.

<orderedlist>

<listitem>

<para>

The program wants to display a progress message, without forcing

for the user to enter any characters.</para></listitem>

<listitem>

<para>

A misfeature of the program causes part of the screen to be

corrupted. Ideally, the program would be fixed, but that may not 

always be practical.

</para>

</listitem></orderedlist>

</para></sect2>

<sect2><title>Other Miscellaneous Functions</title>

<para>

As always, some function defy characterization. Two of <literal remap="tt">newt</literal>'s general

function fit this oddball category.

<screen>

void newtBell(void);

void newtGetScreenSize(int * cols, int * rows);

</screen>

The first sends a beep to the terminal. Depending on the terminal's

settings, this been may or may not be audible. The second function,

<literal remap="tt">newtGetScreenSize()</literal>, fills in the passed pointers with the

current size of the terminal.</para></sect2>

<sect2><title>Basic <literal remap="tt">newt</literal> Example</title>

<para>

To help illustrate the functions presented in this section here is a short

sample <literal remap="tt">newt</literal> program which uses many of them. While it doesn't do

anything interesting, it does show the basic structure of <literal remap="tt">newt</literal> programs.

<screen>

#include <newt.h>

#include <stdlib.h>

int main(void) {

    newtInit();

    newtCls();

    newtDrawRootText(0, 0, "Some root text");

    newtDrawRootText(-25, -2, "Root text in the other corner");

    newtPushHelpLine(NULL);

    newtRefresh();

    sleep(1);

    newtPushHelpLine("A help line");

    newtRefresh();

    sleep(1);

    newtPopHelpLine();

    newtRefresh();

    sleep(1);

    newtFinished();

}

</screen></para></sect2></sect1>

<sect1><title>Windows</title>

<para>

While most <literal remap="tt">newt</literal> applications do use windows, <literal remap="tt">newt</literal>'s window

support is actually extremely limited. Windows must be destroyed in the

opposite of the order they were created, and only the topmost window may be

active. Corollaries to this are:

<itemizedlist>

<listitem>

<para>

The user may not switch between windows.</para></listitem>

<listitem>

<para>

Only the top window may be destroyed.

</para>

</listitem></itemizedlist>

While this is quite a severe limitation, adopting it greatly simplifies

both writing <literal remap="tt">newt</literal> applications and developing <literal remap="tt">newt</literal> itself, as it

separates <literal remap="tt">newt</literal> from the world of event-driven programming. However,

this tradeoff between function and simplicity may make <literal remap="tt">newt</literal>

unsuitable for some tasks.

</para>

<sect2><title>Creating Windows</title>

<para>

There are two main ways of opening <literal remap="tt">newt</literal> windows: with or without

explicit sizings. When grids (which will be introduced later in this

tutorial) are used, a window may be made to just fit the grid. When

grids are not used, explicit sizing must be given.

<screen>

int newtCenteredWindow(int width, int height, const char * title);

int newtOpenWindow(int left, int top, int width, int height, 

		   const char * title);

</screen>

The first of these functions open a centered window of the specified

size. The <literal remap="tt">title</literal> is optional -- if it is <literal remap="tt">NULL</literal>, then no title

is used. <literal remap="tt">newtOpenWindow*(</literal> is similar, but it requires a specific

location for the upper left-hand corner of the window.</para></sect2>

<sect2><title>Destroying Windows</title>

<para>

All windows are destroyed in the same manner, no matter how the windows

were originally created.

<screen>

void newtPopWindow(void);

</screen>

This function removes the top window from the display, and redraws the

display areas which the window overwrote.</para></sect2></sect1> 

<sect1><title>Components</title>

<para>

Components are the basic user interface element <literal remap="tt">newt</literal> provides. A

single component may be (for example) a listbox, push button checkbox,

a collection of other components. Most components are used to display

information in a window, provide a place for the user to enter data, or a

combination of these two functions. 

Forms, however, are a component whose primary purpose is not noticed by

the user at all. Forms are collections of components (a form may contain

another form) which logically relate the components to one another. Once

a form is created and had all of its constituent components added to it,

applications normally then run the form.  This gives control of the

application to the form, which then lets the user enter data onto the

form. When the user is done (a number of different events qualify as

``done''), the form returns control to the part of the application which

invoked it. The application may then read the information the user provided

and continue appropriately.

All <literal remap="tt">newt</literal> components are stored in a common data type, a

<literal remap="tt">newtComponent</literal> (some of the particulars of <literal remap="tt">newtComponent</literal>s have

already been mentioned. While this makes it easy for programmers to pass

components around, it does force them to make sure they don't pass

entry boxes to routines expecting push buttons, as the compiler can't

ensure that for them.

We start off with a brief introduction to forms. While not terribly

complete, this introduction is enough to let us illustrate the rest of

the components with some sample code. We'll then discuss the remainder of

the components, and end this section with a more exhaustive description of

forms.</para>

<sect2><title>Introduction to Forms</title>

<para>

As we've mentioned, forms are simply collections of components. As only one

form can be active (or running) at a time, every component which the user

should be able to access must be on the running form (or on a subform of

the running form). A form is itself a component, which means forms are

stored in <literal remap="tt">newtComponent</literal> data structures.

<screen>

newtComponent newtForm(newtComponent vertBar, const char * help, int flags);

</screen>

To create a form, call <literal remap="tt">newtForm()</literal>. The first parameter is a vertical

scrollbar which should be associated with the form. For now, that should

always be <literal remap="tt">NULL</literal> (we'll discuss how to create scrolling forms later in

this section). The second parameter, <literal remap="tt">help</literal>, is currently unused and

should always be <literal remap="tt">NULL</literal>. The <literal remap="tt">flags</literal> is normally 0, and other values

it can take will be discussed later. Now that we've waved away the

complexity of this function, creating a form boils down to simply:

<screen>

newtComponent myForm;

myForm = newtForm(NULL, NULL, 0);

</screen>

After a form is created, components need to be added to it --- after all,

an empty form isn't terribly useful. There are two functions which add

components to a form.

<screen>

void newtFormAddComponent(newtComponent form, newtComponent co);

void newtFormAddComponents(newtComponent form, ...);

</screen>

The first function, <literal remap="tt">newtFormAddComponent()</literal>, adds a single component

to the form which is passed as the first parameter. The second function

is simply a convenience function. After passing the form to

<literal remap="tt">newtFormAddComponents()</literal>, an arbitrary number of components is then

passed, followed by <literal remap="tt">NULL</literal>. Every component passed is added to the form.

Once a form has been created and components have been added to it, it's

time to run the form.

<screen>

newtComponent newtRunForm(newtComponent form);

</screen>

This function runs the form passed to it, and returns the component which

caused the form to stop running. For now, we'll ignore the return value

completely.

Notice that this function doesn't fit in with <literal remap="tt">newt</literal>'s normal

naming convention. It is an older interface which will not work for all

forms. It was left in <literal remap="tt">newt</literal> only for legacy applications. It is a

simpler interface than the new <literal remap="tt">newtFormRun()</literal> though, and is still used

quite often as a result.

When an application is done with a form, it destroys the form and

all of the components the form contains.

<screen>

void newtFormDestroy(newtComponent form);	

</screen>

This function frees the memory resources used by the form and all of the

components which have been added to the form (including those components

which are on subforms). Once a form has been destroyed, none of the form's

components can be used.</para></sect2>

<sect2><title>Components</title>

<para>

Non-form components are the most important user-interface component for

users. They determine how users interact with <literal remap="tt">newt</literal> and how information

is presented to them.</para></sect2>

<sect2><title>General Component Manipulation</title>

<para>

There are a couple of functions which work on more then one type of

components. The description of each component indicates which (if any)

of these functions are valid for that particular component.

<screen>

typedef void (*newtCallback)(newtComponent, void *);

void newtComponentAddCallback(newtComponent co, newtCallback f, void * data);

void newtComponentTakesFocus(newtComponent co, int val);

</screen>

The first registers a callback function for that component. A callback

function is a function the application provides which <literal remap="tt">newt</literal> calls for a

particular component. Exactly when (if ever) the callback is invoked

depends on the type of component the callback is attached to, and will be

discussed for the components which support callbacks.

<literal remap="tt">newtComponentTakesFocus()</literal> works on all components. It allows the

application to change which components the user is allowed to select as the

current component, and hence provide input to. Components which do not

take focus are skipped over during form traversal, but they are displayed

on the terminal. Some components should never be set to take focus, such

as those which display static text.</para></sect2>

<sect2><title>Buttons</title>

<para>

Nearly all forms contain at least one button. <literal remap="tt">Newt</literal> buttons come in two

flavors, full buttons and compact buttons. Full buttons take up quit a bit

of screen space, but look much better then the single-row compact buttons.

Other then their size, both button styles behave identically. Different

functions are used to create the two types of buttons.

<screen>

newtComponent newtButton(int left, int top, const char * text);

newtComponent newtCompactButton(int left, int top, const char * text);

</screen>

Both functions take identical parameters. The first two parameters are the

location of the upper left corner of the button, and the final parameter is

the text which should be displayed in the button (such as ``Ok'' or

``Cancel'').</para>

<sect3><title>Button Example</title>

<para>

Here is a simple example of both full and compact buttons. It also

illustrates opening and closing windows, as well a simple form.

<screen>

#include <newt.h>

#include <stdlib.h>

void main(void) {

    newtComponent form, b1, b2;

    newtInit();

    newtCls();

    newtOpenWindow(10, 5, 40, 6, "Button Sample");

    b1 = newtButton(10, 1, "Ok");

    b2 = newtCompactButton(22, 2, "Cancel");

    form = newtForm(NULL, NULL, 0);

    newtFormAddComponents(form, b1, b2, NULL);

    newtRunForm(form);

    newtFormDestroy(form);

    newtFinished();

}

</screen></para></sect3></sect2>

<sect2><title>Labels</title>

<para>

Labels are <literal remap="tt">newt</literal>'s simplest component. They display some given text and

don't allow any user input.

<screen>

newtComponent newtLabel(int left, int top, const char * text);

void newtLabelSetText(newtComponent co, const char * text);

</screen>

Creating a label is just like creating a button; just pass the location of

the label and the text it should display. Unlike buttons, labels do let the

application change the text in the label with <literal remap="tt">newtLabelSetText</literal>. When

the label's text is changed, the label automatically redraws itself. It

does not clear out any old text which may be leftover from the previous

time is was displayed, however, so be sure that the new text is at least

as long as the old text.</para></sect2>

<sect2><title>Entry Boxes</title>

<para>

Entry boxes allow the user to enter a text string into the form which the

application can later retrieve.

<screen>

typedef int (*newtEntryFilter)(newtComponent entry, void * data, int ch,

			       int cursor);

newtComponent newtEntry(int left, int top, const char * initialValue, int width,

			char ** resultPtr, int flags);

void newtEntrySet(newtComponent co, const char * value, int cursorAtEnd);

char * newtEntryGetValue(newtComponent co);

void newtEntrySetFilter(newtComponent co, newtEntryFilter filter, void * data);

</screen></para>

<para>

<literal remap="tt">newtEntry()</literal> creates a new entry box. After the location of the entry

box, the initial value for the entry box is passed, which may be <literal remap="tt">NULL</literal>

if the box should start off empty. Next, the width of the physical box is

given. This width may or may not limit the length of the string the user is

allowed to enter; that depends on the <literal remap="tt">flags</literal>. The <literal remap="tt">resultPtr</literal> must

be the address of a <literal remap="tt">char *</literal>. Until the entry box is destroyed by

<literal remap="tt">newtFormDestroy()</literal>, that <literal remap="tt">char *</literal> will point to the current value

of the entry box. It's important that applications make a copy of that

value before destroying the form if they need to use it later. The

<literal remap="tt">resultPtr</literal> may be <literal remap="tt">NULL</literal>, in which case the user must use the

<literal remap="tt">newtEntryGetValue()</literal> function to get the value of the entry box.

Entry boxes support a number of flags:

<variablelist>

<varlistentry>

<term>NEWT_ENTRY_SCROLL</term>

<listitem>

<para>If this flag is not specified, the user cannot

enter text into the entry box which is wider then the entry box itself.

This flag removes this limitation, and lets the user enter data of an

arbitrary length.</para></listitem>

</varlistentry>

<varlistentry>

<term>NEWT_FLAG_HIDDEN</term>

<listitem>

<para>If this flag is specified, the value of the entry box

is not displayed. This is useful when the application needs to read a

password, for example.</para></listitem>

</varlistentry>

<varlistentry>

<term>NEWT_FLAG_RETURNEXIT</term>

<listitem>

<para>When this flag is given, the entry box will cause

the form to stop running if the user pressed return inside of the entry

box. This can provide a nice shortcut for users.</para>

</listitem>

</varlistentry>

</variablelist>

After an entry box has been created, its contents can be set by

<literal remap="tt">newtEntrySet()</literal>. After the entry box itself, the new string to place

in the entry box is passed. The final parameter, <literal remap="tt">cursorAtEnd</literal>, controls

where the cursor will appear in the entry box. If it is zero, the cursor

remains at its present location; a nonzero value moves the cursor to the

end of the entry box's new value.

While the simplest way to find the value of an entry box is by using a

<literal remap="tt">resultPtr</literal>, doing so complicates some applications.

<literal remap="tt">newtEntryGetValue()</literal> returns a pointer to the string which the entry

box currently contains. The returned pointer may not be valid once the

user further modifies the entry box, and will not be valid after the 

entry box has been destroyed, so be sure to save its value in a more

permanent location if necessary.

Entry boxes allow applications to filter characters as they are entered.

This allows programs to ignore characters which are invalid (such as

entering a ^ in the middle of a phone number) and provide intelligent aids

to the user (such as automatically adding a '.' after the user has typed in

the first three numbers in an IP address). 

When a filter is registered through <literal remap="tt">newtEntrySetFilter()</literal>, both the

filter itself and an arbitrary <literal remap="tt">void *</literal>, which passed to the filter

whenever it is invoked, are recorded. This data pointer isn't used for any

other purpose, and may be <literal remap="tt">NULL</literal>. Entry filters take four arguments.

<orderedlist>

<listitem>

<para>

The entry box which had data entered into it</para></listitem>

<listitem>

<para>

The data pointer which was registered along with the filter</para></listitem>

<listitem>

<para>

The new character which <literal remap="tt">newt</literal> is considering inserting into the

entry box</para></listitem>

<listitem>

<para>

The current cursor position (0 is the leftmost position)

</para>

</listitem>

</orderedlist>

The filter returns 0 if the character should be ignored, or the value of

the character which should be inserted into the entry box. Filter functions

which want to do complex manipulations of the string should use

<literal remap="tt">newtEntrySet()</literal> to update the entry box and then return 0 to prevent

the new character from being inserted.

When a callback is attached to a entry box, the callback is invoked