11# XYPlot
2- XYPlot renders XYSeries data onto a graph.
2+ An XYPlot renders one or more XYSeries onto an instance of XYGraphWidget. It also includes two instances
3+ of TextLabelWidget used to display an optional title for the domain and range axis, and an instance
4+ of [ XYLegendWidget] ( #legend ) which by default will automatically display legend items for each XYSeries added to the plot.
35
46![ image] ( images/plot_anatomy.png )
57
68# XYSeries
79XYSeries is the interface Androidplot uses to retrieve your numeric data. You may either create your own
810implementation of XYSeries or use SimpleXYSeries if you don't have tight performance requirements or
9- if your numeric data is easily accessed as an array or list of values.
11+ if your numeric data is easily accessed as an array or list of values. As a convenience, Androidplot provides
12+ an all-purpose implementation of the XYSeries interface called SimpleXYSeries.
1013
1114## SimpleXYSeries
12- TODO - For now, use the DemoApp's source as a reference as nearly all samples rely on SimpleXYSeries
13- to populate the graph with series data.
15+ SimpleXYSeries is used to wrap your raw data with an implementation of the XYSeries interface. You can supply
16+ your data in several ways:
17+
18+ As a list of y-vals; the x-val is implicitly set to array index of each supplied y-val:
19+ ``` java
20+ Number [] yVals = {1 , 4 , 2 , 8 , 4 , 16 , 8 , 32 , 16 , 64 };
21+ XYSeries series1 = new SimpleXYSeries (
22+ Arrays . asList(yVals), SimpleXYSeries . ArrayFormat . Y_VALS_ONLY , " my series" );
23+ ```
24+
25+ An interleaved list of x/y value pairs:
26+ ``` java
27+ Number [] yVals = {1 , 4 , 2 , 8 , 4 , 16 , 8 , 32 , 16 , 64 };
28+ XYSeries series1 = new SimpleXYSeries (
29+ Arrays . asList(yVals), SimpleXYSeries . ArrayFormat . XY_VALS_INTERLEAVED , " my series" );
30+ ```
31+
32+ Separate lists of x-vals and y-vals:
33+ ``` java
34+ Number [] xVals = {1 , 4 , 2 , 8 , 4 , 16 , 8 , 32 , 16 , 64 };
35+ Number [] yVals = {5 , 2 , 10 , 5 , 20 , 10 , 40 , 20 , 80 , 40 };
36+ XYSeries series = new SimpleXYSeries (xVals, yVals, " my series" );
37+ ```
38+
39+ NOTE: SimpleXYSeries is designed to be easy to use for a broad number of applications,; it is not
40+ designed for speed; if you are dynamically displaying data that needs to be refreshed more than several
41+ times a second, you'll probably want to write an implementation of XYSeries designed for your app's
42+ specific needs.
1443
1544# The Graph
1645XYGraphWidget encapsulates XYPlot's graphing functionality. Given an instance of XYPlot, a reference
@@ -75,17 +104,36 @@ only on the left and bottom edges.
75104### Dual Axis Labels
76105Sometimes it is desirable to display additional labels for a single axis, each using it's own scale.
77106
78- TODO - [ f(x) plot example source] ( ../demoapp/src/main/java/com/androidplot/demos/FXPlotExampleActivity.java )
79- provides a reference implementation.
80-
81107### Line Label Interval
82108Androidplot allows you to configure the interval at which labels are rendered for domain and range lines:
83109
84110* ` XYPlot.getGraph().setLinesPerDomainLabel(int interval) `
85111* ` XYPlot.getGraph().setLinesPerRangeLabel(int interval) `
86112
87- ### Line Label Format
88- TODO
113+ ### LineLabelStyle
114+ The styling of the line labels drawn on each edge of the graph is controlled by it's associated style.
115+ this style contains params that control:
116+
117+ * Paint used to draw labels (determines, color, font size, etc.)
118+ * Format used to draw text (can be NumberFormat, etc.)
119+ * Rotation of the label text
120+
121+ To get the style used to draw the left edge (range) labels:
122+
123+ ``` java
124+ plot. getGraph(). getLineLabelStyle(XYGraphWidget . Edge . LEFT );
125+ ```
126+
127+ ### LineLabelRenderer
128+ If you need to implement special rendering behavior for your line labels, such as drawing graphics, symbols, etc.
129+ you can create a custom renderer by extending LineLabelRenderer and injecting it into the graph:
130+
131+ ``` java
132+ plot. getGraph(). setLineLabelRenderer(XYGraphWidget . Edge . LEFT , customLineLabelRenderer);
133+ ```
134+
135+ [ f(x) plot example source] ( ../demoapp/src/main/java/com/androidplot/demos/FXPlotExampleActivity.java )
136+ provides an example of this kind of customization.
89137
90138# Renderers
91139There are several renderers available for XYPlots:
@@ -98,8 +146,35 @@ There are several renderers available for XYPlots:
98146Smooth lines can be created by applying the
99147[ Catmull-Rom interpolator] ( http://androidplot.com/smooth-curves-and-androidplot/ ) to your series' Format.
100148
101- ## The Legend
149+ ## < a name = " legend " ></ a > The Legend
102150By default, Androidplot will automatically produce a legend for your Plot. You however choose to hide the legend
103151or you can customize it to suit your needs.
104152
105- TODO
153+ In addition to the scaling and positioning operations common to all widgets, number and behavior of legend
154+ rows and columns can be configured.
155+
156+ ### The TableModel
157+ The TableModel controls how and where each item in the legend is drawn. Androidplot provides two
158+ default implementations; DynamicTableModel and FixedTableModel (detailed below). All TableModel implementations
159+ organize elements into a grid. This grid is populated with items based on the order which it's corresponding
160+ series was added to the plot. This ordering can be further controlled by setting the TableModel's
161+ TableOrder param to either ROW_MAJOR (items are added left-to-right, top-down) or COLUMN_MAJOR (items are added top-down, left-to-right).
162+
163+ #### DynamicTableModel
164+ The DynamicTableModel takes a desired of numbered rows and columns and evenly subdivides the LegendWidget's
165+ visible space into cells. For example, A 2x2 legend using ROW_MAJOR ordering:
166+
167+ ``` java
168+ plot. getLegend(). setTableModel(new DynamicTableModel (2 , 2 , TableOrder . ROW_MAJOR ));
169+ ```
170+
171+ #### FixedTableModel
172+ The FixedTableModel takes a desired size of each cell in pixels and adds cells using the specified TableOrder.
173+ It automatically wraps to the next row or column (based on TableOrder) when the cell being added
174+ exceeds the legend's available space on a given axis. For example, A FixedTableModel using 300w* 100h cells and
175+ a TableOrder of COLUMN_MAJOR:
176+
177+ ``` java
178+ plot. getLegend(). setTableModel(new FixedTableModel (PixelUtils . dpToPix(300 ),
179+ PixelUtils . dpToPix(100 ), TableOrder . COLUMN_MAJOR ));
180+ ```
0 commit comments