PHIGURE can be used to generate a graphic object which clearly represents the relative size of one data in relation to a set of data. Each is given a numerical value which is expressed as a percentage of the sum of the values of the entire set of data. This percentage is used to calculate the angle of the slice representing the data in question. All the slices together make up a "pie chart".
The pie chart is therefore made up of several slices. Text associated with data, their value and their percentage can be written on the slices in various ways. The C types describing pie chart data are:
typedef struct {
char *text;
Pfloat value;
} Tpie_slice;
typedef struct {
Pint num_slices; Tpie_slice *slice } Tpie_data;
The pie chart can be configured according to a set of attribute functions which determine the presentation of the pie. If these functions are not called, the attributes they set take a default value used by the pie chart construction function tpiech_chart or tpiech_chart3.
Annotation position
Exterior annotation (text, values, percentages) of pie chart slices can be drawn radially with respect to the slices, horizontally, aligned horizontally or vertically, or along a reference square. The C types defining the annotation positioning attributes are:
typedef enum {
TANNOT_POS_RADIAL,
TANNOT_POS_HORIZONTAL,
TANNOT_POS_HORIZONTAL_ALIGNED,
TANNOT_POS_VERTICAL_ALIGNED,
TANNOT_POS_SQUARE_ALIGNED
} Tpie_annot_position;
typedef struct {
TANNOT_INTERNAL,
TANNOT_EXTERNAL
} Tpie_annot_flag;
Interior
annotation of pie chart slices can be drawn radially with respect to the slices
or horizontally.
Annotation visibility flags
Text, values and percentages can be visible or invisible for interior and/or exterior annotation. If several are visible, it is possible to specify the alignment method in an annotation box. The C type describing visibility is:
typedef enum {
TVISIBILITY_ON,
TVISIBILITY_OFF
} Tvisibility_flag;
Annotation
height Character height for text, values and percentages can be defined for interior and/or exterior annotation.
Strings appended to annotation values
A character string can be appended to an interior and/or exterior annotation value. This is useful for adding a string that indicates units of measure.
Exterior annotation arrow
An arrow composed of two branches can join the exterior annotation with it associated slice in a pie chart.
Annotation displacement
The distances indicating the displacement of interior annotation and/or exterior annotation from the center of a pie chart can be set. For exterior annotation these distances define the eventual lengths of the two arrow branches.
Low-value grouping
A pie chart can be difficult to read if there are very many "thin" slices, of low value. To prevent this, a low value limit can be defined and all values under this limit will be grouped together in a single slice. By default, all data slices representing less than 5% are grouped together in a single slice entitled "other". The C types defining the grouping attributes are:
typedef enum {
TGROUP_OFF,
TGROUP_ON
} Tpie_group_low_value;
typedef enum {
TABSOLUTE,
TPERCENTAGE
} Tpie_percent_status;
Slice shift attribute
One slice of the pie chart can be moved out from the center of the circle, to emphasize it in relation to the other slices. The slice can be moved along the axis bisecting the slice.
Slice representation
Slices can be coloured, cross-hatched or filled with a pattern. A table specifying the representation mode of each slice can be selected. Application of these representations during construction of the pie chart is cyclical: if the number of types of representation defined is less than the number of slices in the pie chart, the representations are repeated. By default, the representation type table comprises the first eight colours of the work station (black, white, red, green, blue, cyan, magenta, yellow) which are used to fill the slices of the pie chart.
The C type defining the representation of slices is:
typedef struct {
Pint num_repres;
Pint_style *repres_type;
Pint *repres_index;
} Tpie_slice_representation;
PHIGURE provides one set of functions, tset_piech_*** , to set these attributes for a given structure, and another, tinq_piech_*** , to retrieve them for a given structure. The tinq_piech_*** functions are especially useful for developing an application for interactive modification of the values of pie chart attributes.
As applies to the axis functions, the attribute functions must be called before calling tpiech_chart or tpiech_chart3. PHIGURE also uses the function tinq_piech_slice_number allowing a number representing a designated slice in a pie chart to be retrieved with the aid of the mouse. This gives you the ability to modify pie-chart characteristics interactively.