The Interface Kit: BShape

The Interface Kit Table of Contents | The Interface Kit Index

# BShape

Derived from: BArchivable

Declared in: be/interface/Shape.h

Library: libbe.so

Allocation: Constructor only

###### Summary

The BShape class provides a powerful means of representing the outline of any shape that can be comprised of lines or Beziér curves.

The BShapeIterator class provides a means for utilizing BShape objects in your own code. You can also use BShape objects to obtain outlines of characters in a BFont by calling `BFont::GetGlyphShapes()`.

### Creating a BShape

A BShape is essentially a list of graphics commands, of which there are four types:

- MoveTo. This sets the BShape's coordinates to a specified point in the shape's space.

- LineTo. This represents a line from the current point to the next point in the shape.

- BeziérTo. This represents a Bezier curve, connecting the current point to a new point, with other points serving to control the shape of the curve.

- Close. This indicates the end of the shape's command list.

  Functions by the same names are used to add the corresponding commands to the BShape object. For example, to create a BShape that represents two vertical lines, the following code might be used:

         BShape shape;
         shape.MoveTo(0,0);
         shape.LineTo(0,100);
         shape.MoveTo(5,0);
         shape.LineTo(5,100);

  ## Constructor and Destructor

  ### BShape()

  `BShape()`
  `BShape`(const BShape &copyFrom)
  `BShape(` BMessage *archive`)`

  Creates a new BShape object. The first form of the BShape constructor creates an empty shape. The second form, which accepts another BShape as an argument, copies that shape into the new one. The third form reconstructs a BShape from an archive.

  ### ~BShape()

  virtual `~BShape()`

  Releases memory occupied by the BShape object.

  ## Static Functions

  ### Instantiate()

  static BArchivable *`Instantiate(` BMessage *archive`)`

  Returns a new BShape object, allocated by `new` and created with the version of the constructor that takes a BMessage archive. However, if the archive message doesn't contain data for a BShape object, the return value will be `NULL`.

  See also: `BArchivable::Instantiate()`, `instantiate_object()`, `Archive()`

  ## Member Functions

  ### AddShape()

  status_t `AddShape(`const BShape *otherShape`) `

  `AddShape()` adds the lines and curves that comprise the otherShape to the shape.

  RETURN CODES

  `B_OK`. No error.

  - Other errors. None are defined at this time, but you should always check for errors returned by this function.

  ### BezierTo()

  status_t `BezierTo(` BPoint controlPoints[3]`) `

  Adds a command to the BShape that represents a Beziér curve that begins at the current coordinates and is constructed using the specified control points.

  RETURN CODES

  `B_OK`. No error.

  - Other errors. None are defined at this time, but you should always check for errors returned by this function.

  ### Bounds()

  BRect `Bounds(`void`)` const` `

  `Bounds()` returns the bounds rectangle of the entire shape; this rectangle encloses all the lines and Beziér curves that comprise the shape.

  ### Clear()

  void `Clear(`void`) `

  `Clear()` deletes all the lines and Beziér curves that comprise the shape, leaving it empty.

  ### Close()

  void `Close(`void`) `

  `Close()` should be called when the shape has been fully-constructed by calls to the `BezierTo()`, `LineTo()`, and `MoveTo()` functions.

  RETURN CODES

  `B_OK`. No error.

  - Other errors. None are defined at this time, but you should always check for errors returned by this function.

  ### LineTo()

  status_t `LineTo(` BPoint point`) `

  Adds a "draw line" command to the BShape. A line will be drawn from the previous coordinates to the specified coordinates.

  RETURN CODES

  `B_OK`. No error.

  - Other errors. None are defined at this time, but you should always check for errors returned by this function.

  ### MoveTo()

  status_t `MoveTo(` BPoint point`) `

  Adds a "move to" command to the BShape. The next `LineTo()` or `BezierTo()` will begin at this point. This lets you create noncontiguous shapes.

  RETURN CODES

  `B_OK`. No error.

  - Other errors. None are defined at this time, but you should always check for errors returned by this function.

  ## Archived Fields

  The `Archive()` function adds the following fields to its BMessage argument:

  Field | Type code | Meaning
  --- | --- | ---
  "pts" | `B_POINT_TYPE` | The list of points used by the shape's commands.
  "ops" | `B_INT32_TYPE` | The list of command opcodes indicating the shape's commands.

  The Interface Kit Table of Contents | The Interface Kit Index

  The Be Book,
  ...in lovely HTML...
  for BeOS Release 5.

  Copyright © 2000 Be, Inc. All rights reserved..