[Drawkit] span vs. span unit

[Graham Cox]

On 29/03/2009, at 5:32 AM, Michael Caron wrote:

> Hi Graham,
>
> In DKGridLayer.m, the use of the term "span" seems confusing to me.
>
> First, the conversionFactor argument says "distance in points  
> represented by a single span unit", and then there's a "span"  
> argument that says "the span distance in grid coordinates".
>
> Is a "span unit" like a pixel (given that you've marked 72 as the  
> english conversion factor, and 72 pixels/inch is a standard  
> resolution) or is a "span unit" one tick on the grid ruler?
>
> I don't really understand "the span distance in grid coordinates".  
> What does that mean? Does that mean the distance between ruler ticks  
> on the grid in ticks?
>

Hi Michael,

I agree it's a bit confusing. Partly it stems from the evolution of  
the DKGridLayer - maybe some comments need to be revised.

I'll try and explain as best I can. The important point is that the  
underlying coordinate system used by Quartz is fixed such that 1pt =  
1/72nd of an inch. So everything else ultimately has to end up  
expressing itself in these terms so we can draw the grid and rulers  
using Quartz.

The grid 'span' is the basis for where it lays down the various grid  
lines. The span is broken down into finer 'divisions', the smallest  
drawn grid square, and also multiplied up to a certain number of  
'majors' which are the bolder lines drawn every so often.

The conversion factor sets up the scaling between a single span and  
the underlying quartz coordinates, so for example if you want a span  
of 1 inch, the conversion factor is 72.0, meaning each span line is  
drawn every 72 points, or 1 inch apart. A span of 1 centimetre has a  
conversion factor of 28.346 because 1cm = 28.346 points (you can  
arrive at this figure by dividing 72 by 2.54, the number of  
centimetres in 1 inch). So each span line is drawn 1cm apart.

The confusion probably comes in because there is also the 'span'  
parameter in:

- (void)					setDistanceForUnitSpan:(float) conversionFactor
							drawingUnits:(NSString*) units
							span:(float) span
							divisions:(unsigned) divs
							majors:(unsigned) majors
							rulerSteps:(unsigned) steps;

This parameter is a multiplier - for the situation outlined above, the  
multiplier is 1.0, meaning that the span lines are drawn for every  
span. If the multiplier was 2.0, the spans would be drawn every 2  
spans, and so on. The use of a multiplier allows you to pass in the  
same conversion factor for the underlying coordinate system and  
calculate the interval for you. It also permits non-integer  
multipliers if you wanted. However, I anticipate that almost all of  
the time you'd simply pass 1 here. The multiplier is handy if you  
wanted to work at very small or very large scales, such as microns or  
huge values used in mapping to ensure a sensible density of grid lines  
at those scales, but for typical ordinary uses, there's not much  
reason to use it.

The rulers are also affected. Because of the way NSRulerViews work, we  
need to supply a name and various factors ahead of time so that the  
grid and rulers can be set up to agree with each other. The main  
interval on the ruler (those marked 1, 2, 3, 4 etc) are established by  
multiplying the span by the conversion factor. The rulerSteps are just  
a hint as to how those intervals are split up - it's just passed along  
to NSRulerView as the "step-up cycle" parameter.

I hope that clarifies things a bit - if not, just say!

--Graham