\begindata{text,539040528}
\textdsversion{12}
\template{default}
\define{itemize
menu:[Region,Itemize]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{enumerate
menu:[Region,Enumerate]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{programexample
menu:[Region,ProgramExample]
attr:[Justification LeftJustified Point 0]
attr:[FontFamily Helvetica Int 0]}
\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]}
\italic{styingg}
\begindata{bp,538928712}
\enddata{bp,538928712}
\view{bpv,538928712,1128,0,0}
\center{
\bigger{\bigger{\bold{\bigger{\bigger{Chart}}
Programming Guide}}}
Information Technology Center
Carnegie Mellon University
TC Peters
(3/1/89)
9/6/89
\bold{ Working Draft }
\bold{SUBJECT
TO
SIGNIFICANT
REVISION }
\bold{(c) IBM Corporation
1989}}
\begindata{bp,538271624}
\enddata{bp,538271624}
\view{bpv,538271624,1129,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,538929288}
\enddata{bp,538929288}
\view{bpv,538929288,1130,0,0}
\bold{Introduction}
xxx
\begindata{bp,538928968}
\enddata{bp,538928968}
\view{bpv,538928968,1131,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,538929224}
\enddata{bp,538929224}
\view{bpv,538929224,1132,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,538929032}
\enddata{bp,538929032}
\view{bpv,538929032,1133,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,538929736}
\enddata{bp,538929736}
\view{bpv,538929736,1134,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.
Position-n.}
The first Item is at Position-1, the nth at
\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,538929416}
\enddata{bp,538929416}
\view{bpv,538929416,1135,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 *}
\bold{Exceptions}\block{
|
\italic{Chart Data-
\sans{InsufficientSpace, AttributeConflict}}
\bold{Discussion}\block{
The \sans{Create} facility establishes a
Chart
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 instancepointer 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 datatype
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 verb-prefix
\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{
Result-code.}}
None.}
\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
long(*)()
struct dataobject
long
*object
procedure
*anchor
datum}}
\bold{Returns}\block{
value.}}
\sans{long} \italic{
Client returned-
\bold{Exceptions}\block{
\sans{ApplyInterrupte}d}
\bold{Discussion}\block{
arguments,
in the order shown:
The \sans{procedure} is invoked with these
\indent{\sans{anchor}
Given \sans{anchor}-value
\sans{object}
\sans{item}
\sans{datum}
Identifier of the Chart object
Identifier of present Item
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 verb-prefix
\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
long
*object
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 *}
\bold{Exceptions}\block{
\italic{
Item
None.}
\bold{Discussion}\block{
Where no Item Name matches the given Name,
the 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
struct chart_Item *item
*object
|
NULL}}
\bold{Returns}\block{
code.}}
\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
*object
long(*)()
procedure
}}
\bold{Returns}\block{
|
NULL
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code}}
None.}
\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.
}
\section{2.2
View Object Facilities}
These facilities deal with the Chart View-object.
\subsection{2.2.1 Object Instantiation}
\italic{Item
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 instancepointer 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 datatype
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
}}
*object
attribute
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,538929160}
\enddata{bp,538929160}
\view{bpv,538929160,1136,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,538928776}
\enddata{bp,538928776}
\view{bpv,538928776,1137,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{
*********************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*********************************
}
\section{3.2
Simple Print Chart}
xxxx
\section{3.3
Variation}
xxxx
\begindata{bp,538929352}
\enddata{bp,538929352}
\view{bpv,538929352,1138,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 Resultcode.
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,538929096}
\enddata{bp,538929096}
\view{bpv,538929096,1139,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.
\bold{\sans{charthst}}
Displays data collection as a Histrogram.
Specified slices may be
\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{
chart
charta
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,538928840}
\enddata{bp,538928840}
\view{bpv,538928840,1140,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 Dataobject)
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,538928648}
\enddata{bp,538928648}
\view{bpv,538928648,1141,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,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1143,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 is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice, this permission notice, and the following
disclaimer appear in supporting documentation, and that the names of
IBM, Carnegie Mellon University, and other copyright holders, not be
used in advertising or publicity pertaining to distribution of the
software
without specific, written prior permission.
IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS
DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
IN NO EVENT
SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER 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,539040528}