• Antelope Release 5.9 Mac OS X 10.13.2 2019-05-01

 

NAME

bqplot - BRTT Qt graphics extensions

SYNOPSIS


$(QTNATIVELIBS) -lbqplot_native -lbanner -lbrttutil -lbumapdata $(DBLIBS) $(TRLIBS)

#include "BQ.h"

class BQViewport

class BQGraphicsContext

class BQLayer

class BQAxes

class BQText

class BQTextPopup

class BQPolyline

class BQPolypoint

class BQGlyphs

class BQGlyphsGraphicsContext

class BQTaskbar

class BQMap

class BQMapevents

helper classes:

class BQViewportItem

class BQConfigure

class BQEvent

class BQGlyph

class BQShape

class BQPolyDraw

class BQScaledata

class BQNavigator

DESCRIPTION

These are special Qt-based graphics extensions, available through libbqplot_native (and libbqplot_x11) dynamic link library, written as c++ classes. This is the first production version of the Qt replacement for the venerable tcl/tk based buplot libraries used in tcl, perltk and python/tkinter. Although this package is loosely based on the old buplot concepts, this new package provides a much more capable GUI in terms of functionality, performance, configurability and the quality of the graphical renderings than the old tcl/tk based package. This package is a complete rewrite of the old buplot package in terms of the APIs. This package also makes use of the capabilities in Qt and the c++ programming language. The package documented here consists of c++ classes that can only be used in c++ application programs. However, there is an accompanying python extension package that provides python programmers interfaces into this QT based GUI package.

The viewport concept used in buplot is also used in bqplot. All bqplot graphical objects, except for the BQViewport objects themselves, must be associated with and are slaved to a BQViewport object. The BQViewport objects display a graphics window in which data in its own world coordinates are scaled in a consistent fashion into pixel coordinates. Non-linear scalings such as logarithmic scaling and several different map projection scalings for data longitude-latitude coordinates are supported.

Another concept brought over from the tcl/tk based buplot package is the specification of configuration options through variable argument lists of key-value pairs. In the bqplot package this is extended to automatic parsing of configuration parameters through Antelope parameter file objects.

Neither building this package nor using the package by an application programmer requires the use of the Qt moc compiler. The Qt signal-slot mechanism for connecting "signals" with "receivers" is not used by this package. Mainly, this package uses the lower level Qt rendering primitives along with direct event processing utilizing more traditional callback mechanisms.

OVERVIEW OF ITEM TYPES

Other than BQViewport objects, all other of the bqplot objects must be parented by a single BQViewport object. The concept of viewports is standard within graphical software packages. The idea is that a viewport acts as a window within a "virtual graphical device", such as a graphical monitor screen, that is used to display data that is represented in some data-centric "world" coordinate system. The BQViewport class is the only bqplot class that inherits BQwidget and none of the other bqplot classes inherit the BQViewport class. Therefore, as far as Qt is concerned, the only widgets created from the bqplot package are the BQViewport objects (the only exception to this are BQTextPopupWidget items that display text popup messages in top-level QWidgets). All of the bqplot items slaved to a BQViewport object are managed through the BQViewport object. This includes all paint, resize, mouse and keyboard events. This approach allows for very high performance and low overhead in situations where there are potentially many thousands of graphics objects that need to be displayed as rapidly as possible in a single viewport. Rendering order of BQViewport child objects, along with independent show/hide capabilities, are managed by the BQViewport objects.

The BQViewport object is a widget that will automatically transform data in world coordinates into integer X-Y pixel data coordinates that are suitable for passing directly into the virtual display device drivers (in this case the Qt drivers). A BQViewport can be thought of as a virtual canvas item since it does not by itself result in display graphics (the exception to this is that it will paint certain background colors). However, use of any of the other extension objects require an existing BQViewport object, which is used to define the world to virtual device coordinate transformations. As mentioned previously BQViewport objects also control almost all aspects of Qt event processing for all of its child objects.

