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

 

NAME

pythonbqplot - Python interface to BRTT Qt graphics extensions

SYNOPSIS


sys.path.append( os.environ['ANTELOPE'] + '/data/python' )

import antelope.bqplot as bqplot

DESCRIPTION

This module provides a simple python-accessible interface to the bqplot(3) library of c++ classes for BRTT specialized Qt-based graphics extensions. Note that these extensions will not work properly in generic python interpreters. They will work properly only in the specialized bqpy(1) python interpreter.

OBJECTED ORIENTED INTERFACES

Following are classes that provide object level interfaces.

A NOTE ON CALLBACKS

The normal Qt signal - slot mechanism used in c++ code to connect widget pseudo signals to slots, user defined functions, has been replaced in the python bqplot module with a simple python callback mechanism, very similar to callbacks used in the python tkinter module. All of the bqplot widget class registercallback methods use this mechanism. Each widget class that provides interaction in which the application script can be notified in response to a Qt generated event, such as a mouse click on a button, will contain a method named registercallback, that is used in the application program to define the python callback function to be invoked. For each class that can notify the python script through a callback function, the particular callback function is registered with the object with the following syntax.

<object>.registercallback(proc, client_string='0')

where <object> is the particular class object for which the callback is to be registered. The bqplot module always executes the callbacks with the following syntax.

<callback>(pfstring)

where <callback> is the callback function or method as defined in registercallback and pfstring is a parameter file string that contains all of the parameters needed by the callback function or method. In registercallback the proc argument can be a static python function, or a python object, or a lambda expression. If proc is a static python function or a lambda expression, then that will be the function executed in the callback by the Qt class widget object. Note that the function will be called with the syntax defined above. Therefore, if proc is a static function, then it must contain the single argument pfstring. If proc is a lambda expression, then the variable list must contain the variable pfstring so that the anonymous function will have the proper argument list. Of course the actual function defined by the lambda expression that is called in the lambda generated anonymous function may use the pfstring argument as needed, or even not use it at all if it is not needed, however the pfstring variable must appear in the lambda argument list in order for the anonymous function to be properly constructed. If proc is a python class object, then its method defined by the string client_string will be called as the callback with the single argument pfstring. For all forms of callbacks the client_string string is put into the pfstring passed to callback functions and methods which can be used by the application program to pass application specific information. Various examples of callbacks are shown in the Widgets Class EXAMPLE below.

GraphicsEngine Class

this makes a connection to the graphics server thread and needs to always be called first. Note that no windows are made with this call.

Bqplot Class

This class contains class methods for various utility functions. There is no constructor.

MainWindow Class

Make a Qt QMainWindow which provides for a top menu bar as well as a tool bar, docking widget sites and a bottom status bar. See
http://doc.qt.io/qt-5/qmainwindow.html#details.

Where parent is the parent window of the child QMainWindow window. If parent is the GraphicsEngine object, or is 'none', or is None, then the QMainWindow will be a new top level window. Since multiple top level windows can be made, there needs to be a way to know when to quit the program when a top level window is destroyed through the window manager. The close_window flag can be used to control that. If it is not specified, then the default behavior is for the first top level window created to cause the program to exit and all other windows to be destroyed when the window manager close window button is clicked and for destruction of other top level windows to not cause the program to exit. This behavior can be customized by specifying close_window.

MainWindow Class EXAMPLE


#!/usr/bin/env bqpy

import os
import sys
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *

ge = GraphicsEngine()

mainwindow = MainWindow(ge)
mainwindow.geometry(200, 200)
mainwindow.show()

ge.qtmainloop()
ge.pymainloop()


DockWidget Class

Create a dock widget that is used as a container for other windows that can dock to a MainWindow. See http://doc.qt.io/qt-5/qdockwidget.html#details.
  • CONSTRUCTOR
    bqplot.DockWidget(parent, child, title)
    

Where parent is the parent window of the DockWidget object and must be a MainWindow object, child is the DockWidget contents and must be any QWidget object other than viewport item objects, and title is a title for the dock widget. Note that child can be another MainWindow object.

  • METHODS
    • delete()
      Delete the dock widget.
    • show()
      Show the dock widget.
    • hide()
      Hide the dock widget.
    • update()
      Update the dock widget.
    • setfloating(ans)
      If ans is 0, then the dock widget will be docked to its parent MainWindow, otherwise the dock widget will be undocked, or floating, from its parent MainWindow. Note that by default dock widgets are attached at startup.

Menubar Class

Create a menu bar that can be populated with pull down menus.
  • CONSTRUCTOR
    bqplot.Menubar(parent)
    

Where parent is the parent window of the menu bar. If parent is set to a MainWindow object, then the menu bar will occupy the top menu bar of the QMainWindow.

  • METHODS
    • delete()
      Delete the menu bar.
    • show()
      Show the menu bar.
    • hide()
      Hide the menu bar.
    • update()
      Update the menu bar.
    • getgeometry()
      Return the menubar geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • menu = addmenu(title)
      Add a menu to the menubar with title title. Returns the menu as a Menu class object (defined below).

Menu Class

Create a menu that can be populated with items and other pull down menus.
  • CONSTRUCTOR
    bqplot.Menu(parent)
    

Where parent is the parent window of the menu.

  • METHODS
    • delete()
      Delete the menu.
    • show()
      Show the menu.
    • hide()
      Hide the menu.
    • update()
      Update the menu.
    • getgeometry()
      Return the menu geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • menu = addseparator()
      Add a separator line item to the menu.
    • menu = addmenu(title)
      Add a another menu as an item to the menu with title title. Returns the menu as a Menu class object.
    • action = additem(title)
      Add an item to the menu with title title. Returns the item as an Action class object (defined below) which can be used to implement a callback function.
    • action = addwidget([action_parent,] widget)
      Add widget widget, such as a Checkbox object, to the menu. Returns the item as an Action class object (defined below) which can be used to implement a callback function. if action_parent is specified then it will be used as the parent of the returned Action object. Otherwise, the parent of the returned Action object is set to the parent of the Menu object.
    • popup()
      This will cause a menu to popup in its parent window positioned at the current cursor position. The menu will disappear when a selection is made.

Action Class

Create an object that can be used to implement widget actions as a callback.
  • CONSTRUCTOR
    bqplot.Action(parent, title)
    

Where parent is the parent window of the action and title is a title used when the action is a menu item.

  • METHODS
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. The callback pfstring parameter file string contents are as follows.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the Action object.
      • text
        This is the title string specified in the Action constructor.

Menubar Class EXAMPLE


#!/usr/bin/env bqpy

import os
import sys
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *

ge = GraphicsEngine()

mainwindow = MainWindow(ge)
mainwindow.geometry(200, 200)

mb = Menubar(mainwindow)
file_menu = mb.addmenu('&File')
quit_item = file_menu.additem('Quit')
quit_item.registercallback(lambda pffile: ge.quit())

mainwindow.show()

ge.qtmainloop()
ge.pymainloop()

File Dialog Class

Create a file dialog that can be used for choosing files to read.
  • CONSTRUCTOR
    bqplot.FileDialog(parent, caption, directory, filter)
    

Where parent is the parent window of the file dialog window, caption is a caption string to be displayed in the file dialog window, directory is the file directory for displaying files and filter is a filter spring applied to the files to be displayed. Note that the caption may or may not be displayed depending on the native widget used to implement the file dialog (for instance on mac systems the native cocoa file dialog does not display captionfP). The format for filter is defined at http://doc.qt.io/qt-5/qfiledialog.html#details.

  • METHODS
    • getlist()
      Once the file dialog has been closed by pressing one of the "Open" or "Cancel" buttons, then the selected files can be retrieved by this method which returns the list of selected files as a tuple. The file names contain the full absolute paths.

Save File Dialog Class

Create a file dialog that can be used for choosing files, or specifying new files, to write.
  • CONSTRUCTOR
    bqplot.SaveFileDialog(parent, caption, directory, filter)
    

Where parent is the parent window of the file dialog window, caption is a caption string to be displayed in the save file dialog window, directory is the file directory for displaying files and filter is a filter spring applied to the files to be displayed. Note that the caption may or may not be displayed depending on the native widget used to implement the save file dialog (for instance on mac systems the native cocoa save file dialog does not display captionfP). The format for filter is defined at http://doc.qt.io/qt-5/qfiledialog.html#details.

  • METHODS
    • getname()
      Once the save file dialog has been closed by pressing one of the "Save" or "Cancel" buttons, then the selected save file can be retrieved by this method which returns the name of the file as a string. The file name contains the full absolute paths.

Print Dialog Class

Create a print dialog that can be used for printing window contents, either to files or to a printer.
  • CONSTRUCTOR
    bqplot.PrintDialog(parent, widget, image=None)
    

Where parent is the parent window of the display, widget is the widget to be printed and image, if specified will cause a raster image of the window to be printed. If image is not specified, or it is set to 0, then the print output will be made using Qt graphics primitive objects instead of first converting to a raster image, which will provide the highest possible resolution for PDF print files, but can produce artifacts when displaying Qt widgets. Note that the print dialog window uses the native widget to implement the print dialog. Because of this it is generally not possible to "pre-load" default print file names.

Print Class

Print a widget window to a print PDF file.
  • CONSTRUCTOR
    bqplot.Print(widget, file_name, image=None, orientation='protrait')
    

Where widget is the widget to be printed, file_name is the PDF file name which should end in .pdf and be a complete absolute path name, and image, if specified will cause a raster image of the window to be printed. If image is not specified, or it is set to 0, then the print output will be made using Qt graphics primitive objects instead of first converting to a raster image, which will provide the highest possible resolution for PDF print files, but can produce artifacts when displaying Qt widgets. The orientation can be specified with orientation which should be one of 'protrait' or 'landscape'.

FileDialog and PrintDialog Class EXAMPLE


#!/usr/bin/env bqpy

import os
import sys
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *

def filedialog(parent):
    print (FileDialog(parent,'Open File','.','').getlist())

ge = GraphicsEngine()

mainwindow = MainWindow(ge)
mainwindow.geometry(200, 200)

mb = Menubar(mainwindow)
file_menu = mb.addmenu('&File')
file_item = file_menu.additem('Open...')
file_item.registercallback(lambda pffile: filedialog(mainwindow))
print_item = file_menu.additem('Print...')
print_item.registercallback(lambda pffile: PrintDialog(mainwindow, mainwindow, 1))
quit_item = file_menu.additem('Quit')
quit_item.registercallback(lambda pffile: ge.quit())

mainwindow.show()

ge.qtmainloop()
ge.pymainloop()

Frame Class

Create an empty window (frame) that is used as a container for other windows. See http://doc.qt.io/qt-5/qframe.html#details.
  • CONSTRUCTOR
    bqplot.Frame(parent, close_window=None)
    

Where parent is the parent window of the child frame window. If parent is the GraphicsEngine object, or is 'none', or is None, then the frame will be a new top level window. Since multiple top level windows can be made, there needs to be a way to know when to quit the program when a top level window is destroyed through the window manager. The close_window flag can be used to control that. If it is not specified, then the default behavior is for the first top level window created to cause the program to exit and all other windows to be destroyed when the window manager close window button is clicked and for destruction of other top level windows to not cause the program to exit. This behavior can be customized by specifying close_window.

  • METHODS
    • delete()
      Delete the frame and all of its children.
    • show()
      Show the frame.
    • hide()
      Hide the frame.
    • update()
      Update the frame.
    • getgeometry()
      Return the frame geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • geometry(w, h, fixed=0)
      Set the geometry of the frame window to w pixels width, h pixels height and cause the size to be fixed if fixed is non-zero.
    • geometry(x, y, w, h, fixed=0)
      Set the geometry of the frame window to w pixels width, h pixels height, at position x y pixels and cause the size to be fixed if fixed is non-zero.
    • screengeometry(w, aspect, screen, fixed=0)
      Set the geometry of the frame window to w pixels width, with the height determined by aspect = width divided by height, on screen number screen. Cause the size to be fixed if fixed is non-zero.
    • position(x, y)
      Set the frame absolute position on the screen.
    • seteventtransparency()
      This will cause Qt events, other than paint events, to not be sent to this frame and its children.
    • cleareventtransparency()
      This will cause all Qt events to be sent to this frame and its children.
    • totop()
      Bring the frame to the top of the display stack.
    • tobottom()
      Send the frame to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the frame to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the frame to w pixels.
    • maximumheight(h)
      Set the maximum height of the frame to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the frame to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the frame to w pixels.
    • minimumheight(h)
      Set the minimum height of the frame to h pixels.
    • title(title)
      Set the title of the frame to title.

Dialog Class

Create a dialog window. See http://doc.qt.io/qt-5/qdialog.html#details.
  • CONSTRUCTOR
    bqplot.Dialog(parent)
    

Where parent is the parent window of the child dialog window.

  • METHODS
    • delete()
      Delete the dialog and all of its children.
    • show()
      Show the dialog.
    • hide()
      Hide the dialog.
    • update()
      Update the dialog.
    • getgeometry()
      Return the dialog geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • totop()
      Bring the dialog to the top of the display stack.
    • tobottom()
      Send the dialog to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the dialog to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the dialog to w pixels.
    • maximumheight(h)
      Set the maximum height of the dialog to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the dialog to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the dialog to w pixels.
    • minimumheight(h)
      Set the minimum height of the dialog to h pixels.
    • title(title)
      Set the title of the dialog to title.

Grid Layout Class

Create a grid layout for arranging window geometries. See http://doc.qt.io/qt-5/qgridlayout.html#details.
  • CONSTRUCTOR
    bqplot.GridLayout(parent)
    

Where parent is the parent window of the grid layout. See http://doc.qt.io/qt-5/qgridlayout.html#details.

  • METHODS
    • delete()
      Delete the grid layout.
    • update()
      Update the grid layout.
    • getgeometry()
      Return the grid layout geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • addwidget(widget, fromrow, fromcolumn, rowspan, columnspan)
      Add the widget specified by widget to the grid layout starting at row fromrow and column fromcolumn and spanning over rowspan rows and columnspan columns.
    • columnstretch(column, stretch)
      This sets the stretch factor, stretch specified as an integer, for column column. Stretch factors determine how individual columns are resized realtive to the other columns when the underlying parent widget is resized. For instance, if column 1 has a stretch factor of 2 and the other columns have a stretch factor of 1, then column 1 will get twice the width of the other columns when the underlying parent widgte is resized.
    • rowstretch(row, stretch)
      This sets the stretch factor, stretch specified as an integer, for row row. Stretch factors determine how individual rows are resized realtive to the other rows when the underlying parent widget is resized. For instance, if row 1 has a stretch factor of 2 and the other rows have a stretch factor of 1, then row 1 will get twice the height of the other rows when the underlying parent widgte is resized.
    • columnwidth(column, width)
      Set minimum width of column column to width pixels.
    • rowheight(row, height)
      Set minimum height of row row to height pixels.
    • spacing(hspacing, vspacing)
      Set the horizontal inter-widget spacing to hspacing pixels and the vertical inter-widget spacing to vspacing pixels.
    • hspacing(hspacing)
      Set the horizontal inter-widget spacing to hspacing pixels.
    • vspacing(vspacing)
      Set the vertical inter-widget spacing to vspacing pixels.
    • margins(left, top, right, bottom)
      Set the margins around the grid layout in pixels.

Form Layout Class

Create a form layout for arranging window geometries. See http://doc.qt.io/qt-5/qformlayout.html#details.
  • CONSTRUCTOR
    bqplot.FormLayout(parent)
    

Where parent is the parent window of the form layout. See http://doc.qt.io/qt-5/qformlayout.html#details.

  • METHODS
    • delete()
      Delete the form layout.
    • update()
      Update the form layout.
    • getgeometry()
      Return the form layout geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • addrow(widget, text)
      Add the widget specified by widget to the form layout using the text label text.
    • spacing(hspacing, vspacing)
      Set the horizontal inter-widget spacing to hspacing pixels and the vertical inter-widget spacing to vspacing pixels.
    • hspacing(hspacing)
      Set the horizontal inter-widget spacing to hspacing pixels.
    • vspacing(vspacing)
      Set the vertical inter-widget spacing to vspacing pixels.
    • margins(left, top, right, bottom)
      Set the margins around the form layout in pixels.

Splitter Class

Create a splitter layout for arranging window geometries. See http://doc.qt.io/qt-5/qsplitter.html#details.
  • CONSTRUCTOR
    bqplot.Splitter(parent, orientation='horizontal')
    

Where parent is the parent window of the form layout. The orientation of the child windows is specified by orientation which must be one of 'horizontal', for horizontally arranged child windows with vertical splitter handles, or 'vertical', for vertically arranged child windows with horizontal splitter handles.

  • METHODS
    • delete()
      Delete the splitter.
    • show()
      Show the splitter.
    • hide()
      Hide the splitter.
    • update()
      Update the splitter.
    • getgeometry()
      Return the splitter geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • setsizes(sizes)
      This sets the sizes of the individual splitter widgets to the list of integer pixels sizes specified by sizes. If the splitter is vertical, then the sizes list must correspond to the widget heights from top to bottom. If the splitter is horizontal, then the sizes list must correspond to the widget widths from left to right.
    • totop()
      Bring the splitter to the top of the display stack.
    • tobottom()
      Send the splitter to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the splitter to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the splitter to w pixels.
    • maximumheight(h)
      Set the maximum height of the splitter to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the splitter to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the splitter to w pixels.
    • minimumheight(h)
      Set the minimum height of the splitter to h pixels.
    • addwidget(widget, index)
      Add the widget specified by widget to the splitter layout at index index.
    • stretch(index, factor)
      Set the integer stretch factor factor for the widget at position index index.

ScrollArea Class

Create a scrollarea layout for arranging window geometries. See http://doc.qt.io/qt-5/qscrollarea.html#details.
  • CONSTRUCTOR
    bqplot.ScrollArea(parent)
    

