Background

Newt 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), newt's size was immediately an issue. To help minimize its size, the following design decisions were made early in its implementation:

While newt provides a complete API, it does not handle the low-level screen drawing itself. Instead, newt is layered on top of the screen management capabilities of John E. Davis's S-Lang library.

Designing newt applications

As newt 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 newt application. Some of the programs run as part of the Red Hat installation process (such as Xconfigurator and mouseconfig) were originally written as simple terminal mode programs which used line-oriented menus to get input from the user and were later converted into newt applications (through a process affectionately known as newtering). Such a conversion does not require changes to the control flow of most applications. Programming newt is dramatically different from writing programs for most other windowing systems as newt's API is not event driven. This means that newt applications look dramatically different from programs written for event-driven architectures such as Motif, gtk, or even Borland's old TurboVision libraries. When you're designing your newt 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.

Components

Displayable items in newt are known as components, which are analogous to the widgets provided by most Unix widget sets. There are two main types of components in newt, 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 newtComponent, 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 newtComponent should never be directly manipulated -- they should only be passed to newt functions. As newtComponent variables are pointers, remember that they are always passed by value -- if you pass a newtComponent 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).

Conventions

Newt uses a number of conventions to make it easier for programmers to use.

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 newtComponent for that form to be the first parameter.

Starting and Ending newt Services

There are three functions which nearly every newt application use. The first two are used to initialize the system.

int newtInit(void);
void newtCls(void);

int newtFinished(void);

Handling Keyboard Input

Normally, newt programs don't read input directly from the user. Instead, they let newt read the input and hand it to the program in a semi-digested form. Newt does provide a couple of simple functions which give programs (a bit of) control over the terminal.

void newtWaitForKey(void);
void newtClearKeyBuffer(void);

The first of these, newtWaitForKey(), doesn't return until a key has been pressed. The keystroke is then ignored. If a key is already in the terminal's buffer, newtWaitForKey() discards a keystroke and returns immediately. newtClearKeyBuffer() discards the contents of the terminal's input buffer without waiting for additional input.

Drawing on the Root Window

The background of the terminal's display (the part without any windows covering it) is known as the root window (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 (newt 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. Newt provides two ways of displaying text on the root window. These functions may be called at any time. They are the only newt functions which are meant to write outside of the current window.

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

This function is straightforward. It displays the string text at the position indicated. If either the left or top 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 top 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, newt includes special support for doing exactly that. The last line on the display is known as the help line, 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.

void newtPushHelpLine(const char * text);
void newtPopHelpLine(void);

typedef void (*newtSuspendCallback)(void);

void newtSetSuspendCallback(newtSuspendCallback cb);

void newtSuspend(void);
void newtResume(void);

Refreshing the Screen

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 newtRefresh.

The program wants to display a progress message, without forcing for the user to enter any characters.

Other Miscellaneous Functions

As always, some function defy characterization. Two of newt's general function fit this oddball category.

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

Basic newt Example

To help illustrate the functions presented in this section here is a short sample newt program which uses many of them. While it doesn't do anything interesting, it does show the basic structure of newt programs.

#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();
}

Creating Windows

There are two main ways of opening newt 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.

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

Destroying Windows

All windows are destroyed in the same manner, no matter how the windows were originally created.

void newtPopWindow(void);

Introduction to Forms

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 newtComponent data structures.

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

newtComponent myForm;

myForm = newtForm(NULL, NULL, 0);

void newtFormAddComponent(newtComponent form, newtComponent co);
void newtFormAddComponents(newtComponent form, ...);

newtComponent newtRunForm(newtComponent form);

void newtFormDestroy(newtComponent form);	

Components

Non-form components are the most important user-interface component for users. They determine how users interact with newt and how information is presented to them.

General Component Manipulation

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.

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

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

Buttons

Nearly all forms contain at least one button. Newt 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.

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

#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();
}

Labels

Labels are newt's simplest component. They display some given text and don't allow any user input.

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

Entry Boxes

Entry boxes allow the user to enter a text string into the form which the application can later retrieve.

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);

newtEntry() creates a new entry box. After the location of the entry box, the initial value for the entry box is passed, which may be NULL 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 flags. The resultPtr must be the address of a char *. Until the entry box is destroyed by newtFormDestroy(), that char * 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 resultPtr may be NULL, in which case the user must use the newtEntryGetValue() function to get the value of the entry box. Entry boxes support a number of flags: NEWT_ENTRY_SCROLL

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.

