Ruler Class Reference

#include <ruler.hh>

Collaboration diagram for Ruler:

Public Types
enum	Orientation { HORIZONTAL, VERTICAL }
using	Ptr = boost::shared_ptr< Ruler >

Public Member Functions
	~Ruler ()
	Ruler (const Ruler &)=delete
	Ruler (Ruler &&)=delete
Ruler	operator= (const Ruler &)=delete
Ruler	operator= (Ruler &&)=delete
void	setRange (double lower, double upper)

Static Public Member Functions
static Ptr	create (Orientation orientation, GtkWidget *drawArea)

Private Member Functions
	Ruler (RulerDrawStrategy::Ptr strategy, GtkWidget *drawingArea)
void	draw (GtkWidget *widget, cairo_t *cr)
void	updateAllocatedSize (int newWidth, int newHeight)
void	updateMajorTickInterval ()
void	drawTicks (cairo_t *cr, double lower, double upper, double lineLength)
void	drawSingleTick (cairo_t *cr, double linePosition, double lineLength, bool drawLabel, const std::string &label)
void	drawSubTicks (cairo_t *cr, double lower, double upper, int depth, double lineLength)

Static Private Member Functions
static gboolean	drawCallback (GtkWidget *widget, cairo_t *cr, gpointer data)
static void	sizeAllocateCallback (GtkWidget *widget, GdkRectangle *allocation, gpointer data)

Private Attributes
GtkWidget *	drawingArea {}
double	lowerLimit {DEFAULT_LOWER}
double	upperLimit {DEFAULT_UPPER}
int	width {}
int	height {}
int	majorInterval {1}
int	majorTickSpacing {}
RulerDrawStrategy::Ptr	drawStrategy
GdkRGBA	lineColor {0, 0, 0, 1}

Static Private Attributes
static constexpr double	DEFAULT_LOWER {0}
static constexpr double	DEFAULT_UPPER {10}
constexpr static std::array< int, 2 >	SUBTICK_SEGMENTS {5, 2}
static constexpr int	MIN_SPACE_SUBTICKS {5}
static constexpr double	FONT_SIZE {11}
static constexpr double	LABEL_OFFSET {4}
static constexpr double	LABEL_ALIGN {0.7}
static constexpr double	LINE_MULTIPLIER {0.6}
static constexpr double	LINE_WIDTH {1}
static constexpr double	MAJOR_TICK_LENGTH {0.8}

Detailed Description

This class draws a ruler to a GtkDrawingArea. It is intended as a replacement for the old GTK2 ruler widget and is written to mimic that widget's behavior as close as possible.

Member Typedef Documentation

Ptr

using Ruler::Ptr = boost::shared_ptr<Ruler>

Member Enumeration Documentation

Orientation

enum Ruler::Orientation

Enumerator
HORIZONTAL
VERTICAL

  {
    HORIZONTAL,
    VERTICAL
  };

Constructor & Destructor Documentation

~Ruler()

Ruler::~Ruler

(

)

{
  // Disconnect all signal handlers for this object from the drawing area
  g_signal_handlers_disconnect_by_data(drawingArea, this);
  // Decrement reference count drawing area
  g_object_unref(drawingArea);
}

Ruler() [1/3]

Ruler::Ruler ( const Ruler &  )

delete

Referenced by create().

Here is the caller graph for this function:

Ruler() [2/3]

Ruler::Ruler ( Ruler &&  )

delete

Ruler() [3/3]

Ruler::Ruler ( RulerDrawStrategy::Ptr  strategy, GtkWidget *  drawingArea  )

private

Creates a Ruler.

Parameters

rulerOrientation	The rulerOrientation of the ruler.
drawingArea	The GtkDrawingArea to draw the ruler to.

  : drawingArea{drawingAreaWidget}
  , width{gtk_widget_get_allocated_width(drawingAreaWidget)}
  , height{gtk_widget_get_allocated_height(drawingAreaWidget)}
  , drawStrategy{std::move(strategy)}
{
  require(drawingArea != nullptr);
 
  // Increment reference count of drawing area
  g_object_ref_sink(drawingArea);
 
  // Set size for strategy
  this->drawStrategy->setAllocatedSize(width, height);
 
  // Connect signal handlers
  g_signal_connect(drawingAreaWidget, "draw", G_CALLBACK(drawCallback), this);
  g_signal_connect(drawingAreaWidget, "size-allocate", G_CALLBACK(sizeAllocateCallback), this);
  // Calculate tick intervals and spacing
  updateMajorTickInterval();
}

Member Function Documentation

create()

Ruler::Ptr Ruler::create ( Ruler::Orientation  orientation, GtkWidget *  drawArea  )

