Ndialog is built around a collection of display objects, built into chains and fed to the MENU() function. It supports editable strings, check buttons, pushbuttons, menu lists, checklists, radio checklists, readonly text boxes, and readonly help (html subset) boxes.
To compile something with ndialog, you need to include the header file ndialog.h (if you also want to use the dialog compatability functions, you also need to include dialog.h header file.) When linking, you need to include libnd (libnd_g is the debugging version) and several other libraries, as so:
-lnd -lpanel -lncurses -lgpm
The core function of ndialog is MENU, which takes an object chain, displays it, then lets the user type input into it. Object chains are built up from objects by the function ObjChain, and are disposed of by the function deleteObjChain
The appearance of a MENU form can be slightly modified by passing a combination of the following flags to it:
MENU() has the following return codes:
Objects are created by calling one of the object constructors listed below. Once created, you can do a few things with them:
Does editing on the given object. Event is a pointer to an gpm MEVENT record, and byevent is set if there is an even pending. The way ndialog events work is that when a mouse event happens inside editObj, editObj returns eEVENT so the caller can find out where the mouse even happened, find out which object will get the event, then call that object with byevent set to true.
editObj has the following return codes:editObj may, and probably will, call drawObj to refresh fields while it is running.
The object constructers use some, or all, of the following arguments.
- x,y
- Place the object at (x,y) in the form. (x,y) is relative to the first line in the form after the prompt.
- width
- This is the width of the editable field. Any prefixes are not included in this width, nor are any fancy borders around the object.
- depth
- This is the depth of the editable field. The title is not counted in this depth, nor are any fancy borders around the object.
- prompt
- If a prompt is given, it will be drawn immediately above the editable area in the object.
- prefix
- A prefix is another type of prompt. It goes immediately to the left of the editable field, unless it contains a |, in which case it will be split into a prefix and a suffix (eg: a prefix of foo|bar will display as fooeditablebar).
- callback
- All objects support callback functions which are called when the user uses [Enter] to finish editing that object. Callback functions are passed a two void * arguments -- a pointer to the object and a pointer to display information, which can be passed to drawObj or editObj -- and return an status flag (0 if the callback failed, 1 if the callback succeeded, or -1 if the callback succeeded and wants the caller to close up shop right now.
- help
- This argument, if given, is the name of a helpfile that gives help for this object. Helpfiles are an html subset and are processed by a Help object. Helpfiles can be pathnames or filenames, though it's better to use setHelpRoot() to set the pathname instead of hardcoding it into the object.
Create a string object located at position x,y inside the window and that has a width column wide editing area.
Creates a password string object, which is exactly like a normal string object except that input is not echoed.
Creates a check object. The state of the checkable item is in bfr[0], which is a character.
Create a button object. Buttons are placed on a buttonbar at the bottom of the window, and are placed in order of their number argument (button #1 will be placed to the left of button #2, for example.) The text on the button is the label argument.
Create an OK button. An OK button is somewhat like a regular button, except that when it's pushed, and if the callback approves, MENU() will immediately return with a code of MENU_OK.
Create a Cancel button. It's exactly like an OK button, except that MENU() immediately returns with a code of MENU_CANCEL.
Create a list object. Items is an array of ListItems (defined in ndialog.h as
typedef struct { char *id; char *item; char *help; char selected; } ListItem;where the id field is the libdialog key field, and help is context-sensitive help for this ListItem.
The flags argument is a bitmap determining how the list will be displayed.
You can find out what items are selected inside the callback function by using getObjList(void* obj) to get a pointer to the array of ListItems, getObjListSize(void *obj) to get the number of items in the list, then walking the list looking for selected items.
Creates a radiolist object, which is like a list object except that only one item can be selected at a time.
Creates a menu object, which is like a list object except that it returns to the caller as soon as an item is selected.
Widgets are multipart display objects; they are manipulated exactly the same as other objects, but have wads of additional complexity tossed into them.
List widgets are made up of a string, a list, an ADD button, a DELETE button, and, optionally, a MODIFY button. They can be used for building lists of things, like, oh, dns servers, domains to search, and search order. The list they work on is a List Array object. You use the newListWidget or newEditableList functions to create a list widget.
newListWidget(x, y, width, height, list, prompt, insert callback, delete callback, dummy, help);
newEditableList(x, y, width, height, list, prompt, insert callback, delete callback, update callback, help);
A List Array is a way to encapsulate an array of ListItems. It is primarily used in widget sets, though you can use it to manage your own arrays. A List Array is called a LIA.