1. Purpose
This reference to Pmw.Blt is basically a direct translation of the BLT Graph reference for Tcl programmers (included in the BLT package). To help navigation, the reference manual is divided into logical parts, though all the methods described are members the same Python class (the Pmw.Blt.Graph class).
Note: During the development of this Pmw.Blt manual, several differences between the original Tcl documentation and the Pmw.Blt package were discovered. As both the BLT and the Pmw.Blt package are under continuous development, this is not surprising. The core part of the testing of Pmw.Blt version 0.8.3 was done under Windows 98 using BLT version 2.4m. The differences between Windows 98 and Unix that we have encountered are reported for convenience (such differences may be due to different BLT versions on these two operating systems as well as different implementations of the underlying packages on different platforms).
2. The Graph part
A graph is composed of several components: coordinate axes, data elements, legend, grid, cross hairs, postscript, and annotation markers. Instead of one big set of configuration options and methods, the graph is partitioned, where each component has its own configuration options and methods that specifically control that aspect or part of the graph.
This part does however consider the more general methods that does not fit inside any of the above mentioned parts.
2.1. bar_create(...)
Synopsis
def bar_create(self, name, **kw):
Description
Creates a new bar-chart element named name. It is an error if an element named name already exists. See the Tk-manual for barchart for details about what option and value pairs are valid, or see the Hello Graph example.
See also
line_create(...), HelloGraph.py
2.2. line_create(...)
Synopsis
def line_create(self, name, **kw):
Description
Creates a new element named name. It is an error if an element named name already exists. If additional arguments are present, they specify options valid for the element_configure(...) method.
See also
element_configure(...), bar_create(...), HelloWorld.py
2.3. configure(...)
Synopsis
def configure(self, option = None, **kw):
Description
Queries or modifies the configuration options of the graph. If option=None, a tuple describing the current options for the graph is returned. If option is specified, then a tuple describing option is returned. If one or more option and value pairs are specified, then for each pair, the option is set to value. The following options are valid:
- background = "lightgray"
Sets the background color. This includes the margins and legend, but not the plotting area. (Windows 98: background = "SystemButtonFace") - borderwidth = 2
Sets the width of the 3-D border around the outside edge of the widget. The relief option determines if the border is to be drawn. (Windows 98: borderwidth=0) - bottommargin = 0
If non-zero, overrides the computed size of the margin extending below the X-coordinate axis. If bottommargin is 0, the automatically computed size is used. - bufferelements = 1
Indicates whether an internal pixmap to buffer the display of data elements should be used. If bufferelements is true, data elements are drawn to an internal pixmap. This option is especially useful when the graph is redrawn frequently while most of the data remains unchanged (for example, moving a marker across the plot). In cases of, for example, animation, this option should be turned off. - cursor = "crosshair"
Specifies the widget's cursor. - font = "*-Helvetica-Bold-R-Normal-*-18-180-*"
Specifies the font of the graph title. (Windows 98: font="Arial 12") - halo = "0.5i"
Specifies a maximum distance to consider when searching for the closest data point (see the element_closest(...) method below). Data points further than halo pixels away are ignored. - height = "4i"
Specifies the requested height of widget. - invertxy = 0
Indicates whether the placement X-axis and Y-axis should be inverted. If invertxy is true, the X and Y axes are swapped. - justify = "center"
Specifies how the title should be justified. This matters only when the title contains more than one line of text. Justify must be "left", "right", or "center". - leftmargin = 0
Sets the size of the margin from the left edge of the window to the Y-coordinate axis. If leftmargin is 0, the size is calculated automatically. - plotbackground = "white"
Specifies the background color of the plotting area. - plotborderwidth = 2
Sets the width of the 3-D border around the plotting area. The plotrelief option determines if a border is drawn. - plotpadx = 8
Sets the amount of padding to be added to the left and right sides of the plotting area. Plotpadx can be a tuple of one or two screen distances. If plotpadx has two elements, the left side of the plotting area entry is padded by the first distance and the right side by the second. If plotpadx is just one distance, both the left and right sides are padded evenly. - plotpady = 8
Sets the amount of padding to be added to the top and bottom of the plotting area. Plotpady can be a tuple of one or two screen distances. If plotpady has two elements, the top of the plotting area is padded by the first distance and the bottom by the second. If plotpady is just one distance, both the top and bottom are padded evenly. - plotrelief = "sunken"
Specifies the 3-D effect for the plotting area. Plotrelief specifies how the interior of the plotting area should appear relative to rest of the graph; for example, "raised" means the plot should appear to protrude from the graph, relative to the surface of the graph. Typical values are "raised", "flat" and "sunken". - relief = "flat"
Specifies the 3-D effect for the graph widget. Relief specifies how the graph should appear relative to widget it is packed into; for example, "raised" means the graph should appear to protrude. Typical values are "raised", "flat" and "sunken". - rightmargin = 0
Sets the size of margin from the plotting area to the right edge of the window. By default, the legend is drawn in this margin. If rightmargin is less than 1, the margin size is selected automatically. - takefocus = ""
Provides information used when moving the focus from window to window via keyboard traversal (e.g., Tab and Shift-Tab). If takefocus is 0, this means that this window should be skipped entirely during keyboard traversal. 1 means that the this window should always receive the input focus. An empty value means that the traversal scripts make the decision whether to focus on the window. - tile = ""
Specifies a tiled background for the widget. If tile isn't "", the background is tiled using the image in tile. Otherwise, the normal background color is drawn (see the background option). Tile must be an instance of the Tkinter.PhotoImage() class. - title = ""
Sets the title. If title is "", no title will be displayed. (Unix: title = "Graph Title") - topmargin = 0
Specifies the size of the margin above the x2 axis. If topmargin is 0, the margin size is calculated automatically. - width = "5i"
Specifies the requested width of the widget.
See also
element_configure(...), HelloGraph.py
2.4. extents(...)
Synopsis
def extents(self, item):
Description
Returns the size of a particular item in the graph. Item must be either "leftmargin", "rightmargin", "topmargin", "bottommargin", "plotwidth", or "plotheight". Be aware that this method does not function properly before the mainloop(...) method is entered because the widget is not yet drawn.
See also
2.5. invtransform(...)
Synopsis
def invtransform(self, winX, winY):
Description
Performs an inverse coordinate transformation, mapping window coordinates back to graph coordinates, using the standard X-axis and Y-axis. Returns a tuple containing the X-Y graph coordinates.
Be aware that this method does not function properly before the mainloop(...) method is entered because the widget is not yet drawn.
See also
transform(...), HelloMagnifier.py
2.6. transform(...)
Synopsis
def transform(self, x, y)
Description
Performs a coordinate transformation, mapping graph coordinates to window coordinates, using the standard X-axis and Y-axis. Returns a tuple containing the X-Y screen coordinates.
Be aware that this method does not function properly before the mainloop(...) method is entered because the widget is not yet drawn.
See also
invtransform(...), HelloGraph.py
2.7. inside(...)
Synopsis
def inside(self, x, y)
Description
Returns 1 if the designated screen coordinate (x and y) is inside the plotting area and 0 otherwise.
Be aware that this method does not function properly before the mainloop(...) method is entered because the widget is not yet drawn.
See also
2.8. snap(...)
Synopsis
def snap(self, photoName)
Description
Takes a snapshot of the graph and stores the contents in the photo image photoName. PhotoName must be an instance of the Tkinter.PhotoImage() class or the object's name.
See also
3. Elements
A data element represents a set of data. It contains x and y vectors containing the coordinates of the data points. Elements can be displayed with a symbol at each data point and lines connecting the points. Elements also control the appearance of the data, such as the symbol type, line width, color etc.
When new data elements are created, they are automatically added to a list of displayed elements. The display list controls what elements are drawn and in what order.
The following methods are available for elements:
3.1. element_activate(...)
Synopsis
def element_activate(self, name, *args)
Description
Specifies the data points of element name to be drawn using active foreground and background colors. Name is the name of the element and args is a tuple of numbers representing the indexes of the data points. If no indices are present then all data points become active.
See also
element_deactivate(...), HelloElements.py
3.2. element_bind(...)
Synopsis
def element_bind(self, tagName, sequence = None, func = None, add = None)
Description
Associates function func with tagName such that whenever the event sequence given by sequence occurs for an element with this tag, func will be invoked. The syntax is similar to the bind command except that it operates on graph elements, rather than widgets. See the bind manual entry for complete details on sequence and the substitutions performed on func before invoking it.
If all arguments are specified, then a new binding is created, replacing any existing binding for the same sequence and tagName. If add=1 then command augments an existing binding rather than replacing it. If no func argument is provided then the function currently associated with tagName and sequence (an error occurs if there's no such binding) is returned. If both func and sequence are missing then a tuple of all the event sequences for which bindings have been defined for tagName are returned.
See also
element_unbind(...), HelloWaves.py
3.3. element_unbind(...)
Synopsis
def element_unbind(self, tagName, sequence, funcid = None)
Description
Unbinds functions previously bound to the tag tagName and event given by sequence.
See also
element_bind(...), HelloWaves.py
3.4. element_cget(...)
Synopsis
def element_cget(self, name, key)
Description
Returns the current value of the element configuration option given by key for element name. Key may be any of the options described below for the element_configure(...) method.
See also
element_configure(...), HelloElements.py
3.5. element_closest(...)
Synopsis
def element_closest(self, x, y, *args, **kw)
Description
Finds the data point closest to the window coordinates x and y among the elements specified by args. All elements in args must be visible. If no elements are specified, then all visible elements are searched. It returns the name of the closest element, the index of its closest point, and the graph coordinates of the point in a dictionary with the following keys: 'dist', 'x', 'y', 'index', 'name'. If no data point within the threshold distance can be found, None is returned. The following option-value pairs are legal.
- halo = halo
Specifies a threshold distance where selected data points are ignored. Halo is a valid screen distance, such as 2 or "1.2i". If this option isn't specified, then it defaults to the value of the graph's halo option. - interpolate = 0
Indicates that both the data points and interpolated points along the line segment formed should be considered. If interpolate is true, the closest line segment will be selected instead of the closest point. Interpolate can also be set to "x" or "y" to perform a vertical or horisontal search only.
See also
3.6. element_configure(...)
Synopsis
def element_configure(self, names, option = None, **kw)
Description
Queries or modifies the configuration options for elements. Several elements can be modified at the same time. If option=None, a tuple describing all the current options for names is returned. If option is specified, then a tuple describing the option option is returned. If one or more option and value pairs are specified, then for each pair, the element option is set to value. The following options are valid for elements:
- activepen = "activeLine":
Specifies pen to use to draw active element. If activepen is "", no active elements will be drawn. (Unix: when I tested under Unix, active elements were drawn both with the current pen and the active pen. If you draw symbols with both pens, both symbols are drawn, but the symbol for activeLine is drawn on top of the default symbol. - bindtags = "all":
Specifies the binding tags for the element. Bindtags is a tuple of binding tag names. The tags and their order will determine how events occur for elements. Each tag in the tuple matching the current event sequence will have its function executed. Implicitly the name of the element is always the first tag in the tuple. - color = "black":
Sets the color of the traces connecting the data points. (Windows 98: color = "#000080") - dashes = ""
Sets the dash style of element line. Dashes is a tuple of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the element line. Each number must be between 1 and 255. If dashes is "", the lines will be solid. (Windows 98: This option does not seem to work as specified. As far as I can see, dashes is a boolean where 0 means solid and all other values means dashed. Under Unix it works as specified. Under Unix, it works as specified.) - data = Null:
Specifies the X-Y coordinates of the data. Data is a tuple of numeric expressions representing the X-Y coordinate pairs of each data point. - fill = "defcolor":
Sets the interior color of symbols. If fill is "", then the interior of the symbol is transparent. If fill is "defcolor", then the color will be the same as the color option. - hide = 0:
Indicates whether the element is displayed. - label = name:
Sets the element's label in the legend. If label is "", the element will have no entry in the legend. The default label is the element's name. - labelrelief = "flat"
Specifies which relief to use on the label. Typical values are "raised", "sunken" and "flat". - linewidth = 0:
Sets the width of the connecting lines between data points. If linewidth is 0, no connecting lines will be drawn between symbols. (Windows 98: linewidth = 1) - mapx = "x":
Selects the X-axis to map the element's X-coordinates onto. Mapx must be the name of an existing axis. - mapy = "y":
Selects the Y-axis to map the element's Y-coordinates onto. Mapy must be the name of an existing axis. - offdash = "defcolor":
Sets the color of the stripes when traces are dashed (see the dashes option). If offdash is "", then the "off" pixels will represent gaps instead of stripes. If offdash is defcolor, then the color will be the same as the color option. (Windows 98: This option does not seem to work under Windows 98. Also: offdash = "") - outline = "defcolor":
Sets the color or the outline around each symbol. If outline is "", then no outline is drawn. If outline is defcolor, then the color will be the same as the color option. - outlinewidth = 1:
Sets the width of the outline bordering each symbol. If outlinewidth is 0, no outline will be drawn. The default is 1. - pen = ""
Sets the pen to use. This will override all other options related to line-drawing such as colors, line thickness and symbols. If pen is "" the other options decide the look of the graph. - pixels = "0.125i":
Sets the size of symbols. If pixels is 0, no symbols will be drawn. - scalesymbols = 0:
If scalesymbols is true, the size of the symbols drawn for elemName will change with scale of the X-axis and Y-axis. At the time this option is set, the current ranges of the axes are saved as the normalized scales (i.e scale factor is 1.0) and the element is drawn at its designated size (see the pixels option). As the scale of the axes change, the symbol will be scaled according to the smaller of the X-axis and Y-axis scales. If scalesymbols is false, the element's symbols are drawn at the designated size, regardless of axis scales. - smooth = "linear":
Specifies how connecting line segments are drawn between data points. Smooth can be either "linear", "step", "quadratic", or "natural". If smooth is "linear", a single line segment is drawn, connecting both data points. When smooth is "step", two line segments are drawn. The first is a horizontal line segment that steps the next X-coordinate. The second is a vertical line, moving to the next Y-coordinate. Both natural and quadratic generate multiple segments between data points. If natural, the segments are generated using a cubic spline. If quadratic, a quadratic spline is used. - styles = None:
Specifies what pen to use based on the range of weights given. Styles is a tuple of style specifications. Each style specification, in turn, is a tuple consisting of a pen name, and optionally a minimum and maximum range. Data points whose weight (see the weight option) falls in this range, are drawn with this pen. If no range is specified it defaults to (index-1.0, index) where index is the index of the pen in the tuple. Note that this affects only symbol attributes. Line attributes, such as line width, dashes, etc. are ignored. - symbol = "circle":
Specifies the symbol for data points. Symbol can be either "square", "circle", "diamond", "plus", "cross", "splus", "scross", "triangle", "" (where no symbol is drawn), or a bitmap. Bitmaps are specified as "source mask", where source is the name of the bitmap, and mask is the bitmap's optional mask. - trace = "both":
Indicates whether connecting lines between data points (whose X-coordinate values are either increasing or decreasing) are drawn. Trace must be "increasing", "decreasing", or "both". For example, if trace is "increasing", connecting lines will be drawn only between those data points where X-coordinate values are monotonically increasing. If trace is "both", connecting lines will be drawn between all data points. - weights = None:
Specifies the weights of the individual data points. This, with the tuple pen styles (see the styles option), controls how data points are drawn. Weights is the name of a BLT vector or a tuple of numeric expressions representing the weights for each data point. - xdata = None:
Specifies the X-coordinates of the data. Xdata is the name of a BLT vector or a tuple of numeric expressions. - ydata = None:
Specifies the Y-coordinates of the data. Ydata is the name of a BLT vector or a tuple of numeric expressions.
See also
line_create(...), HelloBLT.py, HelloUser.py
3.7. element_deactivate(...)
Synopsis
def element_deactivate(self, *args)
Description
Deactivates all the elements matching patterns specified in args. Elements whose names match any of the patterns given are redrawn using their normal colors.
See also
element_activate(...), HelloElements.py
3.8. element_delete(...)
Synopsis
def element_delete(self, *args)
Description
Deletes all the named elements. The graph is automatically redrawn.
See also
line_create(...), HelloElements.py
3.9. element_exists(...)
Synopsis
def element_exists(self, name)
Description
Returns 1 if an element named name currently exists and 0 otherwise.
See also
element_names(...), HelloElements.py
3.10. element_names(...)
Synopsis
def element_names(self, *args)
Description
Returns the names of all elements matching one or more pattern. If no pattern is given, the names of all elements are returned.
See also
element_exists(...), HelloElements.py
3.11. element_show(...)
Synopsis
def element_show(self, nameList=None)
Description
Queries or modifies the element display list. The element display list designates the elements drawn and in what order. NameList is a tuple of elements to be displayed in the order they are named. If there is no nameList argument, the current display list is returned.
See also
3.12. element_type(...)
Synopsis
def element_type(self, name)
Description
Returns the type of element named name. If the element is a bar element, the method returns the string "bar", otherwise it returns "line".
See also
element_names(...), element_exists(...), HelloElements.py
4. Axes
Four coordinate axes are automatically created: two X-coordinate axes (x and x2 ) and two Y-coordinate axes (y and y2 ). By default, the axis x is located in the bottom margin, y in the left margin, x2 in the top margin, and y2 in the right margin.
An axis consists of the axis line, title, major and minor ticks, and tick labels. Major ticks are drawn at uniform intervals along the axis. Each tick is labeled with its coordinate value. Minor ticks are drawn at uniform intervals within major ticks.
The range of the axis controls what region of data is plotted. Data points outside the minimum and maximum limits of the axis are not plotted. By default, the minimum and maximum limits are determined from the data, but you can reset either limit.
You can create and use several axes. To create an axis, invoke the axis_create(...) method.
4.1. axis_cget(...)
Synopsis
def axis_cget(self, axisName, key):
Description
Returns the current value of the option given by key for axisName. Key may be any option described below for the axis_configure(...) method.
Note: To operate on a standard axis you may alternatively use:
def xaxis_cget(self, key) def yaxis_cget(self, key) def x2axis_cget(self, key) def y2axis_cget(self, key)
See also
axis_configure(...), HelloAxes.py
4.2. axis_configure(...)
Synopsis
def axis_configure(self, axes, option = None, **kw):
Description
Queries or modifies the configuration options of axisName. Several axes can be changed. If option=None, a tuple describing all the current options for axisName is returned. If option is specified, the value of the specified option is returned. If one or more option and value pairs are specified, then for each pair, the axis option option is set to value. The following options are valid for axes:
- autorange = 0.0
Sets the range of values for the axis to autorange. The axis limits are automatically reset to display the most recent data points in this range. If autorange is 0.0, the range is determined from the limits of the data. If the options min or max are specified, they override this option. (Note: in older versions this option was called "range" rather than "autorange". In Windows 98, however, neither of these options exist.) - color = "black"
Sets the color of the axis and tick labels. - command = ""
Specifies a command to be invoked when formatting the axis tick labels. Command is a string containing the name of a function and any extra arguments for the function. This command is invoked for each major tick on the axis. Two additional arguments are passed to the function: the pathname of the widget and the current numeric value of the tick. The function returns the formatted tick label. If "" is returned, no label will appear next to the tick. You can get the standard tick labels again by setting command to "". Please note that this function is invoked while the graph is redrawn. You may query configuration options. But do not alter them, because this can have unexpected results. - descending = 0
Indicates whether the values along the axis are monotonically increasing or decreasing. If descending is true, the axis values will be decreasing. - hide = 0:
Indicates if the axis and all the elements mapped to it will be displayed. The valid values for hide are 0, 1 and "all" where 0 and 1 means show and hide the axis, and "all" means hide both the axis and all graphs mapped to it. (Note: hide="all" does not seem work.) - justify = "center"
Specifies how the axis title should be justified. This matters only when the axis title contains more than one line of text. Justify must be "left", "right", or "center". - limitsformat = ""
Specifies a printf-like description to format the minimum and maximum limits of the axis. Example: limitsformat = "%4.2fcm" will result in maxlabel "3.30cm" if max limit is 3.3. The limits are displayed at the top/bottom or left/right sides of the plotting area. Limitsformat is a tuple of one or two format descriptions. If one description is supplied, both the minimum and maximum limits are formatted in the same way. If two, the first designates the format for the minimum limit, the second for the maximum. If "" is given as either description, then that limit will not be displayed. (Note: in older versions this option was called "limits" only. This change is not backward compatible as far as I can see.) - limitscolor = "black"
Specifies the color of the limits (see option limitsformat). - limitsfont = "Arial Narrow 8"
Specifies the font to use for the limits (see option limitsformat). - limitsshadow = ""
Specifies the color to use as shadow for the limitstext. If limitsshadow is "" no shadow will be drawn. - linewidth = 1
Sets the width of the axis and tick lines. - logscale = 0
Indicates whether the scale of the axis is logarithmic or linear. If logscale is true, the axis is logarithmic. The default scale is linear. - loose = 0:
Indicates whether the limits of the axis should fit the data points tightly, at the outermost data points, or loosely, at the outer tick intervals. This is relevant only when the axis limit is automatically calculated. If loose is true, the axis range is "loose". - majorticks = ""
Specifies where to display major axis ticks. You can use this option to display ticks at non-uniform intervals. Majorticks is a tuple of axis coordinates designating the location of major ticks. No minor ticks are drawn. If majorticks is "", major ticks will be automatically computed. - max = "":
Sets the maximum limit of axisName. Any data point greater than max is not displayed. If max is "", the maximum limit is calculated using the largest data value. - min = ""
Sets the minimum limit of axisName. Any data point less than min is not displayed. If min is "", the minimum limit is calculated using the smallest data value. - minorticks = ""
Specifies where to display minor axis ticks. You can use this option to display minor ticks at non-uniform intervals. Minorticks is a tuple of real values, ranging from 0.0 to 1.0, designating the placement of a minor tick. No minor ticks are drawn if the majortick option is also set. If minorticks is "", minor ticks will be automatically computed. - rotate = 0.0
Specifies how many degrees to rotate the axis tick labels. rotate is a real value representing the number of degrees to rotate the tick labels. - showticks = 1
Indicates whether axis ticks should be drawn. If showticks is true, ticks are drawn. If false, only the axis line is drawn. - stepsize = 0.0
Specifies the interval between major axis ticks. If stepsize isn't a valid interval (must be less than the axis range), the request is ignored and the step size is automatically calculated. - subdivisions = 2
Indicates how many minor axis ticks are to be drawn. For example, if subdivisions is two, only one minor tick is drawn. If subdivisions is one, no minor ticks are displayed. - tickfont = "*-Courier-Bold-R-Normal-*-100-*"
Specifies the font for axis tick labels. (Windows 98: tickfont = "Arial Narrow 8") - ticklength = "0.1i"
Sets the length of major and minor ticks (minor ticks are half the length of major ticks). If ticklength is less than zero, the axis will be inverted with ticks drawn pointing towards the plot. - tickshadow = ""
Specifies the color to use to draw shadows beneath the ticks. If tickshadow is "", no shadows will be drawn. - title = ""
Sets the title of the axis. If title is "", no axis title will be displayed. - titlecolor = "black"
Sets the color of the axis title. - titlefont = "*-Helvetica-Bold-R-Normal-*-14-140-*"
Specifies the font for axis title. (Windows 98: titlefont = "Arial 8") - titleshadow = ""
Specifies the color to use as shadow for the title. If titleshadow is "", no shadow will be drawn.
Note: To operate on a standard axis you may also use:
def xaxis_configure(self, option = None, **kw) def yaxis_configure(self, option = None, **kw) def x2axis_configure(self, option = None, **kw) def y2axis_configure(self, option = None, **kw)
See also
4.3. axis_create(...)
Synopsis
def axis_create(self, axisName, **kw)
Description
Creates a new axis by the name axisName. No axis with the same name can already exist. If additional arguments are present, they specify options valid for the axis_configure(...) method.
See also
axis_configure(...), HelloAxes.py
4.4. axis_delete(...)
Synopsis
def axis_delete(self, *args)
Description
Deletes the named axes (stored in args). An axis is not really deleted until it is not longer in use, so it's safe to delete axes mapped to elements.
See also
axis_create(...), HelloAxes.py
4.5. axis_invtransform(...)
Synopsis
def axis_invtransform(self, axisName, value)
Description
Performs the inverse transformation, changing the screen coordinate value to a graph coordinate, mapping the value mapped to axisName. Returns the graph coordinate.
Be aware that this method does not function properly before the mainloop(...) method is entered because the widget is not yet drawn.
Note: To operate on a standard axis you may also use:
def xaxis_invtransform(self, value) def yaxis_invtransform(self, value) def x2axis_invtransform(self, value) def y2axis_invtransform(self, value)
See also
axis_transform(...), invtransform(...), HelloAxes.py
4.6. axis_limits(...)
Synopsis
def axis_limits(self, axisName)
Description
Returns a tuple of the minimum and maximum limits for axisName. The order of the tuple is (min, max).
Note: To operate on a standard axis, you may also use:
def xaxis_limits(self) def yaxis_limits(self) def x2axis_limits(self) def y2axis_limits(self)
See also
axis_configure(...), HelloAxes.py
4.7. axis_names(...)
Synopsis
def axis_names(self, *args)
Description
Returns a tuple of axes matching zero or more patterns (stored in args). If no pattern argument is given, the names of all axes are returned.
See also
axis_configure(...), HelloAxes.py
4.8. axis_transform(...)
Synopsis
def axis_transform(self, axisName, value)
Description
Transforms the coordinate value to a screen coordinate by mapping it to axisName. Returns the transformed screen coordinate.
Be aware that this method does not function properly before the mainloop(...) method is entered because the widget is not yet drawn.
Note: To operate on a standard axis you may also use:
def xaxis_transform(self, value) def yaxis_transform(self, value) def x2axis_transform(self, value) def y2axis_transform(self, value)
See also
axis_invtransform(...), transform(...), HelloAxes.py
4.9. xaxis_use(...)
Synopsis
def xaxis_use(self, axisName = None)
Description
Designates the axis axisName to be displayed as the xaxis. AxisName is not allowed to be in use at two locations at the same time. This method returns the name of the axis currently using this location.
See also
axis_create(...), yaxis_use(...), HelloAxes.py
4.10. yaxis_use(...)
Synopsis
def yaxis_use(self, axisName = None)
Description
Designates the axis axisName to be displayed as the yaxis. AxisName is not allowed to be in use at two locations at the same time. This method returns the name of the axis currently using this location.
See also
axis_create(...), xaxis_use(...), HelloAxes.py
4.11. x2axis_use(...)
Synopsis
def x2axis_use(self, axisName = None)
Description
Designates the axis axisName to be displayed as the second x-axis. AxisName is not allowed to be in use at two locations at the same time. This method returns the name of the axis currently using this location.
See also
axis_create(...), xaxis_use(...), HelloAxes.py
4.12. y2axis_use(...)
Synopsis
def y2axis_use(self, axisName = None)
Description
Designates the axis axisName to be displayed as the second y-axis. AxisName is not allowed to be in use at two locations at the same time. This method returns the name of the axis currently using this location.
See also
axis_create(...), yaxis_use(...), HelloAxes.py
5. Grids
Grid lines extend from the major and minor ticks of each axis horizontally or vertically across the plotting area. The following methods are available for grid lines.
5.1. grid_cget(...)
Synopsis
def grid_cget(self, key)
Description
Returns the current value of the grid line configuration option given by key. Key may be any option described below for the grid_configure(...) method.
See also
grid_configure(...), HelloUser.py, HelloGrid.py
5.2. grid_configure(...)
Synopsis
def grid_configure(self, option = None, **kw)
Description
Queries or modifies the configuration options for grid lines. If option=None, a tuple describing all the current grid options for pathName is returned. If option is specified, a tuple describing option is returned. If one or more option and value pairs are specified, then for each pair, the grid line option option is set to value. The following options are valid for grid lines:
- color = "black"
Sets the color of the grid lines. (Windows 98: color="#a3a3a3" ) - dashes = ""
Sets the dash style of the grid lines. Dashes is a tuple of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the grid lines. Each number must be between 1 and 255. If dashes is "", the grid will be solid lines. (Windows 98: This option does not seem to function as specified. It seems that dashes=0 means solid, while dashes > 0 means dashed with length of dashes and gaps equal to dashes. Also dashes defaults to 1. Under Unix it works as specified.) - hide = 1
Indicates whether the grid should be drawn. If hide is true, grid lines are not shown. - linewidth = 1
Sets the width of grid lines. (Windows 98: linewidth = 0, but acts as if linewidth=1!) - mapx = ""
Specifies the X-axis to display grid lines. mapx must be the name of an axis or "" for no grid lines. (Windows 98: mapx = "x"). - mapy = "y"
Specifies the Y-axis to display grid lines. mapy must be the name of an axis or "" for no grid lines. - minor = 1
Indicates whether the grid lines should be drawn for minor ticks. If minor is true, the lines will appear at minor tick intervals.
See also
grid_cget(...), grid_on(...), HelloUser.py
5.3. grid_off(...)
Synopsis
def grid_off(self)
Description
Turns off the grid lines.
See also
grid_configure(...), HelloUser.py, HelloGrid.py
5.4. grid_on(...)
Synopsis
def grid_on(self)
Description
Turns on the grid lines.
See also
grid_configure(...), HelloUser.py, HelloGrid.py
5.5. grid_toggle(...)
Synopsis
def grid_toggle(self)
Description
Toggles the display of the grid.
See also
grid_configure(...), HelloUser.py, HelloGrid.py
6. Legends
The legend displays a list of the data elements. Each entry consists of the element's symbol and label. The legend can appear in any margin (the default location is in the right margin). It can also be positioned anywhere within the plotting area.
The following methods are valid for the legend.
6.1. legend_activate(...)
Synopsis
def legend_activate(self, *args)
Description
Selects legend entries to be drawn using the active legend colors and relief. All entries whose element names match a pattern specified in args are selected. To be selected, the element name must match at least one pattern.
See also
legend_deactivate(...), HelloLegends.py
6.2. legend_bind(...)
Synopsis
def legend_bind(self, tagName, sequence = None, func = None, add = None)
Description
Associates func with tagName such that whenever the event sequence given by sequence occurs for a legend entry with this tag, func will be invoked. Implicitly the element names in the entry are tags. The syntax is similar to the bind command except that it operates on legend entries, rather than widgets. See the bind manual entry for complete details on sequence and the substitutions performed on command before invoking it.
If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName. If add=1 then func augments an existing binding rather than replacing it. If no func argument is provided then the command currently associated with tagName and sequence (an error occurs if there's no such binding) is returned. If both command and sequence are missing then a tuple of all the event sequences for which bindings have been defined for tagName are returned.
See also
legend_unbind(...), HelloLegends.py
6.3. legend_unbind(...)
Synopsis
def legend_unbind(self, tagName, sequence, funcid = None)
Description
Unbinds functions previously bound to the tag named tagName and event given by sequence.
See also
legend_bind(...), HelloLegends.py
6.4. legend_cget(...)
Synopsis
def legend_cget(self, key)
Description
Returns the current value of a legend configuration option. Key may be any option described below in the legend_configure(...) method.
See also
legend_configure(...), HelloUser.py
6.5. legend_configure(...)
Synopsis
def legend_configure(self, option = None, **kw)
Description
Queries or modifies the configuration options for the legend. If option=None, a tuple describing the current legend options for the graph is returned. If option is specified, then a tuple describing option is returned. If one or more option and value pairs are specified, then for each pair, the legend option option is set to value. The following options are valid for the legend:
- activebackground = "gray"
Sets the background color for active legend entries. All legend entries marked active (see the legend_activate(...) method) are drawn using this background color. (Windows 98: activebackground = "#a3a3a3") - activeborderwidth = 2
Sets the width of the 3-D border around the outside edge of the active legend entries. (Note: This option does not seem to work.) - activeforeground = "black"
Sets the foreground color for active legend entries. All legend entries marked as active (see the legend_activate(...) method) are drawn using this foreground color. - activerelief = "flat"
Specifies the 3-D effect desired for active legend entries. Relief denotes how the interior of the entry should appear relative to the legend; for example, raised means the entry should appear to protrude from the legend, relative to the surface of the legend. Typical values are "raised", "sunken" and "flat". (Note: This option does not seem to work.) - anchor = "n"
Tells how to position the legend relative to the positioning point for the legend. Legal values are "n", "ne", "e", "se", "s", "sw", "w", "nw" and "center". Use the position option to set the positioning point. - background = ""
Sets the background color of the legend. If background is "", the legend background will be transparent. - bindtags = "all"
Specifies the binding tags for legend entries. Bindtags is a tuple of binding tag names. The tags and their order will determine how events occur for legend entries. Each tag in the tuple matching the current event sequence will have its function executed. - borderwidth = 2
Sets the width of the 3-D border around the outside edge of the legend (if such border is being drawn; the relief option determines this). - font = "*-Helvetica-Bold-R-Normal-*-12-120-*"
Font specifies a font to use when drawing the labels of each element into the legend. (Windows 98: font = "Arial 6") - foreground = "black":
Sets the foreground color of the text drawn for the element's label. (Windows 98: foreground = "SystemButtonText") - hide = 0
Indicates whether the legend should be displayed. If hide is true, the legend will not be drawn. - ipadx = 2
Sets the amount of internal padding to be added to the width of each legend entry. Ipadx can be a tuple of one or two screen distances. If ipadx has two elements, the left side of the legend entry is padded by the first distance and the right side by the second. If ipadx is just one distance, both the left and right sides are padded evenly. (Windows 98: ipadx = 1) - ipady = 2
Sets an amount of internal padding to be added to the height of each legend entry. Ipady can be a tuple of one or two screen distances. If ipady has two elements, the top of the entry is padded by the first distance and the bottom by the second. If ipady is just one distance, both the top and bottom of the entry are padded evenly. (Windows 98: ipady = 1) - padx = 4
Sets the padding to the left and right exteriors of the legend. Padx can be a tuple of one or two screen distances. If padx has two elements, the left side of the legend is padded by the first distance and the right side by the second. If padx has just one distance, both the left and right sides are padded evenly. (Windows 98: padx = 4) - pady = 0
Sets the padding above and below the legend. Pady can be a tuple of one or two screen distances. If pady has two elements, the area above the legend is padded by the first distance and the area below by the second. If pady is just one distance, both the top and bottom areas are padded evenly. (Windows 98: pady = 1) - position = "right"
Specifies where the legend is drawn. The anchor option also affects where the legend is positioned. If position is "left", "right", "top", or "bottom", the legend is drawn in the specified margin. If pos is "plotarea", then the legend is drawn inside the plotting area at a particular anchor. If pos is in the form "@x,y", where x and y are the window coordinates, the legend is drawn in the plotting area at the specified coordinates. See also option anchor. (Windows 98: position = "rightmargin". Legal values are "leftmargin", "rightmargin", "topmargin", "bottommargin", "plotarea" and "@x,y". You can also use "right", "left" and so on.) - raised = 0
Indicates whether the legend is above or below the data elements. This matters only if the legend is in the plotting area. If raised is true, the legend will be drawn on top of any elements that may overlap it. - relief = "sunken"
Specifies the 3-D effect for the border around the legend. Relief specifies how the interior of the legend should appear relative to the graph; for example, relief="raised" means the legend should appear to protrude from the graph, relative to the surface of the graph. Typical options are "sunken", "raised" and "flat". - shadow = ""
Specifies the color to use to shadow the text in the legend. If shadow is "", no shadow will be drawn.
See also
legend_cget(...), HelloUser.py, HelloLegends.py
6.6. legend_deactivate(...)
Synopsis
def legend_deactivate(self, *args)
Description
Selects legend entries to be drawn using the normal legend colors and relief. All entries whose element names match a pattern in args are selected. To be selected, the element name must match at least one pattern.
See also
legend_activate(...), HelloLegends.py
6.7. legend_get(...)
Synopsis
def legend_get(self, pos)
Description
Returns the name of the element whose entry is at the screen position pos in the legend. Pos must be in the form "@x,y", where x and y are window coordinates. If the given coordinates do not lie over a legend entry, "" is returned.
See also
legend_bind(...), HelloLegends.py
7. Crosshairs
Cross hairs consist of two intersecting lines (one vertical and one horizontal) drawn completely across the plotting area. They are normally used to position the mouse in relation to the coordinate axes. Cross hairs differ from line markers in that they are implemented using XOR drawing primitives. This means that they can be quickly drawn and erased without redrawing the entire graph.
The following methods are available for cross hairs:
7.1. crosshairs_cget(...)
Synopsis
def crosshairs_cget(self, key)
Description
Returns the current value of the cross hairs configuration option given by option. Key may be any option described below for the crosshairs_configure(...) method.
See also
crosshairs_configure(...), HelloCrosshairs.py
7.2. crosshairs_configure(...)
Synopsis
def crosshairs_configure(self, option = None, **kw)
Description
Queries or modifies the configuration options of the cross hairs. If option=Null, a tuple describing all the current options for the cross hairs is returned. If option is specified, the value of the specified option is returned. If one or more option and value pairs are specified, then for each pair, the cross hairs option option is set to value. The following options are available for cross hairs.
- color = "black"
Sets the color of the cross hairs. - dashes = ""
Sets the dash style of the cross hairs. Dashes is a tuple of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the cross hair lines. Each number must be between 1 and 255. If dashes is "", the cross hairs will be solid lines. (Windows 98: This option does not seem to function as specified. It seems that dashes=0 means solid, while dashes > 0 means dashed with length of dashes and gaps equal to dashes. Under Unix it works as specified.) - hide = 1
Indicates whether cross hairs are drawn. If hide is true, cross hairs are not drawn. - linewidth = 1
Set the width of the cross hair lines. (Windows 98: linewidth = 0, but acts as if linewidth = 1). - position = "@-1,-1"
Specifies the screen position where the cross hairs intersect. Postion must be in the form "@x,y", where x and y are the window coordinates of the intersection.
See also
HelloUser.py, HelloCrosshairs.py
7.3. crosshairs_off(...)
Synopsis
def crosshairs_off(self)
Description
Turns off the cross hairs.
See also
crosshairs_on(...), crosshairs_toggle(...), HelloCrosshairs.py
7.4. crosshairs_on(...)
Synopsis
def crosshairs_on(self)
Description
Makes the cross hairs visible.
See also
crosshairs_off(...), crosshairs_toggle(...), HelloCrosshairs.py
7.5. crosshairs_toggle(...)
Synopsis
def crosshairs_toggle(self)
Description
Toggles the current state of the cross hairs, alternately mapping and unmapping the cross hairs.
See also
crosshairs_on(...), crosshairs_toggle(...), HelloCrosshairs.py
8. Pens
Pens define attributes (both symbol and line style) for elements. Pens mirror the configuration options of data elements that pertain to how symbols and lines are drawn. Data elements use pens to determine how they are drawn. A data element may use several pens at once. In this case, the pen used for a particular data point is determined from each element's weight vector (see the element's weight and style options).
One pen, called activeLine, is automatically created. It's used as the default active pen for elements. So you can change the active attributes for all elements by simply reconfiguring this pen.
8.1. pen_cget(...)
Synopsis
def pen_cget(self, name, key)
Description
Returns the current value of the option given by key for the pen named name. Option may be any option described below for the pen_configure(...) method.
See also
pen_configure(...), HelloPens.py
8.2. pen_configure(...)
Synopsis
def pen_configure(self, names, option = None, **kw)
Description
Queries or modifies the configuration options of pens listed in names. Several pens can be modified at once. If option=None, a tuple describing the current options for names is returned. If option is specified, a tuple describing option is returned. If one or more option and value pairs are specified, then for each pair, the pen option is set to value. The following options are valid for pens.
- color = "black"
Sets the color of the traces connecting the data points. (Windows 98: color = "#000080") - dashes = ""
Sets the dash style of element line. Dashes is a tuple of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the element line. Each number must be between 1 and 255. If dashes is "", the lines will be solid. (Windows 98: This option does not seem to function as specified. It seems that dashes=0 means solid, while dashes > 0 means dashed with length of dashes and gaps equal to dashes. Under Unix it works as specified.) - fill = "defcolor"
Sets the interior color of symbols. If fill is "", then the interior of the symbol is transparent. If fill is "defcolor", then the color will be the same as the color option. - linewidth = 0
Sets the width of the connecting lines between data points. If linewidth is 0, no connecting lines will be drawn between symbols. (Windows 98: linewidth = 1) - offdash = "defcolor"
Sets the color of the stripes when traces are dashed (see the dashes option). If offdash is "", then the "off" pixels will represent gaps instead of stripes. If offdash = "defcolor", then the color will be the same as the color option. (Windows 98: offdash="") (Note: I could not get this option to function under Windows 98.) - outline = "defcolor"
Sets the color or the outline around each symbol. If outline is "", then no outline is drawn. If outline = "defcolor", then the color will be the same as the color option. - outlinewidth = 1
Sets the width of the outline bordering each symbol. If outlinewidth is 0, no outline will be drawn. - pixels = "0.125i"
Sets the size of symbols. If pixels is 0, no symbols will be drawn. - symbol = "circle"
Specifies the symbol for data points. Symbol can be either "square", "circle", "diamond", "plus", "cross", "splus", "scross", "triangle", "" (where no symbol is drawn), or a bitmap. Bitmaps are specified as "source mask", where source is the name of the bitmap, and mask is the bitmap's optional mask. - type = "line"
Specifies the type of element the pen is to be used with. This option should only be employed when creating the pen. This is for those that wish to mix different types of elements (bars and lines) on the same graph. Valid values are "line" and "bar".
See also
8.3. pen_create(...)
Synopsis
def pen_create(self, name, **kw)
Description
Creates a new pen named name. You can not have two pens with the same name. If additional arguments are present, they specify options valid for the pen_configure(...) method.
See also
pen_configure(...), pen_delete(...), HelloWeights.py
8.4. pen_delete(...)
Synopsis
def pen_delete(self, *args)
Description
Deletes the named pens listed in args. A pen is not really deleted until it is not longer in use, so it's safe to delete pens mapped to elements.
See also
8.5. pen_names(...)
Synopsis
def pen_names(self, *args)
Description
Returns a tuple of pens matching zero or more patterns listed in args. If no pattern argument is given, the names of all pens are returned.
See also
pen_configure(...), HelloPens.py
9. Postscript
The graph can generate encapsulated PostScript output. There are several configuration options you can specify to control how the plot will be generated. You can change the page dimensions and borders. The plot itself can be scaled, centered, or rotated to landscape. The PostScript output can be written directly to a file or returned through the interpreter.
The following postscript methods are available:
9.1. postscript_cget(...)
Synopsis
def postscript_cget(self, key)
Description
Returns the current value of the postscript option given by key. Key may be any option described below for the postscript_configure(...) method.
See also
postscript_configure(...), HelloPostscript.py
9.2. postscript_configure(...)
Synopsis
def postscript_configure(self, option = None, **kw)
Description
Queries or modifies the configuration options for PostScript generation. If option = None, a tuple describing the current postscript options for the graph is returned. If option is specified, then a tuple describing option is returned. If one or more option and value pairs are specified, then for each pair, the postscript option option is set to value. The following postscript options are available:
- center = 1
Indicates whether the plot should be centered on the PostScript page. If center is false, the plot will be placed in the upper left corner of the page. - colormap = None
Colormap must be a global array variable that specifies a color mapping from the X color name to PostScript. Each element of colormap must consist of PostScript code to set a particular color value (e.g. ``1.0 1.0 0.0 setrgbcolor ''). When generating color information in PostScript, the array variable colormap is checked if an element of the name as the color exists. If so, it uses its value as the PostScript command to set the color. If this option hasn't been specified, or if there isn't an entry in colormap for a given color, then it uses the red, green, and blue intensities from the X color. (Note: this option has not been tested from Python.) - colormode = "color"
Specifies how to output color information. Colormode must be either "color" (for full color output), "gray" (convert all colors to their gray-scale equivalents) or "mono" (convert foreground colors to black and background colors to white). - fontmap = None
Fontmap must be the name of a global array variable that specifies a font mapping from the X font name to PostScript. Each element of fontmap must consist of a Tcl list with one or two elements; the name and point size of a PostScript font. When outputting PostScript commands for a particular font, the array variable fontmap is checked to see if an element by the specified font exists. If there is such an element, then the font information contained in that element is used in the PostScript output. (If the point size is omitted from the list, the point size of the X font is used). Otherwise the X font is examined in an attempt to guess what PostScript font to use. This works only for fonts whose foundry property is Adobe (such as Times, Helvetica, Courier, etc.). If all of this fails then the font defaults to Helvetica-Bold. (Note: this option has not been tested from Python.) - decorations = 1
Indicates whether PostScript commands to generate color backgrounds and 3-D borders will be output. If decorations is false, the background will be white and no 3-D borders will be generated. - height = 0
Sets the height of the plot. This lets you print the graph with a height different from the one drawn on the screen. If height is 0, the height is the same as the widget's height. - landscape = 0
If landscape is true, this specifies the printed area is to be rotated 90 degrees. In non-rotated output the X-axis of the printed area runs along the short dimension of the page (``portrait'' orientation); in rotated output the X-axis runs along the long dimension of the page (``landscape'' orientation). - maxpect = 0
Indicates to scale the plot so that it fills the PostScript page. The aspect ratio of the graph is still retained. - padx = "1i"
Sets the horizontal padding for the left and right page borders. The borders are exterior to the plot. Padx can be a tuple of one or two screen distances. If padx has two elements, the left border is padded by the first distance and the right border by the second. If padx has just one distance, both the left and right borders are padded evenly. - pady = "1i"
Sets the vertical padding for the top and bottom page borders. The borders are exterior to the plot. Pady can be a tuple of one or two screen distances. If pady has two elements, the top border is padded by the first distance and the bottom border by the second. If pady has just one distance, both the top and bottom borders are padded evenly. - paperheight = "11.0i"
Sets the height of the postscript page. This can be used to select between different page sizes (letter, A4, etc). - paperwidth = "8.5i"
Sets the width of the postscript page. This can be used to select between different page sizes (letter, A4, etc). - width = 0
Sets the width of the plot. This lets you generate a plot of a width different from that of the widget. If width is 0, the width is the same as the widget's width.
See also
postscript_cget(...), HelloPostscript.py
9.3. postscript_output(...)
Synopsis
def postscript_output(self, fileName=None, **kw)
Description
Outputs a file of encapsulated PostScript. If a fileName argument isn't present, the method returns the PostScript. If any option-value pairs are present, they set configuration options controlling how the PostScript is generated. Option and value can be anything accepted by the postscript_configure(...) method above.
See also
HelloPostscript.py, HelloUser.py
10. Markers
Markers are simple drawing procedures used to annotate or highlight areas of the graph. Markers have various types: text strings, bitmaps, images, connected lines, windows, or polygons. They can be associated with a particular element, so that when the element is hidden or un-hidden, so is the marker. By default, markers are the last items drawn, so that data elements will appear in behind them. You can change this by configuring the under option.
Markers, in contrast to elements, don't affect the scaling of the coordinate axes. They can also have elastic coordinates (specified by "-Inf" and "Inf" respectively) that translate into the minimum or maximum limit of the axis. For example, you can place a marker so it always remains in the lower left corner of the plotting area, by using the coordinates ("-Inf", "-Inf").
The following methods are available for markers:
10.1. marker_after(...)
Synopsis
def marker_after(self, first, second = None)
Description
Changes the order of the markers, drawing the first marker after the second. If no argument second is specified, the marker is placed at the end of the display list. This method can be used to control how markers are displayed since markers are drawn in the order of this display list.
See also
marker_before(...), HelloMarkers.py
10.2. marker_before(...)
Synopsis
def marker_before(self, first, second = None)
Description
Changes the order of the markers, drawing the first marker before the second. If no argument second is specified, the marker is placed at the beginning of the display list. This method can be used to control how markers are displayed since markers are drawn in the order of this display list.
See also
marker_after(...), HelloMarkers.py
10.3. marker_bind(...)
Synopsis
def marker_bind(self, tagName, sequence = None, func = None, add = None)
Description
Associates func with tagName such that whenever the event sequence given by sequence occurs for a marker with this tag, func will be invoked. The syntax is similar to the bind command except that it operates on graph markers, rather than widgets. See the bind manual entry for complete details on sequence and the substitutions performed on func before invoking it.
If all arguments are specified, then a new binding is created, replacing any existing binding for the same sequence and tagName. If add = 1, func augments an existing binding rather than replacing it. If no command argument is provided then the command currently associated with tagName and sequence (an error occurs if there's no such binding) is returned. If both func and sequence are missing, a tuple of all the event sequences for which bindings have been defined for tagName is returned.
See also
marker_unbind(...), HelloMarkers.py
10.4. marker_unbind(...)
Synopsis
def marker_unbind(self, tagName, sequence, funcid = None)
Description
Unbinds functions previously bound to the tag named tagName and event given by sequence.
See also
marker_bind(...), HelloMarkers.py
10.5. marker_cget(...)
Synopsis
def marker_cget(self, name, key)
Description
Returns the current value of the marker configuration option given by key. Key may be any option described below in the marker_configure(...) method.
See also
marker_configure(...), HelloMarkers.py
10.6. marker_configure(...)
Synopsis
def marker_configure(self, names, option = None, **kw)
Description
Queries or modifies the configuration options for markers. If option = None, a tuple describing the current options for markers listed in names is returned. If option is specified, then a tuple describing option is returned. If one or more option and value pairs are specified, then for each pair, the marker option option is set to value.
The following options are valid for all markers. Each type of marker also has its own type-specific options. They are described in the sections below.
- bindtags = "all"
Specifies the binding tags for the marker. Bindtags is a tuple of binding tag names. The tags and their order will determine how events for markers are handled. Each tag in the tuple matching the current event sequence will have its Tcl command executed. Implicitly the name of the marker is always the first tag in the list. (Windows 98: bindtags = "[markertype] all") - coords = ""
Specifies the coordinates of the marker. Coords is a tuple of graph coordinates. The number of coordinates required is dependent on the type of marker. Text, image, and window markers need only two coordinates (an X-Y coordinate). Bitmap markers can take either two or four coordinates (if four, they represent the corners of the bitmap). Line markers need at least four coordinates, polygons at least six. If coords is "", the marker will not be displayed. - element = ""
Links the marker with the element given by element. The marker is drawn only if the element is also currently displayed (see the element_show(...) method). If element is "", the marker is always drawn. - hide = 0
Indicates whether the marker is drawn. If hide is true, the marker is not drawn. - mapx = "x"
Specifies the X-axis to map the marker's X-coordinates onto. Mapx must the name of an axis. - mapy = "y"
Specifies the Y-axis to map the marker's Y-coordinates onto. Mapy must the name of an axis. - name = None
Changes the identifier for the marker. The identifier name can not be an existing marker name. If this option isn't specified, the marker's name is uniquely generated. - under = 0
Indicates whether the marker is drawn below or above data elements. If under is true, the marker is drawn underneath the data element symbols and lines. Otherwise, the marker is drawn on top of the element. - xoffset = 0
Specifies a screen distance to offset the marker horizontally. Xoffset is a valid screen distance, such as 2 or "1.2i". - yoffset = 0
Specifies a screen distance to offset the markers vertically. Yoffset is a valid screen distance, such as 2 or "1.2i".
A bitmap marker displays a bitmap. The size of the bitmap is controlled by the number of coordinates specified. If two coordinates, they specify the position of the top-left corner of the bitmap. The bitmap retains its normal width and height. If four coordinates, the first and second pairs of coordinates represent the corners of the bitmap. The bitmap will be stretched or reduced as necessary to fit into the bounding rectangle.
The following options are specific to bitmap markers:
- anchor = "center"
Anchor tells how to position the bitmap relative to the positioning point for the bitmap. For example, if anchor is "center" then the bitmap is centered on the point; if anchor is "n" then the bitmap will be drawn such that the top center point of the rectangular region occupied by the bitmap will be at the positioning point. - background = ""
Same as the fill option. (Windows 98: background = "#ffffff" ) - bitmap = ""
Specifies the bitmap to be displayed. If bitmap is "", the marker will not be displayed. Some predefined bitmaps are "question", "questhead", "info" and "warning". - fill = ""
Sets the background color of the bitmap. If fill is the empty string, background will be transparent. (Windows 98: fill = "#ffffff" ) - foreground = "black"
Same as the outline option. - mask = ""
Specifies a mask for the bitmap to be displayed. This mask is a bitmap itself, denoting the pixels that are transparent. If mask is "", all pixels of the bitmap will be drawn. (Windows 98: this option does not exist) - outline = "black"
Sets the foreground color of the bitmap. - rotate = 0.0
Sets the rotation of the bitmap. Rotate is a real number representing the angle of rotation in degrees. The marker is first rotated and then placed according to its anchor position.
An image marker displays an image. The following options are specific to image markers:
- anchor = "center"
Anchor tells how to position the image relative to the positioning point for the image. For example, if anchor is "center" then the image is centered on the point; if anchor is "n" then the image will be drawn such that the top center point of the rectangular region occupied by the image will be at the positioning point. - image = ""
Specifies the image to be drawn. If image is "", the marker will not be drawn. The image should be an instance of the Tkinter.PhotoImage() class.
A line marker displays one or more connected line segments. The following options are specific to line markers:
- dashes = ""
Sets the dash style of the line. Dashes is a tuple of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the line. Each number must be between 1 and 255. If dashes is "", the marker line will be solid. (Windows 98: This option does not seem to function as specified. It seems that dashes=0 means solid, while dashes > 0 means dashed with length of dashes and gaps equal to dashes. Under Unix it works as specified.) - fill = ""
Sets the background color of the line. This color is used with striped lines (see the dashes option). If fill is the empty string, no background color is drawn (the line will be dashed, not striped). (Note: This option does not seem to function properly under Windows 98.) - linewidth = 0
Sets the width of the lines. - outline = "black"
Sets the foreground color of the line. - stipple = ""
Specifies a stipple pattern used to draw the line, rather than a solid line. Stipple specifies a bitmap to use as the stipple pattern. If stipple is "", then the line is drawn in a solid fashion. (Windows 98: this option does not exist) - xor = 0
If xor is true, the line will be draw using xor drawing methods. This is faster, but less pretty if the line crosses lots of different colors.
A polygon marker displays a closed region described as two or more connected line segments. It is assumed the first and last points are connected. The following options are supported for polygon markers:
- dashes = ""
Sets the dash style of the outline of the polygon. Dashes is a tuple of up to 11 numbers that alternately represent the lengths of the dashes and gaps on the outline. Each number must be between 1 and 255. If dashes is "", the outline will be a solid line. (Windows 98: This option does not seem to function as specified. It seems that dashes=0 means solid, while dashes > 0 means dashed with length of dashes and gaps equal to dashes. Under Unix it works as specified.) - fill = "white"
Sets the fill color of the polygon. If color is "", then the interior of the polygon is transparent. (Windows 98: fill = "#ff0000") - linewidth = 0
Sets the width of the outline of the polygon. If linewidth is zero, no outline is drawn. - outline = "black"
Sets the color of the outline of the polygon. If the polygon is stippled (see the stipple option), then this represents the foreground color of the stipple. - stipple = ""
Specifies that the polygon should be drawn with a stippled pattern rather than a solid color. Stipple specifies a bitmap to use as the stipple pattern. If stipple is "", then the polygon is filled with a solid color (if the fill option is set).
A text marker displays a string of characters on one or more lines of text. Embedded newlines cause line breaks. They may be used to annotate regions of the graph. The following options are specific to text markers:
- anchor = "center"
Anchor tells how to position the text relative to the positioning point for the text. For example, if anchor is "center" then the text is centered on the point; if anchor is "n" then the text will be drawn such that the top center point of the rectangular region occupied by the text will be at the positioning point. - background = ""
Same as the fill option. - font = "*-Helvetica-Bold-R-Normal-*-120-*"
Specifies the font of the text. (Windows 98: font = "Arial 8") - fill = ""
Sets the background color of the text. If fill is the empty string, background will be transparent. - foreground = "black"
Same as the outline option. - justify = "center"
Specifies how the text should be justified. This matters only when the marker contains more than one line of text. Justify must be "left", "right", or "center". - outline = "black"
Sets the color of the text. - padx = 4
Sets the padding to the left and right exteriors of the text. Padx can be a tuple of one or two screen distances. If padx has two elements, the left side of the text is padded by the first distance and the right side by the second. If padx has just one distance, both the left and right sides are padded evenly. - pady = 4
Sets the padding above and below the text. Pady can be a tuple of one or two screen distances. If pady has two elements, the area above the text is padded by the first distance and the area below by the second. If pady is just one distance, both the top and bottom areas are padded evenly. - rotate = 0.0
Specifies the number of degrees to rotate the text. Rotate is a real number representing the angle of rotation. The marker is first rotated along its center and is then drawn according to its anchor position. - shadow = ""
Specifies the color to use to make the text shadowed. If shadow is "", no shadow will be drawn. - text = ""
Specifies the text of the marker. The exact way the text is displayed may be affected by other options such as anchor or rotate.
A window marker displays a widget at a given position. The following options are specific to window markers:
- anchor = "center"
Anchor tells how to position the widget relative to the positioning point for the widget. For example, if anchor is "center" then the widget is centered on the point; if anchor is "n" then the widget will be displayed such that the top center point of the rectangular region occupied by the widget will be at the positioning point. - height = ""
Specifies the height to assign to the marker's window. If this option isn't specified, or if it is specified as "", then the window is given whatever height the widget requests internally. - width = ""
Specifies the width to assign to the marker's window. If this option isn't specified, or if it is specified as "" , then the window is given whatever width the widget requests internally. - window = None
Specifies the widget to be managed by the graph. Window must be a child of the graph widget.
See also
marker_cget(...), HelloMagnifier.py, HelloMarkers.py
10.7. marker_create(...)
Synopsis
def marker_create(self, type, **kw)
Description
Creates a marker of the selected type. Type may be either "text", "line", "bitmap", "image", "polygon", or "window". This method returns the marker identifier, used as the name argument in the other marker-related methods. If the name option is used, this overrides the normal marker identifier. If the name provided is already used for another marker, the new marker will replace the old.
If additional arguments are present, they specify options valid for the marker_configure(...) method.
See also
marker_configure(...), HelloMagnifier.py, HelloMarkers.py
10.8. marker_delete(...)
Synopsis
def marker_delete(self, *args)
Description
Removes one of more markers listed in args. The graph will automatically be redrawn without the marker.
See also
marker_create(...), HelloMagnifier.py, HelloMarkers.py
10.9. marker_exists(...)
Synopsis
def marker_exists(self, name)
Description
Returns 1 if the marker name exists and 0 otherwise.
See also
marker_names(...), HelloMarkers.py
10.10. marker_names(...)
Synopsis
def marker_names(self, *args)
Description
Returns the names of all the markers that currently exist. If a tuple of patterns is supplied in args, only those markers whose names match it will be returned.
See also
marker_exists(...), HelloMarkers.py
10.11. marker_type(...)
Synopsis
def marker_type(self, name)
Description
Returns the type of the marker given by name, such as line or text. If name is not a valid marker identifier, "" is returned.