Tk_GetDash

Section: Tk Library Procedures (3)
Updated: 8.3
Page Index

NAME

Tk_GetDash - convert from string to valid dash structure.

SYNOPSIS

#include <tk.h>

int
Tk_GetDash(interp, string, dashPtr)

ARGUMENTS

Tcl_Interp *interp (in) Interpreter to use for error reporting.

const char *string (in) Textual value to be converted.

Tk_Dash *dashPtr (out) Points to place to store the dash pattern value converted from string. Must not be NULL.

DESCRIPTION

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 ``.,-_'' and spaces. If all goes well, TCL_OK is returned and a dash descriptor is stored in the variable pointed to by dashPtr. If string does not have the proper syntax then TCL_ERROR is returned, an error message is left in the interpreter's result, and nothing is stored at *dashPtr.

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 ``outline'' color. The other segments are drawn transparent.

The second possible syntax is a character list containing only 5 possible characters ``.,-_ ''. 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:


    -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}

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 ``.'' will always be displayed as a dot and ``-'' always as a dash regardless of the line width.

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.

KEYWORDS

dash, conversion