Copyright ©1995 by NeXT Computer, Inc. All Rights Reserved.
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 { |
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. |