Plot widget

Modules
	Plot widget options
	These options can be ORed together to specify the behaviour of a plot widget when creating it with wtk_plot_create.
	Plot widget grid options
	These options can be ORed together to specify the behaviour of a plot widget grid when adjusting it via wtk_plot_set_grid.

Functions
bool	wtk_plot_add_value (struct wtk_plot *plot, uint8_t value)
	Add a value to the end of the plot. More...
struct win_window *	wtk_plot_as_child (struct wtk_plot *plot)
	Get pointer to plot window. More...
struct wtk_plot *	wtk_plot_create (struct win_window *parent, struct win_area const *area, uint8_t maximum, uint8_t datapoints, gfx_color_t draw_color, struct gfx_bitmap *background, uint8_t option)
	Create a new plot widget. More...
void	wtk_plot_set_colors (struct wtk_plot *plot, gfx_color_t draw_color, struct gfx_bitmap *background)
	Set new plot colors. More...
void	wtk_plot_set_grid (struct wtk_plot *plot, uint8_t axis_option, uint8_t axis_spacing_x, uint8_t axis_offset_x, uint8_t axis_spacing_y, uint8_t axis_offset_y, gfx_color_t axis_color, gfx_color_t axis_zero_color)
	Set grid/axis parameters. More...
static void	wtk_plot_grid_draw (struct wtk_plot *plot, struct win_area const *area, struct win_clip_region const *clip)
	Grid draw function. More...
static void	wtk_plot_draw (struct wtk_plot *plot, struct win_area const *area, struct win_clip_region const *clip)
	Plot draw function. More...
static bool	wtk_plot_handler (struct win_window *win, enum win_event_type type, void const *data)
	plot event handler. More...

bool wtk_plot_add_value	(	struct wtk_plot *	plot,
		uint8_t	value
	)

Add a value to the end of the plot.

Scales the input value to fit the plot dimensions and adds it to the end of the ring buffer.

Parameters

plot	Pointer to wtk_plot struct to set new value for.
value	New value for the plot.

Returns

True.

References Assert, wtk_plot::buffer_start, wtk_plot::container, wtk_plot::maximum, wtk_plot::num_datapoints, wtk_plot::plot_buffer, win_area::size, win_get_area(), wtk_rescale_value(), and win_point::y.

Referenced by widget_frame_command_handler().

struct win_window* wtk_plot_as_child

(

struct wtk_plot *

plot

)

Get pointer to plot window.

Returns a reference to the window that should be used when managing the widget, such as destroying, moving or reparenting it.

Parameters

plot	Pointer to wtk_plot struct to manage.

Returns

Pointer to window to be used for managing the plot.

References Assert, and wtk_plot::container.

Referenced by widget_frame_command_handler().

struct wtk_plot* wtk_plot_create	(	struct win_window *	parent,
		struct win_area const *	area,
		uint8_t	maximum,
		uint8_t	num_datapoints,
		gfx_color_t	draw_color,
		struct gfx_bitmap *	background,
		uint8_t	option
	)

Create a new plot widget.

Allocates the necessary memory and intializes the window and data for plot widgets. If there is not enough memory, the function returns NULL.
To destroy a plot widget and all its contents, and free its memory, call win_destroy() on the plot's child reference, given by wtk_plot_as_child(), similar to:

win_destroy(wtk_plot_as_child(my_plot_ptr));

The plotted graph will shift from right to left as new data values are added. Data values will be overwritten in the ring buffer as they shift out of the plot window. The maximum parameter scales the input value to fit the plot dimensions.

The num_datapoints parameter must not exceed the maximum membag size, and never over 255.

Refer to <gfx/wtk.h> for available configuration options.

Parameters

parent	Pointer to parent win_window struct.
area	Pointer to win_area struct with position and size of the plot. Minimum size in both x and y direction is 4 pixels.
maximum	Maximum value of the plot.
num_datapoints	Number of datapoints of the plot.
draw_color	Plot drawing color.
background	Pointer to background bitmap for frame. NULL for transparent background. When background is transparent the parent window will automatically be redrawn when the basic frame is drawn.
option	Configuration options for plot.

Returns

Pointer to new plot, if memory allocation was successful.

References win_attributes::area, Assert, wtk_plot::axis_color, wtk_plot::axis_offset_x, wtk_plot::axis_offset_y, wtk_plot::axis_option, wtk_plot::axis_spacing_x, wtk_plot::axis_spacing_y, wtk_plot::axis_zero_color, wtk_plot::background, win_attributes::background, win_attributes::behavior, wtk_plot::buffer_start, wtk_plot::container, win_attributes::custom, wtk_plot::draw_color, win_attributes::event_handler, wtk_plot::maximum, membag_alloc(), membag_free(), NULL, wtk_plot::num_datapoints, wtk_plot::option, wtk_plot::plot_buffer, win_area::size, wtk_plot::spacing, wtk_plot::spacing_error, WIN_BEHAVIOR_REDRAW_PARENT, win_create(), WTK_PLOT_DONT_REDRAW_PARENT, wtk_plot_handler(), WTK_PLOT_SCALE_FACTOR, win_point::x, and win_point::y.

