Object that tracks the zoom state for LineChart.

widgets/linechart/zoom/zoom.go

@@ -0,0 +1,487 @@
+// Copyright 2019 Google Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package zoom contains code that tracks the current zoom level.
+package zoom
+
+import (
+	"fmt"
+	"image"
+	"reflect"
+
+	"github.com/mum4k/termdash/mouse"
+	"github.com/mum4k/termdash/mouse/button"
+	"github.com/mum4k/termdash/numbers"
+	"github.com/mum4k/termdash/terminalapi"
+	"github.com/mum4k/termdash/widgets/linechart/axes"
+)
+
+// Option is used to provide options.
+type Option interface {
+	// set sets the provided option.
+	set(*options)
+}
+
+// options stores the provided options.
+type options struct {
+	scrollStepPerc int
+}
+
+// newOptions creates new options instance and applies the provided options.
+func newOptions(opts ...Option) *options {
+	o := &options{
+		scrollStepPerc: DefaultScrollStep,
+	}
+	for _, opt := range opts {
+		opt.set(o)
+	}
+	return o
+}
+
+// validate validates the provided options.
+func (o *options) validate() error {
+	if min, max := 1, 100; o.scrollStepPerc < min || o.scrollStepPerc > max {
+		return fmt.Errorf("invalid ScrollStep %d, must be a value in the range %d <= value <= %d", o.scrollStepPerc, min, max)
+	}
+	return nil
+}
+
+// option implements Option.
+type option func(*options)
+
+// set implements Option.set.
+func (o option) set(opts *options) {
+	o(opts)
+}
+
+// DefaultScrollStep is the default value for the ScrollStep option.
+const DefaultScrollStep = 10
+
+// ScrollStep sets the amount of zoom in or out on a single mouse scroll event.
+// This is set as a percentage of the current value size of the X axis.
+// Must be a value in range 0 < value <= 100.
+// Defaults to DefaultScrollStep.
+func ScrollStep(perc int) Option {
+	return option(func(opts *options) {
+		opts.scrollStepPerc = perc
+	})
+}
+
+// Tracker tracks the state of mouse selection on the linechart and stores
+// requests for zoom.
+// This object is not thread-safe.
+type Tracker struct {
+	// baseX is the base X axis without any zoom applied.
+	baseX *axes.XDetails
+	// zoomX is the zoomed X axis or nil if zoom isn't applied.
+	zoomX *axes.XDetails
+
+	// cvsAr is the entire canvas available to the linechart widget.
+	cvsAr image.Rectangle
+
+	// graphAr is a smaller part of the cvsAr that contains the linechart
+	// itself. I.e. an area between the axis and the borders of cvsAr.
+	graphAr image.Rectangle
+
+	// fsm is the state machine tracking the state of mouse left button.
+	fsm *button.FSM
+
+	// highlight is the currently highlighted area.
+	highlight *Range
+
+	// opts are the provided options.
+	opts *options
+}
+
+// New returns a new zoom tracker that tracks zoom requests within
+// the provided graph area. The cvsAr argument indicates size of the entire
+// canvas available to the widget.
+func New(baseX *axes.XDetails, cvsAr, graphAr image.Rectangle, opts ...Option) (*Tracker, error) {
+	o := newOptions(opts...)
+	if err := o.validate(); err != nil {
+		return nil, err
+	}
+
+	t := &Tracker{
+		fsm:       button.NewFSM(mouse.ButtonLeft, graphAr),
+		highlight: &Range{},
+		opts:      o,
+	}
+	if err := t.Update(baseX, cvsAr, graphAr); err != nil {
+		return nil, err
+	}
+	return t, nil
+}
+
+// Update is used to inform the zoom tracker about the base X axis and the
+// graph area.
+// Should be called each time the widget redraws.
+func (t *Tracker) Update(baseX *axes.XDetails, cvsAr, graphAr image.Rectangle) error {
+	if !graphAr.In(cvsAr) {
+		return fmt.Errorf("the graphAr %v doesn't fit inside the cvsAr %v", graphAr, cvsAr)
+	}
+	// If any of these parameters changed, we need to reset the FSM and ensure
+	// the current zoom is still within the range of the new X axis.
+	ac, sc := t.axisChanged(baseX), t.sizeChanged(cvsAr, graphAr)
+
+	if sc {
+		t.highlight.reset()
+	}
+	if ac || sc {
+		if t.zoomX != nil {
+			// Input data changed and we have an existing zoom in place.
+			// We need to normalize it again, since it might be outside of the
+			// currently visible values (e.g. if the terminal size decreased).
+			zoomMin := int(t.zoomX.Scale.Min.Value)
+			zoomMax := int(t.zoomX.Scale.Max.Value)
+			min, max := normalize(baseX.Scale.Min, baseX.Scale.Max, zoomMin, zoomMax)
+			zoom, err := newZoomedFromBase(min, max, baseX, cvsAr)
+			if err != nil {
+				return err
+			}
+			t.zoomX = zoom
+		}
+	}
+
+	t.baseX = baseX
+	t.cvsAr = cvsAr
+	t.graphAr = graphAr
+	return nil
+}
+
+// sizeChanged asserts whether the physical layout of the terminal changed.
+func (t *Tracker) sizeChanged(cvsAr, graphAr image.Rectangle) bool {
+	return !cvsAr.Eq(t.cvsAr) || !graphAr.Eq(t.graphAr)
+}
+
+// axisChanged asserts whether the axis scale changed.
+func (t *Tracker) axisChanged(baseX *axes.XDetails) bool {
+	return !reflect.DeepEqual(baseX, t.baseX)
+}
+
+// baseForZoom returns the base axis before zooming.
+// This is either the base provided to New or Update if no zoom was performed
+// yet, or the previously zoomed axis.
+func (t *Tracker) baseForZoom() *axes.XDetails {
+	if t.zoomX == nil {
+		return t.baseX
+	}
+	return t.zoomX
+}
+
+// Mouse is used to forward mouse events to the zoom tracker.
+func (t *Tracker) Mouse(m *terminalapi.Mouse) error {
+	zoom, err := zoomToScroll(m, t.cvsAr, t.graphAr, t.baseForZoom(), t.baseX, t.opts)
+	if err != nil {
+		return err
+	}
+	if zoom != nil {
+		t.zoomX = zoom
+	}
+
+	clicked, bs := t.fsm.Event(m)
+	switch {
+	case bs == button.Down:
+		cellX := m.Position.X - t.graphAr.Min.X
+		t.highlight.addX(cellX)
+
+	case clicked && bs == button.Up:
+		zoom, err := zoomToHighlight(t.baseForZoom(), t.highlight, t.cvsAr)
+		if err != nil {
+			return err
+		}
+		t.zoomX = zoom
+		t.highlight.reset()
+
+	default:
+		t.highlight.reset()
+	}
+	return nil
+}
+
+// Range represents a range of values.
+// The range includes all values x such that Start <= x < End.
+type Range struct {
+	// Start is the start of the range.
+	Start int
+	// End is the end of the range.
+	End int
+
+	// last is the last coordinate that was added to the range.
+	last int
+}
+
+// empty asserts if the range is empty.
+func (r *Range) empty() bool {
+	return r.Start == r.End
+}
+
+// reset resets the range back to zero.
+func (r *Range) reset() {
+	r.Start, r.End, r.last = 0, 0, 0
+}
+
+// addX adds the provided X coordinate to the range.
+func (r *Range) addX(x int) {
+	switch {
+	case r.empty():
+		r.Start = x
+		r.End = x + 1
+
+	case x < r.Start:
+		if r.last == r.End-1 {
+			// Handles fast mouse move to the left across Start.
+			// If we don't adjust the end, we would extend both ends of the
+			// range.
+			r.End = r.Start + 1
+		}
+		r.Start = x
+
+	case x >= r.End:
+		if r.last == r.Start {
+			// Handles fast mouse move to the right across End.
+			// If we don't adjust the start, we would extend both ends of the
+			// range.
+			r.Start = r.End - 1
+		}
+		r.End = x + 1
+
+	case x > r.last:
+		// Handles change of direction from left to right.
+		r.Start = x
+
+	case x < r.last:
+		// Handles change of direction from right to left.
+		r.End = x + 1
+	}
+	r.last = x
+}
+
+// Highlight returns true if a range on the graph area should be highlighted
+// because the user is holding down the left mouse button and dragging mouse
+// across the graph area. The returned range indicates the range of X cell
+// coordinates within the graph area provided to New or Update. These are the
+// columns that should be highlighted.
+// Returns false of no area should be highlighted, in which case the state of
+// the Range return value is undefined.
+func (t *Tracker) Highlight() (bool, *Range) {
+	if t.highlight.empty() {
+		return false, nil
+	}
+	return true, t.highlight
+}
+
+// Zoom returns an adjusted X axis if zoom is applied, or the same axis as was
+// provided to New or Update.
+func (t *Tracker) Zoom() *axes.XDetails {
+	if t.zoomX == nil {
+		return t.baseX
+	}
+	return t.zoomX
+}
+
+// normalize normalizes the zoom range.
+// This handles cases where zoom out would happen above the base axis or
+// when the base axis itself changes (user provided new values) or when the
+// graph areas change (terminal size changed).
+func normalize(baseMin, baseMax *axes.Value, min, max int) (int, int) {
+	bMin := int(baseMin.Value)
+	bMax := int(baseMax.Value)
+	var newMin, newMax int
+	// Don't zoom-out above the base axis.
+	if min < bMin {
+		newMin = bMin
+	} else {
+		newMin = min
+	}
+
+	if max > bMax {
+		newMax = bMax
+	} else {
+		newMax = max
+	}
+	return newMin, newMax
+}
+
+// newZoomedFromBase returns a new X axis zoomed to the provided min and max.
+func newZoomedFromBase(min, max int, base *axes.XDetails, cvsAr image.Rectangle) (*axes.XDetails, error) {
+	zp := *base.Properties // Shallow copy.
+	zp.Min = min
+	zp.Max = max
+
+	zoom, err := axes.NewXDetails(cvsAr, &zp)
+	if err != nil {
+		return nil, fmt.Errorf("failed to create zoomed X axis: %v", err)
+	}
+	return zoom, nil
+}
+
+// findCellPair given two cells on the base X axis returns the values of the
+// closest or the same cells such that the values are distinct.
+// Useful while zooming, if the zoom targets a view that would only have one
+// value, this function adjusts the view to the closest two cells with distinct
+// values.
+func findCellPair(base *axes.XDetails, minCell, maxCell int) (*axes.Value, *axes.Value, error) {
+	minL, err := base.Scale.CellLabel(minCell)
+	if err != nil {
+		return nil, nil, fmt.Errorf("unable to determine min label for cell %d: %v", minCell, err)
+	}
+	maxL, err := base.Scale.CellLabel(maxCell)
+	if err != nil {
+		return nil, nil, fmt.Errorf("unable to determine max label for cell %d: %v", maxCell, err)
+	}
+
+	diff := maxL.Value - minL.Value
+	if diff > 1 {
+		return minL, maxL, nil
+	}
+
+	// Try above the max.
+	for cellNum := maxCell; cellNum < base.Scale.GraphWidth; cellNum++ {
+		l, err := base.Scale.CellLabel(cellNum)
+		if err != nil {
+			return nil, nil, err
+		}
+		if l.Value > minL.Value {
+			return minL, l, nil
+		}
+	}
+
+	// Try below the min.
+	for cellNum := minCell; cellNum >= 0; cellNum-- {
+		l, err := base.Scale.CellLabel(cellNum)
+		if err != nil {
+			return nil, nil, err
+		}
+		if l.Value < maxL.Value {
+			return l, maxL, nil
+		}
+	}
+
+	// Give up and use the first and the last cells.
+	firstL, err := base.Scale.CellLabel(0)
+	if err != nil {
+		return nil, nil, fmt.Errorf("unable to determine label for the first cell: %v", err)
+	}
+	lastL, err := base.Scale.CellLabel(base.Scale.GraphWidth - 1)
+	if err != nil {
+		return nil, nil, fmt.Errorf("unable to determine label for the last cell: %v", err)
+	}
+	return firstL, lastL, nil
+}
+
+// zoomToHighlight zooms the base X axis according to the highlighted range.
+func zoomToHighlight(base *axes.XDetails, hr *Range, cvsAr image.Rectangle) (*axes.XDetails, error) {
+	minL, maxL, err := findCellPair(base, hr.Start, hr.End-1)
+	if err != nil {
+		return nil, err
+	}
+
+	zoom, err := newZoomedFromBase(int(minL.Value), int(maxL.Value), base, cvsAr)
+	if err != nil {
+		return nil, err
+	}
+	return zoom, nil
+}
+
+// zoomToScroll zooms the current X axis in or out depending on the direction of
+// the scroll. Doesn't zoom out above the base X axis view.
+// Doesn't zoom if the scroll button isn't recognized or the event falls
+// outside of the graph area.
+// Can return nil axis if the mouse event didn't result in zooming.
+func zoomToScroll(m *terminalapi.Mouse, cvsAr, graphAr image.Rectangle, curr, base *axes.XDetails, opts *options) (*axes.XDetails, error) {
+	if !m.Position.In(graphAr) {
+		// Ignore scroll events outside of the graph area.
+		return nil, nil
+	}
+
+	var direction int // Positive on zoom in, negative on zoom out.
+	switch m.Button {
+	case mouse.ButtonWheelUp:
+		direction = 1
+
+	case mouse.ButtonWheelDown:
+		direction = -1
+
+	default:
+		// Nothing to do for other buttons.
+		return nil, nil
+	}
+
+	cellX := m.Position.X - graphAr.Min.X
+	tgtVal, err := curr.Scale.CellLabel(cellX)
+	if err != nil {
+		return nil, fmt.Errorf("unable to determine value at the point where scrolling occurred: %v", err)
+	}
+
+	currMin := int(curr.Scale.Min.Value)
+	currMax := int(curr.Scale.Max.Value)
+	baseMin := int(base.Scale.Min.Value)
+	baseMax := int(base.Scale.Max.Value)
+	size := baseMax - baseMin
+	step := size * opts.scrollStepPerc / 100
+	_, left := numbers.MinMaxInts([]int{
+		1,
+		int(tgtVal.Value) - currMin,
+	})
+	_, right := numbers.MinMaxInts([]int{
+		1,
+		currMax - int(tgtVal.Value),
+	})
+
+	splitStep := numbers.SplitByRatio(step, image.Point{left, right})
+	newMin := currMin + (direction * splitStep.X)
+	newMax := currMax - (direction * splitStep.Y)
+
+	var limits *axes.XDetails
+	switch m.Button {
+	case mouse.ButtonWheelUp:
+		if newMin > currMax {
+			newMin = currMax
+		}
+		if newMax < currMin {
+			newMax = currMin
+		}
+		limits = curr
+
+	case mouse.ButtonWheelDown:
+		if newMin < baseMin {
+			newMin = baseMin
+		}
+		if newMax > baseMax {
+			newMax = baseMax
+		}
+		limits = base
+	}
+
+	minCell, err := limits.Scale.ValueToCell(newMin)
+	if err != nil {
+		return nil, err
+	}
+	maxCell, err := limits.Scale.ValueToCell(newMax)
+	if err != nil {
+		return nil, err
+	}
+	minL, maxL, err := findCellPair(limits, minCell, maxCell)
+	if err != nil {
+		return nil, err
+	}
+
+	min, max := normalize(limits.Scale.Min, limits.Scale.Max, int(minL.Value), int(maxL.Value))
+	zoom, err := newZoomedFromBase(min, max, curr, cvsAr)
+	if err != nil {
+		return nil, err
+	}
+	return zoom, nil
+}