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 provides GRASS macro writers with a  mouse  inter-
       face 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 com-
       mand 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  rectan-
	      gle 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 display 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 dis-
	      play 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 dis-
	      play 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 displayed.

       _o_p_t_i_o_n _n_a_m_e(s)
	      The  options that will appear in the menu when dis-
	      played.  Each menu option should appear on a  sepa-
	      rate  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 stan-
       dard  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 moni-
       tor.  (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 dis-
       play 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 monitor 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 point-
       ing  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 Laboratory

       _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)
