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:1];
        [adapter renderPlot];
        [adapter release];
        [pool release];
        return 0;
    }
    

Compile using:
gcc -ObjC main.c -o aqtex -lobjc -framework AquaTerm -framework Foundation
or
gcc main.m -o aqtex -framework AquaTerm -framework Foundation

Global Constants

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;

const int AQTAlignMiddle;

const int AQTAlignBaseline;

const int AQTAlignBottom;

const int AQTAlignTop;

Description:

Constants that specify horizontal and vertical alignment for labels. See addLabel:atPoint:angle:align: for definitions and use.

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
Clip rect, applies to all objects
- setClipRect:
- setDefaultClipRect
Colormap (utility)
- colormapSize
- setColormapEntry:red:green:blue:
- getColormapEntry:red:green:blue:
- takeColorFromColormapEntry:
- takeBackgroundColorFromColormapEntry:
Color handling
- setColorRed:green:blue:
- setBackgroundColorRed:green:blue:
- getColorRed:green:blue:
- getBackgroundColorRed:green:blue:
Text handling
- setFontname:
- setFontsize:
- addLabel:atPoint:
- addLabel:atPoint:angle:align:
- addLabel:atPoint:angle:shearAngle:align:
Line handling
- setLinewidth:
- setLinestylePattern:count:phase:
- setLinestyleSolid
- 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:
- addTransformedImageWithBitmap:size:

Instance Methods

addEdgeToVertexPoint:

- (void) addEdgeToVertexPoint:(NSPoint)point

No method description.

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:

- (void) addLabel:(id)text atPoint:(NSPoint)pos

Convenience form of addLabel:atPoint:angle:shearAngle:align: for horizontal, left and baseline aligned text.

addLabel:atPoint:angle:align:

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

Same as addLabel:atPoint:angle:shearAngle:align: except that shearAngle defaults to 0.

addLabel:atPoint:angle:shearAngle:align:

- (void) addLabel:(id)text atPoint:(NSPoint)pos angle:(float)angle shearAngle:(float)shearAngle 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).
Horizontal AlignDescription
AQTAlignLeftLeft aligned text
AQTAlignCenterCentered text
AQTAlignRightRight aligned text
VerticalAlign-
AQTAlignMiddleApproximate centerline
AQTAlignBaselineNormal
AQTAlignBottomBottom bounds of this string
AQTAlignTopTop bounds of this string
By specifying shearAngle the text may be sheared in order to appear correctly in e.g. 3D plot labels. 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
Attributevalue
@"NSSuperScript"raise-level -3 to 3, default is 0
@"NSUnderline"0 or 1

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:

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

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

addTransformedImageWithBitmap:size:clipRect:

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

Deprecated, use addTransformedImageWithBitmap:size: instead. 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 available in the currently active colormap.

eraseRect:

- (void) eraseRect:(NSRect)aRect

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

getBackgroundColorRed:green:blue:

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

Get background color components by reference.

getColorRed:green:blue:

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

Get current RGB color components by reference.

getColormapEntry:red:green:blue:

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

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

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

No method description.

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.

setClipRect:

- (void) setClipRect:(NSRect)clip

Set a clipping region (rectangular) to apply to all subsequent operations, until changed again by setClipRect: or setDefaultClipRect.

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 colormap, at the position given by entryIndex.

setDefaultClipRect

- (void) setDefaultClipRect

Restore clipping region to the deafult (object bounds), i.e. no clipping performed.

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 string formatDescription
0No event (time-out)
1:x,y:buttonMouse down event
2:x,y:keyKey down event
42:x,y:keyServer error
43:x,y:keyGeneral error

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.
capStyleDescription
AQTButtLineCapStyleLine does not extend beyond endpoint
AQTRoundLineCapStyleLine extends into half-circle beyond endpoint
AQTSquareLineCapStyleLine extends into half-square beyond endpoint
Default is RoundLineCapStyle.

setLinestylePattern:count:phase:

- (void) setLinestylePattern:(float *)newPattern count:(int)newCount phase:(float)newPhase

Set the current line style to pattern style, used for all subsequent lines. The linestyle is specified as a pattern, an array of at most 8 float, where even positions correspond to dash-lengths and odd positions correspond to gap-lengths. To produce e.g. a dash-dotted line, use the pattern {4.0, 2.0, 1.0, 2.0}.

setLinestyleSolid

- (void) setLinestyleSolid

Set the current line style to solid, used for all subsequent lines. This is the default.

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 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 colormap.

waitNextEvent

- (NSString *) waitNextEvent

No method description.