NAME
BQViewport - BRTT Qt graphics extension for establishing a viewport
SYNOPSIS
$(QTNATIVELIBS) -lbqplot_native -lbanner -lbrttutil -lbumapdata $(DBLIBS) $(TRLIBS)
#include "BQ.h"
DESCRIPTION
BQViewport objects are necessary adjuncts to any of the other
bqplot graphics extension objects.
These objects will anchor viewport "frames" into
QWidget parent objects.
A viewport can include margins around the actual data viewport for displaying
graph labels and titles. A
BQViewport object can be configured to be strictly
invisible, meaning the viewport itself will cause no graphics to be rendered,
or it can be configured to paint in background colors before the other
associated objects are rendered. Note that multiple viewports can occupy
the same space in a parent widget. In the following documentation, when we say
"viewport frame" we are referring to the entire rectangular viewport
area including margins for making axes and title displays. When
we refer to "viewport window" we are referring to only the inner portion of the
viewport frame inside of the margins that will contain the actual data.
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
QWidget,
BQViewportItem,
BQConfigure
CONSTRUCTOR
BQViewport(QWidget *parent, int make_parent_layout=1);
Where parent is the Qt parent widget. If make_parent_layout is set,
then a new QGridLayout object is created and used to set the parent's layout
to hold and completely fill the new BQViewport object, otherwise the layout must be done by by the application programmer.
METHODS INHERITED FROM BQConfigure
-
void configure (Pf *params);
An Antelope parameter file object pointer that contains the BQViewport 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 BQViewport object parameters. The parameters are described below.
METHODS INHERITED FROM BQViewportItem
-
void setLayer (QString name);
This will cause the BQViewport 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.
Other BQViewportItem methods can be called but are not normally necessary for this object.
BQViewport METHODS
-
void registerItem (BQViewportItem *item);
-
void deregisterItem (BQViewportItem *item);
-
void addItemAfter (BQViewportItem *item, BQViewportItem *after_item);
-
void moveItemAfter (BQViewportItem *item, BQViewportItem *after_item);
-
void moveItemToTop (BQViewportItem *item);
An internal display list is managed by BQViewport objects. Each child object or item to be displayed
occupies a position in this display list. The order in which objects are drawn and receive events is determined
by their order in the display list. Child objects are registered to the display list and
de-registered from the display list with registerItem and deregisterItem.
Generally these two methods are called automatically by the constructors of other child objects and do not
need to be called by the application programmer. A child object can be inserted into the display after
existing item after_item with a call to addItemAfter.
The methods normally called by application programmers are moveItemAfter and moveItemToTop
which allow for rearrangement of the existing display list without adding or removing items.
-
void grabEventStream (BQViewportItem *item);
-
void ungrabEventStream ();
These methods can be used by a child item object to grab and ungrab the mouse and keyboard Qt event stream.
Once the event stream is grabbed by a child object, only that object will receive any future Qt mouse and keyboard events
until the stream is ungrabbed by the child object.
These methods are typically used automatically by child objects and do not need to be called by
the application programmer unless custom event processing is desired.
-
void setPaintCallback (std::function<BQ_paintCallback> paintCallback, void *item, BQ_ClientData client_data);
This will register a paint callback procedure with the BQViewport object. A pointer to the procedure is given by paintCallback
which will be called with the following syntax:
typedef void (BQ_paintCallback) (void *item, int type, QResizeEvent *event, BQ_ClientData client_data);
-
Where item is a pointer to the child item object, type is one of BQ_QEVENT_TYPE_PAINT, meaning a Qt QPaintEvent
was received, or BQ_QEVENT_TYPE_RESIZE, meaning a Qt QResizeEvent was received and event is the QResizeEvent object
when type = BQ_QEVENT_TYPE_RESIZE. This can be used by other objects to track viewport repaints and resizes.
The use of the std::function declaration
allows either function pointers or lambda expressions to be used.
-
void setEventCallback (std::function<BQ_eventCallback> eventCallback, void *item, BQ_ClientData client_data);
This will register an event callback procedure with the BQViewport object. A pointer to the procedure is given by eventCallback
which will be called with the following syntax:
typedef void (BQ_eventCallback) (void *item, BQEvent *event, BQ_ClientData client_data);
-
Where item is a pointer to the child item object and event is a pointer to a BQEvent object
which contains the parameters associated with mouse and keyboard events.
The use of the std::function declaration
allows either function pointers or lambda expressions to be used.
-
int getWcoords (double x, double y, double *xcoord, double *ycoord, int no_map_tran=0);
This will convert x, y pixel coordinates into world coordinates returned in xcoord, ycoord.
If no_map_tran is set, then the world coordinate transformation will not include map projection transformations.
-
int getPcoords (double xcoord, double ycoord, double *x, double *y, int no_map_tran=0);
This will convert xcoord, ycoord world coordinates into pixel coordinates returned in x, y.
If no_map_tran is set, then the pixel coordinate transformation will not include map projection transformations.
-
QPainterPath *getWcoordsBB (int nside, int *np=NULL, int *sp=NULL);
This will return a QPainterPath object that contains the current viewport bounding box in
world coordinates. The bounding box sides will be interpolated into nside segments.
If np is non-NULL then *np is set if the north pole was contained within the viewport and *sp is
set similarly for the south pole. This method provides a means to grab a map viewport bounding box and reproject it into
another projection in a different map viewport.
-
void setDefaultCursor ();
This will set the mouse cursor to the default bqplot cursor which is a customized cross-hair cursor.
-
void zoom (double xw, double yw, double xfactor, double factor);
This will cause the plot scales to zoom in or out. The center of the zoomed window will be at world coordinates xw, yw.
The zooming will be xfactor in the X-direction (1.0 means no zoom, < 1.0 means zoom out, > 1.0 means zoom in)
and yfactor in the Y-direction.
-
void center (double xw, double yw);
This will pan the scales so world coordinates xw, yw will be in the center of the viewport.
-
void setStale ();
This will set the stale flags for all viewport child items. Setting stale flags will cause all child items to be re-rendered upon the next paint update.
-
QPainterPath *wrapLongitudes (int npts, double *lons, double *lats, int np, int sp);
-
QPainterPath *wrapLongitudes (QPainterPath *path, int np, int sp);
These can be used for map projections Mercator (BQ_MAP_TRAN_MERC) or geographic (BQ_MAP_TRAN_GEOG) where the earth is projected onto a flat surface with longitude
in the X-direction and latitude in the Y-direction so that longitude-latitude polylines are cyclically wrapped when the longitude range is greater than 360 degrees.
A QPainterPath object is returned with the wrapped polylines. If the original polyline contains the North pole, then np should be set and similarly
for the South pole and sp.
OBJECT CONFIGURATION PARAMETERS
-
width widthPixels
Specifies the width in pixels of the viewport frame.
If the width is set to "0", then the width of the viewport
is set according to the variable Qt layout and
will change automatically whenever the parent widget and layout changes.
This defaults to "0".
-
height heightPixels
Specifies the height in pixels of the viewport frame.
If the height is set to "0", then the height of the viewport
is set according to the variable Qt layout and
will change automatically whenever the parent widget and layout changes.
This defaults to "0".
-
mleft leftmarginPixels
This can be used to specify a margin in the X-axis direction that is
applied between the left side of the viewport frame
and the left side of the actual data viewport window.
This defaults to "0".
-
mright rightmarginPixels
This can be used to specify a margin in the X-axis direction that is
applied between the right side of the actual data viewport window.
and the right side of the viewport frame.
This defaults to "0".
-
mbottom bottommarginPixels
This can be used to specify a margin in the Y-axis direction that is
applied between the bottom side of the actual data viewport window.
and the bottom side of the viewport frame.
This defaults to "0".
-
mtop topmarginPixels
This can be used to specify a margin in the Y-axis direction that is
applied between the top side of the viewport frame
and the top side of the actual data viewport window.
This defaults to "0".
-
map mapTran
This specifies a transformation that can be applied to the data
world coordinates before scaling into device plot coordinates.
This is normally used for plotting geographic data in longitude-latitude
world coordinates and must be one of "none", for no transformations,
"merc", for Mercator projection, "edp", for
equal distance projection, "globe", for globe projection, or "geog", for geographic projection. Note that if a transformation is applied,
the xleft, xright, ..., plot scaling options are specified in units of the transformed world coordinates, degrees of longitude, latitude,
for merc and geog transformations or degrees
of distance in the X and Y directions for edp and globe transformations. This defaults to "none".
-
latr latitudeRef
This specifies a reference latitude in degrees for use when map
is specified as "edp" or "globe". This will also center the plot
viewport in latitude when map is "merc" or "geog".
This defaults to "0.0".
-
lonr longitudeRef
This specifies a reference longitude in degrees for use when map
is specified as "edp" or "globe". This will also center the plot
viewport in longitude when map is "merc" or "geog".
This defaults to "0.0".
-
range range
This specifies a X-axis plot window range in degrees for use when
the viewport is displaying in map coordinates. Map viewports are always
centered with latr, lonr.
This defaults to "40.0".
-
xmode modeXaxis
This must be one of "lin", "log", or "time"
and specifies whether the X-axis scaling in the viewport window will
be linear, logarithmic or if the X-axis represents time.
This defaults to "lin".
-
ymode modeYaxis
This must be one of "lin", "log", or "time"
and specifies whether the Y-axis scaling in the viewport window will
be linear, logarithmic or if the Y-axis represents time.
This defaults to "lin".
-
xleft leftdataWorldcoords
This specifies the X-axis data value in transformed world coordinates that will map
onto the left side of the viewport window. This is normally specified
as a floating number, unless the xmode option has been specified
as "time", in which case this can be specified as a normal
Antelope absolute time value in any of the forms allowed in str2epoch(3).
-
xright rightdataWorldcoords
This specifies the X-axis data value in transformed world coordinates that will map
onto the right side of the viewport window. This is normally specified
as a floating number, unless the xmode option has been specified
as "time", in which case this can be specified as a normal
Antelope absolute time value in any of the forms allowed in str2epoch(3).
-
xtranslate xpixels
This will cause a X-direction translation of the world coordinate system
relative to the viewport window. It is used primarily to smoothly pan
a plot window using the cursor. The xpixels argument is the number
of pixels to translate in the X-direction. The translation is temporary
and does not effect the xleft and xright world coordinate scales
until xpixels is set to "apply", which causes the xleft and
xright world coordinate scales to change to match the current
translated viewport window.
-
xgain xgain, xgain_anchor xgain_anchor
These will cause a X-direction temporary scaling of the world coordinate system
relative to the viewport window. It is used primarily to smoothly zoom in or zoom out
a plot window using the cursor. The xgain argument is the X-gain
factor to be applied, with "1.0" preserving the current scale, > 1.0 causing
the plot to zoom in by that factor and < 1.0 causing the plot to zoom out by that factor.
The xgain_anchor argument is the
X-direction pixel coordinate, relative to the parent canvas window, that
should not move in the viewport window. The translation is temporary
and does not effect the xleft and xright world coordinate scales
until xgain is set to "apply", which causes the xleft and
xright world coordinate scales to change to match the current
translated viewport window.
-
preserve_xscale {yes|no}
If this is set to yes, then whenever the viewport is resized, the horizontal scale factor will
be maintained by automatically changing the viewport left side and right side world coordinates so that
the world coordinate at the center of the viewport remains at the center after the resizing.
This is typically used with maps and other displays where the scales need
to be preserved when resizing the viewport. Note this is only used when the viewport is resized.
This defaults to no.
-
ybottom bottomdataWorldcoords
This specifies the Y-axis data value in transformed world coordinates that will map
onto the bottom side of the viewport window. This is normally specified
as a floating number, unless the ymode option has been specified
as "time", in which case this can be specified as a normal
Antelope absolute time value in any of the forms allowed in str2epoch(3).
-
ytop topdataWorldcoords
This specifies the Y-axis data value in transformed world coordinates that will map
onto the top side of the viewport window. This is normally specified
as a floating number, unless the ymode option has been specified
s "time", in which case this can be specified as a normal
Antelope absolute time value in any of the forms allowed in str2epoch(3).
-
ytranslate ypixels
This will cause a Y-direction translation of the world coordinate system
relative to the viewport window. It is used primarily to smoothly pan
a plot window using the cursor. The ypixels argument is the number
of pixels to translate in the Y-direction. The translation is temporary
and does not effect the ybottom and ytop world coordinate scales
until ypixels is set to "apply", which causes the ybottom and
ytop world coordinate scales to change to match the current
translated viewport window.
-
ygain ygain, ygain_anchor ygain_anchor
These will cause a Y-direction temporary scaling of the world coordinate system
relative to the viewport window. It is used primarily to smoothly zoom in or zoom out
a plot window using the cursor. The ygain argument is the Y-gain
factor to be applied, with "1.0".0 preserving the current scale, > 1.0 causing
the plot to zoom in by that factor and < 1.0 causing the plot to zoom out by that factor.
The ygain_anchor argument is the
Y-direction pixel coordinate, relative to the parent canvas window, that
should not move in the viewport window. The translation is temporary
and does not effect the ybottom and ytop world coordinate scales
until ygain is set to "apply", which causes the ybottom and
ytop world coordinate scales to change to match the current
translated viewport window.
-
preserve_yscale {yes|no}
If this is set to yes, then whenever the viewport is resized, the vertical scale factor will
be maintained by automatically changing the viewport top side and bottom side world coordinates so that
the world coordinate at the center of the viewport remains at the center after the resizing.
This is typically used with maps and other displays where the scales need
to be preserved when resizing the viewport. Note this is only used when the viewport is resized.
This defaults to no.
-
constant_aspect constant_aspect
This is a floating point number that causes the Y-axis scaling to be slaved to the X-axis
scaling to preserve constant_aspect aspect ratio of the X world coordinate scaling to the Y world coordinate scaling
expressed as X-scaling/Y-scaling. If this is <= 0.0 then this option is disabled.
Note that this does not relate to the physical aspect ratio of the viewport itself, but rather to the aspect
ratio of the world coordinate scaling so that a value of 1.0 would result in world coordinate Y increments that would
have the same physical size as world coordinate X increments. This is typically used for maps. Note that the scaling is relative to the
transformed coordinates (see option wtran). The Y-axis ytop and ybottom values are adjusted automatically according
to the center_yscale option (see below). If center_yscale is set to no, then the ytop parameter
is automatically adjusted relative to the existing ybottom parameter to preserve the scaling aspect ratio relative
to the existing xleft and xright parameters (which are unchanged).
If center_yscale is set to yes, then both the ytop and ybottom parameters
are automatically adjusted to preserve the scaling aspect ratio relative
to the existing xleft and xright parameters (which are unchanged) so that the Y world coordinate at the center of the viewport
window does not move.
This defaults to 0.0.
-
center_yscale {yes|no}
Used in conjuntion with constant_aspect option as described above.
This defaults to no.
-
zoom xw_anchor yw_anchor xgain ygain
This is a convenience configuration option that is used to zoom in and out the viewport
world coordinates. The xgain and ygain values are as described previously. Typically,
for constant aspect ratio zooming in/out, these are set to the same value.
The gain anchor values are expressed in floating point world coordinates by xw_anchor and yw_anchor.
Note that unlike the xgain, ygain options, this one applies the changes permanently and does not require
a call to apply the changes.
Note that the xw_anchor, yw_anchor, xgain and ygain strings must
be contained within a single string separated by white space.
-
fill fillColor
Specifies a color to use for filling the background of the data viewport
window. Can be specified in any of the forms documented in QColor::setNamedColor(3).
If this is specified as a "" string, then no background will be rendered
for the data viewport window.
This defaults to "".
-
fill_frame framefillColor
Specifies a color to use for filling the background of the entire viewport
frame, including both the data viewport and the margin areas.
Can be specified in any of the forms documented in QColor::setNamedColor(3).
If this is specified as a "" string, then no background will be rendered
for the viewport frame. Note that the frame is rendered before the data
viewport window so that if both fill and fill_frame are specified
then the fill background will be painted on top of the fill_frame
background. Also note that if both fill and fill_frame are NULL, then
the viewport is invisible.
This defaults to "".
-
default_event_interaction defaultEventInteraction
This is a boolean and indicates whether or not the BQViewport object will intercept mouse and keyboard events
to implement basic viewport scaling interaction as described below. If this is set to no, then the BQViewport object
will not process mouse and keyboard events. This defaults to "yes".
DEFAULT EVENT INTERACTION
BQViewport objects can pan, zoom and center the viewport window according to mouse and keyboard events when the default_event_interaction configuration
parameter is set to yes. Left mouse button click and drag will cause the viewport to pan. If the c key is pressed, then the viewport will change so that the
world coordinates at the mouse position when the c key was pressed are panned to the center of the viewport. If i or I keys are pressed the viewport is zoomed in.
If o or O keys are pressed the viewport is zoomed out. Shift left mouse button click and drag will make a rubber band window that will be zoomed into when the button is released.
Shift right mouse button click and drag will make a rubber band window that will be zoomed out of when the button is released.
The mouse wheel will also causing zooming in and out in the normal fashion.
SEE ALSO
bqplot(3), BQViewportItem(3), BQConfigure(3), BQLayer(3)
AUTHOR
Danny Harvey, BRTT