AQTAdapter


Inherits From:
NSObject
Declared In:
AQTAdapter.h


Class Description

AQTAdapter is a class that provides an interface to the functionality of AquaTerm. As such, it bridges the gap between client's procedural calls requesting operations such as drawing a line or placing a label and the object-oriented graph being built. The actual assembling of the graph is performed by an instance of class AQTPlotBuilder.

It seemlessly provides a connection to the viewer (AquaTerm.app) without any work on behalf of the client.

It also provides some utility functionality such an indexed colormap, and an optional error handling callback function for the client.

Event handling of user input is provided through an optional callback function.

Example: HelloAquaTerm.c     
    #import <Foundation/Foundation.h>
    #import "aquaterm/AQTAdapter.h"
    
    int main(void)
    {    
        NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
        AQTAdapter *adapter = [[AQTAdapter alloc] init];
        [adapter openPlotWithIndex:1];
        [adapter setPlotSize:NSMakeSize(600,400)];
        [adapter addLabel:@"HelloAquaTerm!" atPoint:NSMakePoint(300, 200) angle:0.0 align:AQTAlignCenter];
        [adapter renderPlot];
        [adapter release];
        [pool release];
        return 0;
    }
    

gcc -ObjC main.c -o aqtex -I/Users/per/include -L/Users/per/lib -lobjc -laqt -framework Foundation
gcc main.m -o aqtex -I/Users/per/include -L/Users/per/lib -laqt -framework Foundation


Global Variables

Synopsis:

const int AQTButtLineCapStyle;
const int AQTRoundLineCapStyle;
const int AQTSquareLineCapStyle;

Description:

Constants that specify linecap styles.

Synopsis:

const int AQTAlignLeft;
const int AQTAlignCenter;
const int AQTAlignRight;

Description:

Constants that specify horizontal alignment for labels.

Synopsis:

const int AQTAlignMiddle;
const int AQTAlignBaseline;
const int AQTAlignBottom;
const int AQTAlignTop;

Description:

Constants that specify vertical alignment for labels.


Instance Variables

AQTClientManager *_clientManager;
AQTPlotBuilder *_selectedBuilder;
id _aqtReserved1;
id _aqtReserved2;

_clientManager No description.
_selectedBuilder No description.
_aqtReserved1 No description.
_aqtReserved2 No description.


Method Types

Class initialization etc.
- init
- initWithServer:
- setErrorHandler:
- setEventHandler:
Control operations
- openPlotWithIndex:
- selectPlotWithIndex:
- setPlotSize:
- setPlotTitle:
- renderPlot
- clearPlot
- closePlot
Event handling
- setAcceptingEvents:
- lastEvent
- waitNextEvent
Plotting related commands
Colormap (utility), one per open plot.
- colormapSize
- setColormapEntry:red:green:blue:
- getColormapEntry:red:green:blue:
- takeColorFromColormapEntry:
- takeBackgroundColorFromColormapEntry:
Color handling
- setColorRed:green:blue:
- setBackgroundColorRed:green:blue:
- getCurrentColorRed:green:blue:
Text handling
- setFontname:
- setFontsize:
- addLabel:atPoint:angle:align:
Line handling
- setLinewidth:
- setLineCapStyle:
- moveToPoint:
- addLineToPoint:
- addPolylineWithPoints:pointCount:
Rect and polygon handling
- moveToVertexPoint:
- addEdgeToVertexPoint:
- addPolygonWithVertexPoints:pointCount:
- addFilledRect:
- eraseRect:
Image handling
- setImageTransformM11:m12:m21:m22:tX:tY:
- resetImageTransform
- addImageWithBitmap:size:bounds:
- addTransformedImageWithBitmap:size:clipRect:

Instance Methods

addEdgeToVertexPoint:

- (void)addEdgeToVertexPoint:(NSPoint)point

Add an edge to a polygon (filled). See addLineToPoint:.


addFilledRect:

- (void)addFilledRect:(NSRect)aRect

Add a filled rectangle. Will attempt to remove any objects that will be covered by aRect.


addImageWithBitmap:size:bounds:

- (void)addImageWithBitmap:(const void *)bitmap size:(NSSize)bitmapSize bounds:(NSRect)destBounds

