item(S)                        6 January 1993                        item(S)


 Name

    item - CRT menu-item routines

 Syntax


    cc  . . .  -lmenu -lcurses


    #include  <menu.h>

    ITEM *new_item(n, d)
    char *n, *d;

    int free_item(i)
    ITEM * i;

    char *item_name(i)
    ITEM * i;

    char *item_description(i)
    ITEM * i;

    int set_item_opts(i, o)
    ITEM * item;
    OPTIONS o;

    OPTIONS item_opts(i)
    ITEM * i;

    int item_opts_on(item, opts)
    ITEM * item;
    OPTIONS opts;

    int item_opts_off(item, opts)
    ITEM * item;
    OPTIONS opts;

    int set_item_value(i, c)
    ITEM * item;
    int *c;

    int item_value(i)
    ITEM * item;


    int set_item_userptr(i, n)
    ITEM * item;
    char *n;

    char *item_userptr(i)
    ITEM * i;

    int item_count(m)
    MENU *m;

    int item_visible(i)
    ITEM * item;


 Description

    These routines allow you to create, display, and access items.  Menus can
    be displayed on any display device supported by the curses(S) library.
    Once you compile a program that contains a ``#include'' statement for the
    ITEM header file menu.h, you should link it with the ITEM and curses
    library routines.

 Functions

    newitem (n, d) creates a new item with name n and description d.  It
    returns a pointer to the new item.  In general, you should store these
    item field pointers in an array.

    freeitem () frees the storage allocated for the given item.  Once an
    item is freed, you can no longer connect it to a menu.

    itemname (i) returns a pointer to the given item's name.

    itemdescription (i) returns a pointer to the given item's description.

    setitemopts (i, o) turns on the named option(s) for the item and turns
    off its remaining options, if any.  Options are boolean values.
    Currently, there is one item option O_SELECTABLE which enables your end-
    user to select the item.  The initial current default is to have
    O_SELECTABLE on for every item.

    itemopts (i) returns the given item's option(s) setting.  To set
    options, you can apply boolean operators to the value returned by
    itemopts() and let the result be the second argument to setitemopts().

    itemoptson (item, opts) turns on the named options for the item.

    itemoptsoff (item, opts) turns off the named options for the item.

    Unlike single-valued menus, multi-valued menus enable your end-user to
    select one or more items from a menu.  setitemvalue (i, c) sets the
    given item's select value--TRUE (selected) or FALSE (not selected).  To
    make a menu multi-valued, you use setmenuopts() or menuoptsoff() to
    turn off option O_ONEVALUE.  setitemvalue() may be used only with
    multi-valued menus.

    itemvalue (i) returns the select value of the given item, either TRUE
    (selected) or FALSE (unselected).

    Every item has an associated user pointer that you can use to store per-
    tinent information.  setitemuserptr (i, n) sets the item's user
    pointer.

    itemuserptr (i) returns the item's user pointer.

    itemcount (m) returns the number of items in the given menu.

    A menu item is visible if it currently appears in the subwindow of the
    posted menu to which it is connected.  If an item is visible,
    itemvisible (i) returns TRUE.  If not, it returns FALSE.

 Diagnostics

    The following values are returned by one or more routines that return an
    integer.

    EBADARGUMENT           an incorrect argument was passed to the routine

    EBADSTATE              routine called from an inappropriate routine

    ECONNECTED              one or more items are connected to another menu

    ENOMATCH               no match occurred

    ENOROOM                menu does not fit within its subwindow

    ENOTCONNECTED          no items are associated with the menu

    ENOTPOSTED             menu has not yet been posted

    ENOTSELECTABLE         item cannot be selected

    EOK                     routine returned normally

    EPOSTED                 menu is already posted

    EREQUESTDENIED         menu driver could not process the request

    ESYSTEMERROR           system error

    EUNKNOWNCOMMAND        unrecognizable request was given to the driver


 See also

    curses(S), field(S), fieldtype(S), form(S), menu(S), panel(S), tam(S)

 Standards conformance

    item is not part of any currently supported standard; it is an extension
    of AT&T System V provided by the Santa Cruz Operation.