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
const int AQTButtLineCapStyle;
const int AQTRoundLineCapStyle;
const int AQTSquareLineCapStyle;
const int AQTAlignLeft;
const int AQTAlignCenter;
const int AQTAlignRight;
const int AQTAlignMiddle;
const int AQTAlignBaseline;
const int AQTAlignBottom;
const int AQTAlignTop;
Class initialization etc. Control operationsEvent handling Plotting related commands
- - openPlotWithIndex:
- - selectPlotWithIndex:
- - setPlotSize:
- - setPlotTitle:
- - renderPlot
- - clearPlot
- - closePlot
Clip rect, applies to all objects Colormap (utility)
Color handling
- - colormapSize
- - setColormapEntry:red:green:blue:
- - getColormapEntry:red:green:blue:
- - takeColorFromColormapEntry:
- - takeBackgroundColorFromColormapEntry:
Text handling
- - setColorRed:green:blue:
- - setBackgroundColorRed:green:blue:
- - getColorRed:green:blue:
- - getBackgroundColorRed:green:blue:
Line handling
- - setFontname:
- - setFontsize:
- - addLabel:atPoint:
- - addLabel:atPoint:angle:align:
- - addLabel:atPoint:angle:shearAngle:align:
Rect and polygon handling Image handling
- - setLinewidth:
- - setLinestylePattern:count:phase:
- - setLinestyleSolid
- - setLineCapStyle:
- - moveToPoint:
- - addLineToPoint:
- - addPolylineWithPoints:pointCount:
- (void)
addFilledRect:(NSRect)aRect
Add a filled rectangle. Will attempt to remove any objects that will be covered by aRect.
- (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.
- (void)
addLabel:(id)text
atPoint:(NSPoint)pos
Convenience form of addLabel:atPoint:angle:shearAngle:align: for horizontal, left and baseline aligned text.
- (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.
- (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 Align | Description |
| AQTAlignLeft | Left aligned text |
| AQTAlignCenter | Centered text |
| AQTAlignRight | Right aligned text |
| VerticalAlign | - |
| AQTAlignMiddle | Approximate centerline |
| AQTAlignBaseline | Normal |
| AQTAlignBottom | Bottom bounds of this string |
| AQTAlignTop | Top bounds of this string |
| Attribute | value |
| @"NSSuperScript" | raise-level -3 to 3, default is 0 |
| @"NSUnderline" | 0 or 1 |
- (void)
addLineToPoint:(NSPoint)point
Add a line segment from the current point (given by a previous moveToPoint: or addLineToPoint).
- (void)
addPolygonWithVertexPoints:(NSPoint *)points
pointCount:(int)pc
Add a polygon specified by a list of corner points. Number of corners is passed in pc.
- (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.
- (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.
- (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.
- (void)
clearPlot
Clears the current plot and resets default values. To keep plot settings, use eraseRect: instead.
- (void)
closePlot
Closes the current plot but leaves viewer window on screen. Disables event handling.
- (int)
colormapSize
Return the number of color entries available in the currently active colormap.
- (void)
eraseRect:(NSRect)aRect
Remove any objects completely inside aRect. Does not force a redraw of the plot.
- (void)
getBackgroundColorRed:(float *)r
green:(float *)g
blue:(float *)b
Get background color components by reference.
- (void)
getColorRed:(float *)r
green:(float *)g
blue:(float *)b
Get current RGB color components by reference.
- (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.
- (id)
init
Initializes an instance and sets up a connection to the handler object via DO. Launches AquaTerm if necessary.
- (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.
- (NSString *)
lastEvent
Reads the last event logged by the viewer. Will always return NoEvent unless setAcceptingEvents: is called with a YES argument.
- (void)
moveToPoint:(NSPoint)point
Moves the current point (in canvas coordinates) in preparation for a new sequence of line segments.
- (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.
- (void)
resetImageTransform
Set transformation matrix to unity, i.e. no transform.
- (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.
- (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.
- (void)
setBackgroundColorRed:(float)r
green:(float)g
blue:(float)b
Set the background color, overriding any previous color, using explicit RGB components.
- (void)
setClipRect:(NSRect)clip
Set a clipping region (rectangular) to apply to all subsequent operations, until changed again by setClipRect: or setDefaultClipRect.
- (void)
setColorRed:(float)r
green:(float)g
blue:(float)b
Set the current color, used for all subsequent items, using explicit RGB components.
- (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.
- (void)
setDefaultClipRect
Restore clipping region to the deafult (object bounds), i.e. no clipping performed.
- (void)
setErrorHandler:(void (*)(NSString *msg))fPtr
Optionally set an error handling routine of the form customErrorHandler(NSString *errMsg) to override default behaviour.
- (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 format | Description |
| 0 | No event (time-out) |
| 1:x,y:button | Mouse down event |
| 2:x,y:key | Key down event |
| 42:x,y:key | Server error |
| 43:x,y:key | General error |
- (void)
setFontname:(NSString *)newFontname
Set the font to be used. Applies to all future operations. Default is Times-Roman.
- (void)
setFontsize:(float)newFontsize
Set the font size in points. Applies to all future operations. Default is 14pt.
- (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.
- (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 | Line does not extend beyond endpoint |
| AQTRoundLineCapStyle | Line extends into half-circle beyond endpoint |
| AQTSquareLineCapStyle | Line extends into half-square beyond endpoint |
- (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}.
- (void)
setLinestyleSolid
Set the current line style to solid, used for all subsequent lines. This is the default.
- (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.
- (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.
- (void)
setPlotTitle:(NSString *)title
Set title to appear in window titlebar, also default name when saving.
- (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.
- (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.