Fixing the bug preventing iPod playlists from showing in the menu
[MenuTunes.git] / ITMTRemote.h
1 /*
2  *  MenuTunes
3  *  ITMTRemote
4  *    Plugin definition for audio player control via MenuTunes
5  *
6  *  Original Author : Matt Judy <mjudy@ithinksw.com>
7  *   Responsibility : Matt Judy <mjudy@ithinksw.com>
8  *
9  *  Copyright (c) 2002 - 2003 iThink Software.
10  *  All Rights Reserved
11  *
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.
15  *
16  */
17
18 /*!
19  * @header ITMTRemote
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.
21  */
22 #import <Cocoa/Cocoa.h>
23
24 /*!
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.
31  */
32 typedef enum {
33     ITMTRemotePlayerNotRunning = -1,
34     ITMTRemotePlayerLaunching,
35     ITMTRemotePlayerRunning
36 } ITMTRemotePlayerRunningState;
37
38 /*!
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.
47  */
48 typedef enum {
49     ITMTRemotePlayerStopped = -1,
50     ITMTRemotePlayerPaused,
51     ITMTRemotePlayerPlaying,
52     ITMTRemotePlayerRewinding,
53     ITMTRemotePlayerForwarding
54 } ITMTRemotePlayerPlayingState;
55
56 /*!
57  * @enum ITMTRemotePlayerPlaylistClass
58  * @abstract Possible playlist classes used by a remote's player
59  * @discussion Used in functions that report the class of a playlist to MenuTunes. While we borrow the terms/descriptions from iTunes, these should work fine with any other player. If your player doesn't support a given type of playlist, then just return 
60
61 ITMTRemotePlayerPlaylist.
62  * @constant ITMTRemotePlayerLibraryPlaylist For players that have one playlist that contains all of a user's music, or for players that don't have the concept of multiple playlists, this is the class for that "Master" list.
63  * @constant ITMTRemotePlayerPlaylist The generic playlist. Created and maintained by the user.
64  * @constant ITMTRemotePlayerSmartPlaylist A smart playlist is a playlist who's contents are dynamic, based on a set of criteria or updated by a script. These are usually not edited directly by the user, but instead maintained by the player.
65  * @constant ITMTRemotePlayerRadioPlaylist This is for when playing tracks off of (online) radio stations.
66  */
67 typedef enum {
68     ITMTRemotePlayerLibraryPlaylist = -1,
69     ITMTRemotePlayerPlaylist,
70     ITMTRemotePlayerSmartPlaylist,
71     ITMTRemotePlayerRadioPlaylist
72 } ITMTRemotePlayerPlaylistClass;
73
74 typedef enum {
75     ITMTRemoteLibrarySource = -1,
76     ITMTRemoteCDSource,
77     ITMTRemoteRadioSource,
78     ITMTRemoteiPodSource,
79     ITMTRemoteGenericDeviceSource,
80     ITMTRemoteSharedLibrarySource
81 } ITMTRemotePlayerSource;
82
83 /*!
84  * @enum ITMTRemotePlayerRepeatMode
85  * @abstract Possible repeat modes for the remote's player.
86  * @discussion Used in functions that report or set the remote's player's repeat mode.
87  * @constant ITMTRemotePlayerRepeatOff The player plays all of the songs in a playlist through to the end, and then stops.
88  * @constant ITMTRemotePlayerRepeatAll The player plays all of the songs in a playlist through to the end, and then starts over again from the beginning.
89  * @constant ITMTRemotePlayerRepeatOne The player loops playing the selected song.
90  */
91 typedef enum {
92     ITMTRemotePlayerRepeatOff = -1,
93     ITMTRemotePlayerRepeatAll,
94     ITMTRemotePlayerRepeatOne
95 } ITMTRemotePlayerRepeatMode;
96
97 /*!
98  * @protocol ITMTRemote
99  * @discussion The Objective-C protocol which all MenuTunes remotes must implement.
100  */
101 @protocol ITMTRemote
102
103 /*!
104  * @method remote
105  * @abstract Returns an autoreleased instance of the remote.
106  * @discussion Should be very quick and compact.
107  *
108  * EXAMPLE:<br>
109  * + (id)remote<br>
110  * {<br>
111  * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return [[[MyRemote alloc] init] autorelease];<br>
112  * }
113  *
114  * @result An instance of the remote.
115  */
116 + (id)remote;
117
118 /*!
119  * @method remoteTitle
120  * @abstract Returns the remote's title/name.
121  * @discussion This title is shown while the user is selecting which remote to use. This is for informational purposes only.
122  * @result An NSString containing the title/name of the remote.
123  */
124 - (NSString *)remoteTitle;
125
126 /*!
127  * @method remoteInformation
128  * @abstract Returns the remote's information.
129  * @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.
130  * @result An NSString containing the information for the remote.
131  */
132 - (NSString *)remoteInformation;
133
134 /*!
135  * @method remoteIcon
136  * @abstract Returns the remote's icon.
137  * @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.
138  * @result An NSImage containing the icon of the remote.
139  */
140 - (NSImage *)remoteIcon;
141
142 /*!
143  * @method begin
144  * @abstract Sent when the remote should begin operation.
145  * @result A result code signifying success.
146  */
147 - (BOOL)begin;
148
149 /*!
150  * @method halt
151  * @abstract Sent when the remote should cease operation.
152  * @result A result code signifying success.
153  */
154 - (BOOL)halt;
155
156 /*!
157  * @method playerFullName
158  * @abstract Returns the remote's player's application filename.
159  * @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 thei
160
161 r application. This should return "Audion 3", not simply "Audion". See playerSimpleName.
162  * @result An NSString containing the remote's player's application filename
163  */
164 - (NSString *)playerFullName;
165
166 /*!
167  * @method playerSimpleName
168  * @abstract Returns the simplified name of the remote's player.
169  * @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.
170  * @result An NSString containing the simplified name of the remote's player.
171  */
172 - (NSString *)playerSimpleName;
173
174 /*!
175  * @method capabilities
176  * @abstract Returns a dictionary defining the capabilities of the remote and it's player.
177  * @discussion Discussion Forthcoming.
178  * @result An NSDictionary defining the capabilities of the remote and it's player.
179  */
180 - (NSDictionary *)capabilities;
181
182 /*!
183  * @method showPrimaryInterface
184  */
185 - (BOOL)showPrimaryInterface;
186
187 /*!
188  * @method playerRunningState
189  * @abstract Returns the running state of the remote's player.
190  * @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 play
191
192 er's process managment.
193  * @result An ITMTRemotePlayerRunningState defining the running state of the remote's player.
194  */
195 - (ITMTRemotePlayerRunningState)playerRunningState;
196
197 /*!
198  * @method playerPlayingState
199  */
200 - (ITMTRemotePlayerPlayingState)playerPlayingState;
201
202 /*!
203  * @method playlists
204  */
205 - (NSArray *)playlists;
206
207 /*!
208  * @method numberOfSongsInPlaylistAtIndex:
209  */
210 - (int)numberOfSongsInPlaylistAtIndex:(int)index;
211
212 /*!
213  * @method currentSource
214  */
215 - (ITMTRemotePlayerSource)currentSource;
216
217 /*!
218  * @method currentPlaylistClass
219  */
220 - (ITMTRemotePlayerPlaylistClass)currentPlaylistClass;
221
222 /*!
223  * @method currentPlaylistIndex
224  */
225 - (int)currentPlaylistIndex;
226
227 /*!
228  * @method songTitleAtIndex:
229  */
230 - (NSString *)songTitleAtIndex:(int)index;
231
232 /*!
233  * @method currentAlbumTrackCount:
234  */
235 - (int)currentAlbumTrackCount;
236
237 /*!
238  * @method currentSongTrack:
239  */
240 - (int)currentSongTrack;
241
242 /*!
243  * @method playerStateUniqueIdentifier:
244  */
245 - (NSString *)playerStateUniqueIdentifier;
246
247 /*!
248  * @method currentSongIndex
249  */
250 - (int)currentSongIndex;
251
252 /*!
253  * @method currentSongTitle
254  */
255 - (NSString *)currentSongTitle;
256
257 /*!
258  * @method currentSongArtist
259  */
260 - (NSString *)currentSongArtist;
261
262 /*!
263  * @method currentSongAlbum
264  */
265 - (NSString *)currentSongAlbum;
266
267 /*!
268  * @method currentSongGenre
269  */
270 - (NSString *)currentSongGenre;
271
272 /*!
273  * @method currentSongLength
274  */
275 - (NSString *)currentSongLength;
276
277 /*!
278  * @method currentSongRemaining
279  */
280 - (NSString *)currentSongRemaining;
281
282 /*!
283  * @method currentSongElapsed
284  */
285 - (NSString *)currentSongElapsed;
286
287 /*!
288  * @method currentSongAlbumArt
289  */
290 - (NSImage *)currentSongAlbumArt;
291
292 /*!
293  * @method currentSongRating
294  */
295 - (float)currentSongRating;
296
297 /*!
298  * @method setCurrentSongRating:
299  */
300 - (BOOL)setCurrentSongRating:(float)rating;
301
302 /*!
303  * @method eqPresets
304  */
305 - (NSArray *)eqPresets;
306
307 /*!
308  * @method currentEQPresetIndex
309  */
310 - (int)currentEQPresetIndex;
311
312 /*!
313  * @method volume
314  */
315 - (float)volume;
316
317 /*!
318  * @method setVolume:
319  */
320 - (BOOL)setVolume:(float)volume;
321
322 /*!
323  * @method shuffleEnabled
324  */
325 - (BOOL)shuffleEnabled;
326
327 /*!
328  * @method setShuffleEnabled:
329  */
330 - (BOOL)setShuffleEnabled:(BOOL)enabled;
331
332 /*!
333  * @method repeatMode
334  */
335 - (ITMTRemotePlayerRepeatMode)repeatMode;
336
337 /*!
338  * @method setRepeatMode:
339  */
340 - (BOOL)setRepeatMode:(ITMTRemotePlayerRepeatMode)repeatMode;
341
342 /*!
343  * @method play
344  */
345 - (BOOL)play;
346
347 /*!
348  * @method pause
349  */
350 - (BOOL)pause;
351
352 /*!
353  * @method goToNextSong
354  */
355 - (BOOL)goToNextSong;
356
357 /*!
358  * @method goToPreviousSong
359  */
360 - (BOOL)goToPreviousSong;
361
362 /*!
363  * @method forward
364  */
365 - (BOOL)forward;
366
367 /*!
368  * @method rewind
369  */
370 - (BOOL)rewind;
371
372 /*!
373  * @method switchToPlaylistAtIndex:
374  */
375 - (BOOL)switchToPlaylistAtIndex:(int)index;
376
377 /*!
378  * @method switchToSongAtIndex:
379  */
380 - (BOOL)switchToSongAtIndex:(int)index;
381
382 /*!
383  * @method switchToEQAtIndex:
384  */
385 - (BOOL)switchToEQAtIndex:(int)index;
386
387 @end
388
389 /*!
390  * @class ITMTRemote
391  */
392 @interface ITMTRemote : NSObject <ITMTRemote>
393
394 @end