This document describes the BPolygon interface and some basics of how it is implemented. The document has the following sections:
The BPolygon class is used to hold information about a shape composed of a series of straight lines (ie a polygon). On its own, it just describes the shape and can only be drawn by passing it to a BView. The best source of source of information for the BPolygon interface can be found here in the Be Book.
The following use cases cover the BPolygon functionality:
Construction 1: A BPolygon can be constructed without passing it any arguments. When this is done, the polygon will have no points in it (ie no shape) until they are added through AddPoints().
Construction 2: A BPolygon can be constructed by passing it a pointer to an existing BPolygon (ie a copy constructor). The resulting copy will have the exact same state as the one passed in. That means it will have the same number of points in the same locations resulting in the same shape.
Construction 3: A BPolygon can be constructed by passing it a pointer to an array of BPoints and an integer which describes the number of points in that array. The BPolygon will be constructed such that it holds the shape described by that array of points.
Destruction: When a BPolygon is deconstructed any memory allocated in order to hold the state of the BPolygon is freed and the state of the polygon is lost.
Add Points: The AddPoints() member function appends a number of passed in points to the existing set of points already in the polygon. It takes a pointer to an array of BPoints and an integer count of the number of points to append. This is similar to the "Construction 3" use case except in that case there is no existing points so the passed in points describe the entire polygon.
Count Points: The CountPoints() member function returns the number of points which describe the polygon. The result is an integer.
Frame: The Frame() member function returns the smallest BRect which contains all of the points which describes the BPolygon.
Map To: The MapTo() member function applies a translation (ie move) and a scale (ie grow/shrink) operation to the existing polygon, adjusting all points according to the passed in rule. The operation to apply depends on two passed in BRect's. The translation and scale adjustment which turns the first BRect into the second BRect is applied to all points in the BPolygon.
Print To Stream: The PrintToStream() member function sends the set of points which make up the BPolygon to standard output. It does so by performing a PrintToStream() on the individual BPoint's which make up the polygon. This member is generally used for debugging and the output is primarily human readable and not sensitive to changes which could risk backward compatibility.
Assignment Operator The operator=() operator is defined for BPolygon's. It takes a source BPolygon and assigns it to another existing BPolygon target. The state of the target BPolygon is lost and replaced with that of the source. The source retains its state so the outcome is two BPolygons with the same state (ie set of points).
Internally, the BPolygon contains an array of BPoint's which it uses to track the shape it holds. The implementation of BPolygon is fairly simple since it is a fairly basic container class for a set of points.