Add a bitmap image of size bitmapSize scaled to fit destBounds, does not apply transform. Bitmap format is 24bits per pixel in sequence RGBRGB... with 8 bits per color.


addLabel:atPoint:angle:align:

- (void)addLabel:(id)text atPoint:(NSPoint)pos angle:(float)angle align:(int)just

Add text at coordinate given by pos, rotated by angle degrees and aligned vertically and horisontally (with respect to pos and rotation) according to align. Horizontal and vertical align may be combined by an OR operation, e.g. (AQTAlignCenter | AQTAlignMiddle).
HorizontalAlign Description
AQTAlignLeft Left aligned
AQTAlignCenter Centered
AQTAlignRight Right aligned
VerticalAlign -
AQTAlignMiddle Approximate mid-height
AQTAlignBaseline Normal
AQTAlignBottom Bottom bounds of THIS string
AQTAlignTop Top bounds of THIS string
The text can be either an NSString or an NSAttributedString. By using NSAttributedString a subset of the attributes defined in AppKit may be used to format the string beyond the fontface ans size. The currently supported attributes are
Attribute value
@"NSSuperScript" 1 or -1 for super-/subscript
@"NSUnderline" 0 or 1 for (no) underline


addLineToPoint:

- (void)addLineToPoint:(NSPoint)point

Add a line segment from the current point (given by a previous moveToPoint: or addLineToPoint).


addPolygonWithVertexPoints:pointCount:

- (void)addPolygonWithVertexPoints:(NSPoint *)points pointCount:(int)pc

Add a polygon specified by a list of corner points. Number of corners is passed in pc.


addPolylineWithPoints:pointCount:

- (void)addPolylineWithPoints:(NSPoint *)points pointCount:(int)pc

Add a sequence of line segments specified by a list of start-, end-, and joinpoint(s) in points. Parameter pc is number of line segments + 1.


addTransformedImageWithBitmap:size:clipRect:

- (void)addTransformedImageWithBitmap:(const void *)bitmap size:(NSSize)bitmapSize clipRect:(NSRect)destBounds

Add a bitmap image of size bitmapSize honoring transform, transformed image is clipped to destBounds. Bitmap format is 24bits per pixel in sequence RGBRGB... with 8 bits per color.


clearPlot

- (void)clearPlot

Clears the current plot and resets default values. To keep plot settings, use eraseRect: instead.


closePlot

- (void)closePlot

Closes the current plot but leaves viewer window on screen. Disables event handling.


colormapSize

- (int)colormapSize

Return the number of color entries availabel in the currently active colormap.


eraseRect:

- (void)eraseRect:(NSRect)aRect

Remove any objects completely inside aRect. Does not force a redraw of the plot.


getColormapEntry:red:green:blue:

- (void)getColormapEntry:(int)entryIndex red:(float *)r green:(float *)g blue:(float *)b

Get the RGB entry in the current colormap, at the position given by entryIndex.


getCurrentColorRed:green:blue:

- (void)getCurrentColorRed:(float *)r green:(float *)g blue:(float *)b

Get current RGB color components by reference.


init

- (id)init

Initializes an instance and sets up a connection to the handler object via DO. Launches AquaTerm if necessary.


initWithServer:

- (id)initWithServer:(id)localServer

