This is ModuleProtocol.rtf in view mode; [Download] [Up]
Release 2.5, Copyright ©1997 by Sean Luke. All Rights Reserved.
ModuleProtocol
Declared In: ModuleProtocol.h
Protocol Description
This protocol lists current methods available to modules. It is backward-compatible with Resound versions from 2.0a to 2.4. I informally promise that modules adhering to this version of the protocol will be compatible with all non-OPENSTEP Resound versions including and beyond 2.5.
Each module has an id called TheModuleController. This is the instance that should receive the messages below. For more information, see Module.rtf.
It is important to note that you should not access a sound's info string using the standard SoundKit methods and functions. Due to bugs in the SoundKit, Resound must maintain the Sound object's Info String separately in Resound's custom SoundView. There are access and modification methods there; see ModuleSoundView.rtf.
Your module should ordinarily not use any private Windows at all, only Panels. But if in the off chance it must use a Window, call ModuleMenuProtocol's moduleWindowDidBecomeMain whenever your private Window becomes main.
SoundViews and Sounds are lazy in the way they send data to the pasteboard: they only send the data when the pasteboard asks for it (which is when another object tries to paste the data). At the same time, SoundViews and Sounds forget to tell the pasteboard they're gone before they get freed. This presents us with a problem: if you copy data from a sound onto the pasteboard, then free the sound, then try to paste the data, the program will bomb (message to a freed object).
You can get around this in the following extremely nasty way. New to ModuleProtocol is the method stillExists which returns YES if the item on the pasteboard can be found domewhere in Resound's table of active sounds, sound views, and sound windows. This table should only contain valid (not freed) pointers. In the act of pasting, you could use this method to determine if the owner of a pasteboard actually still exists in Resound's records. If it doesn't, you can then invalidate the pasteboard with invalidatePasteboard (also new to ModuleProtocol). Here's the hack:
id pb=[Pasteboard new];
const char* t[2]={NXSoundPboardType,NULL};
if ([pb findAvailableTypeFrom:t num:1]!=NXSoundPboardType)
{
/* can't paste anyway--
no sound on the pasteboard.
do what you like in this
situation here... */
}
else if ([TheModuleController stillExists])
{
/* do our pasting or
whatever stuff here */
}
else
{
[TheModuleController invalidatePasteboard];
/* do whatever you want that
_doesn't_ paste here */
}
When replacing the entire sound of a SoundView (through the use of setSound: or some similar method), you should be sure to invalidate the pasteboard if the SoundView is its current owner. Otherwise, the SoundView will become confused when pasting the sound, and the program will bomb. You can check and invalidate the SoundView using the isOwner: and invalidatePasteboard methods in code like this :
if ([TheModuleController isOwner: mySoundView ])
// mySoundView is the SoundView in question
[TheModuleController invalidatePasteboard];
/* Set the new sound here */
Method Types
Sound Access - currentSound
- currentSoundView
- currentWindow
- currentPlayingSound
- currentPlayingSoundView
- currentPlayingWindow
New Sounds - brandNewSound:
- newSound:for:
Modified Sounds - soundChanged
- selectionChanged
- fragmentationChanged
- zoomChanged
Sound Playing and Recording - stop
- isPlaying
- isRecording
Window Hacks - moduleWindowDidBecomeMain
Pasteboard Hacks - isOwner:
- stillExists
- invalidatePasteboard
Instance Methods
brandNewSound:
- brandNewSound:(Sound*)thisSound
Tells Resound to register and create a new SoundView for the brand new sound thisSound generated by the module.
currentPlayingSound
- currentPlayingSound
Returns the Sound currently playing, or NULL if there is none.
currentPlayingSoundView
- currentPlayingSoundView
Returns the SoundView currently playing, or NULL if there is none.
currentPlayingWindow
- currentPlayingWindow
Returns the sound Window currently playing, or NULL if there is none.
currentSound
- currentSound
Returns the Sound currently being selected and used, or NULL if there is none.
currentSoundView
- currentSoundView
Returns the SoundView currently being selected and used, or NULL if there is none.
currentWindow
- currentWindow
Returns the sound's Window currently being selected and used, or NULL if there is none.
fragmentationChanged
- fragmentationChanged
Tells Resound that the current Sound may have been fragmented or compacted.
invalidatePasteboard
- invalidatePasteboard
Invalidates the pasteboard, that is, removes any cut or copied sound on the pasteboard that belongs to Resound's SoundViews. See the introduction above.
isOwner:
- (BOOL) isOwner:this_sound_or_soundview
Returns YES if this_sound_or_soundview is the owner of the pasteboard or its internal sound is the owner of the pasteboard. See the introduction above.
isPlaying
- (BOOL) isPlaying
Returns 1 a sound is playing, else 0.
isRecording
- (BOOL) isRecording
Returns 1 a sound is recording, else 0.
moduleWindowDidBecomeMain
- moduleWindowDidBecomeMain
In general, it's best if your module doesn't use Windows--use Panels instead. But in the off chance that you need to use windows, Resound needs to know so it can set the CurrentSound, CurrentSoundView, and CurrentWindow to NULL, and update its inspector accordingly. Whenever a Window owned by your module becomes main, make certain to call this method.
newSound:for:
- newSound:(Sound*)thisSound for:(SoundView*)thisSoundView
Informs Resound that thisSoundView (typically the current SoundView) has been given a new associated sound thisSound. This method automatically calls SoundChanged. This procedure does not actually put the Sound in the new SoundView, but merely informs the program. Prior to calling this method, you yourself must set the SoundView's new Sound and free the old one.
selectionChanged
- selectionChanged
Tells Resound that the current SoundView has had its selection changed.
soundChanged
- soundChanged
Tells Resound that the current Sound has been modified.
stillExists
- (BOOL) stillExists
Returns YES if pasteboard owner is NULL or still a valid sound, soundview, or sound window in Resound's sound table. This is useful to determine if the owner of a pboard hasn't been freed before you try to paste data into a sound or soundview. See the introduction above.
zoomChanged
- zoomChanged
Tells Resound that the current SoundView has had its zoom changed.
stop
- stop
Stops any currently playing or recording sound.
These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.