Graphs
Graph views are available in the Xweather iOS SDK that allow you to visualize any type of weather data our Xweather Weather API provides. You can use graph views to show temperature trends over the past 24 hours, show precipitation forecasts in a bar graph for the next week, and more.
When working with graph views in the SDK, you will be working with three primary base classes:
- AWFGraphView: The main view object for a graph and is responsible for managing the graph's series, axis and renderers.
- AWFGraphSeries: The graph's primary data series object that is responsible for managing individual series items (datasources) and performing the necessary range calculations from the graph data.
- AWFSeriesItem: Represents a single dataset in your graph, such as maximum temperatures or precipitation totals. This object will be where most of your graph's configuration and styling are defined as well as providing the data for the series item to the parent graph series.
When loading weather data from the Xweather Weather API, you'll need to use the weather-specific subclasses of AWFGraphSeries and AWFSeriesItem:
- AWFWeatherGraphSeries: A subclass of AWFGraphSeries that interacts with the Xweather Weather API to request data for the graph based on the graph's set of series items.
- AWFWeatherSeriesItem: A subclass of AWFSeriesItem that provides an
AWFWeatherEndpoint
object to be used when requesting data from the Xweather Weather API for this dataset.
For complete, in-depth examples of setting up and using the graphing library provided with the SDK within an application, review the demo application (opens in a new tab) included with the SDK's download.
Graph Data
Graph data is assigned to a graph view through the use of a series instance and one or more series items, one for each data value to be displayed in the graph. Refer to our graph setup guide for a complete description of how to setup your graph view and data.
Graph Axes
A graph view automatically sets up both x and y axes when you initialize a graph view. By default, the x-axis will be an instance of AWFGraphTimeAxis
to represent change in time and expects all x values provided to the graph series to be a valid NSDate
value. The y-axis will default to AWFGraphAxis
, which is just a simple value-based axis.
If you need to change one or both of these default axis objects to a different type or to a custom subclass, you can set the axis instances directly on your graph view through the xAxis
and yAxis
properties. You can also access the graph's currently configured axis objects to override the default configuration for them, such as properties related to the formatting and layout of value ticks and labels along each axis.
For basic axis label and line/grid styling, you can override the default values for textStyle
, tickColor
and gridColor
. For textStyle
, provide an AWFTextStyle
instance that will be applied to the axis labels. The color values you provide for tickColor
and gridColor
control the line color used for rendering the axis tick marks and background grid lines respectively.
Review the API documentation for AWFGraphAxis
and AWFGraphTimeAxis
for more information about the available properties and methods.
Zooming a Graph View
By default, the entire graph series will be rendered to fit within the bounds of the graph by default. This may not work well with your specific datasets, especially if your x-axis spans a large range and the series data points are too close together to interact with.
A graph view supports zooming in a similar manner to that of MKMapView -- a pinch gesture inwards on the graph view will zoom into the graph, whereas a pinch gesture outwards will zoom back out. Additionally, you can perform a double-tap gesture on the graph view to zoom in one level, and then tap with two fingers to zoom back out one level. As a user zoom into a graph view, the width of the series view will increase to provide more distance between each data point along the x-axis to allow better interaction with each point.
Currently zooming is only supported horizontally for the x-axis.
You can disable zooming for a graph view using its zoomEnabled
property:
graphView.zoomEnabled = false
If zooming is disabled, you can also set the zoom scale of a graph view directly if the default zoom scale doesn't work well with your datasets. This will allow your graph view to scroll horizontally as needed to view the entire x-axis range:
graphView.zoomScale = 3.0
Displaying Graph Values
Graph values for specific points are presented using an AWFGraphCalloutView
instance, and there are two ways in which actual values are displayed on the graph.
The primary method for displaying a value is by tapping on a graph's data point. This can either be a point for a line graph or a bar for a bar graph. If the graph renderer associated with the tapped series point supports selections, the graph callout view will be presented from that element within the graph view and will display the series item title and value at that point:
Alternatively, performing a long-pressure gesture anywhere on the graph view will display the values for all series items at the gesture's location within the view. If the point occurs beyond the bounds of a series item, then no value will be displayed for that item in the set.
Dragging horizontally in the graph view while continuing the long-press gesture will continuously update the values in the graph's callout view based on the series values at that point along the x-axis:
If you need to customize you graph's callout view, you can subclass AWFGraphCalloutView
to perform your own implementation and then set your graph view's calloutView
property with an instance of your custom callout view. Note that you must also override the public methods with your own methods to handle the necessary drawing and layout of your callout view.