[libkorigin Index] [libkorigin Heirarchy]
A plot widget ABC for all kind of diagraphs More...
#include </home/mh/korigin/korigin/doc/tmp/plot.h>
Inherits: PageObject
A plot widget ABC for all kind of diagraphs. Overview:
Plot is an ABC for any kind of plots, be it x/y plots, r/phi plots or histograms. Because a plot is a very general thing, this class is full of pure virtual functions. In fact, this class is only the interface definition for plots.
A plot must provide quite a lot of functionality:
- Plots must be able to paint themselves onto a given painter. They have to implement the paint(QPainter*) method.
- Plots must provide information about themselves. That is, they must provide access to their type, a short description, the parameters they take, the icon they want to wear in the tree view, their own main menu entry.
- Plots can include multiple data sets, so they must provide methods to access them: add a new plot, remove an existing one, change an existing one.
- A plot type must register itself, i.e. it has to provide a prototype of itself. This prototype delivers information that would have been implemented as "static virtual" functions if that was possible (which it isnīt), and they are clone()d when the user wants a new plot. See [1] for details on the Prototype pattern. The prototype list is used to provide a global list of available plot types.
A short story about the creation of the design of the ABC:
I thought long about how to realize a base class for _all_ plots. I thought and Thought and THOUGHT, but to no avail. Clumsily, I longed for my last Tannezäpfle, I opened it and drunk. Alocohol and carbon dioxide washed through my brain, and the bitter taste of hops thunder- strucked the synapses... I was enlighted! I could make the "Plot" menu entry local to the plot itself and use getMenu() to get its handle! (Patrick Schemitz, 97/10/16)
In a less prosaic speaking, I hit upon the idea of moving all plot-specific widgets (such as menus, dialogs etc) into the widgets instead of letting the main widget deal with them. To put it even lesser prosaic, I just followed the old o-o rule: if it walks like a duck and quacks like a duck, it *is* a duck.
Since the Plot class wants its subclasses to specify the objects it creates, i.e. the Plot's subclasses are created by the main widget, I clone() the selected Prototype of the concrete plot. Therefore, each plot must register itself to that plot list, plotList().
Debugging:
The Plot classes debug output can be controlled by setting the debug level for "korigin.pw" to 0 (silent), 1 (warnings/errors), 3 (verbose), 4 (*very* verbose).
[1] Gamma, Helm, Johnson, Vlissides: Design Patterns. - Addison-Wesley, 1994.
Construct a Plotīs shell only. Initializes a plot. Warning: the constructor does *not* create the widget belonging to the plot! The widget must be set up with the instantiate() function!!!
Destructor. Deletes the widget of the plot.
Actually create the plotīs widget. The constructor only creates an empty shell of a plot, and a single menu entry for the plotīs menu(): "Plot columns". This function here creates the actual widget representing the plot. and passes its parameters to QWidget. To access the widget from outside the class, use the widget() function. The widget is destructed by Plotīs destructor. You will have to reimplement this function for nearly any concrete plot: in here, colors and fonts can be initialized, as well as the plotīs menu. DONīT FORGET to call the original function, Plot::instantiate() FIRST! You have been warned.
Return the QWidget of the plot. Since the Plot is not a QWidget itself (it only inherits QObject), you need this function to get the associated widget. The widget is set up by instantiate(). If you call widget() before you call instantiate(), a null pointer is returned. Note that the widget is destructed by Plotīs destructor.
Clone function. This function is used to clone the prototype of a derived Plot. Thus the name, Prototype pattern.
Return appropriate "Plot" submenu. A variable "the_menu" of type QPopupMenu* is already defined for you, but the default instantiate() routine inserts only one entry, thus the "Plot columns" entry which is connected to the plotīs plotSelectedColumns() slot. If you want more entries (this is very likely), add them in your instantiate() function.
Set active plot and icon. This sets the activePage to the invoked plots, and changes the plotīs icon to active.
Set inactive plot and icon. This changes the plotīs icon to active.
Store overall options for the plot. With overall options I mean the options that are valid for *all* plots of a kind, i.e. static class variables.
The implementation should store the options in the applicationīs KConfig object, kapp->getConfig().
Restore overall options for the plot. With overall options I mean the options that are valid for *all* plots of a kind, i.e. static class variables.
The implementation should restore the options from the applicationīs KConfig object, kapp->getConfig().
Start-of-plot mark.
Should be something like
End-of-plot mark. Should be something like .
Store a plot to a QFile. This function is intended to write a plot to the given QFile. If with_data==false, only the settings of this instance are stored; if with_data==true, the columns are to be stored, too. Please note that QFile is already opened and positioned when passed to store(). Also note that QFile may already contain other plots and/or worksheets.
Restore a plot from a QFile. This function is intended to read a plot from the given QFile. If with_data==false, only the settings of this instance are restored; if with_data==true, the columns are to be restored, too. Please note that QFile is already opened and positioned when passed to restore(). Also note that QFile may already contain other plots and/or worksheets.
[pure virtual] Return name/type info for your plot. The histogram type, HistoPlot, for example, returns "Histogram 1D".
[pure virtual] Return a short description of instance. The canonical example of a plot, HistoPlot, returns a string with information on the binning (i.e. the x step width) of the histogram.
[pure virtual] Return the pixmap for the tree view. x/y plots have other symbols than R/Phi plots, so pure virtual. BTW, you should check whether this==activePlot and select the "active" symbol if appropriate.
[pure virtual] Number of the plots parameters. This function defines how many columns are feed to a concrete plot (via insertSet). The canonical example, the HistoPlot, has only one parameter, the "Event". An X/Y plot is more interesting: 5 parameters x, y, x error, y error, label.
[pure virtual] Names of the plots parameters. This function defines the names of the parameters of a concrete class. The canonical example, the HistoPlot, has only one parameter, the "Event". An X/Y plot is more interesting: x, y, x error, y error, label.
i | number of the requested parameter name. |
[pure virtual] Paint yourself on a given painter. Your concrete plot must implement this function. The QPainter parameter is where the plot must paint itself on. This may be the plot page's QWidget, or a QPrinter.
p | the painter where your plot has to plot itself on. |
Implement mouse handling. The default implementation does nothing, i.e. ignores mouse events. Your plot widget might pop up a menu on right mouse button, for example.
Note, however, that only right mouse button clicks are passed to this function; the left mouse button is used to move plots around the page.
Returns pointer to the default plot typeīs prototype. This function reads the KConfig entry "default_plot" in the [Plot] group, scans the Plots() list for it and returns a pointer to the corresponding prototype. If it canīt find the default_plot, it returns the first plot in the Plots() list. If the list is empty, it returns 0.
Display the plotīs options dialog. With overall options I mean the options that are valid for *all* plots of a kind, i.e. static class variables.
Plot the data in selected columns of the active worksheet. This function gets the selected (highlighted) columns in the active worksheet via activeWS->getSelected(), and plots then in itself. Of course, this function must be implemented by the concrete plot classes.
variable to store the plotīs widget.
variable to store the concrete plot's menu entry.
variable to store the active icon.
variable to store the inactive icon.
DON'T RE-IMPLEMENT THIS! Just a wrapper for paint(QPainter*).
This signal is emitted when the tree item of the plot has changed. (By editing the caption, (de)activating the plot, deleteing or inserting datasets.)
| Kdoc |