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



NNAAMMEE
       dd..llaabbeellss   -  To create/edit GRASS paint label files for display 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..llaabbeellss

DDEESSCCRRIIPPTTIIOONN
       The _d_._l_a_b_e_l_s program allows the user to interactively create and modify
       paint-labels  files for use with the _p_._m_a_p and _d_._p_a_i_n_t_._l_a_b_e_l_s programs.
       The _p_a_i_n_t _l_a_b_e_l_s files created will be stored  in  the  user's  current
       mapset under the /paint/labels directory.


       _d_._l_a_b_e_l_s  is fully interactive, and requires use of a graphics monitor.
       After the user has typed dd..llaabbeellss

       and has typed in the name of a new or existing paint-labels  file,  the
       user  is  asked	to indicate label positions on the display frame using
       the mouse-pointer, and to edit label parameters that define the label's
       size,  color,  and  other  characteristics  through use of a visual-ask
       (VASK) data entry screen.  The mouse can also be used to  indicate  the
       geographic  coordinates	of  locations  within  the  current geographic
       region in the active frame.  It is helpful to display a	relevant  data
       file  in  the  active  display frame before running _d_._l_a_b_e_l_s to provide
       visual clues for label placement.

UUSSEERR PPRROOMMPPTTSS
       You will first be prompted to enter the name of either  an  old	paint-
       labels  file  that  you wish to modify, or a new paint-labels file that
       you wish to create.  The following is the file name prompt:

       OPTION: Label text file name


       key: name

       required: YES

       enter option >

       If you enter the name of a new (non-existent)  paint-labels  file,  you
       are  asked to indicate a location falling within the current geographic
       region in the active display frame at which the label is to be  placed.


       Mouse Buttons

	      Left:    Place Label Here

	      Middle:  Where Am I ?

	      Right:   Quit

	      Once you have indicated a position, you will be presented with a
	      data-entry screen (also known as a VASK screen) so that you  can
	      enter  the paint-label parameters that define how the label will
	      appear on the display or on the color printer.  Once you	finish
	      entering	the label-parameters, and you hit the  key to proceed,
	      the label will be displayed on the  screen.   If	you  like  the
	      appearance of the label, enter "y" to the "Look OK?" prompt;  if
	      not, enter "n" and you will again be  presented  with  the  data
	      entry  screen.  Once you approve the label's appearance you will
	      be asked to indicate the position of the next label.

       If you choose to display an  already-existing  paint-labels  file,  you
       will  be  shown the labels.  You will then have the option of editing a
       label or adding more labels.

       Buttons

	      Left:    Edit Existing Labels

	      Middle:  Quit

	      Right:   Add more Labels


       On-line help is available.  If you are puzzled about what should go  in
       a  data entry field, just enter "help" in that field, hit the  key, and
       you will be presented with a short description of the  field  and  what
       you may enter.


       The  following  is  a  list  of	the different fields in the data entry
       screen and a short description of each.

       TTEEXXTT:  The user can enter up to four lines of text.

       SSKKIIPP: _y_e_s_/_n_o_.
	      If _n_o, label will  be  printed.	If  _y_e_s,  the  label  will  be
	      retained in the file but not printed.

       LLOOCCAATTIIOONN:
	      Determines  where  the text will be located.  The user specifies
	      the easting and northing in map units, and  (optionally)	speci-
	      fies  a  vertical and horizontal offset (in printer pixels) from
	      the specified easting/northing.  (The vertical (y)  offset  will
	      shift  the location to the south if positive, north if negative.
	      The horizontal (x) offset will shift the location east if  posi-
	      tive,  west  if  negative.)  These offsets are provided to allow
	      finer placement of labels.

       RREESSEETT LLOOCCAATTIIOONN: _y_e_s_/_n_o_.
	      If _y_e_s, the user will be allowed to use the mouse  to  select  a
	      new  location for the label.  The mouse buttons will function as
	      follows:


       Mouse Buttons Left:    Place Label Here Middle:	Where Am I  ?	Right:
       Quit



       PPLLAACCEEMMEENNTT:
	      Determines which part of the label to which the location refers.
	      This may be specified as:


       lower left     (lower left corner of the  text)	lower  right	(lower
       right corner of the text) lower center	(bottom center of the text)


       upper  left     (upper  left  corner of the text) upper right	(upper
       right corner of the text) upper center	(top center of the text)


       center	 (center of the text)



       TTEEXXTT SSIIZZEE:
	      Determines the size of the lettering used in  the  label.   Text
	      size  (height)  is  stated  in units of (ground) meters; e.g., a
	      text size of 500 sets the height of each line of text  equal  to
	      500  ground  meters.   Thus,  text will appear to grow or shrink
	      when displayed,  depending  on  the  user's  current  geographic
	      region settings.

       TTEEXXTT CCOOLLOORR:
	      This selects the text color.  This color can be specified in one
	      of three ways:

	      By color name:
	      aqua black blue brown cyan gray green grey indigo magenta orange
	      purple red violet white yellow

	      As red, green, blue percentages.	For example: .5 .4 .7
	      (This form is not supported by _d_._p_a_i_n_t_._l_a_b_e_l_s, but see _p_._m_a_p and
	      _p_._l_a_b_e_l_s.)

	      By printer color number, to get the exact printer color.
	      (This form is not supported by _d_._p_a_i_n_t_._l_a_b_e_l_s, but see _p_._m_a_p and
	      _p_._l_a_b_e_l_s.)

       Note.   If  the user sets the text color equal to the background color,
       the text will not appear on the graphics monitor.

       WWIIDDTTHH: This determines the line thickness of the letters.   The	normal
	      text  width  should  be set to 1.  Larger numbers can be used to
	      simulate bold face.   (_d_._p_a_i_n_t_._l_a_b_e_l_s  ignores  this  value  and
	      always uses 1.)

       HHIIGGHHLLIIGGHHTT CCOOLLOORR:
	      The  text can be highlighted in another color so that it appears
	      to be in two colors.  The text is drawn first in this color at a
	      wider line width, and then redrawn in the text color at the reg-
	      ular line width.	Highlight colors are not shown on the graphics
	      display,	they  are  only  shown in the output from _p_._l_a_b_e_l_s and
	      _p_._m_a_p.



       HHIIGGHHLLIIGGHHTT WWIIDDTTHH:
	      Specifies how far from the text lines (in pixels) the  highlight
	      color  should  extend.   Highlight  colors  are not shown on the
	      graphics display,  they  are  only  shown  in  the  output  from
	      _p_._l_a_b_e_l_s and _p_._m_a_p.

       BBAACCKKGGRROOUUNNDD CCOOLLOORR:
	      Text  may  be  boxed in a solid color by specifying a background
	      color (see TEXT COLOR above to specify a color).	 Specify  _n_o_n_e
	      to use no background.

       OOPPAAQQUUEE TTOO VVEECCTTOORRSS: _y_e_s_/_n_o.
	      This  field  only has meaning if a background color is selected.
	      _y_e_s will prevent vector lines from entering the background.   _n_o
	      will allow vector lines to enter the background.

       BBOORRDDEERR CCOOLLOORR:
	      Select  a  color	for the border around the background.  Specify
	      _n_o_n_e to suppress the border.




NNOOTTEESS
       This program is fully interactive and requires no  command  line  argu-
       ments.


       If  the	user  types the word hheellpp in a data entry field while entering
       label information, acceptable field choices will be listed.


       Labels must be placed within the current  geographic  region.   If  the
       user attempts to place a label outside of this region, the program will
       appear to loop endlessly.  It is simply	failing  to  display  a  label
       positioned  beyond the boundaries of the current region; in this event,
       the user should simply reposition the label.


       Labels created by this program are stored  in  ASCII  files  under  the
       directory $LOCATION/paint/labels.

SSEEEE AALLSSOO
       _d_._l_a_b_e_l

       _d_._p_a_i_n_t_._l_a_b_e_l_s

       _d_._r_a_s_t

       _d_._v_e_c_t

       _d_._w_h_e_r_e

       _p_._l_a_b_e_l_s

       _p_._m_a_p

AAUUTTHHOORR
       Dave Johnson,

       DBA Systems, Inc.

       _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.labels(1)