Where parent is the parent window of the scrollarea.

  • METHODS
    • delete()
      Delete the scrollarea.
    • show()
      Show the scrollarea.
    • hide()
      Hide the scrollarea.
    • update()
      Update the scrollarea.
    • getgeometry()
      Return the scrollarea geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • geometry(w, h, fixed=0)
      Set the geometry of the scrollarea to w pixels width, h pixels height and cause the size to be fixed if fixed is non-zero.
    • geometry(x, y, w, h, fixed=0)
      Set the geometry of the scrollarea to w pixels width, h pixels height, at position x y pixels and cause the size to be fixed if fixed is non-zero.
    • totop()
      Bring the scrollarea to the top of the display stack.
    • tobottom()
      Send the scrollarea to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the scrollarea to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the scrollarea to w pixels.
    • maximumheight(h)
      Set the maximum height of the scrollarea to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the scrollarea to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the scrollarea to w pixels.
    • minimumheight(h)
      Set the minimum height of the scrollarea to h pixels.
    • widget(widget)
      Set the widget to be scrolled by the scrollarea to widget.
    • widgetresizable({1|0})
      Set the widget resizable property in the scrollarea (see http://doc.qt.io/qt-5/qscrollarea.html#details).
    • enable_horizontalscrollbar({1|0})
      Enable, 1, or disable, 0, the horizontal scroll bar.
    • enable_verticalscrollbar({1|0})
      Enable, 1, or disable, 0, the vertical scroll bar.

Button Class

Create an interactive button. See http://doc.qt.io/qt-5/qpushbutton.html#details.
  • CONSTRUCTOR
    bqplot.Button(parent)
    

Where parent is the parent window of the button.

  • METHODS
    • delete()
      Delete the button.
    • show()
      Show the button.
    • hide()
      Hide the button.
    • update()
      Update the button.
    • getgeometry()
      Return the button geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • totop()
      Bring the button to the top of the display stack.
    • tobottom()
      Send the button to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the button to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the button to w pixels.
    • maximumheight(h)
      Set the maximum height of the button to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the button to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the button to w pixels.
    • minimumheight(h)
      Set the minimum height of the button to h pixels.
    • text(text)
      Set the button text to text.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This gets called whenever the button is pressed. The callback pfstring parameter file string contents are as follows.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the Button object.
      • text
        This is the text string specified in the text method.

Label Class

Create a simple non-interactive label. See http://doc.qt.io/qt-5/qlabel.html#details.
  • CONSTRUCTOR
    bqplot.Label(parent)
    

Where parent is the parent window of the label.

  • METHODS
    • delete()
      Delete the label.
    • show()
      Show the label.
    • hide()
      Hide the label.
    • update()
      Update the label.
    • getgeometry()
      Return the label geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • totop()
      Bring the label to the top of the display stack.
    • tobottom()
      Send the label to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the label to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the label to w pixels.
    • maximumheight(h)
      Set the maximum height of the label to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the label to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the label to w pixels.
    • minimumheight(h)
      Set the minimum height of the label to h pixels.
    • text(text)
      Set the label text to text.
    • selectable({0|1})
      Set the label selectable property. If this property is set, then all or part of the label can be selected by the mouse for a copy-paste operation.

Checkbox Class

Create an interactive checkbox. See http://doc.qt.io/qt-5/qcheckbox.html#details.
  • CONSTRUCTOR
    bqplot.Checkbox(parent)
    

Where parent is the parent window of the checkbox.

  • METHODS
    • delete()
      Delete the checkbox.
    • show()
      Show the checkbox.
    • hide()
      Hide the checkbox.
    • update()
      Update the checkbox.
    • getgeometry()
      Return the checkbox geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • totop()
      Bring the checkbox to the top of the display stack.
    • tobottom()
      Send the checkbox to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the checkbox to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the checkbox to w pixels.
    • maximumheight(h)
      Set the maximum height of the checkbox to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the checkbox to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the checkbox to w pixels.
    • minimumheight(h)
      Set the minimum height of the checkbox to h pixels.
    • text(text)
      Set the checkbox text to text.
    • state([{0|1}])
      Set or retrieve the checkbox state. If no argument is specified, then the state of the checkbox is returned. If an argument is specified, then the state of the checkbox will be set accordingly.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This gets called whenever the checkbox state is changed. The callback pfstring parameter file string contents are as follows.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the Checkbox object.
      • state
        This is the current state of the Checkbox object.

Combobox Class

Create an interactive combobox. See http://doc.qt.io/qt-5/qcombobox.html#details.
  • CONSTRUCTOR
    bqplot.Combobox(parent)
    

Where parent is the parent window of the combobox.

  • METHODS
    • delete()
      Delete the combobox.
    • show()
      Show the combobox.
    • hide()
      Hide the combobox.
    • update()
      Update the combobox.
    • getgeometry()
      Return the combobox geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • totop()
      Bring the combobox to the top of the display stack.
    • tobottom()
      Send the combobox to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the combobox to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the combobox to w pixels.
    • maximumheight(h)
      Set the maximum height of the combobox to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the combobox to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the combobox to w pixels.
    • minimumheight(h)
      Set the minimum height of the combobox to h pixels.
    • additems(items)
      Add items to a combox. items should be a single text string or a tuple of text strings.
    • clear()
      This will clear the items from a combobox.
    • text([text])
      If no argument is specified, then the text corresponding to the current state of the combobox, as specified in the additems method defined above, is returned. If text is specified, then the current state of the combox will be set according to the first combobox item that is the same as text.
    • index([index])
      This behaves like text except that an integer index is specified and returned. The index refers to the item index within the combobox where 1 is the first item.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This gets called whenever the combobox state is changed through mouse interaction. The callback pfstring parameter file string contents are as follows.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the Checkbox object.
      • text
        This is the current text of the Checkbox object.
      • index
        This is the current index of the Checkbox object.

LineEdit Class

Create an interactive single line text editor. See http://doc.qt.io/qt-5/qlineedit.html#details.
  • CONSTRUCTOR
    bqplot.LineEdit(parent)
    

Where parent is the parent window of the line editor.

  • METHODS
    • delete()
      Delete the line editor.
    • show()
      Show the line editor.
    • hide()
      Hide the line editor.
    • update()
      Update the line editor.
    • getgeometry()
      Return the line editor geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • totop()
      Bring the line editor to the top of the display stack.
    • tobottom()
      Send the line editor to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the line editor to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the line editor to w pixels.
    • maximumheight(h)
      Set the maximum height of the line editor to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the line editor to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the line editor to w pixels.
    • minimumheight(h)
      Set the minimum height of the line editor to h pixels.
    • text(text)
      Set the line editor text to text.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This gets called whenever the Return key is pressed. The callback pfstring parameter file string contents are as follows.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the LineEdit object.
      • text
        This is the current LineEdit object text string.
      • signal
        This is the Qt signal that created the event. The values can be textchanged, when the text has changed due to user interaction, or editingfinished, when a Return key was pressed, or a Tab key to switch the focus, or any other reason the focus changes, such as moving the cursor out of the LineEdit object.

Timer Class

Create a timer object. See http://doc.qt.io/qt-5/qtimer.html#details.
  • CONSTRUCTOR
    bqplot.Timer(parent)
    

Where parent is the parent window of the timer.

  • METHODS
    • delete()
      Delete the timer.
    • singleshot(boolean)
      Put the timer into single shot mode if boolean is True, otherwise disable timer single shot mode.
    • interval(interval)
      Set timer time interval where interval is in milliseconds.
    • start(**kwargs)
      Start the timer. If **kwargs is specified, then it can contain interval, for specifying timer interval im milliseconds, and singleshot, for specifying a boolean to set the timer's single shot mode.
    • stop()
      This will stop the timer.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This gets called whenever the timer interval has expired. The callback pfstring parameter file string contents are as follows.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the Timer object.

PfTreeview Class

Create a tree view that shows and allows edits of Antelope parameter file information. See http://doc.qt.io/qt-5/qtreeview.html#details and pythonbupf(3y).
  • CONSTRUCTOR
    bqplot.PfTreeview(parent, bupf)
    

Where parent is the parent window of the pf tree view and bupf is a bupf.Pf object (see pythonbupf(3y)) which will get and edit parameter file information. Note that changes in the input parameter file object as a result of editing in this class are notified through the bupf object callback which must be independently defined by bupf.Pf.registercallback (see pythonbupf(3y)).

  • METHODS
    • delete()
      Delete the pftreeview.
    • show()
      Show the pftreeview.
    • hide()
      Hide the pftreeview.
    • update()
      Update the pftreeview.
    • getgeometry()
      Return the pftreeview geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • geometry(w, h, fixed=0)
      Set the geometry of the pftreeview to w pixels width, h pixels height and cause the size to be fixed if fixed is non-zero.
    • geometry(x, y, w, h, fixed=0)
      Set the geometry of the pftreeview to w pixels width, h pixels height, at position x y pixels and cause the size to be fixed if fixed is non-zero.
    • totop()
      Bring the pftreeview to the top of the display stack.
    • tobottom()
      Send the pftreeview to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the pftreeview to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the pftreeview to w pixels.
    • maximumheight(h)
      Set the maximum height of the pftreeview to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the pftreeview to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the pftreeview to w pixels.
    • minimumheight(h)
      Set the minimum height of the pftreeview to h pixels.
    • expandall()
      Expand all of the tree view nodes.
    • collapseall()
      Collapse all of the tree view nodes.
    • redraw()
      Re-render and redraw the entire tree view.
    • (checkOk, types_tuple) = checkvalue(index, value)
      This method is used to check a potential change in a parameter file value. The value to check is value for the bupf object at index. If value passes the consistency checks, then the returned checkOk will be true. If value does not pass the consistency checks, then checkOk will be false. The types_tuple return is a tuple with types for each of the value fields. Each of the types will be one of string, int, float, color, font, or regex.
    • configure(*args, **kwargs)
      This will cause PfTreeview configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For PfTreeview objects the configuration keys and appropriate values are as follows.
      • allow_value_edits allow_value_edits
        Specifies whether or not the values can be edited. Specified by a Boolean. This defaults to "yes".
      • show_keys show_keys
        Specifies whether or not the the parameter file keys should be displayed. Specified by a Boolean. This defaults to "yes".
      • show_values show_values
        Specifies whether or not the the parameter file values should be displayed. Specified by a Boolean. This defaults to "yes".
      • show_comments show_comments
        Specifies whether or not the the parameter file in-line comments should be displayed. Specified by a Boolean. This defaults to "yes".
      • show_constraints show_constraints
        Specifies whether or not the constraints should be displayed. Specified by a Boolean. This defaults to "no".
      • show_sources show_sources
        Specifies whether or not the corresponding source file information should be displayed. Specified by a Boolean. This defaults to "no".
      • show_noninline_comments show_noninline_constraints
        Specifies whether or not the non-inline comments should be displayed. Specified by a Boolean. This defaults to "no".
      • font font
        Specifies a font to use for displaying the strings. 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. System default for <family> is used as the system default fixed font.
      • font_size font_size
        This is a convenience option that can be used to set the font sizes without specifying the entire font.
      • color_key color_key
        Specifies a color to use for the key text. This defaults to "black".
      • color_key_arr color_key_arr
        Specifies a color to use for the key text when the key is an &Arr. This defaults to "blue".
      • color_key_tbl color_key_tbl
        Specifies a color to use for the key text when the key is a &Tbl. This defaults to "blue".

PfTreeview Class EXAMPLE


#!/usr/bin/env bqpy

import os
import sys
import time
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *
from antelope.bupf import *
from antelope.pfsubs import *

class MyPfTreeview(PfTreeview):
    def __init__ (self, parent, bupf):
        super (MyPfTreeview, self).__init__ (parent, bupf)
        bupf.registercallback (lambda pfstring, s=self: s.pf_callback (pfstring))

    def pf_callback (self, pfstring):
        argsd = PfSubs.pfstring2py (pfstring)
        index = int(argsd['index'])
        value_from = argsd['value_from']
        value_to = argsd['value_to']
        (checkok, types) = self.checkvalue(index,value_to)
        if not checkok:
            print ('costraints exception for', value_to)
            return value_from

argc = len(sys.argv)
if argc != 1 and argc != 2:
    print ("usage:bqpy_test_pftreeview [pfname]")
    sys.exit(1)

if argc == 1:
    pfname = "display_spec"
else:
    pfname = sys.argv[1]

ge = GraphicsEngine()

mainwindow = MainWindow(ge)
layout = GridLayout (mainwindow.getframe())

bupf = Pf (pfname)

pftv = MyPfTreeview (mainwindow, bupf)
pftv.configure ( \
    show_constraints = 'yes', \
)
layout.addwidget (pftv, 0, 0, 1, 1)

mainwindow.geometry(800, 400)
mainwindow.show ()

ge.qtmainloop ()
ge.pymainloop ()

CommandConsole Class

Create a command console that allows user of typed commands and shows simple printed output. See http://doc.qt.io/qt-5/qtextedit.html#details and BQCommandConsole(3).

CommandConsole widgets provide the capability for user typed commands. As well these widgets will accept commands from programmatic sources. A command history is kept internally. The user can scroll through the command history either using a normal scroll bar or by pressing the up and down arrow keys on the keyboard which will fill in the current command from the command history. A current command can be edited with normal mouse interactions and the command is executed when the Return key is pressed.

  • CONSTRUCTOR
    bqplot.CommandConsole(parent)
    

Where parent is the parent window of the command console. The parent window should be either a MainWindow object or a Frame object.

  • METHODS
    • delete()
      Delete the tableview.
    • show()
      Show the tableview.
    • hide()
      Hide the tableview.
    • update()
      Update the tableview.
    • getgeometry()
      Return the tableview geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • geometry(w, h, fixed=0)
      Set the geometry of the tableview to w pixels width, h pixels height and cause the size to be fixed if fixed is non-zero.
    • geometry(x, y, w, h, fixed=0)
      Set the geometry of the tableview to w pixels width, h pixels height, at position x y pixels and cause the size to be fixed if fixed is non-zero.
    • totop()
      Bring the tableview to the top of the display stack.
    • tobottom()
      Send the tableview to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the tableview to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the tableview to w pixels.
    • maximumheight(h)
      Set the maximum height of the tableview to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the tableview to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the tableview to w pixels.
    • minimumheight(h)
      Set the minimum height of the tableview to h pixels.
    • sendcommand(command, echocommand=1, echooutput=1)
      This will cause a command string, command, to be sent to the command console as if it was typed by a user. If echocommand is set, then the command string will be echoed in the command console window as it would if the user had typed the command. If echooutput is set, then any output produced by the command will also be echoed in the command console window.
    • printlineoutput(line, error_output_flag, output_done_flag)
      This will cause a line of output, specified by line, to be printed in the command console window. If error_output_flag is set, then the output is printed using the error color defined below. If output_done_flag is set, then this signals that there will be no further output so that the output is printed and is followed by the prompt character waiting for user input.
    • importfromfile(fname, echocommands=1)
      This will read commands from the file fname, one command per line, and execute them as if they were typed by a user. If echocommands is set, then the commands will be echoed in the command console window.
    • getcommand(fcommand_index)
      This will return a command from the internal command history queue corresponding to the command_index index into the queue going backwards in time, where 0 is the most recent command.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This gets called whenever a command is executed. When a command is being entered manually, execution happens when the Return key is pressed. The callback pfstring parameter file string contents are as follows.
      • client_string
        This is the client_string specified in registercallback.
      • command
        This is the string command that was executed.
  • configure(*args, **kwargs)
    This will cause CommandConsole configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For CommandConsole objects the configuration keys and appropriate values are as follows.
    • font textFont
      Specifies a font to use for displaying the command and output text strings. 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 "courier,14".
    • color_foreground textColor
      Specifies a color to use for drawing the command text. Can be specified in any of the forms documented in BQ_ParseColor(3). This defaults to "blue".
    • color_foreground_selection textSelectionColor
      Specifies a color to use for drawing the command text characters when they are selected. Can be specified in any of the forms documented in BQ_ParseColor(3). This defaults to "lightyellow".
    • color_background backgroundColor
      Specifies a color to use for filling the command text background. Can be specified in any of the forms documented in BQ_ParseColor(3). This defaults to "lightyellow".
    • color_background_selection backgroundSelectionColor
      Specifies a color to use for filling the command text background characters when they are selected. Can be specified in any of the forms documented in BQ_ParseColor(3). This defaults to "blue".
    • 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 "".
    • color_output outputColor
      Specifies a color to use for drawing the output text. Can be specified in any of the forms documented in BQ_ParseColor(3). This defaults to "black".
    • color_erroroutput erroroutputColor
      Specifies a color to use for drawing the error output text. Can be specified in any of the forms documented in BQ_ParseColor(3). This defaults to "red".
    • color_prompt promptColor
      Specifies a color to use for drawing the prompt characters. Can be specified in any of the forms documented in BQ_ParseColor(3). This defaults to "orange".
    • prompt promptString
      Specifies a string to use for drawing the prompt. This defaults to ">".

CommandConsole class EXAMPLE



#!/usr/bin/env bqpy

import os
import sys
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *

def mycallback (cc, pfstring):
    argsd = PfSubs.pfstring2py (pfstring)
    syscommand = "(%s >test.stdout) >&test.stderr" % argsd['command']
    os.system (syscommand)
    stdout = open("test.stdout")
    stderr = open("test.stderr")
    for line in stdout:
        cc.printlineoutput (line, 0, 0)
    stdout.close()
    os.system ("rm -f test.stdout");
    for line in stderr:
        cc.printlineoutput (line, 1, 0)
    stderr.close()
    os.system ("rm -f test.stderr");
    cc.printlineoutput ('', 0, 1)

ge = GraphicsEngine()

mw = MainWindow (ge)
mw.title ('CommandConsole' )

layout = GridLayout (mw.getframe())

cc = CommandConsole (mw)
layout.addwidget (cc, 0, 0, 1, 1)

cc.registercallback (lambda pfstring, c=cc: mycallback (c, pfstring))

mw.geometry(500, 200, 0)
mw.show ()

ge.qtmainloop()
ge.pymainloop()

Tableview Class

Create a table view that shows arbitrary data in a table format. See http://doc.qt.io/qt-5/qtableview.html#details and BQTableview(3).

This class behaves mainly like the QTableView class with a few exceptions.

  • Sorting by clicking on the headers has three states instead of two. The first click produces ascending sort order. The second click produces descending sort order. The third click produces original sort order. Custom sorting can be done at the application level individually on each column.
  • There is a concept of record number, referring to the the row to data relationship as originally produced without sorts. These record numbers can be displayed automatically in the table and are not ambiguated by sorts. As well, sorts can be done on the record numbers.
  • There is internal support for making display changes as the mouse hovers above table cells without button clicks or drags.
  • A callback mechanism is defined to provide a simple API for providing data and display characteristics, such as color and alignment, to the table cells.

Note that this class is meant to replace the deprecated Spreadsheet class.

  • CONSTRUCTOR
    bqplot.Tableview(parent)
    

Where parent is the parent window of the table view. The parent window should be either a MainWindow object or a Frame object.

  • METHODS
    • delete()
      Delete the tableview.
    • show()
      Show the tableview.
    • hide()
      Hide the tableview.
    • update()
      Update the tableview.
    • getgeometry()
      Return the tableview geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • geometry(w, h, fixed=0)
      Set the geometry of the tableview to w pixels width, h pixels height and cause the size to be fixed if fixed is non-zero.
    • geometry(x, y, w, h, fixed=0)
      Set the geometry of the tableview to w pixels width, h pixels height, at position x y pixels and cause the size to be fixed if fixed is non-zero.
    • totop()
      Bring the tableview to the top of the display stack.
    • tobottom()
      Send the tableview to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the tableview to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the tableview to w pixels.
    • maximumheight(h)
      Set the maximum height of the tableview to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the tableview to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the tableview to w pixels.
    • minimumheight(h)
      Set the minimum height of the tableview to h pixels.
    • set_dimensions(nrows, ncolumns)
      This sets the total numbers of rows and columns in the table.
    • set_recordtab(recordtab_tuple)
      This sets the record tab used when sorting is done by the application (see below description of callback syntax). The relationship between sorted and unsorted record numbers is specified by recordtab_tuple which should be a tuple which resolves to type integer.
    • (width, height) = get_totalsize()
      This will return the total size of the table in pixels. The total size refers to the size without scrolling.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This is the means by which all of the table information is obtained by the class. If this callback is not specified, then the table will be empty. Generally, an empty return from this callback indicates no action or a default value. The callback pfstring parameter file string contents are as follows.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the Tableview object.
      • request
        This is a parameter file &Tbl that contains the request information. request[0] is always a request type string as follows.
        • headerdata
          For this request request[1] will contain the column number or row number (depending on whether this is a request for horizontal or vertical header) as a string. The value of request[2] will be either 'horizontal' for the horizontal header, or 'vertical' for the vertical header. The return value should be a string with the horizontal or vertical header name.
        • data
          For this request request[1] will contain the row and column numbers as a single string with the values white space separated. The return value should be a string with the table cell display value.
        • foreground
          For this request request[1] will contain the row and column numbers as a single string with the values white space separated. The return value should be a valid color string specifying the text color.
        • background
          For this request request[1] will contain the row and column numbers as a single string with the values white space separated. The return value should be a valid color string specifying the cell background color.
        • alignment
          For this request request[1] will contain the row and column numbers as a single string with the values white space separated. The return value should be 'w', for a west (left) cell text alignment, 'e', for an east (right) cell text alignment, or 'c' for a center cell text alignment.
        • sort
          For this request request[1] will contain the column number as a string and a string flag in request[2] indicating if the sort should be in ascending order, for string 0, or descending order, for string 1. This request indicates that the horizontal header cell has been clicked to produce a sort on that column. A column value of -1 means that the sorting is in original order. If the application program does not want to implement sorting itself, then this can be considered as a notification requiring no application actions, in which case there should be no return value. If the application program wants to implement sorting itself, then this can be used to trigger the application sorting, in which case the return value should be the string 'disable_sort' to notify the object to disable the default Qt sorting for that column. If an application wants to perform its own custom sorting in this manner, then it should also call the set_recordtab method defined above to establish a sorted to unsorted transformation for displaying disambiguated record numbers.
        • hover
          For this request request[1] will contain the row and column numbers as a single string with the values white space separated. The return value is ignored. This is meant to be a notification for application programs that the mouse is hovering above the table cell.
        • accentuated
          For this request request[1] will contain the row and column numbers as a single string with the values white space separated. The return value should be a string '1', to indicate that the cell should be accentuated, or '0', to indicate the cell should not be accentuated. There are separate colors and backgrounds for accentuated cells as defined in the configuration parameters. Note that only one cell at a time can be accentuated. If a new cell is accentuated, then if there is already another accentuated cell, it will be de-accentuated. The accentuation cell state will be ignored if there is no return value.
        • selection_changed
          For this request request[1] will contain the record number as a string. Only one record at a time can be selected. The return value is ignored. Note that the record number of the original data order is returned as opposed to the sorted row number.
  • configure(*args, **kwargs)
    This will cause Tableview configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Tableview objects the configuration keys and appropriate values are as follows.
    • default_cell_width default_cell_width
      This specifies the default cell width in pixels. If this is -1, then the cell widths are either determined from the column_widths configuration parameter or the widths are set to fit the cell contents. This defaults to -1.
    • column_widths column_widths_pf_string
      This specifies the cell widths in pixels for each column. This should be specified as a parameter file string with a Tbl with the name column_widths. Each entry in the Tbl corresponds to a column in the table view. If the entry value can be parsed as an integer, then that value is used as the width of the column in pixels. Otherwise, the entry is treated as a string and its display font metrics are used to determine a string width which is used to set the column width. Columns with width of -1 pixels are set to fill the contents of the cells. If there are fewer entries than columns, then the remaining columns use the default_cell_width value.
    • show_record_numbers show_record_numbers
      Specifies whether or not the record numbers should be displayed. Specified by a Boolean. When record numbers are shown, they are automatically displayed as integers in the left-most first column, corresponding to the original data row numbers. These record numbers stay consistent through sorts. Also, when record numbers are shown, the column numbers stay consistent with the original data column numbers without the record numbers displayed. This defaults to 'no'.
    • font font
      Specifies a font to use for displaying the cell text strings. Fonts are specified as '<family>[,<size>[,<weight>[,<italic?>]]]', where <family> is a font family name, <size> is a font size in integer pixels, <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. System default for <family> is used as the system default fixed font.
    • font_size font_size
      This is a convenience option that can be used to set the cell text font size without specifying the entire font.
    • font_header font_header
      Specifies a font to use for displaying the cell horizontal header text strings. This font is also used to display record numbers.
    • default_hover_interaction default_hover_interaction
      Specifies whether or not mouse hovers should automatically cause accentuated cell display. Specified by a Boolean. This defaults to 'no'.
    • color_hover color_key
      Specifies a color to use for displaying cell text when accentuated. This defaults to 'black'.
    • color_record_numbers_background color_record_numbers_background
      Specifies a color to use for displaying record number cell backgrounds; This defaults to 'lightgray'.

Tableview Class EXAMPLE

string row number for the 0th column only.


#!/usr/bin/env bqpy

import os
import sys
import time
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *
from antelope.pfsubs import *

class MyTableview(Tableview):
    def __init__ (self, parent, nrows, ncols):
        super (MyTableview, self).__init__ (parent)
        self.registercallback (lambda pfstring, s=self: s.config_callback (pfstring))
        self.nrows = nrows
        self.ncols = ncols
        self.record_tab = []
        for i in range(self.nrows):
            self.record_tab.append(i)
        self.set_dimensions (nrows, ncols)

    def config_callback (self, pfstring):
        argsd = PfSubs.pfstring2py (pfstring)
        if argsd['request'][0] == 'headerdata':
            if argsd['request'][2] == 'horizontal':
                col = int(argsd['request'][1])
                return 'col %d' % col
        if argsd['request'][0] == 'data':
            (row, col) = argsd['request'][1].split()
            row = int(row)
            col = int(col)
            return '%d %d' % (self.record_tab[row], col)
        if argsd['request'][0] == 'foreground':
            (row, col) = argsd['request'][1].split()
            row = int(row)
            col = int(col)
            mod = (row+col)%3
            if mod == 0:
                return
            if mod == 1:
                return "blue"
            if mod == 2:
                return "red"
            return
        if argsd['request'][0] == 'background':
            (row, col) = argsd['request'][1].split()
            row = int(row)
            col = int(col)
            mod = (row+col)%3
            if mod == 0:
                return
            if mod == 1:
                return "pink"
            if mod == 2:
                return "lightblue"
            return
        if argsd['request'][0] == 'sort':
            col = int(argsd['request'][1])
            if col == -1:
                self.record_tab = []
                for i in range(self.nrows):
                    self.record_tab.append(i)
                self.set_recordtab (tuple(self.record_tab))
                return
            if col != 0:
                return
            self.record_tab = []
            if argsd['request'][2] == '1':
                for i in range(self.nrows):
                    self.record_tab.append(self.nrows-i-1)
            else:
                for i in range(self.nrows):
                    self.record_tab.append(i)
            self.set_recordtab (tuple(self.record_tab))
            return 'disable_sort'
        if argsd['request'][0] == 'selection_changed':
            row = int(argsd['request'][1])
            print ('selection ', row)

ge = GraphicsEngine()

mainwindow = MainWindow(ge)
layout = GridLayout (mainwindow.getframe())

tv = MyTableview (mainwindow, 20, 20)
tv.configure ( \
    show_record_numbers = 'yes', \
    default_hover_interaction = 'yes', \
    color_hover = 'magenta', \
    font = 'courier,18,Bold', \
    font_header = 'arial,14,Normal', \
)
layout.addwidget (tv, 0, 0, 1, 1)

(width, height) = tv.get_totalsize()
width += 18
height += 18

mainwindow.geometry(width, height)
mainwindow.show ()

ge.qtmainloop ()
ge.pymainloop ()

DbTableview Class

Create a table view that shows datascope database data in a table format. See http://doc.qt.io/qt-5/qtableview.html#details and BQDbTableview(3).

This class behaves mainly like the QTableView class with a few exceptions.

  • Sorting by clicking on the headers has three states instead of two. The first click produces ascending sort order. The second click produces descending sort order. The third click produces original sort order. Custom sorting can be done on each column by specifying datascope sort fields.
  • There is a concept of record number, referring to the the datascope table or view record number without sorts. These record numbers can be displayed automatically in the table and are not ambiguated by sorts. As well, sorts can be done on the record numbers.
  • There is internal support for making display changes as the mouse hovers above table cells without button clicks or drags.
  • A callback mechanism is defined to provide a simple API for notifications of row/record selections.

Note that this class is meant to replace the deprecated DbSpreadsheet class.

  • CONSTRUCTOR
    bqplot.DbTableview(parent, dbptr)
    

Where parent is the parent window of the table view. The parent window should be either a MainWindow object or a Frame object. The database table or view is specified by dbptr. Currently datascope groups are not supported.

  • METHODS
    • delete()
      Delete the dbtableview.
    • show()
      Show the dbtableview.
    • hide()
      Hide the dbtableview.
    • update()
      Update the dbtableview.
    • getgeometry()
      Return the dbtableview geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • geometry(w, h, fixed=0)
      Set the geometry of the dbtableview to w pixels width, h pixels height and cause the size to be fixed if fixed is non-zero.
    • geometry(x, y, w, h, fixed=0)
      Set the geometry of the dbtableview to w pixels width, h pixels height, at position x y pixels and cause the size to be fixed if fixed is non-zero.
    • totop()
      Bring the dbtableview to the top of the display stack.
    • tobottom()
      Send the dbtableview to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the dbtableview to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the dbtableview to w pixels.
    • maximumheight(h)
      Set the maximum height of the dbtableview to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the dbtableview to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the dbtableview to w pixels.
    • minimumheight(h)
      Set the minimum height of the dbtableview to h pixels.
    • (width, height) = get_totalsize()
      This will return the total size of the table in pixels. The total size refers to the size without scrolling.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This provides the mechanism for actions triggered by selection of a record, returned in record defined below. Note that record corresponds to the original record numbers in the input database table or view.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the DbTableview object.
      • record
        This is the record number selected in the original database table or view.
  • configure(*args, **kwargs)
    This will cause DbTableview configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For DbTableview objects the configuration keys and appropriate values are as follows.
    • column_definitions column_definitions_pf_string
      This specifies column display definitions. This should be specified as a parameter file string with an Arr with the name column_definitions. Each entry in the Arr corresponds to another Arr which is a column definition for displaying cells in the table view. Column definitions have arbitrary names as keys in the top level columns_definitions Arr. Within each column definition are the following key-value pairs.
      • label label
        This is a label string to be used in the column header. If it is not specified, then the label will be set to the column definition name.
      • source source_expression
        This is a datascope expression string that is used to derive the cell text. This must conform to a valid datascope expression for the input table or view (see dbexpressions(5)). Thus must be specified.
      • sort sort_field1[ sort_field2[ ...]
        This is a list of white space separated fields that will be used to sort using this column. Each field must exist in the table or view and will be used to form the fields tbl argument in dbsort(3). If this is not specified, then sorts on this column will use the default Qt string sorting based on the cell text.
      • format format_string
        This is a format specification, ala sprintf(3), for making the cell text. The format string type must match the type returned from the source expression. If this is not specified, then a default string conversion will be done.
      • text_template text_template_string
        This is a template string used to set a fixed width for the column. The font metrics of the string using the current font is used to determine the width in pixels. If this can be parsed as an integer, then that value will be used as the width (see DBTableview(3) column_widths configuration parameter).
      • alignment {w|c|e}
        This determines the cell text horizontal alignment, w for a west (left) alignment, c for a center alignment, or e for an east (right) alignment. If this is not specified then a default alignment will be used.
  • column_names column_names_pf_string
    This specifies the particular columns to be displayed. This should be specified as a parameter file string with a Tbl with the name column_names. Each entry in the Tbl should be a column definition name as defined in column_definitions. The columns will be displayed in the same order as they appear in this table.

DbTableview Class EXAMPLE


#!/usr/bin/env bqpy

import os
import sys
import time
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *
from antelope.datascope import *
from antelope.pfsubs import *

class MyDbTableview(DbTableview):
    def __init__ (self, parent, db):
        super (MyDbTableview, self).__init__ (parent, db)
        self.registercallback (lambda pfstring, s=self: s.selection_callback (pfstring))

    def selection_callback (self, pfstring):
        argsd = PfSubs.pfstring2py (pfstring)
        print (argsd)

ge = GraphicsEngine()

mainwindow = MainWindow(ge)
layout = GridLayout (mainwindow.getframe())

db = dbopen ('/opt/antelope/data/db/demo/demo')
db = db.lookup (table='origin')
dba = db.lookup (table='assoc')
db = db.join (dba)
dba = db.lookup (table='arrival')
db = db.join (dba)

column_names = {
'column_names': [
    'time',
    'lat',
    'lon',
    'depth',
    'ml',
    'sta',
    'phase'
]
}

column_definitions = {
'column_definitions': {
    'time': {
        'label': 'time',
        'text_template': 'XXXXXXXXXXXXXXXXXXXXXX',
        'source': 'epoch2str(time,"%Y%j:%T")',
    },
    'lat': {
        'label': 'lat',
        'text_template': 'XXXXXXXXXX',
        'source': 'lat',
        'sort': 'lat',
        'alignment': 'e',
        'format': '%.3lf',
    },
    'lon': {
        'label': 'lon',
        'text_template': 'XXXXXXXXXX',
        'source': 'lon',
        'sort': 'lon',
        'alignment': 'e',
        'format': '%.3lf',
    },
    'depth': {
        'label': 'depth',
        'text_template': 'XXXXXXXX',
        'source': 'depth',
        'sort': 'depth',
        'alignment': 'e',
        'format': '%.2lf',
    },
    'ml': {
        'label': 'ml',
        'text_template': 'XXXXXXXX',
        'source': 'ml',
        'sort': 'ml',
        'alignment': 'e',
        'format': '%.2lf',
    },
    'sta': {
        'label': 'sta',
        'text_template': 'XXXXXXXX',
        'source': 'sta',
        'sort': 'sta orid iphase',
    },
    'phase': {
        'label': 'phase',
        'text_template': 'XXXXXXXX',
        'source': 'iphase',
    },
}
}

dbtv = MyDbTableview (mainwindow, db)
dbtv.configure ( \
    column_names = PfSubs.py2pfstring(column_names), \
    column_definitions = PfSubs.py2pfstring(column_definitions), \
    show_record_numbers = 'yes', \
    default_hover_interaction = 'no', \
    font = 'courier,18,Normal', \
    font_header = 'arial,14,Normal', \
)
layout.addwidget (dbtv, 0, 0, 1, 1)

(width, height) = dbtv.get_totalsize()
width += 18
height += 18

mainwindow.geometry(width, height)
mainwindow.maximumwidth(width)
mainwindow.show ()

ge.qtmainloop ()
ge.pymainloop ()

EVEventsTableview Class

Create a table view that shows event view information returned from an event view server as described in EV(3). This particular class shows all EVEvent structures as returned by an EVServer. See http://doc.qt.io/qt-5/qtableview.html#details, BQEVEventsTableview(3) and EV(3).

This class behaves mainly like the QTableView class with a few exceptions.

  • Sorting by clicking on the headers has three states instead of two. The first click produces ascending sort order. The second click produces descending sort order. The third click produces original sort order. Custom sorting can be done on each column by specifying EV(3) sort fields as described below.
  • There is a concept of record number, referring to the the original index from the table of EVEvent structures returned through the associated EVClient object without sorts. These record numbers can be displayed automatically in the table and are not ambiguated by sorts. As well, sorts can be done on the record numbers.
  • There is internal support for making display changes as the mouse hovers above table cells without button clicks or drags.
  • A callback mechanism is defined to provide a simple API for notifications of record selections and the associated evid and orid values.

Note that this class is meant to replace the deprecated EVEventsSpreadsheet class.

  • CONSTRUCTOR
    bqplot.EVEventsTableview(parent, evserver)
    

Where parent is the parent window of the table view. The parent window should be either a MainWindow object or a Frame object. The EVServer data source for this object is specified by evserver. The EVClient object used by the this object is created automatically.

  • METHODS
    • delete()
      Delete the
    • show()
      Show the
    • hide()
      Hide the eveventstableview.
    • update()
      Update the eveventstableview.
    • getgeometry()
      Return the eveventstableview geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • geometry(w, h, fixed=0)
      Set the geometry of the eveventstableview to w pixels width, h pixels height and cause the size to be fixed if fixed is non-zero.
    • geometry(x, y, w, h, fixed=0)
      Set the geometry of the eveventstableview to w pixels width, h pixels height, at position x y pixels and cause the size to be fixed if fixed is non-zero.
    • totop()
      Bring the eveventstableview to the top of the display stack.
    • tobottom()
      Send the eveventstableview to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the eveventstableview to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the eveventstableview to w pixels.
    • maximumheight(h)
      Set the maximum height of the eveventstableview to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the eveventstableview to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the eveventstableview to w pixels.
    • minimumheight(h)
      Set the minimum height of the eveventstableview to h pixels.
    • (width, height) = get_totalsize()
      This will return the total size of the table in pixels. The total size refers to the size without scrolling.
    • select_evid(evid, nofeedback=0)
      This will cause the event corresponding to evid to be selected in the display. If nofeedback is set, then the callback, specified by registercallback below, will not be executed due to an internal selection_changed event.
    • show_evid(evid)
      This will cause the display to temporarily show the event corresponding to evid without generating an internal selection_changed event.
    • set_sort_colname(colname, reverse=0)
      This will cause sorting to be done using the column with name colname. If colname is set to rec, then the sorting will be done using the record number. If reverse is set, then the sort is done in reverse order.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This provides the mechanism for actions triggered by selection of a record, returned in record defined below. Note that record corresponds to the original record numbers in the input EVEvent table.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the EVEventsTableview object.
      • record
        This is the record number selected in the original input EVEvent table, independent of the sorting.
      • evid
        This is the evid value corresponding to the record number selected in the original input EVEvent table, independent of the sorting.
      • orid
        This is the orid value corresponding to the record number selected in the original input EVEvent table, independent of the sorting. Note that this will always be the preferred origin for that event.
  • configure(*args, **kwargs)
    This will cause EVEventsTableview configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For EVEventsTableview objects the configuration keys and appropriate values are as follows.
    • column_definitions column_definitions_pf_string
      This specifies column display definitions. This should be specified as a parameter file string with an Arr with the name column_definitions. Each entry in the Arr corresponds to another Arr which is a column definition for displaying cells in the table view. Column definitions have arbitrary names as keys in the top level columns_definitions Arr. Within each column definition are the following key-value pairs.
      • label label
        This is a label string to be used in the column header and is used as the string column name. If it is not specified, then the label will be set to the column definition name.
      • source source_expression
        This is a semicolon delimited list of EV(3) value expressions that are evaluated on each row to determine the cell display values. Each expression can evaluate to a string or to a number. See EV VALUE EXPRESSIONS below for a definition of syntax.
      • sort sort_expression
        This is a semicolon delimited list of EV(3) value expressions that are evaluated on each row to determine the cell values used for sorting. Each expression can evaluate to a string or to a number. See EV EVENTS VALUE EXPRESSIONS below for a definition of syntax. Since the sort involves comparing two rows, the events[%index] part of the expression should be omitted and instead is substituted automatically within the sort function. These expressions should evaluate to a number if numerical based sorting is desired.
      • format format_string
        This is a semicolon delimited list of format specifications, ala sprintf(3), for making the cell text. Each format fragment must correspond to the list of source expressions and each format string type must match the type returned from the source expression list. If this is not specified, then a default string conversion will be done.
      • text_template text_template_string
        This is a template string used to set a fixed width for the column. The font metrics of the string using the current font is used to determine the width in pixels. If this can be parsed as an integer, then that value will be used as the width (see BQTableview(3) column_widths configuration parameter).
      • alignment {w|c|e}
        This determines the cell text horizontal alignment, w for a west (left) alignment, c for a center alignment, or e for an east (right) alignment. If this is not specified then a default alignment will be used.
      • null null_string
        This is a string used to define a null value. This string is compared to the final cell text string after all formatting. If the strings are equal, then the cell text is cleared.
  • column_names column_names_pf_string
    This specifies the particular columns to be displayed. This should be specified as a parameter file string with a Tbl with the name column_names. Each entry in the Tbl should be a column definition name as defined in column_definitions. The columns will be displayed in the same order as they appear in this table.
  • show_err {yes|no}
    If this is yes, then the text string err is displayed for cells that generate valuation errors, otherwise the cell text is blank. The default is no. Cell valuation errors can occur when a particular event has no origins.
  • auto_select_event {mostrecent|lastmodified|no}
    If this is mostrecent, then whenever the EVServer object notifies the associated EVClient of a change of the most recent event, through the client's responseCallback method (see EV(3)), then that event is automatically selected for display, as if the event row in the events table were clicked. If this is lastmodified, then whenever the EVServer object notifies the associated EVClient of a change of the last modified event, through the client's responseCallback method (see EV(3)), then that event is automatically selected for display, as if the event row in the events table were clicked. If this is no, then there is no automatic event selection.

EV EVENTS VALUE EXPRESSIONS

Event View (EV(3)) parameter values can be retrieved using expression strings. An example of an Event View value expression is as follows.

events[0].origins[0].record_origin{lat}

This expression refers to a complete list of events (events), with the single event at the 0th index ([0]), with the single origin at the 0th index of all origins for this event (origins[0]), using the Datascope complete row record for that origin (record_origin) and evaluating the Datascope expression lat for that record ({lat}). This particular expression would return the latitude of that origin as a floating point number.

If the first token in the expression is events, then the expression must be evaluated against a list of EVEvent structures, each structure in the list defining a single event. The index values can be substituted using %index from the tableview callbacks by converting row numbers to index numbers using the various sorting tabs (done automatically). The parameter values for a single event (EVEvent structure) are defined as follows.

  • origins[<index>]
    The list of origins corresponding to the event. This must be accompanied by an index, <index>, to chose the particular origin. The <index> value may be an integer index number, or it may be the keyword pref_origin, in which case the index for the preferred origin for this event will be substituted.
  • norigins
    This is the number of origins for this event.
  • record_event
    The Datascope complete character string record for this event.
  • recno_event
    The row number in the Datascope event table for this event.
  • evid
    The evid attribute for this event
  • prefor
    The prefor attribute for this event
  • lddate_event
    The lddate attribute for this event
  • lddate_view
    The maximum lddate attribute for all of the origins and all joined assoc, arrival, netmag, stamag, mt and detection tables for this event.
  • magnitude
    This is the overall event preferred magnitude.
  • magtype
    This is the overall event preferred magnitude type.
  • pref_origin
    This is the index within the origins list corresponding to the preferred origin for this event.
  • pref_magnitude_origin
    This is the index within the origins list corresponding to the origin with the preferred magnitude for this event.
  • pref_moment_origin
    This is the index within the origins list corresponding to the origin with the preferred moment tensor for this event.

Whenever a single Datascope complete record string is at the end of the expression it can be follow by {<dbexpr>}. When this is done the regular Datascope expression <dbexpr> is evaluated against the record.

EVOriginsTableview Class

Create a table view that shows event view information returned from an event view server as described in EV(3). This particular class shows all EVOrigin structures as returned by an EVServer for a single event. See http://doc.qt.io/qt-5/qtableview.html#details, BQEVOriginsTableview(3) and EV(3).

This class behaves mainly like the QTableView class with a few exceptions.

  • Sorting by clicking on the headers has three states instead of two. The first click produces ascending sort order. The second click produces descending sort order. The third click produces original sort order. Custom sorting can be done on each column by specifying EV(3) sort fields as described below.
  • There is a concept of record number, referring to the the original index from the table of EVOrigin structures for a particular event returned through the associated EVClient object without sorts. These record numbers can be displayed automatically in the table and are not ambiguated by sorts. As well, sorts can be done on the record numbers.
  • There is internal support for making display changes as the mouse hovers above table cells without button clicks or drags.
  • A callback mechanism is defined to provide a simple API for notifications of record selections and the associated evid and orid values.

Note that this class is meant to replace the deprecated EVEventSpreadsheet class.

  • CONSTRUCTOR
    bqplot.EVOriginsTableview(parent, eveventstableview)
    

Where parent is the parent window of the table view. The parent window should be either a MainWindow object or a Frame object. This object is linked with a EVEventsTablevidew object specified by eveventstableview. The EVClient object used by the this object is taken from its EVEventsTableview parent object.

  • METHODS
    • delete()
      Delete the
    • show()
      Show the
    • hide()
      Hide the evoriginstableview.
    • update()
      Update the evoriginstableview.
    • getgeometry()
      Return the evoriginstableview geometry as a tuple with (xglobal, yglobal, x, y, width, height).
    • geometry(w, h, fixed=0)
      Set the geometry of the evoriginstableview to w pixels width, h pixels height and cause the size to be fixed if fixed is non-zero.
    • geometry(x, y, w, h, fixed=0)
      Set the geometry of the evoriginstableview to w pixels width, h pixels height, at position x y pixels and cause the size to be fixed if fixed is non-zero.
    • totop()
      Bring the evoriginstableview to the top of the display stack.
    • tobottom()
      Send the evoriginstableview to the bottom of the display stack.
    • maximumsize(w, h)
      Set the maximum size of the evoriginstableview to w width and h height in pixels.
    • maximumwidth(w)
      Set the maximum width of the evoriginstableview to w pixels.
    • maximumheight(h)
      Set the maximum height of the evoriginstableview to h pixels.
    • minimumsize(w, h)
      Set the minimum size of the evoriginstableview to w width and h height in pixels.
    • minimumwidth(w)
      Set the minimum width of the evoriginstableview to w pixels.
    • minimumheight(h)
      Set the minimum height of the evoriginstableview to h pixels.
    • (width, height) = get_totalsize()
      This will return the total size of the table in pixels. The total size refers to the size without scrolling.
    • select_orid(orid, nofeedback=0)
      This will cause the origin corresponding to orid to be selected in the display. If nofeedback is set, then the callback, specified by registercallback below, will not be executed due to an internal selection_changed event.
    • show_orid(orid)
      This will cause the display to temporarily show the origin corresponding to orid without generating an internal selection_changed event.
    • set_sort_colname(colname, reverse=0)
      This will cause sorting to be done using the column with name colname. If colname is set to rec, then the sorting will be done using the record number. If reverse is set, then the sort is done in reverse order.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See A NOTE ON CALLBACKS above. This provides the mechanism for actions triggered by selection of a record, returned in record defined below. Note that record corresponds to the original record numbers in the input EVEvent table.
      • client_string
        This is the client_string specified in registercallback.
      • handle
        This is the string handle for the EVOriginsTableview object.
      • record
        This is the record number selected in the original input EVEvent table, independent of the sorting.
      • evid
        This is the evid value corresponding to the record number selected in the original input EVEvent table, independent of the sorting.
      • orid
        This is the orid value corresponding to the record number selected in the original input EVOrigin table, independent of the sorting.
  • configure(*args, **kwargs)
    This will cause EVOriginsTableview configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For EVOriginsTableview objects the configuration keys and appropriate values are as follows.
    • column_definitions column_definitions_pf_string
      This specifies column display definitions. This should be specified as a parameter file string with an Arr with the name column_definitions. Each entry in the Arr corresponds to another Arr which is a column definition for displaying cells in the table view. Column definitions have arbitrary names as keys in the top level columns_definitions Arr. Within each column definition are the following key-value pairs.
      • label label
        This is a label string to be used in the column header and is used as the string column name. If it is not specified, then the label will be set to the column definition name.
      • source source_expression
        This is a semicolon delimited list of EV(3) value expressions that are evaluated on each row to determine the cell display values. Each expression can evaluate to a string or to a number. See EV ORIGINS VALUE EXPRESSIONS below for a definition of syntax.
      • sort sort_expression
        This is a semicolon delimited list of EV(3) value expressions that are evaluated on each row to determine the cell values used for sorting. Each expression can evaluate to a string or to a number. See EV EVENTS VALUE EXPRESSIONS below for a definition of syntax. Since the sort involves comparing two rows, the events[%index] part of the expression should be omitted and instead is substituted automatically within the sort function. These expressions should evaluate to a number if numerical based sorting is desired.
      • format format_string
        This is a semicolon delimited list of format specifications, ala sprintf(3), for making the cell text. Each format fragment must correspond to the list of source expressions and each format string type must match the type returned from the source expression list. If this is not specified, then a default string conversion will be done.
      • text_template text_template_string
        This is a template string used to set a fixed width for the column. The font metrics of the string using the current font is used to determine the width in pixels. If this can be parsed as an integer, then that value will be used as the width (see BQTableview(3) column_widths configuration parameter).
      • alignment {w|c|e}
        This determines the cell text horizontal alignment, w for a west (left) alignment, c for a center alignment, or e for an east (right) alignment. If this is not specified then a default alignment will be used.
      • null null_string
        This is a string used to define a null value. This string is compared to the final cell text string after all formatting. If the strings are equal, then the cell text is cleared.
  • column_names column_names_pf_string
    This specifies the particular columns to be displayed. This should be specified as a parameter file string with a Tbl with the name column_names. Each entry in the Tbl should be a column definition name as defined in column_definitions. The columns will be displayed in the same order as they appear in this table.
  • show_err {yes|no}
    If this is yes, then the text string err is displayed for cells that generate valuation errors, otherwise the cell text is blank. The default is no. Cell valuation errors can occur when a particular event has no origins.
  • preferred_origin_foreground preferred_origin_foreground_color
    This is the foreground color of the row in the origins tableview corresponding to the preferred origin. The default is red.

EV ORIGINS VALUE EXPRESSIONS

Event View (EV(3)) parameter values can be retrieved using expression strings. An example of an Event View value expression is as follows.

origins[0].record_origin{lat}

This expression refers to a complete list of origins (origins) for the currently selected event, with the single origin at the 0th index ([0]), using the Datascope complete row record for that origin (record_origin) and evaluating the Datascope expression lat for that record ({lat}). This particular expression would return the latitude of that origin as a floating point number.

If the first token in the expression is origins, then the expression must be evaluated against a list of EVOrigin structures, each structure in the list defining a single origin. The index values can be substituted using %index from the spreadsheet callbacks by converting row numbers to index numbers using the various sorting tabs (done automatically). The parameters values for a single origin (EOrigin structure) are defined as follows.

  • nmagnitudes
    This is the number of magnitudes for this origin.
  • nmoments
    This is the number of moment tensors for this origin.
  • nassociations
    This is the number of arrival associations for this origin.
  • ndetections
    This is the number of detections associated with this origin.
  • record_origin
    The Datascope complete character string record for this origin.
  • recno_origin
    The row number in the Datascope origin table for this origin.
  • record_origerr
    The Datascope complete character string record for the origerr corresponding to this origin.
  • recno_origerr
    The row number in the Datascope origerr table corresponding to this origin.
  • orid
    The orid attribute for this origin.
  • preferred
    This flag is set if the origin is the preferred origin for the event.
  • lddate_origin
    The lddate attribute for this origin.
  • lddate_origin_view
    The maximum lddate attribute for this origin and all of the joined assoc, arrival, netmag, stamag, mt and detection tables for this origin.
  • time
    The time attribute for this origin.
  • magnitude
    This is the overall origin preferred magnitude.
  • magtype
    This is the overall origin preferred magnitude type.

Whenever a single Datascope complete record string is at the end of the expression it can be follow by {<dbexpr>}. When this is done the regular Datascope expression <dbexpr> is evaluated against the record.

EVEventsTableview and EVOriginsTableview Class EXAMPLE



#!/usr/bin/env bqpy

import os
import sys
import time
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *
from antelope.datascope import *
from antelope.pfsubs import *
from antelope.ev import EVServer

class MyEVEventsTableview(EVEventsTableview):
    def __init__ (self, parent, evserver):
        super (MyEVEventsTableview, self).__init__ (parent, evserver)
        self.registercallback (lambda pfstring, s=self: s.selection_callback (pfstring))

    def selection_callback (self, pfstring):
        argsd = PfSubs.pfstring2py (pfstring)
        print(argsd)

class MyEVOriginsTableview(EVOriginsTableview):
    def __init__ (self, parent, evserver):
        super (MyEVOriginsTableview, self).__init__ (parent, evserver)
        self.registercallback (lambda pfstring, s=self: s.selection_callback (pfstring))

    def selection_callback (self, pfstring):
        argsd = PfSubs.pfstring2py (pfstring)
        print(argsd)

ge = GraphicsEngine()

mainwindow = MainWindow(ge)
toplevel = mainwindow.getframe()
splitter = Splitter (toplevel, "vertical")

layout = GridLayout (toplevel)
layout.addwidget (splitter, 0, 0, 1, 1)

evserver = EVServer ('/opt/antelope/data/db/demo/demo')

column_names = {
 'column_names': [
    'evid',
    'time',
    'magnitude',
    'depth',
    'auth',
    'region'
]
}

column_definitions = {
 'column_definitions': {
    'evid': {
        'label': 'evid',
        'text_template': 'XXXXXXXXX',
        'source': 'events[%index].evid',
        'sort': 'evid',
        'alignment': 'e',
        'format': '%ld'
    },
    'time': {
        'label': 'time',
        'text_template': 'XXXXXXXXXXXXXXXXXXXXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{epoch2str(time,"%Y%j:%T")}',
        'sort': 'origins[pref_origin].time'
    },
    'lat': {
        'label': 'lat',
        'text_template': 'XXXXXXXXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{lat}',
        'sort': 'origins[pref_origin].record_origin{lat}',
        'alignment': 'e',
        'format': '%.3lf'
    },
    'lon': {
        'label': 'lon',
        'text_template': 'XXXXXXXXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{lon}',
        'sort': 'origins[pref_origin].record_origin{lon}',
        'alignment': 'e',
        'format': '%.3lf'
    },
    'depth': {
        'label': 'depth',
        'text_template': 'XXXXXXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{depth}',
        'sort': 'origins[pref_origin].record_origin{depth}',
        'alignment': 'e',
        'format': '%.2lf'
    },
    'region': {
        'label': 'region',
        'text_template': 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{grname(lat,lon)}',
        'sort': 'origins[pref_origin].record_origin{grname(lat,lon)}',
        'alignment': 'w'
    },
    'auth': {
        'label': 'auth',
        'text_template': 'XXXXXXXXXXXXXXXXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{auth}',
        'sort': 'origins[pref_origin].record_origin{auth}',
        'alignment': 'w'
    },
    'magnitude': {
        'label': 'magnitude',
        'text_template': 'XXXXXXXXXX',
        'source': 'events[%index].magnitude;events[%index].magtype',
        'sort': 'magnitude;magtype',
        'alignment': 'e',
        'format': '%4.2f;(%s)',
        'null': '-999.00()'
    }
}
}

evtv = MyEVEventsTableview (mainwindow, evserver)
evtv.configure ( \
    column_names = PfSubs.py2pfstring(column_names), \
    column_definitions = PfSubs.py2pfstring(column_definitions), \
    show_record_numbers = 'yes', \
    default_hover_interaction = 'no', \
    font = 'courier,12,Normal', \
    font_header = 'courier,12,Normal', \
    default_cell_height = 15, \
    auto_select_event = 'mostrecent', \
)
evtv.set_sort_colname ('time', 1)
splitter.addwidget (evtv, 0)

origin_column_definitions = \
"column_definitions &Arr{\n\
    evid &Arr{\n\
        label evid\n\
        text_template XXXXXXXXX\n\
        source origins[%index].record_origin{evid}\n\
        sort record_origin{evid}\n\
        alignment e\n\
        format %ld\n\
    }\n\
    orid &Arr{\n\
        label orid\n\
        text_template XXXXXXXXX\n\
        source origins[%index].orid\n\
        sort orid\n\
        alignment e\n\
        format %ld\n\
    }\n\
    ndef &Arr{\n\
        label ndef\n\
        text_template XXXXXX\n\
        source origins[%index].record_origin{ndef}\n\
        sort record_origin{ndef}\n\
        alignment e\n\
        format %ld\n\
    }\n\
    nass &Arr{\n\
        label nass\n\
        text_template XXXXXX\n\
        source origins[%index].record_origin{nass}\n\
        sort record_origin{nass}\n\
        alignment e\n\
        format %ld\n\
    }\n\
    time &Arr{\n\
        label time\n\
        text_template XXXXXXXXXXXXXXXXXXXXXX\n\
        source origins[%index].record_origin{epoch2str(time,
        sort time\n\
    }\n\
    lat &Arr{\n\
        label lat\n\
        text_template XXXXXXXXXX\n\
        source origins[%index].record_origin{lat}\n\
        sort record_origin{lat}\n\
        alignment e\n\
        format %.3lf\n\
    }\n\
    lon &Arr{\n\
        label lon\n\
        text_template XXXXXXXXXX\n\
        source origins[%index].record_origin{lon}\n\
        sort record_origin{lon}\n\
        alignment e\n\
        format %.3lf\n\
    }\n\
    depth &Arr{\n\
        label depth\n\
        text_template XXXXXXXX\n\
        source origins[%index].record_origin{depth}\n\
        sort record_origin{depth}\n\
        alignment e\n\
        format %.2lf\n\
    }\n\
    region &Arr{\n\
        label region\n\
        text_template XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n\
        source origins[%index].record_origin{grname(lat,lon)}\n\
        sort record_origin{grname(lat,lon)}\n\
        alignment e\n\
    }\n\
    auth &Arr{\n\
        label auth\n\
        text_template XXXXXXXXXXXXXXXXXX\n\
        source origins[%index].record_origin{auth}\n\
        sort record_origin{auth}\n\
        alignment e\n\
    }\n\
    magnitude &Arr{\n\
        label magnitude\n\
        text_template XXXXXXXXXX'\n\
        source origins[%index].magnitude;origins[%index].magtype\n\
        sort magnitude;magtype\n\
        alignment e\n\
        format %4.2f;(%s)\n\
        null -999.00()\n\
    }\n\
}"

origin_column_names = 
"column_names &Tbl{\n\
    evid\n\
    orid\n\
    ndef\n\
    nass\n\
    time\n\
    depth\n\
    magnitude\n\
    auth\n\
    latency\n\
}"

evortv = MyEVOriginsTableview (mainwindow, evtv)
evortv.configure ( \
    column_names = origin_column_names, \
    column_definitions = origin_column_definitions, \
    show_record_numbers = 'yes', \
    default_hover_interaction = 'no', \
    font = 'courier,12,Normal', \
    font_header = 'courier,12,Normal', \
    default_cell_height = 15, \
)
evortv.set_sort_colname ('latency')
splitter.addwidget (evortv, 1)

(width, height) = evtv.get_totalsize()
width += 18
height += 18

mainwindow.geometry(width, height)
mainwindow.maximumwidth(width)
mainwindow.show ()

ge.qtmainloop ()
ge.pymainloop ()

BRTT GRAPHICS EXTENSION CLASSES

The following classes are all special Qt-based graphics extensions that act as replacements for the venerable tcl/tk based buplot libraries used in tcl, perltk and python/tkinter. Although these classes are loosely based on the old buplot concepts, these new classes provide 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.

The viewport concept used in buplot is also used in bqplot. All of the following classes, except for the Viewport objects themselves, must be associated with and are slaved to a Viewport object. The Viewport 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 or hashes of key-value pairs. Viewport slave objects are referred to as "viewport items".

Viewport Class

Viewport objects are necessary adjuncts to any of the other bqplot viewport item 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 Viewport 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.
  • CONSTRUCTOR
    bqplot.Viewport(parent, *args, **kwargs)
    

Where parent is the parent window and must be either a MainWindow object or a Frame object. Configuration parameters can be optionally specified through the *args arguments and the **kwargs key-value pairs. These are specifed as in the configure method described below.

  • METHODS
    • show()
      This will cause the viewport to be shown.
    • hide()
      This will cause the viewport to be hidden.
    • update()
      This will cause the viewport to be updated.
    • delete()
      This will cause the viewport and all of its children items to be deleted.
    • setitemstale()
      This will cause the viewport to be marked as stale which will cause the viewport to be rerendered even if it is in a layer.
    • layer_handle = setlayer(layer_name)
      This will cause the viewport to be rendered into a pixel layer with name layer_name
      . When a Viewport object is assigned to a layer, then the viewport rendering is to the layer pixel map and normal Qt paint events just display the pixel layer. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the setlayervisibility method defined below.
    • setlayervisibility(layer_handle, visibility=1)
      This will cause all of the viewport items that have been assigned to layer with handle layer_handle
      to be not shown, if visibility is set to 0, or shown, if visibility is set to non-zero.
    • (xw, yw) = getwcoords(x, y)
      This will convert x
      , y pixel coordinates into world coordinates returned in xw, yw. If no_map_tran is set (see the configure method below), then the world coordinate transformation will not include map projection transformations.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See
      A NOTE ON CALLBACKS above. This gets called whenever a mouse event occurs in the viewport. Following is an example pfstring.
      
      qevstate initial
      client_string 0
      bqevent &Arr{
          type mousemove
          button none
          modifiers none
          pt &Tbl{
              57.000
              199.000
          }
          gpt &Tbl{
              1515.000
              896.000
          }
          delta 0.000
      }
      
      
      

The callback pfstring parameter file string contents are as follows.

  • client_string
    This is the client_string specified in registercallback.
  • qevstate
    This defines the current Qt event state within the viewport. The states are defined as follows.
    • initial
      This is the initial state where there are not pending pans or zooms.
    • pan
      The viewport is being actively panned using a mouse click drag.
    • zoomin
      The viewport is being actively zoomed in using a mouse click drag.
    • zoomout
      The viewport is being actively zoomed out using a mouse click drag.

  • bqevent
    This is a parameter file Arr that defines all of the mouse related event parameters. The values within the Arr are defined as follows.
    • type
      This is the type of event and in one of the following.
      • mousepress
        A mouse button has been pressed.
      • mouserelease
        A mouse button has been released.
      • mousemove
        The mouse has moved.
      • keypress
        A keyboard key has been pressed.
      • wheel
        The mouse wheel has been turned.
  • button
    This defines which mouse button has been pressed or released.
    • none
      No mouse button is pressed or has been released.
    • left
      The left mouse button is pressed or has been released.
    • middle
      The middle mouse button is pressed or has been released.
    • right
      The right mouse button is pressed or has been released.
  • modifiers
    This defines what keyboard modifiers are pressed during a mouse event.
    • none
      No modifiers.
    • shift
      The keyboard SHIFT key is pressed
    • control
      The keyboard CONTROL key is pressed
  • pt
    This is a parameter file Tbl that contains the x and y pixel position of the mouse relative to the viewport frame.
  • gpt
    This is a parameter file Tbl that contains the x and y global pixel position of the mouse relative.
  • delta
    This is the mouse wheel movement during wheel events.
  • configure(*args, **kwargs)
    This will cause Viewport configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Viewport objects the configuration keys and appropriate values are as follows.
    • 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".
    • latl latitudeLight
      This specifies a latitude in degrees for use when maps are shaded and represents the latitude of the light. This defaults to "0.0".
    • lonl longitudeLight
      This specifies a longitude in degrees for use when maps are shaded and represents the longitude of the light. 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".
    • opacity opacity
      This is an opacity applied to the viewport background rendering. A value of 1 mkes the backgrounds fully opaque and a value of 0 mkes the backgrounds fully translucent.
    • 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 Viewport object will intercept mouse and keyboard events to implement basic viewport scaling interaction as described below. If this is set to no, then the Viewport object will not process mouse and keyboard events. This defaults to "yes".
  • DEFAULT EVENT INTERACTION
    Viewport 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.

Axes Class

Axes objects are viewport items used to display plot axes annotations including the axes themselves plus tic marks, text labels for the axes, units labels along the axes and plot grid lines.
  • CONSTRUCTOR
    bqplot.Axes(viewport, *args, **kwargs)
    

Where viewport is the Viewport master object. Configuration parameters can be optionally specified through the *args arguments and the **kwargs key-value pairs. These are specifed as in the configure method described below.

  • METHODS
    • itemshow()
      This will cause the Axes viewport item to be shown.
    • itemhide()
      This will cause the Axes viewport item to be hidden.
    • update()
      This will cause the Axes viewport item to be updated.
    • setitemstale()
      This will cause the viewport to be marked as stale which will cause the viewport to be rerendered even if it is in a layer.
    • layer_handle = setlayer(layer_name)
      This will cause the
      Axes viewport item to be rendered into a pixel layer with name layer_name. When a viewport item object is assigned to a layer, then the item rendering is to the layer pixmap and normal Qt paint events just display the layer pixmap. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the associated Viewport master setlayervisibility method.
    • viewport = getviewport()
      This will return the
      Viewport master for this Axes viewport item.
    • configure(*args, **kwargs)
      This will cause
      Axes configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Axes objects the configuration keys and appropriate values are as follows.
      • color_labels labelColor
        Specifies a color to use for drawing the label fonts. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . These are the text labels for the axes. This defaults to "black".
      • color_numbers numberColor
        Specifies a color to use for drawing the tic number fonts. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . These are the tic mark numerical text labels for the axes. This defaults to "black".
      • color_axes axesColor
        Specifies a color to use for drawing the axes and tic mark lines. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . This defaults to "black".
      • color_time_axis timeAxisColor
        Specifies a color to use for drawing the axis and tic mark lines for a time axis. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . This defaults to "black".
      • color_grids gridsColor
        Specifies a color to use for drawing the major grid lines, both X and Y. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . This defaults to "gray".
      • color_grids_small gridsSmallColor
        Specifies a color to use for drawing the minor grid lines, both X and Y. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . This defaults to NULL.
      • color_grids_x gridsXColor
        Specifies a color to use for drawing the X major grid lines only. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . This defaults to "gray".
      • color_grids_x_small gridsXSmallColor
        Specifies a color to use for drawing the X minor grid lines only Can be specified in any of the forms documented in BQ_ParseColor(3)
        . This defaults to "lightgray".
      • color_grids_y gridsYColor
        Specifies a color to use for drawing the Y major grid lines only. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . This defaults to "gray".
      • color_grids_y_small gridsYSmallColor
        Specifies a color to use for drawing the Y minor minor grid lines only Can be specified in any of the forms documented in BQ_ParseColor(3)
        . This defaults to "lightgray".
      • font_labels labelFont
        Specifies a font to use for displaying the label strings. 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 16".
      • font_numbers numberFont
        Specifies a font to use for displaying the numerical strings. 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".
      • font_numbers_superscripts superscriptFont
        Specifies a font to use for displaying the exponent numerical strings used in the display of logarithmic axis labels. 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 8".
      • linewidth_box boxLinewidth
        Specifies the line width in integer pixels for the axes box. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_time_axis timeAxisLinewidth
        Specifies the line width in integer pixels for the time scale axis. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_tics TicsLinewidth
        Specifies the line width for the X and Y axis large increment tic lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_tics_small TicsSmallLinewidth
        Specifies the line width for the X and Y axis small increment tic lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_tics_x TicsXLinewidth
        Specifies the line width for the X-axis large increment tic lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_tics_x_small TicsXSmallLinewidth
        Specifies the line width for the X axis small increment tic lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_tics_y TicsYLinewidth
        Specifies the line width for the Y-axis large increment tic lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_tics_y_small TicsYSmallLinewidth
        Specifies the line width for the Y axis small increment tic lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_grids GridsLinewidth
        Specifies the line width for the X and Y axis major plot grid lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_grids_small GridsSmallLinewidth
        Specifies the line width for the X and Y axis minor plot grid lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "-1".
      • linewidth_grids_x GridsXLinewidth
        Specifies the line width for the X axis major plot grid lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_grids_x_small GridsXSmallLinewidth
        Specifies the line width for the X axis minor plot grid lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "-1".
      • linewidth_grids_y GridsYLinewidth
        Specifies the line width for the Y axis major plot grid lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "1".
      • linewidth_grids_y_small GridsYSmallLinewidth
        Specifies the line width for the Y axis minor plot grid lines in integer pixels. A value of "-1"
        means the line will not be drawn. This defaults to "-1".
      • length_tics ticLength
        Specifies the length for the X and Y axis large increment tic lines in integer pixels. This defaults to "10"
        .
      • length_tics_small ticSmallLength
        Specifies the length for the X and Y axis small increment tic lines in integer pixels. This defaults to "5"
        .
      • length_tics_x ticXLength
        Specifies the length for the X axis large increment tic lines in integer pixels. This defaults to "10"
        .
      • length_tics_x_small ticXSmallLength
        Specifies the length for the X axis small increment tic lines in integer pixels. This defaults to "5"
        .
      • length_tics_y ticYLength
        Specifies the length for the Y axis large increment tic lines in integer pixels. This defaults to "10"
        .
      • length_tics_y_small ticYSmallLength
        Specifies the length for the Y axis small increment tic lines in integer pixels. This defaults to "5"
        .
      • xvisible_tics {0|1}
        Specifies if the X-axis tic marks are visible, "1"
        , or invisible, "0". This defaults to "1".
      • yvisible_tics {0|1}
        Specifies if the Y-axis axis tic marks are visible, "1"
        , or invisible, "0". This defaults to "1".
      • xvisible_grids {0|1}
        Specifies if the X-axis grid lines are visible, "1"
        , or invisible, "0". This defaults to "1".
      • yvisible_grids {0|1}
        Specifies if the Y-axis grid lines marks are visible, "1"
        , or invisible, "0". This defaults to "1".
      • xincrement incrementXtic
        Specifies an increment for the major tic marks on the X-axis in world coordinate units. If this is set to "0.0"
        , then the major X-axis tic increments are determined automatically. This defaults to "0.0".
      • xincrement_small smallincrementXtic
        Specifies an increment for the minor tic marks on the X-axis in world coordinate units. If this is set to "0.0"
        , then the minor X-axis tic increments are determined automatically. This defaults to "0.0".
      • yincrement incrementYtic
        Specifies an increment for the major tic marks on the Y-axis in world coordinate units. If this is set to "0.0"
        , then the major Y-axis tic increments are determined automatically. This defaults to "0.0".
      • yincrement_small smallincrementYtic
        Specifies an increment for the minor tic marks on the Y-axis in world coordinate units. If this is set to "0.0"
        , then the minor Y-axis tic increments are determined automatically. This defaults to "0.0".
      • mindx minimumXtic
        This is a minimum size hint for the X-axis major tic mark increment. It is used to limit how small major tic intervals can be when the xincrement
        option is set to "0.0". This is specified in units of pixels. This defaults to "200".
      • mindy minimumYtic
        This is a minimum size hint for the Y-axis major tic mark increment. It is used to limit how small major tic intervals can be when the yincrement
        option is set to "0.0". This is specified in units of pixels. This defaults to "100".
      • xlabel labelXaxis
        Specifies a label string that is displayed under the X-axis. This defaults to ""
        .
      • ylabel labelYaxis
        Specifies a label string that is displayed to the left of the Y-axis. Note that the Y-axis label is rotated 90 degrees counter clockwise. This defaults to ""
        .
      • xformat formatXaxis
        This specifies a normal printf(3C)
        -style format string that determines how the X-axis numerical tic labels are displayed. If this is "auto", then the format is determined automatically. If this is "none", then no X-axis numerical labeling will be done. If this is "time", then X-axis numerical labeling will be done assuming the X axis is an absolute time axis and the labels will be similar to those in dbpick(1) and orbrtd(1). Note that the "time" format disables the normal X-axis tic generation and instead draws optional grid time lines. If the grid time lines are drawn using this format option, then they should not be drawn for the X-axis using the BQGrid(3) object (this can be done with the X-axis only by using the visibile_x and visibile_xsmall options). This defaults to "auto".
      • yformat formatYaxis
        This specifies a normal printf(3C)
        -style format string that determines how the Y-axis numerical tic labels are displayed. If this is "auto", then the format is determined automatically. If this is "none", then no Y-axis numerical labeling will be done. This defaults to "auto".
      • time_format timeFormat
        Specifies a format string for labeling the X-axis time values. This is only used when xformat
        is set to "time". This string is in the style of the time format specifications used by epoch2str(3). If this string is set to "", then a time label is not displayed. This defaults to "%T".
      • date_format dateFormat
        Specifies a format string for labeling the X-axis date values. This is only used when xformat
        is set to "time". This string is in the style of the time format specifications used by epoch2str(3). If this string is set to "", then a date label is not displayed. This defaults to "%G".
      • axis_style axisStyle
        This specifies on which sides of the viewport window the axis lines are to be drawn, with n
        for north (top), s for south (bottom), e, for east (right), and w, for west (left). The characters for each desired side are concatenated together in the string. This defaults to "nsew".
      • tic_style ticStyle
        This specifies where and how tic marks will be drawn. Each entry consists of two characters with the first character specifying the viewport window side for drawing the tic marks, the same as the n
        , s, e, w characters in the axis_style argument, and the second character specifying one of i, to draw the tic marks inside of the viewport window, o, to draw the tic marks outside of the viewport window, or c, to center the tic marks on the sides of the viewport window. The characters for each desired side are concatenated together in the string. This defaults to "nisieiwi".

Text Class

Text objects are viewport items used to display general text string annotations using world coordinate positioning. It also allows text to be rotated.
  • CONSTRUCTOR
    bqplot.Text(viewport, text, x, y, *args, **kwargs)
    

Where viewport is the Viewport master object, text 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. Configuration parameters can be optionally specified through the *args arguments and the **kwargs key-value pairs. These are specifed as in the configure method described below.

  • METHODS
    • itemshow()
      This will cause the
      Text viewport item to be shown.
    • itemhide()
      This will cause the
      Text viewport item to be hidden.
    • update()
      This will cause the
      Text viewport item to be updated.
    • setitemstale()
      This will cause the viewport to be marked as stale which will cause the viewport to be rerendered even if it is in a layer.
    • layer_handle = setlayer(layer_name)
      This will cause the
      Text viewport item to be rendered into a pixel layer with name layer_name. When a viewport item object is assigned to a layer, then the item rendering is to the layer pixmap and normal Qt paint events just display the layer pixmap. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the associated Viewport master setlayervisibility method.
    • viewport = getviewport()
      This will return the
      Viewport master for this Text viewport item.
    • configure(*args, **kwargs)
      This will cause
      Text configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Text objects the configuration keys and appropriate values are as follows.
      • 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".
      • 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".

Textpopup Class

Textpopup objects are viewport items used to display general text popup dialog boxes. A text popup window will either occupy the lower left hand corner of the viewport frame, or it will be displayed as a top-level popup window at a specified position usually close the the mouse cursor. In this way it can be used as a help balloon dialog utility.
  • CONSTRUCTOR
    bqplot.Textpopup(viewport, *args, **kwargs)
    

Where viewport is the Viewport master object. Configuration parameters can be optionally specified through the *args arguments and the **kwargs key-value pairs. These are specifed as in the configure method described below.

  • METHODS
    • itemshow()
      This will cause the
      Textpopup viewport item to be shown.
    • itemhide()
      This will cause the
      Textpopup viewport item to be hidden.
    • update()
      This will cause the
      Textpopup viewport item to be updated.
    • setitemstale()
      This will cause the
      Textpopup viewport item to be marked as stale which will cause the Textpopup viewport item to be rerendered even if it is in a layer.
    • layer_handle = setlayer(layer_name)
      This will cause the
      Textpopup viewport item to be rendered into a pixel layer with name layer_name. When a viewport item object is assigned to a layer, then the item rendering is to the layer pixmap and normal Qt paint events just display the layer pixmap. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the associated Viewport master setlayervisibility method.
    • viewport = getviewport()
      This will return the
      Viewport master for this Textpopup viewport item.
    • configure(*args, **kwargs)
      This will cause
      Textpopup configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Textpopup objects the configuration keys and appropriate values are as follows.
      • color_background backgroundColor
        Specifies a color to use for filling the text popup background. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . This defaults to "lightyellow".
      • text textString
        This will set the text popup text. Newlines in the string will cause new lines in the popup.
      • position xPos yPos
        This will set the position of the upper left hand corner of the text popup in screen coordinate pixels. If this is set, then the popup will be a top-level window that will extend outside of the underlying viewport window. If this is not specified, then the popup will be place so that its lower left hand corner is at the lower left hand corner of the viewport window.
      • timeout timeoutValue
        This will set a timeout value in seconds that will cause the text popup to automatically be hidden and deleted. If this is not set ot
        timeout <= 0.0 then the popup will remain displayed indefinitely.
      • justification justificationValue
        This will set a text justification value that is used to anchor the popup. Must be one of 'c'
        , 'nw', 'n', 'ne', 'e', 'se', 's', 'sw', or 'w'.
      • opacity opacity
        This is a floating opacity factor applied to rendering of the text popup. A value of 1.0
        means complete opaque and a value of 0.0 means completely translucent. This defaults to "1.0".

Polyline Class

Polyline objects are Viewport items used to display general polygonal figures with lines and also optionally filled figures.
  • CONSTRUCTOR
    bqplot.Polyline(viewport, *args, **kwargs)
    

Where viewport is the Viewport master object. Configuration parameters can be optionally specified through the *args arguments and the **kwargs key-value pairs. These are specifed as in the configure method described below.

  • METHODS
    • itemshow()
      This will cause the
      Polyline viewport item to be shown.
    • itemhide()
      This will cause the
      Polyline viewport item to be hidden.
    • update()
      This will cause the
      Polyline viewport item to be updated.
    • setitemstale()
      This will cause the
      Polyline viewport item to be marked as stale which will cause the Polyline viewport item to be rerendered even if it is in a layer.
    • layer_handle = setlayer(layer_name)
      This will cause the
      Polyline viewport item to be rendered into a pixel layer with name layer_name. When a viewport item object is assigned to a layer, then the item rendering is to the layer pixmap and normal Qt paint events just display the layer pixmap. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the associated Viewport master setlayervisibility method.
    • viewport = getviewport()
      This will return the
      Viewport master for this Polyline viewport item.
    • configure(*args, **kwargs)
      This will cause
      Polyline configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Polyline objects the configuration keys and appropriate values are as follows.
      • vector vectorHandle[:index]
        This specifies the source of the X-Y coordinate data for making the polyline plot as coming from a buvector(3)
        object. Note that an optional index value can be specified after the vector handle to specify the index of the dependent variable in vector objects that have more than one dependent variable (the index starts at 0). Note that all data must be in world coordinates.
      • trace Dbptr
        This specifies a row from a Datascope Trace database as the source of the data to be plotted. The
        Dbptr should be a Datascope object from a Trace4.0 or Trace4.1 schema database. The Dbptr can point to a table already set to trace with the record set to the record to be displayed, or it can point to a group view of a sorted trace table with the record set to the group to be displayed. When specifying a group view all of the traces corresponding to the group will be displayed.
      • test {on|off}
        If this is set to
        "on", then an internally generated test function is used for the X-Y coordinate data.
      • color_fill fillColor
        Specifies a color to use for filling the closed polygons. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . If this is specified as a NULL string (""), then there will be no polygon filling. This defaults to "".
      • color_outline lineColor
        Specifies a color to use for drawing lines. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . If this is specified as a NULL string (""), then there will be no line plots. This defaults to "black".
      • linewidth lineWidth
        Specifies the line width for the lineplots in pixels. This defaults to "1"
        .

Polypoint Class

Polypoint objects are Viewport items used to display general glyph symbols. This class is meant to provide compatibility with the old buplot polypoint objects.
  • CONSTRUCTOR
    bqplot.Polypoint(viewport, *args, **kwargs)
    

Where viewport is the Viewport master object. Configuration parameters can be optionally specified through the *args arguments and the **kwargs key-value pairs. These are specifed as in the configure method described below.

  • METHODS
    • itemshow()
      This will cause the
      Polypoint viewport item to be shown.
    • itemhide()
      This will cause the
      Polypoint viewport item to be hidden.
    • update()
      This will cause the
      Polypoint viewport item to be updated.
    • setitemstale()
      This will cause the
      Polypoint viewport item to be marked as stale which will cause the Polypoint viewport item to be rerendered even if it is in a layer.
    • layer_handle = setlayer(layer_name)
      This will cause the
      Polypoint viewport item to be rendered into a pixel layer with name layer_name. When a viewport item object is assigned to a layer, then the item rendering is to the layer pixmap and normal Qt paint events just display the layer pixmap. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the associated Viewport master setlayervisibility method.
    • viewport = getviewport()
      This will return the
      Viewport master for this Polypoint viewport item.
    • registercallback(proc, client_string='0')
      Register the callback procedure with this object. See
      A NOTE ON CALLBACKS above. This gets called whenever a mouse event occurs in one of the polypoint glyphs. Following is an example pfstring.
      
      client_string 0
      bqevent &Arr{
          type mousemove
          button left
          modifiers none
          pt &Tbl{
              254.000
              230.000
          }
          gpt &Tbl{
              1234.000
              692.000
          }
          delta 0.000
      }
      bqglyph &Arr{
          state pan
          index 0
      }
      
      
      

The callback pfstring parameter file string contents are as follows.

  • client_string
    This is the client_string specified in registercallback.
  • bqevent
    This is a parameter file Arr that defines all of the mouse related event parameters. The values within the Arr are defined as follows.
    • type
      This is the type of event and in one of the following.
      • mousepress
        A mouse button has been pressed.
      • mouserelease
        A mouse button has been released.
      • mousemove
        The mouse has moved.
      • keypress
        A keyboard key has been pressed.
      • wheel
        The mouse wheel has been turned.
      • enter
        The mouse has moved into a glyph.
      • leave
        The mouse has moved out of a glyph.

  • button
    This defines which mouse button has been pressed or released.
    • none
      No mouse button is pressed or has been released.
    • left
      The left mouse button is pressed or has been released.
    • middle
      The middle mouse button is pressed or has been released.
    • right
      The right mouse button is pressed or has been released.
  • modifiers
    This defines what keyboard modifiers are pressed during a mouse event.
    • none
      No modifiers.
    • shift
      The keyboard SHIFT key is pressed
    • control
      The keyboard CONTROL key is pressed
  • pt
    This is a parameter file Tbl that contains the x and y pixel position of the mouse relative to the viewport frame.
  • gpt
    This is a parameter file Tbl that contains the x and y global pixel position of the mouse relative.
  • delta
    This is the mouse wheel movement during wheel events.
  • bqglyph
    This is a parameter file Arr that defines all of the glyph paramaters. The values within the Arr are defined as follows.
    • index
      This is the polypoint glyph index.
    • state
      This is the state of the glyph interaction and should be one of the following.
      • initial
        This is the initial state where there are no pending pans.
      • pan
        The glyph is being actively panned using a mouse click drag.
  • configure(*args, **kwargs)
    This will cause Polypoint configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Polypoint objects the configuration keys and appropriate values are as follows.
    • vector vectorHandle[:index]
      This specifies the source of the X-Y coordinate data for making the polypoint symbol plots as coming from a buvector(3) object. Note that an optional index value can be specified after the vector handle to specify the index of the dependent variable in vector objects that have more than one dependent variable (the index starts at 0). Note that all data must be in world coordinates. Each of the plot points defined in the input vector object may be configured so that the plot label and plot symbol fill color, outline color and size can be different for each point. This is done by specifying a label field for each of the vector points (see buvector(3)). The label for each plot point can be displayed as a text label if the showlabels option is set to "1". In order to effect changes in symbol attributes, each vector point label attribute must also contain tokens in the form {f=symbolfillColor o=symboloutlineColor sz=symbolSize sy=symbolType}. These tokens can appear with or without a text label. For instance, if a vector point text label is set to "Apt {f=red o=black sz=20 sy=circle}", then that point's plot symbol, a circle, will be filled in red, with a line outline in black, sized to 20 pixels and a text label of "Apt" will also be displayed. Note that the other symbol attributes will be the same for all points and generally it is safest to use fill and/or outline on each symbol the same across the plot points (i.e. don't try to disable filling for certain points and enable it for others). Also, the various symbol control tokens may be omitted in the point labels which causes the default colors and size to be used.
      Token definitions are as follows.
    • sy
      This is the symbol type according to the symbol symbolType defined below. Note that when a beachball symbol is to be displayed, the form of the token must be sy=bb,<mxx>,<myy>,<mzz>,<mxy>,<mxz>,<myz> where <mxx>, <myy>, ... are the XX, YY, ZZ, XY, XZ, YZ components of the moment tensor X=positive East, Y=positive North, Z=positive Up.
    • sz
      This is the symbol size according to the size symbolSize defined below.
    • f
      This is the symbol fill color according to the fill symbolfillColor defined below.
    • o
      This is the symbol outline color according to the outline symboloutlineColor defined below.
  • symbol symbolType
    This specifies a default plot symbol type and must be one of "point", "cross", "x", "triangle", "square", "circle", "star", or "diamond". Note that a beachball cannot be defined as the default plot symbol. This defaults to "point".
  • size symbolSize
    This specifies a default plot symbol size in pixels. This defaults to "5.0".
  • color_fill symbolfillColor
    Specifies a default color to use for filling the plot symbols. Can be specified in any of the forms documented in BQ_ParseColor(3). If this is specified as a NULL string (""), then the plot symbols will not be filled. This defaults to "".
  • color_fill_node nodefillColor
    Specifies a default color to use for filling the beachball node shapes. Can be specified in any of the forms documented in BQ_ParseColor(3). If this is specified as a NULL string (""), then the beachball nodes will not be filled. This defaults to "".
  • color_outline symboloutlineColor
    Specifies a default color to use for drawing the plot symbol outlines. Can be specified in any of the forms documented in BQ_ParseColor(3). If this is specified as a NULL string (""), then there will be no symbol outlines drawn. This defaults to "black".
  • linewidth lineWidth
    Specifies the default line width for the symbol outlines in pixels. A value less than one means don't draw the symbol outlines. This defaults to "1".
  • linewidth_node nodelineWidth
    Specifies the default line width for the beachball node outlines in pixels. A value less than one means don't draw the beachball node outlines. This defaults to "-1".
  • font textFont
    Specifies a default font to use for displaying the label text strings. 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".
  • color_text textColor
    Specifies a color to use for displaying the label text fonts. Can be specified in any of the forms documented in BQ_ParseColor(3). This defaults to "black".
  • showlabels {0|1}
    Specifies if the polypoint label text strings are visible, "1", or invisible, "0". This defaults to "1".
  • opacity opacity
    This is a floating opacity factor applied to rendering of the symbols. A value of 1.0 means complete opaque and a value if 0.0 means completely translucent. This defaults to "1.0".
  • interaction interaction
    This defines the mouse interaction with the symbol glyphs and should be one of "none", for no mouse interaction, "show", for temporarily accentuating the symbol glyphs as the mouse is moved throught the symbols, as described in BQGlyphs(3), or "move", in which the glyph symbol is moved by a mouse press-drag-release sequence.

Viewport, Axes, Polyline and polypoint Class EXAMPLE


#!/usr/bin/env bqpy

import os
import sys
import time
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *
from antelope.pfsubs import *
from antelope.buplot import *

class Mycallback(object):
    instance = -1
    instances = {}

    def __init__ (self, vp, pl, vecpl):
        Mycallback.instance += 1
        Mycallback.instances[Mycallback.instance] = self
        self.vp = vp
        self.pl = pl
        self.vecpl = vecpl

    @classmethod
    def mycallback (self, pfstring):
        argsd = PfSubs.pfstring2py (pfstring)
        instance = int(argsd['client_string'])
        obj = Mycallback.instances[instance]

        if argsd['bqglyph']['state'] == 'pan':
            if argsd['bqevent']['type'] == 'mousemove':
                (x, y) = (float(argsd['bqevent']['pt'][0]), float(argsd['bqevent']['pt'][1]))
                (xw, yw) = obj.vp.getwcoords (x, y)
                index = int(argsd['bqglyph']['index'])
                buvector_put (obj.vecpl, index, xw, yw)
                if index == 0:
                    buvector_put (obj.vecpl, 4, xw, yw)
                obj.pl.configure ("vector", obj.vecpl)
                obj.pl.setitemstale ()

        return 'ok'

ge = GraphicsEngine()

mainwindow = MainWindow(ge)

menubar = Menubar (mainwindow)
file_menu = menubar.addmenu ("&File")
quit_item = file_menu.additem ("&Quit")
quit_item.registercallback ( lambda self: ge.quit() )
file_menu.addseparator ()
page_item = file_menu.additem ("&Page Setup...")
page_item.registercallback ( lambda self: PageDialog(mainwindow.getframe()) )
print_item = file_menu.additem ("&Print...")
print_item.registercallback ( lambda self: PrintDialog(mainwindow, mainwindow, 1) )
view_menu = menubar.addmenu ("&View")

vp = Viewport (mainwindow)
self.assertTrue(vp != None)

vp.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" )

axes = Axes (vp)
self.assertTrue(axes != None)

axes.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" )

text = Text (vp, "My text", "0.5v", "top+10")
self.assertTrue(text != None)

text.configure ( \
    "color_text",   "red", \
    "font",     "Times 14 Bold", \
    "justification","s", \
    "angle",    0 )

polyline = Polyline (vp)
self.assertTrue(polyline != None)

polyline.configure ( \
    "test",     "on", \
    "color_outline","#400000ff", \
    "linewidth",    "3" )

layer1_name = axes.setlayer ("layer1")
text.setlayer ("layer1")
polyline.setlayer ("layer1")

layer1_on_item = view_menu.additem ("&Show layer1")
layer1_on_item.registercallback ( lambda self: vp.setlayervisibility (layer1_name, 1) )
layer1_off_item = view_menu.additem ("&Hide layer1")
layer1_off_item.registercallback ( lambda self: vp.setlayervisibility (layer1_name, 0) )

vecpl = buvector_create ()
buvector_append (vecpl, -1, 0.1, 0.6)
buvector_append (vecpl, -1, 1.9, 0.4)
buvector_append (vecpl, -1, 0.3, 0.9)
buvector_append (vecpl, -1, 0.4, 0.8)
buvector_append (vecpl, -1, 0.1, 0.6)

polyline2 = Polyline (vp)
self.assertTrue(polyline2 != None)

polyline2.configure ( \
    "vector",   vecpl, \
    "color_fill",   "#80ffff00", \
    "color_outline","red", \
    "linewidth",    2 )

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

polypoint = Polypoint (vp)
self.assertTrue(polypoint != None)

mycallback = Mycallback (vp, polyline2, vecpl)
polypoint.registercallback ("Mycallback.mycallback", '%d' % mycallback.instance)

polypoint.configure ( \
    "vector",   vecpp, \
    "symbol",   "triangle",  \
    "color_fill",   "white", \
    "color_outline","green", \
    "font",     "Helvetica 12 Bold", \
    "color_text",   "brown", \
    "linewidth",    2, \
    "size",     50, \
    "interaction",  "move" )

layer2_name = polyline2.setlayer ("layer2")
polypoint.setlayer ("layer2")

layer2_on_item = view_menu.additem ("&Show layer2")
layer2_on_item.registercallback ( lambda self: vp.setlayervisibility (layer2_name, 1) )
layer2_off_item = view_menu.additem ("&Hide layer2")
layer2_off_item.registercallback ( lambda self: vp.setlayervisibility (layer2_name, 0) )

mainwindow.geometry(1000, 1000, 0)
mainwindow.show ()
ge.qtmainloop ()
ge.pymainloop()

Taskbar Class

Taskbar objects are Viewport items used to display simple taskbars consisting of a set of buttons that can change state. The taskbar buttons are not normal Qt PushButtons but are instead implemented as glyphs with minimal decoration painted on top of a Viewport with optional opacity so as not to obscure the images underneath.
  • CONSTRUCTOR
    bqplot.Taskbar(viewport, *args, **kwargs)
    

Where viewport is the Viewport master object. Configuration parameters can be optionally specified through the *args arguments and the **kwargs key-value pairs. These are specifed as in the configure method described below.

  • METHODS
    • itemshow()
      This will cause the Taskbar viewport item to be shown.
    • itemhide()
      This will cause the Taskbar viewport item to be hidden.
    • update()
      This will cause the Taskbar viewport item to be updated.
    • setitemstale()
      This will cause the Taskbar viewport item to be marked as stale which will cause the Taskbar viewport item to be rerendered even if it is in a layer.
    • layer_handle = setlayer(layer_name)
      This will cause the
      Taskbar viewport item to be rendered into a pixel layer with name layer_name. When a viewport item object is assigned to a layer, then the item rendering is to the layer pixmap and normal Qt paint events just display the layer pixmap. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the associated Viewport master setlayervisibility method.
    • viewport = getviewport()
      This will return the
      Viewport master for this Taskbar viewport item.
    • configure(*args, **kwargs)
      This will cause
      Taskbar configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Taskbar objects the configuration keys and appropriate values are as follows.
      • taskbar_background backgroundColor
        Specifies a default color to use for filling taskbar button backgrounds. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . If this is specified as a "" string, then the default backgrounds will not be filled. This defaults to "".
      • taskbar_buttons_definitions taskbarButtonsDefinitionsString
        This item configuration option is used to define the taskbar buttons parameters. The
        taskbarButtonsDefinitionsString is an Antelope parameter file string that contains these parameters. Following is a typical taskbarButtonsDefinitionsString for this option.
        
        buttons_definitions &Arr{
            basemap &Arr{
                height 26
                description base map
                states &Arr{
                    bluemarble &Arr{
                        label            B
                        description      NASA Bluemarble
                        action           configure maplayers_template bluemarble
                        opacity          0.5
                        background_color blue
                        fill_color       yellow
                        order            0
                    }
                    vector &Arr{
                        label            V
                        description      vector shorelines
                        action           configure maplayers_template vector
                        opacity          0.5
                        background_color #fff2e5
                        fill_color       black
                        order            1
                    }
                }
            }
            zoomin &Arr{
                height 26
                label            +
                description      zoom in
                opacity          0.5
                background_color white
                fill_color       black
                bpq_layer        vector
                action &Tbl{
                    mod=shift configure zoom 2.0
                    mod=notshift configure zoom 1.1
                }
            }
            zoomout &Arr{
                height 26
                label            -
                description      zoom out
                opacity          0.5
                background_color white
                fill_color       black
                bpq_layer        vector
                action &Tbl{
                    mod=shift configure zoom 0.5
                    mod=notshift configure zoom 0.9090909090909
                }
            }
         }
        
        
        
      • The parameter file must contain an associate array named buttons_definitions. The buttons_definitions array defines the various taskbar buttons that can be displayed. Each entry in the buttons_definitions array is another associative array with a unique and arbitrary taskbar button name. Taskbar button parameters are defined as follows.
        • states
          If this exists and is an associative array, then it defines a set of button states that all will occupy the same button position in the taskbar. Each entry in the states array must also be associative arrays that define the parameters for each button state. When multiple states are defined, then a left mouse click on the button will cycle through the states. The label, description, action, opacity, background_color and fill_color parameters for each button state are defined below. In addition, the order parameter defines the order of the buttons as they are cycled. Note that when states is specified, then the label, description, action, opacity, background_color and fill_color parameters must be in each button state array.
        • description
          This is a description string that is displayed as a tool tip using a BQTextPopup object. You can define descriptions for each button state as well as for a button ityself when there are multiple states.
        • label
          This is a text label that will be displayed in the button.
        • opacity
          This is a floating point opacity value that is applied to the button rendering relative to the layers underneath it. A value of 1.0 means complete opaque and a value of 0.0 means completely translucent.
        • background_color
          This is the button background color. If this is "", then the background is not filled. If this is "$BACKGROUND", then the default value corresponding to option taskbar_background will be used. Can be specified in any of the forms documented in BQ_ParseColor(3).
        • fill_color
          This is the button text fill color. If this is "", then the text label is not displayed. Can be specified in any of the forms documented in BQ_ParseColor(3).
        • action
          This is a string that defines the action that will be taken when the button is pressed. This can either be a table of actions, in which case each action in the table is performed in the order in which it appears, or a single action. The following whitespace separated fields define the action to be taken. The first field is the action type and currently can only be configure, which means to run the configure method. The following two fields are used to define the configure option name and the option value. An optional mouse modifier field can precede the type field. This optional modifier field should always start with mod=. The string after the mod= prefix defines mouse modifiers that must be present in order for that action to be taken. Currently the only modifiers defined are shift, meaning that the SHIFT key was pressed when the mouse button was pressed, or notshift, meaning the SHIFT key was not pressed when the mouse button was pressed. This provides a means for changing the action parameters based upon modifier keys. Note that typically a Taskbar object is created by another object, for example a Map object. The object that creates the BQTaskbar object will usually arrange for the BQTaskbar object to properly process the calling object's configuration parameters through a call to BUConfigure::setConfigureSpecs (see BUConfigure(3)) using the calling object's parameter structure.
  • taskbar_buttons taskbarButtonsString
    This item configuration option is used to define a specific set of taskbar buttons to be displayed and used. The taskbarButtonsString is an Antelope parameter file string that contains these parameters. Following is a typical taskbarButtonsString for this option.
    
    buttons &Tbl{
        basemap       neb    1.0v-10    1.0v-10    1
        zoomin        neb    -1r        0r
        zoomout       neb    -1r        0r
    }
    
    
  • The parameter file must contain a table named buttons. The first field in each entry in the buttons table must correspond to a name from the buttons_definitions array. Taskbar buttons are created and displayed in the order in this table. The second field is a justification string used to display the button label. The third and fourth fields are the x and y positions of the string button relative to the justification point. See BQText(3) for a description of justification and the x and y parameters. The fifth field is optional and specifies the starting state value, as an index starting at 0, for buttons with multiple states.
  • taskbar_set_state taskbarSetStateString
    This provides a means for the application program to change the current state of a taskbar button. The taskbarSetStateString value should be in the form "<button_name>:<state_name>", where <button_name> is the name of the button to be set and <state_name> is the state name to set it to.

Traceview Class

Traceview objects are Viewport items used to display seismic waveform traces, arrival flags, detections, predicted arrivals, seismic event associations and residuals. As well, Traceview objects support interactive editing of seismic arrivals. This class is meant to provide the same functionality as dbpick(1) but in a Qt-based python class object that can be used in a variety of application scripts. In addition this class provides much advanced functionality when compared to dbpick(1) and will provide a basis for other more advanced display and editing capabilities in the future.

An attempt has been made to make Traceview objects to behave as much like dbpick(1) as is reasonably possible. Most of the trace display interaction has been preserved. Arrival editing interaction has also been preserved as much as reasonably possible. In addition many new capabilities and interactions have been introduced. In particular, the user typein interface from dbpick(1) and the ability to send commands through the typein interface have been preserved and enhanced using the CommandConsole class. Database sources are supported through the use of EV(3) server and class objects. This provides the capability to display and edit dynamically changing data in a completely safe manner.

The underlying BQTraceview class is complex with lots of features and configuration options. Instead of repeating the documentation here, we encourage looking at BQTraceview(3) for more details. This covers all aspects of Traceview objects including display components and layout, individual trace representation, trace expressions, interactions with data sources, graphical user interaction and traceview commands.

  • CONSTRUCTOR
    bqplot.Traceview(viewport, commandconsole=None, make_taskbar_flag=1, vp_taskbar=None
    

Where viewport is the Viewport master for this object. An interactive user typein interface is provided through the commandconsole object to a previously assigned CommandConsole object. A CommandConsole object can be assigned later using the setcommandconsole method defined below. An optional BQTaskbar(3) object, enhanced to support commands through the Taskview command interface defined below, will be created if make_taskbar_flag is specified as non-zero. If make_taskbar_flag is non-zero, then if vp_taskbar is not None, then the taskbar is assigned to that viewport. Otherwise the taskbar is assigned to the viewport viewport.

  • METHODS
    • itemshow()
      This will cause the Traceview viewport item to be shown.
    • itemhide()
      This will cause the Traceview viewport item to be hidden.
    • update()
      This will cause the Traceview viewport item to be updated.
    • setitemstale()
      This will cause the Traceview viewport item to be marked as stale which will cause the Traceview viewport item to be rerendered even if it is in a layer.
    • layer_handle = setlayer(layer_name)
      This will cause the
      Traceview viewport item to be rendered into a pixel layer with name layer_name. When a viewport item object is assigned to a layer, then the item rendering is to the layer pixmap and normal Qt paint events just display the layer pixmap. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the associated Viewport master setlayervisibility method.
    • viewport = getviewport()
      This will return the
      Viewport master for this Traceview viewport item.
    • createtraces(evserver, stachan_accept='.* .*')
      This will create a set of seismic waveform traces from the database being served by
      EVServer object evserver. A new EVCLient object is automatically created (see EV(3)). Only traces that match stachan_accept will be processed. If stachan_accept is empty, then all stations and channels will be processed. The format of stachan_accept is a station expression followed by a whitespace separated channel expression.
    • setcommandconsole(commandconsole)
      This will set the typein command console to commandconsole
      .
    • sendcommand(command, provide_output=0, send_to_commandconsole=1, nofeedback_flagfB=0)
      This causes a
      Traceview command, specified by the string command, to be sent to the object where it is then executed. If provide_output is set, then any string output or error messages generated by the command will be returned. If the flag send_to_commandconsole is set, then the command is echoed through the attached CommandConsole is if it were typed. The nofeedback_flag argument is an advanced argument used to control command feedback.
    • link_eveventstableview(eveventstableview)
      This will cause a
      EVEventsTableview object, eveventstableview, to be linked to the traceview object. When the two objects are linked, then they are internally and automatically synchronized, in both directions, with no need for application program callbacks or any other application program intervention. Synchronization means that when an event or origin is selected in the eveventstableview and its associated EVOriginsTableview spreadsheets, it will be shown in the traceview object display, through automatically generated event show and origin show commands, and when an event or origin is selected within the traceview object by sending event show and origin show commands either by typing in the command console or from some other source (such as task buttons), that event or origin is automatically selected in the linked EVEventsTableview and EVOriginsTableview objects.
    • configure(*args, **kwargs)
      This will cause
      Traceview configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Traceview objects the configuration keys and appropriate values are as follows.
      • traceview_display_parameters pfstring
        This specifies a number of display parameters. The
        pfstring value is a parameter file string of the following form.
        
        traceview_display_parameters &Arr{
          main_display &Arr{    # these are display parameters for the main window
            color_background                     \#000080          #<color> color of the trace window background
            color_foreground                     yellow            #<color> color of the trace window foreground (traces color)
            color_time_grids                     \#80e0e0e0        #<color> color of the time grid lines
            font_trace_label                     courier,16,Normal #<font> font used for trace labels
            color_trace_label                    black             #<color> color used for trace labels
            color_trace_select_background        lightgray         #<color> color used for selected trace label backgrounds
            color_trace_select_order_label       blue              #<color> color used for selected trace labels
            font_trace_amp_label                 courier,12,Normal #<font> font used for trace amplitude labels
            color_trace_amp_label                \#808080          #<color> color used for trace amplitude labels
            font_trace_filter_label              courier,14,Normal #<font> font used for trace filter labels
            color_trace_filter_label             blue              #<color> color used for trace filter labels
            color_coordinates_status             \#d0ffffff        #<color> color used for coordinate status background
            color_origin_status                  pink              #<color> color used for origin status background
            color_preferred_origin_status        lightblue         #<color> color used for preferred origin status background
            linewidth                            1                 #<float> linewidth used for trace plots
            color_detection_outline              0.0,1.0,0.7       #<color> color for detection flag outline
            color_detection_text                 0.0,1.0,0.7       #<color> color for detection flag text
            color_detection_fill                 \#00000000        #<color> color for detection flag fill
            linewidth_detection                  3                 #<float> detection flag linewidth
            color_predicted_arrival_outline      lightblue         #<color> color for predicted arrival flag outline
            color_predicted_arrival_text         lightblue         #<color> color for predicted arrival flag text
            color_predicted_arrival_fill         \#00000000        #<color> color for predicted arrival flag fill
            linewidth_predicted_arrival          3                 #<float> predicted arrival flag linewidth
            color_arrival_normal_outline         \#ffc0c0c0        #<color> color for normal arrival flag outline
            color_arrival_normal_text            \#ffc0c0c0        #<color> color for normal arrival flag text
            color_arrival_normal_fill            red               #<color> color for normal arrival flag fill
            linewidth_arrival_normal             3                 #<float> normal arrival flag linewidth
            color_arrival_defining_outline       \#ffc0c0c0        #<color> color for defining arrival flag outline
            color_arrival_defining_text          \#ffc0c0c0        #<color> color for defining arrival flag text
            color_arrival_defining_fill          blue              #<color> color for defining arrival flag fill
            linewidth_arrival_defining           3                 #<float> defining arrival flag linewidth
            color_arrival_nondefining_outline    \#ffc0c0c0        #<color> color for non-defining arrival flag outline
            color_arrival_nondefining_text       \#ffc0c0c0        #<color> color for non-defining arrival flag text
            color_arrival_nondefining_fill       green             #<color> color for non-defining arrival flag fill
            linewidth_arrival_nondefining        3                 #<float> non-defining arrival flag linewidth
            color_arrival_magnitude_outline      \#ffc0c0c0        #<color> color for magnitude arrival flag outline
            color_arrival_magnitude_text         \#ffc0c0c0        #<color> color for magnitude arrival flag text
            color_arrival_magnitude_fill         300.0,0.9,0.2     #<color> color for magnitude arrival flag fill
            linewidth_arrival_magnitude          3                 #<float> magnitude arrival flag linewidth
            color_arrival_nonassociated_outline  \#ffc0c0c0        #<color> color for non-associated arrival flag outline
            color_arrival_nonassociated_text     black             #<color> color for non-associated arrival flag text
            color_arrival_nonassociated_fill     yellow            #<color> color for non-associated arrival flag fill
            linewidth_arrival_nonassociated      3                 #<float> non-associated arrival flag linewidth
            arrival_select_expr                  .*                #<expr> arrival flag select expression applied to phase
            arrival_reject_expr                                    #<expr> arrival flag reject expression applied to phase
            arrival_status_line &Arr{                              # define status print line
              format %s %s %s arid=%s phase=%s deltim=%s fm=%s auth=%s
              arguments &Tbl{
                epoch2str(time,\"%Y%j:%T\") %s
                sta                           %s
                chan                          %s
                arid                          %ld
                iphase                        %s
                deltim                        %.2f
                fm                            %s
                auth                          %s
              }
            }
          }
          edit_display &Arr{      # these are display parameters for the arrival edit window
            color_background                     \#e0e0e0          #<color> color of the trace window background
            color_foreground                     gray              #<color> color of the trace window foreground (traces color)
            color_time_grids                     \#80000000        #<color> color of the time grid lines
            linewidth                            1                 #<float> linewidth used for trace plots
            color_detection_outline              0.0,1.0,0.7       #<color> color for detection flag outline
            color_detection_text                 0.0,1.0,0.7       #<color> color for detection flag text
            color_detection_fill                 \#00000000        #<color> color for detection flag fill
            color_detection_fill                 \#00000000        #<color> color for detection flag fill
            color_predicted_arrival_outline      pink              #<color> color for predicted arrival flag outline
            color_predicted_arrival_text         pink              #<color> color for predicted arrival flag text
            color_predicted_arrival_fill         \#00000000        #<color> color for predicted arrival flag fill
            linewidth_predicted_arrival          3                 #<float> predicted arrival flag linewidth
            color_arrival_normal_outline         \#ffc0c0c0        #<color> color for normal arrival flag outline
            color_arrival_normal_text            \#ffc0c0c0        #<color> color for normal arrival flag text
            color_arrival_normal_fill            red               #<color> color for normal arrival flag fill
            linewidth_arrival_normal             3                 #<float> normal arrival flag linewidth
            color_arrival_selected_outline       black             #<color> color for selected arrival flag outline
            color_arrival_selected_text          black             #<color> color for selected arrival flag text
            color_arrival_selected_fill          cyan              #<color> color for selected arrival flag fill
            linewidth_arrival_selected           3                 #<float> selected arrival flag linewidth
            color_arrival_edit_outline           red               #<color> color for edited arrival flag outline
            color_arrival_edit_text              red               #<color> color for edited arrival flag text
            color_arrival_edit_fill              lightblue         #<color> color for edited arrival flag fill
            linewidth_arrival_edit               3                 #<float> edited arrival flag linewidth
            color_arrival_defining_outline       \#ffc0c0c0        #<color> color for defining arrival flag outline
            color_arrival_defining_text          \#ffc0c0c0        #<color> color for defining arrival flag text
            color_arrival_defining_fill          blue              #<color> color for defining arrival flag fill
            linewidth_arrival_defining           3                 #<float> defining arrival flag linewidth
            color_arrival_nondefining_outline    \#ffc0c0c0        #<color> color for non-defining arrival flag outline
            color_arrival_nondefining_text       \#ffc0c0c0        #<color> color for non-defining arrival flag text
            color_arrival_nondefining_fill       green             #<color> color for non-defining arrival flag fill
            linewidth_arrival_nondefining        3                 #<float> non-defining arrival flag linewidth
            color_arrival_defining_tag_outline   black             #<color> color for tagged defining arrival flag outline
            color_arrival_defining_tag_text      black             #<color> color for tagged defining arrival flag text
            color_arrival_defining_tag_fill      lightblue         #<color> color for tagged defining arrival flag fill
            linewidth_arrival_defining_tag       3                 #<float> tagged defining arrival flag linewidth
            color_arrival_nondefining_tag_outline black            #<color> color for tagged non-defining arrival flag outline
            color_arrival_nondefining_tag_text    black            #<color> color for tagged non-defining arrival flag text
            color_arrival_nondefining_tag_fill    lightgreen       #<color> color for tagged non-defining arrival flag fill
            linewidth_arrival_nondefining_tag     3                #<float> tagged non-defining arrival flag linewidth
            color_arrival_nonassociated_outline   black            #<color> color for non-associated arrival flag outline
            color_arrival_nonassociated_text      black            #<color> color for non-associated arrival flag text
            color_arrival_nonassociated_fill      yellow           #<color> color for non-associated arrival flag fill
            linewidth_arrival_nonassociated       3                #<float> non-associated arrival flag linewidth
            color_arrival_residual_outline        0.0,1.0,0.7      #<color> color for arrival residual glyph outline
            color_arrival_residual_text           0.0,1.0,0.7      #<color> color for arrival residual glyph text
            linewidth_arrival_residual            5                #<float> arrival residual glyph linewidth
            color_arrival_deltime_fill            \#a0a0ffa0       #<color> color for arrival deltime glyph fill
            arrival_select_expr                   .*               #<expr> arrival flag select expression applied to phase
            arrival_reject_expr                   [Mm].*           #<expr> arrival flag reject expression applied to phase
            arrival_status_line &Arr{                              # define status print line
              format %s %s %s arid=%s phase=%s deltim=%s fm=%s auth=%s
              arguments &Tbl{
                epoch2str(time,\"%Y%j:%T\") %s
                sta                           %s
                chan                          %s
                arid                          %ld
                iphase                        %s
                deltim                        %.2f
                fm                            %s
                auth                          %s
              }
            }
          }
        }
        
        
        
      • The parameter file string must contain an associative array named traceview_display_params. The traceview_display_params array defines display parameters for the normal (main) display window, when the display is not in edit mode, and for the arrival edit display window, when the display is in edit mode. Main display window parameters are defined in an associative array named main_display. Arrival edit display window parameters are defined in an associative array named edit_display. The individual parameters are defined above in the example pfstring value. Note that only parameters that change need to be specified.
      • show_arrivals {yes|no}
        This sets the Traceview object default show arrivals flag. Each individual BQTrace object will use this to show or hide arrival flags when the corresponding BQTrace object configuration value is set to default.
      • show_detections {yes|no}
        This sets the Traceview object default show detections flag. Each individual BQTrace object will use this to show or hide detection glyphs when the corresponding BQTrace object configuration value is set to default.
      • show_predicted_arrivals {yes|no}
        This sets the Traceview object default show predicted arrivals flag. Each individual BQTrace object will use this to show or hide predicted arrival flags when the corresponding BQTrace object configuration value is set to default.
      • show_residuals {yes|no}
        This sets the Traceview object default show residuals flag. Each individual BQTrace object will use this to show or hide residual glyphs when the corresponding BQTrace object configuration value is set to default.
      • trace_label_visible {yes|no}
        This sets the Traceview object trace label visibility. Each individual BQTrace object will use this to show or hide trace labels when the BQTrace object label_visible configuration value is set to default.
      • ampscale_visible {yes|no}
        This sets the Traceview object default trace amplitude scales visibility. Each individual BQTrace object will use this to show or hide trace amplitude scale annotations when the corresponding BQTrace object configuration value is set to default.
      • show_crosshairs {yes|no}
        This will enable or disable the mouse cursor crosshairs in the display.
      • show_coordinates_status {yes|no}
        This will enable or disable the coordinates status text in the display
      • show_arrival_status {yes|no}
        This will enable or disable the arrival status text in the display
      • show_origin_status {yes|no}
        This will enable or disable the selected event and origin status text in the display.
      • use_wheel {yes|no}
        This will enable or disable the use of the mouse wheel (including the track pad).
      • palign {yes|no}
        This will enable or disable the P-alignment of traces and is equivalent to calling setPalign({yes|no}).
      • auto_distance_sort {yes|no}
        This will enable or disable the automatic distance sorting of traces and is equivalent to calling setAutoDistanceSort({yes|no}).
      • preserve_time_scale_on_resize {yes|no}
        When this is set to yes, then the pixels per second time scale is preserved when the display is resized keeping the time at the left of the display unchanged. If this is set to no, then the left and right edge time values are preserved during resizes. Note that the behavior of dbpick(1) corresponds to the no value. This is equivalent to calling setPreserveTimeScaleOnResize({yes|no}).
      • preserve_traces_scale_on_resize {yes|no}
        When this is set to yes, then the pixels per non-dimensional Y-axis trace value scale is preserved when the display is resized keeping the value at the top of the display unchanged. If this is set to no, then the top and bottom edge Y-axis values are preserved during resizes. Note that the behavior of dbpick(1) corresponds to the no value. This is equivalent to calling setPreserveTracesScaleOnResize({yes|no}).
      • max_traces number
        This will set a maximum number of traces, specified by number, to be displayed. If set to < = 0, then there is no maximum number of trace to be displayed. This forces no more than number traces to ever be displayed regardless of other settings.
      • min_pixels_traces npixels
        This will set a minimum vertical pixel size for each trace, specified by npixels, to be displayed. If set to < = 0, then there is no minimum trace vertical pixel size to be displayed. This constrains each trace vertical height to be no less than npixels pixels and is enforced regardless of other settings.
      • ampscale_mode {auto|fixed}
        This sets the Traceview object default trace amplitude scale mode. Each individual BQTrace object will use this as the trace amplitude scale mode when the corresponding BQTrace object configuration value is set to default. A value of auto will cause automatic trace amplitude scaling so that entire range of trace amplitudes within a display time window will be scaled to the trace height. A value of fixed will fix trace amplitude scaling, in which case the BQTrace::setScale method should be called to set the trace amplitude scale factors.
      • units {source|counts}
        This sets the Traceview object default units display mode. Each individual BQTrace object will use this as the trace units display mode when the corresponding BQTrace object configuration value is set to default. A value of source will cause trace units to correspond to the data source units. A value of counts will cause trace units to be digital counts.
      • gain gain_value
        This sets the Traceview object default trace gain value to gain_value. Each individual BQTrace object will use this to set the trace gain value when the corresponding BQTrace object configuration value is set to 0.0. The trace gain is applied to the trace amplitude plot scaling to increase the trace amplitude, when gain_value > 1.0, or to decrease the trace amplitude, when gain_value < 1.0.
      • clip {yes|no}
        This sets the Traceview object default clip flag. Each individual BQTrace object will use this to enable or disable display clipping when the corresponding BQTrace object configuration value is set to default.
      • antialias {yes|no}
        This sets the Traceview object display antialias flag. Each individual BQTrace object will use this to enable or disable display plot antialiasing when the corresponding BQTrace object configuration value is set to default.
      • filter_string filter_string
        This sets the Traceview object default trace filter string. Each individual BQTrace object will use this to set the trace filter string when the corresponding BQTrace object configuration value is set to NULL. The filter_string can be none, meaning no filtering, or any proper filter string as defined in wffil(3), wffilbrtt(3) and wffilave(3).
      • filter_tpad filter_tpad
        This sets the Traceview object default trace filter time pad. Each individual BQTrace object will use this to set the trace filter time pad when the BQTrace object filter_string configuration value is set to NULL. The filter_tpad is a floating time pad in seconds for removing filter transients in the display.
      • predicted_phases predicted_phases
        This is used for determining the predicted arrival times. An example of predicted_phases is P,S. The value of predicted_phases can be any phase list that is recognized by the tttaup(3) routines.
      • default_phase default_phase
        This is the default phase code used whenever a new arrival is added.
      • traceview_buttons_definitions pfstring
        This specifies button definitions for the optional taskbar. The pfstring value is a parameter file string of the following form.
        
        traceview_buttons_definitions &Arr{
          pal &Arr{
            height           20
            description      enable/disable P-arrival alignment
            states &Arr{
              on &Arr{
                label        Pal
                description  enable P-arrival alignment
                action       command display palign on
                opacity      0.5
                background_color #fff2e5
                fill_color   blue
                order        0
              }
              off &Arr{
                label        Pal
                show_not_symbol  yes
                description  disable P-arrival alignment
                action       command display palign off
                opacity      0.5
                background_color #fff2e5
                fill_color   blue
                order        1
              }
            }
          }
          spa &Arr{
            height           20
            description      show/hide predicted arrivals
            states &Arr{
              on &Arr{
                label        Spa
                description  show predicted arrivals
                action       command display show_pred on
                opacity      0.5
                background_color #fff2e5
                fill_color   blue
                order        0
              }
              off &Arr{
                label        Spa
                show_not_symbol  yes
                description  hide predicted arrivals
                action       command display show_pred off
                opacity      0.5
                background_color #fff2e5
                fill_color   blue
                order        1
              }
            }
          }
        
          ...
        
          le &Arr{
            height           20
            description      show last event
            states &Arr{
              on &Arr{
                label        Evl
                description  show last event
                action &Tbl{
                  command display batch on
                  command arrivals tag clear_all
                  command arrivals select clear
                  command event show 10000000
                  command display batch off
                }
                opacity      0.5
                background_color #fff2e5
                fill_color   blue
                order        0
              }
            }
          }
        
          ...
        
        }
        
        
      • The parameter file string must contain an associative array named traceview_buttons_definitions. The contents of the traceview_buttons_definitions array is parsed the same as the BQTaskbar(3) taskbar_buttons_definitions configuration parameter except that the first field in the action parameter may be command, in which case the remaining fields are interpreted as commands sent to the Traceview object (see Traceview COMMANDS below).
      • traceview_buttons pfstring
        This specifies buttons for the optional taskbar. The pfstring value is a parameter file string of the following form.
        
        traceview_buttons &Tbl{
          pal   nwb  0.0v+5  ftop 1 1
          spa   nwb  +1r-1   0r 0 0
          stad  nwb  +1r-1   0r 1 1
          ds    nwb  +1r-1   0r 0 1
          fe    nwb  +1r-1   0r 0 0
          ne    nwb  +1r-1   0r 0 0
          ce    nwb  +1r-1   0r 0 0
          pe    nwb  +1r-1   0r 0 0
          le    nwb  +1r-1   0r 0 0
          cle   nwb  +1r-1   0r 0 0
          fo    nwb  +1r-1   0r 0 0
          no    nwb  +1r-1   0r 0 0
          pref  nwb  +1r-1   0r 0 0
          po    nwb  +1r-1   0r 0 0
          adda  nwb  +1r-1   0r 0 0
        }
        
        
      • The parameter file string must contain an associative array named traceview_buttons. The contents of the traceview_buttons array is parsed the same as the BQTaskbar(3) taskbar_buttons configuration parameter.
      • aliases pfstring
        This specifies command alias definitions. The pfstring value is a parameter file string of the following form.
        
        aliases &Arr{
          ts     display time_start
          tw     display time_window
          cm     traces maximum
          cw     traces zoom
          z      traces zoom
          zs     traces:selected zoom
          ta     arrivals tag associated
          tc     arrivals tag clear_all
          to     arrivals output tagged
          z10    z 10
          fit    traces fit
          f      fit
          stadon   &Tbl{
            traces stad on
            z10
          }
        }
        
        
      • The parameter file string must contain an associative array named aliases. The contents of the aliases array contain alias name keys with the values set to command definitions. Commands issued by sendCommand or typed into the command console can be alias names defined by the key values in the aliases array. The alias name is replaced by the corresponding aliases array value. Any fields after the alias name are appended to the command value in aliases. Aliases are recursively processed so that aliases of aliases are allowed and properly processed. Aliases can be a list of commands by specifying the value as a &Tbl.
      • hotkeys pfstring
        This specifies hot key command alias definitions. A hot key is a key pressed while the mouse cursor is in the main Traceview display. The pfstring value is a parameter file string of the following form.
        
        hotkeys &Arr{
          left         display time_start +%dxw                        # pan time left
          shift-left   display time_zoom 1.25 %xw                      # zoom time out
          right        display time_start -%dxw                        # pan time right
          shift-right  display time_zoom 0.8 %xw                       # zoom time in
          up           traces start -%dyw                              # pan traces up
          shift-up     traces zoom 1.25 %yw                            # zoom traces out
          control-up   traces gain *1.25                               # gain traces up
          down         traces start +%dyw                              # pan traces down
          shift-down   traces zoom 0.8 %yw                             # zoom traces in
          control-down traces gain *0.8                                # gain traces down
          n            traces filter none                              # clear all traces filters
          0            traces filter none                              # clear all traces filters
          1            traces filter TPAD 100.0 BW 0.8 4 3.0 4 \#tele  # set all traces filters to teleseismic
          2            traces filter TPAD 10.0 BW 1.0 4 0.0 0 \#1hp    # set all traces filters to 1hz high pass
          3            traces filter TPAD 10.0 BW 5.0 4 0.0 0 \#5hp    # set all traces filters to 5hz high pass
          shift-a            display configure antialias toggle              # toggle traces antialias flag
          shift-c            display configure clip toggle                   # toggle traces clip flag
          e            arrivals edit_mode toggle                       # toggle arrivals edit mode
          a            arrivals add_mode yes                           # enable arrivals add mode
          f            traces fit                                      # fit traces
          c            arrivals select clear                           # clear arrival selections
          shift-p      arrivals phase P                                # set selected arrivals phase to P
          shift-s      arrivals phase S                                # set selected arrivals phase to S
          shift-d      arrivals tag D                                  # set selected arrivals tag to D
          shift-n      arrivals tag N                                  # set selected arrivals tag to N
        }
        
        
      • The parameter file string must contain an associative array named hotkeys. The contents of the hotkeys array contain hotkeys as associative array keys with the values set to command definitions. A hot key should be a single printable character or of the form [{shift|control|controlshift}-]{up|down|left|right|<key>}, where shift, control and controlshift are modifier keys, up, down, left and right are the corresponding keyboard arrow keys and <key> is a single lower case keyboard key. The values are the commands that will be executed. Variable substitutions are made based upon the mouse position when the key was pressed. The mouse X-position in world coordinates (epoch time) is substituted for the %xw token. The mouse X-position in world coordinates relative to the left edge of the display is substituted for the %dxw token. The mouse Y-position in world coordinates (Y-axis non-dimensional value) is substituted for the %yw token. The mouse Y-position in world coordinates relative to the bottom edge of the display is substituted for the %dyw token.
      • arrivals_menu pfstring
        This specifies popup menus that appear when a key is pressed on an arrival flag and the Traceview object is in edit mode.
        
        arrivals_menus &Arr{
          right &Tbl{                        # right mouse button menu
            &Arr{                            # set phase codes to P
              label   P                      # menu item label
              command arrivals phase P       # traceview command
            }
            &Arr{                            # set phase codes to S
              label   S                      # menu item label
              command arrivals phase S       # traceview command
            }
            &Arr{                            # mark arrivals as deleted
              label   delete                 # menu item label
              command arrivals phase del     # traceview command
            }
            &Arr{                            # tag arrivals as defining
              label   tag as defining        # menu item label
              command arrivals tag D         # traceview command
            }
            &Arr{                            # tag arrivals as non-defining
              label   tag as non-defining    # menu item label
              command arrivals tag N         # traceview command
            }
            &Arr{                            # clear arrivals tags
              label   clear tag              # menu item label
              command arrivals tag clear_all # traceview command
            }
          }
        }
        
        
      • The parameter file string must contain an associative array named arrivals_menus. The contents of the arrivals_menus array may contain three tables, right, corresponding to a mouse right button click popup menu, middle, corresponding to a mouse middle button click popup menu, or left, corresponding to a mouse left button click popup menu. All three menus can be defined. Within each of the right, middle abd left menus are a list of associative arrays each corresponding to a popup menu entry. Within each of these associative arrays are two parameters, label, for the menu item label and command, for the command executed for that item.

Traceview COMMANDS

Traceview objects can be configured through a set of string commands that can be typed in through a command console object, or programmatically using the sendcommand method, or through the taskbar buttons, hotkeys or arrivals menus defined previously. This command interface provides similar functionality to the typein interface for dbpick(1). Note that commands typed into the command console object or programmatic commands that have been routed through the command console object can generate text output that will be shown in the command console.

Simple command aliases can be defined. The aliases are all evaluated against the first word in a command. Arguments after the aliased command are appended to the unaliased command. Alias substitutions are evaluated recursively providing aliases of aliases functionality. Certain tokens in the commands will automatically be substituted by current display values. Substitution tokens are define below.

  • %time_start
    This token will be substituted with the current epoch time at the left edge of the display.
  • %time_end
    This token will be substituted with the current epoch time at the right edge of the display.
  • %time_middle
    This token will be substituted with the current epoch time at the middle of the display.
  • %time_window
    This token will be substituted with the current display time window.

Following is a list of the commands.

  • ?
    Show a help listing of all of the currently recognized commands.
  • help
    Show a help listing of all of the currently recognized commands.
  • echo string
    Echo the string with token substitution.
  • quit
    Call exit which will cause the program to exit.
  • alias name [substitution_string]
    Define a command alias with name name and command substitution string substitution_string. If substitution_string is not specified, then the value of any existing substitution_string for alias name will be output.
  • unalias name
    This will remove any alias of name name.
  • aliases
    This will output the list of all currently defined aliases.
  • hotkey name [substitution_string]
    Define a hotkey command with key name and command substitution string substitution_string. If substitution_string is not specified, then the value of any existing substitution_string for hotkey name will be output. A hot key name should be a single printable character or of the form [{shift|control|controlshift}-]{up|down|left|right}, where shift, control and controlshift are modifier keys and up, down, left and right are the corresponding keyboard arrow keys. The substitution_string is the command that will be executed. Variable substitutions are made based upon the mouse position when the key was pressed. The mouse X-position in world coordinates (epoch time) is substituted for the %xw token. The mouse X-position in world coordinates relative to the left edge of the display is substituted for the %dxw token. The mouse Y-position in world coordinates (Y-axis non-dimensional value) is substituted for the %yw token. The mouse Y-position in world coordinates relative to the bottom edge of the display is substituted for the %dyw token. If substitution_string is not specified, then the value of any existing substitution_string for hotkey name will be output.
  • unhotkey name
    This will remove any hotkey of name name.
  • hotkeys
    This will output the list of all currently defined hotkeys.
  • main import file_name
    This will import commands from file name file_name and is equivalent to calling importCommands.
  • main export file_name
    This will export commands to file name file_name and is equivalent to calling exportCommands.
  • display time_start {time_string|+time_string|-time_string}
    This will cause the main display to scroll in time. For time_string specification, then time_string is a proper Datascope epoch time string which will correspond to the left edge of the display. For +time_string specification, then time_string is an increment in seconds that will shift the display in time that many seconds to the left (increase the time at the left edge of the display). For -time_string specification, then time_string is an increment in seconds that will shift the display in time that many seconds to the right (decrease the time at the left edge of the display).
  • display time_window time_string
    This will cause the main display time window (display increment) to change to time_string seconds. The time at the left edge of the display will remain unchanged.
  • display time_zoom factor [time_anchor]
    This will zoom the time scale in or out according to factor and time_anchor. The amount of zoom is determined by factor which should be a floating number where factor > 1.0 will cause the display to zoom out in time and factor < 1.0 will cause the display to zoom in in time. if time_anchor is specified, then it should be an epoch time string corresponding to a time value that will stay unchanged in its X position after the zoom. If time_anchor is not specified then the time at the left edge of the display will remain unchanged.
  • display palign [{yes|no|toggle}]
    This sets or unsets automatically time aligning traces to the first predicted P-arrival time for the selected event and origin.
  • display show_pred [{yes|no|toggle}]
    This sets or unsets showing predicted arrivals for the selected event and origin.
  • display batch [{yes|no|toggle}]
    This sets or unsets the Traceview object rendering "batch" mode. When the batch mode has been set, then subsequent commands and method calls to change the display in any way are performed but are not actually rendered on the screen. When the batch mode is unset, then a refresh is called which will immediately render the display with all changes that occurred since the last time the batch mode was set and subsequent changes will be rendered immediately. This provides a way to prevent display "flashing" and to increase the performance when a set of object changes are made.
  • display linewidth linewidth
    This sets the Traceview object default trace linewidth to linewidth pixels. Each individual BQTrace object will use this to set the trace linewidth when the BQTrace object linewidth configuration value is set to < 0.0.
  • traces maximum number
    This will set a maximum number of traces, specified by number, to be displayed. If set to < = 0, then there is no maximum number of trace to be displayed. This forces no more than number traces to ever be displayed regardless of other settings.
  • traces minimum_pixels number
    This will set a minimum vertical pixel size for each trace, specified by number, to be displayed. If set to < = 0, then there is no minimum trace vertical pixel size to be displayed. This constrains each trace vertical height to be no less than number pixels and is enforced regardless of other settings.
  • traces fit [{auto|toggle|no}]
    This will zoom the currently selected traces in the vertical direction to fit within the display window. If the traces fit form is used with no other arguments, then the zoom is applied once. If auto is specified, then the zoom is applied automatically whenever there is a change in the event or origin displayed. If no is specified, then the automatic zooming is disabled. If toggle is specified, then the automatic zooming is toggled. Note that the number of traces that are displayed is still subject to the traces maximum and traces minimum_pixels limits.
  • traces sta [{yes|no|toggle}]
    This sets or unsets automatically showing only traces that have arrivals within the current display time window. If toggle, then the behavior is toggled. This behavior is dynamic with any change of the display time window.
  • traces std [{yes|no|toggle}]
    This sets or unsets automatically showing only traces that have detections within the current display time window. If toggle, then the behavior is toggled. This behavior is dynamic with any change of the display time window.
  • traces stad [{yes|no|toggle}]
    This sets or unsets automatically showing only traces that have arrivals or detections within the current display time window. If toggle, then the behavior is toggled. This behavior is dynamic with any change of the display time window.
  • traces auto_distance_sort [{yes|no|toggle}]
    This sets or unsets automatically sorting traces according to distance from the selected event and origin. If toggle, then the behavior is toggled. This behavior is dynamic with any change of the selected event or origin.
  • traces gain {gain|*gain_factor|/gain_factor}
    This causes all trace amplitudes to be gained up or down in the display by the value gain. The gain is applied to the trace amplitude plot scaling to increase the trace amplitudes, when gain > 1.0, or to decrease the trace amplitudes, when gain < 1.0. If the *gain_factor form is used, then gain_factor is used to multiply the current trace gains. If the /gain_factor form is used, then gain_factor is used to divide the current trace gains.
  • traces[:trace_exprs] select [{yes|no|toggle}]
    This causes traces to be marked as selected or deselected. When a trace is marked as selected, its trace label region is rendered with different colors along with a selection order text value. If toggle, then the behavior is toggled. If :trace_exprs is not specified, then all traces are selected or deselected. If :trace_exprs is specified, then trace_exprs is evaluated against all of the traces to produce an ordered list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3). Each trace in the list is then selected or deselected. The traces selection list is cumulative. It can be cleared with a traces select no command.
  • traces[:trace_exprs] configure key value
    If :trace_exprs is not specified, then the Traceview object configure method is called with arguments key and value. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of traces is used, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3). For each BQTrace object in the list, its configure method is called with arguments key and value (see BQTrace(3)).
  • traces[:trace_exprs] dup
    This duplicates traces. If :trace_exprs is not specified, then all traces are duplicated. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of traces are duplicated, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces are duplicated. Note that you cannot duplicate duplicated traces, only original traces. Duplicate traces are identified by the <copy> field in the standard trace labels as described previously in the INDIVIDUAL TRACE REPRESENTATION section.
  • traces[:trace_exprs] show [{yes|no|toggle}]
    This will cause traces to be shown or hidden. If toggle, then the behavior is toggled. If :trace_exprs is not specified, then all traces are shown or hidden. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of traces are shown or hidden, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section previously, and those traces are show or hidden. If the "traces[:traces_exprs] show" form is used with no other arguments, then the traces that match the expression are shown and all other traces are hidden.
  • traces[:trace_exprs] order
    This both shows and orders traces in the display. If :trace_exprs is not specified, then all traces are shown and ordered in the original traces source data order. If :trace_exprs is specified and trace_exprs is set to selected, then the current ordered selected list of traces is used to show and order the traces in the display, otherwise trace_exprs is evaluated against all of the traces to produce an ordered list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces are show and ordered according to the list. Note that traces that do not match are automatically hidden. Also not that ordering traces with this command can work against other automatic trace show/hide/order, commands like traces auto_distance_sort and traces stad commands. Usually when using this command you would first want to disable the other automatic show/hide/order commands.
  • traces[:trace_exprs] zoom [{first_index number|number|factor [first_y]}]
    This will zoom in the vertical traces dimension. If there are no arguments specified, then first a list of traces is composed. If there are no arguments and :trace_exprs is not specified, then all traces in the original traces source data order are put into the list. If There are no arguments and :trace_exprs is specified and trace_exprs is set to selected, then the current ordered selected list of traces is used as the zoom list, otherwise trace_exprs is evaluated against all of the traces to produce an ordered list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces are used in the zoom list. Once the zoom list has been composed, then the zoom is such that the first trace in the list is at the top of the display and the last trace in the list is at the bottom of the display. If the argument is first_index number, then :trace_exprs should not be specified and the zoom will be such that the topmost trace is the trace with integer index first_index in the current trace display (starting with 0) and number is the integer number of traces to the bottom edge of the display. If the argument is number, then :trace_exprs should not be specified and the zoom will be such that the topmost trace remains unchanged and number is the integer number of traces to the bottom edge of the display. If the argument is factor [first_y], then :trace_exprs should not be specified and the zoom will be such that the Y-axis scale is zoomed in by floating factor < 1.0 and zoomed out by floating factor > 1.0. The Y-axis zoom can be anchored to Y-axis non-dimensional floating value first_y as the topmost trace, or if not specified the topmost trace remains unchanged.
  • traces[:trace_exprs] start [first_index]
    This will pan (scroll) in the vertical traces dimension. If there are no arguments specified, then first a list of traces is composed. If there are no arguments and :trace_exprs is not specified, then all traces in the original traces source data order are put into the list. If There are no arguments and :trace_exprs is specified and trace_exprs is set to selected, then the current ordered selected list of traces is used as the pan list, otherwise trace_exprs is evaluated against all of the traces to produce an ordered list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces are used in the pan list. Once the pan list has been composed, then the pan is such that the first trace in the list is at the top of the display. If the argument is first_index, then :trace_exprs should not be specified and the pan will be such that the topmost trace is the trace with integer index first_index in the current trace display (starting with 0).
  • traces[:trace_exprs] stretch factor
    This applies a vertical stretch factor to one or more traces in the display. The vertical stretch factor is used to make trace vertical height in the display larger or smaller than other traces in the display. The vertical stretch factor is relative to all of the traces in the display. Therefore is all of the traces are set to the same vertical stretch factor, then the trace display heights will all be equal and remain the same regardless of the value of factor. If :trace_exprs is not specified, then all trace stretch factor are set to the floating factor. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of trace stretch factors will be set to the floating factor, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces stretch factors are set to the floating factor.
  • traces[:trace_exprs] color [color_string]
    This sets trace foreground colors. The foreground color is the color of the trace waveform lines. If color_string is not specified, then the trace foreground colors are set to NULL which causes the traces to use the default Traceview foreground color for the main and edit display windows. If :trace_exprs is not specified, then all trace foreground colors are set to the color color_string. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of trace foreground colors will be set to the color color_string, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces foreground colors are set to the color color_string.
  • traces[:trace_exprs] color_background [color_string]
    This sets trace background colors. If color_string is not specified, then the trace background colors are set to NULL which causes the traces to use the default Traceview background color for the main and edit display windows. If :trace_exprs is not specified, then all trace background colors are set to the color color_string. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of trace background colors will be set to the color color_string, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces background colors are set to the color color_string.
  • traces[:trace_exprs] linewidth [linewidth]
    This sets trace linewidths. If linewidth is not specified, then the trace linewidths are set to -1.0 which causes the traces to use the default Traceview linewidth for the main and edit display windows. If :trace_exprs is not specified, then all trace linewidths are set to the floating pixel linewidth. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of trace background colors will be set to the floating pixel linewidth, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces background colors are set to the floating pixel linewidth.
  • traces[:trace_exprs] filter [TPAD time_pad ]filter_string [# filter_label]
    This specifies a waveform filter to be applied to traces before display. If the filter parameters are not specified, then the trace filters are set to NULL which causes the traces to use the default Traceview filter for the main and edit display windows. If :trace_exprs is not specified, then all trace filters are set to the filter parameters. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of traces will have their filters set to the filter parameters, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces will have their filters set to the filter parameters. The filter_string can be none, meaning no filtering, or any proper filter string as defined in wffil(3), wffilbrtt(3) and wffilave(3). If TPAD time_pad is specified, then time_pad is a floating time value in seconds that is used as a time pad for removing filter transients in the display. If # filter_label is specified, then filter_label is a string label for the filter that is displayed below the trace label to the left of the trace display, otherwise the filter label is set to filter_string.
  • traces[:trace_exprs] units [{source|counts|sm}]
    This sets the trace display units values. If the filter parameters are not specified, then the trace display units are set to default which causes the traces to use the default Traceview trace display units for the main and edit display windows. If :trace_exprs is not specified, then all trace display unit are set to the units argument. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of traces will have their display units set to the units argument, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces will have their display units set to the units argument. A units argument value of source will cause trace units to correspond to the data source units. A value of counts will cause trace units to be digital counts. A value of sm will cause trace units to be strong motion units of cm/s for velocity traces and mg for acceleration traces.
  • traces[:trace_exprs] scale [{fixed abottom atop|auto}]
    This sets the trace amplitude display scale modes and scale factors. If the scale parameters are not specified, then the trace amplitude scale modes are set to default which causes the traces to use the default Traceview trace amplitude scale modes and scale factors for the main and edit display windows. If :trace_exprs is not specified, then all trace amplitude scale modes and scale factors are set to the scale parameters. If :trace_exprs is specified and trace_exprs is set to selected, then the current selected list of traces will have their amplitude scale modes and scale factors set to the scale parameters, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and those traces will have their amplitude scale modes and scale factors set to the scale parameters. If fixed abottom atop is specified, then the trace amplitude display scale modes are set to fixed, the amplitude corresponding to the bottom of the single trace display window is abottom in native source units and the amplitude corresponding to the top of the single trace display window is top in native source units. If auto is specified, then the trace amplitude display scale modes are set to auto.
  • arrivals edit_mode {yes|no|toggle}
    This will set or unset the display mode to the edit state. Arrival edits are only permitted when the display mode is in the edit state. If toggle, then the behavior is toggled.
  • arrivals select {clear|arid {yes|no|toggle}}
    This will set or clear arrival selected states. When arrivals are selected, they can be edited. if clear is specified, then all arrival selections are cleared. If arid {yes|no|toggle} is specified, then the selection is set or unset or toggled for arrival with arid value arid.
  • arrivals add_mode {yes|no|toggle}
    This sets, unsets or toggles the add new arrival modes used only when the main display is in edit mode. If the main display is in edit mode and if the add arrivals mode flag is set, then a left mouse click will add new arrivals and continue to add new arrivals until either the add arrivals mode flag has been unset, or the right mouse button is clicked which automatically unsets the add arrivals mode flag.
  • arrivals phase phase_string
    This will edit all of the currently selected arrivals so that the CSS iphase attribute is set to phase_string. Only selected arrivals are edited and this happens only if the main display is in edit mode. Arrival edits are immediately flushed out to the database files.
  • arrivals tag {clear|clear_all|associated|tag_string}
    This clears and sets tag values for arrivals. if clear is specified, then all currently selected arrival tags are cleared. if clear_all is specified, then all arrival tags are cleared. if associated is specified, then arrivals that are associated with the currently selected event and origin are tagged according to the CSS assoc table timedef attribute so that defining arrivals are tagged with D and non-defining arrivals are tagged with N. if tag_string is specified, then the currently selected arrivals tags will be set to tag_string.
  • arrivals output {tagged|selected}
    This will cause the output string in a SendCommand to contain a list of arrival arid values and the associated tag values. if tagged is specified, then the output list will contain all arrival with tags. if selected is specified, then the output list will contain all currently selected arrivals.
  • arrivals copy [clear]
    If clear is specified, this clears the copy clipboard, otherwise this sets the copy clipboard to the currently selected arrivals. The current selection is cleared.
  • arrivals paste [dont_paste_tags] time_string
    This pastes the copy clipboard as new arrivals. The time of the earliest arrival is set to time_string and the other arrival times maintain their relative positions. If dont_paste_tags is specified, then the copy clipboard arrival tags are not copied, otherwise they are copied. Note that when tags are copied any existing tags are first cleared. Also, any existing selections are cleared and the newly added arrivals are left in a selected state.
  • arrivals[:trace_exprs] show [{yes|no|toggle}]
    This will cause arrivals to be shown or hidden. If toggle, then the behavior is toggled. If :trace_exprs is not specified, then all arrivals are shown or hidden. If :trace_exprs is specified and trace_exprs is set to selected, then the arrivals for the current selected list of traces are shown or hidden, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and the arrivals for those traces are shown or hidden.
  • detections[:trace_exprs] show [{yes|no|toggle}]
    This will cause detections to be shown or hidden. If toggle, then the behavior is toggled. If :trace_exprs is not specified, then all detections are shown or hidden. If :trace_exprs is specified and trace_exprs is set to selected, then the detections for the current selected list of traces are shown or hidden, otherwise trace_exprs is evaluated against all of the traces to produce a list of matching BQTrace object pointers, as described in the TRACE EXPRESSIONS section in BQTraceview(3), and the detections for those traces are shown or hidden.
  • event show {index|+incr|-incr|eevid|noev}
    This will set an event as selected, or no event will be selected if noev is set. If eevid is specified, where evid is a valid database evid value, then the event will be set to the corresponding evid and the origin will be set to the event's preferred origin. If +incr is specified, then the event will be incremented by incr entries in the event list returned by EVClient::getEvents() (see EV(3)) and the origin will be set to the event's preferred origin. If -incr is specified, then the event will be decremented by incr entries in the event list returned by EVClient::getEvents() (see EV(3)) and the origin will be set to the event's preferred origin. If index is specified, then the event will be set to the indexth entry in the event list returned by EVClient::getEvents() (see EV(3)) and the origin will be set to the event's preferred origin. When an event and origin are selected, the display is automatically time scrolled to the origin time and the selected event status display is updated.
  • origin show {index|+incr|-incr|oorid|pref}
    This will set an origin as selected. Only the origins associated with the current selected event can be selected with this command. If pref is set, then the preferred origin is selected. If oorid is set, where orid is a valid database orid value for one of the origins associated with the current selected event, then the origin will be set to the corresponding orid. If +incr is set, then the origin will be incremented by incr entries in the origin list within the current selected event EVEvent structure (see EV(3)). If -incr is set, then the origin will be decremented by incr entries in the origin list within the current selected event EVEvent structure (see EV(3)). If index is set, then the origin will be set to the indexth entry in the selected event origin list in the EVEvent structure (see EV(3)). When an origin is selected, the display is automatically time scrolled to the origin time and the selected event status display is updated.

Traceview class EXAMPLE


#!/usr/bin/env bqpy

import os
import sys
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *
from antelope.ev import EVServer
import antelope.bupf as bupf

ge = GraphicsEngine()

mw = MainWindow (ge)

vp = Viewport (mw)

traceview = Traceview (vp)

pf = bupf.Pf("traceview")
traceview.configure (pf.getpfstring())

evserver = EVServer ('/opt/antelope/data/db/demo/demo')
traceview.createtraces (evserver)
traceview.sendcommand ('display time_window 1800')
traceview.sendcommand ('event show 0')

mw.geometry(1000, 1000, 0)
mw.show ()

ge.qtmainloop()
ge.pymainloop()

Map Class

Map objects are Viewport items used to display geographic base maps. Maps can be latitude-longitude map image grids expressed as color pixels, such as the NASA Bluemarble images, or Digital Elevation Model (DEM) latitude-longitude grids, such as the NASA SRTM30 DEM grid, or vector polylines representing shorelines, displayed as polygons with outlines and fills, or other non-filled polylines, such as political boundaries and rivers, such as the Global Self-consistent Hierarchial High-resolution Shoreline (GSHHS) database from NOAA's National Geophysical Data Center.
  • CONSTRUCTOR
    bqplot.Map(viewport, *args, **kwargs)
    

Where viewport is the Viewport master object. Configuration parameters can be optionally specified through the *args arguments and the **kwargs key-value pairs. These are specifed as in the configure method described below. Note that it is not necessary to set the master Viewport parameters. These are done automatically by the map object.

  • METHODS
    • itemshow()
      This will cause the Map viewport item to be shown.
    • itemhide()
      This will cause the Map viewport item to be hidden.
    • update()
      This will cause the Map viewport item to be updated.
    • setitemstale()
      This will cause the Map viewport item to be marked as stale which will cause the Map viewport item to be rerendered even if it is in a layer.
    • layer_handle = setlayer(layer_name)
      This will cause the
      Map viewport item to be rendered into a pixel layer with name layer_name. When a viewport item object is assigned to a layer, then the item rendering is to the layer pixmap and normal Qt paint events just display the layer pixmap. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the associated Viewport master setlayervisibility method.
    • setdefaults()
      This will set default parameters for the Map
      viewport item.
    • viewport = getviewport()
      This will return the
      Viewport master for this Map viewport item.
    • taskbar = gettaskbar()
      This will return the
      Taskbar object for this Map viewport item.
    • configure(*args, **kwargs)
      This will cause
      Map configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Map objects the configuration keys and appropriate values are as follows.
      • fill_land landfillColor
        Specifies a color to use for filling land areas. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . If this is specified as a "" string, then land areas will not be filled. This defaults to "#fff2e5". This is substituted for the $FILL_LAND tokens in the maplayer definitions.
      • fill_water waterfillColor
        Specifies a color to use for filling water areas. Can be specified in any of the forms documented in BQ_ParseColor(3)
        . If this is specified as a "" string, then water areas will not be filled. This defaults to "#e0e0ff". This is substituted for the $FILL_WATER tokens in the maplayerdefinitions.
      • maplayer_definitions maplayerDefinitionsString
        This item configuration option is used to define the various base map layers. and do not necessarily map one-to-one to BQLayer
        objects. The maplayerDefinitionsString is an Antelope parameter file string that contains these parameters. Following is a typical maplayerDefinitionsString for this option.
        
        maplayer_definitions &Arr{
            bluemarble &Arr{
                mapdata_source_file /opt/antelope/data/maps/bmd/bluemarble.world.200407.v01.grid.bmd
                opacity     1.0
                gamma       0.7
                lightmin    0.1
                antialias   0
                type        grid
                bq_layer    image
            }
            dem &Arr{
                mapdata_source_file /opt/antelope/data/maps/bmd/srtm30.dem.world.v01.grid.bmd
                opacity     1.0
                antialias   0
                type        grid
                bq_layer    image
            }
            water &Arr{
                mapdata_source_file coasts.vector.bmd
                opacity     1.0
                antialias   0
                type        vector_fill
                bq_layer    water
                outline_linewidth   -1
                background_color    $FILL_WATER
                fill_color      $FILL_LAND
                transparent_color   $FILL_LAND
            }
            coasts &Arr{
                mapdata_source_file coasts.vector.bmd
                opacity     1.0
                antialias   1
                type        vector_fill
                bq_layer    vector
                outline_linewidth   1
                outline_color       \#000000
                background_color    $FILL_WATER
                fill_color      $FILL_LAND
            }
            coast_outlines &Arr{
                mapdata_source_file coasts.vector.bmd
                opacity     1.0
                antialias   1
                type        vector
                bq_layer    vector
                outline_color   \#40000000
                outline_linewidth   0
            }
            political &Arr{
                mapdata_source_file political.vector.bmd
                opacity     1.0
                antialias   1
                type        vector
                bq_layer    vector
                levels &Tbl{
                    1   \#80ff0000
                    0   \#8000a000 3
                    0   \#c0a52a2a
                }
            }
            rivers &Arr{
                mapdata_source_file rivers.vector.bmd
                opacity     1.0
                antialias   1
                type        vector
                bq_layer    vector
                levels &Tbl{
                    1   \#c0c0ff
                }
            }
            rivers_image &Arr{
                mapdata_source_file rivers.vector.bmd
                opacity     1.0
                antialias   1
                type        vector
                bq_layer    vector
                levels &Tbl{
                    1   \#400000ff
                    1   \#400000ff 3
                    1   \#400000ff 3
                }
            }
            shade &Arr{
                opacity     1.0
                type        shade
                bq_layer    vector
                proj        globe
            }
        }
        
        
        
      • The parameter file must contain an associate array named maplayer_definitions. The maplayer_definitions array defines the various base map layers that can be displayed. Each entry in the maplayer_definitions array is another associative array with a unique and arbitrary map layer name and there are automatically generated maplayer objects for each entry. The definitions of the individual map layer parameters are as follows.
        • mapdata_source_file
          This is a file name that contains the map data. The map file formats currently supported are bmd and rgb. If the file name starts with a / character, then the file name is an absolute file name, otherwise the file is assumed to be in $ANTELOPE/data/maps/bmd. Note that the GSHHS coastline, political and river vector data are normally distributed with the Antelope install image and will be installed in $ANTELOPE/data/maps/bmd. The various grid map files are not contained in the Antelope install image and must be downloaded separately.
        • opacity
          This is a floating point opacity value that is applied to the layer rendering relative to the layers underneath it. A value of 1.0 means complete opaque and a value of 0.0 means completely translucent.
        • antialias
          This is a flag that specifies if the QPainter setRenderHint(QPainter::Antialiasing) method should be called prior to any rendering. Setting this flag will cause lines to be antialiased as they are rendered.
        • type typeString
          This must be one of grid, for latitude-longitude pixel color grid maps or latitude-longitude DEM grid maps, vector, for vector maps, or shade for a shade overlay.
        • proj
          This is only used when typeString is set to shade. This is a , separated list of projection types for which the shading will be applied. See the projection configuration parameter below for projection type strings. The shading will only be appied when the projection is set to one of these types.
        • bq_layer
          This is a layer name that will be used to contain this map layer. If the layer object has not been previously created, then it will be created and assigned this name automatically. Note that more than one map layers can be assigned to the same layer object.
        • outline_width
          This is the width in pixels of vector outline plots. If this is set to -1, then the vector outline plot is not made.
        • background_color
          This is the fill color of "background" areas for maps that describe vector polygons, such as coastline maps. For coastline maps this would correspond to the water color. If this is "", then the background is not filled. This can be set to $FILL_WATER, meaning to substitute the Map object waterfillColor parameter or $FILL_LAND, meaning to substitute the the Map object landfillColor parameter. Can be specified in any of the forms documented in BQ_ParseColor(3).
        • fill_color
          This is the fill color of "foreground" areas for maps that describe vector polygons, such as coastline maps. For coastline maps this would correspond to the land color. If this is "", then the foreground is not filled. This can be set to $FILL_WATER, meaning to substitute the Map object waterfillColor parameter or $FILL_LAND, meaning to substitute the the Map object landfillColor parameter. Can be specified in any of the forms documented in BQ_ParseColor(3).
        • transparent_color
          This can be specified in the same way as the background_color and fill_color parameters. If this is specified, then the pixel colors specified will be converted to completely translucent colors when the layer is rendered. This provides a means to make color masks, such as water or land masks. If this is not specified, then this rendering transformation is not done.
        • levels
          This is a table that defines display parameters as a function of the various levels in a vector map. Many vector maps assign a level to a set of vector polylines. For instance, the GSHHS political vector map assigns national boundaries to level 1, state/provential boundaries to level 2, etc. Each line in the table corresponds to a level. Each line contains white space separated linewidth, color and optionally resolution fields. The linewidth field is as defined above with the outline_linewidth parameter. The color field is as defined above with the fill_land and fill_water parameters. The resolution field is an optional integer number that specifies the minimum map internal resolution for which the layer should be displayed. Many vector maps have different map resolutions. For instance, the GSHHS vector maps have five resolution levels; crude, low, intermediate, high and full. If this field is specified as 3, for example, then that particular level will only be displayed for map resolutions 3 and higher, corresponding to intermediate, high and full resolutions for GSHHS maps.
        • Note that levels that are not defined will not be displayed.
  • define_maplayers_template maplayersTemplateDefinitionString
    This item configuration option is used to define a new map layers template. The maplayersTemplateDefinitionString is an Antelope parameter file string that contains these parameters. Following is a typical maplayersTemplateDefinitionString for this option.
    
    name bluemarble
    maplayers &Tbl{
        bluemarble
        rivers
        political
     }
    
    
  • The parameter file must contain a parameter named name which will be the name of this template. The parameter file must also contain a table named maplayers. Each entry in the maplayers table must correspond to a name from the maplayer_definitions array. Map layers are created and displayed in the order in this table. Use of this template (with maplayer_template configuration option) will cause the associated map layers to be displayed. Note that this configuration option can be called multiple times to define multiple templates.
  • define_maplayers_templates maplayersTemplatesDefinitionString
    This is an alternative way to define map layers templates. In this case multiple templates can be defined with a single configuration call. Following is a typical maplayersTemplatesDefinitionString for this option.
    
    maplayers_templates &Arr{
        vector &Arr{
            maplayers &Tbl{
                coasts
                rivers
                political
                shade
            }
        }
        vector_coasts &Arr{
            maplayers &Tbl{
                coasts
                coast_outlines
                rivers
                political
                shade
            }
        }
        bluemarble &Arr{
            maplayers &Tbl{
                bluemarble
                rivers_image
                political
            }
        }
        dem &Arr{
            maplayers &Tbl{
                dem
                rivers_image
                political
            }
        }
        demw &Arr{
            maplayers &Tbl{
                dem
                water
                rivers_image
                political
                shade
            }
        }
    }
    
    
  • The template names appear as the key values in an associative array named maplayers_templates.
  • maplayers_template maplayersTemplateNameString
    This is the name of a previously defined map layers template that should be displayed.
  • maplayer_show maplayerNameString
    This causes the named maplayer to be displayed.
  • maplayer_hide maplayerNameString
    This causes the named maplayer to be hidden.
  • maplayer_visibility_toggle maplayerNameString
    This causes the named maplayer's visibility to be toggled; i.e. a layer that is currently displayed will be hidden and a layer that is currently hidden will be displayed.
  • map_taskbar_buttons_definitions taskbarButtonsDefinitionsString
    This item configuration option is used to define the optional taskbar buttons. The Map class uses a Taskbar object which offers a very simple internal taskbar in which buttons and associated actions can be defined. This is completely optional. The taskbarButtonsDefinitionsString is an Antelope parameter file string that contains these parameters. Following is a typical taskbarButtonsDefinitionsString for this option.
    
    map_buttons_definitions &Arr{
        basemap &Arr{
            height 26
            description base map
            states &Arr{
                bluemarble &Arr{
                    label   BaB
                    description NASA Bluemarble
                    action  configure maplayers_template bluemarble
                    opacity 0.5
                    background_color blue
                    fill_color  yellow
                    order   0
                }
                dem &Arr{
                    label   BaD
                    description SRTM30 DEM
                    action  configure maplayers_template dem
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  black
                    order   1
                }
                demw &Arr{
                    label   BaW
                    description SRTM30 DEM with water masks
                    action  configure maplayers_template demw
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  black
                    order   2
                }
                vector &Arr{
                    label   BaV
                    description fill based on vector shorelines
                    action  configure maplayers_template vector
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  black
                    order   3
                }
                vector_coasts &Arr{
                    label   BaVC
                    description fill based on vector shorelines with shorelines
                    action  configure maplayers_template vector_coasts
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  black
                    order   4
                }
            }
        }
        projection &Arr{
            height 26
            description map projection
            states &Arr{
                globe &Arr{
                    label   PrGl
                    description globe projection
                    action configure projection globe
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  blue
                    order   0
                }
                edp &Arr{
                    label   PrE
                    description equal distance projection
                    action configure projection edp
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  blue
                    order   1
                }
                merc &Arr{
                    label   PrM
                    description Mercator projection
                    action configure projection merc
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  blue
                    order   2
                }
                geog &Arr{
                    label   PrLL
                    description lat-lon projection
                    action configure projection geog
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  blue
                    order   3
                }
            }
        }
        political &Arr{
            height 26
            description toggle political
            states &Arr{
                on &Arr{
                    label   P
                    action  configure maplayer_show political
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  red
                    order   0
                }
                off &Arr{
                    label   P
                    action  configure maplayer_hide political
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  red
                    order   1
                    show_not_symbol  yes
                }
            }
        }
        rivers &Arr{
            height 26
            description toggle rivers
            states &Arr{
                on &Arr{
                    label   R
                    action  &Tbl{
                        configure maplayer_show rivers
                        configure maplayer_show rivers_image
                    }
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  blue
                    order   0
                }
                off &Arr{
                    label   R
                    action  &Tbl{
                        configure maplayer_hide rivers
                        configure maplayer_hide rivers_image
                    }
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  blue
                    order   1
                    show_not_symbol  yes
                }
            }
        }
        nav &Arr{
            height 26
            description show/hide navigator window
            states &Arr{
                auto &Arr{
                    label   NaA
                    description auto
                    action  configure show_nav auto
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  blue
                    order   0
                }
                on &Arr{
                    label   Na
                    description on
                    action  configure show_nav on
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  blue
                    order   1
                }
                off &Arr{
                    label   Na
                    description off
                    action  configure show_nav off
                    opacity 0.5
                    background_color \#fff2e5
                    fill_color  blue
                    order   2
                    show_not_symbol  yes
                }
            }
        }
        zoomin &Arr{
            height 26
            label   +
            description zoom in
            action &Tbl{
                mod=shift configure zoom 2.0
                mod=notshift configure zoom 1.1
            }
            opacity 0.5
            background_color \#fff2e5
            fill_color  black
        }
        zoomout &Arr{
            height 26
            label   -
            description zoom out
            action &Tbl{
                mod=shift configure zoom 0.5
                mod=notshift configure zoom 0.9090909090909
            }
            opacity 0.5
            background_color \#fff2e5
            fill_color  black
        }
    }
    
    
  • The parameter file must contain an associate array named map_buttons_definitions. The map_buttons_definitions array defines the various taskbar buttons that can be displayed. This parameter file string is passed to the Taskbar.configure method with the "taskbar_buttons_definitions" option name with the string "buttons_definitions" substituted for the string "map_buttons_definitions". The definitions of the individual taskbar parameters are specified previously.
  • map_taskbar_buttons taskbarButtonsString
    This item configuration option is used to define a specific set of taskbar buttons to be displayed and used. The taskbarButtonsString is an Antelope parameter file string that contains these parameters. Following is a typical taskbarButtonsString for this option.
    
    map_buttons &Tbl{
        basemap     neb 1.0v-2  1.0v-2  0
        projection  neb -1r-1   0r  edp
        political   neb -1r-1   0r
        rivers      neb -1r-1   0r
        nav     neb -1r-1   0r
        zoomin      neb -1r-1   0r
        zoomout     neb -1r-1   0r
    }
    
    
  • The parameter file must contain a table named map_buttons. This parameter file string is passed to the Taskbar.configure method with the "taskbar_buttons" option name with the string "buttons" substituted for the string "map_buttons". The definitions of the individual taskbar parameters are specified previously.
  • map_taskbar_set_state taskbarSetStateString
    This is a convenience configuration parameter that sets the states of the taskbar buttons. This string is passed to the Taskbar.configure method with the "taskbar_set_state" option name. The definitions of the individual taskbar parameters are specified previously.
  • projection projectionString
    This is a convenience option that will cause the map projection to be set and for the map scales to be adjusted to keep the viewport so it is showing approximately the same map limits. This must be one of globe, for a spherical globe projection, edp, for equal distance projection, merc, for Mercator projection, or geog for straight geographic longitude-latitude projection.
  • zoom zoomFactor
    This is a convenience option that will cause the map to zoom in or out according to zoomFactor. A factor > 1.0 causes the map to zoom in. The center coordinate of the map viewport is preserved.
  • show_nav showNav
    This determines when the BQNavigastor(3) window is shown. It should be a boolean string to indicate if the window should be shown, or "auto", which causes the window to automatically be shown/hidden depending on the range of the map.
  • latr latitudeRef
    This is a convenience option and specifies a reference latitude in degrees. See Viewport previously for a definition.
  • lonr longitudeRef
    This is a convenience option and specifies a reference longitude in degrees. See Viewport previously for a definition.
  • range range
    This is a convenience option and specifies a X-axis range in degrees. See Viewport previously for a definition.
  • cache_maxsize cacheMaxsize
    This is an integer number of bytes that defines the maximum uncompressed map tile cache size. Most of the grid map files contain compressed map tile images. These tiles must first be decompressed before they can be used. In order to avoid the performance penalty in order to decompress these compressed tiles every time that tile needs to be displayed, the Map object maintains a cache with uncompressed tile images. This number specifies how big that cache can be. When an expansion of a new tile causes the cache size to go over this limit, the oldest tiles in the cache are freed until the cache size comes back below the tolerance. This defaults to 500000000.
  • nthreads numberThreads
    The rendering of grid images into the current map projection and scales is threaded within Map. This integer specifies how many threads to be used in this rendering. This defaults to 16.

Map Class EXAMPLE


#!/usr/bin/env bqpy

import os
import sys
import time
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *

ge = GraphicsEngine ()

width = 800
height = 800

mw = MainWindow (ge)

vp = Viewport (mw.getframe())

map = Map (vp)
map.setdefaults()

mw.geometry(width, height, 0)

mw.show()
ge.qtmainloop()
ge.pymainloop()

Mapevents Class

Mapevents objects are Viewport items used to display geographic base maps overlaid with seismic event locations, detection locations, all of the origins for each event, origin error ellipses, associated arrivals and detections for each origin, beachball displays when there are associated moment tensor solutions, and great circle paths between origins and stations. There is extensive built in mouse interaction to allow selection of events, selection of origins, as well as the extensive interaction of the underlying maps.

All Mapevents objects open Event View client connections to an Event View server (see EV(3)). All database information is derived from this Event View client connection. The Event View client-server implementation is intended to provide very robust permanent monitoring of a rapidly changing database, such as databases that are being constantly updated in a real-time processing system as well as by analysts who are changing the database and administrative tasks such as database cleaning. Event View client connections provide real-time dynamic updating of all changes in the underlying databases through callback mechanisms internal to the Mapevents objects. The various Mapevents display windows are automatically updated to reflect changes in the underlying databases. Note that the application script can set up its own separate Event View client connection to the Event View server. This allows the application program to have its own version of the various Event View lists. However, if this is done in the application script it is important that the application script use the Mapevents.registercallback method described below to register its own Event View callback instead of doing it through the EVClient.registercallback method. Use of callbacks through both objects simultaneously can cause synchronization problems.

All Mapevents objects make use of other bqplot objects, such as map objects and glyph objects, and synchronize interaction and display updates across these objects. There are three windows managed by a single Mapevents object. Each of these windows displays a map with event related information displayed as glyphs and other graphics objects overlaying the maps. The primary window displays all events in the database on a map and we refer to this window as the "events" window. The second window displays a single selected origin from a single event on a map along with its associated arrivals and detections that are within a certain time range from the origin time, along with great circle paths. We refer to this window as the "event" window. A third window can also be displayed which shows all of the origins for the selected event on a map along with the origin error ellipses. We refer to this window as the "origins" window. Textpopup objects can also be created and managed by each Mapevents object. These popups provide detailed textual information on selected events, origins, arrivals and detections. A separate Taskbar object can also be created and managed by each Mapevents object. this taskbar contains buttons related to changing display characteristics of the various display glyphs.

  • CONSTRUCTOR
    bqplot.Mapevents(events_viewport, event_viewport, origins_viewport, *args, **kwargs)
    

Where events_viewport is the Viewport master object for the events window, event_viewport is the Viewport master object for the event window and origins_viewport is the Viewport master object for the origins window. Configuration parameters can be optionally specified through the *args arguments and the **kwargs key-value pairs. These are specifed as in the configure method described below. Note that it is not necessary to set the various master Viewport parameters. These are done automatically by the Mapevents object.

  • METHODS
    • itemshow()
      This will cause the Mapevents viewport item to be shown.
    • itemhide()
      This will cause the Mapevents viewport item to be hidden.
    • update()
      This will cause the Mapevents viewport item to be updated.
    • setitemstale()
      This will cause the Mapevents viewport item to be marked as stale which will cause the Mapevents viewport item to be rerendered even if it is in a layer. This method is usually not necessary from the application program as the internal item rendering is managed automatically.
    • layer_handle = setlayer(layer_name)
      This will cause the
      Mapevents viewport item to be rendered into a pixel layer with name layer_name. When a viewport item object is assigned to a layer, then the item rendering is to the layer pixmap and normal Qt paint events just display the layer pixmap. Rendering to a layer can be forced with a call to the setitemstale method. Note that this method returns a layer handle in layer_handle which is an internal reference to the layer and must be used in the associated Viewport master setlayervisibility method.
    • setdefaults(nort=False)
      This will set default parameters for the
      Mapevents viewport item. If nort is set to True, then the real-time management button in the events taskbar will not be displayed.
    • viewport = getviewport()
      This will return the
      Viewport events window master for this Mapevents viewport item.
    • taskbar = gettaskbar()
      This will return the
      Taskbar object for this Mapevents viewport item.
    • seteventview(evserver)
      This will set the Event View for this object to evserver
      which should be an EVServer object. The Event View client used by the Mapevents object is created automatically.
    • refresheventview()
      This will cause the Event View to manually refresh with the database. This is normally only used when the Event View server is not configured for automatic updates.
    • link_eveventstableview(eveventstableview)
      This will cause a
      EVEventsTableview object, eveventstableview, to be linked to the mapevents object. When the two objects are linked, then they are internally and automatically synchronized, in both directions, with no need for application program callbacks or any other application program intervention. Synchronization means that when an event or origin is selected in the eveventstableview and its associated EVOriginsTableview spreadsheets, it will be shown in the various mapevent object displays and when an event or origin is selected within the mapevents object by clicking on the appropriate glyphs, that event or origin is automatically selected in the linked EVEventsTableview and EVOriginsTableview objects.
    • registercallback(proc, client_string_glyphs='0', client_string_event=None, client_string_eventview=None)
      Register the callback procedure with this object. See
      A NOTE ON CALLBACKS above. This is a little different from the other registercallback methods in that for Mapevents objects there are three different callback conditions. The first, specified by setting the client_string parameter in pfstring to client_string_glyphs, occurs when there are glyph-related mouse events, like with Polypoint objects. The second condition, specified by setting the client_string parameter in pfstring to client_string_event, occurs whenever the selected event is changed. The third condition, specified by setting the client_string parameter in pfstring to client_string_eventview, occurs whenever the underlying Event View server executes a callback because something changed in the database being monitored. The event and eventview callbacks can be omitted by setting the appropriate client strings to None.

Following is an example pfstring for glyph callbacks.


client_string glyphs
display_mode selected
bqevent &Arr{
    type mousemove
    button none
    modifiers none
    pt &Tbl{
        462.000
        228.000
    }
    gpt &Tbl{
        1222.000
        742.000
    }
    delta 0.000
}
bqglyph &Arr{
    index 82
    type event
    evid 317
}


The callback pfstring parameter file string contents for glyph callbacks are as follows.

  • client_string
    This is the client_string_glyphs specified in registercallback.
  • display_mode
    This indicates the display mode for the events window display and should be one of initial, indicating that all events in the display are sensitive to mouse events, or selected, meaning that only the selected event will be sensitive to mouse events. Note that the detections in the events window are always sensitive to mouse events.
  • bqevent
    This is a parameter file Arr that defines all of the mouse related event parameters. The parameter definitions are the same as for the bqevent Arr defined previously for the Polypoint.registercallback method.
  • bqglyph
    This is a parameter file Arr that defines glyph related parameters for the glyph under the mouse. The values within the Arr are defined as follows.
    • type
      This is the glyph type the defines what the glyph represents and should be one of event, origin, detection or association.
    • index
      This is the glyph index which should correspond to indexes within EVEvent vectors, or EVOrigin vectors, or EVDetection vectors, or EVAssociation vectors, according to type (see EV(3)).
    • evid
      This is the event evid value when type is event.
    • orid
      This is the origin orid value when type is origin.
    • presidual
      This is the P-wave residual in seconds for detection glyphs in the event window only when type is detection.
    • sresidual
      This is the S-wave residual in seconds for detection glyphs in the event window only when type is detection.

Following is an example pfstring for event callbacks.


client_string event
display_mode selected
evid 623

The callback pfstring parameter file string contents for event callbacks are as follows.

  • client_string
    This is the client_string_event specified in registercallback.
  • display_mode
    This indicates the display mode for the events window display and should be one of initial, indicating that all events in the display are sensitive to mouse events and that no new event has been selected, or selected, meaning that only the selected event will be sensitive to mouse events.
  • evid
    This is the new selected event evid value. This only appears when display_mode is selected.

Following is an example pfstring for eventview callbacks.


client_string eventview
database_reset 0
events_changed 1
detections_changed 0
last_modified_event_changed 1
last_modified_event_evid 312
expanded_events_changed &Tbl{
    312
    306
}

The callback pfstring parameter file string contents for eventview callbacks are as follows.

  • client_string
    This is the client_string_eventview specified in registercallback.
  • database_reset
    This is a 0 or 1 flag that indicates if the EVServer had to reset the database scans because of substantive changes, such as database purging or row rearrangements. When this flag is set the Mapevents object has already requested and received new view lists through its EVClient connection. If the application program has its own EVClient connection then it should assume everything in the database has changed and should act appropriately.
  • events_changed
    This is a 0 or 1 flag that indicates if the EVServer had to notify the internal EVClient within the Mapevents object because of some detected changes in the EVEvent vector. When this flag is set the Mapevents object has already requested and received a new EVEvent list through its EVClient connection. If the application program has its own EVClient connection then it should assume the EVEvent list has changed and should act appropriately.
  • detections_changed
    This is a 0 or 1 flag that indicates if the EVServer had to notify the internal EVClient within the Mapevents object because of some detected changes in the EVDetection vector. When this flag is set the Mapevents object has already requested and received a new EVDetection list through its EVClient connection. If the application program has its own EVClient connection then it should assume the EVDetection list has changed and should act appropriately.
  • last_modified_event_changed
    This is a 0 or 1 flag that indicates if the EVServer noticed changes to the most recently modified event in the database.
  • last_modified_event_evid
    This is the evid value of the most recently modified event.
  • expanded_events_changed
    This is a Tbl of evid values for expanded events that have changed. Expanded events are the ones shown in the event window that correspond to selected or previously selected events for which the full origin, detection and association information has been joined. See EV(3) for a more detailed description of expanded events. If the application program has its own EVClient connection then it should assume the expanded events list has changed and should act appropriately.
  • configure(*args, **kwargs)
    This will cause Mapevents configuration parameters to be set. The configuration parameters can be specified as a set of pairs of a string key followed by a value in the *args list, or they can be specified as hash <key>=<value> entries where <key> is a key name and not a string. For Mapevents objects the configuration keys and appropriate values are as follows.
    • mapevents_taskbar_buttons_definitions taksbarButtonsDefinitionsString
      This item configuration option is used to define the optional taskbar buttons. The Mapevents class uses a Taskbar object which offers a very simple internal taskbar in which buttons and associated actions can be defined. This is completely optional. The parameter file must contain an associate array named mapevents_buttons_definitions. The mapevents_buttons_definitions array defines the various taskbar buttons that can be displayed. This parameter file string is passed to the Taskbar.configure method with the "taskbar_buttons_definitions" option name with the string "buttons_definitions" substituted for the string "mapevents_buttons_definitions". The definitions of the individual taskbar parameters are in Taskbar. Following is a typical taskbarButtonsDefinitionsString for this option.
      
      mapevents_buttons_definitions &Arr{
          rt &Arr{
              height 26
              description real-time processing
              states &Arr{
                  none &Arr{
                      label   Rt
                      description no real-time processing
                      action &Tbl{
                          configure update_interval 0
                          configure auto_show_event no
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      show_not_symbol  yes
                      order       0
                  }
                  rt &Arr{
                      label   Rt
                      description enable real-time processing
                      action &Tbl{
                          configure update_interval 10
                          configure auto_show_event no
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       1
                  }
                  rtp &Arr{
                      label   RtE
                      description enable real-time processing plus auto show event
                      action &Tbl{
                          configure update_interval 10
                          configure auto_show_event yes
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       1
                  }
              }
          }
          autoc &Arr{
              height 26
              description automatic event centering
              states &Arr{
                  none &Arr{
                      label   EvC
                      description no event automatic centering
                      action  configure auto_center no
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      show_not_symbol  yes
                      order       0
                  }
                  depth &Arr{
                      label   EvC
                      description enable event automatic centering
                      action  configure auto_center yes
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       1
                  }
              }
          }
          symbol &Arr{
              height 26
              description symbol coding
              states &Arr{
                  circle &Arr{
                      label   SyC
                      description circle
                      action &Tbl{
                          configure set_gc_definitions events=events,events
                          configure set_gc_definitions events_selected=events_selected,events_selected
                          configure set_gc_definitions origins=origins,origins
                          configure set_gc_definitions origins_pref=origins_pref,origins_pref
                          configure update_displays all
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       0
                  }
                  beachball &Arr{
                      label   SyBB
                      description beachballs
                      action &Tbl{
                          configure set_gc_definitions events=events,events_bb
                          configure set_gc_definitions events_selected=events_selected,events_selected_bb
                          configure set_gc_definitions origins=origins,origins_bb
                          configure set_gc_definitions origins_pref=origins_pref,origins_pref_bb
                          configure update_displays all
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       1
                  }
              }
          }
          color &Arr{
              height 26
              description color coding
              states &Arr{
                  none &Arr{
                      label   Cl
                      description no color coding
                      action &Tbl{
                          configure glyphs_change_gc_definitions events=fill_color:constant
                          configure glyphs_change_gc_definitions events_bb=fill_color:constant,fill_color:constant2
                          configure glyphs_change_gc_definitions events_selected=fill_color:constant
                          configure glyphs_change_gc_definitions events_selected_bb=fill_color:constant,fill_color:constant2
                          configure glyphs_change_gc_definitions origins=fill_color:constant
                          configure glyphs_change_gc_definitions origins_bb=fill_color:constant,fill_color:constant2
                          configure glyphs_change_gc_definitions origins_pref=fill_color:constant
                          configure glyphs_change_gc_definitions origins_pref_bb=fill_color:constant,fill_color:constant2
                          configure update_displays all
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      show_not_symbol  yes
                      order       0
                  }
                  depth &Arr{
                      label   ClD
                      description depth coding
                      action &Tbl{
                          configure glyphs_change_gc_definitions events=fill_color:depth
                          configure glyphs_change_gc_definitions events_bb=fill_color:depthbb,fill_color:depthbbnode
                          configure glyphs_change_gc_definitions events_selected=fill_color:depth
                          configure glyphs_change_gc_definitions events_selected_bb=fill_color:depthbb,fill_color:depthbbnode
                          configure glyphs_change_gc_definitions origins=fill_color:depth
                          configure glyphs_change_gc_definitions origins_bb=fill_color:depthbb,fill_color:depthbbnode
                          configure glyphs_change_gc_definitions origins_pref=fill_color:depth
                          configure glyphs_change_gc_definitions origins_pref_bb=fill_color:depthbb,fill_color:depthbbnode
                          configure update_displays all
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       1
                  }
              }
          }
          size &Arr{
              height 26
              description size coding
              states &Arr{
                  none &Arr{
                      label   Sz
                      description no size coding
                      action &Tbl{
                          configure glyphs_change_gc_definitions events=size:events
                          configure glyphs_change_gc_definitions events_bb=size:events_bb
                          configure glyphs_change_gc_definitions events_selected=size:events
                          configure glyphs_change_gc_definitions events_selected_bb=size:events_bb
                          configure glyphs_change_gc_definitions origins=size:origins
                          configure glyphs_change_gc_definitions origins_bb=size:origins
                          configure glyphs_change_gc_definitions origins_pref=size:origins_pref
                          configure glyphs_change_gc_definitions origins_pref_bb=size:origins_pref
                          configure events_window_selection_opacity_reduction_factor 0.5
                          configure events_window_selection_size_increase_factor 4.0
                          configure update_displays all
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      show_not_symbol  yes
                      order       0
                  }
                  magnitude &Arr{
                      label   SzM
                      description magnitude coding
                      action &Tbl{
                          configure glyphs_change_gc_definitions events=size:magnitude
                          configure glyphs_change_gc_definitions events_bb=size:magnitude
                          configure glyphs_change_gc_definitions events_selected=size:magnitude
                          configure glyphs_change_gc_definitions events_selected_bb=size:magnitude
                          configure glyphs_change_gc_definitions origins=size:magnitude
                          configure glyphs_change_gc_definitions origins_bb=size:magnitude
                          configure glyphs_change_gc_definitions origins_pref=size:magnitude
                          configure glyphs_change_gc_definitions origins_pref_bb=size:magnitude
                          configure events_window_selection_opacity_reduction_factor 0.25
                          configure events_window_selection_size_increase_factor 1.0
                          configure update_displays all
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       1
                  }
              }
          }
          fader &Arr{
              height 26
              description fader coding
              states &Arr{
                  none &Arr{
                      label   Fd
                      description no fader coding
                      action &Tbl{
                          configure glyphs_change_gc_definitions events=opacity:1
                          configure glyphs_change_gc_definitions events_bb=opacity:1
                          configure update_displays events
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      show_not_symbol  yes
                      order       0
                  }
                  ageyr &Arr{
                      label   FdAy
                      description fader age coding one year
                      action &Tbl{
                          configure glyphs_change_gc_definitions events=opacity:age1y
                          configure glyphs_change_gc_definitions events_bb=opacity:age1y
                          configure update_displays events
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       1
                  }
                  agemo &Arr{
                      label   FdAm
                      description fader age coding one month
                      action &Tbl{
                          configure glyphs_change_gc_definitions events=opacity:age1m
                          configure glyphs_change_gc_definitions events_bb=opacity:age1m
                          configure update_displays events
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       2
                  }
                  agewk &Arr{
                      label   FdAw
                      description fader age coding one week
                      action &Tbl{
                          configure glyphs_change_gc_definitions events=opacity:age1w
                          configure glyphs_change_gc_definitions events_bb=opacity:age1w
                          configure update_displays events
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       3
                  }
                  ageda &Arr{
                      label   FdAd
                      description fader age coding one day
                      action &Tbl{
                          configure glyphs_change_gc_definitions events=opacity:age1d
                          configure glyphs_change_gc_definitions events_bb=opacity:age1d
                          configure update_displays events
                      }
                      opacity 0.5
                      background_color \#a0ffa0
                      fill_color  black
                      order       4
                  }
              }
          }
      }
      
      
    • mapevents_taskbar_buttons taksbarButtonsString
      The parameter file must contain a table named mapevents_buttons. This parameter file string is passed to the Taskbar.configure method with the "taskbar_buttons" option name with the string "buttons" substituted for the string "mapevents_buttons". The definitions of the individual taskbar parameters are in Taskbar. Following is a typical taskbarButtonsString for this option.
      
      mapevents_buttons &Tbl{
          rt  neb 1.0v-2  1.0v-30 2
          symbol  neb -1r-1   0r  1
          size    neb -1r-1   0r  0
          color   neb -1r-1   0r  1
          fader   neb -1r-1   0r  0
          autoc   neb -1r-1   0r  1
      }
      
      
    • glyphs_gcitem_definitions gcItemDefinitionsString
      Following is a typical gcItemDefinitionsString for this option.
      
      glyphs_gcitem_definitions &Arr{
          symbol:events           circle
          symbol:events_bb        beachball
          symbol:origins          circle
          symbol:origins_bb       beachball
          symbol:arrivals         triangle
          symbol:events_detections triangle
          size:constant           constant    20
          size:events             constant    10
          size:events_bb          constant    20
          size:origins            constant    20
          size:origins_pref       constant    30
          size:arrivals           constant    10
          size:event_origins      constant    30
          size:events_detections  age 0.0,25.0:1800.0,12.0:12.0:25.0
          size:magnitude          magnitude   4.0,10:7.0,50:10:100
          size:arrivals_detections residual    5.0,20:5.01,15:15:20
          fill_color:constant     constant    \#a0a0a0
          fill_color:constant2    constant    \#d0d0d0
          fill_color:depth        depth       0.0,240.0:650.0,0.0;1.0;0.8
          fill_color:depthbb      depth       0.0,240.0:650.0,0.0;1.0;0.8
          fill_color:depthbbnode  depth       0.0,240.0:650.0,0.0;1.0;0.7
          fill_color:arrivals_def constant    magenta
          fill_color:arrivals_ndef constant    orange
          fill_color:arrivals_detections  constant    cyan
          fill_color:arrivals_detections_late constant    yellow
          fill_color:events_detections    constant    magenta
          outline_color:events    constant    \#80000000
          outline_color:events_selected   constant    red
          outline_color:origins_pref  constant    red
          outline_linewidth:0     constant    0.5
          outline_linewidth:3     constant    3.0
          outline_linewidth:none  constant    -1.0
          opacity:1               constant    1.0
          opacity:age1y           age     0.0,1.0:31536000.0,0.0:0.0:1.0
          opacity:age1m           age     0.0,1.0:2592000.0,0.0:0.0:1.0
          opacity:age1w           age     0.0,1.0:604800.0,0.0:0.0:1.0
          opacity:age1d           age     0.0,1.0:86400.0,0.0:0.0:1.0
          opacity:age1h           age     0.0,1.0:3600.0,0.0:0.0:1.0
          opacity:arrivals_detections residual    5.0,1:10.0,0.4:0.4:1
          opacity:events_detections   age 0.0,1:3600.0,0.0:0.0:1
      }
      
      
    • The parameter file must contain an associative array named glyphs_gcitem_definitions. These define the graphics context items used to display all of the event, detection, origin, and association glyphs. There are six different graphics context item types that define how a glyph is drawn; symbol, which defines the glyph symbol, size, which defines the glyph size, fill_color, which defines the glyph fill color, outline_color, which defines the glyph outline color, outline_width, which defines the outline line width and opacity, which defines the glyph overall opacity. Each entry in the glyphs_gcitem_definitions Arr consists of a key string of the form <glyph_item_type>:<name>, where <glyph_item_type> must be one of the glyph item types listed previously and <name> is an arbitrary name tag to reference the particular item definition.
    • The value string in the glyphs_gcitem_definitions Arr defines the particular graphics context item. For item type symbol, the value should be one of circle, square, triangle, point, cross, x, star, diamond or beachball. For all other graphics context items the value in the glyphs_gcitem_definitions Arr entries should consist of two white space separated strings, <value_type> <value>. The <value_type> string can be one of constant, age, depth, magnitude or residual. If the <value_type> string is constant, then the <value> string should be an integer or floating number or string appropriate to the graphics context item. All of the other <value_type> strings are representations of "coded" graphics context items.
    • Coded graphics context items allow the context to change linearly as a function of some indepent variable. An example would be fill_color as a function of event depth or size as a function of magnitude. If the <value_type> is not constant, then it must be one of age, for age (latency) based coding, depth, for event depth based coding, magnitude, for event or origin magnitude based coding or residual or residual, for detection lowest P or S residual based coding. The coding <value> string describes the linear relationship between the coding independent variable and the graphics context item value. For scalar graphics context items (all items other than colors) the <value> string should take the form of <iv1>,<dv1>:<iv2>,<dv2>[:<min>:<max>], where <iv1>,<dv1> are an independent variable and dependent variable pair for one point in the linear relationship <iv2>,<dv2> are an independent variable and dependent variable pair for a second point in the linear relationship and <min> and <max> are optional minimum and maximum limits placed on the dependent variable. An example shown above is the entry
      
          size:magnitude          magnitude   4.0,10:7.0,50:10:100
      
      
    • For this entry, a glyph size graphics context item, the size is coded according to the event or origin magnitude with a magnitude of 4.0 corresponding to a glyph size of 10 pixels and with a magnitude of 7.0 corresponding to a glyph size of 50 pixels and with minimum and maximum glyph sizes of 10 and 100 pixels respectively.
    • Colors are more complicated because a color specification requires three numbers (red, green, blue, or hue, saturation, lightness, etc.). The fill_colorll and outline_color graphics context items require three separate coding definitions when coding constructs are used. Each of hue, from 0 to 360, saturation,from 0.0 to 1.0 and lightness, from 0.0 to 1.0. This is accomplished in the fill_color andoutline_color graphics context item <value> specifications for coded graphics context items by specifying each of the hue, saturation and lightness values as with the scalar coded values each separated by the ; character. For colors a constant hue, saturation or lightness value may be specified. An example shown above is the entry
      
          fill_color:depth        depth       0.0,240.0:650.0,0.0;1.0;0.8
      
      
      
    • For this entry, a glyph fill color graphics context item, the fill color is coded according to the event or origin depth with a depth of 0.0 corresponding to a glyph fill color hue of 240.0 (blue) and with a depth of 650.0 corresponding to a glyph fill color hue of 0.0 (red) and with the saturation set to a constant 1.0 and the lightness set to a constant 0.8.
    • glyphs_gcitem_definition gcItemDefinitionString
      This provides a very useful way to add new graphics context items or the change an existing item. Following is a typical gcDefinitionString for this option.
      
      outline_color:events_selected constant blue
      
      
    • This would cause the outline_color:events_selected graphics context item to be changed to the constant color blue.
    • glyphs_gc_definitions gcDefinitionsString
      Following is a typical gcDefinitionsString for this option.
      
      glyphs_gc_definitions &Arr{
          events &Tbl{
              symbol:events
              size:events
              fill_color:depth
              outline_linewidth:0
              outline_color:events
              opacity:1
          }
          events_bb &Tbl{
              symbol:events_bb
              size:events_bb
              fill_color:depthbb
              outline_linewidth:0
              outline_color:events
              opacity:1
              fill_color:depthbbnode
              outline_linewidth:0
          }
          events_selected &Tbl{
              symbol:events
              size:events
              fill_color:depth
              outline_linewidth:3
              outline_color:events_selected
              opacity:1
          }
          events_selected_bb &Tbl{
              symbol:events_bb
              size:events_bb
              fill_color:depthbb
              outline_linewidth:3
              outline_color:events_selected
              opacity:1
              fill_color:depthbbnode
              outline_linewidth:0
          }
          events_detections &Tbl{
              symbol:events_detections
              size:events_detections
              fill_color:events_detections
              outline_linewidth:0
              outline_color:events
              opacity:events_detections
          }
          origins &Tbl{
              symbol:origins
              size:origins
              fill_color:depth
              outline_linewidth:0
              outline_color:events
              opacity:1
          }
          origins_pref &Tbl{
              symbol:origins
              size:origins_pref
              fill_color:depth
              outline_linewidth:3
              outline_color:origins_pref
              opacity:1
          }
          origins_bb &Tbl{
              symbol:origins_bb
              size:origins
              fill_color:depth
              outline_linewidth:0
              outline_color:events
              opacity:1
              fill_color:depthbbnode
          }
          origins_pref_bb &Tbl{
              symbol:origins_bb
              size:origins_pref
              fill_color:depth
              outline_linewidth:3
              outline_color:events
              opacity:1
              fill_color:depthbbnode
              outline_linewidth:0
          }
          arrivals_def &Tbl{
              symbol:arrivals
              size:arrivals
              fill_color:arrivals_def
              outline_linewidth:none
              outline_color:events
              opacity:1
          }
          arrivals_ndef &Tbl{
              symbol:arrivals
              size:arrivals
              fill_color:arrivals_ndef
              outline_linewidth:none
              outline_color:events
              opacity:1
          }
          arrivals_detections &Tbl{
              symbol:arrivals
              size:arrivals_detections
              fill_color:arrivals_detections
              outline_linewidth:0
              outline_color:events
              opacity:arrivals_detections
          }
          arrivals_detections_late &Tbl{
              symbol:arrivals
              size:arrivals_detections
              fill_color:arrivals_detections_late
              outline_linewidth:0
              outline_color:events
              opacity:arrivals_detections
          }
      }
      
      
    • The parameter file must contain an associative array named glyphs_gc_definitions. These define the complete graphics contexts as lists of graphics context items used to display all of the event, detection, origin, and association glyphs. There are thirteen different graphics contexts corresponding to the thirteen different glyphs in the various Mapevents display windows. The key strings for these thirteen different glyphs are as follows.
      • events
        These are the non-selected events glyphs in the events window that do not display beachballs.
      • events_bb
        These are the non-selected events glyphs in the events window that display beachballs.
      • events_selected
        These are the selected events glyphs in the events window that do not display beachballs.
      • events_selected_bb
        These are the selected events glyphs in the events window that display beachballs.
      • events_detections
        These are the detection glyphs in the events window.
      • origins
        These are the non-preferred origins glyphs in the event and origins window that do not display beachballs.
      • origins_pref
        These are the preferred origins glyphs in the event and origins window that do not display beachballs.
      • origins_bb
        These are the non-preferred origins glyphs in the event and origins window that display beachballs.
      • origins_pref_bb
        These are the preferred origins glyphs in the event and origins window that display beachballs.
      • arrivals_def
        These are the arrivals glyphs in the event window for defining arrivals.
      • arrivals_ndef
        These are the arrivals glyphs in the event window for non-defining arrivals.
      • arrivals_detections
        These are the detections glyphs in the event window detections with load dates prior to the origin load date.
      • arrivals_detections_late
        These are the detections glyphs in the event window detections with load dates after the origin load date.
  • The values are all Tbls with the entries being key strings from the glyphs_gcitem_definitions Arr defined above. Normally there should be the six graphics context item values except for beachball glyphs which allow for two different specifications of fill_color, outline_color and outline_linewidth corresponding to the two different nodes in each beachball. These second sets of graphics context items for beachballs are listed after the first set. Graphics context items that do not change in this second set can be omitted in the list.
  • set_gc_definitions setDefinitionsString
    This is the final piece of the puzzle for specifying the glyphs graphics contexts. Following is a typical setDefinitionsString for this option.
    
    events=events,events_bb
    
    
  • The string must be in the form <glyph_type>=<glyphs_definition_name1>,<glyphs_definition_name2>, where <glyph_type> is one of events, for the unselected events glyphs shown in the events window, events_selected, for the selected events glyphs shown in the events window, origins, for the non-preferred origins glyphs shown in the event and origins windows or origins_pref, for the preferred origins glyphs shown in the event and origins windows. The <glyphs_definition_name1> and <glyphs_definition_name2> strings must be key values in the gcDefinitionsString defined above corresponding respectively to event and origin glyphs without moment tensor solutions and event and origin glyphs with moment tensor solutions. This provides a simple switching mechanism to disable the display of beachball glyphs and is typically used through the taskbar buttons.
  • glyphs_changet_gc_definitions changeDefinitionsString
    This provides a mechanism for changing the graphics context items used by a glyph definition as specified in the gcDefinitionsString defined above. Following is a typical changeDefinitionsString for this option.
    
    events_selected_bb=fill_color:depthbb,fill_color:depthbbnode
    
    
  • The string must be in the form <glyph_type>=<glyphs_gcitem_name1>[,<glyphs_gcitem_name2>], where <glyph_type> is one of the thirteen glyph types in the gcDefinitionsString string defined above and <glyphs_gcitem_name1> is one of the glyphs_gcitem_definitions Arr key values, defined above. A second <glyphs_gcitem_name1> string can be optionally specified for beachball glyphs. The specified graphics context items will replace the previously defined graphics context items. This provides a mechanism for modifying glyph graphics contexts and is typically used through the taskbar buttons.
  • auto_center autocenterBoolean
    This is a boolean that determines if the various display windows should be automatically panned to center the selected event. Automatic zooming also takes place for the event window. This default to "no".
  • update_interval updateInterval
    This is an interval in seconds that is used to poll the event view to see if it needs to be refreshed. If this is "0.0", then there is no real-time polling and the event view can only be refreshed by a direct call to Mapevents.refresheventview.
  • show_detections {yes|no}
    this determines if detections are processed and shown in the displays. The default value is yes.
  • max_age_detections maxAgeDetections
    This specifies the maximum age of detections in seconds to be processed in the events window. The default value is 86400. This only effects detections displayed in the events window. Detections in the event window are always processed and displayed regardless of age.
  • age_ref_now {yes|no}
    This determines if the reference for determining detection ages is now(). The default value is yes. This only effects the detections shown in the events window. If this is set to no, then the age reference time is the latest load date time for all of the events. Setting this to no is typically done for static databases that are not changing.
  • auto_show_event {yes|no}
    This determines if the selected event is automatically changed in response to Event View changes. The default value is yes.
  • show_evid evid
    This causes the event with evid evid to be shown and to be set as the selected event.
  • show_orid orid
    This causes the origin with orid orid to be shown and brought to the top in the event and origins windows.
  • show_popups showPopupsString
    This controls which text popups should be shown. showPopupsString should be in the form <popup_name>={yes|no} where <popup_name> is one of all, meaning all text popups, events, meaning the events text popup in the events window, events_selected, meaning the selected event text popup in the event window or origins, meaning the origin text popups in the origins window. The default value is all=yes.
  • events_window_selection_size_increase_factor increaseFactor
    In the events window when an event is selected or an event is accentuated by a mouse moveover, its size is automatically increased by this factor. The default value is 4.0.
  • events_window_selection_opacity_reduction_factor reductionFactor
    In the events window when an event is selected or an event is accentuated by a mouse moveover, the opacity of all of the other events is reduced by this factor. The default value is 0.5.

Mapevents Class EXAMPLE

In this example we also show how to use an EVEventsTableview object and EVOriginsTableview objects synchronously with a Mapevents object. Also note the change of selected event outline color using the glyphs_gcitem_definition configuration option and the callback used for mouse right click events while over an event glyph.

#!/usr/bin/env bqpy

import os
import sys
import time
sys.path.append(os.environ['ANTELOPE'] + "/data/python")

import signal

signal.signal(signal.SIGINT, signal.SIG_DFL)

from antelope.bqplot import *
from antelope.pfsubs import *
from antelope.ev import *

def mapevents_callback (pfstring):
    argsd = PfSubs.pfstring2py (pfstring)
    if argsd['client_string'] != 'glyphs':
        return
    if argsd['bqevent']['button'] != 'right':
        return
    if argsd['bqevent']['type'] != 'mousepress':
        return
    if 'evid' not in argsd['bqglyph']:
        return

    toplevel = Frame(None)
    xg = int(float(argsd['bqevent']['gpt'][0]))
    yg = int(float(argsd['bqevent']['gpt'][1]))
    toplevel.position (xg+20, yg+20)
    evid = Button (toplevel)
    evid.text (argsd['bqglyph']['evid'])
    done = Button (toplevel)
    done.text ('Done')
    done.registercallback (lambda self: toplevel.delete())
    button_grid_layout = GridLayout (toplevel)
    button_grid_layout.addwidget (evid, 0, 0, 1, 1)
    button_grid_layout.addwidget (done, 1, 0, 1, 1)
    toplevel.show()

    return 'ok'

argc = len(sys.argv)
if argc != 1 and argc != 2 and argc != 3:
    print ("usage:bqpy_ev_test [dbname [refresh_interval]]")
    sys.exit(1)

if argc == 1:
    dbname = "/opt/antelope/data/db/demo/demo"
else:
    dbname = sys.argv[1]
interval = 0.0
if argc == 3:
    interval = float(sys.argv[2])

if interval > 0.0:
    try:
        evserver = EVServer(dbname, 1, 1000, 0)
    except Exception as e:
        print (e)
        exit (1)
else:
    try:
        evserver = EVServer(dbname, 0, 1000, 0)
    except Exception as e:
        print (e)
        exit (1)

evclient = EVClient(evserver)

colhash_events = {
    'event_row': {
        'label': 'event_row',
        'text_template': 'XXXXXXXXXXX',
        'source': 'events[%index].recno_event',
        'source_sort': 'recno_event',
        'format': '%9d',
    },
    'origin_row': {
        'label': 'origin_row',
        'text_template': 'XXXXXXXXXXX',
        'source': 'events[%index].origins[pref_origin].recno_origin',
        'source_sort': 'origins[pref_origin].recno_origin',
        'format': '%9d',
    },
    'time': {
        'label': 'time',
        'text_template': 'XXXXXXX XX/XX XX:XX:XX.XXX',
        'source': 'events[%index].origins[pref_origin].record_origin{epoch2str(time, "%Y%j %m/%d %T")}',
        'source_sort': 'origins[pref_origin].time',
        'anchor': 'e',
    },
    'lat': {
        'label': 'latitude',
        'text_template': 'XXX.XXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{lat}',
        'source_sort': 'origins[pref_origin].record_origin{lat}',
        'format': '%8.4f',
        'anchor': 'e',
    },
    'lon': {
        'label': 'longitude',
        'text_template': 'XXXX.XXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{lon}',
        'source_sort': 'origins[pref_origin].record_origin{lon}',
        'format': '%9.4f',
        'anchor': 'e',
    },
    'depth': {
        'label': 'depth',
        'text_template': 'XXX.XX',
        'source': 'events[%index].origins[pref_origin].record_origin{depth}',
        'source_sort': 'origins[pref_origin].record_origin{depth}',
        'format': '%6.2f',
        'anchor': 'e',
    },
    'evid': {
        'label': 'evid',
        'text_template': 'XXXXXXXXX',
        'source': 'events[%index].evid',
        'source_sort': 'evid',
        'format': '%9d',
        'anchor': 'e',
    },
    'orid': {
        'label': 'orid',
        'text_template': 'XXXXXXXXX',
        'source': 'events[%index].prefor',
        'source_sort': 'prefor',
        'format': '%9d',
        'anchor': 'e',
    },
    'ndef': {
        'label': 'ndef',
        'text_template': 'XXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{ndef}',
        'source_sort': 'origins[pref_origin].record_origin{ndef}',
        'format': '%4d',
        'anchor': 'e',
    },
    'nass': {
        'label': 'nass',
        'text_template': 'XXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{nass}',
        'source_sort': 'origins[pref_origin].record_origin{nass}',
        'format': '%4d',
        'anchor': 'e',
    },
    'auth': {
        'label': 'auth',
        'text_template': 'XXXXXXXXXXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{auth}',
        'source_sort': 'origins[pref_origin].record_origin{auth}',
        'anchor': 'e',
    },
    'region': {
        'label': 'region',
        'text_template': 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX',
        'source': 'events[%index].origins[pref_origin].record_origin{grname(lat,lon)}',
        'source_sort': 'origins[pref_origin].record_origin{grname(lat,lon)}',
        'anchor': 'e',
    },
    'magnitude': {
        'label': 'magnitude',
        'text_template': 'XXXXXXXXXX',
        'source': 'events[%index].magnitude;events[%index].magtype',
        'source_sort': 'magnitude;magtype',
        'format': '%4.2f(%s)',
        'anchor': 'e',
    },
}
collist_events = ['evid', 'magnitude', 'auth', 'time', 'region', \
           'lat', 'lon', 'depth', 'ndef', 'nass', 'event_row', 'origin_row']

colhash_origins = {
    'origin_row': {
        'label': 'origin_row',
        'text_template': 'XXXXXXXXXXX',
        'source': 'origins[%index].recno_origin',
        'source_sort': 'recno_origin',
        'format': '%9d',
    },
    'time': {
        'label': 'time',
        'text_template': 'XXXXXXX XX/XX XX:XX:XX.XXX',
        'source': 'origins[%index].record_origin{epoch2str(time, "%Y%j %m/%d %T")}',
        'source_sort': 'time',
        'anchor': 'e',
    },
    'latency': {
        'label': 'latency',
        'text_template': 'XXX:XX:XX:XX.XXX',
        'source': 'origins[%index].record_origin{strtdelta(lddate-time)}',
        'source_sort': 'record_origin{lddate-time}',
        'anchor': 'e',
    },
    'lat': {
        'label': 'latitude',
        'text_template': 'XXX.XXXX',
        'source': 'origins[%index].record_origin{lat}',
        'source_sort': 'record_origin{lat}',
        'format': '%8.4f',
        'anchor': 'e',
    },
    'lon': {
        'label': 'longitude',
        'text_template': 'XXXX.XXXX',
        'source': 'origins[%index].record_origin{lon}',
        'source_sort': 'record_origin{lon}',
        'format': '%9.4f',
        'anchor': 'e',
    },
    'depth': {
        'label': 'depth',
        'text_template': 'XXX.XX',
        'source': 'origins[%index].record_origin{depth}',
        'source+sort': 'record_origin{depth}',
        'format': '%6.2f',
        'anchor': 'e',
    },
    'orid': {
        'label': 'orid',
        'text_template': 'XXXXXXXXX',
        'source': 'origins[%index].orid',
        'source_sort': 'orid',
        'format': '%9d',
        'anchor': 'e',
    },
    'ndef': {
        'label': 'ndef',
        'text_template': 'XXXX',
        'source': 'origins[%index].record_origin{ndef}',
        'source_sort': 'record_origin{ndef}',
        'format': '%4d',
        'anchor': 'e',
    },
    'nass': {
        'label': 'nass',
        'text_template': 'XXXX',
        'source': 'origins[%index].record_origin{nass}',
        'source_sort': 'record_origin{nass}',
        'format': '%4d',
        'anchor': 'e',
    },
    'auth': {
        'label': 'auth',
        'text_template': 'XXXXXXXXXXXX',
        'source': 'origins[%index].record_origin{auth}',
        'source_sort': 'record_origin{auth}',
        'anchor': 'e',
    },
    'magnitude': {
        'label': 'magnitude',
        'text_template': 'XXXXXXXXXX',
        'source': 'origins[%index].magnitude;origins[%index].magtype',
        'source_sort': 'magnitude;magtype',
        'format': '%4.2f(%s)',
        'anchor': 'e',
    },
}
collist_origins = ['orid', 'latency', 'auth', 'magnitude', 'time', \
           'lat', 'lon', 'depth', 'ndef', 'nass', 'origin_row']

width = 1800
height = 800
mapevents_width = 900
mapevents_height = 300
mapevent_height = 500

maporigins_width = int(0.3*(width - mapevents_width))
maporigins_width = 0
mapevent_width = width - mapevents_width - maporigins_width

ge = GraphicsEngine ()

mw = MainWindow(ge)
toplevel = mw.getframe()

splitterh = Splitter(toplevel)
splitterevents = Splitter(toplevel, "vertical")
splittereventoriginsmaps = Splitter(toplevel)
splittereventorigins = Splitter(toplevel, "vertical")
splittereventorigins.addwidget (splittereventoriginsmaps, 0)
bqplot_geometry (splitterevents.gethandle(), mapevents_width, height, 0)
bqplot_geometry (splittereventoriginsmaps.gethandle(), maporigins_width+mapevent_width, height, 0)
bqplot_geometry (splittereventorigins.gethandle(), maporigins_width+mapevent_width, height, 0)

framemapevents = Frame (toplevel)
framemaporigins = Frame (toplevel)
framemapevent = Frame (toplevel)
splittereventoriginsmaps.addwidget (framemaporigins, 1)
splittereventoriginsmaps.addwidget (framemapevent, 0)
bqplot_geometry (framemapevents.gethandle(), mapevents_width, mapevents_height, 0)
bqplot_geometry (framemaporigins.gethandle(), maporigins_width, mapevent_height, 0)
bqplot_geometry (framemapevent.gethandle(), mapevent_width, mapevent_height, 0)

layout = GridLayout (toplevel)
layout.addwidget (splitterh, 0, 0, 1, 1)

vpmapevents = Viewport (framemapevents)
vpmaporigins = Viewport (framemaporigins)
vpmapevent = Viewport (framemapevent)
mapevents = Mapevents (vpmapevents, vpmapevent, vpmaporigins)
mapevents.setdefaults ()

mapevents.configure ( \
            "glyphs_gcitem_definition", "outline_color:events_selected constant blue",
            "show_popups", "origins=no" )

if interval == 0:
    mapevents.configure ( \
            "update_interval", "0.0", \
            "age_ref_now", "no")
else:
    mapevents.configure ( \
            "update_interval", "1.0", \
            "age_ref_now", "yes")

map = mapevents.getmap ()
map.configure ( \
          "map_taskbar_set_state",   "basemap:vector", \
          "map_taskbar_set_state",   "projection:globe", \
          "map_taskbar_set_state",   "political:off", \
          "map_taskbar_set_state",   "rivers:off", \
          "range",  10.0 )

mapevents.seteventview (evserver)

spreadsheet_events = EVEventsTableview (toplevel, evserver)
params = {}
params['column_names'] = collist_events
params['column_definitions'] = colhash_events
spreadsheet_events.configure ( \
    column_names = PfSubs.py2pfstring(params), \
    column_definitions = PfSubs.py2pfstring(params), \
    show_record_numbers = 'yes', \
    default_hover_interaction = 'no', \
    font = 'courier,12,Normal', \
    font_header = 'courier,12,Normal', \
    default_cell_height = 15, \
    auto_select_event = 'mostrecent', \
)

spreadsheet_origins = EVOriginsTableview (toplevel, spreadsheet_events)
params = {}
params['column_names'] = collist_origins
params['column_definitions'] = colhash_origins
spreadsheet_origins.configure ( \
    column_names = PfSubs.py2pfstring(params), \
    column_definitions = PfSubs.py2pfstring(params), \
    show_record_numbers = 'yes', \
    default_hover_interaction = 'no', \
    font = 'courier,12,Normal', \
    font_header = 'courier,12,Normal', \
    default_cell_height = 15, \
)

splittereventorigins.addwidget(spreadsheet_origins, 1)
splitterevents.addwidget(spreadsheet_events, 1)
splitterevents.addwidget (framemapevents, 0)
splitterh.addwidget (splitterevents, 0)
splitterh.addwidget (splittereventorigins, 1)

spreadsheet_events.set_sort_colname ('time', 1)
spreadsheet_origins.set_sort_colname ('latency')

mapevents.link_eveventstableview (spreadsheet_events)

menubar = Menubar (mw)

file_menu = menubar.addmenu ("&File")
quit_item = file_menu.additem (menubar, "&Quit")
quit_item.registercallback ( lambda self: bqplot_quit() )
file_menu.addseparator ()
print_item = file_menu.additem (menubar, "&Print...")
print_item.registercallback ( lambda self: PrintDialog(mw, mw, 1) )

view_menu = menubar.addmenu ("&View")
refresh_item = view_menu.additem (menubar, "&Refresh")
refresh_item.registercallback ( lambda self, s=evserver: s.refresh(1) )
max_events_menu = view_menu.addmenu ("&MaxEvents")
item_100 = max_events_menu.additem (menubar, "&100")
item_100.registercallback ( lambda self, s=evserver: s.set_maxevents(100) )
item_500 = max_events_menu.additem (menubar, "&500")
item_500.registercallback ( lambda self, s=evserver: s.set_maxevents(500) )
item_1000 = max_events_menu.additem (menubar, "&1000")
item_1000.registercallback ( lambda self, s=evserver: s.set_maxevents(1000) )
item_2000 = max_events_menu.additem (menubar, "&2000")
item_2000.registercallback ( lambda self, s=evserver: s.set_maxevents(2000) )
item_5000 = max_events_menu.additem (menubar, "&5000")
item_5000.registercallback ( lambda self, s=evserver: s.set_maxevents(5000) )
item_10000 = max_events_menu.additem (menubar, "&10000")
item_10000.registercallback ( lambda self, s=evserver: s.set_maxevents(10000) )
item_unlimited = max_events_menu.additem (menubar, "&Unlimited")
item_unlimited.registercallback ( lambda self, s=evserver: s.set_maxevents() )

mw.geometry(width, height, 0)

cb = lambda pfstring: mapevents_callback(pfstring)
mapevents.registercallback (cb, 'glyphs', 'event', 'ev')

if interval > 0.0:
    evserver.auto_refresh(interval)

mw.show()
ge.qtmainloop()
ge.pymainloop()

SEE ALSO

bqplot(3), pythonbupf(3y), BUPf(3), BQPfTreeview(3), BQTableview(3), BQDbTableview(3)

AUTHOR

Danny Harvey, BRTT