SoundView

SoundView

Inherits From: View : Responder : Object

Declared In: soundkit/SoundView.h

Class Description

A SoundView object provides a graphical representation of sound data. This data is taken from an associated Sound object. In addition to displaying a Sound object's data, a SoundView provides methods that let you play and record into the Sound object, and peform simple cut, copy, and paste editing of its data. A cursor into the display is provided, allowing the user to set the insertion point and to create a selection over the sound data.

Sound Display
Sounds are displayed on a two-dimensional graph. The amplitudes of individual samples are measured vertically and plotted against time, which proceeds left to right along the horizontal axis. A SoundView's coordinate system is scaled and translated (vertically) so full amplitude fits within the bounds rectangle with 0.0 amplitude running through the center of the view.
For many sounds, the length of the sound data in samples is greater than the horizontal measure of the bounds rectangle. A SoundView employs a reduction factor to determine the ratio of samples to display units and plots the minimum and maximum amplitude values of the samples within that ratio. For example, a reduction factor of 10.0 means that the minimum and maximum values among the first ten samples are plotted in the first display unit, the minimum and maximum values of the next ten samples are displayed in the second display unit and so on.
Lines are drawn between the chosen values to yield a continuous shape. Two drawing modes are provided:

In NX_SOUNDVIEW_WAVE mode, the drawing is rendered in an oscilloscopic fashion.

In NX_SOUNDVIEW_MINMAX mode, two lines are drawn, one to connect the maximum values, and one to connect the minimum values.

As you zoom in (as the reduction factor decreases), the two drawing modes become indistinguishable.

Autoscaling the Display
When a SoundView's sound data changes (due to editing or recording), the manner in which the SoundView is redisplayed depends on its autoscale flag. With autoscaling disabled, the SoundView's frame grows or shrinks (horizontally) to fit the new sound data and the reduction factor is unchanged. If autoscaling is enabled, the reduction factor is automatically recomputed to maintain a constant frame size. By default, autoscaling is disabled; this is to accommodate the use of a SoundView object as the document of a ScrollView.

Instance Variables

id sound;
id reduction;
id delegate;
NXRect selectionRect;
int displayMode;
float backgroundGray;
float foregroundGray;
float reductionFactor;
struct {
unsigned int disabled:1;
unsigned int continuous:1;
unsigned int calcDrawInfo:1;
unsigned int selectionDirty:1;
unsigned int autoscale:1;
unsigned int bezeled:1;
unsigned int notEditable:1;
unsigned int notOptimizedForSpeed:1;
} svFlags;

sound The object's Sound.

reduction The data reduced version of the object's Sound.

delegate The object's delegate.

selectionRect The object's current selection.

displayMode Display mode; NX_SOUNDVIEW_MINMAX by default.

backgroundGray Background color; NX_WHITE by default.

foregroundGray Foreground color; NX_BLACK by default.

reductionFactor The ratio of sound samples to display units.

svFlags.disabled Does the object (not) respond to mouse events?

svFlags.continuous Does the object respond to mouse dragged events?

svFlags.calcDrawInfo Does drawing info need to be recalculated?

svFlags.selectionDirty Has the object changed (but not been played)?

svFlags.autoscale Does it rescale the display when the sound data changes?

svFlags.bezeled Does the object have a bezeled border?

svFlags.notEditable Is the sound data not editable?

svFlags.notOptimizedForSpeed Is the object not optimized for fast loading?

Method Types

Initializing a SoundView object initFrame:

Freeing a SoundView instance free

Modifying the object scaleToFit

setBackgroundGray:
setBezeled:
setContinuous:
setDelegate:
setDisplayMode:
setEnabled:
setForegroundGray:
setOptimizedForSpeed:
setSound:
sizeToFit

Querying the object backgroundGray

delegate
displayMode
foregroundGray
getSelection:size:
isAutoScale
isBezeled
isContinuous
isEnabled
isOptimizedForSpeed
reductionFactor
sound

