Functions and Directives

Function GraSetAttrLine() Foundation

Determines attributes for lines which are drawn with GraLine().

Syntax
GraSetAttrLine( [<oPS>], [<aAttributes>] ) --> aOldAttributes
Parameters
<oPS>
The argument <oPS> specifies the presentation space where line attributes are set. If the current window is an XbpCrt window, <oPS>is optional. If it is NIL, the return value of SetAppWindow():presSpace() is used. In all other cases <oPS> is not optional. It must be created either using XbpPresSpace():new() or a "Micro PS" must be requested from an Xbase Part using the method :lockPS(). After graphic output the Micro PS must be released with :unlockPS().
<aAttributes> := Array( GRA_AL_COUNT )
<aAttributes> is an array whose elements contain the attributes for lines drawn by graphic functions.
#define constants of the attribute array for lines
Array element #define group Default value
GRA_AL_COLOR GRA_CLR_* GRA_CLR_NEUTRAL
GRA_AL_MIXMODE GRA_FGMIX_* GRA_FGMIX_OVERPAINT
GRA_AL_WIDTH GRA_LINEWIDTH_* GRA_LINEWIDTH_NORMAL
GRA_AL_TYPE GRA_LINETYPE_* GRA_LINETYPE_SOLID
Return

The function GraSetAttrLine() returns a copy of the current line attribute array. If new attributes are specified by <aAttributes>, the function returns an array containing the previous attributes.

Description

The function GraSetAttrLine() determines the attributes for lines. It has an effect when graphic primitives such as GraLine() and GraSpline() are used to draw lines. The graphic primitives belong to this group. Line attributes are used for the borders drawn with the functions GraArc() and GraBox(). Line attributes are also employed by the function GraPathOutline() which outlines a graphic path. The line attributes which can be specified are the following:

Attributes for lines
Array element Description
GRA_AL_COLOR Foreground color
GRA_AL_MIXMODE Color mix attribute for foreground
GRA_AL_WIDTH Line width
GRA_AL_TYPE Line type

All line attributes set remain until the function GraSetAttrLine() is called again. The exceptions to this are the colors, which are redefined with GraSetColor().

Foreground color

By default, colors set by GraSetColor() are used. For lines a foreground color is specified separately and lines have no background color.

Mix attributes

Mix attributes for colors have meaning when lines are output over previously drawn graphic elements. For lines, only the mix attribute for foreground color can be set. Important attributes for the foreground color are GRA_FGMIX_OVERPAINT (the line overpaints everything previously visible) and GRA_FGMIX_OR (the overlapping section of the line receives another color).

Another mix attribute is GRA_FGMIX_XOR. This attribute effectively deletes a graphic primitive from the screen when it is executed or drawn a second time at the same coordinates.

Line Width

The line width is specified in logical units, that is, the units specified in XbpPresSpace:create(). Per default, this is pixel. For setting a line width other than the default, a numeric value greater than 0 can be specified for the GRA_AL_WIDTH attribute. Alternatively, one of the two predefined #define constants GRA_LINEWIDTH_NORMAL (normal line) or GRA_LINEWIDTH_THICK (thick line) may be used.

Windows does not support selecting certain line types if the line width is greater than one unit. Furthermore, lines of width GRA_LINEWIDTH_NORMAL are always displayed one pixel wide on the Windows platform and are not affected by graphic transforms. If the viewport of a Presentation Space is used to scale graphical output, for example, the width of lines rendered using GRA_LINEWIDTH_NORMAL will not be scaled. Lines of other widths, however, are subject to graphic transforms and may therefore vary depending on the transform set for the Presentation Space. To select a normal, 1 unit-wide line that is subject to scaling, the value 1 must be specified for the line width attribute.

Line type

The following illustration shows the line types which can be selected by GraSetAttrLine().

Line types and their #define constants

Some line types available under OS/2 are not provided on the Windows platforms. In this case, a similar line type is choosen by Xbase++. Furthermore, line types other than GRA_LINETYPE_SOLID or GRA_LINETYPE_INVISIBLE cannot be selected if the line width specified in GRA_AL_WIDTH is greater than one unit or GRA_LINEWIDTH_NORMAL, respectively.

Examples
Displays all line types

// This example displays all available line types. 

#include "Gra.ch" 

PROCEDURE Main 
   LOCAL aAttr, aLines, i 

   SetColor("N/W")                     // fill window pale gray 
   CLS 
                                       // #define constants as 
   aLines:= { ;                        // text and as a value 
      { "GRA_LINETYPE_DEFAULT      ", GRA_LINETYPE_DEFAULT       }, ; 
      { "GRA_LINETYPE_DOT          ", GRA_LINETYPE_DOT           }, ; 
      { "GRA_LINETYPE_SHORTDASH    ", GRA_LINETYPE_SHORTDASH     }, ; 
      { "GRA_LINETYPE_DASHDOT      ", GRA_LINETYPE_DASHDOT       }, ; 
      { "GRA_LINETYPE_DOUBLEDOT    ", GRA_LINETYPE_DOUBLEDOT     }, ; 
      { "GRA_LINETYPE_LONGDASH     ", GRA_LINETYPE_LONGDASH      }, ; 
      { "GRA_LINETYPE_DASHDOUBLEDOT", GRA_LINETYPE_DASHDOUBLEDOT }, ; 
      { "GRA_LINETYPE_SOLID        ", GRA_LINETYPE_SOLID         }, ; 
      { "GRA_LINETYPE_INVISIBLE    ", GRA_LINETYPE_INVISIBLE     }, ; 
      { "GRA_LINETYPE_ALTERNATE    ", GRA_LINETYPE_ALTERNATE     }  ; 
   } 

   aAttr := Array( GRA_AL_COUNT )      // array for line 
                                       // attributes 
   FOR i:=1 TO 10 
      aAttr[ GRA_AL_TYPE ] := aLines[i,2] 
      graSetAttrLine( NIL, aAttr )     // set attributes 

      graStringAt( NIL, { 30, 360-30*i }, ; // output text 
                          aLines[i,1]     ) 

      graLine( NIL, { 270, 360-30*i }, ;    // draw line 
                    { 600, 360-30*i }  ) 
   NEXT 

   Inkey(0)                            // wait for key press 
RETURN 
Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.