'\"
'\" 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.
'\"
.TH Tk_GetDash 3 8.3 Tk "Tk Library Procedures"
.so man.macros
.BS
.SH NAME
Tk_GetDash \- convert from string to valid dash structure.
.SH SYNOPSIS
.nf
\fB#include <tk.h>\fR

int
\fBTk_GetDash\fR(\fIinterp, string, dashPtr\fR)
.fi
.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. Must not be NULL.
.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
and spaces. If all
goes well, \fBTCL_OK\fR is returned and a dash descriptor is stored
in the variable pointed to by \fIdashPtr\fR.
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 in the first position of the string. Some examples:
.PP
.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 between this syntax and the numeric 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
ensures 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 to the first one.
.SH "SEE ALSO"
canvas(n), Tk_CreateItemType(3)
.SH KEYWORDS
dash, conversion