title: Are layer-hosting NSViews allowed to have subviews?
body: <p>Layer-hosting NSViews (so NSViews that you supply a CALayer instance for and set it with <code>setLayer:</code>) can obviously contain subviews. Why obviously? Because in Apple's own <a href="https://developer.apple.com/library/mac/#samplecode/CocoaSlides/Introduction/Intro.html#//apple_ref/doc/uid/DTS10004072" rel="noreferrer">Cocoa Slides sample code project</a>, you can check a checkbox that switches the <code>AssetCollectionView</code> from being layer-backed to being layer-hosting:</p>
  
  <pre><code>- (void)setUsesQuartzCompositionBackground:(BOOL)flag {
      if (usesQuartzCompositionBackground != flag) {
          usesQuartzCompositionBackground = flag;
  
          /* We can display a Quartz Composition in a layer-backed view tree by 
             substituting our own QCCompositionLayer in place of the default automanaged 
             layer that AppKit would otherwise create for the view.  Eventually, hosting of 
             QCViews in a layer-backed view subtree may be made more automatic, rendering 
             this unnecessary.  To minimize visual glitches during the transition, 
             temporarily suspend window updates during the switch, and toggle layer-backed 
             view rendering temporarily off and back on again while we prepare and set the 
             layer.
          */
          [[self window] disableScreenUpdatesUntilFlush];
          [self setWantsLayer:NO];
          if (usesQuartzCompositionBackground) {
              QCCompositionLayer *qcLayer = [QCCompositionLayer compositionLayerWithFile:[[NSBundle mainBundle] pathForResource:@"Cells" ofType:@"qtz"]];
              [self setLayer:qcLayer];
          } else {
              [self setLayer:nil]; // Discard the QCCompositionLayer we were using, and let AppKit automatically create self's backing layer instead.
          }
          [self setWantsLayer:YES];
      }
  }
  </code></pre>
  
  <p>In the same <code>AssetCollectionView</code> class, subviews are added for each image that should be displayed:</p>
  
  <pre><code>- (AssetCollectionViewNode *)insertNodeForAssetAtIndex:(NSUInteger)index {
      Asset *asset = [[[self assetCollection] assets] objectAtIndex:index];
      AssetCollectionViewNode *node = [[AssetCollectionViewNode alloc] init];
      [node setAsset:asset];
      [[self animator] addSubview:[node rootView]];
      [nodes addObject:node];
  
      return [node autorelease];
  }
  </code></pre>
  
  <p>When I build and run the app and play around with it, everything seems to be fine.</p>
  
  <p>However, in <a href="https://developer.apple.com/library/mac/documentation/Cocoa/Reference/ApplicationKit/Classes/NSView_Class/Reference/NSView.html#//apple_ref/occ/instm/NSView/setWantsLayer:" rel="noreferrer">Apple's NSView Class Reference for the <code>setWantsLayer:</code> method</a> it reads:</p>
  
  <blockquote>
    <p>When using a layer-hosting view you should not rely on the view for
    drawing, nor should you add subviews to the layer-hosting view.</p>
  </blockquote>
  
  <p>What is true? Is the sample code incorrect and it's just a coincidence that it works? Or is the documentation false (which I doubt)? Or is it OK because the subviews are added through the animator proxy?</p>