A couple more modifications, as well as some comments to ease others'

[MenuTunes.git] / ITMTRemote.h

diff --git a/ITMTRemote.h b/ITMTRemote.h
index 3527c85..aedbc4d 100755 (executable)
--- a/ITMTRemote.h
+++ b/ITMTRemote.h
@@ -1,99 +1,113 @@
-/*
- *  MenuTunes
- *  ITMTRemote
- *    Plugin definition for audio player control via MenuTunes
- *
- *  Original Author : Matt Judy <mjudy@ithinksw.com>
- *   Responsibility : Matt Judy <mjudy@ithinksw.com>
- *
- *  Copyright (c) 2002 - 2003 iThink Software.
- *  All Rights Reserved
- *
- *     This header defines the Objective-C protocol which all MenuTunes Remote
- *  plugins must implement.  To build a remote, create a subclass of this
- *  object, and implement each method in the @protocol below.
- *
- */
-
-/*
- * TO DO:
- *
- * - Capability methods
- *
- */
-
-/*! @header ITMTRemote
- *  @abstract Declares the necessary protocol and class to implement a MenuTunes Remote.
- */
+/****************************************
+    ITMTRemote 1.0 (MenuTunes Remotes)
+    ITMTRemote.h
+    
+    Responsibility:
+        Joseph Spiros <joseph.spiros@ithinksw.com>
+    
+    Copyright (c) 2002 - 2003 by iThink Software.
+    All Rights Reserved.
+****************************************/
 
 #import <Cocoa/Cocoa.h>
 
-/*! @protocol ITMTRemote
- *  @abstract Declares what a MenuTunes Remote must be able to do.
- *  @discussion A MenuTunes Remote must be able to return and change state information.
- */
-
+#import <ITMTRemote/ITMTPlayer.h>
+#import <ITMTRemote/ITMTPlaylist.h>
+#import <ITMTRemote/ITMTTrack.h>
+#import <ITMTRemote/ITMTEqualizer.h>
+
+/*!
+    @typedef ITMTGenericProperty
+    @constant ITMTNameProperty The object's human readable name.
+    @constant ITMTImageProperty An image that can be associated with the object.
+*/
+typedef enum {
+    ITMTNameProperty,
+    ITMTImageProperty
+} ITMTGenericProperty;
+/*!
+    @typedef ITMTRemoteProperty
+    @constant ITMTRemoteNameProperty
+    @constant ITMTRemoteImageProperty
+    @constant ITMTRemoteAuthorProperty
+    @constant ITMTRemoteDescriptionProperty
+    @constant ITMTRemoteURLProperty
+    @constant ITMTRemoteCopyrightProperty
+*/
+typedef enum {
+    ITMTRemoteNameProperty,
+    ITMTRemoteImageProperty,
+    ITMTRemoteAuthorProperty,
+    ITMTRemoteDescriptionProperty,
+    ITMTRemoteURLProperty,
+    ITMTRemoteCopyrightProperty,
+    ITMTRemoteActivationStringProperty,
+    ITMTRemoteDeactivationStringProperty
+} ITMTRemoteProperty
+/*!
+    @typedef ITMTPlayerStyle
+    @constant ITMTSinglePlayerStyle Like iTunes, One player controls all available songs.
+    @constant ITMTMultiplePlayerStyle Like Audion, Multiple players control multiple playlists.
+    @constant ITMTSinglePlayerSinglePlaylistStyle Like *Amp, XMMS. Not recommended, but instead, developers are urged to use ITMTSinglePlayerStyle with emulated support for multiple playlists.
+*/
+typedef enum {
+    ITMTSinglePlayerStyle,
+    ITMTMultiplePlayerStyle,
+    ITMTSinglePlayerSinglePlaylistStyle
+} ITMTPlayerStyle;
+
+/*!
+    @protocol ITMTRemote
+    @abstract The ITMTRemote protocol is the protocol that all MenuTunes remotes' primary class must implement.
+*/
 @protocol ITMTRemote
-/*! @method remote:
- *  @abstract Return an autoreleased instance of the remote.
- *  @discussion Should be very quick and compact.
- * EXAMPLE:
- *   + (id)remote
- *   {
- *       return [[[MyRemote alloc] init] autorelease];
- *   }
- * @result The instance.
- */
+/*!
+    @method remote
+    @result Returns an autoreleased instance of the remote.
+*/
 + (id)remote;
 
-- (NSString *)title;
-// Return the title of the remote.
-
-- (NSString *)description;
-// Return a short description of the remote.
-
-- (NSImage *)icon;
-// Return a 16x16 icon representation for the remote.
-
-- (BOOL)begin;
-// Sent to the plugin when it should begin operation.
-
-- (BOOL)halt;
-// Sent to the plugin when it should cease operation.
-
-- (NSArray *)sources;
-- (int)currentSourceIndex;
-
-- (NSArray *)playlistsForCurrentSource;
-- (int)currentPlaylistIndex;
-
-- (NSString *)songTitleAtIndex;
-- (int)currentSongIndex;
-
-- (NSString *)currentSongTitle;
-- (NSString *)currentSongArtist;
-- (NSString *)currentSongAlbum;
-- (NSString *)currentSongGenre;
-- (NSString *)currentSongLength;
-- (NSString *)currentSongRemaining;
-
-- (NSArray *)eqPresets;
-
-- (BOOL)play;
-- (BOOL)pause;
-- (BOOL)goToNextSong;
-- (BOOL)goToPreviousSong;
-- (BOOL)goToNextPlaylist;
-- (BOOL)goToPreviousPlaylist;
-
-- (BOOL)switchToSourceAtIndex:(int)index;
-- (BOOL)switchToPlaylistAtIndex:(int)index;
-- (BOOL)switchToSongAtIndex:(int)index;
-- (BOOL)switchToEQAtIndex:(int)index;
-
+/*!
+    @method valueOfProperty:
+*/
+- (id)valueOfProperty:(ITMTRemoteProperty)property;
+
+/*!
+    @method propertiesAndValues
+*/
+- (NSDictionary *)propertiesAndValues;
+
+/*!
+    @method playerStyle
+    @result An ITMTPlayerStyle defining how the remote works with players and playlists.
+*/
+- (ITMTPlayerStyle)playerStyle;
+
+/*!
+    @method activate
+    @result A BOOL indicating success or failure.
+*/
+- (BOOL)activate;
+/*!
+    @method deactivate
+    @result A BOOL indicating success or failure.
+*/
+- (BOOL)deactivate;
+
+/*!
+    @method currentPlayer
+    @result An ITMTPlayer object representing the currently active player that the remote is controlling.
+*/
+- (ITMTPlayer *)currentPlayer
+/*!
+    @method players
+    @result An NSArray filled with ITMTPlayer objects.
+*/
+- (NSArray *)players;
 @end
 
-
+/*!
+    @class ITMTRemote
+*/
 @interface ITMTRemote : NSObject <ITMTRemote>
-
 @end