1<HTML> 2<!-- $Id: BPolygonUseCases.html 1727 2002-10-28 02:50:08Z jrand $ --> 3<HEAD> 4<TITLE>BPolygon Use Cases and Implementation Details</TITLE> 5</HEAD> 6 7<BODY BGCOLOR="white" LINK="#000067" VLINK="#000067" ALINK="#0000FF"> 8 9<FONT FACE="Verdana,Arial,Helvetica,sans-serif" SIZE="-1"> 10 11<H1>BPolygon Use Cases and Implementation Details:</H1> 12 13<P>This document describes the BPolygon interface and some basics of how it is implemented. 14The document has the following sections:</P> 15 16<OL> 17<LI><A HREF="#interface">BPolygon Interface</A></LI> 18<LI><A HREF="#usecases">BPolygon Use Cases</A></LI> 19<LI><A HREF="#implement">BPolygon Implementation</A></LI> 20</OL> 21 22<A NAME="interface"></A><H2>BPolygon Interface:</H2> 23 24<P>The BPolygon class is used to hold information about a shape composed of a series of straight 25lines (ie a polygon). On its own, it just describes the shape and can only be drawn by passing 26it to a BView. The best source of source of information for the BPolygon is 27<A HREF="https://www.haiku-os.org/legacy-docs/bebook/BPolygon.html">the Be Book page about it</A>. 28</P> 29 30<A NAME="usecases"></A><H2>BPolygon Use Cases:</H2> 31 32<P>The following use cases cover the BPolygon functionality:</P> 33 34<OL> 35<LI><P><B>Construction 1:</B> A BPolygon can be constructed without passing it any arguments. When 36this is done, the polygon will have no points in it (ie no shape) until they are added through 37AddPoints().</P></LI> 38 39<LI><P><B>Construction 2:</B> A BPolygon can be constructed by passing it a pointer to an existing 40BPolygon (ie a copy constructor). The resulting copy will have the exact same state as the 41one passed in. That means it will have the same number of points in the same locations resulting 42in the same shape.</P></LI> 43 44<LI><P><B>Construction 3:</B> A BPolygon can be constructed by passing it a pointer to an array of 45BPoints and an integer which describes the number of points in that array. The BPolygon will be 46constructed such that it holds the shape described by that array of points.</P></LI> 47 48<LI><P><B>Destruction:</B> When a BPolygon is deconstructed any memory allocated in order to hold 49the state of the BPolygon is freed and the state of the polygon is lost.</P></LI> 50 51<LI><P><B>Add Points:</B> The AddPoints() member function appends a number of passed in points to 52the existing set of points already in the polygon. It takes a pointer to an array of BPoints and 53an integer count of the number of points to append. This is similar to the "Construction 3" use 54case except in that case there is no existing points so the passed in points describe the entire 55polygon.</P></LI> 56 57<LI><P><B>Count Points:</B> The CountPoints() member function returns the number of points which 58describe the polygon. The result is an integer.</P></LI> 59 60<LI><P><B>Frame:</B> The Frame() member function returns the smallest BRect which contains all of 61the points which describes the BPolygon.</P></LI> 62 63<LI><P><B>Map To:</B> The MapTo() member function applies a translation (ie move) and a scale (ie 64grow/shrink) operation to the existing polygon, adjusting all points according to the passed in 65rule. The operation to apply depends on two passed in BRect's. The translation and scale 66adjustment which turns the first BRect into the second BRect is applied to all points in the 67BPolygon.</P></LI> 68 69<LI><P><B>Print To Stream:</B> The PrintToStream() member function sends the set of points which 70make up the BPolygon to standard output. It does so by performing a PrintToStream() on the 71individual BPoint's which make up the polygon. This member is generally used for debugging and 72the output is primarily human readable and not sensitive to changes which could risk backward 73compatibility.</P></LI> 74 75<LI><P><B>Assignment Operator</B> The operator=() operator is defined for BPolygon's. It takes 76a source BPolygon and assigns it to another existing BPolygon target. The state of the target 77BPolygon is lost and replaced with that of the source. The source retains its state so the outcome 78is two BPolygons with the same state (ie set of points).</P></LI> 79 80</OL> 81 82<A NAME="implement"></A><H2>BPolygon Implementation:</H2> 83 84<P>Internally, the BPolygon contains an array of BPoint's which it uses to track the shape it 85holds. The implementation of BPolygon is fairly simple since it is a fairly basic container 86class for a set of points.</P> 87 88</BODY> 89</HTML> 90