#import <Cocoa/Cocoa.h>


/*

PMFlowView Gestures and Actions
===============================

Mouse:

	+ left button double click:
	  - open selected item by sending -flowView:openIndex:withEvent: to the delegate

	+ left button single click:
	  - make first responder
	  - move, unless the user clicked near the selected item's image
	    - keep moving if the button is held, get faster with time

	+ left button drag:  
	  - horizontally: move
	  - vertically (delta>50): select first/last item, then start over

	+ right button single click:
	  - show context menu as supplied by the delegate via -flowView:menuForEvent:

	+ horizonal scrollwheel/touchpad swipe:
	  - move (mildly exponential)

Keyboard:

	+ left/right arrow:
	  - move

	+ return/enter:
	  - open selected item by sending -flowView:openIndex:withEvent: to the delegate

	+ backspace/delete:
	  - delete selected item by sending -flowView:deleteIndex: to the delegate

	+ escape:
	  - exit fullscreen mode by sending -flowView:changeCaptureState: to the delegate

*/


// PMFlowView.bundle's principal class, the one you'll ask for flow views
@protocol PMFlowViewBundleController

	// get an autoreleased flow view instance -- delegate must exist and conform to PMFlowViewDelegate
	+ (id)flowViewWithFrame: (NSRect)theFrame delegate: (id)theDelegate key: (id)theKey;

@end


// this is how you talk to your flow views
@protocol PMFlowView

	// the delegate you had to supply
	- (id)delegate;	// this is a weak reference, i.e. the delegate is not retained by the flow view

	// populate flow view
	- (void)reloadData;
	- (void)reloadDataAfterDelay: (NSTimeInterval)theDelay;	// triggered automatically on frame size changes
	- (void)clear;	// doesn't empty the cache -- see below

	// send one of these when an image has changed
	- (BOOL)invalidateImageAtIndex: (int)theIndex;
	- (BOOL)invalidateImageWithUniqueID: (NSString*)theUniqueID;

	// empties the image cache, which is only used when you return valid unique IDs -- see below
	- (void)emptyCache;

	// set/get the frontmost image via index
	- (void)selectIndex: (int)theIndex;
	- (void)moveSelectedIndex: (int)theIndexDelta;
	- (int)selectedIndex;

	// invert horizontal scrollwheel/touchpad scrolling?
	- (void)setInverted: (BOOL)invert;
	- (BOOL)isInverted;

	// full screen mode -- we're actually displaying a full screen window instead of capturing the screen, because we want to be able to display the menu bar and overlay windows
	- (BOOL)setCapturesScreen: (BOOL)capture;
	- (BOOL)capturesScreen;

@end


// and this is how flow views talk to you
@protocol PMFlowViewDelegate

	// number of items to display
	- (int)numberOfItemsInFlowView: (NSView<PMFlowView>*)theFlowView;

	// the actual data -- images will be cached unless the delegate returns nil in -flowView:uniqueIDAtIndex:
	- (NSString*)flowView: (NSView<PMFlowView>*)theFlowView uniqueIDAtIndex: (int)theIndex;	// e.g., a UUID
	- (NSImage*)flowView: (NSView<PMFlowView>*)theFlowView imageAtIndex: (int)theIndex;
	- (NSString*)flowView: (NSView<PMFlowView>*)theFlowView nameAtIndex: (int)theIndex;

	// sent on selection updates
	- (void)flowView: (NSView<PMFlowView>*)theFlowView selectedIndexMightHaveChanged: (int)theIndex;

	// context menu
	- (NSMenu*)flowView: (NSView<PMFlowView>*)theFlowView menuForEvent: (NSEvent*)theEvent;

	// open the selected item
	- (BOOL)flowView: (NSView<PMFlowView>*)theFlowView openIndex: (int)theIndex withEvent: (NSEvent*)theEvent;

	// delete selected item -- updates the interface if the delegate returns YES
	- (BOOL)flowView: (NSView<PMFlowView>*)theFlowView deleteIndex: (int)theIndex;

	// image cell size -- it's a good idea to have this depend on the view's size
	- (NSSize)cellSizeOfFlowView: (NSView<PMFlowView>*)theFlowView;

	// the user wants to toggle full screen mode -- if that's fine with the delegate, send -setCapturesScreen:
	- (BOOL)flowView: (NSView<PMFlowView>*)theFlowView changeCaptureState: (BOOL)capture;

@end