#include <newt.h>
#include <stdlib.h>
#include <stdio.h>

void main(void) {
    newtComponent form, label, entry, button;
    char * entryValue;

    newtInit();
    newtCls();

    newtOpenWindow(10, 5, 40, 8, "Entry and Label Sample");

    label = newtLabel(1, 1, "Enter a string");
    entry = newtEntry(16, 1, "sample", 20, &entryValue, 
		      NEWT_FLAG_SCROLL | NEWT_FLAG_RETURNEXIT);
    button = newtButton(17, 3, "Ok");
    form = newtForm(NULL, NULL, 0);
    newtFormAddComponents(form, label, entry, button, NULL);

    newtRunForm(form);

    newtFinished();

    printf("Final string was: %s\n", entryValue);

    /* We cannot destroy the form until after we've used the value
       from the entry widget. */
    newtFormDestroy(form);
}

Checkboxes

Most widget sets include checkboxes which toggle between two value (checked or not checked). Newt checkboxes are more flexible. When the user presses the space bar on a checkbox, the checkbox's value changes to the next value in an arbitrary sequence (which wraps). Most checkboxes have two items in that sequence, checked or not, but newt allows an arbitrary number of value. This is useful when the user must pick from a limited number of choices. Each item in the sequence is a single character, and the sequence itself is represented as a string. The checkbox components displays the character which currently represents its value the left of a text label, and returns the same character as its current value. The default sequence for checkboxes is " *", with ' ' indicating false and '*' true.

newtComponent newtCheckbox(int left, int top, const char * text, char defValue,
			   const char * seq, char * result);
char newtCheckboxGetValue(newtComponent co);

