Scroll to navigation

pie(3tk) tkpiechart pie class pie(3tk) 





NAME


pie - 2D or 3D pie chart object in a canvas






SYNOPSIS


package require stooop 4.1


package require switched 2.2


package require tkpiechart 6.6


stooop::new pie canvas x y
    ?options?


switched::configure pieObject ?options?


switched::cget pieObject option


stooop::delete pieObject


pie::newSlice pieObject ?labelText?


pie::deleteSlice pieObject sliceObject


pie::sizeSlice pieObject sliceObject
    unitShare ?displayedValue?


pie::labelSlice pieObject sliceObject
  string


pie::selectedSlices pieObject










DESCRIPTION


A pie object is used to visualize a set of values, usually as
    shares of a total. Each value is represented by a colored slice, which may
    have a 2 dimensional or 3 dimensional look. Each slice is associated with a
    label displaying the data name, and a numerical field showing the percentage
    taken by the slice. The labels are placed by the chosen labeler object
    (-labeler option). Each label color matches its related slice.


A pie chart is made of Tk canvas items, found in
    pieBoxLabeler, piePeripheralLabeler and canvasLabel
    objects, that compose the pie object. The pie constructor creates the pie
    itself and its background slice within the parent canvas. Once the pie
    object exists, slices can be created and resized. At the time the pie is
    created, the parent Tk canvas widget must exist.


Slice colors are automatically generated, using a default color
    list for all pies, unless another list is used (using the -colors
    option). When a 3D look is used, the slice edge is darker than its top while
    using the same color tone.



  

  
Creates a pie object in the specified Tk canvas. The upper left corner of
      the pie is placed at the specified coordinates in the canvas. The pie
      object identifier is returned (referred to as pieObject in this
      document).

  

  
Configures a pie object or returns all the options with their current
      values if no options are passed as parameters.

  

  
Returns an option value for the specified pie object.

  

  
Deletes the specified pie object.








OVERVIEW


The pie class is part of the tkpiechart extension that allows the
    programmer to create and dynamically update 2D or 3D pie charts in a Tcl/Tk
    application. The tkpiechart package is written in Tcl only, using object
    oriented techniques thanks to the stooop package, included in tcllib.






OPTIONS



  

  
Boolean value specifying whether all the slices and their labels are
      redrawn when a slice size is changed. On by default. Turn it off and
      invoke pie::update if you change many slices at once and want to
      improve performance.

  

  
Slices may or may not fill up the 100% of the pie. The unoccupied part of
      the pie is a slice that takes 100% of the pie. It is by default
      transparent with a black border. The color of this background slice may be
      set by the user using color names as in the -background standard
      option (see the Tk options manual page for more details). When the
      pie has a 3D look, the background of a slice edge is darker than the top
      and uses the same color tone.

  

  
Specifies a list of colors for slices. In this case, the slice colors will
      successively be drawn from the list in the list order, cycling through if
      there are more slices than colors in the list. Colors are specified in the
      same format as the -background option.

  

  
Specifies the total height for the pie, including the room taken by the
      labeler labels. The pie slices are resized when labels are added or
      deleted (when adding or deleting slices) so that the total height remains
      constant. This value may be specified in any of the forms described in the
      canvas COORDINATES manual section.

  

  
Specifies a placer object for the slice labels, so that, for example,
      slice values may be placed next to them. If not specified, the
      pieBoxLabeler (see corresponding manual) is used, the other option
      being the piePeripheralLabeler class. Each labeler has a specific
      behavior which may be set via its options. The labeler object is
      automatically deleted when the pie object is itself deleted. The labeler
      cannot be changed once the pie is created.

  

  
Boolean value specifying whether slices are selectable or not. Acceptable
      values are those defined by the Tcl language itself for boolean values. If
      selectable, slices can be selected with the first mouse button, by
      clicking on either the slice or its label. Selection can be extended by
      using the classical control or shift clicks. The list of
      currently selected slices can be retrieved at any time using the
      selectedSlices pie class member procedure.

  

  
Title text to be placed above the pie.

  

  
Font for the title text.

  

  
Distance between the bottom of the title text and the top of the pie
      slices. This value may be specified in any of the forms described in the
      sizes section below.

  

  
The thickness is set to 0 by default, giving the pie a simple 2D shape,
      much faster to display. A positive thickness value will give the pie a 3D
      look with matched darker colors for the slices edges. These values may be
      specified in any of the forms described in the SIZES section
    below.

  

  
Specifies the total width for the pie, including the room taken by the
      labeler labels. The pie slices are resized when labels are added or
      deleted (when adding or deleting slices) so that the total width remains
      constant. This value may be specified in any of the forms described in the
      canvas COORDINATES manual section.








MEMBER PROCEDURES



  

  
Creates a slice. A unique object identifier is returned (referred to as
      sliceObject in this document). The slice color is automatically
      allocated and the slice label placed using the specified labeler (using
      the -labeler option). The slice itself is placed after (clockwise)
      the existing slices. The slice object identifier will be used for sizing
      and resizing the slice.
    
If the label text is not specified, it will be set to
        "slice n", n being the number of the slice in
        the order of creation (first slice is number 1).

  

  

  
Deletes a slice. The following slices (clockwise) if any are then moved to
      compensate for the empty space left by the deleted slice.

  

  
Sizes or resizes a slice. The slice is then automatically recalculated so
      it occupies the proper share of the whole pie. The unitShare
      parameter is a floating point number expressed in share (between 0 and 1)
      of the whole pie. The following slices (clockwise) are moved to
      accommodate the new slice size. The slice size value next to the slice
      label is also updated with the new share value or displayedValue if
      specified.

  

  
Updates a slice label. Can be invoked at any time.

  

  
Returns a list of currently selected slice objects.








TAGS


The whole pie, the pie graphics (all slices), and each slice have
    the following specific tags:


    
  
  • pie(pieObject)
    • 
  
  • pieSlices(pieObject)
    • 
  
  • slice(sliceObject)
    • 



For example, the whole pie can be moved using the canvas
    move command on the pie tag, or bindings on slices can be set using
    the slice tags (see the canvas manual page ITEM IDS AND TAGS
    section for more information).






SIZES


All sizes related to pies are stored as floating point numbers.
    The coordinates and sizes are specified in screen units, which are floating
    point numbers optionally followed by one of several letters as specified in
    the canvas COORDINATES manual section.






LIMITATIONS


If the number of slices is too big, identical colors will be used
    for some of the slices. You may set your own colors in this case.






BUGS, IDEAS, FEEDBACK


This document, and the package it describes, will undoubtedly
    contain bugs and other problems. Please report such in the category
    tkpiechart of the Tklib Trackers
    [http://core.tcl.tk/tklib/reportlist]. Please also report any ideas for
    enhancements you may have for either package and/or documentation.






SEE ALSO


canvasLabel, pieBoxLabeler, piePeripheralLabeler






KEYWORDS


canvas, labeler, pie, slice






COPYRIGHT


Copyright (c) 1995-2004 Jean-Luc Fontaine <jfontain@free.fr>








  

    6.6
    tklib