A couple more modifications, as well as some comments to ease others'
[MenuTunes.git] / ITMTRemote.h
index 8c1dcef..aedbc4d 100755 (executable)
-/*
-    iThink Software
-    MenuTunes SDK BETA (SUBJECT TO CHANGE)
+/****************************************
+    ITMTRemote 1.0 (MenuTunes Remotes)
     ITMTRemote.h
     
     ITMTRemote.h
     
-    Copyright 2003 by iThink Software, All Rights Reserved.
-    This is under Non-Disclosure
-*/
-
-/* 
-    Remotes need to include an Info.plist in their
-    bundle/wrapper. It needs to have the following keys
-    (with string values):
-        
-        ITMTRemoteName
-        ITMTRemoteVersion
-        ITMTRemotePublisher
-        ITMTRemoteCopyright
-        ITMTRemoteDescription
-        ITMTRemoteIconFile
-        
-    It also needs to have an icon file who's filename (Relative)
-    is indicated in the ITMTRemoteIconFile value.
-*/
-
+    Responsibility:
+        Joseph Spiros <joseph.spiros@ithinksw.com>
+    
+    Copyright (c) 2002 - 2003 by iThink Software.
+    All Rights Reserved.
+****************************************/
 
 #import <Cocoa/Cocoa.h>
 
 
 #import <Cocoa/Cocoa.h>
 
-typedef enum {
-    ITMTRemoteName,
-    ITMTRemoteVersion,
-    ITMTRemotePublisher,
-    ITMTRemoteCopyright,
-    ITMTRemoteDescription
-} ITMTRemoteInformationString;
-
-typedef enum {
-    ITMTRemotePlayerStopped = -1,
-    ITMTRemotePlayerPaused,
-    ITMTRemotePlayerPlaying,
-    ITMTRemotePlayerRewinding,
-    ITMTRemotePlayerForwarding
-} ITMTRemoteControlState;
-
-typedef enum {
-    ITMTRemoteStop = -1,
-    ITMTRemotePause,
-    ITMTRemotePlay,
-    ITMTRemoteRewind,
-    ITMTRemoteFastForward,
-    ITMTRemotePreviousTrack,
-    ITMTRemoteNextTrack
-} ITMTRemoteControlAction;
+#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 {
 typedef enum {
-    ITMTRemoteSinglePlaylist,
-    ITMTRemoteLibraryAndPlaylists,
-    ITMTRemoteSeperatePlaylists
-} ITMTRemotePlaylistMode;
-
+    ITMTNameProperty,
+    ITMTImageProperty
+} ITMTGenericProperty;
+/*!
+    @typedef ITMTRemoteProperty
+    @constant ITMTRemoteNameProperty
+    @constant ITMTRemoteImageProperty
+    @constant ITMTRemoteAuthorProperty
+    @constant ITMTRemoteDescriptionProperty
+    @constant ITMTRemoteURLProperty
+    @constant ITMTRemoteCopyrightProperty
+*/
 typedef enum {
 typedef enum {
-    ITMTRemoteTrackName,
-    ITMTRemoteTrackArtist,
-    ITMTRemoteTrackAlbum,
-    ITMTRemoteTrackComposer,
-    ITMTRemoteTrackNumber,
-    ITMTRemoteTrackTotal,
-    ITMTRemoteTrackComment,
-    ITMTRemoteTrackGenre,
-    ITMTRemoteTrackYear,
-    ITMTRemoteTrackRating,
-    ITMTRemoteTrackArt
-} ITMTRemoteTrackProperty;
-
+    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 {
 typedef enum {
-    ITMTRemoteRepeatNone,
-    ITMTRemoteRepeatAll,
-    ITMTRemoteRepeatOne
-} ITMTRemoteRepeatMode;
-
-/*enum {
-    ITMTRemoteCustomPreset = -1;
-}*/
-
+    ITMTSinglePlayerStyle,
+    ITMTMultiplePlayerStyle,
+    ITMTSinglePlayerSinglePlaylistStyle
+} ITMTPlayerStyle;
+
+/*!
+    @protocol ITMTRemote
+    @abstract The ITMTRemote protocol is the protocol that all MenuTunes remotes' primary class must implement.
+*/
 @protocol ITMTRemote
 @protocol ITMTRemote
+/*!
+    @method remote
+    @result Returns an autoreleased instance of the remote.
+*/
 + (id)remote;
 + (id)remote;
-- (NSString*)informationString:(ITMTRemoteInformationString)string;
-- (NSImage*)icon;
-
-- (BOOL)begin;
-- (BOOL)halt;
-
-- (BOOL)supportsControlAction:(ITMTRemoteControlAction)action;
-- (BOOL)sendControlAction:(ITMTRemoteControlAction)action;
-- (ITMTRemoteControlState)controlState;
-
-- (ITMTRemotePlaylistMode)playlistMode;
-- (NSArray*)playlistNames;
-- (BOOL)switchToPlaylist:(int)playlistIndex;
-- (BOOL)switchToTrackAtIndex:(int)index;
-- (int)indexForTrack:(int)identifier inPlaylist:(int)playlistIndex;
-- (int)identifierForTrackAtIndex:(int)index inPlaylist:(int)playlistIndex;
-
-- (BOOL)supportsTrackProperty:(ITMTRemoteTrackProperty)property;
-- (id)trackProperty:(ITMTRemoteTrackProperty)property atIndex:(int)index;
-- (BOOL)setTrackProperty:(ITMTRemoteTrackProperty)property toValue:(id)value atIndex:(int)index;
-/* currently only used to set Ratings... someday, we might provide a full frontend? well, it is possible that other apps could use MT remotes, as such, they might want to set other values. For Rating, send in an NSNumber from a float 0.0 - 1.0. For Art, send in an NSImage... this is also what you'll recieve when using the accessor */
 
 
+/*!
+    @method valueOfProperty:
+*/
+- (id)valueOfProperty:(ITMTRemoteProperty)property;
 
 
-- (BOOL)supportsShuffle;
-- (BOOL)setShuffle:(BOOL)toggle;
-- (BOOL)shuffle;
-
-- (BOOL)supportsRepeatMode:(ITMTRemoteRepeatMode)repeatMode;
-- (BOOL)setRepeatMode:(ITMTRemoteRepeatMode)repeatMode;
-- (ITMTRemoteRepeatMode)repeatMode;
-
-- (BOOL)supportsVolume;
-- (BOOL)setVolume:(float)volume;
-- (float)volume;
-
-- (BOOL)supportsCustomEqualizer;
-- (BOOL)showEqualizerWindow;
+/*!
+    @method propertiesAndValues
+*/
+- (NSDictionary *)propertiesAndValues;
 
 
-- (BOOL)supportsEqualizerPresets;
-- (NSArray*)equalizerPresetNames;
-- (BOOL)switchToEqualizerPreset:(int)index; // ITMTRemoteCustomPreset = Custom
+/*!
+    @method playerStyle
+    @result An ITMTPlayerStyle defining how the remote works with players and playlists.
+*/
+- (ITMTPlayerStyle)playerStyle;
 
 
-- (BOOL)supportsExternalWindow;
-- (NSString*)externalWindowName;
-- (BOOL)showExternalWindow;
+/*!
+    @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
 
 @end
 
+/*!
+    @class ITMTRemote
+*/
 @interface ITMTRemote : NSObject <ITMTRemote>
 @interface ITMTRemote : NSObject <ITMTRemote>
-
-@end
\ No newline at end of file
+@end