1CLASS:: GridLines
2summary:: given a spec and the actual data's min and max values, calculates the ideal spacing and labelling of grid lines for plotting
3categories:: GUI>Accessories
4related:: Reference/plot, Classes/Plotter, Classes/DrawGrid
5
6DESCRIPTION::
7GridLines is a strategy object that implements a general strategy for finding a suitable min max range for graphing and suitable intervals for grid lines and labelling.
8
9The object that does the actual drawing on a view is DrawGrid.
10
11A GridLines object uses a ControlSpec to define the minimum and maximum possible values.  Given a data set's actual minimum and maximum values, the GridLines object can choose a logical range for graphing that encompasses the data that will be plotted.
12
13Future development work will add subclasses of GridLines that can bind more tightly with the data they are representing.  For instance a FreqGridLines (not yet implemented) could apply stronger lines to octave divisions.  A DegreeGridLines could be used to draw pitch degree gridlines behind a frequency plot.
14
15Spec has a .grid variable that points to its preferred GridLines object that should be used for graphing.
16
17code::
18\freq.asSpec.grid
19::
20
21This default implementation does not know anything about the data is displaying:
22
23code::
24DrawGrid.test( nil, \midinote.asSpec.grid );
25::
26
27A MidinoteGrid could be written that labels these correctly, shows octaves and individual notes depending on the current zoom.
28
29Note that the GridLines does not know which axis it is to be used on and could also be used in polar plots or in 3D rendering.
30
31CLASSMETHODS::
32
33METHOD:: new
34
35argument:: spec
36The ControlSpec that defines the mininum and maximum values, warn and step.
37
38returns:: a GridLines
39
40
41INSTANCEMETHODS::
42
43METHOD:: spec
44get/set the spec
45
46returns:: a ControlSpec
47
48METHOD:: asGrid
49return self.  nil.asGrid would return a BlankGridLines which is a subclass of GridLines.  So when plotting if you specify a grid of nil then you will get no lines at all.
50
51returns:: self
52
53METHOD:: niceNum
54Based on: http://books.google.de/books?id=fvA7zLEFWZgC&pg=PA61&lpg=PA61
55This rounds a value to a logical nice number.  It is mostly used to support internal calculation, though it may be useful for other applications.
56
57argument:: val
58The value.
59
60argument:: round
61Boolean. Rounding uses a specific algorithm.  This is not simple rounding to an integer value.
62
63returns:: the nice number
64
65METHOD:: ideals
66for internal use
67
68argument:: min
69(describe argument here)
70
71argument:: max
72(describe argument here)
73
74argument:: ntick
75(describe argument here)
76
77returns:: (returnvalue)
78
79METHOD:: looseRange
80Returns the logical minimum and maximum that will contain the data.
81
82argument:: min
83minimum value
84
85argument:: max
86maximum value.
87
88argument:: ntick
89the number of lines you would like (which usually varies by how much screen space you have and what you consider cluttered)
90
91returns:: [ideal min, ideal max]
92
93METHOD:: getParams
94Specifically for use by DrawGrid. This returns a dictionary filled with:
95'lines': an array of values where lines should be drawn
96'labels': [value, formatted label] for each line
97
98argument:: valueMin
99minimum value of the data to be plotted
100
101argument:: valueMax
102maximum value of the data to be plotted
103
104argument:: pixelMin
105If numTicks is nil: used to guess the ideal numTicks based on the graph size.
106
107argument:: pixelMax
108If numTicks is nil: used to guess the ideal numTicks based on the graph size.
109
110argument:: numTicks
111Explicit number of ticks you would like to see on the graph.
112
113returns:: A dictionary
114
115METHOD:: formatLabel
116Round the value and append the spec's units
117
118argument:: val
119The value
120
121argument:: numDecimalPlaces
122Number of decimal places
123
124returns:: a string
125
126
127