NAME
BQGraphicsContext - BRTT Qt graphics extension graphics context class
SYNOPSIS
$(QTNATIVELIBS) -lbqplot_native -lbanner -lbrttutil -lbumapdata $(DBLIBS) $(TRLIBS)
#include "BQ.h"
DESCRIPTION
The
BQGraphicsContext class is used by certain
bqplot graphics items
as a means to specify and configure lists of graphics attributes, called graphics context items,
that determine the appearance of displayed graphical entities. All graphical display entities
are rendered according to sets of display attributes, such as pen color and fill brush color.
The
BQGraphicsContext class systematizes the specification of these graphical attributes and
also provides functionality for attribute "coding" - the automatic variation of attribute values as
a function of some independent variable. An example of attribute coding would be earthquake symbols
whose background fill color is a function of earthquake depth.
BQGraphicsContext objects contain a list of individual graphics context items,
typed BqGraphicsContextItem. Each graphics context item has a unique string name within
the BQGraphicsContext object. An objective of the BQGraphicsContext class
is to provide context sharing, including attribute coding, across a large number of graphical
entities, such as glyphs.
this minimizes heap storage use and also provides a simple mechanism for rapidly changing
graphical entity display attributes across a large number of entities. Each of
the BqGraphicsContextItem items within a BQGraphicsContext object is meant to be
shared across multiple graphics display objects. Simple lists of BqGraphicsContextItem items
are returned as BqGraphicsContext lists.
Currently the BQGlyphs, BQPolyline, BQPolypoint, BQMap and BQMapevents
items use BQGraphicsContext objects. Another associated (but not based from) class
is BQGlyphsGraphicsContext, which is used by BQGlyphs objects.
CONSTRUCTOR
BQGraphicsContext();
BQGraphicsContext(BQGraphicsContext *source);
If a source is specified, then the returned object is a deep copy of the source object.
BQViewportItem METHODS
-
void copy(BQGraphicsContext *source);
This makes a deep copy of source into the object so that all BqGraphicsContext items
are re-allocated and copied from source. Note that the existing graphics context items are lost.
-
BqGraphicsContextItem *setGcItem (QString name, int type, int replace=0);
-
BqGraphicsContextItem *setGcItem (QString name, int type, QColor param, int replace=0);
-
BqGraphicsContextItem *setGcItem (QString name, int type, Qt::PenStyle style, int replace=0);
-
BqGraphicsContextItem *setGcItem (QString name, int type, Qt::PenJoinStyle style, int replace=0);
-
BqGraphicsContextItem *setGcItem (QString name, int type, Qt::PenCapStyle style, int replace=0);
-
BqGraphicsContextItem *setGcItem (QString name, int type, long param, int replace=0);
-
BqGraphicsContextItem *setGcItem (QString name, int type, double param, int replace=0);
-
BqGraphicsContextItem *setGcItem (QString name, int type, QString param, int replace=0);
These functions are used to create and set individual graphics context items. Each graphics context
item within a BQGraphicsContext object must have a unique name. If the named item does not
exist, then it is created. If the replace flag is set and the item exists, then the item is re-created.
Otherwise, if the item exists and the replace flags is not set, then the existing item is
returned and the item's attributes are set according to the function parameters. Re-setting an item's
parameters for an item that is being used by bqplot graphics items is a quick way to change
the appearance of all of the objects that use that item. The type argument specifies the
graphics context item type and must be one of the following.
BQ_GRAPHICS_CONTEXT_TYPE_CLEAR_PEN /* clears the Qt pen by causing a Qt::NoPen to be set */
BQ_GRAPHICS_CONTEXT_TYPE_COLOR_PEN /* sets the Qt pen color */
BQ_GRAPHICS_CONTEXT_TYPE_LINESTYLE_PEN /* sets the Qt pen line style (Qt::SolidLine, etc.) */
BQ_GRAPHICS_CONTEXT_TYPE_JOINSTYLE_PEN /* sets the Qt pen join style (Qt::BevelJoin, etc.) */
BQ_GRAPHICS_CONTEXT_TYPE_CAPSTYLE_PEN /* sets the Qt pen cap style (Qt::SquareCap, etc.) */
BQ_GRAPHICS_CONTEXT_TYPE_CLEAR_BRUSH /* clears the Qt brush by causing a Qt::NoBrush to be set */
BQ_GRAPHICS_CONTEXT_TYPE_COLOR_BRUSH /* sets the Qt brush color */
BQ_GRAPHICS_CONTEXT_TYPE_LINEWIDTH /* sets the Qt pen line width to an integer */
BQ_GRAPHICS_CONTEXT_TYPE_LINEWIDTHF /* sets the Wt pen line width to a double */
BQ_GRAPHICS_CONTEXT_TYPE_OPACITY /* sets the Qt display opacity */
BQ_GRAPHICS_CONTEXT_TYPE_SYMBOL /* sets the symbol type for glyphs */
BQ_GRAPHICS_CONTEXT_TYPE_SIZE /* sets the symbol size for glyphs */
-
The attribute parameter types should correspond properly to the type argument or an error
will be returned. The return value is a pointer to the graphics context item, or NULL if an error
occurs. Note that the BQ_GRAPHICS_CONTEXT_TYPE_SIZE type requires a double parameter (in pixels)
and the BQ_GRAPHICS_CONTEXT_TYPE_SYMBOL requires a long parameter set to one of
BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_DEFAULT, BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_POINT,
BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_CROSS, BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_X,
BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_TRIANGLE, BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_SQUARE,
BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_CIRCLE, BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_STAR,
BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_DIAMOND, BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_BEACHBALL,
or BQ_GRAPHICS_CONTEXT_SYMBOL_TYPE_SHAPE. The shape and size items are only used for BQGlyph objects.
-
The setGcItem function with the QString param argument will accept all of the type
values except for BQ_GRAPHICS_CONTEXT_TYPE_CLEAR_PEN and BQ_GRAPHICS_CONTEXT_TYPE_CLEAR_BRUSH.
The param value is a string representation of the attribute value.
If type == BQ_GRAPHICS_CONTEXT_TYPE_LINESTYLE_PEN, then param should be one
of "SolidLine", "DashLine", "DotLine", "DashDotLine", or "DashDotDotLine".
If type == BQ_GRAPHICS_CONTEXT_TYPE_JOINSTYLE_PEN, then param should be one
of "MiterJoin", "BevelJoin", "RoundJoin", or "SvgMiterJoin".
If type == BQ_GRAPHICS_CONTEXT_TYPE_CAPSTYLE_PEN, then param should be one
of "MiterJoin", "FlatCap", "SquareCap", or "RoundCap".
-
If type == BQ_GRAPHICS_CONTEXT_TYPE_COLOR_PEN or BQ_GRAPHICS_CONTEXT_TYPE_COLOR_BRUSH,
then param should be specified as a string of form "<color_string>"
or "<hue_string>;<saturation_string>;<lightness_string>".
If param is specified in the "<color_string>" form, then the color
is set to a constant according to any of the string formats acceptable
by BQ_ParseColor (see BQsubs(3)).
If param is specified
in the "<hue_string>;<saturation_string>;<lightness_string>"
form, then the color is specified by hue, from 0.0 to 360.0 degrees, saturation, from 0.0 to 1.0,
and lightness, from 0.0 to 1.0, in a format that will accept graphics item coding specifications.
As mentioned previously, graphics item coding is a mechanism that allows graphics context item parameters
to be computed on-the-fly as glyphs are displayed based upon functions of arbitrary independent
variables. In this form each of the <hue_string>, <saturation_string>
and <lightness_string> strings are specified in the form "<constant_value>"
or "<independent_value_1>,<dependent_value_1>:<independent_value_2>,<dependent_value_2>"
where <independent_value_{1|2}> is the independent coding value (such as earthquake depth)
and <dependent_value_{1|2}> is the corresponding dependent value, either hue, saturation
or lightness. This establishes a linear relationship between the coding independent variable and the
associated graphics context item parameter. An example would be
0.0,240.0:650.0,0.0;1.0;0.8
-
where the hue ranges from 240.0 (blue) for a coding value of 0.0 to 0.0 (red)
for a coding value of 650.0 and the saturation and lightness are constant values of 1.0
and 0.8 respectively.
-
If type == BQ_GRAPHICS_CONTEXT_TYPE_LINEWIDTHF, BQ_GRAPHICS_CONTEXT_TYPE_OPACITY,
or BQ_GRAPHICS_CONTEXT_TYPE_SIZE,
then param should be specified as a string of form "<value_string>"
or "<independent_value_1>,<dependent_value_1>:<independent_value_2>,<dependent_value_2>[:<min>:<max>]".
If param is specified in the "<value_string>" form, then the corresponding
graphics context item value is set to a constant.
If param is specified in the
"<independent_value_1>,<dependent_value_1>:<independent_value_2>,<dependent_value_2>[:<min>:<max"
form, then the corresponding graphics context item value is set according to coding inputs
where <independent_value_{1|2}> is the independent coding value (such as earthquake magnitude)
and <dependent_value_{1|2}> is the corresponding dependent value, such as symbol size.
This establishes a linear relationship between the coding independent variable and the
associated graphics context item parameter. The optional <min> and <max> strings
can be used to limit the dependent value range. An example would be
0.0,1.0:31536000.0,0.0:0.0:1.0
-
where the opacity value, in this case, ranges from 1.0 (fully opaque) for a coding
value of 0.0, in this case earthquake age, to 0.0 (fully translucent) for
a coding value of 31536000.0 seconds (one year) with the opacity limited to the range of 0.0
to 1.0.
-
BqGraphicsContextItem *getGcItem (QString name);
This will return the graphics context item corresponding to name or NULL if there is no
graphics context item corresponding to that name.
-
BqGraphicsContext *getGc (QString gcname);
This will return a BqGraphicsContext list of BeGraphicsContextItem items corresponding
to the graphics context set name of gcname. Generally, graphics context item names have arbitrary
syntaxes. However, graphics context item names have an informal naming convention that uses the :
character to separate naming fields. When a new item is created using one of the setGcItem
functions, if there is no : character in the name, then the specified name is prepended
with "default:". This function will return a list for which the item names
have gcname as the first : delimited field. this provides a simple mechanism for grouping
graphics context items into sets for a particular graphics object. Note that more complex objects,
such as BQMapevents objects, violate this convention but still use the : character
to delimit fields within the graphics context item names.
-
static BqGraphicsContext *copy (BqGraphicsContext *gc);
This will perform a shallow copy of the graphics context items from one list into a copy.
-
static void getValue (const BqGraphicsContextItem *item, void **value);
-
static void getValue (const BqGraphicsContextItem *item, int *value);
-
static void getValue (const BqGraphicsContextItem *item, long *value);
-
static void getValue (const BqGraphicsContextItem *item, double *value);
These are static functions that will return the various *value arguments of the current values
associated with the item graphics context item.
-
static void initContextItem (BqGraphicsContextItem *item);
This static function should be called to initialize newly allocated BqGraphicsContextItem structures.
-
static void setGcCoding (BqGraphicsContextCoding *coding, double in1, double out1, double in2, double out2, double outmin=1.0, double outmax=-1.0);
As described previously, graphics context item coding is a mechanism for dynamically computing a graphics
context item attribute value as a function of some independent coding variable. This is accomplished internally
through the use of BqGraphicsContextCoding structures that contain the functional parameters used to
compute a graphics context item attribute value as a function of the coding input variable. This static
function is used to set the contents of *item according to in1, out1, the coding variable
value and corresponding graphics context item attribute value and in2, out2, the coding value
and attribute value for a second point. The two in1, out1 and in2, out2 points
define a linear function of the graphics context item attribute value as a function of the coding variable.
if outmax > outmin, then these define clipping ranges of the output graphics item attribute value,
otherwise no clipping is done.
-
void setGcItemCoding (QString name, int coding_type, BqGraphicsContextCoding coding);
-
void setGcItemCoding (QString name, int coding_type, BqGraphicsContextCoding *coding = NULL);
-
static void setGcItemCoding (BqGraphicsContextItem *item, int coding_type, BqGraphicsContextCoding coding);
-
static void setGcItemCoding (BqGraphicsContextItem *item, int coding_type, BqGraphicsContextCoding *coding = NULL);
These are normal methods plus static class versions of functions that will associate BqGraphicsCoding
structures, specified by coding, with BqGraphicsContextItems, specified either by name
or by item pointers. The value of coding_type defines the coding type and must be one
of BQ_GRAPHICS_CONTEXT_CODING_TYPE_NONE, for no coding, BQ_GRAPHICS_CONTEXT_CODING_TYPE_SCALAR,
for simple scalar-based coding such as size or opacity coding,
or BQ_GRAPHICS_CONTEXT_CODING_TYPE_COLOR_HSL, for color coding using independent hue, saturation and lightness
coding functions. For scalar coding, a single coding structure is needed. For color coding,
an array of three coding
structures are needed corresponding to the hue, saturation and lightness attribute values which must be specified
using the BqGraphicsContextCoding *coding versions of the functions.
SEE ALSO
bqplot(3), BQGlyphGraphicsContext(3),
BQGlyph(3),
BQGlyphs(3),
BQPolyline(3),
BQPolypoint(3), BqMapevents(3), BQsubs(3)
AUTHOR
Danny Harvey, BRTT