<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>GRASS GIS: d.menu</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
<body bgcolor="white">
<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>
<h2>NAME</h2>
<em><b>d.menu</b></em> - Creates and displays a menu within the active frame on the graphics monitor.
<h2>KEYWORDS</h2>
display
<h2>SYNOPSIS</h2>
<b>d.menu</b><br>
<b>d.menu help</b><br>
<b>d.menu</b> [<b>bcolor</b>=<em>string</em>] [<b>tcolor</b>=<em>string</em>] [<b>dcolor</b>=<em>string</em>] [<b>size</b>=<em>integer</em>] [--<b>verbose</b>] [--<b>quiet</b>]
<h3>Parameters:</h3>
<DL>
<DT><b>bcolor</b>=<em>string</em></DT>
<DD>Sets the color of the menu background</DD>
<DD>Options: <em>red,orange,yellow,green,blue,indigo,violet,white,black,gray,brown,magenta,aqua,grey,cyan,purple</em></DD>
<DD>Default: <em>white</em></DD>
<DT><b>tcolor</b>=<em>string</em></DT>
<DD>Sets the color of the menu text</DD>
<DD>Options: <em>red,orange,yellow,green,blue,indigo,violet,white,black,gray,brown,magenta,aqua,grey,cyan,purple</em></DD>
<DD>Default: <em>black</em></DD>
<DT><b>dcolor</b>=<em>string</em></DT>
<DD>Sets the color dividing lines of text</DD>
<DD>Options: <em>red,orange,yellow,green,blue,indigo,violet,white,black,gray,brown,magenta,aqua,grey,cyan,purple</em></DD>
<DD>Default: <em>black</em></DD>
<DT><b>size</b>=<em>integer</em></DT>
<DD>Sets the menu text size (in percent)</DD>
<DD>Options: <em>1-100</em></DD>
<DD>Default: <em>3</em></DD>
</DL>
<H2>DESCRIPTION</H2>
<EM>d.menu</EM> 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 mouse must be used to select one of the menu
options. The number associated with the selected menu
option is then printed to standard output (<tt>stdout</tt>) and the program
exits. This program provides
GRASS macro writers with a mouse interface for user interaction.
<P>
Parameters can be stated on the command line, from within standard input
(<tt>stdin</tt>), or from within a script file
(as illustrated <A HREF="#example">below</A>).
<P>
The user can specify the menu's background, text, and line
colors (<B>bcolor</B>, <B>tcolor</B>, and
<B>dcolor</B>) and the menu size (<B>size</B>) 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 will be set (automatically) to their default values.
<h2>NOTES</h2>
<H3>Menu Information:</H3>
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 right corner of the active display frame
by default if the user does not position it elsewhere using
the <tt>.T</tt> or <tt>.L</tt> commands.
<P>
The user specifies the menu contents by entering a menu
TITLE followed by the option choices to appear in the menu
when displayed. The user <EM>must</EM> enter a menu TITLE
and at least one menu option.
All <tt>.dot</tt> commands are optional.
<DL>
<DT>
<B>#</B>
<DD>
Comment line. (ignored)
<DT>
<B>.B</B> <EM>value</EM>
<DD>
Specifies the menu's background color.
<DT>
<B>.C</B> <EM>value</EM>
<DD>
Specifies the menu's text color.
<DT>
<B>.D</B> <EM>value</EM>
<DD>
Specifies the menu's dividing line color.
<DT>
<B>.F</B> <EM>value</EM>
<DD>
Specifies the menu's font. May be any of the standard GRASS fonts.
(see <EM><A HREF="d.font.html">d.font</A></EM>)
<DT>
<B>.S</B> <EM>value</EM>
<DD>
Specifies the menu's font size.
(as a percentage of the active frame's height).
<DT>
<B>.T</B> <EM>value</EM>
<DD>
Specifies the menu's distance from the active display frame's top edge
(as a percentage of the active frame's height).
<DT>
<B>.L</B> <EM>value</EM>
<DD>
Specifies the menu's distance from the active display frame's left edge
(as a percentage of the active frame's width).
<DT>
<EM>menu TITLE</EM>
<DD>
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.
<DT>
<EM>option name</EM>(s)
<DD>
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.
</DL>
Note: The user should choose a menu size and location that will allow
all menu options to be displayed in the active frame.
<P>
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 <EM>control-d</EM> </B> to end
input and display the menu in the active frame on the
graphics monitor. (Note: The <EM>d.menu</EM> program can
also be incorporated into UNIX Bourne shell script macros.
The below example shows how this might be done.)
<A NAME="example"></a>
<H2>EXAMPLES</H2>
<h3>Example 1</h3>
<div class="code"><pre>
a=`d.menu << EOF
# set the background color
.B brown
# set the text color
.C yellow
# set the text size in % of entire screen height
.S 3
# set the top edge
.T 10
# set the LEFT edge
.L 10
# The menu Title
Sample Menu
# the options
option 1
option 2
option 3
option 4
option 5
option 6
EOF
`
echo "You have just chosen option $a"
</pre></div>
<BR>
<h3>Example 2</h3>
In the following example, the shell script <EM>menu2</EM>
calls the shell script <EM>color.select</EM> which contains
<EM>d.menu</EM> 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 <EM>menu2</EM>.
<H4>Contents of file <EM>menu2</EM>:</H4>
<div class="code"><PRE>
#! /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
</PRE></div>
<H4>Contents of file <EM>color.select</EM>:</H4>
<div class="code"><PRE>
#! /bin/csh -f
d.menu bcolor=red tcolor=green dcolor=yellow size=5 << EOF
.T 25
.L 25
Color Choices
Option 1
Option 2
Option 3
Option 4
Option 5
EOF
</PRE></div>
<P>
If the user runs <EM>menu2</EM>, 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
pointing with the mouse) one of the displayed menu
options. Here, these menu options are called
<EM>Option 1</EM>, <EM>Option 2</EM>, and
<EM>Option 3</EM>, etc. The first line of text (here,
the words <EM>Color Choices</EM>) contains the TITLE of
the menu; this line is <B>not</B> 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 <EM>menu2</EM>.
<EM>menu2</EM> is a simple example that takes this
information and only echoes it to the screen.
<H2>NOTES</H2>
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.
<H2>SEE ALSO</H2>
<EM><A HREF="d.ask.html">d.ask</A></EM><br>
<EM><A HREF="d.font.html">d.font</A></EM><br>
<EM><A HREF="d.frame.html">d.frame</A></EM><br>
<EM><A HREF="d.grid.html">d.grid</A></EM><br>
<EM><A HREF="d.legend.html">d.legend</A></EM><br>
<EM><A HREF="d.labels.html">d.paint.labels</A></EM><br>
<EM><A HREF="d.text.html">d.text</A></EM><br>
<EM><A HREF="d.title.html">d.title</A></EM><br>
<H2>AUTHOR</H2>
James Westervelt,
U.S. Army Construction Engineering
Research Laboratory
<p><i>Last changed: $Date: 2006-07-07 11:56:35 +0200 (Fri, 07 Jul 2006) $</i></p>
<HR>
<P><a href="index.html">Main index</a> - <a href="display.html">display index</a> - <a href="full_index.html">Full index</a></P>
<P>© 2003-2008 <a href="http://grass.osgeo.org">GRASS Development Team</a></p>
</body>
</html>
