4 * Plugin definition for audio player control via MenuTunes
6 * Original Author : Matt Judy <mjudy@ithinksw.com>
7 * Responsibility : Matt Judy <mjudy@ithinksw.com>
9 * Copyright (c) 2002 - 2003 iThink Software.
12 * This header defines the Objective-C protocol which all MenuTunes Remote
13 * plugins must implement. To build a remote, create a subclass of this
14 * object, and implement each method in the @protocol below.
20 * @discussion This header defines the Objective-C protocol which all MenuTunes Remote plugins must implement. To build a remote, create a subclass of the ITMTRemote object, and implement each method in the ITMTRemote protocol.
22 #import <Cocoa/Cocoa.h>
25 * @enum ITMTRemotePlayerRunningState
26 * @abstract Possible running states for the remote's player.
27 * @discussion Used in fuctions that report or take the running state of the remote's player application.
28 * @constant ITMTRemotePlayerNotRunning The remote's player isn't running.
29 * @constant ITMTRemotePlayerLaunching The remote's player is starting up, or is running, but not yet accepting remote commands.
30 * @constant ITMTRemotePlayerRunning The remote's player is running, and as such, is accepting remote commands.
33 ITMTRemotePlayerNotRunning = -1,
34 ITMTRemotePlayerLaunching,
35 ITMTRemotePlayerRunning
36 } ITMTRemotePlayerRunningState;
39 * @enum ITMTRemotePlayerPlayingState
40 * @abstract Possible playing states for the remote's player.
41 * @discussion Used in functions that report or take the playing state of the remote's player application.
42 * @constant ITMTRemotePlayerStopped The remote's player is stopped.
43 * @constant ITMTRemotePlayerPaused The remote's player is paused.
44 * @constant ITMTRemotePlayerPlaying The remote's player is playing.
45 * @constant ITMTRemotePlayerRewinding The remote's player is rewinding.
46 * @constant ITMTRemotePlayerForwarding The remote's player is forwarding.
49 ITMTRemotePlayerStopped = -1,
50 ITMTRemotePlayerPaused,
51 ITMTRemotePlayerPlaying,
52 ITMTRemotePlayerRewinding,
53 ITMTRemotePlayerForwarding
54 } ITMTRemotePlayerPlayingState;
57 * @enum ITMTRemotePlayerRepeatMode
58 * @abstract Possible repeat modes for the remote's player.
59 * @discussion Used in functions that report or set the remote's player's repeat mode.
60 * @constant ITMTRemotePlayerRepeatOff The player plays all of the songs in a playlist through to the end, and then stops.
61 * @constant ITMTRemotePlayerRepeatAll The player plays all of the songs in a playlist through to the end, and then starts over again from the beginning.
62 * @constant ITMTRemotePlayerRepeatOne The player loops playing the selected song.
65 ITMTRemotePlayerRepeatOff = -1,
66 ITMTRemotePlayerRepeatAll,
67 ITMTRemotePlayerRepeatOne
68 } ITMTRemotePlayerRepeatMode;
71 * @protocol ITMTRemote
72 * @discussion The Objective-C protocol which all MenuTunes remotes must implement.
78 * @abstract Returns an autoreleased instance of the remote.
79 * @discussion Should be very quick and compact.
84 * return [[[MyRemote alloc] init] autorelease];<br>
87 * @result An instance of the remote.
93 * @abstract Returns the remote's title/name.
94 * @discussion This title is shown while the user is selecting which remote to use. This is for informational purposes only.
95 * @result An NSString containing the title/name of the remote.
97 - (NSString *)remoteTitle;
100 * @method remoteInformation
101 * @abstract Returns the remote's information.
102 * @discussion Information on the remote that the user will see when selecting which remote to use. The information returned here has no bearing on how the remote works, it's simply here for informing the user.
103 * @result An NSString containing the information for the remote.
105 - (NSString *)remoteInformation;
109 * @abstract Returns the remote's icon.
110 * @discussion This icon is shown while the user is selecting which remote to use. Typically, this is the remote's player's application icon, however it can be anything you like.
111 * @result An NSImage containing the icon of the remote.
113 - (NSImage *)remoteIcon;
117 * @abstract Sent when the remote should begin operation.
118 * @result A result code signifying success.
124 * @abstract Sent when the remote should cease operation.
125 * @result A result code signifying success.
130 * @method playerFullName
131 * @abstract Returns the remote's player's application filename.
132 * @discussion This string should be the name typically used by the remote's player's application bundle/file. For example, Panic's Audion audio player is known simply as "Audion", however, the application bundle is called "Audion 3" for version 3 of their application. This should return "Audion 3", not simply "Audion". See playerSimpleName.
133 * @result An NSString containing the remote's player's application filename
135 - (NSString *)playerFullName;
138 * @method playerSimpleName
139 * @abstract Returns the simplified name of the remote's player.
140 * @discussion This is the name used in the User Interface for when referring to the remote's player. Continuing the example from the playerFullName method, this method would return simply "Audion", as that is how the player is known.
141 * @result An NSString containing the simplified name of the remote's player.
143 - (NSString *)playerSimpleName;
146 * @method capabilities
147 * @abstract Returns a dictionary defining the capabilities of the remote and it's player.
148 * @discussion Discussion Forthcoming.
149 * @result An NSDictionary defining the capabilities of the remote and it's player.
151 - (NSDictionary *)capabilities;
154 * @method playerRunningState
155 * @abstract Returns the running state of the remote's player.
156 * @discussion While most remotes will use only ITMTRemotePlayerNotRunning or ITMTRemotePlayerRunning, we have included support for ITMTRemotePlayerLaunching (see ITMTRemotePlayerRunningState) for remotes that want the most precise control over their player's process managment.
157 * @result An ITMTRemotePlayerRunningState defining the running state of the remote's player.
159 - (ITMTRemotePlayerRunningState)playerRunningState;
162 * @method playerPlayingState
164 - (ITMTRemotePlayerPlayingState)playerPlayingState;
169 - (NSArray *)playlists;
172 * @method numberOfSongsInPlaylistAtIndex:
174 - (int)numberOfSongsInPlaylistAtIndex:(int)index;
177 * @method classOfPlaylistAtIndex:
179 - (NSString *)classOfPlaylistAtIndex:(int)index;
182 * @method currentPlaylistIndex
184 - (int)currentPlaylistIndex;
187 * @method songTitleAtIndex:
189 - (NSString *)songTitleAtIndex:(int)index;
192 * @method currentSongIndex
194 - (int)currentSongIndex;
197 * @method currentSongTitle
199 - (NSString *)currentSongTitle;
202 * @method currentSongArtist
204 - (NSString *)currentSongArtist;
207 * @method currentSongAlbum
209 - (NSString *)currentSongAlbum;
212 * @method currentSongGenre
214 - (NSString *)currentSongGenre;
217 * @method currentSongLength
219 - (NSString *)currentSongLength;
222 * @method currentSongRemaining
224 - (NSString *)currentSongRemaining;
227 * @method currentSongRating
229 - (float)currentSongRating;
232 * @method setCurrentSongRating:
234 - (BOOL)setCurrentSongRating:(float)rating;
237 * @method equalizerEnabled
239 - (BOOL)equalizerEnabled;
242 * @method setEqualizerEnabled:
244 - (BOOL)setEqualizerEnabled:(BOOL)enabled;
249 - (NSArray *)eqPresets;
252 * @method currentEQPresetIndex
254 - (int)currentEQPresetIndex;
264 - (BOOL)setVolume:(float)volume;
267 * @method shuffleEnabled
269 - (BOOL)shuffleEnabled;
272 * @method setShuffleEnabled:
274 - (BOOL)setShuffleEnabled:(BOOL)enabled;
279 - (ITMTRemotePlayerRepeatMode)repeatMode;
282 * @method setRepeatMode:
284 - (BOOL)setRepeatMode:(ITMTRemotePlayerRepeatMode)repeatMode;
297 * @method goToNextSong
299 - (BOOL)goToNextSong;
302 * @method goToPreviousSong
304 - (BOOL)goToPreviousSong;
317 * @method switchToPlaylistAtIndex:
319 - (BOOL)switchToPlaylistAtIndex:(int)index;
322 * @method switchToSongAtIndex:
324 - (BOOL)switchToSongAtIndex:(int)index;
327 * @method switchToEQAtIndex:
329 - (BOOL)switchToEQAtIndex:(int)index;
336 @interface ITMTRemote : NSObject <ITMTRemote>