Prev: container.html Up Next: mpad.html
Canvas & Pad

Practical Guide:
pad &p = pad::mknew(0,0,0.5,4*CM).border_3D(true).bgcolor(color(0.6,0.6,0.5));
   // create a new pad in the current canvas, and store a reference to it
   // simple numbers specify fractions of the parent's width or height,
   // respectively.

   // set other attributes using the stored reference (this could have
   // been done on the previous commandline as well).

A canvas is the topmost element in the object hierarchy: every object must be contained in a canvas, or in other containers, which are themselves stored in a canvas. As stated elsewhere as well, drawing to a canvas does not mean producing any output: only references are stored in the canvas; the canvas resides only in the computer's memory. In order to make it appeare somewhere (in a file, on your screen, etc), you have to explicitely print it to a terminal. You can have several canvases at the same time. A canvas is also a pad, so all the following descriptions of pads are valid for a canvas as well. There is one exception: the canvas (which finally inherits from grob) overwrites the off() and invisible() functions inherited from grob: you can not switch off a canvas, or make it invisible (well, indeed: if you do not want it to appear anywhere, then simply don't print it :-)

pad::mknew A pad is used to create a sub-region of its parent (which can be a canvas, another pad, or a frame as well). A pad can be created within the current canvas with the static member function of pad:

pad &pad::mknew(length x1, length y1, length x2, length y2);
The arguments specify the lower left and upper right corners of the new pad. You can write simple numbers as well (like 0.5); these mean fractional parts of the parent's cwidth or cheight, respectively.

pad::mksub The mksub(...) static member function creates a new pad within any container, which is specified by the extra 5th argument:

pad &pad::mksub(length x1, length y1, length x2, length y2, container &parent = pad::current())
The default value of the 5th argument is the current pad, so if you omit this argument, the new pad will be created in the current one. Both the mknew and mksub functions return a reference to the newly created pad, so other member functions to midify the attributes of this pad can be called:
pad &p = pad::mknew(0,0,0.5,4*CM).bordercolor(red).borderwidth(MM);

Pad provides the member functions left(), right(), bottom(), top(), width() and height() to access its geometrical attributes. A pad is a container as well, so it inherits all the functionalities of a container (cleft(), etc). The following figure shows the geometrical attributes of a pad, which is placed into the canvas directly. (The border of this pad is set to be 3D, but the same holds for simple-border pads, where the border iw a simple line). (The script which was used to produce this figure is here)

In order to simplify the user's script, there is always a current (or active) pad, into which the drawing operations draw. To select a pad to be the current one, call the cd() member function on that pad. The static current() function of the pad class can be used to get the currently active pad:

   pad &p1 = pad::mknew(0,0,0.5,0.5);
   pad &p2 = pad::mknew(0.5,0.5,1,1);;
   label::pdraw("this is pad1",MM,MM);;
   pad::current()->borderwidth(3*MM).draw_border(true); // equivalent to p2.borderwidth(3*MM);
   label::pdraw("this is pad2",CM,CM);

The remainig member functions, which set the attributes of the pad, all return a reference to the pad itself, so they can be called in chain. They are more or less self-explanatory:

   pad &pad::draw_border(bool);           // switch on/off border-drawing
   pad &pad::bordercolor(const color &);  // color of the border (not too surprisingly)
   pad &pad::borderwidth(const length &); // set the width of the border
   pad &pad::border_3D(bool);             // draw a 3D border
   pad &pad::bgcolor(const color &);      // set the bgcolor, and implicitely call fill_bg
   pad &pad::fill_bg(bool);               // fill the background with bgcolor

Source files:

Prev: container.html Up Next: mpad.html