Like most components, the position of the checkbox is the first thing passed to the function that creates one. The next parameter, text, is the text which is displayed to the right of the area which is checked. The defValue is the initial value for the checkbox, and seq is the sequence which the checkbox should go through (defValue must be in seq. seq may be NULL, in which case " *" is used. The final parameter, result, should point to a character which the checkbox should always record its current value in. If result is NULL, newtCheckboxGetValue() must be used to get the current value of the checkbox. newtCheckboxGetValue() is straightforward, returning the character in the sequence which indicates the current value of the checkbox If a callback is attached to a checkbox, the callback is invoked whenever the checkbox responds to a user's keystroke. The entry box may respond by taking focus or giving up focus, as well as by changing its current value.

Radio Buttons

Radio buttons look very similar to checkboxes. The key difference between the two is that radio buttons are grouped into sets, and exactly one radio button in that set may be turned on. If another radio button is selected, the button which was selected is automatically deselected.

newtComponent newtRadiobutton(int left, int top, const char * text, 
			      int isDefault, newtComponent prevButton);
newtComponent newtRadioGetCurrent(newtComponent setMember);

#include <newt.h>
#include <stdlib.h>
#include <stdio.h>

void main(void) {
    newtComponent form, checkbox, rb[3], button;
    char cbValue;
    int i;

    newtInit();
    newtCls();

    newtOpenWindow(10, 5, 40, 11, "Checkboxes and Radio buttons");

    checkbox = newtCheckbox(1, 1, "A checkbox", ' ', " *X", &cbValue);

    rb[0] = newtRadiobutton(1, 3, "Choice 1", 1, NULL);
    rb[1] = newtRadiobutton(1, 4, "Choice 2", 0, rb[0]);
    rb[2] = newtRadiobutton(1, 5, "Choice 3", 0, rb[1]);

    button = newtButton(1, 7, "Ok");

    form = newtForm(NULL, NULL, 0);
    newtFormAddComponent(form, checkbox);
    for (i = 0; i < 3; i++)
	newtFormAddComponent(form, rb[i]);
    newtFormAddComponent(form, button);

    newtRunForm(form);
    newtFinished();

    /* We cannot destroy the form until after we've found the current
       radio button */

    for (i = 0; i < 3; i++)
	if (newtRadioGetCurrent(rb[0]) == rb[i])
	    printf("radio button picked: %d\n", i);
    newtFormDestroy(form);

    /* But the checkbox's value is stored locally */
    printf("checkbox value: '%c'\n", cbValue);
}

Scales

It's common for programs to need to display a progress meter on the terminal while it performs some length operation (it behaves like an anesthetic). The scale component is a simple way of doing this. It displays a horizontal bar graph which the application can update as the operation continues.

newtComponent newtScale(int left, int top, int width, long long fullValue);
void newtScaleSet(newtComponent co, unsigned long long amount);

Textboxes

Textboxes display a block of text on the terminal, and is appropriate for display large amounts of text.

newtComponent newtTextbox(int left, int top, int width, int height, int flags);
void newtTextboxSetText(newtComponent co, const char * text);

char * newtReflowText(char * text, int width, int flexDown, int flexUp,
		      int * actualWidth, int * actualHeight);
newtComponent newtTextboxReflowed(int left, int top, char * text, int width,
				  int flexDown, int flexUp, int flags);
int newtTextboxGetNumLines(newtComponent co);

#include <newt.h>
#include <stdlib.h>

char message[] = "This is a pretty long message. It will be displayed "
		 "in a newt textbox, and illustrates how to construct "
		 "a textbox from arbitrary text which may not have "
		 "very good line breaks.\n\n"
		 "Notice how literal \\n characters are respected, and "
		 "may be used to force line breaks and blank lines.";

void main(void) {
    newtComponent form, text, button;

    newtInit();
    newtCls();

    text = newtTextboxReflowed(1, 1, message, 30, 5, 5, 0);
    button = newtButton(12, newtTextboxGetNumLines(text) + 2, "Ok");

    newtOpenWindow(10, 5, 37,
		   newtTextboxGetNumLines(text) + 7, "Textboxes");

    form = newtForm(NULL, NULL, 0);
    newtFormAddComponents(form, text, button, NULL);

    newtRunForm(form);
    newtFormDestroy(form);
    newtFinished();
}

Scrollbars

Scrollbars (which, currently, are always vertical in newt), may be attached to forms to let them contain more data then they have space for. While the actual process of making scrolling forms is discussed at the end of this section, we'll go ahead and introduce scrollbars now so you'll be ready.

newtComponent newtVerticalScrollbar(int left, int top, int height,
				    int normalColorset, int thumbColorset);

Listboxes

Listboxes are the most complicated components newt provides. They can allow a single selection or multiple selection, and are easy to update. Unfortunately, their API is also the least consistent of newt's components. Each entry in a listbox is a ordered pair of the text which should be displayed for that item and a key, which is a void * that uniquely identifies that listbox item. Many applications pass integers in as keys, but using arbitrary pointers makes many applications significantly easier to code.

newtComponent newtListbox(int left, int top, int height, int flags);
int newtListboxAppendEntry(newtComponent co, const char * text, 
			   const void * data);
void * newtListboxGetCurrent(newtComponent co);
void newtListboxSetWidth(newtComponent co, int width);
void newtListboxSetCurrent(newtComponent co, int num);
void newtListboxSetCurrentByKey(newtComponent co, void * key);

void newtListboxSetEntry(newtComponent co, void * key, const char * text);
int newtListboxInsertEntry(newtComponent co, const char * text, 
                           const void * data, void * key);
int newtListboxDeleteEntry(newtComponent co, void * key);
void newtListboxClear(newtComponent co);

void newtListboxClearSelection(newtComponent co);
void **newtListboxGetSelection(newtComponent co, int *numitems);
void newtListboxSelectItem(newtComponent co, const void * key,
	                   enum newtFlagsSense sense);

Advanced Forms

Forms, which tie components together, are quite important in the world of newt. While we've already discussed the basics of forms, we've omitted many of the details.

void newtFormAddHotKey(newtComponent co, int key);
void newtFormWatchFd(newtComponent form, int fd, int fdFlags);

void newtDrawForm(newtComponent form);
newtComponent newtFormGetCurrent(newtComponent co);
void newtFormSetCurrent(newtComponent co, newtComponent subco);
void newtFormRun(newtComponent co, struct newtExitStruct * es);

newtComponent newtForm(newtComponent vertBar, const char * help, int flags);
void newtFormSetBackground(newtComponent co, int color);
void newtFormSetHeight(newtComponent co, int height);
void newtFormSetWidth(newtComponent co, int width);