Using Canvas

BEFORE PROCEEDING, PLEASE SEE THE Building Programs PAGE FOR MORE INFORMATION ON HOW TO COMPILE AND RUN A PROGRAM WITH TSGL CODE!!!

So, you've downloaded and installed TSGL. Congrats! Now what? Well, there's a lot you can do with TSGL. For now, let's start by making a simple Hello World program using the Canvas!

The Canvas is used for creating dynamic visualizations and the Background of a Canvas is used for creating static visualizations.

Linux/Mac/WSL/Cygwin users: Start off by creating a folder and name it "Tutorial2". Create a file inside of Tutorial2 and name it "hello.cpp". Then, navigate to the cloned TSGL folder and into the genericMakefile folder. Copy the Makefile into Tutorial1 and change the "TARGET" line so that "program" is now "hello".

All platforms: Follow the steps in the Building Programs page on how to compile and run the program (This is a single-file program).

Now, we'll be writing in C++, so let's place our #include and using directives:

#include <tsgl.h>
using namespace tsgl;

tsgl.h contains #include directives for all of the necessary header files needed in order to use the TSGL library. This includes vital class header files such as those for the Canvas class and the Timer class. TSGL also has its own namespace which must be used when using the TSGL library.

Moving forward, let's add some code that will create and initialize a Canvas. A Canvas is essentially a screen that draws and displays whatever it is that you want to draw and display. There's a special kind of Canvas, the CartesianCanvas, that we will look at later on.

For now, let's focus on the normal Canvas:

int main() {
  Canvas c(0, 0, 800, 400, "Hello World!");
  c.start();
  c.wait();
}

This is essentially the skeleton code for any TSGL program. Let's break it down. In the main method, a Canvas object is created positioned at (0, 0) (on your monitor) with a width of 800 and a height of 400. It has a title, Hello World!.

The c.start() and c.wait() statements tell the Canvas to start drawing and then wait to close once it has completed drawing.

In between the c.start() and c.wait() statements is where the magic happens. We will place a new statement which will draw a line to the Canvas:

#include <tsgl.h>
using namespace tsgl;

int main() {
  Canvas c(0, 0, 800, 400, "Hello World!", GRAY);
  c.start();

  //'H'
  Line h0(-350, 100, 0, -350, -100, 0, 0, 0, 0, BLACK);
  Line h1(-350, 0, 0, -250, 0, 0, 0, 0, 0, BLACK);
  Line h2(-250, 100, 0, -250, -100, 0, 0, 0, 0, BLACK);

  //'E'
  Line e0(-200, 100, 0, -200, -100, 0, 0, 0, 0, BLACK);
  Line e1(-200, 100, 0, -100, 100, 0, 0, 0, 0, BLACK);
  Line e2(-200, 0, 0, -100, 0, 0, 0, 0, 0, BLACK);
  Line e3(-200, -100, 0, -100, -100, 0, 0, 0, 0, BLACK);

  //The two 'L's
  Line l0(-50, 100, 0, -50, -100, 0, 0, 0, 0, BLACK);
  Line l1(-50, -100, 0, 50, -100, 0, 0, 0, 0, BLACK);
  Line l2(100, 100, 0, 100, -100, 0, 0, 0, 0, BLACK);
  Line l3(100, -100, 0, 200, -100, 0, 0, 0, 0, BLACK);

  //'O'
  Ellipse o0(300, 0, 0, 50, 100, 0, 0, 0, BLACK);
  Ellipse o1(300, 0, 0, 48, 98, 0, 0, 0, c.getBackgroundColor());

  //Add 'HELLO' to the Canvas
  c.add(&h0); c.add(&h1); c.add(&h2);
  c.add(&e0); c.add(&e1); c.add(&e2); c.add(&e3);
  c.add(&l0); c.add(&l1); c.add(&l2); c.add(&l3);
  c.add(&o0); c.add(&o1);

  c.wait();
}

We will examine the Line and Ellipse classes in the Using Shapes tutorial. For now, just know that Line() creates a Line, Ellipse() creates an ellipse, and add() draws any Drawable object to the Canvas.

Our code is now complete! Compile the code using make, and then once it has compiled correctly, run it using ./tutorial2. A window should pop up with "Hello" written on it. To close the window, press the ESC key or click the 'x' in one of the corners.

Please note that the c.start() and c.wait() methods MUST be used at least once when working with the Canvas class. Bad things will happen if you do not have these methods and decide to draw something on a Canvas.

There are also special types of Canvases for different situations. CartesianCanvas also draws lines and circles, but using methods like c.drawLine() and c.drawCircle(), rather than the object oriented approach, and on a Cartesian coordinate system instead. RasterCanvas and CartesianRasterCanvas are used like their non-Raster equivalents, but they render each object once and then it cannot be removed with c.remove(). RasterCanvas is particularly useful for drawing points. See the Mandelbrot example for a use of the RasterCanvas.

Next up, in Using Shapes, we take a look at how to draw shapes onto a Canvas.