File: programming/cocoa/UKDistributedView.zip/UKDistributedView/UKDistributedView.h


/* =============================================================================
	FILE:		UKDistributedView.h
	PROJECT:	UKDistributedView
 
	PURPOSE:	An NSTableView-like class that allows arbitrary positioning
				of evenly-sized items. This is intended for things like the
				Finder's "icon view", and even lets you snap items to a grid
				in various ways, reorder them etc.
				
				Your data source must be able to provide a position for its
				list items, which are simply enumerated. An NSCell subclass
				can be used for actually displaying the data, e.g. as an
				NSImage or similar.
 
    COPYRIGHT:  (c) 2003 M. Uli Kusterer, all rights reserved.
    
	AUTHORS:	M. Uli Kusterer - UK
    
    LICENSES:   GPL or Commercial (See Readme)
 
	REVISIONS:
        2005-02-22  UK  Moved multi-positioning-mode flag to runtime flags.
                        Somehow it had ended up in the persistent flags struct.
		2003-06-24  UK	Created.
   ========================================================================== */
 
/* -----------------------------------------------------------------------------
	Headers:
   -------------------------------------------------------------------------- */
 
#import <AppKit/AppKit.h>
 
 
/* -----------------------------------------------------------------------------
	Constants:
   -------------------------------------------------------------------------- */
 
/* Set this to zero to cause "snap guides" to be drawn as simple blue boxes
	with a semi-transparent white fill. If this is on (the default) you'll
	get a transparent version of the cell drawn in the location it will snap
	to. */
 
#ifndef UKDISTVIEW_DRAW_FANCY_SNAP_GUIDES
#define UKDISTVIEW_DRAW_FANCY_SNAP_GUIDES		1
#endif
 
/* Set this to 0 to cause deprecated methods to be excluded. This is useful
	for spotting where your app still makes calls to them. */
 
#ifndef UKDISTVIEW_BACKWARDS_COMPATIBLE
#define UKDISTVIEW_BACKWARDS_COMPATIBLE			1
#endif
 
/* The following is used to determine how many items to cache around the ones
	actually visible. More means speedier scrolling, less means better drawing
	and mouse tracking performance. Note that this doesn't really find that
	number of items on each side, but rather just extends the rect in which
	items must lie to be cached so it can hold that many items. */
#ifndef UKDISTVIEW_INVIS_ITEMS_CACHE_COUNT
#define UKDISTVIEW_INVIS_ITEMS_CACHE_COUNT		0
#endif
 
 
/* Amount of seconds within which another key must be pressed to still be added
    to the current "word" for type-ahead-selection. If you wait longer than
    this, the search string will be cleared and it will look for an item
    beginning with the typed character. */
#ifndef UKDV_TYPEAHEAD_INTERVAL
#define UKDV_TYPEAHEAD_INTERVAL                 0.8
#endif
 
 
/* This is the pasteboard type that is used during a real "drag and drop"
	drag to add the positions of the dragged items to the drag. Note that
	these positions are relative to the location of the dragged image, i.e.
	if you drag 5 items, the one in the lower left will probably be at 0,0.
	The coordinates are stored as an array of NSData objects containing an
	NSPoint, and are in Quartz coordinates, i.e. the y axis increases upwards. */
#define UKDistributedViewPositionsPboardType	@"UKDistributedViewPositionsPboardType"
 
 
/* -----------------------------------------------------------------------------
	Data Types:
   -------------------------------------------------------------------------- */
 
/* UKDVPersistentFlags:
	These flags are used to keep how you set up the view. They control general
	behaviour and are saved to NSArchivers and restored from there (think NIB). */#ifdef __BIG_ENDIAN__
// Force all cells' positions to the grid. This behaves like "keep arranged by name" in Finder, and doesn't change actual cell positions.
// Force moved and new cells' positions to the grid. This behaves like "snap to grid" in MacOS 9's Finder and actually changes cell positions, but doesn't move existing cells.
// Dragging an item changes its position.
// Try to drag locally even when the data source supports inter-application drag & drop, and only start DnD drag when the mouse leaves the view.
// Can select more than one item?
// Can select less than one item?
// May user drag in empty areas to get a "rubber band"-style selection rect?
// Should this view always resize to enclose its items?
// Show position indicator boxes during drag with grid?
// Draw lines where the grid is?
// Fill the background with white? (calls -drawBackgroundInRect:)
// unused.
      #else
