//
// WTFeedbackViewDemo   1.0
//
// Created by Wagner Truppel on 2009-10-08.
// Copyright 2009 Wagner Truppel (jrcapab@gmail.com). All rights reserved.
//
// Redistribution and use in binary and source forms, with or without
// modification, are permitted for any project, commercial or otherwise,
// provided that the following conditions are met:
//
// Redistributions in binary form must display the copyright notice in the
// About view, website, and/or documentation.
//
// Redistributions of source code must retain the copyright notice, this
// list of conditions, and the following disclaimer.
//
// THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
// OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY RIGHTS.
// IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
// DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
// OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
// USE OR OTHER DEALINGS IN THIS SOFTWARE.
//



WTFeedbackView is a class to display a HUD-like view with either an activity
indicator view or a progress view. It's based on DSActivityView by David
Sinclair (http://www.dejal.com/developer/dsactivityview), with some significant
additions and modifications.



More specifically, WTFeedbackView offers:

- Client access through a single class, by means of class methods only,
  for all features;

- Changes to the text being shown trigger an animation that resizes the
  HUD view appropriately;

- Three built-in styles (like DSActivityView):

    * Simple style: displays a transparent view containing an activity
      indicator view next to the text explaining the ongoing activity;

    * Bezel style: displays a dark semi-transparent view containing
      either an activity indicator view or a progress view, above the
      text explaining the ongoing activity;

    * Keyboard style: same as the Bezel style, but covering only the
      keyboard;

- Three built-in kinds:

    * Activity kind: displays only an activity indicator view, plus
      the text explaining the ongoing activity;

    * Progress kind: displays only a progress view, plus the text
      explaining the ongoing activity;

    * Flexible kind: contains both an activity indicator view and a
      progress view (plus the text explaining the ongoing activity),
      but displays only one at a time, on demand. This is useful when
      the ongoing activity has parts whose lengths are sometimes
      known and sometimes unknown. Rather than create a new feedback
      view for each part, a single one can be used, minimizing
      screen distractions;

- Easy updating of the progress view, through a class method
  +updateProgress: (CGFloat) progress;

- Thread-safety where needed. For instance, +updateProgress: can be
  safely invoked from a background thread;

- Possibility to subclass WTFeedbackView to create custom feedback
  views having the general behavior of WTFeedbackView but looking
  differently.



Usage:


The typical usage is very simple: invoke one of the factory methods

+ (WTFeedbackView*) newSimpleActivityViewForView: (UIView*) addToView;
+ (WTFeedbackView*) newSimpleActivityViewForView: (UIView*) addToView
                                        withText: (NSString*) labelText;

+ (WTFeedbackView*) newBezelActivityViewForView: (UIView*) addToView;
+ (WTFeedbackView*) newBezelActivityViewForView: (UIView*) addToView
                                       withText: (NSString*) labelText;

+ (WTFeedbackView*) newBezelProgressViewForView: (UIView*) addToView;
+ (WTFeedbackView*) newBezelProgressViewForView: (UIView*) addToView
                                       withText: (NSString*) labelText;

+ (WTFeedbackView*) newBezelFlexibleViewForView: (UIView*) addToView
                            showingProgressView: (BOOL) showing;
+ (WTFeedbackView*) newBezelFlexibleViewForView: (UIView*) addToView
                            showingProgressView: (BOOL) showing
                                       withText: (NSString*) labelText;

+ (WTFeedbackView*) newKeyboardActivityView;
+ (WTFeedbackView*) newKeyboardActivityViewWithText: (NSString*) labelText;

+ (WTFeedbackView*) newKeyboardProgressView;
+ (WTFeedbackView*) newKeyboardProgressViewWithText: (NSString*) labelText;

+ (WTFeedbackView*) newKeyboardFlexibleViewShowingProgressView: (BOOL) showing;
+ (WTFeedbackView*) newKeyboardFlexibleViewShowingProgressView: (BOOL) showing
                                               withText: (NSString*) labelText;

to display the feedback view, then invoke one of the dismissal methods

+ (void) removeView;
+ (void) removeViewAnimating: (BOOL) animating;

when you want to remove the feedback view from the screen.



If you're using a feedback view that contains a progress view, then you use

+ (void) updateProgress: (CGFloat) progress;

to update the state of the progress bar.



If you're using a flexible feedback view (one that can show both an activity
indicator view and a progress view), then you use

+ (void) switchToActivityIndicatorView;
+ (void) switchToProgressView;

to switch to the view you need at the moment.



If you need to change the text being shown, you invoke

+ (void) setText: (NSString*) text;



All these methods are thread-safe.



If you need to create a customized feedback view, look at the FunkyFeedbackView
class of the demo application, which shows how to subclass WTFeedbackView to
produce a feedback view that behaves like WTFeedbackView but which looks
differently.



Although iPhoneOS 3.x isn't a requirement, WTFeedbackView and the demo were
compiled using iPhoneOS 3.1.2. They were *not* tested on any version prior
to 3.x, so don't assume they will work with 2.x.



NOTE: The demo source code contains some odd-looking statements (BEGIN, END,
and RETURN). These are preprocessor macros defined in CustomLogging.h, and are
used along with WTLOG(@"...") as a replacement for NSLog(@"..."), showing the
call stack in a hierarchical fashion, like so:


(Main) AppDelegate: -applicationDidFinishLaunching
  (Main) RootViewController: -shouldAutorotateToInterfaceOrientation
  (Main) RootViewController: -shouldAutorotateToInterfaceOrientation
(Main) RootViewController: -viewDidLoad
(Main) RootViewController: -shouldAutorotateToInterfaceOrientation
  (Main) RootViewSection: -awakeFromNib
  (Main) RootViewSection: -awakeFromNib
  (Main) RootViewSection: -awakeFromNib
  (Main) RootViewSection: -awakeFromNib
  (Main) RootViewSection: -awakeFromNib
  (Main) RootViewSection: -awakeFromNib
  (Main) RootViewSection: -awakeFromNib
  (Main) RootViewSection: -awakeFromNib
    (Main) RootViewCell: -awakeFromNib
    (Main) RootViewCell: -awakeFromNib
    (Main) RootViewCell: -awakeFromNib
    (Main) RootViewCell: -awakeFromNib
  (Main) DemoViewController: -viewDidLoad
    (Main) DemoViewController: -setControlStates
    (Main) DemoViewController: -displayFeedbackView
      (Main) DemoViewController: -updateControlStatesGoingIn
  (Main) DemoViewController: -shouldAutorotateToInterfaceOrientation
(Main) DemoViewController: -displayFeedbackView
(Main) DemoViewController: -changeFromText1ToText2
(Main) DemoViewController: -doChangeFromText1ToText2
(Main) DemoViewController: -changeFromText2ToText3
(Main) DemoViewController: -doChangeFromText2ToText3
(Main) DemoViewController: -removeFeedbackView
(Main) DemoViewController: -doRemoveFeedbackView
(Main) DemoViewController: -updateControlStatesGoingOut
(Main) DemoViewController: -viewDidDisappear: animated = YES
  (Main) DemoViewController: -doRemoveFeedbackView
(Main) DemoViewController: -updateControlStatesGoingOut
(Main) DemoViewController: -dealloc


"Main" refers to the main thread. Background-invoked methods have their
thread names shown in place of Main. I find this to be much more useful
than NSLog(@"..."). If you like it, feel free to use it and/or modify it.
It takes a little getting used to, however, because you must be diligent
about typing RETURN rather than return. It's worth it, though.



Enjoy!
Wagner