static

Creates a ruler.

Parameters

orientation	The orientation of the ruler.
drawArea	The GtkDrawingArea to draw the ruler to.

Returns

The newly created ruler.

{
  Ruler::Ptr ruler;
  // We pass a different drawing strategy to the ruler depending on orientation
  if(orientation == HORIZONTAL)
  {
    ruler = Ruler::Ptr(new Ruler(HorizontalDrawStrategy::create(), drawingArea));
  }
  else
  {
    ruler = Ruler::Ptr(new Ruler(VerticalDrawStrategy::create(), drawingArea));
  }
  return ruler;
}

Referenced by BOOST_AUTO_TEST_CASE().

Here is the call graph for this function:

Here is the caller graph for this function:

draw()

void Ruler::draw ( GtkWidget *  widget, cairo_t *  cr  )

private

Draws the ruler to the given Cairo context.

Parameters

widget	The widget that received the draw signal.
cr	Cairo context to draw to.

{
  // Initialize cairo
  cairo_set_antialias(cr, CAIRO_ANTIALIAS_NONE);
  cairo_set_line_cap(cr, CAIRO_LINE_CAP_SQUARE);
 
  // Draw background using widget's style context
  GtkStyleContext* context = gtk_widget_get_style_context(widget);
  gtk_render_background(context, cr, 0, 0, width, height);
 
  // Draw outline
  gdk_cairo_set_source_rgba(cr, &lineColor);
  drawStrategy->drawOutline(cr, LINE_WIDTH);
  cairo_set_line_width(cr, Ruler::LINE_WIDTH);
 
  // The majorInterval is invalid, don't attempt to draw anything else
  if(majorInterval <= 0)
  {
    return;
  }
 
  // Calculate the line length for the major ticks given the size of the ruler
  const double lineLength = drawStrategy->getMajorTickLength(MAJOR_TICK_LENGTH);
 
  const int firstTick = RulerCalculations::firstTick(lowerLimit, majorInterval);
 
  // Draw the range [0, upperLimit]
  drawTicks(cr, firstTick, upperLimit, lineLength);
}

Referenced by drawCallback().

Here is the call graph for this function:

Here is the caller graph for this function:

drawCallback()

gboolean Ruler::drawCallback ( GtkWidget *  widget, cairo_t *  cr, gpointer  data  )

staticprivate

A callback to be connected to a GtkDrawingArea's "draw" signal. Draws the ruler to the drawing area.

Parameters

widget	The widget that received the signal.
cr	Cairo context to draw to.
data	Pointer to a ruler instance.

Returns

TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

{
  auto* ruler = static_cast<Ruler*>(data);
  ruler->draw(widget, cr);
 
  return FALSE;
}

Here is the call graph for this function:

drawSingleTick()

void Ruler::drawSingleTick ( cairo_t *  cr, double  linePosition, double  lineLength, bool  drawLabel, const std::string &  label  )

private

Draws a single tick, taking into account the ruler's orientation.

Parameters

cr	Cairo context to draw to.
linePosition	The position of the line along the ruler.
lineLength	Length of the line in pixels.
drawLabel	True if a label should be drawn to the right/top of the line.
label	The label to draw if drawLabel is true.

{
  const double DRAW_AREA_SIZE = drawStrategy->getDrawAreaSize();
  // Draw the line if is within the drawing area
  if(0 < linePosition && linePosition < DRAW_AREA_SIZE)
  {
    // Draw line
    drawStrategy->drawTickLine(cr, linePosition, LINE_WIDTH, lineLength);
  }
 
  // We'll be modifying the transformation matrix so
  // we save the current one to restore later
  cairo_save(cr);
  if(drawLabel) // Draw the tick label
  {
    // Set text font and size
    cairo_select_font_face(cr, "sans-serif", CAIRO_FONT_SLANT_NORMAL, CAIRO_FONT_WEIGHT_NORMAL);
    cairo_set_font_size(cr, FONT_SIZE);
    // drawTickText(cairo_t *cr, std::string label, double linePosition, double labelOffset, double labelAlign, double lineLength,
    // int width, int height) = 0;
    drawStrategy->drawTickText(cr, label, linePosition, LABEL_OFFSET, LABEL_ALIGN, lineLength);
  }
  cairo_restore(cr);
}

Referenced by drawSubTicks(), and drawTicks().

Here is the caller graph for this function:

drawSubTicks()

void Ruler::drawSubTicks ( cairo_t *  cr, double  lower, double  upper, int  depth, double  lineLength  )

private

Draws the smaller ticks in between the major ticks from left-to-right / bottom-to-top.

Parameters