// unused.
// Fill the background with white? (calls -drawBackgroundInRect:)
// Draw lines where the grid is?
// Show position indicator boxes during drag with grid?
// Should this view always resize to enclose its items?
// May user drag in empty areas to get a "rubber band"-style selection rect?
// Can select less than one item?
// Can select more than one item?
// Try to drag locally even when the data source supports inter-application drag & drop, and only start DnD drag when the mouse leaves the view.
// Dragging an item changes its position.
// Force moved and new cells' positions to the grid. This behaves like "snap to grid" in MacOS 9's Finder and actually changes cell positions, but doesn't move existing cells.
// Force all cells' positions to the grid. This behaves like "keep arranged by name" in Finder, and doesn't change actual cell positions.
      #endif
/* UKDVRuntimeFlags
	These are flags that aren't persistent and are simply for state while the
	view is being used. Flags specified here won't be saved to an NSArchiver. */#ifdef __BIG_ENDIAN__
// Draw "snap position" indicator behind selected items right now?
// Draw highlight indicating we accept a drop around the edges of the view?
// YES when we're in multi-position mode, which causes a speed-up when positioning new items by doing some caching.
// unused.
      #else
// unused.
// YES when we're in multi-position mode, which causes a speed-up when positioning new items by doing some caching.
// Draw highlight indicating we accept a drop around the edges of the view?
// Draw "snap position" indicator behind selected items right now?
      #endif
/* -----------------------------------------------------------------------------
	UKDistributedView:
   -------------------------------------------------------------------------- */// You *should* be using the accessors below:
// The data source thet provides our items.
// The delegate that receives messages from us.
	NSSize				cellSize;					// Size of cells and grid when ordering items by grid.
// Size of grid to align items on. Usually, this is half our cell size.
// How many pixels of border to leave around the items.
// The prototype cell used for our items.
// The selection. *not persistent*
	UKDVPersistentFlags flags;                      // Persistent flags and boolean properties.
// Color to use for grid lines.
 
// private: *do not use*
// Item currently being tracked on a click.
// Last mouse position during mouse tracking.
// Selection rect while we're tracking it.
// Flags used to temporarily change behavior at runtime.
// Cached item position for multiPositionMode to more quickly allow positioning new items.
// Cached indexes of the items that are below the lastSuggestedItemPos. These are the only ones we have to collision-detect.
// Rect in which we last cached the indexes of visible items.
// Cached indexes of the items that are visible in the visibleItemRect.
// Item being highlighted during drop.
// Position dragged image started out in.
// Item being edited using inline-editing. -1 if we're not editing.
// String used for type-selection.
// Last time user typed ahead, so we know when to clear typeAheadSearchStr.
// Used to find out how many items to add/remove on numberOfItemsChanged.
// Reserved for future use.
// Reserved for future use.
// Reserved for future use.
// Reserved for future use.
}
 
// Data source & delegate:
// Selection:
// Set to YES to get a "rubber-band" selection rectangle when empty areas are clicked.
// Use above calls if possible, your users will be grateful.
#if UKDISTVIEW_BACKWARDS_COMPATIBLE
// Deprecated name. Use selectedItemIndex instead.
#endif /*UKDISTVIEW_BACKWARDS_COMPATIBLE*/
// UKDistView-specific actions:
// Options for behavior:
// Nudges all items into the grid when displaying/hit testing.
// Snaps items moved by the user and newly created ones to the grid, but keeps existing items at their positions.
// Shows little boxes when dragging an item with grid on, so the user knows where the item will actually end up.
// Clicking an item allows the user to drag it around.
// Use view-internal drags until mouse leaves this view, and only then try to DnD.
// Options for drawing:
// The cell used for displaying items:
// Data management:
// Sizing, margins etc.:
// Set margin around content area. This border isn't really enforced, but is used by the positioning and rescrolling methods.
// Cell size. All items must be the same size. Also changes gridSize to cellSize /2.
// Always make this object resize so it encloses all its items or fills the visible area of the containing scroll view.
/* Determining/changing positions of items in this view:
	Note that those of these for changing a position change the actual item positions, *permanently*. */// Get best position for a new item.