A set of axes, axis labels and plot grid lines can be created with a BQAxes object. Text can be anchored in world coordinates, justified and rotated using a BQText object. Complex polyline objects can be rendered with a BQPolyline object. Polyline objects can be displayed as line outlines and/or as filled polygons. A set of plot symbols can be displayed with the BQPolypoint object. Each plot symbol shape, color, and an associated text label can be specified independently. Both BQPolyline and BQPolypoint objects can use buvector(3) C-library for representing vectors of plot coordinates and symbol attributes. Geographic mapping data sets can be displayed with BQMap objects which will make geographic maps of water areas, land areas, coastlines, rivers and political boundaries for the entire world at high resolution, as well as earth-surface images either from photography or virtual images such as digital elevation grids. Base map rendering with overlying plot glyphs representing earthquake origins along with the station locations corresponding to arrivals and detections can be displayed with BQMapevents objects. A generalized double buffering resource can be created with a BQLayer object which also acts as an independent graphics "layer" that can be made visible or invisible or can be translucent.

In addition to the main display objects there are several user interface and other ancillary display objects. A simple user interface can be created using BQTaskbar objects. Informational text popup windows can be created with BQTextPopup objects. Another feature of this package is the use of graphics contexts, through the BQGraphicsContext and BQGlyphsGraphicsContext objects. A graphics context is a collection of graphics context items that define the appearance of graphics objects such as lines and glyphs. Examples of graphics context items are pen color, fill brush color, linewidth, linestyle and opacity. The bqplot BQGraphicsContext and BQGlyphsGraphicsContext objects facilitate generalized and easy to configure graphics contexts for many of the other bqplot objects.

OBJECT PARAMETERS

The bqplot objects all utilize a standard configurator approach in which the many object parameters are configured through either Antelope parameter file based key-value pairs, or variable argument list key-value pairs. This avoids the plethora of class methods for setting the many configuration parameters. For the variable argument list constructors and configuration methods, all values, as well as keys, must be in character string form.

EXAMPLES

Following is an example for using many of the bqplot extension objects.

% cat Makefile
BIN=        bqplot_test_graph

fflags=
ldflags=

cflags = -g
cxxflags = -g -I$(QTINCLUDE)
ldlibs    = -lbqplot_native $(QTNATIVELIBS) -lbanner -lbrttutil $(DBLIBS)

include $(ANTELOPEMAKE)

OBJS= bqplot_test_graph.o
$(BIN) : $(OBJS)
    $(CXX) $(CXXFLAGS) -g -o $(BIN) $(OBJS) $(LDFLAGS) $(LDLIBS)
%
% cat bqplot_test_graph.cc

#include "BQ.h"

#define STATE_INITIAL       0
#define STATE_PAN           1
#define STATE_DRAG_POINT    2

int
main (int argc, char **argv)

