Upstream Chrome on iOS source code [8/11].

ios/chrome/browser/ui/stack_view/card_stack_layout_manager.h

+// Copyright 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef IOS_CHROME_BROWSER_UI_STACK_VIEW_CARD_STACK_LAYOUT_MANAGER_H_
+#define IOS_CHROME_BROWSER_UI_STACK_VIEW_CARD_STACK_LAYOUT_MANAGER_H_
+
+#import <CoreGraphics/CoreGraphics.h>
+#import <Foundation/Foundation.h>
+
+#include "base/mac/scoped_nsobject.h"
+
+@class StackCard;
+
+// Encapsulates a stack of cards and their layout behavior, supporting
+// fanning the cards out along an axis and gathering them to fit in a given
+// area.
+@interface CardStackLayoutManager : NSObject {
+ @private
+  base::scoped_nsobject<NSMutableArray> cards_;
+  // YES if the previous call to one of {|scrollCardAtIndex|,
+  // |handleMultitouchWithFirstDelta|} was to the former method; NO otherwise.
+  BOOL treatOverExtensionAsScroll_;
+  NSUInteger previousFirstPinchCardIndex_;
+  NSUInteger previousSecondPinchCardIndex_;
+}
+
+// The size of a card. Setting this property preserves card origins with the
+// exception that cards are moved as necessary to satisfy placement constraints
+// (e.g., that a card is not placed too far away from its preceding neighbor).
+@property(nonatomic, assign) CGSize cardSize;
+// The center of a card along the axis that is not the layout axis.
+@property(nonatomic, assign) CGFloat layoutAxisPosition;
+// The amount cards should be staggered at full expansion.
+@property(nonatomic, assign) CGFloat maxStagger;
+// The maximum amount that the first card is allowed to overextend toward the
+// start or the end.
+@property(nonatomic, assign) CGFloat maximumOverextensionAmount;
+// The offset denoting the start of the visible stack.
+@property(nonatomic, assign) CGFloat startLimit;
+// The offset denoting the end of the visible stack. Setting this property
+// causes the end stack to be recomputed.
+@property(nonatomic, assign) CGFloat endLimit;
+// YES if the cards should be laid out vertically. Default is YES. A change in
+// this property also sets the cards' positions along the new layout axis to
+// their positions along the previous layout axis.
+@property(nonatomic, assign) BOOL layoutIsVertical;
+// TODO(blundell): The below two vars should be changed to NSUIntegers so that
+// the implementation can uniformly use NSUIntegers. b/5956653
+// The index of the last card that is in the initial stack.
+@property(nonatomic, readonly, assign) NSInteger lastStartStackCardIndex;
+// The index of the first card that is in the ending stack.
+@property(nonatomic, readonly, assign) NSInteger firstEndStackCardIndex;
+
+// Adds a |card| to the top (z-index) of the stack.
+- (void)addCard:(StackCard*)card;
+
+// Adds a |card| to the stack at the given index.
+- (void)insertCard:(StackCard*)card atIndex:(NSUInteger)index;
+
+// Removes |card| from the stack.
+- (void)removeCard:(StackCard*)card;
+
+// Removes all cards from the stack.
+- (void)removeAllCards;
+
+// Returns an array of cards, ordered from bottom to top of the stack (in
+// z-order terms).
+- (NSArray*)cards;
+
+// Based on the cards' current positions and the value of |startLimit|, caps
+// cards that should be in the start stack.
+- (void)layOutStartStack;
+
+// Fans out the cards and then gathers them in such that the first card not
+// collapsed into the start stack is the card at |startIndex|.
+- (void)fanOutCardsWithStartIndex:(NSUInteger)startIndex;
+
+// Scrolls the card at |index| by |delta| (and trailing cards by a maximum of
+// |delta| depending on whether evening out after pinching needs to occur).
+// Scrolls leading cards by delta if |scrollLeadingCards| is |YES|; otherwise,
+// does not scroll leading cards. Allows a certain amount of overscrolling
+// toward the start and end. If |decayOnOverscroll| is |YES|, the impact of the
+// scroll decays once the stack is overscrolled. If |allowEarlyOverscroll|
+// is |YES|, overscrolling is allowed to occur naturally on the scrolled card;
+// otherwise, overscrolling is not allowed to occur until the stack is fully
+// collapsed/fanned out.
+- (void)scrollCardAtIndex:(NSUInteger)index
+                  byDelta:(CGFloat)delta
+     allowEarlyOverscroll:(BOOL)allowEarlyOverscroll
+        decayOnOverscroll:(BOOL)decayOnOverscroll
+       scrollLeadingCards:(BOOL)scrollLeadingCards;
+
+// Returns whether the card at |index| is overextended toward the start.
+- (BOOL)overextensionTowardStartOnCardAtIndex:(NSUInteger)index;
+// Returns whether the first card is overextended toward the end. Note that
+// overextension is not a meaningful concept for other cards, as a pinch is
+// allowed to leave cards other than the first card resting in arbitrary
+// positions.
+- (BOOL)overextensionTowardEndOnFirstCard;
+// Moves the cards so that any overextension is eliminated, with the nature of
+// the movement being dependent on whether a scroll or a pinch occurred last.
+- (void)eliminateOverextension;
+
+// Scrolls the card at |index| to be at the maximum separation from the
+// neighboring card, followed by handling start and end capping. If |preceding|,
+// the card at |index| is scrolled away from the previous card toward the end
+// stack, otherwise it is scrolled away from the next card toward the start
+// stack. Also scrolls the cards that the card at |index| is scrolled toward,
+// but does not alter the positions of the cards it is being scrolled away from.
+- (void)scrollCardAtIndex:(NSUInteger)index awayFromNeighbor:(BOOL)preceding;
+
+// Updates the card positions based on the passed-in multitouch event, in which
+// |firstCardIndex| represents the card closer to the start stack,
+// |secondCardIndex > firstCardIndex| represents the card closer to the end
+// stack, and |firstDelta| and |secondDelta| represent the two cards'
+// respective movements. Caps card positions when cards get too close to each
+// other. Allows overpinch toward the start stack, and allows the first card to
+// overpinch toward the end stack when it is being pinched. If
+// |decayOnOverpinch| is |YES|, the impact of each side of the pinch is
+// decayed once the card being pinched is overpinched.
+- (void)handleMultitouchWithFirstDelta:(CGFloat)firstDelta
+                           secondDelta:(CGFloat)secondDelta
+                        firstCardIndex:(NSInteger)firstCardIndex
+                       secondCardIndex:(NSInteger)secondCardIndex
+                      decayOnOverpinch:(BOOL)decayOnOverpinch;
+
+// The length required to display a fully fanned-out stack.
+- (CGFloat)fannedStackLength;
+
+// The maximum length that the stack could possibly grow to accounting for the
+// fact that the user can pinch to pull cards apart further than the fanned-out
+// separation.
+- (CGFloat)maximumStackLength;
+
+// The length required to display a fully collapsed stack. Note that this does
+// not depend on the number of cards in the stack; it will always return the
+// amount needed to show an arbitrarily large stack, so that it has a
+// consistent result that can be used to compute card sizes/margins.
+- (CGFloat)fullyCollapsedStackLength;
+
+// Returns YES if |card| is completely covered by other cards.
+- (BOOL)cardIsCovered:(StackCard*)card;
+
+// Returns whether |card| is collapsed behind its succeeding neighbor, defined
+// as being separated by <= the separation distance between visible cards in the
+// edge stacks.
+- (BOOL)cardIsCollapsed:(StackCard*)card;
+
+// Returns whether the title label for |card| is covered by its succeeding
+// neighbor or the edge of the screen.
+- (BOOL)cardLabelCovered:(StackCard*)card;
+
+// Returns |YES| if all cards are scrolled into the start stack.
+- (BOOL)stackIsFullyCollapsed;
+
+// Returns |YES| if the stack is fully fanned out.
+- (BOOL)stackIsFullyFannedOut;
+
+// Returns |YES| if the stack is fully overextended toward the start or the
+// end.
+- (BOOL)stackIsFullyOverextended;
+
+// The amount that the first card is currently overextended.
+- (CGFloat)overextensionAmount;
+
+// The number of cards visible when stack is fanned out.
+- (NSUInteger)fannedStackCount;
+
+@end
+
+#endif  // IOS_CHROME_BROWSER_UI_STACK_VIEW_CARD_STACK_LAYOUT_MANAGER_H_