@c label.texi
  
@c This file is part of the 3DLDF User and Reference Manual.
@c Copyright (C) 2003, 2004 Laurence D. Finston 
@c See the section "GNU Free Documentation License" in the file 
@c fdl.texi for copying conditions.

@c $Id: label.texi,v 1.5 2004/01/12 18:39:42 lfinsto1 Exp lfinsto1 $

@node Label Reference, Picture Reference, Transform Reference, Top
@chapter Label Reference

@tindex Label
Class @code{Label} is defined in @file{pictures.web}.
@code{Point} and @code{Picture} are @code{friends} of @code{Label}. 

Labels can be included in drawings by using the @code{label()} and
@code{dotlabel()} functions, which are currently defined for the classes
@code{Point} and @code{Path}, and the classes derived from them.
@xref{Labelling Points, , Point Reference; Labelling}, and
@xref{Labelling Paths, , Path Reference; Labelling}.
They are currently not defined for @code{Solid}, and its derived classes.  
I plan to add them for @code{Solid} soon. 

Users will normally
never need to declare objects of type @code{Label}, access its data
members or call its member functions directly.

When @code{label()} or @code{dotlabel()} is invoked, one or more @code{Labels} is
allocated dynamically and pointers to the new @code{Labels} are placed
onto the @code{vector<Label*> labels} of a @code{Picture}:
@code{current_picture}, by default.  There are no explicitly defined
constructors for @code{Label}, nor is it intended that @code{Labels}
ever be created in any way other than through @code{label()} or
@code{dotlabel()}.  When a @code{Picture} is copied, the @code{Labels} are
copied, too, and when a @code{Picture} is cleared (using
@code{Picture::clear()}) or destroyed, the @code{Labels} are deallocated
and destroyed.

@menu
* Label Data Members::          
* Copying Labels::              
* Outputting Labels::           
@end menu
 
@node Label Data Members, Copying Labels, Label Reference, Label Reference
@section Data Members

@deftypevr {Private variable} {Point*} pt
A pointer to the @code{Point} representing the location of the
@code{Label}.   
@end deftypevr

@deftypevr {Private variable} bool dot
@code{true} if the label should be dotted, otherwise
@code{false}. 

@code{dot} will be @code{false}, if the label was generated
by a call to @code{label()} with the ``@code{dot}'' argument
@code{false} (the default), @code{true}, if 
the label was generated by a call to @code{dotlabel()},
or to @code{label()} with the ``@code{dot}'' argument
@code{true}.  
@end deftypevr

@deftypevr {Private variable} string text
The text of the label.
@var{text} is always put between ``@code{btex}'' and ``@code{etex}'' in
the MetaPost code, so that @TeX{} will be used to format the labels. In
particular, this means that @TeX{}'s math mode can be used.  However,
double backslashes must be used instead of single backslashes, in order
that single backslashes be written to @code{out_stream}.  

@example
Point P(1, 1, 2);
origin.drawarrow(P);
P.label("$\\vec@{P@}$");
@end example

@iftex
@tex
\ifmakeexamples
\BEX
\BGRP
\immediate\write\examples{default_focus.set(2, 1, -10, 2, 1, 10, 10);}
\immediate\write\examples{Point P(1, 1, 2);}
\immediate\write\examples{origin.drawarrow(P);}
\immediate\write\examples{P.label("$\DBKS{vec}@OCB{}P@CCB{}$");}
\immediate\write\examples{draw_axes(gray);}
\OEX{}
\EGRP
\EEX 1
\fi
\PEX 
@end tex
@end iftex

@ifhtml
@html
<p align="center">
<br>
<img src="./graphics/png/3DLDFmp.76.png"
alt="[Figure 76. Not displayed.]"
/>
<br>
<br>
Fig. 76.
<br>
</p>
@end html
@end ifhtml

@ifinfo
[Figure 76 not displayed.]
@end ifinfo

@end deftypevr


@deftypevr {Private variable} string position
The position of the text with respect to
@code{*pt}.  Valid values are as in MetaPost:
``top'', ``bot'' (bottom), ``lft'' (left), ``rt''
(right), ``ulft'' (upper left),
``llft'' (lower left), ``urt'' (upper right),
``lrt'' (lower right).
@end deftypevr 

@deftypevr {Public static variable} bool DO_LABELS
Enables or disables creation
of @code{Labels}.  If @code{true}, @code{label}
and @code{dotlabel()} cause @code{Labels} to be
created and put onto a @code{Picture}.  If
@code{false}, they are not.  Note that it is also
possible to suppress output of existing
@code{Labels} when outputting a @code{Picture}.
@end deftypevr

@node Copying Labels, Outputting Labels, Label Data Members, Label Reference
@section Copying

@deftypefn {@code{const} Function} {Label*} get_copy (void)
Creates a copy of the @code{Label} and returns a pointer to the copy. 
Called in @code{Picture::operator=()} and @code{Picture::operator+=()}
where @code{Pictures} are copied.  
Users should never need to call this function directly.  
@xref{Picture Operators, , Picture Reference; Operators}.

This function dynamically allocates a new
@code{Label} and a new @code{Point} within the @code{Label}, and copies
the @code{strings} from @code{*this} to the new @code{Label}.  The 
standard library functions for @code{strings} take care of the
allocation for the @code{string} members of @code{Label}.  
@end deftypefn

@node Outputting Labels,  , Copying Labels, Label Reference
@section Outputting

@deftypefun void output ({const Focus&} @var{f}, {const unsigned short} @var{proj}, real @var{factor}, {const Transform&} @var{t})
Writes MetaPost code for the labels to @code{out_stream}.  
It is called in @code{Picture::output()} 
(@pxref{Outputting Pictures,,Picture Reference; Outputting}). 
Users should never need to call this function directly.  

When @code{Picture::output()} is
invoked, the MetaPost code for @code{Labels} is written to @code{out_stream}
after the code for the drawing and filling commands.  This prevents the
@code{Labels} from being covered up.  However, they can still be covered
by other @code{Labels}, or by @code{Shapes} or @code{Labels} from
subsequent invocations of @code{Picture::output()} within the same
figure (@pxref{I/O Functions}, for descriptions of @code{beginfig() and
@code{endfig()}}).   
@end deftypefun

