X-Git-Url: https://ncurses.scripts.mit.edu/?a=blobdiff_plain;f=doc%2Fncurses-intro.doc;fp=misc%2Fncurses-intro.doc;h=669b0b391705d61925e9a8e249a7d154b6c52d9d;hb=b1f61d9f3aa244512045a6b02e759825d7049d34;hp=e45ca3530f202e642ed92549e39911dc0db0b153;hpb=0eb88fc5281804773e2a0c7a488a4452463535ce;p=ncurses.git diff --git a/misc/ncurses-intro.doc b/doc/ncurses-intro.doc similarity index 99% rename from misc/ncurses-intro.doc rename to doc/ncurses-intro.doc index e45ca353..669b0b39 100644 --- a/misc/ncurses-intro.doc +++ b/doc/ncurses-intro.doc @@ -153,7 +153,6 @@ Scope of This Document This document describes ncurses, a free implementation of the System V curses API with some clearly marked extensions. It includes the following System V curses features: - * Support for multiple screen highlights (BSD curses could only handle one `standout' highlight, usually reverse-video). * Support for line- and box-drawing using forms characters. @@ -336,14 +335,16 @@ Using the Library function names and parameters as mentioned above. Here is a sample program to motivate the discussion: - #include #include static void finish(int sig); +int main(int argc, char *argv[]) { + int num = 0; + /* initialize your non-curses data structures here */ (void) signal(SIGINT, finish); /* arrange interrupts to terminate */ @@ -352,28 +353,32 @@ main(int argc, char *argv[]) keypad(stdscr, TRUE); /* enable keyboard mapping */ (void) nonl(); /* tell curses not to do NL->CR/NL on output */ (void) cbreak(); /* take input chars one at a time, no wait for \n */ - (void) noecho(); /* don't echo input */ + (void) echo(); /* echo input - in color */ if (has_colors()) { start_color(); /* - * Simple color assignment, often all we need. + * Simple color assignment, often all we need. Color pair 0 cannot + * be redefined. This example uses the same value for the color + * pair as for the foreground color, though of course that is not + * necessary: */ - init_pair(COLOR_BLACK, COLOR_BLACK, COLOR_BLACK); - init_pair(COLOR_GREEN, COLOR_GREEN, COLOR_BLACK); - init_pair(COLOR_RED, COLOR_RED, COLOR_BLACK); - init_pair(COLOR_CYAN, COLOR_CYAN, COLOR_BLACK); - init_pair(COLOR_WHITE, COLOR_WHITE, COLOR_BLACK); - init_pair(COLOR_MAGENTA, COLOR_MAGENTA, COLOR_BLACK); - init_pair(COLOR_BLUE, COLOR_BLUE, COLOR_BLACK); - init_pair(COLOR_YELLOW, COLOR_YELLOW, COLOR_BLACK); + init_pair(1, COLOR_RED, COLOR_BLACK); + init_pair(2, COLOR_GREEN, COLOR_BLACK); + init_pair(3, COLOR_YELLOW, COLOR_BLACK); + init_pair(4, COLOR_BLUE, COLOR_BLACK); + init_pair(5, COLOR_CYAN, COLOR_BLACK); + init_pair(6, COLOR_MAGENTA, COLOR_BLACK); + init_pair(7, COLOR_WHITE, COLOR_BLACK); } for (;;) { int c = getch(); /* refresh, accept single keystroke of input */ + attrset(COLOR_PAIR(num % 8)); + num++; /* process the command keystroke */ } @@ -1137,7 +1142,6 @@ Menu Display The menu library calculates a minimum display size for your window, based on the following variables: - * The number and maximum length of the menu items * Whether the O_ROWMAJOR option is enabled * Whether display of descriptions is enabled @@ -1330,7 +1334,6 @@ Overview of Forms Creating and Freeing Fields and Forms The basic function for creating fields is new_field(): - FIELD *new_field(int height, int width, /* new field size */ int top, int left, /* upper left corner */ int offscreen, /* number of offscreen rows */ @@ -1360,7 +1363,6 @@ FIELD *new_field(int height, int width, /* new field size */ position in the field plus a NUL terminator. The sixth argument is the number of additional data buffers to allocate for the field; your application can use them for its own purposes. - FIELD *dup_field(FIELD *field, /* field to copy */ int top, int left); /* location of new copy */ @@ -1368,7 +1370,6 @@ FIELD *dup_field(FIELD *field, /* field to copy */ location. Size and buffering information are copied; some attribute flags and status bits are not (see the form_field_new(3X) for details). - FIELD *link_field(FIELD *field, /* field to copy */ int top, int left); /* location of new copy */ @@ -1390,7 +1391,6 @@ FIELD *link_field(FIELD *field, /* field to copy */ out-of-bounds arguments. To connect fields to a form, use - FORM *new_form(FIELD **fields); This function expects to see a NULL-terminated array of field @@ -1425,7 +1425,6 @@ Fetching and Changing Field Attributes Fetching Size and Location Data You can retrieve field sizes and locations through: - int field_info(FIELD *field, /* field from which to fetch */ int *height, *int width, /* field size */ int *top, int *left, /* upper left corner */ @@ -1439,7 +1438,6 @@ int field_info(FIELD *field, /* field from which to fetch */ Changing the Field Location It is possible to move a field's location on the screen: - int move_field(FIELD *field, /* field to alter */ int top, int left); /* new upper-left corner */ @@ -1449,7 +1447,6 @@ int move_field(FIELD *field, /* field to alter */ One-line fields may be unjustified, justified right, justified left, or centered. Here is how you manipulate this attribute: - int set_field_just(FIELD *field, /* field to alter */ int justmode); /* mode to set */ @@ -1469,7 +1466,6 @@ int field_just(FIELD *field); /* fetch mode of field */ This group of four field attributes controls the visual appearance of the field on the screen, without affecting in any way the data in the field buffer. - int set_field_fore(FIELD *field, /* field to alter */ chtype attr); /* attribute to set */ @@ -1586,7 +1582,6 @@ Field Status Every field has a status flag, which is set to FALSE when the field is created and TRUE when the value in field buffer 0 changes. This flag can be queried and set directly: - int set_field_status(FIELD *field, /* field to alter */ int status); /* mode to set */ @@ -1641,7 +1636,6 @@ Variable-Sized Fields Normally, a dynamic field is allowed to grow without limit. But it is possible to set an upper limit on the size of a dynamic field. You do it with this function: - int set_max_field(FIELD *field, /* field to alter (may not be NULL) */ int max_size); /* upper limit on field size */ @@ -1680,7 +1674,6 @@ Field Validation and gives you the capability to define custom ones of your own. You can examine and change field validation attributes with the following functions: - int set_field_type(FIELD *field, /* field to alter */ FIELDTYPE *ftype, /* type to associate */ ...); /* additional arguments*/ @@ -1699,7 +1692,6 @@ FIELDTYPE *field_type(FIELD *field); /* field to query */ This field type accepts alphabetic data; no blanks, no digits, no special characters (this is checked at character-entry time). It is set up with: - int set_field_type(FIELD *field, /* field to alter */ TYPE_ALPHA, /* type to associate */ int width); /* maximum width of field */ @@ -1714,7 +1706,6 @@ int set_field_type(FIELD *field, /* field to alter */ This field type accepts alphabetic data and digits; no blanks, no special characters (this is checked at character-entry time). It is set up with: - int set_field_type(FIELD *field, /* field to alter */ TYPE_ALNUM, /* type to associate */ int width); /* maximum width of field */ @@ -1729,7 +1720,6 @@ int set_field_type(FIELD *field, /* field to alter */ This type allows you to restrict a field's values to be among a specified set of string values (for example, the two-letter postal codes for U.S. states). It is set up with: - int set_field_type(FIELD *field, /* field to alter */ TYPE_ENUM, /* type to associate */ char **valuelist; /* list of possible values */ @@ -1757,7 +1747,6 @@ int set_field_type(FIELD *field, /* field to alter */ TYPE_INTEGER This field type accepts an integer. It is set up as follows: - int set_field_type(FIELD *field, /* field to alter */ TYPE_INTEGER, /* type to associate */ int padding, /* # places to zero-pad to */ @@ -1776,7 +1765,6 @@ int set_field_type(FIELD *field, /* field to alter */ TYPE_NUMERIC This field type accepts a decimal number. It is set up as follows: - int set_field_type(FIELD *field, /* field to alter */ TYPE_NUMERIC, /* type to associate */ int padding, /* # places of precision */ @@ -1798,7 +1786,6 @@ int set_field_type(FIELD *field, /* field to alter */ This field type accepts data matching a regular expression. It is set up as follows: - int set_field_type(FIELD *field, /* field to alter */ TYPE_REGEXP, /* type to associate */ char *regexp); /* expression to match */ @@ -1811,7 +1798,6 @@ Direct Field Buffer Manipulation The chief attribute of a field is its buffer contents. When a form has been completed, your application usually needs to know the state of each field buffer. You can find this out with: - char *field_buffer(FIELD *field, /* field to query */ int bufindex); /* number of buffer to query */ @@ -1846,7 +1832,6 @@ Attributes of Forms The principal attribute of a form is its field list. You can query and change this list with: - int set_form_fields(FORM *form, /* form to alter */ FIELD **fields); /* fields to connect */ @@ -1895,7 +1880,6 @@ Control of Form Display In order to declare your own frame window for a form, you'll need to know the size of the form's bounding rectangle. You can get this information with: - int scale_form(FORM *form, /* form to query */ int *rows, /* form rows */ int *cols); /* form cols */ @@ -1919,7 +1903,6 @@ WINDOW *form_sub(FORM *form); /* fetch form subwindow of form */ It is possible to check from your application whether all of a scrollable field is actually displayed within the menu subwindow. Use these functions: - int data_ahead(FORM *form); /* form to be queried */ int data_behind(FORM *form); /* form to be queried */ @@ -1933,7 +1916,6 @@ int data_behind(FORM *form); /* form to be queried */ Finally, there is a function to restore the form window's cursor to the value expected by the forms driver: - int pos_form_cursor(FORM *) /* form to be queried */ If your application changes the form window cursor, call this function @@ -1945,7 +1927,6 @@ Input Processing in the Forms Driver The function form_driver() handles virtualized input requests for form navigation, editing, and validation requests, just as menu_driver does for menus (see the section on menu input handling). - int form_driver(FORM *form, /* form to pass input to */ int request); /* form request code */ @@ -2255,7 +2236,6 @@ Field Change Hooks It is possible to set function hooks to be executed whenever the current field or form changes. Here are the functions that support this: - typedef void (*HOOK)(); /* pointer to function returning void */ int set_form_init(FORM *form, /* form to alter */ @@ -2320,7 +2300,6 @@ Field Change Commands focus for editing and viewing under control of your application, or ask which field it currently is in. The following functions help you accomplish this: - int set_current_field(FORM *form, /* form to alter */ FIELD *field); /* field to shift to */ @@ -2337,7 +2316,6 @@ int field_index(FORM *form, /* form to query */ first page. The function set_form_fields() resets this. It is also possible to move around by pages. - int set_form_page(FORM *form, /* form to alter */ int page); /* page to go to (0-origin) */ @@ -2350,7 +2328,6 @@ Form Options Like fields, forms may have control option bits. They can be changed or queried with these functions: - int set_form_opts(FORM *form, /* form to alter */ int attr); /* attribute to set */ @@ -2391,7 +2368,6 @@ Custom Validation Types The simplest way to create a custom data type is to compose it from two preexisting ones: - FIELD *link_fieldtype(FIELDTYPE *type1, FIELDTYPE *type2); @@ -2409,13 +2385,11 @@ FIELD *link_fieldtype(FIELDTYPE *type1, To create a field type from scratch, you need to specify one or both of the following things: - * A character-validation function, to check each character as it is entered. * A field-validation function to be applied on exit from the field. Here's how you do that: - typedef int (*HOOK)(); /* pointer to function returning int */ FIELDTYPE *new_fieldtype(HOOK f_validate, /* field validator */ @@ -2457,7 +2431,6 @@ int free_fieldtype(FIELDTYPE *ftype); /* type to free */ and a pointer to the pile will be passed to the validation functions. Here is how you make the association: - typedef char *(*PTRHOOK)(); /* pointer to function returning (char *) */ typedef void (*VOIDHOOK)(); /* pointer to function returning void */ @@ -2497,7 +2470,6 @@ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */ way that TYPE_ENUM is. For such types, it is possible to define successor and predecessor functions to support the REQ_NEXT_CHOICE and REQ_PREV_CHOICE requests. Here's how: - typedef int (*INTHOOK)(); /* pointer to function returning int */ int set_fieldtype_arg(FIELDTYPE *type, /* type to alter */