HelpSource/Classes/GridLines.schelp

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