// Calculate a position based on its item number and the view's width. Use this to calculate item positions if you're implementing "keep arranged by..."-style views.
// Move an item from its current to the next best position (as in, unoccupied and on-grid).
// Set this to YES to speed up groups of positionItem: calls
// Places all items on grid positions, starting at the top left in horizontal lines. They are put in their natural order, i.e. starting with 0 in the top left, 1 to its right etc.
// Places all items on the nearest grid positions. Does the same as "clean up" does in the Finder.
// Returns a flipped rect.
 
// Drawing:
// Cause redraw of an item (eventually calls setNeedsDisplayInRect: on this view).
// Position has reversed Y-axis.
 
// Hit-testing:
// aBox must have a reversed Y-axis. This checks for intersection of the two rects.
 
// Goodies for zooming/sizing windows:
// This is what Finder X never gets right. This moves all items so the leftmost one is at the left of the view and the topmost one at the top, removing any empty space above them, but not changing the items' relative positions.
// Do this after a rescroll to get the best size for showing all window contents at their current positions.
-(NSSize)	bestSize;						// Similar to bestRect, but returns the extents of all items (plus margins). I.e. this is what bestRect.size would be after a rescroll.
// Useful for zooming. Calls bestSize to determine a good size for this view.
// Same as windowFrameSizeForBestSize, but returns a rect so the window's upper left corner doesn't move.
 
// Inline editing:
/*may be NIL*/// Scrolling when embedded in an NSScrollView:
// Customization:
// Draws one of the "snap guide" boxes indicating where your item will end up.
// By default fills the rect with white.
// private:
// Calls forceRectToGrid if forceToGrid is true, otherwise returns the rect unmodified.
// Build cache of (potentially) visible items used for drawing and mouse tracking.
// Uses cache in multi-positioning mode, otherwise calls getUncachedItemIndexInRect:.
/* -----------------------------------------------------------------------------
	Data source protocol:
   -------------------------------------------------------------------------- *//* NOTE: Item positions are in "flipped" coordinates, i.e. the y-axis has
		been reversed and starts at the top and increases down. That way,
		items will not need to be repositioned when the view or window
		are resized. */
 
/* You *must* implement these to do anything useful:
	You are supposed to directly manipulate the cell passed to display your
	data in it appropriately. Handy tip: Messages to nil objects are simply
	ignored. *//* may be nil if the view only wants the item position. */// Implement this if you want the user to be able to reposition your items:
// Implement this if you want user to be able to edit cell titles:
//  In addition, you will have to set your prototype cell's isEditable property
//  either when creating it, or in distributedView:positionForCell:atItemIndex:
//  in the course of preparing your cell.
// Implement this if you want tool tips for items in the view:
/* -----------------------------------------------------------------------------
	Drag & Drop protocol for data source:
   -------------------------------------------------------------------------- */
 
//  These are optional. If not implemented, but setPosition is, you can still
//  perform old-style "live" moving of the items inside their window.
// Write the requested items' data to the specified pasteboard:
// Are we copying when dragging out of this view?
// Specify where the dropped data should end up. On ("inside") an item, or just among them?
// Change "row", if you want. -1 means it's not on any item.
 
// Say whether you accept a drop of an item:
// Use this to handle drops on the trash etc:
/* -----------------------------------------------------------------------------
	Delegate protocol:
   -------------------------------------------------------------------------- */// Called upon a mouseUp in a cell: (except if it was a drag)
// Called on the second mouseDown of a double-click in a cell: (except if it was on the text area and the cell is editable)
// Selection changes: (not sent for programmatic selection changes)
// Return the item that matches a string:
//  UKDV sends this for type-ahead with options being NSCaseInsensitiveSearch and NSAnchoredSearch
//  (meaning ignore case and match only strings that start with this string), and
//  when you call selectItemContainingString: with options NSCaseInsensitiveSearch.
//	UKDV provides a default implementation of this that works if your items are
//	ordered alphabetically already.
// For displaying progress info for large lists:
/* -----------------------------------------------------------------------------
	Notifications:
   -------------------------------------------------------------------------- */// Object is the UKDistributedView.
 

This code uses the PclZip Zip File reading code, which is subject to the GNU LGPL. It also uses the GeSHi syntax highlighter, subject to the GPL. Ask if you want this for your own web site, it's free.