gandi(3) - Linux man page
Name
GANDI - Gathering of Additional Ncurses Development ImplementsSynopsis
#include <gandi_core.h>Description
To avert a possible misinterpertation it must be said that GANDI cannot replace ncurses and this is definetly not its aim. Ncurses contains many capabilities you will never (as far as I can imagine) find in GANDI. GANDI is to be a small and fast system. It is intended to solve common problems of programming in conjunction with ncurses. But GANDI is not intended as X in a text console, although its UI is similiar.
A program using GANDI must be linked with the -lgandi_core option and some others depending on what capabilities it requires. And do not forget that GANDI uses ncurses hence always add -lpanel and -lncurses options too.
The Essentials of the GANDI System
You create a general UI image with widgets (they are a part of GANDI) and call GANDI_driver to bring them to life. The rest is your program.Each widget must be registrated in the system (it is applied automatically) thus it becomes a GANDIW_widget. Then you create it either as a core subject or as widget itself (acording to the desired effect). In the first case you use core routines (from gandi_core) in the other - routines defined for this particular widget (from its own library). In most cases you do not have to directly call core functions, there are high-level bindings for this (unless you write a curse widget yourself ).
Routine and Argument Names
GANDI contains a number of libraries and it is necessary to make name accomodations. The identifier name must begin with the library name which provides it. And libraries are named specifically too. If a library contains a widget its name will begin with gandiw_, otherwise with gandi_. Within a library the first word in the name consists of capital letters only, e.g. GANDIW_. In most cases distinct words in one identifier name are separated (like in GANDI_resize_widget) but it is not a strict rule (e.g. GANDI_activateNwidget).Coordinates are always in the form (int y; int x), and size - (int line; int column). If a function requires both of these properties, size usually follows after the coordinates.
Library Name Index
The following table lists common GANDI libraries and contains a brief description.| Library Name | Man Page | Brief Description |
| Core | gandi_core(3gandi) | Core provides an API |
| and widget capability. | ||
| Widget Manager | gandi_wm(3gandi) | Some features for |
| widget managment. |
The next sheet contains standard GANDI widgets and their description.
| Widget Name | Man Page | Brief Description |
| Button Group | button_group(3gandi) | Controls all accredited buttons. |
| Check Box | check_box(3gandi) | Like radio button, but displays |
| another bullet column and | ||
| supports tristate mode. | ||
| Combo Box | combo_box(3gandi) | A slipping list box. |
| List Box | list_box(3gandi) | Container of character strings. |
| Supports their selection. | ||
| Push Button | push_button(3gandi) | Calls determined function on |
| RETURN key. In a toggle mode has | ||
| two states. | ||
| Radio Button | radio_button(3gandi) | Displays a text and acts as |
| a switch. | ||
| Scroll Bar | scroll_bar(3gandi) | A line for scrolling. |
| Scroll Box | scroll_box(3gandi) | Controls two scroll bars and panel |
| they scrolls. | ||
| Text Edit | text_edit(3gandi) | For displaying, navigation and |
| changing text. Supports colors. | ||
| Text Label | text_label(3gandi) | Displays text. |
Widget Name Agreements.
Aside from the main name requirements there are some special ones for widgets. First a widget must be created. No widget can avoid this. Thus the make function is common for all GANDI widgets. So that is the first requirement - each widget has to have a make function named _make (preceding letters you may get considering the Routine and Argument Names section above). E.g. you may create a text label with GANDIW_text_label_make function. Also widgets often support _kill and _driver functions. But the core functions provide GANDI_kill_emptywidget and standard system driver which recognizes some system keys (you may turn them off if it's desirable). They can replace the widget's own routines.Widget Make Function.
This function looks like this:GANDIW_widget *GANDIW_widget_make(int nlines, int cols, int by, int bx, void *parent, ...)
There are:
| nlines, ncols | size; |
| by, bx | coordinates; |
| parent | if it's not-NULL parent the widget will have this in its |
| own children list; the core will cooperate them on move, | |
| hide, etc.; | |
| ... | some specifics for widget arguments (e.g. caption). |
GANDIW_widget here is a widget's main structure. Thus a push button widget has GANDIW_push_button structure.
Widget Main Structure
Almost all functions from the widget library (except _make) require a pointer to this structure as the first argument. Each structure without exception has the first field of GANDIW_widget * type. It is a common widget structure. GANDI core only works with it, by getting widget's main structure itself (except GANDI_registrate_widget and GANDI_unregistrate_widget, but there is no need to use them strictly)!Return Value
Each int function returns OK or ERR if there is no explicit requirement for another result (such in GANDI_countchild which returns the number of children). If a function returns a pointer (e.g. _make) it returns NULL on failure and something else otherwise. It's the same for char * routines as well.Files
Two directories:$PREFIX/lib/GANDI
$PREFIX/include/GANDI
contain GANDI libraries and includes accordingly ($PREFIX is where GANDI is installed).
Notes
- <gandi_core.h>
- includes <panel.h>
- <gandi_wm.h>
- includes <gandi_core.h>
Each widget has to include <gandi_core.h> and <gandi_wm.h> is left as a programmist option.