static void wtk_plot_draw ( struct wtk_plot *  plot, struct win_area const *  area, struct win_clip_region const *  clip  )

static

Plot draw function.

Draws the plot itself.

Parameters

plot	Pointer to wtk_plot struct to draw.
area	Pointer to win_area struct with position and size of the plot.
clip	Pointer to win_clip_region.

Called by the event handler to draw the plot.

References wtk_plot::buffer_start, wtk_plot::draw_color, gfx_draw_line, wtk_plot::num_datapoints, wtk_plot::option, win_clip_region::origin, wtk_plot::plot_buffer, win_area::size, wtk_plot::spacing, wtk_plot::spacing_error, WTK_PLOT_INVERT, WTK_PLOT_RIGHT_TO_LEFT, WTK_PLOT_SCALE_FACTOR, win_point::x, and win_point::y.

Referenced by wtk_plot_handler().

static void wtk_plot_grid_draw ( struct wtk_plot *  plot, struct win_area const *  area, struct win_clip_region const *  clip  )

static

Grid draw function.

Draws the grid or axis, and zero line based on options.

Parameters

plot	Pointer to wtk_plot struct to draw.
area	Pointer to win_area struct with position and size of the plot.
clip	Pointer to win_clip_region.

Called by the event handler to draw the grid.

References wtk_plot::axis_color, wtk_plot::axis_offset_x, wtk_plot::axis_offset_y, wtk_plot::axis_option, wtk_plot::axis_spacing_x, wtk_plot::axis_spacing_y, wtk_plot::axis_zero_color, gfx_draw_line, win_clip_region::origin, win_area::size, WTK_PLOT_GRID_HORIZONTAL, WTK_PLOT_GRID_VERTICAL, WTK_PLOT_TICK_MARKER_LENGTH, WTK_PLOT_TICKS_HORIZONTAL, WTK_PLOT_TICKS_VERTICAL, WTK_PLOT_ZERO, win_point::x, and win_point::y.

Referenced by wtk_plot_handler().

static bool wtk_plot_handler ( struct win_window *  win, enum win_event_type  type, void const *  data  )

static

plot event handler.

This is the window event handler for plot widgets. It handles the two relevant event types sent to a plot's container window, i.e., drawing, and destroy events.

Parameters

win	Window receiving the event.
type	The event type.
data	Custom data, depending on event type.

Returns

True if the event was recognized and accepted.

References Assert, wtk_plot::background, wtk_plot::container, gfx_draw_rect, membag_free(), NULL, win_clip_region::origin, wtk_plot::plot_buffer, win_area::size, WIN_EVENT_DESTROY, WIN_EVENT_DRAW, win_get_area(), win_get_custom_data(), WTK_PLOT_BORDER_COLOR, wtk_plot_draw(), wtk_plot_grid_draw(), win_point::x, and win_point::y.

Referenced by wtk_plot_create().

void wtk_plot_set_colors	(	struct wtk_plot *	plot,
		gfx_color_t	draw_color,
		struct gfx_bitmap *	background
	)

Set new plot colors.

This sets new draw and background colors for the plot.

Parameters

plot	Pointer to wtk_plot struct to set colors for.
draw_color	Draw color to set for plot.
background	Background color to set for plot.

References Assert, wtk_plot::background, and wtk_plot::draw_color.

void wtk_plot_set_grid	(	struct wtk_plot *	plot,
		uint8_t	axis_option,
		uint8_t	axis_spacing_x,
		uint8_t	axis_offset_x,
		uint8_t	axis_spacing_y,
		uint8_t	axis_offset_y,
		gfx_color_t	axis_color,
		gfx_color_t	axis_zero_color
	)

Set grid/axis parameters.

This function sets the grid and axis options, colors for the plot. The axis_spacing_y and axis_offset_y parameter is rescaled to fit the plot. Both grid and axis can not be used on the same plot.

Refer to <gfx/wtk.h> for available configuration options.

Parameters

plot	Pointer to wtk_plot struct to set colors for.
axis_option	Configuration of axis, grid and zero-line behaviour.
axis_spacing_x	Space between x-axis grid lines/tick marks.
axis_offset_x	Grid/axis offset along the x-axis.
axis_spacing_y	Space between y-axis grid lines/tick marks.
axis_offset_y	Grid/axis offset along the y-axis.
axis_color	Color for the tick marks and grid lines.
axis_zero_color	Color for the zero line.

References Assert, wtk_plot::axis_color, wtk_plot::axis_offset_x, wtk_plot::axis_offset_y, wtk_plot::axis_option, wtk_plot::axis_spacing_x, wtk_plot::axis_spacing_y, wtk_plot::axis_zero_color, wtk_plot::container, wtk_plot::maximum, win_area::size, win_get_area(), wtk_rescale_value(), and win_point::y.