SAS Component Language Dictionary

COLORLIST

Displays a selection list of the names of a device's valid colors and returns user selections

Category:

Selection List

Syntax
Details
Example
See Also

Syntax

selections=COLORLIST(color-set,num-sel<,message <,autoclose>>);

selections

contains one or more user selections from the list. Multiple selections are separated by blanks. By default, selections is 200 bytes long. To accommodate values longer than 200 bytes, you should explicitly declare selections with a longer length.

Type: Character

color-set

specifies the set of colors to display in the selection list:

device

specifies the name of a SAS/GRAPH device. If device is supplied, the selection list includes only the colors that are valid for the specified device, and an All... choice to display all possible colors. Device can be the name of a monitor, plotter, printer, or camera. This name can be up to eight characters long and must be specified within quotes. If the device entry is not found, the list contains all possible colors without regard to whether the device supports them.

'?'

opens the Color Selector window in which a user can design a color. Only one color can be defined, so num-sel is ignored. For additional information, use the window's online help.

Type: Character

num-sel

is the maximum number of items that a user can select from the list. To display the list for information purposes only (no selections allowed), specify 0. To specify an unlimited number of selections, use a value such as 9999 that is larger than the number of available selections. A user cannot make a number of selections that exceeds the number of items in the list.

Type: Numeric

message

is the message text to display above the selection list. The default message tells users to make up to the number of selections specified in num-sel.

Type: Character

autoclose

specifies whether the selection list window closes automatically after a user makes a selection when only one choice is allowed:

'Y'

closes the window automatically. (This is the default.)

'N'

leaves the window open until the user explicitly closes it.

This option is ignored when num-sel is not 1.

Type: Character

Details

By default, the message above the selection list asks the user to make num-sel selections. Also by default, the selection list window closes when the user makes a choice and presses ENTER if the selection list allows only one choice.

The FIND item in the selection list window enables you to specify characters that a value in the list contains. If the value is found, it is displayed as selected. If the value is not found, a message is displayed in the selection list window.

You can provide default values that will be initially selected when the color selection list is displayed. To do this, assign the values to the selections variable before calling COLORLIST.

If a user closes the selection list window without making a selection, COLORLIST returns a blank value unless there was an initial value for the selections variable before COLORLIST was called.

Selections from the window can be placed in the current result list, if one is available. The current result list is a special SCL list that is automatically filled with the values that are selected from a selection list. To use a current result list, use the MAKELIST function to create it, and use the CURLIST function to designate it as the current result list. The current result list must exist before you call the COLORLIST function.

You can use COLORLIST to enable a user to interactively design the RGB components for a color. If a user designs a color that is not supported on that device, SCL uses the closest color that is supported.

When COLORLIST is invoked, the current result list is cleared. After COLORLIST is invoked, the result list contains one element for each selected color name. The selections can be retrieved by using GETITEMC.

Example

Display a list of devices of type MONITOR that are available in the catalog SASHELP.DEVICES and allow users to select a device. Users can choose up to four colors from the selection list. If no device is chosen, display a list of all possible colors.

usrdev=devlist('sashelp.devices','monitor',
                       'Select a device. ');
device=substr(usrdev,41,8);
devcolor=colorlist(device,4);

Use a current result list to process multiple selections:

listid=makelist();
rc=curlist(listid);
selection=devlist('sashelp.devices','monitor',
                           'Select a device.');
device=substr(selection,41,8);
devcolor=colorlist(device,4);
n=listlen(listid);
do i=1 to n;
   color=getitemc(listid,i);
   put color=;
end;

Display a color selection dialog window:

color=colorlist('?',1,'Design a color for the
                                         bars');