'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
'\" RCS: @(#) $Id: GetDash.3,v 1.5.2.1 2007/11/01 16:37:12 dgp Exp $
'\" 
.so man.macros
.TH Tk_GetDash 3 8.3 Tk "Tk Library Procedures"
.BS
.SH NAME
Tk_GetDash \- convert from string to valid dash structure.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR
.sp
int
\fBTk_GetDash\fR(\fIinterp, string, dashPtr\fR)
.SH ARGUMENTS
.AS Tk_Dash *dashPtr
.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP "const char *" string in
Textual value to be converted.
.AP Tk_Dash *dashPtr out
Points to place to store the dash pattern
value converted from \fIstring\fR.
.BE

.SH DESCRIPTION
.PP
These procedure parses the string and fills in the result in the
Tk_Dash structure. The string can be a list of integers or a
character string containing only
.QW \fB.,\-_\fR
or spaces. If all
goes well, \fBTCL_OK\fR is returned. If \fIstring\fR does not have the
proper syntax then \fBTCL_ERROR\fR is returned, an error message is left
in the interpreter's result, and nothing is stored at *\fIdashPtr\fR.
.PP
The first possible syntax is a list of integers. Each element
represents the number of pixels of a line segment. Only the odd
segments are drawn using the
.QW outline
color. The other segments are drawn transparent.
.PP
The second possible syntax is a character list containing only
5 possible characters
.QW "\fB.,\-_ \fR" .
The space can be used
to enlarge the space between other line elements, and can not
occur as the first position in the string. Some examples:
.CS
    \-dash .     = \-dash {2 4}
    \-dash \-     = \-dash {6 4}
    \-dash \-.    = \-dash {6 4 2 4}
    \-dash \-..   = \-dash {6 4 2 4 2 4}
    \-dash {. }  = \-dash {2 8}
    \-dash ,     = \-dash {4 4}
.CE
.PP
The main difference of this syntax with the previous is that it
is shape-conserving. This means that all values in the dash
list will be multiplied by the line width before display. This
assures that
.QW .
will always be displayed as a dot and
.QW \-
always as a dash regardless of the line width.
.PP
On systems where only a limited set of dash patterns, the dash
pattern will be displayed as the most close dash pattern that
is available. For example, on Windows only the first 4 of the
above examples are available. The last 2 examples will be
displayed identically as the first one.

.SH KEYWORDS
dash, conversion