Selecting and editing the sound data

copy:

cut:
delete:
mouseDown:
paste:
selectAll:
setSelection:size:
isEditable
setEditable:

Pasteboard and Services support pasteboard:provideData:

readSelectionFromPasteboard:
validRequestorForSendType:andReturnType:
writeSelectionToPasteboard:types:

Modifying the display coordinates

setAutoscale:

setReductionFactor:

Drawing the object drawSelf::

drawSamplesFrom:to:
hideCursor
showCursor
sizeTo::

Responding to events acceptsFirstResponder

becomeFirstResponder
resignFirstResponder

Performing the sound data pause:

isPlayable
play:
record:
resume:
soundBeingProcessed
stop:

Archiving the object read:

write:

Accessing the delegate didPlay:

didRecord:
hadError:
tellDelegate:
willPlay:
willRecord:

Instance Methods

acceptsFirstResponder

(BOOL)acceptsFirstResponder

If the SoundView is enabled, this returns YES, allowing the SoundView to become the first responder. Otherwise, it returns NO. This method is automatically invoked by objects defined by the Application Kit; you should never need to invoke it directly.

backgroundGray

(float)backgroundGray

Returns the SoundView's background gray value (NX_WHITE by default).

becomeFirstResponder

becomeFirstResponder

Promotes the SoundView to first responder. You never invoke this method directly. Returns self.

copy:

copy:sender

Copies the current selection to the pasteboard. Returns self.

cut:

cut:sender

Deletes the current selection from the SoundView, copies it to the pasteboard, and sends a soundDidChange: message to the delegate. The insertion point is positioned to where the selection used to start. Returns self.

delegate

delegate

Returns the SoundView's delegate object.

delete:

delete:sender

Deletes the current selection from the SoundView's Sound and sends the soundDidChange: message to the delegate. The deletion isn't placed on the pasteboard. Returns self.

didPlay:

didPlay:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

didRecord:

didRecord:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

displayMode

(int)displayMode

Returns the SoundView's display mode, one of NX_SOUNDVIEW_WAVE (oscilloscopic display) or NX_SOUNDVIEW_MINMAX (minimum/maximum display; this is the default).

drawSamplesFrom:to:

drawSamplesFrom:(int)first to:(int)last

Redisplays the given range of samples. Return self.

drawSelf::

drawSelf:(const NXRect *)rects :(int)rectCount

Displays the SoundView's sound data. The selection is highlighted and the cursor is drawn (if it isn't currently hidden). Returns self.
You never send the drawSelf:: message directly to a SoundView object. To cause a SoundView to draw itself, send it one of the display messages defined by the View class.

foregroundGray

(float)foregroundGray

Returns the SoundView's foreground gray value (NX_BLACK by default).

free

free

Frees the SoundView but not its Sound object nor its delegate. The willFree: message is sent to the delegate.

getSelection:size:

getSelection:(int *)firstSample size:(int *)sampleCount

Returns the selection by reference. The index of the selection's first sample (counting from 0) is returned in firstSample. The size of the selection in samples is returned in sampleCount. The method itself returns self.

hadError:

hadError:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

hideCursor

hideCursor

Hides the SoundView's cursor. This is usually handled automatically. Returns self.

initFrame:

initFrame:(const NXRect *)frameRect

Initializes the SoundView, fitting the object within the rectangle pointing to by frameRect. The initialized SoundView doesn't contain any sound data. Returns self.

isAutoScale

(BOOL)isAutoScale

Returns YES if the SoundView is in autoscaling mode, otherwise returns NO.

isBezeled

(BOOL)isBezeled

Returns YES if the SoundView has a bezeled border, otherwise returns NO (the default).

isContinuous

(BOOL)isContinuous

Returns YES if the SoundView responds to mouse-dragged events (as set through setContinuous:). The default is NO.

isEditable

(BOOL)isEditable

