<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>GRASS GIS: d.ask</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.ask</b></em> - Prompts the user to select a GRASS data base file from among files displayed in a menu on the graphics monitor.
<h2>KEYWORDS</h2>
display
<h2>SYNOPSIS</h2>
<b>d.ask</b><br>
<b>d.ask help</b><br>
<b>d.ask</b> <b>element</b>=<em>name,description</em> [<b>prompt</b>=<em>"message"</em>] [--<b>verbose</b>] [--<b>quiet</b>]
<h3>Parameters:</h3>
<DL>
<DT><b>element</b>=<em>name,description</em></DT>
<DD>Database element , one word description</DD>
<DT><b>prompt</b>=<em>"message"</em></DT>
<DD>Short user prompt message</DD>
</DL>
<H2>DESCRIPTION</H2>
<EM>d.ask</EM> is designed for shell scripts that need to prompt the user for
the name of a data base file in the user's current GRASS mapset search path.
After <EM>d.ask</EM> is invoked with needed parameters,
the mouse becomes active and a menu containing files of the specified
<EM>element</EM> type is displayed on the user's graphics monitor.
The user is prompted by the prompt "<EM>message</EM>" to select one of the
listed file names with the mouse. Specifically, the query that appears
to the user takes the form:
<P>
<DL>
<DD> <B>Double</B> click on the <EM>prompt</EM> "message"
<DD> <B>Double</B> click here to cancel
<P>
<DD> (A list of files of the specified <EM>element</EM> type from each
of the mapsets listed in the user's mapset search path is also
displayed.)
</DL>
<P>
After the user responds, the mouse is deactivated and
the displayed menu is erased from the screen
(leaving any underlying materials on display intact).
Three lines are written to standard output (the user's terminal screen):
<P>
<DL>
<DD><B>name=</B><EM>file_name</em>
<DD><B>mapset=</B><EM>mapset_name</em>
<DD><B>fullname=</B><EM>file_name@mapset_name</em>
</DL>
<P>
<H3>Parameters:</H3>
<DL>
<DT><B>element=</B><EM>name,description</em>
<DD>Name of a GRASS data base element, followed by a one word description of the
element. GRASS data base elements are mapset subdirectories; these include:
bdlg, cats, cell, cell_misc, cellhd, colr, colr2, dig, dig_ascii, dig_att,
dig_cats, dig_plus, dlg, group, hist, icons, noise, paint, site_lists, and
windows.
The <EM>description</EM> will be used to display an error message to the screen
if no files of the named element type exist in the user's mapset search path.
The prompt "<EM>message</EM>" will appear in the pop-up menu displayed on the
user's graphics monitor. The files listed in the menu will be of the
specified <EM>element</EM> type, and exist in mapsets listed in the user's
current mapset search path.
<DT><B>prompt=</B>"<EM>message</EM>"
<DD>A brief message with which the user will be prompted.
If this message contains more than one word, it should be
enclosed within double quotes ("").
It is a non-selectable message displayed in the menu bar of a pop-up menu.
Selectable items in the displayed menu include a cancel option and any of the
files in the mapset subdirectory <EM>name</EM> in the user's mapset search path.
</DL>
<H2>EXAMPLE</H2>
Given the following input,
<P>
<DL>
<DD>
<B>d.ask element=</B>cell,raster <B>prompt=</B>"raster map layer to
be used"
</DL>
<P>
<EM>d.ask</EM> will prompt the user to select a raster (cell) file from among
those listed in the "cell" directories of the mapsets listed in his current
mapset search path. A pop-up menu will be displayed on the user's graphics
monitor, containing the prompt:
<P>
<DL>
<DD> <B>Double</B> click on the <EM>raster</EM> map layer to be used
<DD> <B>Double</B> click here to cancel
</DL>
<H2>OUTPUT</H2>
If the user selects a file name from the displayed menu,
<EM>d.ask</EM> writes three lines to standard output:
<P>
<DL>
<DD> <B>name=</B><EM>file_name</EM>
<DD> <B>mapset=</B><EM>mapset_name</EM>
<DD> <B>fullname=</B><EM>file_name@mapset_name</EM>
</DL>
<P>
The output is in the form of /bin/sh commands to set the variable
<EM>name</EM>
to the file name specified by the user
(of the <EM>element</EM> type requested by <EM>d.ask</EM>), <EM>mapset</EM>
to the GRASS mapset in which this file resides, and <EM>fullname</EM>
to the name of the file and its mapset.
<P>
If the user elects not to select a file but instead chooses the
"Double click here to cancel" option,
the mouse will be deactivated and no variable assignments will be
returned to standard output.
<P>
If no files of the specified <EM>element</EM> type are found in the user's
current mapset search path, the mouse is activated and the following message
is displayed on the user's graphics monitor:
<P>
<DL>
<DD> <B>No <EM>element</EM> description files found</B>
<DD> <B>Click here to continue</B>
</DL>
<P>
<H2>NOTES</H2>
Parameter values
(the <EM>element</EM> name and description, and <EM>prompt</EM> message)
cannot be supplied to <EM>d.ask</EM> interactively;
they must be supplied on the command line or from a file.
<H2>SEE ALSO</H2>
<EM>
<A HREF="g.ask.html">g.ask</A>,<br>
<A HREF="g.filename.html">g.filename</A>,<br>
<A HREF="g.findfile.html">g.findfile</A>,<br>
<A HREF="g.gisenv.html">g.gisenv</A>,<br>
<A HREF="g.mapsets.html">g.mapsets</A>
</EM>
<H2>BUGS</H2>
This program calls other GRASS programs which may generate confusing
error messages. Example: an error message from the
program <A HREF="d.menu.html">d.menu</A>
will appear if a nonexistent map element is chosen.
<H2>AUTHOR</H2>
Michael Shapiro, U.S. Army Construction Engineering Research Laboratory
<p>
<i>Last changed: $Date: 2007-06-04 12:36:33 +0200 (Mon, 04 Jun 2007) $</i>
<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>
