chrome/browser/ui/cocoa/browser_window_enter_fullscreen_transition.h

   1 // Copyright 2015 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CHROME_BROWSER_UI_COCOA_BROWSER_WINDOW_FULLSCREEN_TRANSITION_H_
   6 #define CHROME_BROWSER_UI_COCOA_BROWSER_WINDOW_FULLSCREEN_TRANSITION_H_
   7
   8 #import <Cocoa/Cocoa.h>
   9
  10 // This class is responsible for managing the custom transition of a
  11 // BrowserWindow from its normal state into an AppKit Fullscreen state.
  12 //
  13 // By default, when AppKit Fullscreens a window, it creates a new virtual
  14 // desktop and slides it in from the right of the screen. At the same time, the
  15 // old virtual desktop slides off to the left. This animation takes one second,
  16 // and the time is not customizable without elevated privileges or a
  17 // self-modifying binary
  18 // (https://code.google.com/p/chromium/issues/detail?id=414527). During that
  19 // second, no user interaction is possible.
  20 //
  21 // The default implementation of the AppKit transition smoothly animates a
  22 // window from its original size to the full size of the screen. At the
  23 // beginning of the animation, it takes a snapshot of the window's current
  24 // state. Then it resizes the window, calls drawRect: (theorized, not tested),
  25 // and takes a snapshot of the window's final state. The animation is a simple
  26 // crossfade between the two snapshots. This has a flaw. Frequently, the
  27 // renderer has not yet drawn content for the resized window by the time
  28 // drawRect: is called. As a result, the animation is effectively a no-op. When
  29 // the animation is finished, the new web content flashes in.
  30 //
  31 // The window's delegate can override two methods to customize the transition.
  32 //  -customWindowsToEnterFullScreenForWindow:
  33 //    The return of this method is an array of NSWindows. Each window that is
  34 //    returned will be added to the new virtual desktop after the animation is
  35 //    finished, but will not be a part of the animation itself.
  36 //  -window:startCustomAnimationToEnterFullScreenWithDuration:
  37 //    In this method, the window's delegate adds animations to the windows
  38 //    returned in the above method.
  39 //
  40 // The goal of this class is to mimic the default animation, but instead of
  41 // taking a snapshot of the final web content, it uses the live web content
  42 // during the animation.
  43 //
  44 // See https://code.google.com/p/chromium/issues/detail?id=414527#c22 and its
  45 // preceding comments for a more detailed description of the implementation,
  46 // and the reasoning behind the decisions made.
  47 //
  48 // Recommended usage:
  49 //  (Override method on NSWindow's delegate)
  50 //  - (NSArray*)customWindowsToEnterFullScreenForWindow:(NSWindow*)window {
  51 //    self.transition = [[[BrowserWindowEnterFullscreenTransition alloc]
  52 //        initWithWindow:window] autorelease];
  53 //    return [self.transition customWindowsToEnterFullScreen];
  54 //  }
  55 //
  56 //  (Override method on NSWindow's delegate)
  57 //  - (void)window:(NSWindow*)window
  58 //  startCustomAnimationToEnterFullScreenWithDuration:(NSTimeInterval)duration {
  59 //    [self.transition
  60 //        startCustomAnimationToEnterFullScreenWithDuration:duration];
  61 //  }
  62 //
  63 //  (Override method on NSWindow's delegate)
  64 //  - (void)windowDidEnterFullScreen:(NSNotification*)notification {
  65 //    self.transition = nil;
  66 //  }
  67 //
  68 //  (Override method on NSWindow)
  69 //  - (NSRect)constrainFrameRect:(NSRect)frame toScreen:(NSScreen*)screen {
  70 //    if (self.transition && ![self.transition shouldWindowBeConstrained])
  71 //      return frame;
  72 //    return [super constrainFrameRect:frame toScreen:screen];
  73 //  }
  74
  75 @interface BrowserWindowEnterFullscreenTransition : NSObject
  76
  77 // Designated initializer. |window| is the NSWindow that is going to be moved
  78 // into a fullscreen Space (virtual desktop), and resized to have the same size
  79 // as the screen. |window|'s root view must be layer backed.
  80 - (instancetype)initWithWindow:(NSWindow*)window;
  81
  82 // Returns the windows to be used in the custom transition.
  83 //   - Takes a snapshot of the current window.
  84 //   - Makes a new snapshot window which shows the snapshot in the same
  85 //   location as the current window.
  86 //   - Adds the style mask NSFullScreenWindowMask to the current window.
  87 //   - Makes the current window transparent, and resizes the current window to
  88 //   be the same size as the screen.
  89 - (NSArray*)customWindowsToEnterFullScreen;
  90
  91 // Begins the animations used for the custom fullscreen transition.
  92 //   - Animates the snapshot to the full size of the screen while fading it out.
  93 //   - Animates the current window from it's original location to its final
  94 //   location, while fading it in.
  95 // Note: The two animations are added to different layers in different windows.
  96 // There is no explicit logic to keep the two animations in sync. If this
  97 // proves to be a problem, the relevant layers should attempt to sync up their
  98 // time offsets with CACurrentMediaTime().
  99 - (void)startCustomAnimationToEnterFullScreenWithDuration:
 100     (NSTimeInterval)duration;
 101
 102 // When this method returns true, the NSWindow method
 103 // -constrainFrameRect:toScreen: must return the frame rect without
 104 // constraining it. The owner of the instance of this class is responsible for
 105 // hooking up this logic.
 106 - (BOOL)shouldWindowBeUnconstrained;
 107
 108 @end
 109
 110 #endif  // CHROME_BROWSER_UI_COCOA_BROWSER_WINDOW_FULLSCREEN_TRANSITION_H_