d.menu(1)		      Grass User's Manual		     d.menu(1)



NNAAMMEE
       dd..mmeennuu  -  Creates  and	displays a menu within the active frame on the
       graphics monitor.
       _(_G_R_A_S_S _D_i_s_p_l_a_y _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       dd..mmeennuu
       dd..mmeennuu hheellpp
       dd..mmeennuu [bbccoolloorr==_n_a_m_e] [ttccoolloorr==_n_a_m_e] [ddccoolloorr==_n_a_m_e] [ssiizzee==_v_a_l_u_e]

DDEESSCCRRIIPPTTIIOONN
       _d_._m_e_n_u allows the user to create a menu containing a TITLE and options,
       and  to	display this menu in the active frame on the graphics monitor.
       After the menu is displayed in the active frame,  the  pointing	device
       (mouse)	is  activated  and  must  be  used  to	select one of the menu
       options.  The number associated with the selected menu option  is  then
       printed	to  standard  output and the program exits.  This program pro-
       vides GRASS macro writers with a mouse interface for users.


       Parameters can be stated on the	command  line,	from  within  standard
       input, or (as illustrated in EXAMPLE) from within a script file.


       The  user  can  specify	the  menu's  background, text, and line colors
       (bbccoolloorr, ttccoolloorr, and ddccoolloorr) and the menu size (ssiizzee)  on  the  command
       line.  If  the  user  sets  at least one of these values on the command
       line, any remaining values that are not specified on the  command  line
       will  be  set  (automatically)  to  their  default  values (see below).
       Alternately, the user can simply type dd..mmeennuu on the  command  line;  in
       this  case,  the  program  will prompt the user for the menu colors and
       text size using the standard GRASS parser  interface.   The  user  will
       then  be  (silently) prompted to enter the menu's location and contents
       through standard input (see Menu Information, below).



   PPaarraammeetteerrss::
       bbccoolloorr==_n_a_m_e
	      Sets the color of the menu background (the  rectangle  on  which
	      the text sits).
	      Options:	red,  orange,  yellow,	green,	blue,  indigo, violet,
	      magenta, brown, gray, white, and black.
	      Default: _b_l_a_c_k

       ttccoolloorr==_n_a_m_e
	      Sets the color of the menu text.
	      Options: Same as those for _b_c_o_l_o_r.
	      Default: _w_h_i_t_e

       ddccoolloorr==_n_a_m_e
	      Sets the line color used to divide text lines in the menu.
	      Options: Same as those for _b_c_o_l_o_r.
	      Default: _w_h_i_t_e

       ssiizzee==_v_a_l_u_e
	      Sets the menu's text size to  the  specified  value.  Sizes  are
	      stated  as percentages of the height of the active graphics dis-
	      play frame.
	      Options: 1 - 100
	      Default: 3 (i.e., 3%)


   MMeennuu IInnffoorrmmaattiioonn::
       After the user has (optionally) specified menu  colors  and  size,  the
       program expects the user to enter information about the menu's location
       and content.  The menu will be placed in the lower left corner  of  the
       active  display frame by default if the user does not position it else-
       where using the .T or .L commands.


       The user specifies the menu contents by typing in a menu TITLE followed
       by  the	option choices to appear in the menu when displayed.  The user
       _m_u_s_t enter a menu TITLE and at least one menu option.

       ..TT _v_a_l_u_e
	      Specifies the menu's distance from the  active  display  frame's
	      top edge (as a percentage of the active frame's height).
	      Note: Not required

       ..LL _v_a_l_u_e
	      Specifies  the  menu's  distance from the active display frame's
	      left edge (as a percentage of the active frame's width).
	      Note: Not required

       _m_e_n_u _T_I_T_L_E
	      A TITLE that describes the type of options listed in  the  menu,
	      and  that  will  appear  at  the top of the menu when it is dis-
	      played.

       _o_p_t_i_o_n _n_a_m_e(s)
	      The options that will appear in the menu when  displayed.   Each
	      menu  option  should  appear  on	a separate line.  The user may
	      enter as many options as desired, but must enter	at  least  one
	      menu option.

       Note:  The  user should choose a menu size and location that will allow
       all menu options to be displayed in the active frame.


       If the user enters the menu TITLE and  option(s)  from  standard  input
       (i.e.,  at the keyboard rather than from a file), the user should enter
       _c_o_n_t_r_o_l_-_d  to end input and display the menu in the active frame on the
       graphics  monitor.   (Note: The _d_._m_e_n_u program can also be incorporated
       into UNIX Bourne shell script macros.  The below example shows how this
       might be done.)

EEXXAAMMPPLLEE
       In the following example, the shell script _m_e_n_u_2 calls the shell script
       _c_o_l_o_r_._s_e_l_e_c_t which contains _d_._m_e_n_u commands to display a  menu  in  the
       current	frame  on  the	graphics  monitor.   After the user selects an
       option from the display menu, the selection number is available for use
       by _m_e_n_u_2.

   CCoonntteennttss ooff ffiillee _m_e_n_u_2:
       #! /bin/csh -f
       set option = 0
       set colors = (red green blue black white )
       @ option = `color.select`

       if ($option <= 5) then
	    set color = $colors[$option]
	    echo $color

       endif
       exit


   CCoonntteennttss ooff ffiillee _c_o_l_o_r_._s_e_l_e_c_t:
       #! /bin/csh -f
       d.menu bcolor=red tcolor=green dcolor=yellow size=5 << EOF
       Color Choices
       Option 1
       Option 2
       Option 3
       Option 4
       Option 5
       EOF



       If  the user runs _m_e_n_u_2, a menu will be displayed on the graphics moni-
       tor that has red background, green text, with menu options  divided  by
       yellow lines, and a text size of 5% of the active display frame height.
       The mouse cursor will become active, allowing the user  to  select  (by
       pointing  with  the  mouse)  one  of the displayed menu options.  Here,
       these menu options are called _O_p_t_i_o_n _1, _O_p_t_i_o_n _2, and  _O_p_t_i_o_n  _3,  etc.
       The  first  line  of  text (here, the words _C_o_l_o_r _C_h_o_i_c_e_s) contains the
       TITLE of the menu; this line is nnoott a menu option that can be chosen by
       the user with the mouse. When the user presses one of the mouse buttons
       while pointing to the desired menu choice, the  number  of  the	option
       chosen  will be available for capture by the shell script _m_e_n_u_2.  _m_e_n_u_2
       is a simple example that takes this information and only echoes	it  to
       the screen.

NNOOTTEESS
       Although  the user can vary text size, all text within the same menu is
       displayed in a single text size (and font). If the user specifies  that
       items  included in the menu's text be displayed in different sizes, all
       text will be displayed in the size stated last.

SSEEEE AALLSSOO
       _d_._d_i_s_p_l_a_y

       _d_._f_o_n_t

       _d_._f_r_a_m_e

       _d_._g_r_i_d

       _d_._l_a_b_e_l

       _d_._l_e_g_e_n_d

       _d_._p_a_i_n_t_._l_a_b_e_l_s

       _d_._t_e_x_t

       _d_._t_i_t_l_e

       _s_h_o_w_._f_o_n_t_s_._s_h

       _p_a_r_s_e_r

AAUUTTHHOORR
       James Westervelt, U.S. Army Construction Engineering  Research  Labora-
       tory

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_3 _$



GRASS 5.0							     d.menu(1)
