Set_Line_Pattern

Functions

void Set_Line_Pattern (const char *pattern)
 Applies a pattern of dashes and dots to lines and polylines. More...
 
void UnSet_Line_Pattern (void)
 Removes all settings established by a previous call to Set_Line_Pattern(). More...
 

Detailed Description

Function Documentation

◆ Set_Line_Pattern()

void Set_Line_Pattern ( const char *  pattern)

Applies a pattern of dashes and dots to lines and polylines.

Parameters
pattern- Special constant (see below.)

DETAILS

Declares, changes, or removes a value for the Line Pattern attribute. You would do this when you wanted to make one collection of lines look different from another on the screen.

The pattern string syntax is

"[start cap token][end cap token]pattern_name[segment cap token][join token]"

where the bracketed items are optional.

Here are some examples:

HC_Set_Line_Pattern("mypattern");
HC_Set_Line_Pattern("[(mypattern@>");
HC_Set_Line_Pattern("|...fine#");

In addition to whatever line styles may have been defined with Define_Line_Pattern(), the possible values for pattern are as follows:

-------------------------------------------------------------
"---"       A solid line.                                      
"- -"       A simple dashed line.                              
"..."       A dotted line.                                     
"-."        Dashes and dots alternating.                       
"-.."       Dashes and double-dot alternating.                 
"-..."      Dashes and triple-dot alternating.                 
"-- --"     Long dashes.                                       
"center"    Very-long-dash and short-dash alternating.         
"phantom"   Very-long-dash and double-short-dash alternating. 
"...fine"   A very fine dotted line.
"finedot"   Same as "...fine".
 
-------------------------------------------------------------

By adding a prefix to pattern, Set_Line_Pattern() allows the user to specify the start- and end-cap style of thick lines (when the line weight is > 1.0). Legal prefixes for pattern include the following:

-------------------------------------------------------------
"|" (vertical bar)         A "butt" line cap.
"[" (left square bracket)  A "square" line cap.
"(" (left parenthesis)     A "round" line cap.
"<" (left angle bracket)   A "mitre" line cap
-------------------------------------------------------------

The pattern can consist of any two of these prefixes, where the first prefix is the start-cap and the second is the end-cap style. If only one prefix is set, then it is assumed that the start- and end-caps are the same. The default end-cap style is "|" (butt).

By specifying a suffix, caps can be applied to the ends of each line segment within a non-solid line pattern. In addition, suffixes can be used to control the way line segments are joined when thick polylines are used. Legal suffixes for pattern include:

-------------------------------------------------------------
"#" square (hash symbol)          A "square" segment cap.
"^" pointy (carat symbol)         A "mitre" segment cap.
"@" round  ("at" symbol)          A "round" line segment cap.
">" mitre  (right angle bracket)  A "mitre" line join.
"]" bevel  (right square bracket) A "bevel" line join.
")" round  (right parenthesis)    A "round" line join.
-------------------------------------------------------------

By default no line segment caps are applied to non-solid patterns.

Set applies the pattern to the currently open segment; QSet applies it to the named segment(s); UnSet removes any previous value from the currently open segment; and QUnSet removes the value from the named segment(s). On a Set or QSet, any previous value is discarded.
Line Pattern only applies to lines generated by an Insert_Line() , an Insert_Polyline() , or an Insert_Ink() sequence. There is a separate method of adjusting the lines that represent the edges of filled objects.
The precise length of the pattern as it finally appears on the screen depends on the display device at hand. This is true whether the pattern scales itself up or down appropriately as the view being represented changes, or whether, on a Polyline, the pattern continues without interruption around the corners, or whether the tail end of the line is marked by "backtracking" and coloring it in even if the pattern is blank at that point.

NOTES

The system tries to be forgiving about which way the patterns are spelled, repeated, or rotated—for example, "- - -", "- - - -", and "- " are all equivalent to "- -", and ".-..-." is equivalent to "-..".
Line cap and join attributes are device specific when applied to patterned lines. Some devices apply the cap attributes to each portion of the line. In other words, each dash of a dashed line might have round caps at both ends.

Lines may be turned off entirely with Set_Visibility() .

Beginning with v21, the DX11 and OpenGL2 drivers can hardware accelerate some line patterns when the following conditions are met:

  • You are using the DX11 or OpenGL2 driver
  • You are using Visualize 2015 or later
  • Segment-level display lists are enabled
  • The line weight is 1

The line patterns that can be accelerated are:

  • "- -" A simple dashed line.
  • "..." A dotted line.
  • "-." Dashes and dots alternating.
  • "-.." Dashes and double-dot alternating.
  • "-..." Dashes and triple-dot alternating.
  • "-- --" Long dashes.
  • "...fine" A very fine dotted line.
  • "finedot" Same as "...fine".

Custom patterns which can be represented as 16 or 32 bits for the on/off values (beginning with "dash" and alternating "blank" and "dash" afterwards) are also hardware accelerated. Note that "center" and "phantom" can not be hardware accelerated. Note that the pattern does not continue along adjacent edges. The pattern is restarted for each edge.

The "-.-" "-..-" "-...-" and "phantom" line patterns can be drawn more quickly with the OpenGL driver (but with some minor visual differences) with the following code, which matches the pre-12.00 behavior:

  HC_Define_Line_Style("-.", "18 dash, 6 blank, 4 dash, 4 blank");
  HC_Define_Line_Style("1", "18 dash, 6 blank, 4 dash, 4 blank");
            
  HC_Define_Line_Style("-..", "14 dash, 4 blank, 4 dash, 2 blank, 4 dash, 4 blank");
  HC_Define_Line_Style("4", "14 dash, 4 blank, 4 dash, 2 blank, 4 dash, 4 blank");
        
  HC_Define_Line_Style("-...", "12 dash, 2 blank, 4 dash, 2 blank, 4 dash, 2 blank, 4 dash, 2 blank");
  HC_Define_Line_Style("5", "12 dash, 2 blank, 4 dash, 2 blank, 4 dash, 2 blank, 4 dash, 2 blank");

  HC_Define_Line_Style("phantom", "81 dash, 9 blank, 18 dash, 9 blank, 18 dash, 9 blank");
  HC_Define_Line_Style("8", "81 dash, 9 blank, 18 dash, 9 blank, 18 dash, 9 blank");

The OpenGL driver will be able to hardware accelerate any line patterns that can be expressed with a sequence of 16 bits for the on/off values, plus an integer scale value (hence the note above about redefining some of the legacy patterns). For example "8 dash, 24 blank" could be accelerated, but "8 dash, 23 blank" could not.

RESTRICTIONS

See also
Define_Line_Style, Set_Line_Pattern_Explicit, Insert_Ink, Insert_Line, Insert_Polyline, Set_Color, Set_Edge_Pattern, Set_Line_Weight, Show_Line_Pattern.

◆ UnSet_Line_Pattern()

void UnSet_Line_Pattern ( void  )

Removes all settings established by a previous call to Set_Line_Pattern().

DETAILS

No additional details. See Set_Line_Pattern()