The interface_plugin_ops structure
The interface_plugin_ops structure that is returned by the Instantiate_Plugin function
and defines an instance of a general purpose plugin, is defined as:
typedef status_t op_ui_show(void*);
typedef void op_ui_hide(void*);
typedef void op_ui_setconfig(void*,BMessage *config);
typedef void op_ui_getconfig(void*,BMessage *config);
typedef struct interface_plugin_ops
{
// first some bookkeeping stuff
uint32 ops_magic;
uint32 ops_version;
op_ui_show (*Show);
op_ui_hide (*Hide);
op_ui_setconfig (*SetConfig); // leave NULL if not implemented
op_ui_getconfig (*GetConfig); // leave NULL if not implemented
} interface_plugin_ops;
-
op_magic is a magic number that you should set to PLUGIN_INTERFACE_MAGIC
-
ops_version is the current API version, and you should set it to PLUGIN_INTERFACE_VERSION
-
After instantiating the plugin, SoundPlay will call Show and Hide to enable/disable the plugin. You should not
display the interface until Show() has been called. If the interface wants to close itself, it should use SoundPlayController::DisableInterface (see below)
-
The configuration of interface plugins is done using the SetConfig and GetConfig functions. The Configure function
from the plugin descriptor is not used.
The SoundPlayController class
The SoundPlayController class is used to control various functions of SoundPlay. It is
passed (through the plugin_info structure) to each type of plugin when it is instantiated.
Although it is primarily intented for plugins that want to provide an additional or
alternative userinterface for SoundPlay, its functions can be used by all plugin-types.
The SoundPlayController class is defined as:
class SoundPlayController
{
public:
virtual int32 Version(); // soundplay version, encoded like this: X.Y.Z -> 0x000XYZ00
virtual const char *VersionString(); // version as a string, e.g. "3.2"
virtual void Quit(void);
virtual void DisableInterface(const char *id);
virtual void HideMainInterface(void);
virtual void ShowMainInterface(void);
virtual bool IsMainInterfaceHidden(void);
virtual const uint16* GetFFTForBuffer(const void *buffer, int32 channel); // get 256-point FFT data for the specified channel
// You must lock the controller object before doing anything
// with its tracks, and unlock it afterwards
// Note that as long as you have a PlaylistPtr for a playlist,
// that playlist will remain valid. Its associated controls
// might go away (i.e. the playlist gets removed from the controller),
// but you can still work with the files in the playlist, or add it
// to the controller again.
virtual void Lock(void);
virtual void Unlock(void);
virtual uint32 CountPlaylists(void);
virtual PlaylistPtr PlaylistAt(uint32 index);
virtual PlaylistPtr AddPlaylist(); // create a new playlist+controls
virtual status_t AddPlaylist(PlaylistPtr playlist); // add an existing playlist to the controller
virtual status_t RemovePlaylist(PlaylistPtr playlist);
virtual void OpenEditor(PlaylistPtr playlist);
virtual void AddWindow(BWindow*, int32 filterflags=FILTER_HOTKEYS|FILTER_REFS); // tell SoundPlay about your window(s) so that SP can do some hotkey-management for it and accept dropped files
virtual status_t AddListener(BHandler *handler);
virtual status_t RemoveListener(BHandler *handler);
// plugins can use these functions to store and retrieve preferences as BMessages
virtual status_t StorePreference(const char *name, const BMessage *message);
virtual status_t RetrievePreference(const char *name, BMessage *message);
};
-
version is SoundPlay's version number. If your plugin requires a specific version of SoundPlay to function properly,
it should check this value. Version X.Y.Z is encoded as 0x000XYZ00.
-
versionstring SoundPlay's version number as an ASCII string.
-
Quit. Call this function to quit SoundPlay
-
DisableInterface. Call this function with the ID of the interface plugin you wish to disable. Use this to disable your own interface,
for example if the user closed your interface's window.
-
HideMainInterface hides the main SoundPlay interface, leaving only the enabled interface plugins.
-
ShowMainInterface shows the main SoundPlay interface again.
-
IsMainInterfaceHidden returns whether or not the main interface is currently hidden.
-
GetFFTForBuffer returns a 256 point FFT for the given visualization buffer and channel. You need to pass in the visualization
buffer you're interested in (this implies that only visualization plugins can use this function), and the channel you want (one of
SP_LEFT_CHANNEL, SP_RIGHT_CHANNEL or SP_MONO_CHANNEL).
-
Lock and Unlock lock and unlock the controller object. Only one entity, be that a plugin or SoundPlay itself, can have
a lock on the controller object at a time. Do not keep the object locked for long periods of time.
-
CountPlaylists returns the number of playlists SoundPlay is playing. The controller must be locked to call this function.
-
PlaylistAt returns a PlaylistPtr object (see below). The controller must be locked to call this function.
-
AddPlaylist() adds a new track. The controller must be locked to call this function. The new playlist is returned as a PlaylistPtr object
AddPlaylist(PlaylistPtr) adds the given playlist to the controller. The controller must be locked to call this function. The new playlist is returned as a PlaylistPtr object
-
RemovePlaylist removes the specified playlist. The controller must be locked to call this function.
OpenEditor opens a playlisteditor for the given playlist. The controller must be locked to call this function.
-
AddWindow lets SoundPlay know that it should process hotkeys and/or drag&dropped files for the given window. If your interface
or effect plugin opens its own window, it is recommended that you let SoundPlay handle hotkeys for it. Note that your window will still
receive keypresses for non-hotkey keys.
-
AddListener marks the given BHandler as the recipient of notification for changes to the SoundPlayController. Whenever
something happens to the SoundPlayController (add/removing tracks, playlisteditor open-request) the handler will receive
a message informing it of that fact. The controller must be locked to call this function.
-
RemoveListener removes the BHandler from the notification-list. The controller must be locked to call this function.
-
StorePreference stores the given BMessage in SoundPlay's persistent preferences storage with the given name.
-
RetrievePreference retrieves the named BMessage from SoundPlay's persistent preference storage.
Note: as of SoundPlay 4.6, it is no longer necessary to link against the SoundPlay executable in order to
call SoundPlayController-functions (but you still need to link against it if you want to manipulate playlists).
The Playlist class
Through the SoundPlayController class you can obtain a PlaylistPtr object for a SoundPlay-playlist.
A PlaylistPtr is a reference-counted handle for a PrivatePlaylist object. You dereference the PlaylistPtr as
if it were a pointer, even though it is not. You should always make copies of PlaylistPtr objects, never
pass around pointers to it.
The PrivatePlaylist object that you reference through the PlaylistPtr object contains functions to manipulate
files in the playlist. Most of these functions require you to lock the playlist first.
Note that in order to manipulate PlaylistPtr objects, your plugin will need to link against the SoundPlay
executable.
Please refer to the headers and example plugins for more information.
Copyright © 1999 Marco Nelissen