NAME
BQText - BRTT Qt graphics extension for drawing text strings
SYNOPSIS
-lbqplot_native -lbanner -lbrttutil -lbumapdata $(QTNATIVELIBS) $(DBLIBS)
#include "BQ.h"
DESCRIPTION
BQText objects are used to display general text string annotations
using world coordinate positioning. It also allows
text to be rotated.
This class inherits the BQConfigure class which is itself a subclass of the BUConfigure class
with extensions to process Qt colors and fonts. The configure methods are implemented
in the BUConfigure parent (see BUConfigure(3)).
INHERITS FROM
BQViewportItem,
BQConfigure
CONSTRUCTOR
BQText(BQViewport *master, QString textstring, QString x, QString y);
Where "master" is the BQViewport master for this object, "textstring" is
the text string to be displayed and "x y" are
the location of the text string relative to the viewport.
If specified as a numerical string,
then x, y are used as device coordinates (i.e. pixels) relative to the lower left hand
corner of the viewport window.
In addition, there are
a number of other tokens that can be used in defining x and y.
If either ends in d, then the coordinate is in data world coordinates.
If either ends in v, then the coordinate is in units of viewport window width or height,
so that x corresponding to the middle of the viewport window would be "0.5v".
A viewport window or viewport frame qualifier, one of
bottom, for Y-axis viewport window bottom,
fbottom, for Y-axis viewport frame bottom,
top, for Y-axis viewport window top,
ftop, for Y-axis viewport frame top,
left, for X-axis viewport window left edge,
fleft, for X-axis viewport frame left edge,
right, for X-axis viewport window right edge,
fright, for X-axis viewport frame right edge,
can also be put at the beginning of the
strings to represent anchoring the coordinate to a particular edge of the frame or window.
An example of this would be "top+10" for y which would position the
text 10 pixels above the top of the viewport window.
If either ends in r, then the coordinate is relative to another BQText object
expressed as a fraction of the other object's width. In this case the relative configuration parameter must
be called to specify the reference object.
METHODS INHERITED FROM BQConfigure
-
void configure (Pf *params);
An Antelope parameter file object pointer that contains the BQText object
parameters. The parameters are described below.
-
void configure (...);
A variable argument list composed entirely of character string key-value pairs with
a single NULL terminating argument. This is an alternate method for specifying
the BQText object parameters. The parameters are described below.
METHODS INHERITED FROM BQViewportItem
-
void setLayer (QString name);
This will cause the BQText object to be put into the BQLayer object buffer with name name (see BQLayer(3)).
The BQLayer object will automatically be created if an object with name name does not exist.
BQText METHODS
-
void getBB (double *x, double *y, int *w, int *h);
This will return the bounding box of the text
in *x, *y, *w and *h.
-
void setTextCallback (std::function<BQ_textCallback> textCallback, BQ_ClientData client_data);
This will register a text callback procedure with the BQText object. A pointer
to the procedure is given by textCallback
which will be called with the following syntax:
typedef int (BQ_textCallback) (BQText *text, int type, QEvent *event, BQ_ClientData client_data);
-
Where text is a pointer to the BQText object, type is one of
BQ_QEVENT_TYPE_MOUSEPRESS, BQ_QEVENT_TYPE_MOUSEMOVE, BQ_QEVENT_TYPE_MOUSERELEASE, BQ_QEVENT_TYPE_KEYPRESS, BQ_QEVENT_TYPE_WHEEL, BQ_QEVENT_TYPE_ENTER, or BQ_QEVENT_TYPE_LEAVE,
event is the QEvent object and client_data
is copied from client_data in the setTextCallback call. This callback
can be used for implementing a simple text-based button GUI. The use of
the std::function declaration
allows either function pointers or lambda expressions to be used.
The return value should either be BQ_QEVENT_RETURN_OK, meaning the event
was processed and should continue to be propagated through the other items in
the viewport display list, or BQ_QEVENT_RETURN_DONT_PROPAGATE, meaning the
event was processed and should not be propagated
to the other items in the viewport display list.
OBJECT CONFIGURATION PARAMETERS
-
color_text textColor
Specifies a color to use for drawing the text fonts.
Can be specified in any of the forms documented in BQ_ParseColor(3).
This defaults to "black".
-
color_background backgroundColor
Specifies a color to use for filling the text background.
Can be specified in any of the forms documented in BQ_ParseColor(3).
This defaults to "".
-
color_background_outline outlineColor
Specifies a color to use for drawing an outline box around the text.
Can be specified in any of the forms documented in BQ_ParseColor(3).
This defaults to "".
-
font textFont
Specifies a font to use for displaying the text string.
Fonts are specified as "<family>[ <size>[ <weight>[ <italic?>]]]",
where <family> is a font family name, <size>size is a font size in integer points, <weight>
is an integer weight or can be one of Light, Normal, DemiBold, Bold or Black,
and <italic?> is a boolean (yes or no) to indicate if the font is in italics. System defaults
for <size>, <weight> and <italic?> are used if not specified.
This defaults to "Helvetica 12".
-
justification textJustification
Specifies how to position the text string relative to
the x, y positioning point for the item. The n, s, e, w and c
characters sre used for north (top), south (bottom), east (right), west (left) and center anchoring.
For instance, if textJustification is "c" then the text is centered on the
point; if textJustification is "n" then the text will be drawn
so that its top center point is at the positioning
point. This option defaults to "sw".
-
relative BQText *
This is used to specify a reference BQText object when using relative text positioning as described previously.
This defaults to NULL.
-
angle textAngle
This specifies a rotation angle of the text string in degrees counter clockwise
with the reference point being the justification point. A value of "0.0"
will display the text in a normal horizontal manner.
This option default to "0.0".
-
width widthPixels
This forces the width of the text background to be widthPixels pixels.
If it is <= 0, then the width is determined automatically from the text
bounding box.
This option default to "0".
-
height heightPixels
This forces the height of the text background to be heightPixels pixels.
If it is <= 0, then the height is determined automatically from the text
bounding box.
This option default to "0".
-
text textString
This allows the text string to be modified.
-
opacity opacity
This is a floating opacity factor applied to rendering of the text. A value of 1.0 means complete opaque and a value
of 0.0 means completely translucent.
This defaults to "1.0".
SEE ALSO
bqplot(3),
BQViewport(3),
BQLayer(3),
BQConfigure(3)
AUTHOR
Danny Harvey, BRTT