SAS Component Language Dictionary

LEGEND

Displays a legend window or refreshes the current LEGEND window

Category:

Legend

Syntax
Details
Example
See Also

Syntax

CALL LEGEND(<window-name<,back-color
<,border-color<,border-attr>>>>);

window-name

is the name that is displayed in the window border. Once assigned, a window name is displayed on subsequent legend windows until it is changed by another LEGEND routine that assigns a different name or that assigns a null string ('') to delete the name from the current legend window.

Type: Character

back-color

is a background color name, or '' for the default color. Available colors are BLACK, BLUE, BROWN, CYAN, GRAY, GREEN, MAGENTA, ORANGE, PINK, RED, WHITE, and YELLOW. SASCOLOR window elements can also be used.

The default background color is the SASCOLOR window element "Secondary Background."

Type: Character

border-color

is a border color name, or '' for the default color. Available colors are listed under back-color. SASCOLOR window elements can also be used for border-color.

The default border color is the SASCOLOR window element "Secondary Border."

Type: Character

border-attr

is a border attribute, or '' for the default attribute. Attributes are NONE, BLINKING, HIGHLIGHT, HIREV, REVERSE, and UNDERLINE. If you specify a SASCOLOR window element for border-color, then border-attr is ignored, because the SASCOLOR window element contains a display attribute.

The default border attribute is the SASCOLOR window element "Secondary Border".

Type: Character

Details

The LEGEND routine displays legend text that has been previously specified with the PUTLEGEND routine. You can specify any combination of optional arguments for LEGEND.

By default, the LEGEND window has the following characteristics:

The window occupies rows 1 through 6 and columns 1 through the width of the display device.
The window name is either the name that was specified by the last LEGEND routine or the name of the current legend window.

Before invoking the LEGEND routine, you may need to resize the associated application window so that it does not obscure the LEGEND window. To do this, either use the WDEF routine or assign a new size to the window.

Additionally, you can specify a size for a legend window by using the WREGION routine before calling the legend.

Example

Suppose you have two FRAME entries, X and Y. Assume that X.FRAME contains two pushbuttons named PUSHPOP and ENDLGND, and that X.SCL contains the corresponding control labels. When the PUSHPOP button is activated, the PUSHLEGEND call will save X's legend, and the Y.FRAME will be displayed. Y will then set up and display its own legend. After the return from Y, the POPLEGEND call will restore X's legend.

If the ENDLGND button is activated, ENDLEGEND will close the LEGEND window, and the application window will be restored to its original size.

X.SCL contains the following program:

INIT:
      /* Get the number of rows and columns for later */
      /* use.                                     */
   nr = winfo('numrows');
   nc = winfo('numcols');
      /* Resize the application window to */
      /* start at row 10. */
   call wdef(10, 1, nr-9, nc);

      /* Set the size of the LEGEND window - row 1  */
      /* through row 9.  Pass a null string */
      /* as the fifth parameter to indicate */
      /* that the LEGEND window has no      */
      /* command area.                      */
   call wregion(1, 1, 9, nc, '');

      /* Set up the legend text and display it. */
   call putlegend(1,'This is line one of the legend for X',
                  'yellow','none');
   call putlegend(2,'This is line two of the legend for X', 
                  'yellow','none');
   call legend('Sample LEGEND Window for X',
               'gray','blue');
return;

MAIN:
return;

   /* PUSHPOP label.  If this is executed, */
   /* we'll save the current  */
   /* legend and call y, */
   /* which will display its own legend. */
PUSHPOP:

      /* Push and call. */
   call pushlegend();
   call display('y.frame');

      /* Restore the original legend. */
   call poplegend();
return;

   /* ENDLGND label. If this is executed,    */
   /* the LEGEND window will be              */
   /* closed, and the application window     */
   /* will be restored to its original size. */
ENDLGND:
   call endlegend();
   call wdef(1, 1, nr, nc);
return;

TERM:
return;

Y.SCL contains the following program:

INIT:
      /* Set up and display Y's own */
      /* LEGEND window. */
   nr = winfo('numrows');
   nc = winfo('numcols');
   call wdef(10, 1, nr-9, nc);
   call wregion(1, 1, 9, nc, '');
   call putlegend(1,'This is line one of the legend for Y',
                  'yellow', 'none');
   call putlegend(2,'This is line two of the legend for Y',
                  'yellow', 'none');
   call legend('Sample LEGEND Window for Y',
               'gray', 'blue');
return;
MAIN:
TERM:
return;