cr	Cairo context to draw to.
lower	The lower limit of the range in draw space.
upper	The upper limit of the range in draw space.
depth	The depth of this recursive function. Functions as an index into the ruler's SUBTICK_SEGMENTS array.
lineLength	Length of the lines in pixels.

{
  // We don't need to divide the segment any further so return
  if(static_cast<unsigned int>(depth) >= SUBTICK_SEGMENTS.size())
  {
    return;
  }
 
  const int    numSegments = SUBTICK_SEGMENTS.at(depth);
  const double interval    = abs(upper - lower) / numSegments;
 
  if(interval < MIN_SPACE_SUBTICKS)
  {
    return;
  }
 
  // We draw from lower->upper / upper->lower, but in the process, we might be exceeding
  // the ruler area, so we also check that we're still inside the drawing area
  const double DRAW_AREA_SIZE = drawStrategy->getDrawAreaSize();
  const double limit          = DRAW_AREA_SIZE;
 
  // Position along the ruler to draw tick at
  double tick = 0;
  double pos  = lower;
 
  // Draw at most (numSegments - 1) ticks, while not exceeding the limit
  while(tick < numSegments && pos < limit)
  {
    // We don't want to draw the tick for tick == 0, because
    // we would end up drawing over other ticks
    if(tick != 0)
    {
      drawSingleTick(cr, pos, lineLength, false, "");
    }
    tick++;
    // Draw ticks at level below
    drawSubTicks(cr, pos, pos + interval, depth + 1, LINE_MULTIPLIER * lineLength);
 
    pos += interval;
  }
}

Referenced by drawTicks().

Here is the call graph for this function:

Here is the caller graph for this function:

drawTicks()

void Ruler::drawTicks ( cairo_t *  cr, double  lower, double  upper, double  lineLength  )

private

Draws the tick marks of the ruler for a given subset of the range from left-to-right / bottom-to-top.

Parameters

cr	Cairo context to draw to.
lower	The lower limit of the range to draw.
upper	The upper limit of the range to draw.
lineLength	Length of the lines in pixels.

{
  // Position in ruler range
  double pos = lower;
 
  const double DRAW_AREA_ORIGIN = 0;
  // We need to scale to either [0, width] or [0, height] depending
  // on the orientation of the ruler
  const double DRAW_AREA_SIZE = drawStrategy->getDrawAreaSize();
 
  // Move pos across range
  while(pos < upper)
  {
    // Map pos from the ruler range to a drawing area position
    const double s =
      RulerCalculations::scaleToRange(pos, lowerLimit, upperLimit, DRAW_AREA_ORIGIN, DRAW_AREA_ORIGIN + DRAW_AREA_SIZE);
    // Draw tick for this position
    drawSingleTick(cr, s, lineLength, true, std::to_string(static_cast<int>(floor(pos))));
 
    drawSubTicks(cr, s, s + majorTickSpacing, 0, LINE_MULTIPLIER * lineLength);
    pos += majorInterval;
  }
}

Referenced by draw().

Here is the call graph for this function:

Here is the caller graph for this function:

operator=() [1/2]

Ruler Ruler::operator= ( const Ruler &  )

delete

operator=() [2/2]

Ruler Ruler::operator= ( Ruler &&  )

delete

setRange()

void Ruler::setRange	(	double	lower,
		double	upper
	)

Sets the range for the ruler to display.

Parameters

lower	Lower limit of the ruler range. Must be strictly less than upper.
upper	Upper limit of the ruler range. Must be strictly greater than lower.

{
  lowerLimit = lower;
  upperLimit = upper;
 
  updateMajorTickInterval();
 
  // We need to manually trigger the widget to redraw
  gtk_widget_queue_draw(drawingArea);
}

Here is the call graph for this function:

sizeAllocateCallback()

void Ruler::sizeAllocateCallback ( GtkWidget *  widget, GdkRectangle *  allocation, gpointer  data  )

staticprivate

A callback to be connected to a GtkDrawingArea's "size-allocate" signal. Updates the internal state of the ruler when the size of the ruler changes.

Parameters

widget	The widget that received the signal.
allocation	The region which has been allocated to the widget.
data	Pointer to a ruler instance.

{
  auto* ruler = static_cast<Ruler*>(data);
 
  const int width  = gtk_widget_get_allocated_width(widget);
  const int height = gtk_widget_get_allocated_height(widget);
 
  ruler->updateAllocatedSize(width, height);
}

updateAllocatedSize()

void Ruler::updateAllocatedSize ( int  newWidth, int  newHeight  )

private

Updates the stored allocated size of the ruler.

Parameters

newWidth	The newWidth of the ruler in pixels.
newHeight	The newHeight of the ruler in pixels.

