\begindata{text,538429080}
\textdsversion{12}
\template{default}
\define{programexample
menu:[Region,ProgramExample]
attr:[Justification LeftJustified Point 0]
attr:[FontFamily Helvetica Int 0]}
\define{itemize
menu:[Region,Itemize]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{enumerate
menu:[Region,Enumerate]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{notetotypesetter
menu:[Region,NoteToTypesetter]
attr:[Flags PassThru Int Set]}
\define{title
menu:[Heading,Title]
attr:[Justification Centered Point 0]
attr:[FontSize PreviousFontSize Point 4]}
\define{appendix
menu:[Heading,Appendix]
attr:[FontFace Bold Int Set]
attr:[FontSize PreviousFontSize Point 4]}
\define{ibm
menu:[Font,IBM]
attr:[FontFamily ibm Int 0]}
\define{centre
menu:[Region,Centre]
attr:[Justification Centered Point 0]}
\define{passthrough
menu:[Region,Passthrough]
attr:[Flags PassThru Int Set]}
\define{sans
menu:[Font,Sans]
attr:[FontFamily AndySans Int 0]
attr:[FontSize PreviousFontSize Point -2]}
\define{block
menu:[Region,Block]
attr:[LeftMargin LeftMargin Inch 81920]}
\center{
\bigger{\bigger{\bold{\bigger{\bigger{Chart}}
Programming Guide}}}
Information Technology Center
Carnegie Mellon University
TC Peters
(3/1/89)
9/6/89
\bold{(c) IBM Corporation
1989}}
\begindata{bp,539404616}
Version 2
n 0
\enddata{bp,539404616}
\view{bpv,539404616,1,0,0}
\bold{Preface}
This document presents the Concepts and Facilities of the \bold{Chart}
class. This class provides interactive views upon data collections via
an
extensible set of Chart formats. A given collection of data can be
displayed in different Chart formats simply by changing the Chart
\italic{type}; similarly, Chart \italic{filigree}, such as Titles,
Coordinates, Ticks, and Fonts can be changed from their defaults to
desired
alternatives. Editing facilities provided by the Chart class support
both
data-entry and Chart styling, as well as facilities for introducing new
Chart Presentation classes.
The Chart class is a sub-class of the \italic{aptview} class (see
the\italic{ Apt Programming Guide} for details regarding built-in
Iconification, Help, and other common features). The Chart class
provides
both a Data-object and a View-object: it supports the standard
DataObject
and View class operations, such as Read, Write, FullUpdate,
ReceiveInputFocus, Update, etc, including the Print operation. As a
generic class, it is meant to be used by client-programs to provide a
variety of interactive visual interfaces to Charts.
\begindata{bp,539405864}
Version 2
n 0
\enddata{bp,539405864}
\view{bpv,539405864,2,0,0}
\bold{Introduction}
xxx
\begindata{bp,539406344}
Version 2
n 0
\enddata{bp,539406344}
\view{bpv,539406344,3,0,0}
\chapter{1 Concepts}
The \bold{Chart} class supports interactive views upon \italic{Charts} of
zero or more \italic{Items}. The Chart visual is an optionally bordered
rectangle; this area is termed the \italic{Container}. Chart Items are
arranged within the Container in various fashions, as specified by the
Client-program.
\center{
*********************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
CONTAINER
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*********************************
}\center{
\begindata{bp,539407688}
Version 2
n 0
\enddata{bp,539407688}
\view{bpv,539407688,4,0,0}}
Although you can set various attributes to tailor the manner in which a
Chart and its Items are displayed and manipulated, all have defaults that
should yield acceptable formatting. You should begin with the defaults,
and subsequently try experimentation with the attributes. (See the first
example in the section \italic{Sample Programs}.)
Some typical Chart views:
\center{
*********************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*********************************
}
(See the chapter \italic{Sample Programs} for additional Chart visuals.)
\begindata{bp,539408312}
Version 2
n 0
\enddata{bp,539408312}
\view{bpv,539408312,5,0,0}
By way of example, the following is a complete program
(\italic{\sans{chartx1a}}) employing the Chart class. Its functionality
is
rather simple: it shows the proportion of houshold income apportioned to
several categories.
\center{\typewriter{
**************************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
**************************************
}}
\sans{\leftindent{
#include <andrewos.h>
#include
<im.ih>
#include
<frame.ih>
#include
<chart.ih>
#include
<chartv.ih>
#include
<chartx1a.eh>
#define
Chart
(self->chart_data_object)
#define
ChartView
#define
Frame
#define
Im
(self->chart_view_object)
(self->frame)
(self->im)
boolean \
chartx1app__InitializeObject( classID, self )
register struct classheader
*classID;
register struct chartx1app *self;
\{
chartx1app_SetMajorVersion( self, 0 );
chartx1app_SetMinorVersion( self, 0 );
Chart = chart_New();
ChartView = chartv_New();
return TRUE;
\}
boolean
chartx1app__Start( self )
struct chartx1app
*self;
\{
long
status = TRUE;
super_Start( self );
if ( Chart
&&
ChartView )
\{
Frame = frame_New();
frame_SetView( Frame, ChartView );
Im = im_Create(NULL);
im_SetView( Im, Frame );
chart_SetChartAttribute( Chart, chart_Type( "Pie" ) );
chart_SetChartAttribute( Chart, chart_TitleCaption( "Home Budget" )
);
chart_SetItemAttribute( Chart, chart_CreateItem( Chart, "Mortgage",
NULL ),
chart_ItemValue( 28 ) );
chart_SetItemAttribute( Chart, chart_CreateItem( Chart, "Food", NULL
),
chart_ItemValue( 32 ) );
chart_SetItemAttribute( Chart, chart_CreateItem( Chart, "Insurance",
NULL ),
chart_ItemValue( 7 ) );
chart_SetItemAttribute( Chart, chart_CreateItem( Chart,
"Entertainment", NULL ),
chart_ItemValue( 8 ) );
chart_SetItemAttribute( Chart, chart_CreateItem( Chart, "Savings",
NULL
),
chart_ItemValue( 5 ) );
chart_SetItemAttribute( Chart, chart_CreateItem( Chart, "Education",
NULL ),
chart_ItemValue( 10 ) );
chart_SetItemAttribute( Chart, chart_CreateItem( Chart, "Vacation",
NULL ),
chart_ItemValue( 10 ) );
chartv_SetDataObject( ChartView, Chart );
chartv_WantInputFocus( ChartView, ChartView );
return
status;
\}
else \
\{
printf( "ChartX1: Failed to Create objects\\n" );
return FALSE;
\}
\}
}}
The attributes are discussed in the sections \italic{Chart
Specifications}
and \italic{Item Specifications}. Other sections detail usage of
interactive programming through \italic{Handlers}, procedures that react
to
User selection of Items.
You can print Charts in various fashions, as detailed in the section on
\italic{Printing}.
\section{1.1
Data/View Dichotomy}
\section{1.2
Data Specifications}
\subsection{1.2.1 Chart Data Attributes}
The fashion in which Charts are displayed, as well as the nature and
format
of its Items, is governed by the Specification argument optionally
provided
when the Chart object is created. (See the \sans{Create} facility,
discussed in the chapter \italic{Facilities.})
The syntax of a specification is best shown through an example.
Chart
is produced through the following specification:
This
XXXX
\begindata{bp,539410952}
Version 2
n 0
\enddata{bp,539410952}
\view{bpv,539410952,6,0,0}
The Specification is composed of macros, each requiring an argument. The
argument is sometimes a \italic{symbolic} (eg, \sans{chart_RoundAngle}),
sometimes a \italic{numeric value} (eg, the value 3 in
\sans{chart_BorderSize}), sometimes a \italic{character-string} (eg, the
quoted characters \italic{Production Options} in
\sans{chart_TitleCaption}), and sometimes a \italic{procedure-pointer}
(eg,
\sans{Option_Procedure} in \sans{chart_HitHandler}). Note that all
symbolics are prefixed with \sans{ chart_ } to avoid name-clashes within
the Client-program. There is no required ordering amongst the items in
the
Specification structure: it is parsed sequentially, such that a
subsequent
attribute overrides an earlier conflicting attribute.
See chapter \italic{Sample Programs} for more complete examples.
The attributes of the Chart and its Items, their defaults and
alternatives,
are discussed below. (Attributes are listed \italic{alphabetically}, for
ease of reference.)
\bold{\sans{chart_Datum}}
\indent{Any Client-program datum (eg, a scalar or a pointer to a
Client-program defined structure). Dynamically accessible via the
\sans{SetChartAttribute} and \sans{ChartAttribute} facilities. (Also see
the \sans{ItemDatum }attribute, which provides the item-specific data
attribute.)}
\sans{\bold{chart_FileName}}
\indent{For 'stand-alone' (application) usage, the anme of the file in
which the Chart Datastream is to be stored.}
\bold{\sans{chart_TitleCaption}}
\indent{A Chart may contain a \italic{Title}. The Title may be a caption
or
an Inset. By default, the Title is centered at the top of the Container,
within the Container's Border. A Title caption may contain
\italic{new-line} characters: the Title then occupies multiple vertical
lines. (See \sans{TitlePlacement}.)}
\sans{ }\bold{\sans{chart_TitleDataObjectName}}
\indent{Instead of a caption, any ATK \italic{inset} can be specified as
the substance of a Title. The object name is a character-string.}
\bold{\sans{chart_TitleViewObjectName}}
\indent{Where a \sans{TitleDataObjectName} is specified, an associated
\sans{TitleViewObjectName} may be specified; in the absence of a
specified\italic{ }\sans{TitleViewObjectName}, the default
\sans{TitleViewObjectName} implied by the \sans{TitleDataObjectName} will
be employed.}
\sans{\bold{chart_Type}}
\indent{The Chart Type attribute, which defaults to
\sans{chart_Histogram},
specifies the Chart Presentation class to be employed to display the
Chart.
This attribute may be re-set dynamically.
\indent{\sans{chart_Pie
chart_Histogram
chart_StackedHistogram
chart_EKG
chart_Dot
chart_Cartesian
chart_Polar
chart_Map
chart_xxx}}}
XXX
\subsection{1.2.2 Item Data Attributes}
\sans{\bold{chart_ItemDatum}}
\indent{Each Item has a \italic{Datum} attribute, initialized to Null
(zero).}
\sans{\bold{chart_ItemName}}
\indent{Each Item has a \italic{Name} attribute, initialized to Null
(zero).
}
\sans{\bold{chart_ItemPosition}}
\indent{Each Item has a \italic{Position} attribute, indicating its
position within the set of Items. The first Item is at Position-1, the
nth
at Position-n.}
\sans{\bold{chart_ItemValue}}
\indent{Each Item has a \italic{Value} attribute, initialized to Null
(zero), subsequently modified by User interaction. The Values of a
Chart's
Items comprises the semantics of a Chart.}
\section{1.3
View Specifications}
\subsection{1.3.1 Chart View Attributes}
\sans{\bold{chartv_Arrangement}}
\indent{By default, charts are drawn Vertically (eg, Histogram bars are
vertical); ...}
\sans{\bold{chartv_BackgroundShade}}
\indent{...}
\bold{\sans{chartv_BorderStyle}}
\indent{The Container may be bordered; by default, the border is a
\sans{Rectangle}, whose line-width is one. Its style may be specified
in
various other fashions:
\indent{
\sans{chartv_Rectangle}
\sans{chartv_Invisible}
\sans{chartv_None}
\sans{chartv_Roundangle}
\sans{chartv_Circle}
\sans{chartv_Oval}}}
\bold{\sans{chartv_BorderSize}}
\indent{Where the \sans{BorderStyle} is other than \sans{None}, the
pixel-width of the line may be specified (default is one).}
\bold{\sans{chartv_Cursor}}
\indent{The cursor for the entire Chart may be specified; the value
specified is a single character. If the \sans{CursorFontName} is not
specified, the default font is \italic{icon12}. The default cursor is
the
standard Arrow.
Example:
\sans{chartv_Cursor( 'E' )}}
\bold{\sans{chartv_CursorName}}
\indent{The cursor for the entire Chart may be specified; the value
specified is one of the standard cursor names -- eg, \sans{Cursor_Arrow},
\sans{Cursor_Gunsight}, etc. If the \sans{CursorFontName} is not
specified, the default font is \italic{icon12}.
Example:
\sans{chartv_CursorName( Cursor_Gunsight )}}
\bold{\sans{chartv_CursorFontName}}
\indent{The font for the Chart's cursor may be specified. The default
font
is \italic{icon12}.
Example
\sans{chartv_CursorFontName( "charticon20" )}}
\bold{\sans{chartv_Datum}}
\indent{Any Client-program datum (eg, a scalar or a pointer to a
Client-program defined structure). Dynamically accessible via the
\sans{SetChartAttribute} and \sans{ChartAttribute} facilities. (Also see
the \sans{ItemDatum }attribute, which provides the item-specific data
attribute.)}
\bold{\sans{chartv_HitHandler}}
\indent{A Chart may specify a Client-program procedure to be invoked
whenever any area within the Container is hit. (See the section
\italic{Handlers}.)}
\bold{\sans{chartv_ItemBorderStyle}}
\indent{Items may be styled with or without Borders; by default, the
border
is a \sans{Rectangle}, whose line-width is one. Borders may be one of
the
styles:
\indent{\sans{chartv_Rectangle}
\sans{chartv_Invisible}
\sans{chartv_None}
\sans{chartv_Roundangle}
\sans{chartv_Circle}
\sans{chartv_Oval}}
}\bold{\sans{chartv_ItemBorderSize}}
\indent{Where the \sans{ItemBorderStyle} is other than \sans{None}, the
pixel-width of the line may be specified (default is one).}
\bold{\sans{chartv_ItemHighlightStyle}}
\indent{Items may be highlighted, either upon User selection or through
Client-program request. The styles for Highlighting, which may be used
in
combination, are:
\indent{\sans{chartv_Invert}
\sans{chartv_Border}
\sans{chartv_Bold}
\sans{chartv_Italic}}
To combine several styles, the syntax is -\sans{chartv_ItemHighlightStyle( chartv_Bold | chartv_Italic)}}
\bold{\sans{chartv_LabelFontName}}
\indent{The font used to display Labels may be specified. By default, the
\sans{LabelFontName} is that specified via the preference for "bodyfont"}
\
\bold{\sans{chartv_ScaleFontName}}
\indent{The font used to display Scales may be specified. By default, the
\sans{ScaleFontName} is that specified via the preference for "bodyfont"}
\
\bold{\sans{chartv_TitleBorderStyle}}
\indent{The Title may be bordered; by default, the border is Invisible.
Its style may instead be specified in other fashions:
\indent{
\sans{chartv_Rectangle}
\sans{chartv_Invisible}
\sans{chartv_None}
\sans{chartv_Roundangle}
\sans{chartv_Circle}
\sans{chartv_Oval}}}
\bold{\sans{chartv_TitleBorderSize}}
\indent{Where the \sans{TitleBorderStyle} is not \sans{Invisible}, the
pixel-width of the line (default is one) may be specified.}
\bold{\sans{chartv_TitleCaptionFontName}}
\indent{Given a Title that is a Caption, its font may be specified. By
default, the \sans{TitleCaptionFontName} is that specified via the
preference for "bodyfont"}
\
\bold{\sans{chartv_TitleDataObjectHandler}}
\indent{A \sans{procedure} may be specified to be associated with the
Title
Data-object. That procedure is invoked upon instantiation of the
object.}
\bold{\sans{chartv_TitleHighlightStyle}}
\indent{Titles may be highlighted, either upon User selection or through
Client-program request. The styles for Highlighting, which may be used
in
combination, are:
\indent{\sans{chartv_Invert}
\sans{chartv_Border}
\sans{chartv_Bold}
\sans{chartv_Italic}}}
\bold{\sans{chartv_TitleHitHandler}}
\indent{A Chart may specify a Client-program \sans{procedure} to be
invoked
whenever the Chart \italic{Title} transitions from un-selected to
selected.
(See below, \italic{Handlers}.)}
\bold{\sans{chartv_TitlePlacement}}
\indent{The Title may be placed at the \
\indent{\sans{chartv_Top}
\sans{chartv_Bottom}
\sans{chartv_Left}
\sans{chartv_Right}
\sans{chartv_Line} }\
of the Container. The Title can be separated from the Item-area by a
dividing line.}
\bold{\sans{chartv_TitleViewObjectHandler}}
\indent{A \sans{procedure} may be specified to be associated with the
Title
View-object. That procedure is invoked upon instantiation of the
object.}
\subsection{1.3.2 Item View Attributes}
\section{1.4
Handlers}
Whereas the Chart class provides appropriate housekeeeping to reflect
User
interaction with a Chart through its view, it is the Client-program's
Handlers (also known as "call-back procedures") that effect whatever
functionality such interaction implies. There are various interactions
and
events that will cause a Handler to be invoked.
There are two kinds of Handlers: those that cope with Hits and those
that
deal with Titles, etc, specified as Objects (ie, not simply Captions).
\subsection{1.4.1 Hit Handlers}
Upon invocation, a Hit Handler is passed these arguments:
\indent{\bold{Argument-1:}
The Client-program Anchor associated with the Chart View (as provided via
the \sans{chartv_Create} facility).
\bold{Argument-2:}
Identifier of the Chart View-object.
\bold{Argument-3:}
Identifier of the object hit.
\bold{Argument-4:}
Hit-object type (\sans{chartv_ItemObject}, \sans{chartv_TitlteObject}, or
\sans{Null})
\bold{Arguments 5-8:}
Standard ATK Mouse inchartation -- action, x, y, clicks.}
Thus, a typical Hit Handler would be written:
\indent{\sans{My_Hit_Handler( self, chart, object, object-type, action,
x,
y, clicks )}}
(The parameter \sans{self} is the value specified as the \italic{Anchor}
by
the Client-program via \sans{chartv_Create}.)
Note that all mouse-actions (including DownMovement) are passed through
to
the HitHandler, whether or not an Item or Title is affected.
\subsection{1.4.2 Object Handlers}
Handlers may specified to deal with instantiation of Title Data and View
objects.
... \
Upon invocation, an Object Handler is passed these arguments:
\indent{\bold{Argument-1:}
The Anchor associated with the Chart.
\bold{Argument-2:}
Identifier of the Chart.
\bold{Argument 3:}
Identifier of the object
\bold{Argument 4:}
Object-type (\sans{chartv_TitleObject} or Null).
}
Thus, a typical Object Handler would be written:
\sans{\indent{My_Object_Handler( self, chart, item, type )}}
\section{1.5
Printing}
Printed output is in PostScript chart.
xxx
\begindata{bp,539442536}
Version 2
n 0
\enddata{bp,539442536}
\view{bpv,539442536,7,0,0}
\chapter{2 Facilities}
Facilities are ClassProcedures, Methods, or MacroMethods provided by a
Class to facilitate communication between an object and its creator.
There
are two groups of facilities: those for the Chart itself, and those for
the Items of the Chart.
The facilities are presented in a standard chart:
A brief \italic{\bold{description}}\bold{ }of the facility, followed by
these topics -\italic{\bold{Synopsis }}
arguments.
\italic{\bold{Returns}}
returned.
Prototype statement syntax and data-types of
Data-type and description of value
\italic{\bold{Exceptions}}
Name of any exceptions raised.
\italic{\bold{Discussion}}
its
role and usage.
Elaboration of the nature of the facility,
\bold{Syntax Conventions}
To provide examples of their usage, both sample statements and a chapter
of
Sample Programs are listed; these are shown in the syntax of the ATK
\italic{Class} extension.
Of particular interest are certain implications upon naming-conventions
and
required arguments:
\description{\indent{
o The ATK Class feature requires methods to be prefixed with the name of
the Class to which they belong. Further, it requires that the first
argument always be the Identifier (handle or pointer) of the instantiated
Object being invoked. Thus -\sans{\bold{\indent{chart_SetChartAttribute( \italic{object},
chart_TitleCaption( \italic{title} ) );}}}
\indent{
where :
\sans{\bold{object}} is the Identifier of the instance of the Class (as
returned from the \sans{chart_Create} facility);
\sans{\bold{title}} is a pointer to a character-string}
}}\indent{
o }\description{\indent{All symbolic-names (eg, those of the options and
exception-codes) are prefixed with the character "chart_" or "chartv_" to
preclude name-clashes with Client-program names.}}
\section{2.1
Data Object Facilities}
\subsection{2.1.1 Object Instantiation}
Chart Data-objects are instantiated through either the \sans{Create} or
the
\sans{New} facility. Where the \sans{Create} facility is employed, you
can
override the default object attributes.
\paragraph{2.1.1.1
Create}
Creates an instance of the chart Data-object. Parses the optional
Specification to establish initial attributes; reserves the requesting
object's Identifier (for subsequent call-backs)..
\bold{Synopsis}\block{ \sans{chart_Create( specification, anchor )
chart_Specification
specification
struct basicobject
\bold{Returns}\block{
object
identifier.}}
*anchor
|
|
NULL
NULL}}
\sans{struct chart *}
\italic{Chart Data-
\bold{Exceptions}\block{
\sans{InsufficientSpace, AttributeConflict}}
\bold{Discussion}\block{
Chart
The \sans{Create} facility establishes a
Data-object through an optional Chart Specification. This
\sans{specification} argument is a pointer to a vector of symbolics,
values, or pointers to values. Such vectors are specified within the
Client program through special Chart macros, such as chart_BorderStyle,
chart_HitHandler, etc. (See section \italic{Chart Specifications}; also
chapter \italic{Sample Programs} for illustrations.) The \sans{anchor}
argument is usually the instance-pointer of the object requesting the
creation of an Chart object; this argument may be NULL.
The Attribute-Names are symbolics, the Attribute-Values are of the
data-type appropriate to the specific Attribute. The Attributes and
associated Values are discussed in the \italic{Concepts} chapter.}
\subsection{2.1.2 Chart Attributes}
Chart attributes may be set either at compile-time, through the static
declaration of the Specification vector passed as an optional argument
to
the \sans{Create} facility, or dynamically through the
\sans{SetChartAttribute} facility. In most instances, the static fashion
suffices.
Changing attributes does not result in immediate changes to the Chart
display: only upon the next FullUpdate are the changes reflected.
There
are, however, several facilities provided to effect immediate visual
changes for certain attributes. These facilities all have the verbprefix
\sans{Change (eg, chart_ChangeTitle).}
\paragraph{2.1.2.1
SetChartAttribute}
Sets the specifed attribute to the given value.
\bold{Synopsis}\block{ \sans{chart_SetChartAttribute( object,
attribute_value)
struct chart
long
*object
attribute_value}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
None.}
Result-code.}}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Chart Specifications} can be set either statically or
dynamically.
The syntax for this facility is that employed in the static declaration
of
attributes, for example -\sans{
chart_SetChartAttribute( object, chart_TitleCaption( "Hourly Weather" )
);}
Note that those Attributes that have an impact upon the Chart display do
not take effect until either the next FullUpdate or Update request is
effected.}
\paragraph{2.1.2.2
ChartAttribute}
Yields the value of the given Chart attribute.
\bold{Synopsis}\block{ \sans{chart_ChartAttribute( object,
struct chart
long
attribute)
*object
attribute
}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Value.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Chart Specifications} can be queried.
The syntax of this facility is similar to that of the
\sans{SetChartAttribute} facility, but differs in that the parenthesized
argument is 0 (Null) -\sans{chart_ChartAttribute( object, chart_Datum(0) );}
}
\subsection{2.1.3 Chart Manipulation}
These facilities deal with the Chart's entire set of Items.
\paragraph{2.1.3.1
Reset}
Resets the Chart to its initial state -- in particular, Normalizes and
Activates all Items.
\bold{Synopsis}\block{ \sans{chart_Reset( object)
struct chart
*object}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code.}}
None.}
\bold{Discussion}\block{
See also: \sans{ chart_Clear},
\sans{chart_ClearItems}, and \sans{chart_DestroyItem}.}
\paragraph{2.1.3.2
Apply}
Iterates across each of the Chart's \sans{Items}, invoking the given
\sans{procedure} for each \sans{Item }in turn. \
\bold{Synopsis}\block{ \sans{chart_Apply( object, procedure, anchor,
datum )
struct chart
*object
long(*)()
procedure
struct dataobject
long
*anchor
datum}}
\bold{Returns}\block{
value.}}
\sans{long} \italic{
\bold{Exceptions}\block{
Client returned-
\sans{ApplyInterrupte}d}
\bold{Discussion}\block{
The \sans{procedure} is invoked with these
arguments, in the order shown:
\indent{\sans{anchor}
\sans{object}
\sans{item}
Given \sans{anchor}-value
Identifier of the Chart object
Identifier of present Item
\sans{datum}
Given \sans{datum}-value}
Within the \sans{procedure}, all Chart facilities may be employed; note
that alteration of the Chart will affect subsequent invocations to the
procedure.
The order in which the Items are accessed is that specified when the
Chart
was created, or the order in which they were dynamically created.
The invoked procedure breaks the scan by returning a non-zero value (a
zero-value continues the scan); the \sans{Apply} facility returns this
value as the scan stops. Where the scan stops because it reaches the end
of the Items, Null is returned.}
\subsection{2.1.4 Item Attributes}
Item attributes may be set either at compile-time, through the static
declaration of the Specification vector passed as an optional argument
to
the \sans{Create} facility, or dynamically through the
\sans{SetItemAttribute} facility. In most instances, the static fashion
suffices.
Changing attributes does not result in immediate changes to the Chart
display: only upon the next FullUpdate are the changes reflected.
There
are, however, several facilities provided to effect immediate visual
changes for certain attributes. These facilities all have the verbprefix
\sans{Change (eg, chart_ChangeItemCaption).}
\paragraph{2.1.4.1
SetItemAttribute}
Sets the specifed attribute of the given Item to the given value.
\bold{Synopsis}\block{ \sans{chart_SetItemAttribute( object, item,
attribute_value)
struct chart
*object
struct chart_item
*item
chart_Specification
}}
\bold{Returns}\block{
attribute_value
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Item Specifications} can be set either statically or dynamically.
The syntax for this facility is that employed in the static declaration
of
attributes, for example:
\sans{\description{chart_SetItemAttribute( object, item, chart_ItemValue(
2351 ) );}
}
Note that those Attributes that have an impact upon the Chart display do
not take effect until either the next FullUpdate or Update request is
effected.}
\paragraph{2.1.4.2
ItemAttribute}
Yields the value of the given attribute for the given Item.
\bold{Synopsis}\block{ \sans{chart_ItemAttribute( object, item,
attribute)
struct chart
*object
struct chart_item
*item
long
attribute
}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Value.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Item Specifications} can be queried.
The syntax of this facility is similar to that of the
\sans{SetItemAttribute} facility, but differs in that the parenthesized
argument is 0 (Null):
\sans{\description{chart_ItemAttribute( object, item, chart_ItemValue(0)
);}
}}
\subsection{2.1.5 Item Identification}
Identifiers of individual Items may be obtained through facilities that
scan the Item set to locate one that matches a given value. These
facilities need only be employed in those instances that a particular
Item
is to be located -- in most instances, such as HitHandlers, you will find
that the identifier of the Item passed to such procedures suffices.
Some of the location facilities (eg, \sans{ItemsOfName}) returns a
pointer
to a null-terminated vector of Item identifiers; others return a Item
identifier.
\paragraph{2.1.5.1
ItemOfDatum}
Yields Identifier of the Item whose Datum attribute matches the given
Datum.
\bold{Synopsis}\block{ \sans{chart_ItemOfDatum( object, datum )
struct chart
long
*object
datum}}
\bold{Returns}\block{
Identifier}}
\sans{struct chart_item *}
\bold{Exceptions}\block{
\italic{
Item
None.}
\bold{Discussion}\block{
Where no Item Datum matches the given Datum,
the
value Null is returned. Where Null Datum is given, the first Item whose
Datum is Null is returned.}
\paragraph{2.1.5.2
ItemsOfDatum}
Yields Identifier(s) of the Item(s) whose Datum attribute matches the
given
Datum.
\bold{Synopsis}\block{ \sans{chart_ItemsOfDatum( object, datum )
struct chart
*object
long
datum}}
\bold{Returns}\block{
Identifier
vector}}
\sans{struct chart_item **} \italic{Item
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Where no Item Datum matches the given Datum,
the
value Null is returned. Where Null Datum is given, Items whose Datum is
Null are returned.}
\paragraph{2.1.5.3
ItemOfName}
Yields Identifier of the Item whose Name field matches the given Name.
\bold{Synopsis}\block{ \sans{chart_ItemOfName( object, name )
struct chart
char
*object
*name}}
\bold{Returns}\block{
Identifier.}}
\sans{struct chart_item *}
\italic{
Item
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
the
Where no Item Name matches the given Name,
value Null is returned. Where the Null Name is given, the first Item
whose
Name is Null is returned.}
\paragraph{2.1.5.4
ItemsOfName}
Yields Identifier(s) of the Item(s) whose Name field matches the given
Name.
\bold{Synopsis}\block{ \sans{chart_ItemOfName( object, name )
struct chart
char
*object
*name}}
\bold{Returns}\block{
Identifier
vector.}}
\sans{struct chart_item **} \italic{Item
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Where no Item Name matches the given Name,
the
value Null is returned. Where the Null Name is given, Items whose Name
is
Null are returned.}
\subsection{2.1.6 Item Selection}
Items are selected by the User through mouse-hits within their borders.
In
general, control is passed for only for Up-transition mouse-actions; see
the \italic{Concepts} discussion regarding \sans{Inclusive} versus
\sans{Exclusive} Charts, as well as \sans{ReadWrite} Items.
\paragraph{2.1.6.1
HighlightItem}
Highlights the given Item, in the HighlightStyle specified.
\bold{Synopsis}\block{ \sans{chart_HighlightItem( object, item )
struct chart
*object
struct chart_item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-
\sans{NonExistentItem}}
\bold{Discussion}\block{
This method is only employed when the
Client-program needs to set an Item's highlight, since the appropriate
highlighting is automatically provided by the Chart whenever the User
selects that Item.}
\paragraph{2.1.6.2
ItemHighlighted}
Yields \sans{true} if the given Item is highlighted, otherwise
\sans{false}.
\bold{Synopsis}\block{ \sans{chart_ItemHighlighted( object, item )
struct chart
*object
struct chart_Item *item
\bold{Returns}\block{
code.}}
|
NULL}}
\sans{boolean}
\italic{Result-
\bold{Exceptions}\block{
}None.
\bold{Discussion}\block{
\sans{false}
is returned.}
Where the given \sans{Item} is Null,
\paragraph{2.1.6.3
NormalizeItem}
Normalizes the given Item, with reference to the HighlightStyle
specified.
\bold{Synopsis}\block{ \sans{chart_NormalizeItem( object, item )
struct chart
*object
struct chart_item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-
\sans{NonExistentItem}}
\bold{Discussion}\block{
This method is only employed when the
Client-program needs to normalize an Item, since the appropriate
normalizing is automatically provided by the Chart's view-mechanism
whenever the User de-selects that Item.}
\subsection{2.1.7 Exception Handling}
All Chart facilities return either a \italic{result-code}, indicating the
success or failure of an operation, or a \italic{function value} such as
an
Item identifier, a scalar, or a pointer. In the charter case, you may
test
the result-code for success or failure; in the latter, the Null value is
returned for exceptional conditions. When an exception is raised, you
can
use the Exception facilities to determine its nature.
You may elect to rely upon the default responses to run-time exceptions
or
you may specify a procedure to be invoked whenever such conditions are
detected.
\paragraph{2.1.7.1
SetExceptionHandler}
Sets the given procedure as the ExceptionHandler.
\bold{Synopsis}\block{ \sans{chart_SetExceptionHandler( object, procedure
)
struct chart
long(*)()
}}
\bold{Returns}\block{
*object
procedure
|
NULL
\sans{long} \italic{
\bold{Exceptions}\block{
None.}
Result-code}}
\bold{Discussion}\block{
Where the \sans{procedure} is NULL, reverts
to
default Exception-handling operation.
Upon an exception, the \sans{procedure} is invoked with these arguments:
\indent{
\sans{anchor}
Chart's Anchor attribute
\sans{object}
Identifier of the Chart object
\sans{item}
Identifier of present Item
\sans{exception
}
Numeric-code
}
Where the \sans{item} argument identifies the Item (if any) for which the
exception was raised. The \sans{exception} argument is one of the codes
described in the chapter \italic{Problem Determination}.
}
\paragraph{2.1.7.2
ExceptionCode}
Yields the result-code of the most recent exception.
\bold{Synopsis}\block{ \sans{chart_ExceptionCode( object,)
struct chart
*object
}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code}}
None.}
\bold{Discussion}\block{
The \sans{exception_code} is one of the
codes
described in the chapter \italic{Problem Determination}.
}
\paragraph{2.1.7.3
ExceptionItem}
Yields the identifier of the Item that suffered the most recent
exceptional
condition.
\bold{Synopsis}\block{ \sans{chart_ExceptionItem( object)
struct chart
*object
}}
\bold{Returns}\block{
identifier}}
\sans{struct chart_item *}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
None.
\italic{Item
}
\section{2.2
View Object Facilities}
These facilities deal with the Chart View-object.
\subsection{2.2.1 Object Instantiation}
Chart View-objects are instantiated through either the \sans{Create} or
the
\sans{New} facility. Where the \sans{Create} facility is employed, you
can
override the default object attributes.
\paragraph{2.2.1.1
Create}
Creates an instance of the Chart View-object. Parses the optional
Specification to establish initial attributes.
\bold{Synopsis}\block{ \sans{chartv_Create( specification, anchor )
chart_Specification
specification
struct basicobject
\bold{Returns}\block{
object
identifier.}}
*anchor
|
|
NULL}}
\sans{struct chartv *}
\bold{Exceptions}\block{
NULL
\italic{Chart view-
\sans{InsufficientSpace, AttributeConflict}}
\bold{Discussion}\block{
The \sans{Create} facility establishes a
Chart
view-object through an optional Chart Specification. This
\sans{specification} argument is a pointer to a vector of symbolics,
values, or pointers to values. Such vectors are specified within the
Client program through special Chart macros, such as chart_BorderStyle,
chart_HitHandler, etc. (See section \italic{Chart Specifications}; also
chapter \italic{Sample Programs} for illustrations.) The \sans{anchor}
argument is usually the instance-pointer of the object requesting the
creation of an Chart view-object; this argument may be NULL.
The Attribute-Names are symbolics, the Attribute-Values are of the
data-type appropriate to the specific Attribute. The Attributes and
associated Values are discussed in the \italic{Concepts} chapter.}
\subsection{2.2.2 Chart Attributes}
\paragraph{2.2.2.1
SetChartAttribute}
Sets the specifed attribute to the given value.
\bold{Synopsis}\block{ \sans{chartv_SetChartAttribute( object,
attribute_value)
struct chartv
long
*object
attribute_value}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Chart View Specifications} can be set either statically or
dynamically. The syntax for this facility is that employed in the static
declaration of attributes, for example -\sans{
chartv_SetChartAttribute( object, chart_BorderStyle( chartv_Roundangle )
);}
Note that those Attributes that have an impact upon the Chart display do
not take effect until either the next FullUpdate or Update request is
effected.}
\paragraph{2.2.2.2
ChartAttribute}
Yields the value of the given Chart attribute.
\bold{Synopsis}\block{ \sans{chartv_ChartAttribute( object,
struct chartv
long
attribute)
*object
attribute
}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Value.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Chart View Specifications} can be queried.
The syntax of this facility is similar to that of the
\sans{SetChartAttribute} facility, but differs in that the parenthesized
argument is 0 (Null) -\sans{chart_ChartAttribute( object, chart_HighlightStyle(0) );}
}
\begindata{bp,539493128}
Version 2
n 0
\enddata{bp,539493128}
\view{bpv,539493128,8,0,0}
\chapter{3 Sample Programs}
Rather diverse displays can be developed for Charts. A potpourri to
stimulate the imagination:
\center{
*********************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*********************************
}
See \italic{Sample Programs}, following.
\begindata{bp,539493944}
Version 2
n 0
\enddata{bp,539493944}
\view{bpv,539493944,9,0,0}
\section{3.1
Simple Chart}
Given the program -\sans{void
char
Flavor_Choice ();
*list []
=
\{"Vanilla","Strawberry","Chocolate","Grape","Fudge",
"Licorice","Caramel","Lemon","Orange", 0 \};
chart_Specification
flavors[] =
\{
chart_HitHandler (Flavor_Choice),
chart_ItemCaptionList ( list ),
0
\};
ClientProcedure ()
\{
chart_Create ( flavors, self );
\}}
this view results (assuming appropriate height and width of the viewing
rectangle):
\center{
*********************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*********************************
}
Another sample chart is available here
\begindata{link,539845336}
Datastream version: 3
$ANDREWDIR/doc/atk/chart/sample.cht
0
0
\begindata{link,539845336}
Datastream version: 2
sample
2
black
white
\enddata{link,539845336}
\enddata{link,539845336}
\view{linkview,539845336,24,0,0}.
\begindata{bp,539495048}
Version 2
n 0
\enddata{bp,539495048}
\view{bpv,539495048,10,0,0}
\chapter{4 Problem Determination}
Compile-time problems are usually merely syntactic difficulties, and
these
would most likely occur in the declaration of a Specification structure
vector. That structure is built up through macros, which expect single
arguments. In particular, be sure to use Null as the last item in the
vector.
Run-time problems can occur at several points:
\indent{When creating the Chart object;
When setting Chart or Item Attributes;
Within HitHandlers.}
All Chart facilities return either an identifier, a scalar, or a
Result-code. Where a Result-code is returned, it should assist you in
tracking down the difficulty. Where an identifier or other value is
returned, you can still access a exception-code that should aid in
problem
determination. Such a code, as well as other inchartation, is available
through the \sans{Exception} facilities; see the section
\italic{Exception
Handling}.
There is also a built-in tracing feature, used primarily for development.
You can turn it on and off via the \sans{SetDebug} facility.
\bold{Exception Codes}
\sans{NonExistentItem}
\sans{InsufficientSpace}
\sans{AttributeConflict}
xxx
\begindata{bp,539496632}
Version 2
n 0
\enddata{bp,539496632}
\view{bpv,539496632,11,0,0}
\chapter{5 Appendices}
\section{5.1
Available Chart Classes}
The initial set of Chart Presentation classes include:
\bold{\sans{chartpie}}
Displays data collection as a Pie-chart.
outjogged.
Specified slices may be
\bold{\sans{charthst}}
Displays data collection as a Histrogram.
\
\bold{\sans{chartdot}}
Displays data collection as Dot-chart.
Dots may be connected.
\bold{\sans{chartstk}}
Displays data collection as Stacked-Histogram-chart.
\bold{\sans{chartmap}}
Displays data collection as Map-chart.
\bold{\sans{chartcsn}}
Displays data collection as Cartesian-chart.
\section{5.2
Extending the Chart Classes}
This section need only be read by those who intend to extend the set of
\italic{Chart Presentation} classes. None of this material is necessary
for those intending only to use the Chart Inset.
The Chart classes consists of not only the usual Inset pair DataObject
(\sans{chart}) and View(\sans{chartv}) subclasses, but also an extensible
set of specialized chart viewers: \sans{chartpie}, \sans{charthst},
\sans{chartdot}, etc., known as \italic{Chart Presentation} classes
Additionally, an Application subclass (\sans{charta}) exists to support
"stand-alone" operation.
Instantiated Chart objects are dynamically related according to this
structure:
\indent{\sans{
charta
chart
\
chartpie
chartv
charthst
chartobj
chartdot
...}}
(In place of \sans{charta}, the Chart Application object, EZ or any other
object might stand. Note that this diagram does not represent a
\italic{class hierarchy}, except insofaras \sans{chartpie},\sans{
charthst}, and \sans{chartdot} are subclasses of the abstract class
\sans{chartobj}.)
The \sans{chart }and \sans{chartv} objects comprise the usual Inset pair;
\sans{ chartpie}, etc, are instantiated by \sans{chartv} to support each
particular type of Chart Presentation. Each Chart Presentation class is
a
subclass of the \italic{abstract} class \sans{chartobj}. The set
\sans{chartpie}, etc, can be augmented by other Chart Presentation
classes.
The nature of these Chart Presentation classes, their interfaces and
their functionality, is covered below.
As usual, the abstract class \sans{chartobj} provides \italic{default}
procedures for all the facilities required of any Chart Presentation
subclass. Implementation of a Chart Presentation class is effected
through
the usual technique of \italic{overriding} some or all of the methods of
the \sans{chartobj} super-class. (Note that the class \sans{chartobj} is
itself a subclass of \sans{aptview}, which is in turn a subclass of the
standard abstract class \sans{view}; accordingly, methods such as
\sans{SetDataObject}, \sans{FullUpdate}, \sans{Hit}, etc, as well as
those
provided by \sans{aptview --} \sans{PrintObject}, etc -- are not
discussed.)
A Chart Presentation class depends upon the facilities provided by both
the
\sans{chartv} and the \sans{chartobj} classes. These classes are
designed
such that the programming required of each Presentation is minimal.
Specifically, a Presentation class is expected to override the following
\sans{chartobj} methods -\sans{\leftindent{DrawChart
PrintChart
HitChart
Moniker}}
Given all the housekeeping performed by the \sans{chartv} and
\sans{chartobj} classes in behalf of Chart Presentation classes, the
effort
to program a Presentation is confined to the special visuals peculiar to
each such class. (Examples such as \sans{charthst} or \sans{chartdot}
should be studied.)
The information required by a Chart Presentation class is found within
its
associated Data-object (\sans{chartv} invokes an instantiated Chart
Presentation object with the standard \sans{SetDataObject }request to
effect this association). Queries issued by the Chart Presentation
object
to its associated Data-object yield the information needed to determine
parameters such as the number of Items, the value of each Item, the Low
and
High value range for the Item set, etc. Similarly, as the User edits a
chart via a Chart Presentation object, the modifications are reflected
into
the associated Data-object; the Data-object's standard
\sans{NotifyObservers} method is called upon at appropriate times.
Beyond the specifications obtained from the associated \sans{chart}
Data-object, a Chart Presentation object should override various
\sans{chartobj} methods to provide appropriate visual support for dynamic
customizations such as User-specified fonts, Foreground and Background
color, etc.
\begindata{bp,539506136}
Version 2
n 0
\enddata{bp,539506136}
\view{bpv,539506136,12,0,0}
By way of example, the chart -\center{\typewriter{
**************************************
*
Inches of Rainfall
*
*
*
*
*
*
***
1980
*
*
*
*
********
1981
*
*
*
*
*********************
1982
*
*
*
******
1983
*
*
*
*
***********
1984
*
*
*
*
*
*
********************
1985
*
*
**************************************
}}
would be produced by the display class \sans{\bold{charthst}} upon being
associated with a Chart Data-object whose specifications were generated
through these requests:
\indent{\sans{SetChartAttribute( object,
Rainfall" ) )
CreateItem( object, "1980",
);
CreateItem( object, "1981",
);
CreateItem( object, "1982",
);
CreateItem( object, "1983",
);
CreateItem( object, "1984",
);
CreateItem( object, "1985",
);}}
chart_TitleCaption( "Inches of
In the same vein, these same specifications (ie, the same Chart
Data-object) could be viewed by the Chart Presentation class
\sans{\bold{chartdot}}, with this result -\center{\typewriter{
**************************************
*
Inches of Rainfall
*
*
*
*
*
*
*
*
.
*
.
*
.
*
.
*
*
*
.
*
*
*
.
.
*
*
.
*
.
.
.
.
.
*
.
.
*
*
*
*
*
. .
*
*
*
*
*
*
*
*
*
* 1980
1981
1982
1983
1984
1985 *
*
*
**************************************
}}
Depending upon the semantics of the individual Chart Presentation
classes,
these particular requests might or might not result in a meaningful
display.
\begindata{bp,539507912}
Version 2
n 0
\enddata{bp,539507912}
\view{bpv,539507912,13,0,0}
\bold{Chart Presentation Editing}
In addition to the requirements that a Chart Presentation class implement
both the operations needed to generate a screen visual and those needed
to
generate the appropriate PrintStream, each such class is required to
support \italic{interactive editing} of its associated \sans{chart}
Data-object. This requirement is by far the most difficult to meet.
There is a \italic{style} for editing Charts. While the following points
attempt to describe that style, the best recourse is extensive use and
study of those Chart Presentation classes distributed with the system.
The
intent is to offer the User a homogeneous collection of diverse charting
features, each developed according to the \italic{Principle of Least
Surprise}. Among other factors, this principle guarantees the User that
the techniques learned to work with one Chart Presentation class can be
employed to manipulate any other Chart Presentation class. (Developers
who
ignore this consideration might find their audience considerably
diminished.)
x
\begindata{bp,539508872}
Version 2
n 0
\enddata{bp,539508872}
\view{bpv,539508872,14,0,0}
Copyright 1992 Carnegie Mellon University and IBM.
All rights reserved.
\smaller{\smaller{$Disclaimer:
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name of IBM not be used in advertising or
publicity pertaining to distribution of the software without specific,
written prior permission.
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ANY COPYRIGHT
HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
$
}}\enddata{text,538429080}