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 cre-
       ate  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  cre-
       ated 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 fin-
	      ish 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 appear-
	      ance 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) specifies  a  vertical  and
	      horizontal  offset  (in  printer	pixels)  from the
	      specified easting/northing.  (The vertical (y) off-
	      set  will  shift the location to the south if posi-
	      tive, north if negative.	The horizontal (x) offset
	      will  shift  the location east if positive, 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  cen-
       ter   (bottom center of the text)


       upper  left     (upper  left  corner  of  the  text) upper
       right	(upper right  corner  of  the  text)  upper  cen-
       ter   (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 back-
       ground 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  regular
	      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  col-
	      ors 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 back-
	      ground.  Specify _n_o_n_e to suppress the border.




NNOOTTEESS
       This program is fully interactive and requires no  command
       line arguments.


       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)
