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  * @protocol ITMTRemote
  58  * @discussion The Objective-C protocol which all MenuTunes remotes must implement.
  59  */
  60 @protocol ITMTRemote
  61
  62 /*!
  63  * @method remote
  64  * @abstract Returns an autoreleased instance of the remote.
  65  * @discussion Should be very quick and compact.
  66  *
  67  * EXAMPLE:<br>
  68  * + (id)remote<br>
  69  * {<br>
  70  * &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;return [[[MyRemote alloc] init] autorelease];<br>
  71  * }
  72  *
  73  * @result An instance of the remote.
  74  */
  75 + (id)remote;
  76
  77 /*!
  78  * @method remoteTitle
  79  * @abstract Returns the remote's title/name.
  80  * @discussion This title is shown while the user is selecting which remote to use. This is for informational purposes only.
  81  * @result An NSString containing the title/name of the remote.
  82  */
  83 - (NSString *)remoteTitle;
  84
  85 /*!
  86  * @method remoteInformation
  87  * @abstract Returns the remote's information.
  88  * @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.
  89  * @result An NSString containing the information for the remote.
  90  */
  91 - (NSString *)remoteInformation;
  92
  93 /*!
  94  * @method remoteIcon
  95  * @abstract Returns the remote's icon.
  96  * @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.
  97  * @result An NSImage containing the icon of the remote.
  98  */
  99 - (NSImage *)remoteIcon;
 100
 101 /*!
 102  * @method begin
 103  * @abstract Sent when the remote should begin operation.
 104  * @result A result code signifying success.
 105  */
 106 - (BOOL)begin;
 107
 108 /*!
 109  * @method halt
 110  * @abstract Sent when the remote should cease operation.
 111  * @result A result code signifying success.
 112  */
 113 - (BOOL)halt;
 114
 115 /*!
 116  * @method playerFullName
 117  * @abstract Returns the remote's player's application filename.
 118  * @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.
 119  * @result An NSString containing the remote's player's application filename
 120  */
 121 - (NSString *)playerFullName;
 122
 123 /*!
 124  * @method playerSimpleName
 125  * @abstract Returns the simplified name of the remote's player.
 126  * @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.
 127  * @result An NSString containing the simplified name of the remote's player.
 128  */
 129 - (NSString *)playerSimpleName;
 130
 131 /*!
 132  * @method capabilities
 133  * @abstract Returns a dictionary defining the capabilities of the remote and it's player.
 134  * @discussion Discussion Forthcoming.
 135  * @result An NSDictionary defining the capabilities of the remote and it's player.
 136  */
 137 - (NSDictionary *)capabilities;
 138
 139 /*!
 140  * @method playerRunningState
 141  * @abstract Returns the running state of the remote's player.
 142  * @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.
 143  * @result An ITMTRemotePlayerRunningState defining the running state of the remote's player.
 144  */
 145 - (ITMTRemotePlayerRunningState)playerRunningState;
 146
 147 /*!
 148  * @method playerPlayingState
 149  */
 150 - (ITMTRemotePlayerPlayingState)playerPlayingState;
 151
 152 /*!
 153  * @method playlists
 154  */
 155 - (NSArray *)playlists;
 156
 157 /*!
 158  * @method numberOfSongsInPlaylistAtIndex:
 159  */
 160 - (int)numberOfSongsInPlaylistAtIndex:(int)index;
 161
 162 /*!
 163  * @method classOfPlaylistAtIndex:
 164  */
 165 - (NSString *)classOfPlaylistAtIndex:(int)index;
 166
 167 /*!
 168  * @method currentPlaylistIndex
 169  */
 170 - (int)currentPlaylistIndex;
 171
 172 /*!
 173  * @method songTitleAtIndex:
 174  */
 175 - (NSString *)songTitleAtIndex:(int)index;
 176
 177 /*!
 178  * @method currentSongIndex
 179  */
 180 - (int)currentSongIndex;
 181
 182 /*!
 183  * @method currentSongTitle
 184  */
 185 - (NSString *)currentSongTitle;
 186
 187 /*!
 188  * @method currentSongArtist
 189  */
 190 - (NSString *)currentSongArtist;
 191
 192 /*!
 193  * @method currentSongAlbum
 194  */
 195 - (NSString *)currentSongAlbum;
 196
 197 /*!
 198  * @method currentSongGenre
 199  */
 200 - (NSString *)currentSongGenre;
 201
 202 /*!
 203  * @method currentSongLength
 204  */
 205 - (NSString *)currentSongLength;
 206
 207 /*!
 208  * @method currentSongRemaining
 209  */
 210 - (NSString *)currentSongRemaining;
 211
 212 /*!
 213  * @method currentSongRating
 214  */
 215 - (float)currentSongRating;
 216
 217 /*!
 218  * @method setCurrentSongRating:
 219  */
 220 - (BOOL)setCurrentSongRating:(float)rating;
 221
 222 /*!
 223  * @method equalizerEnabled
 224  */
 225 - (BOOL)equalizerEnabled;
 226
 227 /*!
 228  * @method setEqualizerEnabled:
 229  */
 230 - (BOOL)setEqualizerEnabled:(BOOL)enabled;
 231
 232 /*!
 233  * @method eqPresets
 234  */
 235 - (NSArray *)eqPresets;
 236
 237 /*!
 238  * @method currentEQPresetIndex
 239  */
 240 - (int)currentEQPresetIndex;
 241
 242 /*!
 243  * @method volume
 244  */
 245 - (float)volume;
 246
 247 /*!
 248  * @method setVolume:
 249  */
 250 - (BOOL)setVolume:(float)volume;
 251
 252 /*!
 253  * @method play
 254  */
 255 - (BOOL)play;
 256
 257 /*!
 258  * @method pause
 259  */
 260 - (BOOL)pause;
 261
 262 /*!
 263  * @method goToNextSong
 264  */
 265 - (BOOL)goToNextSong;
 266
 267 /*!
 268  * @method goToPreviousSong
 269  */
 270 - (BOOL)goToPreviousSong;
 271
 272 /*!
 273  * @method forward
 274  */
 275 - (BOOL)forward;
 276
 277 /*!
 278  * @method rewind
 279  */
 280 - (BOOL)rewind;
 281
 282 /*!
 283  * @method switchToPlaylistAtIndex:
 284  */
 285 - (BOOL)switchToPlaylistAtIndex:(int)index;
 286
 287 /*!
 288  * @method switchToSongAtIndex:
 289  */
 290 - (BOOL)switchToSongAtIndex:(int)index;
 291
 292 /*!
 293  * @method switchToEQAtIndex:
 294  */
 295 - (BOOL)switchToEQAtIndex:(int)index;
 296
 297 @end
 298
 299 /*!
 300  * @class ITMTRemote
 301  */
 302 @interface ITMTRemote : NSObject <ITMTRemote>
 303
 304 @end