Index pitfalls

From Vectorlab
Jump to: navigation, search

Below a list of index pitfalls. By Orso B. Schmid


Line Style (dash style)

Dash styles evolved from objects outside the name list to named resources in the default content. The routines usable for creating and analyzing dash styles use the Dash Style List and haven't been upgraded to use the Name List, this causes difficulties. There are no routines for creating or editing complex line types as of VW 2016. The maximum count of dash styles increased to 32767 starting from VW 2012 (17).

Dash Style List
from -1 to -NumDashStyles. This ignores complex line types and only includes dashes.
Name List
from 1 to ... (I don't know the limit)

There is no routine for converting from one index system to the other, you must develop a routine yourself. In the category sub-routines there are two proposals which still work, but might become obsolete any time: Attr-NameIndx2DashIndx and Attr-DashIndx2NameIndx.

Across the documentation these terms are used as synonyms:

  • dash styles
  • line styles
  • line types
Before VW 2013 (18) After VW 2013
Dash Style list Name List
patterns
line styles
Dash styles are not named resources, but have nevertheless names stored into their own dash style list:
  • positive index = pen pattern (range 0 to 71)
  • negative index = dash (INTEGER range -1 to -NumDashStyles)
Dash styles are now named resources and can be accessed by type using one the various Resource listing routines (BuildResourceList, BuildResourceList2, BuildResourceListN, BuildResourceListN2).
  • positive index = pen pattern (range 0 to 71)
  • negative index = dash (LONGINT range -1 to -count resources of type 96)
Complex Line Types
Line Types
Introduction of a new name: Line Types (dashes) and Complex Line Types (with geometry repetition)
  • object type 96
  • folder type 174

As far as I know complex line types cannot be created or edited with VS as of VW 2016 (21).

Document
FPenPat: INTEGER;
PenPat(dashListIndex: INTEGER);
FPenPatN: LONGINT;
PenPatN(nameListIndex: LONGINT);
GetDashDataValPairAt(dashListIndex: INTEGER; dataIndex: INTEGER; VAR dash: REAL; VAR gap: REAL): BOOLEAN;
GetNumDashDataPairs(dashListIndex: INTEGER; VAR swt: BOOLEAN): INTEGER;

<--

GetDashStyle(scalesWithThickness: BOOLEAN; numPairs: INTEGER; dash1, gap1, dash2, gap2, dash3, gap3, dash4, gap4, dash5, gap5: REAL): INTEGER;
SetDashStyle(scalesWithThickness: BOOLEAN; numPairs: INTEGER; dash1, gap1, dash2, gap2, dash3, gap3, dash4, gap4, dash5, gap5: REAL): INTEGER;
SetDashStyleN(name: STRING; scalesWithThickness: BOOLEAN; numPairs: INTEGER; dash1, gap1, dash2, gap2, dash3, gap3, dash4, gap4, dash5, gap5: REAL);
Usage
pass the dash-gap values (in page inches) of the searched/wished dash style to retrive it or create it. You can omit pairs if not needed.
Warning
pass the dash-gap values in points to retrive the index from the Dash list corresponding to that definition. You can enter up to 10 page inches values (5 pairs). The fact that the index is returned by value comparison would imply a unicity of the dashes based on the dash-gap values, but this isn't true, you can duplicate a Dash Style and it will differ by its name only. The index returned corresponds to the first dash style found by the given values. A different scalesWithThickness value does make a difference.

<--

NumDashStyles: INTEGER;
Warning
Lists only dashes ignoring eventual complex line types.
NumDashStyles is still valid but you'll need a list created with one of the BuildResourceList routines to fetch also the complex line types, if any:
lineTypeList := BuildResourceList(96, 0, '', numLineTypes); { sets the var numLineTypes }
GetDashStyleIndex(scalesWithThickness: BOOLEAN; numPairs: INTEGER; dash1, gap1, dash2, gap2, dash3, gap3, dash4, gap4, dash5, gap5: REAL): INTEGER;

<--

GetDashStyleName(dashListIndex: INTEGER): STRING;
SetDashStyleName(dashListIndex: INTEGER; dashStyleName: STRING): BOOLEAN;
Warning
GetDashStyleName will get the name stored in the Dash Style list, not in the Name list.
SetDashStyleName will set the name in the Dash Style list, not in the Name list.

<--

Object
GetLS(h: HANDLE): INTEGER;
SetLS(h: HANDLE; dashListIndex: INTEGER);
GetLSN(h: HANDLE): LONGINT;
SetLSN(h: HANDLE; nameListIndex: LONGINT);
Classes
GetClLS(className: STRING): INTEGER;
SetClLS(className: STRING; dashListIndex: INTEGER);
GetClLSN(className: STRING): LONGINT;
SetClLSN(className: STRING; nameListIndex: LONGINT);
Dialogs
GetLineStyleChoice(dialogID: LONGINT; itemID: LONGINT; VAR dashListIndex: INTEGER);
SetLineStyleChoice(dialogID: LONGINT; itemID: LONGINT; dashListIndex: INTEGER);

<--

List Browsers
GetLBItemDashStyle(dialogID, componentID: LONGINT; itemIndex:INTEGER; subItemIndex: INTEGER; VAR dashListIndex, VAR lineWeight: INTEGER): BOOLEAN;
SetLBItemDashStyle(dialogID: LONGINT; componentID: LONGINT; itemIndex: INTEGER; subItemIndex: INTEGER; dashListIndex: INTEGER; lineWeight: INTEGER): BOOLEAN;
Warning
dashListIndex here is a positive index, NOT negative, as everywhere else.

<--


Arrowheads (marker) style

Document defaults routines gets and sets arrowheads using bit values in pairs of 4, while object and class routines use flags in range 0-6. Some Modern Dialogs routines use a 1-based index.

ARROW TYPE INDEX 1-BASED FLAG BIT VALUE
arrowheads
Dialogs - Modern:
GetMarkerChoice, SetMarkerChoice

only when using predefined arrowheads,
and you use the choice index parameter,
otherwise using the style parameter
pass the 0-based flag (on the right)!

GetMarkerPopupSelectedItem

deprecated routine!

Object:
GetMarker, SetMarker
GetObjArrow, SetObjArrow

Classes:

GetClassArrow, SetClassArrow
Document defaults:
FMarker, Marker
Solid arrow 1 0 0=none, 1=start, 2=end, 3=both
Hollow Arrow 2 1 4=none, 5=start, 6=end, 7=both
Open Arrow 3 2 8=none, 9=start, 10=end, 11=both
Dot 4 3 12=none, 13=start, 14=end, 15=both
Circle 5 4 16=none, 17=start, 18=end, 19=both
Slash 6 5 20=none, 21=start, 22=end, 23=both
Cross 7 6 24=none, 25=start, 26=end, 27=both
A value between 0-6
for all object and class marker styles. The object routines allow for checking start and end of marker through boolean values, not all routines allow for checking the angle (and not all markers have an angle parameter, like dots, for example). Class routines do allow for checking end and start marker only since VW 12.5.
Note (objects' markers)
GetMarker, SetMarker do not set the marker's angle!
Use GetObjArrow, SetObjArrow instead
Note (classes' markers)
GetClassArrow, SetClassArrow do not set start and end marker, whereby as to the present VW edition (12.5.1) it is not possible to set different markers for start or end using the "Class Edit" dialog. This might hint to a feature yet to come.
The following vailable routines are not recognized by VW 12.5 Fundamentals:


Fill Type

The fill type of a referenced object can be retrived through the standard routines FFillPat, GetFPat, GetClFPat, etc, or through the object preference flag 696. The fill index is returned by the previously mentioned routines, while GetObjectVariableLongint(h, 695) seems to return always the same value, no matter how the object attributes are:

FILL FILL TYPE and STYLE INDEX FILL TYPE FILL STYLE INDEX
patterns
FFillPat, FillPat

GetFPat, SetFPat

GetClFPat, SetClFPat

GetObjectVariableInt

(h, 696) read only

GetObjectVariableLongint

(h, 695) should be read/write

none (no fill) 0 1 unchanging longint value
solid 1 2 unchanging longint value
bitmap pattern 0-71 3 unchanging longint value
hatch negative index value 4 unchanging longint value
gradient negative index value 5 unchanging longint value
image negative index value 6 unchanging longint value
Example
AlrtDialog(concat(
'Fill type with obj prefs: ', GetObjectVariableInt(FSActLayer, 696), chr(13), 
'Fill index with obj prefs: ', GetObjectVariableInt(FSActLayer, 695), chr(13), 
'Fill index with getFPat: ', getFPat(FSActLayer)
)); { fill type and fill style of the first selected object }


Poly and Poly3D

The following polygon/polyline routines are toggling the index base from 0-based to 1-based. Special care is needed.

Index 1-based Index 0-based
GetPolyPt GetPolyPt3D from VW 13 it returns z-value adding the layer's Z
SetPolyPt SetPolyPt3D from VW 13 it sets z-value subtracting the layer's Z


Colors

color palette with color indexes

Colors are a theme for itself. Please read Colours (isma) for a more extensive discussion about the topic. Let here only be given a short comparison list of the different values used.

Undocumented feature
While most routines should accept a LONGINT triplet value in range 0-65535, many basic attributes routines also accept a color index. The routines labelled with 1 or 2 have this feature. This might come handy in many cases, saving needless conversions through: RGBToColorIndex or the other way around ColorIndexToRGB.
Known bug
SetFillBack, SetFillFore will remove the "ByClass" attribute of the PEN as well.
SetPenBack, SetPenFore will remove the "ByClass" attribute of the FILL.
Remember to parse for the "ByClass" attribute and restore it (up to VW 13).
COLOR INDEX (color palette) INT VALUE 0-255 LONGINT VALUE 0-65535
Document defaults:
PenBack[1], PenFore[1]
FillBack[1], FillFore[1]

Object:

SetPenBack[1], SetPenFore[1]
SetFillBack[1], SetFillFore[1]

Classes:

SetClPenBack[1], SetClPenFore[1]
SetClFillBack[1], SetClFillFore[1]

Layer:

LPenBack[1], LPenFore[1]
LFillBack[1]. LFillFore[1]

Hatches:

AddVectorFillLayer, BeginVectorFillN

Dialog - Modern:

GetColorChoice, SetColorChoice
GetPatternData, SetPatternData
GetGradientSliderData, SetGradientSliderData

Worksheet:

GetWSCellFill, SetWSCellFill
GetWSCellTextColor, SetWSCellTextColor
Gradient (document defaults):
GetGradientData, SetGradientData
GetGradientSpotColor, GetGradientSpotColor
InsertGradientSegment

List Browser:

GetLBItemFillBackColor, SetLBItemFillBackColor
GetLBItemFillForeColor, SetLBItemFillForeColor
GetLBItemPenBackColor, SetLBItemPenBackColor
GetLBItemPenForeColor, SetLBItemPenForeColor
GetLBItemTextColor, SetLBItemTextColor
Document defaults:
FPenBack, PenBack[2]
FPenFore, PenFore[2]
FFillBack, FillBack[2]
FFillFore, FillFore[2]

Object:

GetPenBack, SetPenBack[2]
GetPenFore, SetPenFore[2]
GetFillBack, SetFillBack[2]
GetFillFore, SetFillFore[2]

Classes:

GetClPenBack, SetClPenBack[2]
GetClPenFore, SetClPenFore[2]
GetClFillBack, SetClFillBack[2]
GetClFillFore, SetClFillFore[2]

Layer:

LPenBack[2], LPenFore[2]
LFillBack[2]. LFillFore[2]

Light:

GetLightColorRGB, SetLightColorRGB
GetLayerAmbientColor, SetLayerAmbientColor

Dialog - Modern:

GetColorButton, SetColorButton
Exceptions:
  1. 1.00 1.01 1.02 1.03 1.04 1.05 1.06 1.07 1.08 1.09 1.10 1.11 1.12 1.13 1.14 1.15 Officially documented for accepting three LONGINT values in range 0-65535, this routine also accept a single color index value corresponding to the color palette.
  2. 2.00 2.01 2.02 2.03 2.04 2.05 2.06 2.07 2.08 2.09 2.10 2.11 2.12 2.13 2.14 2.15 Also accepts a single parameter of type INTEGER corresponding to one of the 256 Colors defined in the document's Color Palette.