Components

Button Example

Here is a simple example of both full and compact buttons. It also illustrates opening and closing windows, as well a simple form.

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

Reflowing Text

When applications need to display large amounts of text, it's common not to know exactly where the linebreaks should go. While textboxes are quite willing to scroll the text, the programmer still must know what width the text will look ``best'' at (where ``best'' means most exactly rectangular; no lines much shorter or much longer then the rest). This common is especially prevalent in internationalized programs, which need to make a wide variety of message string look god on a screen. To help with this, newt provides routines to reformat text to look good. It tries different widths to figure out which one will look ``best'' to the user. As these commons are almost always used to format text for textbox components, newt makes it easy to construct a textbox with reflowed 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);

newtReflowText() reflows the text to a target width of width. The actual width of the longest line in the returned string is between width - flexDown and width + flexUp; the actual maximum line length is chosen to make the displayed check look rectangular. The ints pointed to by actualWidth and actualHeight are set to the width of the longest line and the number of lines in in the returned text, respectively. Either one may be NULL. The return value points to the reflowed text, and is allocated through malloc(). When the reflowed text is being placed in a textbox it may be easier to use newtTextboxReflowed(), which creates a textbox, reflows the text, and places the reflowed text in the listbox. It's parameters consist of the position of the final textbox, the width and flex values for the text (which are identical to the parameters passed to newtReflowText(), and the flags for the textbox (which are the same as the flags for newtTextbox(). This function does not let you limit the height of the textbox, however, making limiting it's use to constructing textboxes which don't need to scroll. To find out how tall the textbox created by newtTextboxReflowed() is, use newtTextboxGetNumLines(), which returns the number of lines in the textbox. For textboxes created by newtTextboxReflowed(), this is always the same as the height of the textbox. Here's a simple program which uses a textbox to display a message.

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

Basic Listboxes

Let's start off by looking at the most important listbox functions.

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

A listbox is created at a certain position and a given height. The height is used for two things. First of all, it is the minimum height the listbox will use. If there are less items in the listbox then the height, suggests the listbox will still take up that minimum amount of space. Secondly, if the listbox is set to be scrollable (by setting the NEWT_FLAG_SCROLL flag, the height is also the maximum height of the listbox. If the listbox may not scroll, it increases its height to display all of its items. The following flags may be used when creating a listbox:

Once a listbox has been created, items are added to it by invoking newtListboxAppendEntry(), which adds new items to the end of the list. In addition to the listbox component, newtListboxAppendEntry() needs both elements of the (text, key) ordered pair. For lists which only allow a single selection, newtListboxGetCurrent() should be used to find out which listbox item is currently selected. It returns the key of the currently selected item. Normally, a listbox is as wide as its widest element, plus space for a scrollbar if the listbox is supposed to have one. To make the listbox any larger then that, use newtListboxSetWidth(), which overrides the natural list of the listbox. Once the width has been set, it's fixed. The listbox will no longer grow to accommodate new entries, so bad things may happen! An application can change the current position of the listbox (where the selection bar is displayed) by calling newtListboxSetCurrent() or newtListboxSetCurrentByKey(). The first sets the current position to the entry number which is passed as the second argument, with 0 indicating the first entry. newtListboxSetCurrentByKey() sets the current position to the entry whose key is passed into the function.

Manipulating Listbox Contents

While the contents of many listboxes never need to change, some applications need to change the contents of listboxes regularly. Newt includes complete support for updating listboxes. These new functions are in addition to newtListboxAppendEntry(), which was already discussed.

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

The first of these, newtListboxSetEntry(), updates the text for a key which is already in the listbox. The key specifies which listbox entry should be modified, and text becomes the new text for that entry in the listbox. newtListboxInsertEntry() inserts a new listbox entry after an already existing entry, which is specified by the key parameter. The text and data parameters specify the new entry which should be added. Already-existing entries are removed from a listbox with newtListboxDeleteEntry(). It removes the listbox entry with the specified key. If you want to remove all of the entries from a listbox, use newtListboxClear().

Multiple Selections

When a listbox is created with NEWT_FLAG_MULTIPLE, the user can select multiple items from the list. When this option is used, a different set of functions must be used to manipulate the listbox selection.

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

Exiting From Forms

Forms return control to the application for a number of reasons:

• A component can force the form to exit. Buttons do this whenever they are pushed, and other components exit when NEWT_FLAG_RETURNEXIT has been specified.

• Applications can setup hot keys which cause the form to exit when they are pressed.

• Newt can exit when file descriptors are ready to be read or ready to be written to.

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