Returns YES if the SoundView's sound data can be edited.

isEnabled

(BOOL)isEnabled

Returns YES if the SoundView is enabled, otherwise returns NO. The mouse has no effect in a disabled SoundView. By default, a SoundView is enabled.

isOptimizedForSpeed

(BOOL)isOptimizedForSpeed

Returns YES if the SoundView is optimized for speedy display. SoundViews are optimized by default.

isPlayable

(BOOL)isPlayable

Returns YES if the SoundView's sound data can be played without first being converted.

mouseDown:

mouseDown:(NXEvent *)theEvent

Allows a selection to be defined by clicking and dragging the mouse. This method takes control until a mouse-up occurs. While dragging, the selected region is highlighted. On mouse up, the delegate is sent the selectionChanged: message. If isContinuous is YES, selectionChanged: messages are also sent while the mouse is being dragged. You never invoke this method; it's invoked automatically in response to the user's actions. Returns self.

paste:

paste:sender

Replaces the current selection with a copy of the sound data currently on the pasteboard. If there is no selection the pasteboard data is inserted at the cursor position. The pasteboard data must be compatible with the SoundView's data, as determined by the Sound method compatibleWith:. If the paste is successful, the soundDidChange: message is sent to the delegate. Returns self.

pasteboard:provideData:

pasteboard:thePasteboard provideData:(const char *)pboardType

Places the SoundView's entire sound on the given pasteboard. Currently, the pboardType argument must be "NXSoundPboardType", the pasteboard type that represents sound data. Returns self.

pause:

pause:sender

Pauses the current playback or recording session by invoking Sound's pause: method. If no sound is being processed, returns nil; otherwise, returns self.

play:

play:sender

Play the current selection by invoking Sound's play: method. If there is no selection, the SoundView's entire Sound is played. The willPlay: message is sent to the delegate before the selection is played; didPlay: is sent when the selection is done playing. Returns self.

read:

read:(void *)stream

Unarchives the SoundView by reading it from stream. Returns self.

readSelectionFromPasteboard:

readSelectionFromPasteboard:thePasteboard

Replaces the SoundView's current selection with the sound data on the given pasteboard. The pasteboard data is converted to the format of the data in the SoundView (if possible). If the SoundView has no selection, the pasteboard data is inserted at the cursor position. Sets the current error code for the SoundView's Sound object (which you can retrieve by sending processingError to the Sound) and returns self.

record:

record:sender

Replaces the SoundView's current selection with newly recorded material. If there is no selection, the recording is inserted at the cursor. The willRecord: message is sent to the delegate before the recording is started; didRecord: is sent after the recording has completed. Recorded data is always taken from the CODEC microphone input. Returns self.

reductionFactor

(float)reductionFactor

Returns the SoundView's reduction factor, computed as

reductionFactor = sampleCount / displayUnits

resignFirstResponder

resignFirstResponder

Resigns the position of first responder. Returns self.

resume:

resume:sender

Resumes the current playback or recording session by invoking Sound's resume: method. If no sound is being processed, returns nil; otherwise, returns self.

scaleToFit

scaleToFit

Recomputes the SoundView's reduction factor to fit the sound data (horizontally) within the current frame. Invoked automatically when the SoundView's data changes and the SoundView is in autoscale mode. If the SoundView isn't in autoscale mode, sizeToFit is invoked when the data changes. You never invoke this method directly; a subclass can reimplement this method to provide specialized behavior. Returns self.

selectAll:

selectAll:sender

Creates a selection over the SoundView's entire Sound. Returns self.

setAutoscale:

setAutoscale:(BOOL)aFlag

Sets the SoundView's automatic scaling mode, used to determine how the SoundView is redisplayed when its data changes. With autoscaling enabled (aFlag is YES), the SoundView's reduction factor is recomputed so the sound data fits within the view frame. If it's disabled (aFlag is NO), the frame is resized and the reduction factor is unchanged. If the SoundView is in a ScrollingView, autoScaling should be disabled (autoscaling is disabled by default). Returns self.