{
  this->width  = newWidth;
  this->height = newHeight;
  drawStrategy->setAllocatedSize(newWidth, newHeight);
 
  updateMajorTickInterval();
}

Here is the call graph for this function:

updateMajorTickInterval()

void Ruler::updateMajorTickInterval ( )

private

Calculates an appropriate interval between major ticks, given the current range and dimensions.

{
  const double ALLOCATED_SIZE = drawStrategy->getDrawAreaSize();
 
  // lowerLimit could equal upperLimit, ALLOCATED_SIZE could be 0
  if(lowerLimit < upperLimit && 0 < ALLOCATED_SIZE)
  {
    // Calculate the interval between major ruler ticks
    majorInterval = RulerCalculations::calculateInterval(lowerLimit, upperLimit, ALLOCATED_SIZE);
    // Calculate the spacing in pixels between major ruler ticks
    majorTickSpacing = RulerCalculations::intervalPixelSpacing(majorInterval, lowerLimit, upperLimit, ALLOCATED_SIZE);
  }
  else
  {
    // Arbitrary numbers
    majorInterval    = 10;
    majorTickSpacing = 10;
  }
}

Referenced by setRange(), and updateAllocatedSize().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Data Documentation

DEFAULT_LOWER

constexpr double Ruler::DEFAULT_LOWER {0}

staticconstexprprivate

DEFAULT_UPPER

constexpr double Ruler::DEFAULT_UPPER {10}

staticconstexprprivate

drawingArea

GtkWidget* Ruler::drawingArea {}

private

Referenced by create(), setRange(), and ~Ruler().

drawStrategy

RulerDrawStrategy::Ptr Ruler::drawStrategy

private

Referenced by draw(), drawSingleTick(), drawSubTicks(), drawTicks(), updateAllocatedSize(), and updateMajorTickInterval().

FONT_SIZE

constexpr double Ruler::FONT_SIZE {11}

staticconstexprprivate

Referenced by drawSingleTick().

height

int Ruler::height {}

private

Referenced by draw(), sizeAllocateCallback(), and updateAllocatedSize().

LABEL_ALIGN

constexpr double Ruler::LABEL_ALIGN {0.7}

staticconstexprprivate

Alignment of tick label along the tick line as a fraction of line height.

Referenced by drawSingleTick().

LABEL_OFFSET

constexpr double Ruler::LABEL_OFFSET {4}

staticconstexprprivate

Offset of tick label from the tick line in pixels.

Referenced by drawSingleTick().

LINE_MULTIPLIER

constexpr double Ruler::LINE_MULTIPLIER {0.6}

staticconstexprprivate

The length of a tick one "level" down, as a fraction of the line length of the ticks one level up.

Referenced by drawSubTicks(), and drawTicks().

LINE_WIDTH

constexpr double Ruler::LINE_WIDTH {1}

staticconstexprprivate

Referenced by draw(), and drawSingleTick().

lineColor

GdkRGBA Ruler::lineColor {0, 0, 0, 1}

private

Referenced by draw().

lowerLimit

double Ruler::lowerLimit {DEFAULT_LOWER}

private

Referenced by draw(), drawTicks(), setRange(), and updateMajorTickInterval().

MAJOR_TICK_LENGTH

constexpr double Ruler::MAJOR_TICK_LENGTH {0.8}

staticconstexprprivate

Length of the major tick lines as a fraction of the width/height.

Referenced by draw().

majorInterval

int Ruler::majorInterval {1}

private

The chosen interval between major ticks.

Referenced by draw(), drawTicks(), and updateMajorTickInterval().

majorTickSpacing

int Ruler::majorTickSpacing {}

private

The space between major ticks when drawn.

Referenced by drawTicks(), and updateMajorTickInterval().

MIN_SPACE_SUBTICKS

constexpr int Ruler::MIN_SPACE_SUBTICKS {5}

staticconstexprprivate

The minimum space between sub-ticks.

Referenced by drawSubTicks().

SUBTICK_SEGMENTS

constexpr static std::array<int, 2> Ruler::SUBTICK_SEGMENTS {5, 2}

staticconstexprprivate

Each space between major ticks is split into 5 smaller segments and those segments are split into 2. (Assuming there's enough space.)

Referenced by drawSubTicks().

upperLimit

double Ruler::upperLimit {DEFAULT_UPPER}

private

Referenced by draw(), drawTicks(), setRange(), and updateMajorTickInterval().

width

int Ruler::width {}

private

Referenced by draw(), sizeAllocateCallback(), and updateAllocatedSize().

---

The documentation for this class was generated from the following files:

• gui/ruler/inc/ruler.hh
• gui/ruler/src/ruler.cc