#
6 Area

class `area.T`
  Class `area.T` defines the location and size of a chart. It also defines the coordinate system (linear, log, or enumeration) of the X and Y axes.

  The X (or Y) coordinate system is defined by attribute `x_coord` (or `y_coord`), which takes an object of type `coord.T`. Class `coord.T` defines how an X (or a Y) value is mapped to a display (canvas) location. PyChart provides three standard coordinate systems: `linear_coord.T` (for linear mapping; this is the default), `log_coord.T` (for logarithmic mapping), and `category_coord.T` (enumeration of values). Most charts will do ok by instantiating one of these pre-defined coordinate classes, but you can also define your own wacky coordinate system.

  See Also:

  See Section 6.1 for more about the coordinate system.

  For log and linear coordinate systems, the minimum and maximum displayable values in the area are computed automatically from the plots unless they are defined explicitly via attribute `x_range`. In the next example, the X axis is drawn with a logarithmic scale. The minimum value will be 10, and the maximum value will be computed from the values given to plots.

      ar = area.T(x_coord = log_coord.T(), x_range = (10, None), ...)

  In the below example of a category coordinate system, the X axis will list three strings, ``apple'', ``orange'', and ``blueberry''.

      samples = [("apple", 10), ("orange", 30), ("blueberry", 20)],
      ar = area.T(x_coord = category_coord(samples, 0))
      ar.add_plot(bar_plot.T(data = samples))

We now list the attributes understood by an `area.T` object.

`bg_style`
  Type: fill_style.T ( see Section 16) Default: None.

  Background fill-pattern.

`border_line_style`
  Type: line_style.T ( see Section 14) Default: None.

  Line style of the outer frame of the chart.

`legend`
  Type: legend.T ( see Section 6.3) Default: a legend is by default displayed in the right-center of the chart. If you don't want to draw a legend, you should explicitly set None to this attribute..

  The legend of the chart.

`loc`
  Type: (x,y) or None Default: (0, 0).

  The location of the bottom-left corner of the chart. None means to use the default value.

`size`
  Type: (x,y) or None Default: (120, 110).

  The size of the chart-drawing area, excluding axis labels, legends, tick marks, etc. None means to use the default value.

`x_axis`
  Type: axis.X Default: None.

  The X axis. See Section 6.2.

`x_axis2`
  Type: axis.X Default: None.

  The second X axis. This axis should be non-None either when you want to display plots with two distinct domains or when you just want to display two axes at the top and bottom of the chart. See Section 6.2

`x_coord`
  Type: coord.T (see Section 6.1) Default: A linear coordinate system..

  Set the X coordinate system.

`x_grid_interval`
  Type: number or function Default: None.

  The horizontal grid-line interval. A numeric value specifies the interval at which lines are drawn. If value is a function, it takes two arguments, (MIN, MAX), that tells the minimum and maximum values found in the sample data. The function should return a list of values at which lines are drawn.

`x_grid_over_plot`
  Type: bool Default: False.

  If True, grid lines are drawn over plots. Otherwise, plots are drawn over grid lines.

`x_grid_style`
  Type: line_style.T ( see Section 14) Default: None.

  The style of horizontal grid lines.

`x_range`
  Type: (x,y) or None Default: None.

  Specifies the range of X values that are displayed in the chart. IF the value is None, both the values are computed automatically from the samples. Otherwise, the value must be a tuple of format (MIN, MAX). MIN and MAX must be either None or a number. If None, the value is computed automatically from the samples. For example, if x_range = (None,5), then the minimum X value is computed automatically, but the maximum X value is fixed at 5.

`y_axis`
  Type: axis.Y Default: None.

  The Y axis. See Section 6.2.

`y_axis2`
  Type: axis.Y Default: None.

  The second Y axis. This axis should be non-None either when you want to display plots with two distinct ranges or when you just want to display two axes at the left and right of the chart. See Section 6.2

`y_coord`
  Type: coord.T (see Section 6.1) Default: A linear coordinate system..

  Set the Y coordinate system.

`y_grid_interval`
  Type: number or function Default: None.

  The vertical grid-line interval. See also x_grid_interval

`y_grid_over_plot`
  Type: int Default: False.

  See x_grid_over_plot.

`y_grid_style`
  Type: line_style.T ( see Section 14) Default: line_style.gray70_dash3.

  The style of vertical grid lines.

`y_range`
  Type: (x,y) or None Default: None.

  Specifies the range of Y values that are displayed in the chart. IF the value is None, both the values are computed automatically from the samples. Otherwise, the value must be a tuple of format (MIN, MAX). MIN and MAX must be either None or a number. If None, the value is computed automatically from the samples. For example, if y_range = (None,5), then the minimum Y value is computed automatically, but the maximum Y value is fixed at 5.

An object of `area.T` also provides several methods:

`add_plot`( | plot, ...)

  Add plots to the area. Each plot must be a plot object. See Section 9, Section 7, Section 11, Section 10.

`draw`( | canvas = None)

  Draw plots, axes, and the legend. This procedure must be called at the end of every PyChart application. Parameter canvas is an optional parameter that specifies the output. If omitted, the default canvas is used.

  See Also:

  Section 21 for more about canvas.

`x_pos`( | xval)

  Converts xval to a coordinate on the canvas ( see Section 21). See Section 4.

`y_pos`( | yval)

  Converts yval to a coordinate on the canvas ( see Section 21). See Section 4.

    ar = area.T(loc=(50, 50), size=(100, 100),
                xrange=(0,200), yrange=(0, 1000))
    px = ar.x_pos(50)
    py = ar.y_pos(100)

In the above example, the chart is drawn in the area defined by rectangle (50, 50) - (150, 150). The point (`px, py`) will be at (75, 60), which is the screen location at which the point (50, 100) would be drawn (i.e., 50 + 100 * 50/200 = 75, 50 + 100 * 100 / 1000 = 60).