setBackgroundGray:

setBackgroundGray:(float)aGray

Sets the SoundView's background gray value to aGray; the default is NX_WHITE. Returns self.

setBezeled:

setBezeled:(BOOL)aFlag

If aFlag is YES, the display is given a bezeled border. By default, the border of a SoundView display isn't bezeled. If autodisplaying is enabled, the Sound is automatically redisplayed. Returns self.

setContinuous:

setContinuous:(BOOL)aFlag

Sets the state of continuous action messages. If aFlag is YES, selectionChanged: messages are sent to the delegate as the mouse is being dragged. If NO, the message is sent only on mouse up. The default is NO. Returns self.

setDelegate:

setDelegate:anObject

Sets the SoundView's delegate to anObject. The delegate is sent messages when the user changes or acts on the selection. Returns self.

setDisplayMode:

setDisplayMode:(int)aMode

Sets the SoundView's display mode, either NX_SOUNDVIEW_WAVE or NX_SOUNDVIEW_MINMAX (the default). If autodisplaying is enabled, the Sound is automatically redisplayed. Returns self.

setEditable:

setEditable:(BOOL)aFlag

Enables or disables editing in the SoundView as aFlag is YES or NO. By default, a SoundView is editable. Returns self.

setEnabled:

setEnabled:(BOOL)aFlag

Enables or disables the SoundView as aFlag is YES or NO. The mouse has no effect in a disabled SoundView. By default, a SoundView is enabled. Returns self.

setForegroundGray:

setForegroundGray:(float)aGray

Sets the SoundView's foreground gray value to aGray. The default is NX_BLACK. Returns self.

setOptimizedForSpeed:

setOptimizedForSpeed:(BOOL)flag

Sets the SoundView to optimize its display mechanism. Optimization greatly increases the speed with which data can be drawn, particularly for large sounds. It does so at the loss of some precision in representing the sound data; however, these inaccuracies are corrected as you zoom in on the data. All SoundView's are optimized by default. Returns self.

setReductionFactor:

setReductionFactor:(float)reductionFactor

Recomputes the size of the SoundView's frame, if autoscaling is disabled. The frame's size (in display units) is set according to the formula

displayUnits = sampleCount / reductionFactor

Increasing the reduction factor zooms out, decreasing zooms in on the data. If autodisplaying is enabled, the Sound is automatically redisplayed.
If the SoundView is in autoscaling mode, or reductionFactor is less than 1.0, the method avoids computing the frame size and returns nil. (In autoscaling mode, the reduction factor is automatically recomputed when the sound data changes--see scaleToFit:.) Otherwise, the method returns self. If reductionFactor is the same as the current reduction factor, the method returns immediately without recomputing the frame size.

setSelection:size:

setSelection:(int)firstSample size:(int)sampleCount

Sets the selection to be sampleCount samples wide, starting with sample firstSample (samples are counted from 0). Returns self.

setSound:

setSound:aSound

Sets the SoundView's Sound object to aSound. If autoscaling is enabled, the drawing coordinate system is adjusted so aSound's data fits within the current frame. Otherwise, the frame is resized to accommodate the length of the data. If autodisplaying is enabled, the SoundView is automatically redisplayed. Returns self.

showCursor

showCursor

Displays the SoundView's cursor. This is usually handled automatically. Returns self.

sizeTo::

sizeTo:(NXCoord)width :(NXCoord)height

Sets the width and height of the SoundView's frame. If autodisplaying is enabled, the SoundView is automatically redisplayed. Returns self.

sizeToFit

sizeToFit

Resizes the SoundView's frame (horizontally) to maintain a constant reduction factor. This method is invoked automatically when the SoundView's data changes and the SoundView isn't in autoscale mode. If the SoundView is in autoscale mode, scaleToFit is invoked when the data changes. You never invoke this method directly; a subclass can reimplement this method to provide specialized behavior. Returns self.

