The gx module defines the graphics primitives used for rendering to a display device. For example there implements for "painting" to computer screens and another for "painting" a PDF file. Many of the simple types used in the rest of the stack are defined in gx including BColor, BFont, BPen, BBrush, BGeom, and BTransform.
The gx APIs use a vector coordinate system based on x and y represented as doubles. The origin 0,0 is the top left hand corner with x incrementing to the right and y incrementing down. This coordinate system is called the logical coordinate space (sometimes called the user space). How the logical coordinate space maps to the device coordinate space is environment specific. Usually a logical coordinate maps directly into pixels, although transforms may alter this mapping.
BColor stores an RGBA color. It's string syntax supports a wide range of formats including most specified by CSS3:
BFont is composed of three components:
The format of fonts is "[italic || bold || underline] {size}pt {name}". Examples: "12pt Times New Roman",
"bold 11pt sans-serif", "italic underline 10pt Arial". The BFont
class also provides access
to a font's metrics such as baseline, height, ascent, descent, and for calculating character widths.
The BBrush class encapsulates how a shape is filled. The gx brush model is based on the SVG paint model. There are four types of brushes:
The BPen class models how a geometric shape is outlined. A pen is composed of:
The following set of classes is designed to work with the gx coordinate system. Each concept is modeled by three classes: an interface, a mutable class, and an immutable BSimple version that manages the string encoding.
The IPoint, Point, and BPoint classes store an x and y location using two doubles. The string format is "x, y". Example "40,20", "0.4,17.33".
The ISize, Size, and BSize classes store a width and height using two doubles. The string format is "width,height". Examples include "100,20", "10.5, 0.5".
The IInsets, Insets, and BInsets classes store side distances using four doubles (top, right, bottom, and right). The string format for insets follows CSS margin style: "top,right,bottom,left". If only one value is provided it applies to all four sides. If two values are provided the first is top/bottom and the second right/left. If three values are provided the first is top, second is right/left, and third is bottom. Four values apply to top, right, bottom, left respectively. Examples "4" expands to "4,4,4,4"; "2,3" expands to "2,3,2,3"; "1,2,3" expands to "1,2,3,2".
The geometry classes are used to model rendering primitives. They all following the pattern used with Point, Size, and Insets with an interface, mutable class, and immutable BSimple. Geometries can be used to stroke outlines, fill shapes, or set clip bounds.
The IGeom, Geom, and BGeom classes are all abstract base classes for the geometry APIs.
The ILineGeom, LineGeom, and BLineGeom classes model a line between two points in the logical coordinate system. The string format of line is "x1,y1,x2,y2".
The IRectGeom, RectGeom, and BRectGeom classes model a rectangle in the logical coordinate system. The string format of rectangle is "x,y,width,height".
The IEllipseGeom, EllipseGeom, and BEllipseGeom classes model a ellipse bounded by a rectangle in the logical coordinate space. The string format is "x,y,width,height".
The IPolygonGeom, PolygonGeom, and BPolygonGeom classes model a closed area defined by a series of line segments. The string format of polygon is "x1,y1 x2,y2,...".
The IPathGeom, PathGeom, and BPathGeom classes define a general path to draw or fill. The model and string format of a path is based on the SVG path element. The format is a list of operations. Each operation is denoted by a single letter. A capital letter implies absolute coordinates and a lowercase letter implies relative coordinates. Multiple operations of the same type may omit the letter after the first declaration.
Refer to the W3 SVG spec (http://www.w3.org/TR/SVG/) for the formal specification and examples.
Transforms allow a new logical coordinate system to be derived from an existing coordinate system. The gx transform model is based on SVG and uses the exact string formatting. BTransform stores a list of transform operations:
The BImage
class is used to manage bitmap images. Image's are typically loaded from a
list of ords which identify a list of files (GIF, PNG, and JPEG supported).
When more than file is specified, the image is composited using alpha
transparency from bottom to top (useful for "badging" icons). Images may
also be created in memory and "painted" using the Graphics
API.
The framework will often load images asynchronously in a background thread
to maintain performance. Developers using BImages
directly
can poll to see if the image is loaded via the isLoaded()
method.
Use the sync()
method to block until the image is fully loaded.
Animated GIFs require that the developer call animate()
at a frame
rate of 10frames/second. Typically developers should display images using BLabel
which automatically handles async loading and animation.
The framework caches images based on their size and how recently they are used. You may use the Image Manager spy page to review the current cache.
Painting to a device is encapsulated by the Graphics class. The primitive paint operations are:
All paint operations perform compositing and clipping. Compositing means that
colors are combined as painting occurs bottom to top. For example drawing a GIF or
PNG file with transparent pixels allows the pixels drawn underneath to show
through. Alpha transparency performs color blending with the pixels underneath.
Clipping is the processing of constraining paint operations to a specified
geometry. Any pixels from a paint operation which would be drawn outside the
clip geometry are ignored. Use the clip()
method to clip to a
specific region.
Often it is necessary to save the current state of the graphics to perform a
temporary paint operation, and then to restore the graphics. An example is to
set a clip region, paint something, then restore the original clip. The
push()
and pop()
are used to accomplish this functionality
by maintaining a stack of graphics state. You should always call pop()
in a try finally
block to ensure that your code cleans up properly.
Copyright © 2000-2019 Tridium Inc. All rights reserved.