{
    QApplication qapp(argc, argv);

    qapp.setApplicationName("bqplot_test_graph");

    QWidget *widget = new QWidget();
    widget->setWindowTitle("bqplot_test_graph");
    widget->show();
    widget->resize (800, 800);

    BQViewport *myvp = new BQViewport(widget);

    myvp->configure (
            "xleft",        "-1.0",
            "xright",       "5.0",
            "ybottom",      "-1.1",
            "ytop",         "1.1",
            "mleft",        "80",
            "mright",       "20",
            "mbottom",      "50",
            "mtop",         "30",
            "fill_frame",   "lightblue",
            "fill",         "#e0e0e0",
            NULL);

    BQAxes *myax = new BQAxes(myvp);
    myax->configure (
            "xlabel",               "My X-stuff",
            "ylabel",               "My Y-stuff",
            "xformat",              "%.1f",
            "yformat",              "%.1f",
            "linewidth_box",        "0",
            "linewidth_tics",       "2",
            "linewidth_tics_small", "0",
            "axis_style",           "sw",
            "tic_style",            "siwinoeo",
            "linewidth_grids",      "2",
            "linewidth_grids_small","0",
            "color_grids",          "black",
            "color_grids_small",    "#c0c0c0",
            NULL);

    BQText *mytx = new BQText(myvp, (char *) "My text", (char *) "0.5v", (char *) "top+10");
    mytx->configure (
            "color_text",   "red",
            "font",         "Times 14 Bold",
            "justification","s",
            "angle",        "0",
            NULL);

    BQPolyline *myplt = new BQPolyline(myvp);
    myplt->configure (
            "test",         "on",
            "color_outline","#400000ff",
            "linewidth",    "3",
            NULL);

    myvp->setLayer ("layer1");
    myax->setLayer ("layer1");
    mytx->setLayer ("layer1");
    myplt->setLayer ("layer1");

    char vecpl[256];
    if (buvector_create (0, 1, NULL, vecpl) == NULL) {
        BQ_die (0, "buvector_create() error.\n");
    }

    double y;
    y = 0.6;
    buvector_append (vecpl, -1, 0.1, &y, NULL);
    y = 0.4;
    buvector_append (vecpl, -1, 1.9, &y, NULL);
    y = 0.9;
    buvector_append (vecpl, -1, 0.3, &y, NULL);
    y = 0.8;
    buvector_append (vecpl, -1, 0.4, &y, NULL);
    y = 0.6;
    buvector_append (vecpl, -1, 0.1, &y, NULL);

    BQPolyline *mypl = new BQPolyline(myvp);
    mypl->configure (
            "vector",       vecpl,
            "color_fill",   "#80ffff00",
            "color_outline","red",
            "linewidth",    "2",
            NULL);

    char vecpp[256];
    if (buvector_create (0, 1, NULL, vecpp) == NULL) {
        BQ_die (0, "buvector_create() error.\n");
    }

    y = 0.6;
    buvector_append (vecpp, -1, 0.1, &y, (char *)"Apt {o=black f=white n=red sz=30 sy=bb,1,2,3,4,5,6}");
    y = 0.4;
    buvector_append (vecpp, -1, 1.9, &y, (char *)"Bpt {f=#400000b0 sz=30 sy=square}");
    y = 0.9;
    buvector_append (vecpp, -1, 0.3, &y, (char *)"Cpt {f=white o=#00ff00 sz=20 sy=star}");
    y = 0.8;
    buvector_append (vecpp, -1, 0.4, &y, (char *)"Dpt {f=black o=orange sz=15}");

    BQPolypoint *mypp = new BQPolypoint(myvp);
    mypp->configure (
            "vector",       vecpp,
            "symbol",       "triangle",
            "color_fill",   "white",
            "color_outline","green",
            "font",         "Helvetica 12 Bold",
            "color_text",   "brown",
            "linewidth",    "2",
            "showtext",     "1",
            "size",         "50",
            "interaction",  "move",
            NULL);

    mypp->setGlyphCallback( [&] (BQGlyph *glyph, BQEvent *event, BQ_ClientData client_data) {
            QMouseEvent *mevent;
            QPointF pt;
            double xw, yw;

            int state = glyph->getQEventState ();
            switch (state) {
            default:
                break;
            case BQ_QEVENT_STATE_PAN:
                switch (event->type) {
                default:
                    break;
                case BQ_QEVENT_TYPE_MOUSEMOVE:
                    myvp->getWcoords (event->pt.x(), event->pt.y(), &xw, &yw);
                    buvector_put (vecpl, glyph->getIndex(), xw, &yw, NULL);
                    if (glyph->getIndex() == 0) {
                        buvector_put (vecpl, 4, xw, &yw, NULL);
                    }
                    mypl->configure ( "vector", vecpl, NULL );
                    mypl->setItemStale();
                    break;
                }
                break;
            }

            delete event;

            return (BQ_QEVENT_RETURN_OK);
        }, NULL);

    mypl->setLayer ("layer2");
    mypp->setLayer ("layer2");

    qapp.exec();

    exit (0);
}

SEE ALSO

BQViewport(3), BQAxes(3), BQText(3), BQPolyline(3), BQPolypoint(3), BQMap(3), BQMapevents(3), BQLayer(3), BQTaskbar(3), BQTextPopup(3), BQGraphicsContext(3), BQGlyphs(3), BQGlyphsGraphicsContext(3)

AUTHOR

Danny Harvey, BRTT
Printer icon