sound

sound

Returns a pointer to the SoundView's Sound object.

soundBeingProcessed

soundBeingProcessed

Returns the Sound object that's currently being played or recorded into. Note that the actual Sound object that's being performed isn't necessarily the SoundView's sound (the object returned by the sound method); for efficiency, SoundView creates a private performance Sound object. While this is generally an implementation detail, this method is supplied in case the SoundView's delegate needs to know exactly which object will be (or was) performed.

stop:

stop:sender

Stops the SoundView's current recording or playback. Returns self.

tellDelegate:

tellDelegate:(SEL)theMessage

Sends theMessage to the SoundView's delegate with the SoundView as the argument. If the delegate doesn't respond to the message, then it isn't sent. You normally never invoke this method; it's invoked automatically when an action, such as playing or editing, is performed. However, you can invoke it in the design of a SoundView subclass. Returns self.

validRequestorForSendType:andReturnType:

validRequestorForSendType:(NXAtom)sendType

andReturnType:(NXAtom)returnType

You never invoke this method; it's implemented to support services that act on sound data.

willPlay:

willPlay:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

willRecord:

willRecord:sender

Used to redirect delegate messages from the SoundView's Sound object; you never invoke this method directly.

write:

write:(void *)stream

Archives the SoundView by writing it to stream. Returns self.

writeSelectionToPasteboard:types:

writeSelectionToPasteboard:thePasteboard types:(NXAtom *)pboardTypes

Places a copy of the SoundView's current selection on the given pasteboard. The pboardTypes argument is currently ignored. Returns self.

Methods Implemented by the Delegate

didPlay:

didPlay:sender

Sent to the delegate just after the SoundView's sound is played.

didRecord:

didRecord:sender

Sent to the delegate just after the SoundView's sound is recorded into.

hadError:

hadError:sender

Sent to the delegate if an error is encountered during recording or playback of the SoundView's sound.

selectionChanged:

selectionChanged:sender

Sent to the delegate when the SoundView's selection changes.

soundDidChange:

soundDidChange:sender

Sent to the delegate when the SoundView's sound data is edited.

willFree:

willFree:sender

Sent to the delegate when the SoundView is freed.

willPlay:

willPlay:sender

Sent to the delegate just before the SoundView's sound is played.

willRecord:

willRecord:sender

Sent to the delegate just before the SoundView's sound is recorded into.

	Inherits From:	View : Responder : Object

	Declared In:	soundkit/SoundView.h

		In NX_SOUNDVIEW_WAVE mode, the drawing is rendered in an oscilloscopic fashion.

		In NX_SOUNDVIEW_MINMAX mode, two lines are drawn, one to connect the maximum values, and one to connect the minimum values.

	sound	The object's Sound.

	reduction	The data reduced version of the object's Sound.

	delegate	The object's delegate.

	selectionRect	The object's current selection.

	displayMode	Display mode; NX_SOUNDVIEW_MINMAX by default.

	backgroundGray	Background color; NX_WHITE by default.

	foregroundGray	Foreground color; NX_BLACK by default.

	reductionFactor	The ratio of sound samples to display units.

	svFlags.disabled	Does the object (not) respond to mouse events?

	svFlags.continuous	Does the object respond to mouse dragged events?

	svFlags.calcDrawInfo	Does drawing info need to be recalculated?

	svFlags.selectionDirty	Has the object changed (but not been played)?

	svFlags.autoscale	Does it rescale the display when the sound data changes?

	svFlags.bezeled	Does the object have a bezeled border?

	svFlags.notEditable	Is the sound data not editable?

	svFlags.notOptimizedForSpeed	Is the object not optimized for fast loading?

	Initializing a SoundView object	initFrame:

	Freeing a SoundView instance	free

	Modifying the object	scaleToFit