DESIGN (xvutils) functions


LIBRARY ROUTINE

xvu_run_list_multsel_wait - display list, wait for multiple choices and acknowledgement

LIBRARY CALL

xvw_list_struct
*xvu_run_list_multsel_wait(
   char   *list[],
   size_t  size,
   char   *prompt,
   char   *label,
   int    user_defined,
   int    duplicates_ok,
   int    *num)

INPUT

OUTPUT

RETURN VALUE

An array of xvw_list_structs containing the strings and the indices of those strings describing the selections made from the list by the user. Returns NULL if the user clicks on "Cancel".

DESCRIPTION

Takes an array of strings, and uses them to create a pop-up list object. The user is allowed to select as many different strings as desired from the list; those strings are then returned to the caller with their indices in an array of xvu_list_struct's. If the user clicks on the "Cancel" button, NULL is returned.

Control is not returned to the application program until the user chooses an item from the list, or clicks on "cancel".

If the "duplicates_ok" flag is passed as FALSE, the user will only be allowed to select any given item from the list once. Selected items will be marked with a star. For example, the item "depth" would be displayed as "depth" if it had never been selected, but would be displayed as "* depth" after it was selected. A second click on the entry would cause it to be de-selected, and again it would be displayed as "depth". The array of xvu_list_struct's returned will have all unique elements; elements will appear according to the order in which selections were made by the user.

If the "duplicates_ok" flag is passed as TRUE, the user will be allowed to select any item from the list as many times as desired. Each selection from the list will cause that item to have the number in front of it incremented. For example, the item "depth" would be displayed as "depth" if it had never been selected, but "(1) depth" after the first time it was selected, and "(2) depth" after the second time it was selected. The array of xvu_list_struct's returned will have identical elements for each item that is selected multiple times. The elements of the xvu_list_struct array will appear in the order in which the items were selected by the user. For example, if the user chose "depth" twice, and then "width", and then "depth" again before clicking on "Ok", the array of xvu_list_structs returned would appear in the following order (identified by list_struct->string): depth, depth, width, depth.

If the "user_defined" flag is passed as TRUE, a string object will be created at the bottom of the list object where the user will be allowed to enter their own new value for the list. When the user hits <cr> following their newly defined list item, the new value will be added to the list, and may subsequently be selected, either once (if duplicates are not allowed), or many times (if duplicates are allowed).

ADDITIONAL INFORMATION

none

EXAMPLES

none

SIDE EFFECTS

none

RESTRICTIONS

none

MODIFICATION

none

FILES

$DESIGN/objects/library/xvutils/src/multlist.c

SEE ALSO

xvutils(3)

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.