Skip to content

Commit 31b653f

Browse files
committed
Documentation
1 parent 943d4f8 commit 31b653f

4 files changed

Lines changed: 96 additions & 78 deletions

File tree

androidplot-core/src/main/java/com/androidplot/ui/DynamicTableModel.java

Lines changed: 0 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -35,21 +35,9 @@
3535
*/
3636
public class DynamicTableModel extends TableModel {
3737

38-
//private float cellWidth;
39-
//private float cellHeight;
40-
//private TableSizingMethod rowSizingMethod;
41-
//private TableSizingMethod columnSizingMethod;
42-
43-
4438
private int numRows;
4539
private int numColumns;
4640

47-
private Float cellWidth;
48-
private Float cellHeight;
49-
50-
private CellSizingMethod rowSizingMethod;
51-
private CellSizingMethod columnSizingMethod;
52-
5341
/**
5442
* Convenience method. Sets order to ROW_MAJOR.
5543
* @param numColumns
@@ -63,30 +51,9 @@ public DynamicTableModel(int numColumns, int numRows) {
6351
public DynamicTableModel(int numColumns, int numRows, TableOrder order) {
6452
super(order);
6553
this.numColumns = numColumns;
66-
//this.cellWidth = cellWidth;
67-
//this.rowSizingMethod = rowSizingMethod;
6854
this.numRows = numRows;
69-
//this.cellHeight = cellHeight;
70-
//this.columnSizingMethod = columnSizingMethod;
71-
//this.order = order;
7255
}
7356

74-
/*public DynamicTableModel(Number colVal, CellSizingMethod colSzMethod, Number rowVal, CellSizingMethod rowSzMethod, TableOrder order) {
75-
if(colVal == null || rowVal == null) {
76-
throw new NullPointerException();
77-
}
78-
columnSizingMethod = colSzMethod;
79-
switch(columnSizingMethod) {
80-
case FILL:
81-
numColumns = colVal.intValue();
82-
break;
83-
case FIXED:
84-
cellWidth = colVal.floatValue();
85-
break;
86-
}
87-
rowSzMethod = rowSzMethod;
88-
}*/
89-
9057
@Override
9158
public TableModelIterator getIterator(RectF tableRect, int totalElements) {
9259
return new TableModelIterator(this, tableRect, totalElements);
@@ -103,9 +70,7 @@ public RectF getCellRect(RectF tableRect, int numElements) {
10370
RectF cellRect = new RectF();
10471
cellRect.left = tableRect.left;
10572
cellRect.top = tableRect.top;
106-
//cellRect.bottom = getElementHeightPix(tableRect);
10773
cellRect.bottom = tableRect.top + calculateCellSize(tableRect, TableModel.Axis.ROW, numElements);
108-
//cellRect.right = getElementWidthPix(tableRect);
10974
cellRect.right = tableRect.left + calculateCellSize(tableRect, TableModel.Axis.COLUMN, numElements);
11075
return cellRect;
11176
}
@@ -120,24 +85,19 @@ public RectF getCellRect(RectF tableRect, int numElements) {
12085
private float calculateCellSize(RectF tableRect,
12186
Axis axis,
12287
int numElementsInTable) {
123-
//float elementSizeInPix = 0;
12488
int axisElements = 0;
12589

12690
float axisSizePix = 0;
12791
switch (axis) {
12892
case ROW:
129-
//elementSizeInPix = cellHeight;
13093
axisElements = numRows;
13194
axisSizePix = tableRect.height();
13295
break;
13396
case COLUMN:
134-
//elementSizeInPix = cellWidth;
13597
axisElements = numColumns;
13698
axisSizePix = tableRect.width();
13799
break;
138100
}
139-
//if (elementSizeInPix != 0) {
140-
// return elementSizeInPix;
141101
if(axisElements != 0) {
142102
return axisSizePix / axisElements;
143103
} else {
@@ -163,22 +123,6 @@ public void setNumColumns(int numColumns) {
163123
this.numColumns = numColumns;
164124
}
165125

166-
/* public void setCellWidth(Float cellWidth) {
167-
this.cellWidth = cellWidth;
168-
}
169-
170-
public Float getCellWidth() {
171-
return cellWidth;
172-
}
173-
174-
public Float getCellHeight() {
175-
return cellHeight;
176-
}
177-
178-
public void setCellHeight(Float cellHeight) {
179-
this.cellHeight = cellHeight;
180-
}*/
181-
182126
private class TableModelIterator implements Iterator<RectF> {
183127
private boolean isOk = true;
184128
int lastColumn = 0; // most recent column iterated
@@ -207,15 +151,13 @@ public TableModelIterator(DynamicTableModel dynamicTableModel, RectF tableRect,
207151
// round up:
208152
calculatedColumns = new Float((totalElements / (float) calculatedRows) + 0.5).intValue();
209153
} else if(dynamicTableModel.getNumRows() == 0 && dynamicTableModel.getNumColumns() >= 1) {
210-
//order = TableOrder.ROW_MAJOR;
211154
calculatedColumns = dynamicTableModel.getNumColumns();
212155
calculatedRows = new Float((totalElements / (float) calculatedColumns) + 0.5).intValue();
213156
// unlimited rows and columns (impossible) so default a single row with n columns:
214157
}else if(dynamicTableModel.getNumColumns() == 0 && dynamicTableModel.getNumRows() == 0) {
215158
calculatedRows = 1;
216159
calculatedColumns = totalElements;
217160
} else {
218-
//order = dynamicTableModel.getOrder();
219161
calculatedRows = dynamicTableModel.getNumRows();
220162
calculatedColumns = dynamicTableModel.getNumColumns();
221163
}

androidplot-core/src/main/java/com/androidplot/ui/FixedTableModel.java

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@
2323
public class FixedTableModel extends TableModel {
2424
private float cellWidth;
2525
private float cellHeight;
26-
protected FixedTableModel(float cellWidth, float cellHeight, TableOrder order) {
26+
27+
public FixedTableModel(float cellWidth, float cellHeight, TableOrder order) {
2728
super(order);
2829
setCellWidth(cellWidth);
2930
setCellHeight(cellHeight);

docs/index.md

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,10 @@
11
# Androidplot Documentation
2-
This is the documentation for Androidplot 1.0. Be aware that many classes have been renamed or removed in this release
3-
to make usage as simple possible. _**If you are upgrading from a previous release of Androidplot code changes will almost certainly be
4-
necessary.**_
52

6-
This documentation is limited. Your best resource
3+
Documentation is limited. Your best resource
74
is the [DemoApp's example source code](../demoapp) as it's kept up to date for every release. If you can't
85
find an answer feel free to ask a question on Stack Overflow using the
96
[Androidplot tag](http://stackoverflow.com/questions/tagged/androidplot).
107

11-
If you see something that isn't right or want to contribute, please submit a pull-request - these docs
12-
live the main repo in the top-level `/docs` directory.
13-
148
# Tutorials
159
These tutorials are roughly in the order that they should be read. Quickstart will get your app
1610
up and running with a basic xy plot. Plot Composition explains the common anatomy of all plots
@@ -25,5 +19,11 @@ specific plot types explaining styling and other advanced topics.
2519
* [Pie Charts](piechart.md)
2620
* Dynamic Plots (TODO)
2721

22+
# Previous Releases
23+
Documentation for Androidplot 0.9.8 and earlier [can be found here](http://androidplot.com/docs/).
24+
2825
# Misc
29-
* [Release Notes](release_notes.md)
26+
* [Release Notes](release_notes.md)
27+
28+
_If you see something that isn't right or want to contribute, please submit a pull-request - these docs
29+
live the main repo in the top-level `/docs` directory._

docs/xyplot.md

Lines changed: 86 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,45 @@
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
79
XYSeries is the interface Androidplot uses to retrieve your numeric data. You may either create your own
810
implementation 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
1645
XYGraphWidget 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
76105
Sometimes 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
82108
Androidplot 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
91139
There are several renderers available for XYPlots:
@@ -98,8 +146,35 @@ There are several renderers available for XYPlots:
98146
Smooth 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
102150
By default, Androidplot will automatically produce a legend for your Plot. You however choose to hide the legend
103151
or 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

Comments
 (0)