This is the designated initalizer, allowing for the default handler (an object vended by AquaTerm via OS X's distributed objects mechanism) to be replaced by a local instance. In most cases init should be used, which calls initWithHandler: with a nil argument.


lastEvent

- (NSString *)lastEvent

Reads the last event logged by the viewer. Will always return NoEvent unless setAcceptingEvents: is called with a YES argument.


moveToPoint:

- (void)moveToPoint:(NSPoint)point

Moves the current point (in canvas coordinates) in preparation for a new sequence of line segments.


moveToVertexPoint:

- (void)moveToVertexPoint:(NSPoint)point

Begin a polygon (filled). See moveToPoint:.


openPlotWithIndex:

- (void)openPlotWithIndex:(int)refNum

Open up a new plot with internal reference number refNum and make it the target for subsequent commands. If the referenced plot already exists, it is selected and cleared. Disables event handling for previously targeted plot.


renderPlot

- (void)renderPlot

Render the current plot in the viewer.


resetImageTransform

- (void)resetImageTransform

Set transformation matrix to unity, i.e. no transform.


selectPlotWithIndex:

- (BOOL)selectPlotWithIndex:(int)refNum

Get the plot referenced by refNum and make it the target for subsequent commands. If no plot exists for refNum, the currently targeted plot remain unchanged. Disables event handling for previously targeted plot. Returns YES on success.


setAcceptingEvents:

- (void)setAcceptingEvents:(BOOL)flag

Inform AquaTerm whether or not events should be passed from the currently selected plot. Deactivates event passing from any plot previously set to pass events.


setBackgroundColorRed:green:blue:

- (void)setBackgroundColorRed:(float)r green:(float)g blue:(float)b

Set the background color, overriding any previous color, using explicit RGB components.


setColorRed:green:blue:

- (void)setColorRed:(float)r green:(float)g blue:(float)b

Set the current color, used for all subsequent items, using explicit RGB components.


setColormapEntry:red:green:blue:

- (void)setColormapEntry:(int)entryIndex red:(float)r green:(float)g blue:(float)b

Set an RGB entry in the current colormap, at the position given by entryIndex.


setErrorHandler:

- (void)setErrorHandler:(void (*)(NSString *msg))fPtr

Optionally set an error handling routine of the form customErrorHandler(NSString *errMsg) to override default behaviour.


setEventHandler:

- (void)setEventHandler:(void (*)(int index, NSString *event))fPtr

Optionally set an event handling routine of the form customEventHandler(int index, NSString *event). The reference number of the plot that generated the event is passed in index and the structure of the string event is @"type:data1:data2:..." Currently supported events are:
event description
0 No event
1:{x, y}:button Mouse down at (x, y) left (button=1) or right (button=2) button pressed
2:{x,y}:key Key key pressed while cursor over (x, y)
42:{x, y}:key Server error x,y and key are random
43:{x,y}:key Error x,y and key are random


setFontname:

- (void)setFontname:(NSString *)newFontname

Set the font to be used. Applies to all future operations. Default is Times-Roman.


setFontsize:

- (void)setFontsize:(float)newFontsize

Set the font size in points. Applies to all future operations. Default is 14pt.


setImageTransformM11:m12:m21:m22:tX:tY:

- (void)setImageTransformM11:(float)m11 m12:(float)m12 m21:(float)m21 m22:(float)m22 tX:(float)tX tY:(float)tY

Set a transformation matrix for images added by addTransformedImageWithBitmap:size:clipRect:, see NSImage documentation for details.


setLineCapStyle:

- (void)setLineCapStyle:(int)capStyle

Set the current line cap style (in points), used for all subsequent lines. Any line currently being built by moveToPoint:/addLineToPoint will be considered finished since any coalesced sequence of line segments must share the same cap style.
capStyle Description
AQTButtLineCapStyle Butt line caps
AQTRoundLineCapStyle Rounded line caps
AQTSquareLineCapStyle Square line caps
Default is AQTRoundLineCapStyle.


setLinewidth:

- (void)setLinewidth:(float)newLinewidth

Set the current linewidth (in points), used for all subsequent lines. Any line currently being built by moveToPoint:/addLineToPoint will be considered finished since any coalesced sequence of line segments must share the same linewidth. Default linewidth is 1pt.


setPlotSize:

- (void)setPlotSize:(NSSize)canvasSize

Set the limits of the plot area. Must be set before any drawing command following an openPlotWithIndex: or clearPlot command or behaviour is undefined.


setPlotTitle:

- (void)setPlotTitle:(NSString *)title

Set title to appear in window titlebar, also default name when saving.


takeBackgroundColorFromColormapEntry:

- (void)takeBackgroundColorFromColormapEntry:(int)index

Set the background color, overriding any previous color, using the color stored at the position given by index in the current colormap.


takeColorFromColormapEntry:

- (void)takeColorFromColormapEntry:(int)index

Set the current color, used for all subsequent items, using the color stored at the position given by index in the current colormap.


waitNextEvent

- (NSString *)waitNextEvent

Block until event recieved. See setEventHandler: for a description of the information returned. Will return a NoEvent after a certain time.


Version 1.1 Copyright ©2003 by AquaTerm. All Rights Reserved. Mon Dec 29 23:43:45 2003