Web Tools (for use with Emscripten)¶
D3 Data Visualization Tools¶
Animations¶
Manage animations on a web site.
To build an animation, you must provide a function to be run repeatedly. When Start() is triggered, the function will be called 60 time per second (or as close as possible), until Stop() is caled.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Animate
- #include <Animate.hpp>
An object that, when active, repeatedly calls a function as fast as possible, to a maximum of 60 frames per second.
Parameters to the animation function can be:
double (representing time since the last frame)
a const reference to the animation object itself
nothing
Control methods: void Start() void Stop() void Step() void ToggleActive()
Access methods: bool GetActive() const bool GetDoStep() const double GetStartTime() const double GetPrevTime() const double GetCurTime() const double GetStepTime() const double GetRunTime() const int GetFrameCount() const
Config methods: void SetCallback(const std::function<void(const Animate &)> & fun) void SetCallback(const std::function<void(double)> & fun) void SetCallback(const std::function<void()> & fun)
Public Functions
-
Animate
() Setup an Animate object to call an anim_fun as fast as possible, at most 60 times a second. Call virtual function DoFrame() if no other functon is provided (which can be overridden if you derive a new class from Animate)
-
template<typename ...
W_TYPES
>Animate
(const anim_fun_t &fun, W_TYPES&... targets) Construct an Animate object with the function to run each animation step and zero or more UI elements that should be updated after each frame.
-
~Animate
()
-
Animate
(const Animate&) = delete Do not copy animations directly.
-
void
Start
() Start this animation running.
-
void
Stop
() Halt this animation for now.
-
void
Step
() Take a single step in this animation.
-
void
ToggleActive
() Toggle whether this animation is running or paused.
-
bool
GetActive
() const Determine if this animation is currently running.
-
bool
GetDoStep
() const Determine if this animation is currently in the process of running a single step.
-
double
GetStartTime
() const Return the time point that this animation started MOST RECENTLY.
-
double
GetPrevTime
() const Determine the time point when this animation last updated a frame.
-
double
GetCurTime
() const Get the current time of the animation.
-
double
GetStepTime
() const Determine how long the last step between frames took.
-
double
GetRunTime
() const Determine the total amount of time that this animation has run.
-
int
GetFrameCount
() const Determine how many total frames have existed thus far in this animation.
-
void
SetCallback
(const anim_fun_t &fun) Set a new function for this animation to call when running that takes a const reference to the Animation object as an argument.
-
void
SetCallback
(const std::function<void(double)> &fun) Set a new function for this animation to call when running that takes the amount of time since the last frame (a double) as an argument.
-
void
SetCallback
(const std::function<void()> &fun) Set a new function for this animation to call when running that takes no arguments.
-
Button
GetToggleButton
(const std::string &but_name, const std::string &start_label = "Start", const std::string &stop_label = "Stop") Get a toggle button that will start/stop this animation.
- Parameters
but_name
: The HTML identifier used for this button.start_label
: The name on the button when it will start the animation (default=”Start”)stop_label
: The name on the button when it will halt the animation (default=”Stop”)
Protected Types
Protected Functions
-
void
LoadTargets
()
-
void
AdvanceFrame
()
Protected Attributes
-
anim_fun_t
anim_fun
Function to repeatedly run for animation.
-
bool
active
Is this animation currently running?
-
bool
do_step
Should this animation take just a single step?
-
size_t
callback_id
Intenral ID for javascript to call back AdvanceFrame()
-
double
start_time
At what time did this animation most recently start?
-
double
prev_time
What was the time point of the previous frame?
-
double
cur_time
What time did the current frame start?
-
double
run_time
How much run time has accumulated?
-
int
frame_count
How many animation frames have gone by?
-
Button
toggle_but
A button to start/stop this animation.
-
Button
step_but
A button to advance this animation one step.
-
class
-
namespace
Attributes¶
An Attributes class for tracking non-style features about HTML objects.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Attributes
- #include <Attributes.hpp>
Maintains a map of attribute names to values for use in JavaScript Closely related to Style.h, which is for CSS-values.
Public Functions
-
Attributes
()
-
Attributes
(const Attributes&) = default
-
Attributes &
operator=
(const Attributes&) = default
-
int
GetSize
() const Return a count of the number of attributes that have been set.
-
Attributes &
DoSet
(const std::string &in_set, const std::string &in_val)
-
Attributes &
DoAddAttr
(const std::string in_attr, const std::string &in_val) Append a new value to an existing attribute
- Parameters
in_attr
: attribute namein_val
: attribute value to be added
-
template<typename
SET_TYPE
>
Attributes &Set
(const std::string &s, SET_TYPE v) Record that attribute “a” is set to value “v” (converted to string) and return this object.
-
Attributes &
Insert
(const Attributes &in_attr) Set all values from in_attr here as well. Return this object.
-
bool
Has
(const std::string &setting) const Return true/false based on whether “setting” has been given a value in this Attributes obj.
-
const std::string &
Get
(const std::string &setting) const Return the (string) value of “setting” that has been recorded in this Attributes obj.
-
void
Remove
(const std::string &setting)
-
void
Clear
() Remove all setting values.
-
void
Apply
(const std::string &widget_id) Apply ALL of the Attribute’s settings to dom element “widget_id”.
-
void
Apply
(const std::string &widget_id, const std::string &setting) Apply only a SPECIFIC attributes setting from the setting library to widget_id.
-
operator bool
() const Convert to true if there are any setting, false otherwise.
Public Static Functions
-
-
class
-
namespace
Canvas¶
Manage an HTML canvas object.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Canvas
: public internal::WidgetFacet<Canvas> - #include <Canvas.hpp>
Manage an HTML Canvas object.
Public Types
-
using
INFO_TYPE
= CanvasInfo
Public Functions
-
Canvas
(double w, double h, const std::string &in_id = "") Create a new canvas with the specified size and optional HTML identifier.
-
Canvas
(const Canvas &in) Link to an existing canvas.
-
Canvas
(const Widget &in)
-
Canvas
()
-
~Canvas
()
-
double
GetWidth
() const Get the pixel width of this Canvas.
-
double
GetHeight
() const Get the pixel height of this Canvas.
-
void
SetWidth
(double w) Set a new width for this Canvas.
-
void
SetHeight
(double h) Set a new height for this Canvas.
-
void
SetSize
(double w, double h) Set Canvas size.
-
template<typename ...
Ts
>
Canvas &Circle
(Point center, double _r, Ts&&... vals) Add a Circle to this canvas; provide constructor for the CanvasCircle with a position and radius as well as optional face color, line color, and line width.
-
template<typename ...
Ts
>
Canvas &Rect
(Point corner, double w, double h, Ts&&... vals) Add a Rectangle to this canvas at x,y with width w and heigh h. Optional face color and line color.
-
template<typename ...
Ts
>
Canvas &Image
(const emp::RawImage &image, Point corner, Ts&&... vals) Add an Image to this canvas at x,y with width w and heigh h.
-
template<typename ...
Ts
>
Canvas &Line
(double x1, double y1, double x2, double y2, Ts&&... vals) Add a Line from x1,y1 to x2,y2. Optional face color and line color.
-
template<typename ...
Ts
>
Canvas &MultiLine
(emp::Point p1, const emp::vector<emp::Point> &points, Ts&&... vals) Add a Line from x1,y1 to x2,y2. Optional face color and line color.
-
template<typename ...
Ts
>
Canvas &Text
(emp::Point p, Ts&&... vals) Add a string to this canvas at x,y with specified text. Optional face color and line color.
-
template<typename ...
Ts
>
Canvas &CenterText
(emp::Point p, Ts&&... vals) Add a string to this canvas centered at x,y with specified text. Optional face color and line color.
-
Canvas &
Draw
(const emp::Circle &circle, const std::string &fc = "", const std::string &lc = "") Draw a circle onto this canvas.
-
Canvas &
Draw
(const CanvasShape &shape) Draw an arbitrary shape onto this canvas.
-
Canvas &
Rotate
(double angle) Rotate the entire canvas.
-
Canvas &
Clear
() Clear everything off of this canvas.
-
void
DownloadPNG
() const Download a PNG image of a canvas.
-
void
DownloadPNG
(const std::string &fname) const Download a PNG image of a canvas.
-
void
SavePNG
(const std::string &fname) const Save a PNG image of a canvas with node.js.
Protected Functions
-
CanvasInfo *
Info
()
-
const CanvasInfo *
Info
() const
-
Canvas
(CanvasInfo *in_info)
Friends
- friend class CanvasInfo
-
using
-
class
-
namespace
Canvas Utilities¶
Various versions of the Draw() function to draw images onto a canvas.
Each version of
Draw() takes a canvas widget and some form of data to be drawn on the widget, such as a circle, a bit matrix, or a geometric surface.- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
Functions
-
void
Draw
(Canvas canvas, const emp::Circle &circle, const std::string &fill = "", const std::string &line = "") Draw a Circle onto the canvas.
-
template<size_t
COLS
, size_tROWS
>
voidDraw
(Canvas canvas, const BitMatrix<COLS, ROWS> &matrix, double w, double h) Draw a BitMatrix onto a canvas using black and white squares (can specify cell width and height)
-
template<typename ...
BODY_TYPES
>
voidDraw
(Canvas canvas, const Surface<BODY_TYPES...> &surface, const emp::vector<std::string> &color_map) Draw a Surface, specifying the full colormap to be used. The surface has a range of circle bodies, each with a color id.
- Parameters
canvas
: The Canvas to draw on.surface
: A surface containing a set of shapes to draw.color_map
: Mapping of values to the colors with which they should be associated.
-
template<typename ...
BODY_TYPES
>
voidDraw
(Canvas canvas, const Surface<BODY_TYPES...> &surface, size_t num_colors) Draw a Surface, just specifying the number of colors (and using a generated hue map). The surface has a range of circle bodies, each with a color id.
- Parameters
canvas
: The Canvas to draw on.surface
: A surface containing a set of shapes to draw.num_colors
: The number of distinct colors to use in visualization.
-
template<typename
BODY_TYPE
>
voidDraw
(Canvas canvas, const Surface2D<BODY_TYPE> &surface, const emp::vector<std::string> &color_map) Draw a Surface2D, specifying the full colormap to be used. The surface has a range of circle bodies, each with a color id.
- Parameters
canvas
: The Canvas to draw on.surface
: A surface containing a set of shapes to draw.color_map
: Mapping of values to the colors with which they should be associated.
-
template<typename
BODY_TYPE
>
voidDraw
(Canvas canvas, const Surface2D<BODY_TYPE> &surface, size_t num_colors) Draw a Surface2D, just specifying the number of colors (and using a generated hue map). The surface has a range of circle bodies, each with a color id.
- Parameters
canvas
: The Canvas to draw on.surface
: A surface containing a set of shapes to draw.num_colors
: The number of distinct colors to use in visualization.
-
void
Draw
(Canvas canvas, const emp::vector<emp::vector<size_t>> &grid, const emp::vector<std::string> &color_map, std::string line_color, double cell_width, double cell_height, double offset_x, double offset_y) Draw a grid onto a canvas.
- Parameters
canvas
: The Canvas to draw on.grid
: A vector of vectors of color IDs.color_map
: Mapping of values to the colors with which they should be associated.line_color
: The background line color for the grid.cell_width
: How many pixels wide is each cell to draw?cell_height
: How many pixels tall is each cell to draw?offset_x
: How far should we shift the grid relative to the left side of the canvas?offset_y
: How far should we shift the grid relative to the top of the canvas?
-
void
Draw
(Canvas canvas, const emp::vector<emp::vector<size_t>> &grid, const emp::vector<std::string> &color_map, std::string line_color, double cell_w, double cell_h) Draw a grid onto a canvas, but without offsets provided the grid is centered.
- Parameters
canvas
: The Canvas to draw on.grid
: A vector of vectors of color IDs.color_map
: Mapping of values to the colors with which they should be associated.line_color
: The background line color for the grid.cell_w
: How many pixels wide is each cell to draw?cell_h
: How many pixels tall is each cell to draw?
-
void
Draw
(Canvas canvas, const emp::vector<emp::vector<size_t>> &grid, const emp::vector<std::string> &color_map, std::string line_color = "black") Draw a grid onto a canvas, but without cell size provided maximize to fill the canvas!
- Parameters
canvas
: The Canvas to draw on.grid
: A vector of vectors of color IDs.color_map
: Mapping of values to the colors with which they should be associated.line_color
: The background line color for the grid.
-
void
Draw
(Canvas canvas, const emp::vector<size_t> &grid, size_t grid_cols, const emp::vector<std::string> &color_map, std::string line_color, double cell_width, double cell_height, double offset_x, double offset_y) Draw a vector onto a canvas as a grid.
- Parameters
canvas
: The Canvas to draw on.grid
: A vector of vectors of color IDsgrid_cols
: Number of columns in the gridcolor_map
: Mapping of values to the colors with which they should be associated.line_color
: The background line color for the gridcell_width
: How many pixels wide is each cell to draw?cell_height
: How many pixels tall is each cell to draw?offset_x
: How far should we shift the grid relative to the left side of the canvas?offset_y
: How far should we shift the grid relative to the top of the canvas?
-
void
Draw
(Canvas canvas, const StateGrid &state_grid, const emp::vector<std::string> &color_map, std::string line_color = "black") Draw a state grid onto a canvas.
-
void
DrawGridBG
(Canvas canvas, size_t rows, size_t cols, const std::string &bg_color, const std::string &line_color) Draw a grid as the background of a canvas. Since this is a BG, clear the canvas first.
- Parameters
canvas
: The Canvas to draw on.rows
: Number of rows to draw in the grid.cols
: Number of columns to draw in the grid.bg_color
: The background color for the grid.line_color
: The color of the liens on the grid.
-
template<typename
CONTAINER_T
, typenamePOINT_FUN_T
, typenameCOLOR_FUN_T
>
voidDrawPoints
(Canvas canvas, CONTAINER_T &&container, double radius, POINT_FUN_T &&point_fun, COLOR_FUN_T &&color_fun, const std::string &line_color = "black")
-
void
-
namespace
Canvas Actions¶
Define a base class for all actions that can be done to widgets, plus simple actions.
CanvasAction objects modify the appearance of a canvas and can be tracked to reconstruct the state of the canvas from scratch.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
Other, more specific actions defined here are: CanvasStrokeColor CanvasRotate CanvasFont
See also CanvasShape.h for more actions.
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
CanvasAction
- #include <CanvasAction.hpp>
Base class to maintain canvas actions.
Subclassed by emp::web::CanvasFont, emp::web::CanvasImage, emp::web::CanvasRotate, emp::web::CanvasShape, emp::web::CanvasStrokeColor
Public Functions
-
CanvasAction
()
-
CanvasAction
(const CanvasAction&)
-
~CanvasAction
()
-
void
Apply
() = 0 Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const = 0 Make a copy of the current action.
-
-
class
CanvasFont
: public emp::web::CanvasAction - #include <CanvasAction.hpp>
Change the default font to be used.
Public Functions
-
CanvasFont
(const std::string &f)
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
Protected Attributes
-
std::string
font
-
-
class
CanvasImage
: public emp::web::CanvasAction - #include <CanvasAction.hpp>
Change the default font to be used.
Public Functions
-
CanvasImage
(const RawImage &raw_image, double _x = 0.0, double _y = 0.0, double _w = 0.0, double _h = 0.0)
-
CanvasImage
(const std::string &url, double _x = 0.0, double _y = 0.0, double _w = 0.0, double _h = 0.0)
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
-
-
class
CanvasRotate
: public emp::web::CanvasAction - #include <CanvasAction.hpp>
Rotate the entire canvas for subsequent drawings.
Public Functions
-
CanvasRotate
(double a)
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
Protected Attributes
-
double
angle
-
-
class
CanvasStrokeColor
: public emp::web::CanvasAction - #include <CanvasAction.hpp>
Set the line color on subsequent draw-related actions.
Public Functions
-
CanvasStrokeColor
(const std::string &c)
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
Protected Attributes
-
std::string
color
Color to use.
-
-
class
-
namespace
Canvas Shapes¶
Define simple shapes to draw on a canvas.
Canvas shapes can be definied in detail, describing how they modify a canvas.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
Other, more specific actions defined here are: CanvasCircle CanvasRect
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
CanvasCircle
: public emp::web::CanvasShape - #include <CanvasShape.hpp>
Track a circle shape to be drawn on a canvas.
Public Functions
-
CanvasCircle
(double _x, double _y, double _r, const std::string &fc = "", const std::string &lc = "", double lw = 1.0)
-
CanvasCircle
(Point _p, double _r, const std::string &fc = "", const std::string &lc = "", double lw = 1.0)
-
CanvasCircle
(emp::Circle circle, const std::string &fc = "", const std::string &lc = "", double lw = 1.0)
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
Private Members
-
double
radius
Circle radius.
-
-
class
CanvasClearRect
: public emp::web::CanvasShape - #include <CanvasShape.hpp>
Clear a rectangular area in a canvas.
Public Functions
-
CanvasClearRect
(Point _p, double _w, double _h)
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
Private Members
-
double
w
Rectangle widgth.
-
double
h
Rectangle height.
-
-
class
CanvasLine
: public emp::web::CanvasShape - #include <CanvasShape.hpp>
A line segment on the canvas.
Public Functions
-
CanvasLine
(double _x1, double _y1, double _x2, double _y2, const std::string &lc = "", double lw = 1.0) Y-position for second point of line segment.
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
Private Members
-
double
x2
-
double
y2
X-position for second point of line segment.
-
-
class
CanvasMultiLine
: public emp::web::CanvasShape - #include <CanvasShape.hpp>
A whole series of line segments on the canvas. Currently not working…
Public Functions
-
CanvasMultiLine
(double _x1, double _y1, const emp::vector<Point> &_points, const std::string &lc = "", double lw = 1.0)
-
CanvasMultiLine
(Point p1, const emp::vector<Point> &_points, const std::string &lc = "", double lw = 1.0)
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
-
-
class
CanvasPolygon
: public emp::web::CanvasShape - #include <CanvasShape.hpp>
An arbitrary-sized polygon to be drawn on a canvas.
Public Functions
-
CanvasPolygon &
AddPoint
(double x, double y)
-
CanvasPolygon &
AddPoint
(Point p)
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
-
CanvasPolygon &
-
class
CanvasRect
: public emp::web::CanvasShape - #include <CanvasShape.hpp>
Track a rectangle shape to be drawn on a canvas.
Public Functions
-
CanvasRect
(double _x, double _y, double _w, double _h, const std::string &fc = "", const std::string &lc = "")
-
void
Apply
() Apply current action to emp_i.ctx.
-
CanvasAction *
Clone
() const Make a copy of the current action.
Private Members
-
double
w
Rectangle widgth.
-
double
h
Rectangle height.
-
-
class
CanvasShape
: public emp::web::CanvasAction - #include <CanvasShape.hpp>
Define an arbitrary shape to draw on a canvas (base clase)
Subclassed by emp::web::CanvasCircle, emp::web::CanvasClearRect, emp::web::CanvasLine, emp::web::CanvasMultiLine, emp::web::CanvasPolygon, emp::web::CanvasRect, emp::web::CanvasText
Public Functions
-
CanvasShape
(double _x, double _y, const std::string &fc = "", const std::string &lc = "", double lw = 1.0)
-
~CanvasShape
()
-
void
MoveTo
(Point _p) Shift the position of this shape to a point.
-
void
MoveTo
(double _x, double _y) Shift the position of this shape to coordinates.
-
void
SetLineWidth
(double lw = 1.0) Setup details needed before drawing lines.
-
void
SetFillColor
(const std::string &color) Change the fill color of this shape.
-
void
SetLineColor
(const std::string &color) Change the stroke color of this shape.
-
void
ApplyColor
() Actually change the color on screen.
-
-
class
CanvasText
: public emp::web::CanvasShape - #include <CanvasShape.hpp>
Text to be written on a canvas.
Public Functions
-
CanvasText
(Point p, const std::string &_text, const std::string &fc = "", const std::string &lc = "")
-
void
Apply
() Apply current action to emp_i.ctx.
-
void
Center
(bool c = true) Center this text.
-
bool
GetCenter
() const Identify if text is centered.
-
CanvasAction *
Clone
() const Make a copy of the current action.
Protected Attributes
-
std::string
text
Specific text to be written.
-
bool
center
Should this text be centered (or is anchor on left side)?
-
-
class
-
namespace
Color maps¶
Tools to dynamically build (and cache) color maps.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
-
namespace
emp
If we are in emscripten, make sure to include the header.
Functions
-
std::string
ColorHSL
(double h, double s, double l) Generate a string to describe a JS color out of HSL values.
-
std::string
ColorRGB
(int r, int g, int b) Generate a string to describe a JS color out of RGB values.
-
std::string
ColorRGB
(int r, int g, int b, double a) Generate a string to describe a JS color with an alpha channel.
-
std::string
ColorHSV
(double h, double s, double v) Generate a string to describe a JS color out of HSV values.
-
std::string
Commands¶
A set of command-defining classes that can be fed into widgets using the << operator.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
Variables
-
const PrintStr endl ("<br>")
Pre-define emp::endl to insert a “<br>” and thus acting like a newline.
-
class
Close
: public WidgetCommand - #include <commands.hpp>
The Close command will prevent the specified widget from accepting further appends (and instead revert to trying parents)
Public Functions
-
Close
(const std::string &id)
-
bool
Trigger
(internal::WidgetInfo &w) const override
-
const std::string &
GetID
() const
Private Members
-
std::string
close_id
-
-
-
namespace
Divs¶
Div Widgets maintain an ordered collection of other widgets in an HTML div.
When printed to the web page, these internal widgets are presented in order.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
To create a Div:
emp::web::Div my_div(“name”);
To use a Div:
my_div << “Add this text!” << emp::web::Image(“my_image.png”) << “<br>”;
To register a Div in a Document:
my_doc << my_div;
- Note
Formerly called Slate.h
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Div
: public internal::WidgetFacet<Div> - #include <Div.hpp>
A widget to track a div in an HTML file, and all of its contents.
Subclassed by emp::prefab::Card, emp::prefab::CommentBox, emp::prefab::ConfigPanel, emp::prefab::Modal, emp::prefab::ValueBox, emp::web::Document, emp::web::Element
Public Types
-
using
INFO_TYPE
= internal::DivInfo
Public Functions
-
Div
(const std::string &in_name = "")
-
Div
(const Div &in)
-
Div
(const Widget &in)
-
~Div
()
-
double
ScrollTop
() const Where is the top of the scroll region?
-
Div &
ScrollTop
(double in_top) Set the scroll position.
-
void
Clear
() Clear the contents of this div.
-
void
ClearChildren
() Remove all child widgets from this div.
-
bool
HasChild
(const Widget &test_child) const Determine if a specified widget is internal to this one.
-
void
Deactivate
(bool top_level) override Remove this widget from the current document.
-
Widget &
Find
(const std::string &test_name) Get an internal widget to this div, by the specified name.
-
bool
HasChild
(const std::string &test_name) const Determine if a specified widget is internal to this one.
Protected Functions
-
internal::DivInfo *
Info
()
-
const internal::DivInfo *
Info
() const
-
Div
(internal::DivInfo *in_info)
-
using
-
class
-
namespace
Documents¶
Manage an entire document.
The Document class is built off of Div, but initializes the EMP web framework, if neeeded, and activates itself. It also provides quick ways to add and lookup widgets.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
For example, you can use doc.AddButon(…) to add a new button to the document, where the … can be any of the mechanisms to build a new button. This technique works for any widget type.
You can also look up any widget by name. For example, if you previously created a Canvas widget with the HTML id “my_canvas”, you can look it up later by using doc.Canvas(“my_canvas”)
Defines
-
emp_main
Useful functions for emscripten¶
Specialized, useful function for Empirical.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
Defines
-
AlertVar
(VAR)
-
namespace
emp
If we are in emscripten, make sure to include the header.
Functions
-
void
DelayCall
(const std::function<void()> &in_funint delay, ) Call a function after a specified amount of time.
-
void
OnResize
(const std::function<void()> &in_fun) Provide a function to call whenever a window’s size changes (no arguments).
-
void
OnResize
(const std::function<void(int, int)> &in_fun) Provide a function to call whenever a window’s size changes (new size as arguments)
-
double
GetTime
() Get the current time, as provided by the web browser.
-
int
GetWindowInnerWidth
() Determine with width of the current window.
-
int
GetWindowInnerHeight
() Determine with height of the current window.
-
void
SetBackgroundColor
(const std::string color) Set the background color of this web page.
-
void
SetColor
(const std::string color)
-
void
SetCursor
(const char *type)
-
void
OpenWindow
(const std::string &url)
-
void
Event Handling¶
Event handlers that use JQuery.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
Functions
-
template<typename
FUN_TYPE
>
voidOnDocumentReady
(FUN_TYPE &&fun) Runs the specified function when the document is finished loading and being set up.
-
template<typename
FUN_TYPE
>
voidOnDocumentLoad
(FUN_TYPE &&fun) Runs the specified function when the document is finished loading.
-
struct
Event
- #include <events.hpp>
Data common to all web events.
Subclassed by emp::web::KeyboardEvent, emp::web::MouseEvent, emp::web::WheelEvent
Public Functions
-
template<int
ARG_ID
>
voidLoadFromArg
()
Public Members
-
bool
bubbles
Is this a bubbling event?
-
bool
cancelable
Can the default action be prevented?
-
template<int
-
struct
KeyboardEvent
: public emp::web::Event - #include <events.hpp>
Keyboard-specific information about web events.
Public Functions
-
template<int
ARG_ID
>
voidLoadFromArg
()
Public Members
-
bool
altKey
Was “ALT” key was pressed?
-
bool
ctrlKey
Was “CTRL” key pressed?
-
bool
metaKey
Was “META” key pressed?
-
bool
shiftKey
Was “SHIFT” key pressed?
-
int
charCode
Unicode character pressed.
-
int
keyCode
Which key was pressed on the keyboard (e.g., ‘a’ and ‘A’ are the same)
-
template<int
-
struct
MouseEvent
: public emp::web::Event - #include <events.hpp>
Mouse-specific information about web events.
Public Functions
-
template<int
ARG_ID
>
voidLoadFromArg
()
Public Members
-
bool
altKey
Was “ALT” key was pressed?
-
bool
ctrlKey
Was “CTRL” key pressed?
-
bool
metaKey
Was “META” key pressed?
-
bool
shiftKey
Was “SHIFT” key pressed?
-
int
button
Which mouse button was pressed? -1=none (0/1/2)
-
int
detail
How many clicks happened in short succession?
-
int
clientX
X-mouse postion, relative to current window.
-
int
clientY
Y-mouse postion, relative to current window.
-
int
screenX
X-mouse position, relative to the screen.
-
int
screenY
Y-mouse position, relative to the screen.
-
template<int
-
struct
WheelEvent
: public emp::web::Event - #include <events.hpp>
Mouse-wheel-specific information about web events.
Public Functions
-
template<int
ARG_ID
>
voidLoadFromArg
()
Public Members
-
int
deltaX
Horizontal scroll amount.
-
int
deltaY
Vertical scroll amount.
-
int
deltaZ
Scroll amount of a mouse wheel for the z-axis.
-
int
deltaMode
The unit of measurements for delta values (pixels, lines or pages)
-
template<int
-
template<typename
-
namespace
File Input¶
Specs for the FileInput widget (click on to upload a file)
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
FileInput
: public internal::WidgetFacet<FileInput> - #include <FileInput.hpp>
FileInput will convert the file to a std::string and pass the result to a designated function.
To create a new file input, you must pass it a void function that takes a const std::string & as its only argument. When a file is loaded, the specified function is called and the body of the file is passed in as the string.
Public Types
-
using
INFO_TYPE
= FileInputInfo
Public Functions
-
FileInput
(const std::function<void(const std::string&)> &in_cb, const std::string &in_id = "", ) Create a new Fileinput; supply the function to call with the file contents as a string (and optionally the HTML identifier to be used).
-
FileInput
(const std::function<void(const emp::File&)> &cb, const std::string &in_id = "", ) Create a new FileInput; supply the function to call with the file contents as a File object (and optionally the HTML identifier to be used).
-
FileInput
(const Widget &in)
-
~FileInput
()
-
FileInput &
Callback
(const std::function<void(const std::string&)> &in_cb) Change the callback function to use when a new file is loaded.
-
bool
HasAutofocus
() const Determine if this object currently has autofocus.
-
bool
IsDisabled
() const Determine if this object is currently disabled.
Protected Functions
-
FileInputInfo *
Info
()
-
const FileInputInfo *
Info
() const
-
FileInput
(FileInputInfo *in_info)
Friends
- friend class FileInputInfo
-
using
-
class
-
namespace
Font¶
Maintains basic information about a font to be used in HTML.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Font
- #include <Font.hpp>
Maintain information about an HTML font.
Public Functions
-
Font
(const Font&) = default
-
Font
(Font&&) = default
-
Font
(const std::string &_family = "Helvetica", int _size = 15, const std::string &_color = "black", bool _bold = false, bool _italic = false)
-
Font
(int _size, const std::string &_color = "black", bool _bold = false, bool _italic = false)
-
~Font
()
-
const std::string &
GetFamily
() const - Return
font family
-
int
GetSize
() const - Return
font size (in pixels)
-
const std::string &
GetColor
() const - Return
font color
-
const std::string &
GetLineColor
() const - Return
color of lines through text (underline or strikethrough)
-
bool
IsBold
() const - Return
boolean indicating whether font is bold
-
bool
IsItalic
() const - Return
boolean indicating whether font is italic
-
bool
IsSmallcaps
() const - Return
boolean indicating whether font is in small caps
-
bool
IsUnderlined
() const - Return
boolean indicating whether font is underlined
-
bool
IsOverlined
() const - Return
boolean indicating whether font is overlined
-
bool
IsStrikethrough
() const - Return
boolean indicating whether font is strikethrough
-
bool
IsWavyLine
() const - Return
boolean indicating whether font is wavy line
-
bool
HasLine
() const - Return
boolean indicating whether font has any kind of line (underline, overline, or strikethrough)
-
Font &
SetFamily
(const std::string &_family) Sets font family to specified value
- Return
reference to this font for easy chaining
-
Font &
SetSize
(int _size) Sets font size to specified value
- Return
reference to this font for easy chaining
-
Font &
SetColor
(const std::string &_color) Sets font color to specified value
- Return
reference to this font for easy chaining
-
Font &
SetLineColor
(const std::string &_color) Sets color of any lines through, under, or over this font
- Return
reference to this font for easy chaining
-
Font &
SetBold
(bool _in = true) Sets whether font is bold
- Return
reference to this font for easy chaining
-
Font &
SetItalic
(bool _in = true) Sets whether font is italic
- Return
reference to this font for easy chaining
-
Font &
SetSmallcaps
(bool _in = true) Sets whether font is small caps
- Return
reference to this font for easy chaining
-
Font &
SetUnderlined
(bool _in = true) Sets whether font is underlined
- Return
reference to this font for easy chaining
-
Font &
SetOverlined
(bool _in = true) Sets whether font is overlined
- Return
reference to this font for easy chaining
-
Font &
SetStrikethrough
(bool _in = true) Sets whether font is strikethrough-ed
- Return
reference to this font for easy chaining
-
Font &
SetWavyLine
(bool _in = true) Sets whether font is wavy line
- Return
reference to this font for easy chaining
-
void
ConfigStyle
(Style &style) const Take a Style object an fill it out based on this font information.
-
Style
AsStyle
() const - Return
a style object filled out according to this font information
-
std::string
GetHTMLStart
() - Return
a string containing the html necessary to open a span element using this font.
-
std::string
GetHTMLEnd
() - Return
a string containing the html necessary to close a span element created by
GetHTMLStart()
-
bool
operator==
(const Font &_in) const Fonts will evaluate to equal if all of their properties are the same.
-
bool
operator!=
(const Font &_in) const Fonts will evaluate to equal if all of their properties are the same.
Protected Attributes
-
int
size
Font size (in px) to use.
-
std::string
line_color
Color of lines through the text (underline, linethrough, etc.)
-
bool
is_bold
Is this font bold?
-
bool
is_italic
Is this font italic?
-
bool
is_smallcaps
Should this text be in small caps?
-
bool
is_underlined
Should this text be underlined?
-
bool
is_overlined
Should this text have a line above it?
-
bool
is_linethrough
Should this text have a line through it?
-
bool
is_wavy_line
Should lines be made wavy?
-
-
class
-
namespace
Images¶
Easily load an image and place it in a document.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Image
: public internal::WidgetFacet<Image> - #include <Image.hpp>
The Image widget will load an image from a specified URL. For example, you can use emp::web::Image(“http://kripken.github.io/emscripten-site/_static/Emscripten_logo_full.png”) to load the emscripten logo from its website. These can be easily inserted into a web document using << and all JS callbacks (after loading) will be handled automatically.
You can also set the Alt-text with the Alt() function.
Public Types
-
using
INFO_TYPE
= ImageInfo
Public Functions
-
Image
(const std::string &in_url, const std::string &in_id = "") Create a new image, indicating the URL to load from.
-
Image
(const Widget &in)
-
~Image
()
Protected Functions
-
ImageInfo *
Info
()
-
const ImageInfo *
Info
() const
-
Image
(ImageInfo *in_info)
Friends
- friend class ImageInfo
-
using
-
class
-
namespace
Initialization¶
Define Initialize() and other functions to set up Empirical to build Emscripten projects.
Init.hpp should always be included if you are compiling Empirical’s web tools with Emscripten. It handles making sure that behind the scenes stuff is all set up properly. It also defines some useful stubs and dummy functions so that your code will still be possible to comple with a normal C++ compiler (although the web part won’t do anything, of course). These stubs are also helpful for avoiding confusion in linters and IDEs.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018.
Javascript Utilities¶
Tools for passing data between C++ and Javascript.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
Functions
-
std::map<std::string, std::string>
get_type_to_string_map
() This function returns a std::map mapping typeid names to the appropriate strings to describe those types in Javscript. This is useful when using getValue() from within MAIN_THREAD_EM_ASM macros.
For example, say we have a templated function that takes a pointer to type T. We find out the appropriate string for type T: std::map<const char*, std::string> type_map = GetTypeToStringMap(); std::string type_string = type_map[typeid(T).name()];
Now we can pass type_string.c_str() into MAIN_THREAD_EM_ASM: `MAIN_THREAD_EM_ASM({ var value = getValue($0, $1); }, pointer, type_string.c_str();`
-
template<typename
C
, class = typename C::value_type>
voidpass_array_to_javascript
(C values) This function can be called to pass an array, vector, or other container with contiguously stored data into Javascript. The array will be stored in emp.__incoming_array. Currently supports arrays containing all of the types defined in get_type_to_string_map, which are also all of the types that emscripten supports getting via pointer. This function also supports nested arrays, and arrays of objects created with introspective tuple structs.
-
template<std::size_t
SIZE
, typenameT
>
voidpass_array_to_cpp
(emp::array<T, SIZE> &arr, bool recurse = false) This function lets you pass an array from javascript to C++! It takes a reference to the array as an argument and populates it with the contents of emp.__outgoing_array.
Currently accepts arrays of ints, floats, doubles, chars, and std::strings The size of the passed array must be equal to the size of the array stored in emp.__outgoing_array
-
template<typename
T
>
voidpass_vector_to_cpp
(emp::vector<T> &arr, bool recurse = false) Same as pass_array_to_cpp, but lets you store values in a vector instead.
-
template<typename
KEY_T
, typenameVAL_T
>
voidpass_map_to_javascript
(const emp::map<KEY_T, VAL_T> &dict) This function can be called to pass a map into JavaScript. The resulting JavaScript object will be stored in emp.__incoming_map.
- Parameters
dict
: the map being passed into JavaScript
-
template<typename
KEY_T
, typenameVAL_T
, size_tSIZE
>
voidpass_map_to_javascript
(const emp::array<KEY_T, SIZE> &keys, const emp::array<VAL_T, SIZE> &values) This function can be called to pass two arrays of the same length into JavaScript (where a map is then created) One array should hold keys, and the other should hold values (note that the key-value pairs must line up across the arrays) The resulting JavaScript object will be stored in emp.__incoming_map.
- Parameters
keys
: an array holding the keys to the mapvalues
: an array holding the values to the map
-
int
GetViewPortSize
() Helper function that returns DOM view port size in pixels.
-
std::map<std::string, std::string>
JSWrap¶
Wrap a C++ function and convert it to an integer that can be called from Javascript.
To wrap a function, call:
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
uint32_t fun_id = emp::JSWrap(FunctionToBeWrapped, "JS_Function_Name");
`
To manually callback a function from Javascript, first set emp_i.cb_args
to an array of function arguments, then call empCppCallback( fun_id );
This all happens automatically if you use the emp.Callback(fun_id, args...)
function from Javascript.
The JS_Function_Name string is optional, but if you use it, the appropriate function will be automatically generated in Javascript by JSWrap, in the emp class.
For example, if you have:
int AddPair(int x, int y) { return x + y; }
`
You can wrap it with:
size_t fun_id = emp::JSWrap(AddPair, "AddPair");
And then in Javascript, you can simply call it as:
emp.AddPair(4, 5); // will return 9.
Functions
-
void
empDoCppCallback
(const size_t cb_id) This function is dispatched by empCppCallback. It should be dispatched on the thread hosting the main Empirical runtime. If running with Emscripten pthreads, that would be the worker thread hosting the main Empirical runtime. If not running with Emscripten pthreads, that would be the main browser thread. (In a few limited cases when running with Emscripten pthreads, this function is called on the main browser thread.)
-
void
empCppCallback
(const size_t cb_id) Once you use JSWrap to create an ID, you can call the wrapped function from Javascript by supplying CPPCallback with the id and all args. If running with Emscripten pthreads, this method is to be called from the DOM and it will forward the call to empDoCppCallback on the web worker hosting Empirical runtime. If not running with Emscripten pthreads, this method simply calls empDoCppCallback (on the main browser thread).
-
namespace
emp
If we are in emscripten, make sure to include the header.
Functions
-
template<typename
FUN_TYPE
>
size_tJSWrap
(const FUN_TYPE &in_fun, const std::string &fun_name = "", bool dispose_on_use = false) JSWrap takes a C++ function and wraps it in Javascript for easy calling in web code
- Return
the id of the function on the Javascript side
- Parameters
in_fun
: a C++ function to wrapfun_name
: optionally, a name to call the function on the Javascript sizedispose_on_use
: should we delete this function after using it?
-
template<typename
FUN_TYPE
>
size_tJSWrapOnce
(FUN_TYPE &&in_fun) If we want a quick, unnammed, disposable function, use JSWrapOnce.
-
void
JSDelete
(size_t fun_id) Cleanup a function pointer when finished with it.
-
template<typename
Keypress Manager¶
KeypressManager is a tracker for keypresses in HTML5 pages.
When a KeypressManager is created, it can be given functions to run in response to different types of key presses via overloaded version of the AddKeydownCallback method. Each of these accepts an order parameter that is optional and, if provided, will indicate the order in which tests should be performed to resolve a keypress. If order is not provided, tests will occur in the order that they were given to the manager.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
The specific versions of AddKeydownCallback are:
void AddKeydownCallback(std::function<bool(const emp::web::KeyboardEvent &)> cb_fun, int order=-1)
Link a function to the KeypressManager that is called for any unresolved keypress. The function must take in an emp::web::KeyboardEvent (which includes information about the specific key pressed as well as any modifiers such as SHIFT or CTRL) and it must return a boolean value indicating whether it has resolved the keypress.
void AddKeydownCallback(char key, std::function<void()> cb_fun, int order=-1)
Link a specific key to a target function to be called when that key is pressed. The function my return a void and take no arguments.
void AddKeydownCallback(const std::string & key_set, std::function<void()> cb_fun, int order=-1)
Same as the previous method, but will respond to any of the keys in the provided string.
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
KeypressManager
Public Functions
-
KeypressManager
()
-
~KeypressManager
()
-
int
GetFunCount
() const
-
int
GetNextOrder
() const
-
void
AddKeydownCallback
(std::function<bool(const KeyboardEvent&)> cb_fun, int order = -1, ) Link a function to the KeypressManager that is called for any unresolved keypress. The function must take in an emp::web::KeyboardEvent (which includes information about the specific key pressed as well as any modifiers such as SHIFT or CTRL) and it must return a boolean value indicating whether it has resolved the keypress.
-
void
AddKeydownCallback
(char key, std::function<void()> cb_funint order = -1, ) Link a specific key to a target function to be called when that key is pressed. The function my return a void and take no arguments. Specify keys as lowercase characters. To sepcify uppercase, you’ll need to monitor fo rthe shift modifier associated with a KeypressEvent.
-
void
AddKeydownCallback
(const std::string &key_set, const std::function<void()> &cb_funint order, ) Provide a whole set of keys that should all trigger the same function, including an ordering for priority. Specify keys as lowercase characters. To sepcify uppercase, you’ll need to monitor fo rthe shift modifier associated with a KeypressEvent.
Private Functions
-
bool
DoCallback
(const KeyboardEvent &evt_info)
Private Members
-
std::map<int, std::function<bool(const KeyboardEvent&)>>
fun_map
-
int
next_order
-
uint32_t
callback_id
-
-
class
-
namespace
Listeners¶
A class for tracking font event listeners for Widgets.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Listeners
- #include <Listeners.hpp>
Track a set of JavaScript Listeners with their callback IDs.
Public Functions
-
Listeners
()
-
Listeners
(const Listeners&) = default
-
size_t
GetSize
() const How many listeners are we tracking?
-
Listeners &
Set
(const std::string &name, size_t fun_id) Use a pre-calculated function ID with a new listener.
-
template<typename ...
Ts
>
Listeners &Set
(const std::string &name, const std::function<void(Ts... args)> &in_fun) Calculate its own function ID with JSWrap.
-
bool
Has
(const std::string &event_name) const Determine if a specified listener exists.
-
size_t
GetID
(const std::string &event_name) Get the ID associated with a specific listener.
-
void
Clear
() Remove all listeners.
-
void
Remove
(const std::string &event_name) Remove a specific listener.
-
void
Apply
(const std::string &widget_id) Apply all of the listeners being tracked.
-
operator bool
() const true/false : do any listeners exist?
Public Static Functions
-
-
class
-
namespace
Raw Image¶
Handle the fundamental loading of an image (without Widget tracking)
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
class
RawImage
- #include <RawImage.hpp>
Fundamental information about a single image.
Public Functions
-
RawImage
(const std::string &url)
-
RawImage
(const RawImage&) = default
-
~RawImage
()
-
int
GetID
() const
-
const std::string &
GetURL
() const
-
bool
HasLoaded
() const
-
bool
HasError
() const
-
void
OnLoad
(const std::function<void()> &callback_fun) Add a new function to be called when the image finishes loading.
-
void
OnError
(const std::function<void()> &callback_fun) Add a new function to be called if an image load has an error.
Private Members
-
Ptr<internal::ImageInfo>
info
Private Static Functions
-
internal::ImageManager &
GetManager
()
-
-
class
Selector¶
Specs for the Selector widget.
A Selector widget provides the user with a pull-down menu. It can be examined at any time (via GetSelectID()) or else alerts call a designated function when a particular option is chosen.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
UI::Selector sel(“sel”);
sel.SetOption(“Option 1”); sel.SetOption(“Option B”, TriggerB) ; sel.SetOption(“Option the Third”, [](){ emp::Alert(“3 chosen!”} ); sel.SetOption(“Option IV”);
In this example, the second option will call TriggerB when it is chosen, while the third option will call the provided lambda function.
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Selector
: public internal::WidgetFacet<Selector> Public Types
-
using
INFO_TYPE
= SelectorInfo
Public Functions
-
Selector
(const std::string &in_id = "")
-
Selector
(const Selector &in)
-
Selector
(const Widget &in)
-
~Selector
()
-
size_t
GetSelectID
() const Get the ID of the currently active selection.
-
size_t
GetNumOptions
() const Get the total number of options setup in the selector.
-
const std::string &
GetOption
(size_t id) const Get the label associated with a specific option ID.
-
bool
HasAutofocus
() const Determine if the selector has autofocus.
-
bool
IsDisabled
() const Is the selector currently disabled?
-
Selector &
SelectID
(size_t id) Set a specific ID as currently active.
-
Selector &
SetOption
(const std::string &in_option, const std::function<void()> &in_cb) Add a new option to the selector and the function to be called if it is chosen.
-
Selector &
SetOption
(const std::string &in_option, const std::function<void()> &in_cbsize_t opt_id, ) Add an option to the selector associated with a specific ID (and the function to be called if it is chosen)
-
Selector &
SetOption
(const std::string &in_option) Set a selector option name, but no function to be called.
-
Selector &
SetOption
(const std::string &in_option, size_t opt_id) Set a specific selection option name, determined by the ID, but no function to call.
-
Selector &
Autofocus
(bool in_af) Update autofocus setting.
-
Selector &
Disabled
(bool in_dis) Update disabled status.
Protected Functions
-
SelectorInfo *
Info
()
-
const SelectorInfo *
Info
() const
-
Selector
(SelectorInfo *in_info)
Friends
- friend class SelectorInfo
-
using
-
class
-
namespace
Styles¶
A CSS class for tracking font style, etc.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Style
- #include <Style.hpp>
Class to maintain a map of setting names to values that can be easily ported over to JavaScript. A companial class, Attributes, also exists.
Public Functions
-
Style
()
-
Style
(const Style&) = default
-
Style
(Style&&) = default
-
size_t
GetSize
() const Return a count of the number of settings that have been set.
-
size_t
GetNClasses
() const Return a count of the number of classes that have been added.
-
template<typename
SET_TYPE
>
Style &Set
(const std::string &s, SET_TYPE v) Record that setting “s” is set to value “v” (converted to string) and return this object.
-
bool
Has
(const std::string &setting) const Return true/false based on whether “setting” has been given a value in this Style.
-
const std::string &
Get
(const std::string &setting) const Return the (string) value of “setting” that has been recorded in this Style.
-
void
Clear
() Remove all setting values and all classes.
-
void
Remove
(const std::string &setting) Remove a specific setting value.
-
void
RemoveClass
(const std::string &clss) Remove a specific class.
-
void
Apply
(const std::string &widget_id) Apply ALL of the style settings to a specified widget.
-
void
Apply
(const std::string &widget_id, const std::string &setting) Apply only a SPECIFIC style setting from the setting library.
-
operator bool
() const Have any settings be set?
-
-
class
-
namespace
Tables¶
Specs for the Table widget.
TableInfo is the core information for a table and has two helper classes: TableRowInfo and TableDataInfo. The Table class is a smart pointer to a TableInfo object.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
A Table is composed of a series of rows, each with the same number of columns. TableDataInfo may be muliple cells wide/tall, masking other cells.
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Table
: public emp::web::TableWidget Public Functions
-
Table
(size_t r, size_t c, const std::string &in_id = "")
-
Table
(const TableWidget &in)
-
Table
(const Widget &in)
-
Table
(internal::TableInfo *in_info, size_t _row, size_t _col)
-
Table
()
-
Table &
Clear
()
-
Table &
ClearStyle
()
-
Table &
ClearAttr
()
-
Table &
ClearListen
()
-
Table &
ClearExtras
()
-
Table &
ClearChildren
()
-
Table &
Rows
(size_t r) Resize the number of rows in the table.
-
Table &
Cols
(size_t c) Resize the number of columns in the table.
-
Table &
Resize
(size_t r, size_t c) Fully resize the table (both rows and columns)
-
Table &
SetColSpan
(size_t new_span) Setup the number of columns the current column group.
-
template<typename
SETTING_TYPE
>
Table &RowCSS
(size_t row_id, const std::string &setting, SETTING_TYPE &&value) Apply CSS to target row.
-
template<typename
SETTING_TYPE
>
Table &CellCSS
(size_t row_id, size_t col_id, const std::string &setting, SETTING_TYPE &&value) Apply CSS to target cell.
-
template<typename
SETTING_TYPE
>
Table &RowsCSS
(const std::string &setting, SETTING_TYPE &&value) Apply CSS to all rows. (: Should we use fancier jquery here?)
-
template<typename
SETTING_TYPE
>
Table &CellsCSS
(const std::string &setting, SETTING_TYPE &&value) Apply CSS to all cells.
-
-
class
TableWidget
: public internal::WidgetFacet<TableWidget> Subclassed by emp::web::Table
Public Types
-
using
INFO_TYPE
= internal::TableInfo
Public Functions
-
TableWidget
(size_t r, size_t c, const std::string &in_id = "")
-
TableWidget
(const TableWidget &in)
-
TableWidget
(const Widget &in)
-
TableWidget
()
-
~TableWidget
()
-
size_t
GetNumCols
() const
-
size_t
GetNumRows
() const
-
size_t
GetNumCells
() const
-
void
PrepareAppend
() override
-
size_t
GetCurRow
() const Determine which row currently has focus.
-
size_t
GetCurCol
() const Determine which column currently has focus.
-
void
ClearTable
()
-
void
ClearRows
()
-
void
ClearRow
(size_t r)
-
void
ClearCol
(size_t c)
-
void
ClearRowGroup
(size_t r)
-
void
ClearColGroup
(size_t c)
-
void
ClearCells
()
-
void
ClearCell
(size_t r, size_t c)
-
TableCell
GetCell
(size_t r, size_t c) const Focus on a specifc cell in the table.
-
TableRow
GetRow
(size_t r) const Focus on a specifc row in the table.
-
TableCol
GetCol
(size_t c) const Focus on a specifc column in the table.
-
TableRowGroup
GetRowGroup
(size_t r) const Focus on a specifc group of rows in the table.
-
TableColGroup
GetColGroup
(size_t c) const Focus on a specifc group of columns in the table.
-
Table
GetTable
() const Focus on a the entire table.
-
Widget
AddText
(size_t r, size_t c, const std::string &text) Add text to a specified cell in the table.
-
Widget
AddHeader
(size_t r, size_t c, const std::string &text) Set a specified cell to be a table header.
Protected Types
-
using
parent_t
= internal::WidgetFacet<TableWidget>
Protected Functions
-
internal::TableInfo *
Info
() Get a properly cast version of info.
-
internal::TableInfo *const
Info
() const
-
TableWidget
(internal::TableInfo *in_info, size_t _row = 0, size_t _col = 0)
-
void
DoCSS
(const std::string &setting, const std::string &value) override Apply CSS to appropriate component based on current state.
-
void
DoAttr
(const std::string &setting, const std::string &value) override Apply CSS to appropriate component based on current state.
-
void
DoListen
(const std::string &event_name, size_t fun_id) override Apply CSS to appropriate component based on current state.
Protected Attributes
-
size_t
cur_row
-
size_t
cur_col
Friends
- friend class internal::TableInfo
-
using
-
class
-
namespace
Text¶
Specs for the Text widget.
A representation of text on a web page. Text Widgets can be included inside of Divs or Tables to cordon off a section of text (and will be automatically created when text is streamed into these other widgets). The primary benefit of explicitly creating your own text widget is to control the text style.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Text
: public internal::WidgetFacet<Text> - #include <Text.hpp>
A Text widget handles putting text on a web page that can be controlled and modified.
Public Types
-
using
INFO_TYPE
= TextInfo
Public Functions
-
Text
(const std::string &in_id = "")
-
Text
(const Text &in)
-
Text
(const Widget &in)
-
~Text
()
-
size_t
GetSize
() const How many text items are contained?
-
Text &
Clear
() Erase current text.
Friends
- friend class TextInfo
-
class
TextInfo
: public WidgetInfo Public Functions
-
std::string
GetType
() override
Protected Functions
-
TextInfo
(const std::string &in_id = "")
-
TextInfo
(const TextInfo&) = delete
-
~TextInfo
()
-
std::string
GetTypeName
() const override
-
bool
AppendOK
() const override
-
void
PreventAppend
() override
-
Widget
Append
(const std::function<std::string()> &in_fun) override Add a function that produces text to this widget. Every time the widget is re-drawn, the function will be re-run to get the latest version of the text. When a Live() function wraps a variable it simply makes sure that this version of Append is called so that the value of the variable is kept live.
-
void
GetHTML
(std::stringstream &HTML) override
Protected Attributes
-
DynamicString
strings
All string (and functions returning strings) in Text widget.
-
bool
append_ok
Can this Text widget be extended?
Private Members
-
friend Text
-
std::string
-
using
-
class
-
namespace
Text Areas¶
Specs for the TextArea widget.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2018
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
TextArea
: public internal::WidgetFacet<TextArea> - #include <TextArea.hpp>
An input field for text data. A function provided at creation time will be called each time the contents of the TextWidget are changed. The current text contents can also always be accessed with the GetText() member function.
Public Types
-
using
INFO_TYPE
= TextAreaInfo
Public Functions
-
TextArea
(const std::string &in_id = "") Build a text area with a specified HTML identifier.
-
TextArea
(std::function<void(const std::string&)> in_cb, const std::string &in_id = "", ) Build a text area with a specified function to call with every change.
-
TextArea
(const Widget &in)
-
~TextArea
()
-
TextArea &
SetAutofocus
(bool in_af) Make this text area have focus by default.
-
TextArea &
SetCallback
(const std::function<void(const std::string&)> &in_cb) Change the callback function for this TextArea.
-
TextArea &
SetDisabled
(bool in_dis) Gray out this text area.
-
bool
HasAutofocus
() const Does this widget have auto focus set?
-
bool
IsDisabled
() const Is this widget currently disabled?
Protected Functions
-
TextAreaInfo *
Info
()
-
const TextAreaInfo *
Info
() const
-
TextArea
(TextAreaInfo *in_info)
Friends
- friend class TextAreaInfo
-
using
-
class
-
namespace
Tweens¶
A Tween manages the gradual shift in properties of one or more widgets over time.
To create a Tween, a duration must be specified, along with an optional default target. Once a Tween is setup, paths can be added to it, which represent the changes that should occur over the specified duration.
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
A path can be a function to call (with the 0.0 to 1.0 fraction of the time that’s gone by) or a variable to set to the current fraction. Dependants can also be set to refresh with each Tween update.
Available methods include: Tween & AddPath(std::function<void(double)> set_fun, double start_val, double end_val, std::function<double(double)> timing=LINEAR); Tween & AddPath(double & set_var, double start_val, double end_val, std::function<double(double)> timing=LINEAR); Tween & AddDependant(Widget w); void Start(); void Stop();
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
class
Tween
Public Functions
-
Tween
(double d = 1.0, const Widget &t = nullptr) Build a new tween, specifying the duration it should run for and the widget it should modify.
-
~Tween
()
-
double
GetDuration
() const Retrieve the full duration of this Tween.
-
Tween &
AddPath
(std::function<void(double)> set_fun, double start_val, double end_val, std::function<double(double)> timing = LINEAR) Alter the path of the change that this tween should take and the function it should call.
-
Tween &
AddPath
(double &set_var, double start_val, double end_val, std::function<double(double)> timing = LINEAR) Alter the path of the change that this tween should take and the variable it should modify.
-
Tween &
AddPath
(Widget w, std::string setting, double start_val, double end_val) Alter the path of the change that this tween should take and the widget setting it should alter. (TODO!)
-
Tween &
AddUpdate
(std::function<void(void)> ud_fun) Add an additional function to update as the Tween runs.
-
void
Start
() Start running this Tween, as configured.
-
void
Stop
() Pause this Tween.
Private Functions
-
void
AdvanceFrame
()
Private Members
-
double
duration
-
Widget
default_target
-
bool
running
-
size_t
callback_id
-
double
start_time
-
double
cur_time
-
double
run_time
Private Static Functions
-
double
LINEAR
(double in)
-
struct
Event
-
struct
Path
Public Functions
-
void
Set
(const double frac)
-
void
-
-
class
-
namespace
Widgets¶
A collection of extra details about HTML Widgets (attributes, style, listerns)
- Note
This file is part of Empirical, https://github.com/devosoft/Empirical
- Copyright
Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
- Date
2015-2017
-
namespace
emp
If we are in emscripten, make sure to include the header.
-
namespace
web
-
struct
WidgetExtras
Public Functions
-
bool
HasStyle
(const std::string &setting) const
-
void
RemoveStyle
(const std::string &setting)
-
bool
HasAttr
(const std::string &setting) const
-
void
RemoveAttr
(const std::string &setting)
-
void
Apply
(const std::string &name) Apply all HTML details associated with this widget.
-
void
Clear
() Clear all of style, attributes, and listeners.
-
operator bool
() const Have any details been set?
Public Members
-
Attributes
attr
HTML Attributes about a cell.
-
Listeners
listen
Listen for web events.
-
bool
-
struct
-
namespace