[css] Flesh out the docs. Nearly ready to go!

jprothwell · Oct 25, 2011 · 51ac230 · 51ac230
1 parent fc321de
commit 51ac230
Show file tree

Hide file tree

Showing 17 changed files with 556 additions and 138 deletions.
diff --git a/examples/css/CSSDemo.xcodeproj/project.pbxproj b/examples/css/CSSDemo.xcodeproj/project.pbxproj
@@ -44,6 +44,8 @@
 		66832E0A14435A07003E413C /* NIChameleonObserver.m in Sources */ = {isa = PBXBuildFile; fileRef = 66832E0914435A07003E413C /* NIChameleonObserver.m */; };
 		66832E1814442D17003E413C /* css in Resources */ = {isa = PBXBuildFile; fileRef = 66832E1714442D17003E413C /* css */; };
 		668ECDC3145325B700455266 /* NISimpleRequest.m in Sources */ = {isa = PBXBuildFile; fileRef = 668ECDC2145325B700455266 /* NISimpleRequest.m */; };
+		668ECDCB1456438C00455266 /* NIStylesheetCache.m in Sources */ = {isa = PBXBuildFile; fileRef = 668ECDCA1456438C00455266 /* NIStylesheetCache.m */; };
+		668ECDCE145656F400455266 /* UIButton+NIStyleable.m in Sources */ = {isa = PBXBuildFile; fileRef = 668ECDCD145656F400455266 /* UIButton+NIStyleable.m */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXFileReference section */
@@ -123,6 +125,10 @@
 		66832E1714442D17003E413C /* css */ = {isa = PBXFileReference; lastKnownFileType = folder; name = css; path = resources/css; sourceTree = "<group>"; };
 		668ECDC1145325B700455266 /* NISimpleRequest.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = NISimpleRequest.h; path = ../../src/core/src/NISimpleRequest.h; sourceTree = "<group>"; };
 		668ECDC2145325B700455266 /* NISimpleRequest.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = NISimpleRequest.m; path = ../../src/core/src/NISimpleRequest.m; sourceTree = "<group>"; };
+		668ECDC91456438C00455266 /* NIStylesheetCache.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = NIStylesheetCache.h; path = ../../src/css/src/NIStylesheetCache.h; sourceTree = "<group>"; };
+		668ECDCA1456438C00455266 /* NIStylesheetCache.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = NIStylesheetCache.m; path = ../../src/css/src/NIStylesheetCache.m; sourceTree = "<group>"; };
+		668ECDCC145656F300455266 /* UIButton+NIStyleable.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = "UIButton+NIStyleable.h"; path = "../../src/css/src/UIButton+NIStyleable.h"; sourceTree = "<group>"; };
+		668ECDCD145656F400455266 /* UIButton+NIStyleable.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = "UIButton+NIStyleable.m"; path = "../../src/css/src/UIButton+NIStyleable.m"; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -267,6 +273,10 @@
 				66832DEA14434FBE003E413C /* NIDOM.m */,
 				66832DEB14434FBE003E413C /* NIStylesheet.h */,
 				66832DEC14434FBE003E413C /* NIStylesheet.m */,
+				668ECDC91456438C00455266 /* NIStylesheetCache.h */,
+				668ECDCA1456438C00455266 /* NIStylesheetCache.m */,
+				668ECDCC145656F300455266 /* UIButton+NIStyleable.h */,
+				668ECDCD145656F400455266 /* UIButton+NIStyleable.m */,
 				66832DEF14434FBE003E413C /* UILabel+NIStyleable.h */,
 				66832DF014434FBE003E413C /* UILabel+NIStyleable.m */,
 				66832DF114434FBE003E413C /* UIView+NIStyleable.h */,
@@ -387,6 +397,8 @@
 				66832E0214434FBE003E413C /* CSSTokens.m in Sources */,
 				66832E0A14435A07003E413C /* NIChameleonObserver.m in Sources */,
 				668ECDC3145325B700455266 /* NISimpleRequest.m in Sources */,
+				668ECDCB1456438C00455266 /* NIStylesheetCache.m in Sources */,
+				668ECDCE145656F400455266 /* UIButton+NIStyleable.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

diff --git a/examples/css/CSSDemo/AppDelegate.h b/examples/css/CSSDemo/AppDelegate.h
@@ -20,10 +20,11 @@
   UIWindow* _window;
   UIViewController* _rootController;
   NIChameleonObserver* _chameleonObserver;
+  NIStylesheetCache* _stylesheetCache;
 }
 
 @property (nonatomic, readwrite, retain) UIWindow* window;
-@property (nonatomic, readonly, retain) NIChameleonObserver* chameleonObserver;
+@property (nonatomic, readonly, retain) NIStylesheetCache* stylesheetCache;
 
 @end
 
diff --git a/examples/css/CSSDemo/AppDelegate.m b/examples/css/CSSDemo/AppDelegate.m
@@ -26,14 +26,15 @@
 @implementation AppDelegate
 
 @synthesize window = _window;
-@synthesize chameleonObserver = _chameleonObserver;
+@synthesize stylesheetCache = _stylesheetCache;
 
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 - (void)dealloc {
   NI_RELEASE_SAFELY(_window);
   NI_RELEASE_SAFELY(_rootController);
   NI_RELEASE_SAFELY(_chameleonObserver);
+  NI_RELEASE_SAFELY(_stylesheetCache);
 
   [super dealloc];
 }
@@ -52,8 +53,11 @@ - (BOOL)              application:(UIApplication *)application
 
   NSString* pathPrefix = NIPathForBundleResource(nil, @"css");
   NSString* host = @"http://localhost:8888/";
-  _chameleonObserver = [[NIChameleonObserver alloc] initWithPathPrefix:pathPrefix
-                                                                  host:host];
+
+  _stylesheetCache = [[NIStylesheetCache alloc] initWithPathPrefix:pathPrefix];
+
+  _chameleonObserver = [[NIChameleonObserver alloc] initWithStylesheetCache:_stylesheetCache
+                                                                       host:host];
   [_chameleonObserver watchSkinChanges];
 
   RootViewController* mainController =

diff --git a/examples/css/CSSDemo/RootViewController.m b/examples/css/CSSDemo/RootViewController.m
@@ -39,13 +39,13 @@ - (void)dealloc {
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 - (id)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
   if ((self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil])) {
-    NIChameleonObserver* chameleonObserver =
-    [(AppDelegate *)[UIApplication sharedApplication].delegate chameleonObserver];
-    NIStylesheet* stylesheet = [chameleonObserver stylesheetForFilename:@"root/root.css"];
+    NIStylesheetCache* stylesheetCache =
+    [(AppDelegate *)[UIApplication sharedApplication].delegate stylesheetCache];
+    NIStylesheet* stylesheet = [stylesheetCache stylesheetWithPath:@"root/root.css"];
     _dom = [[NIDOM alloc] initWithStylesheet:stylesheet];
     [[NSNotificationCenter defaultCenter] addObserver:self
-                                             selector:@selector(chameleonSkinDidChange)
-                                                 name:NIChameleonSkinDidChangeNotification
+                                             selector:@selector(stylesheetDidChange)
+                                                 name:NIStylesheetDidChangeNotification
                                                object:stylesheet];
     self.title = @"Nimbus CSS Demo";
   }
@@ -125,7 +125,7 @@ - (void)viewDidUnload {
 
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
-- (void)chameleonSkinDidChange {
+- (void)stylesheetDidChange {
   [_dom refresh];
   [self layoutSubviews];
 }

diff --git a/examples/css/CSSDemo/resources/css/root/root.css b/examples/css/CSSDemo/resources/css/root/root.css
@@ -1,6 +1,6 @@
 
 .background {
-  background-color: white;
+  background-color: black;
 }
 
 .noticeBox {
@@ -15,5 +15,5 @@ UILabel {
   color: white;
   text-shadow: rgba(0, 0, 0, 0.5) 0 -1;
   text-align: center;
-  font-size: default;
+  font-size: 17;
 }
diff --git a/src/Nimbus.xcodeproj/project.pbxproj b/src/Nimbus.xcodeproj/project.pbxproj
@@ -128,6 +128,8 @@
 		66832E0714435071003E413C /* NIChameleonObserver.m in Sources */ = {isa = PBXBuildFile; fileRef = 66832E0514435071003E413C /* NIChameleonObserver.m */; };
 		668ECDBE1452B8A600455266 /* NISimpleRequest.h in Headers */ = {isa = PBXBuildFile; fileRef = 668ECDBC1452B8A600455266 /* NISimpleRequest.h */; };
 		668ECDBF1452B8A600455266 /* NISimpleRequest.m in Sources */ = {isa = PBXBuildFile; fileRef = 668ECDBD1452B8A600455266 /* NISimpleRequest.m */; };
+		668ECDC71455C17200455266 /* NIStylesheetCache.h in Headers */ = {isa = PBXBuildFile; fileRef = 668ECDC51455C17100455266 /* NIStylesheetCache.h */; };
+		668ECDC81455C17200455266 /* NIStylesheetCache.m in Sources */ = {isa = PBXBuildFile; fileRef = 668ECDC61455C17100455266 /* NIStylesheetCache.m */; };
 		66A03C0D13E6E85E00B514F3 /* Foundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 66A03C0C13E6E85E00B514F3 /* Foundation.framework */; };
 		66A03C1B13E6E85E00B514F3 /* SenTestingKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 66A03C1A13E6E85E00B514F3 /* SenTestingKit.framework */; };
 		66A03C1E13E6E85E00B514F3 /* Foundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 66A03C0C13E6E85E00B514F3 /* Foundation.framework */; };
@@ -531,6 +533,8 @@
 		66832E0514435071003E413C /* NIChameleonObserver.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = NIChameleonObserver.m; path = css/src/NIChameleonObserver.m; sourceTree = SOURCE_ROOT; };
 		668ECDBC1452B8A600455266 /* NISimpleRequest.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = NISimpleRequest.h; sourceTree = "<group>"; };
 		668ECDBD1452B8A600455266 /* NISimpleRequest.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = NISimpleRequest.m; sourceTree = "<group>"; };
+		668ECDC51455C17100455266 /* NIStylesheetCache.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; name = NIStylesheetCache.h; path = css/src/NIStylesheetCache.h; sourceTree = SOURCE_ROOT; };
+		668ECDC61455C17100455266 /* NIStylesheetCache.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; name = NIStylesheetCache.m; path = css/src/NIStylesheetCache.m; sourceTree = SOURCE_ROOT; };
 		669E98AD13E9EA1F00D99140 /* libz.dylib */ = {isa = PBXFileReference; lastKnownFileType = "compiled.mach-o.dylib"; name = libz.dylib; path = Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS5.0.sdk/usr/lib/libz.dylib; sourceTree = DEVELOPER_DIR; };
 		66A03C0913E6E85E00B514F3 /* libNimbusCore.a */ = {isa = PBXFileReference; explicitFileType = archive.ar; includeInIndex = 0; path = libNimbusCore.a; sourceTree = BUILT_PRODUCTS_DIR; };
 		66A03C0C13E6E85E00B514F3 /* Foundation.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = Foundation.framework; path = System/Library/Frameworks/Foundation.framework; sourceTree = SDKROOT; };
@@ -1084,18 +1088,21 @@
 			isa = PBXGroup;
 			children = (
 				66832CB7143D681B003E413C /* NimbusCSS.h */,
+				66832E0414435071003E413C /* NIChameleonObserver.h */,
+				66832E0514435071003E413C /* NIChameleonObserver.m */,
+				66832CC2143D7898003E413C /* NICSSParser.h */,
+				66832CC3143D7898003E413C /* NICSSParser.m */,
+				66832D05143E3A30003E413C /* NICSSRuleset.h */,
+				66832D06143E3A30003E413C /* NICSSRuleset.m */,
 				66832CFA143E2C0D003E413C /* NIDOM.h */,
 				66832CFB143E2C0D003E413C /* NIDOM.m */,
 				66832D09143E3B55003E413C /* NIStyleable.h */,
 				66832CF4143E0C35003E413C /* NIStylesheet.h */,
 				66832CF5143E0C35003E413C /* NIStylesheet.m */,
-				66832D05143E3A30003E413C /* NICSSRuleset.h */,
-				66832D06143E3A30003E413C /* NICSSRuleset.m */,
-				66832CC2143D7898003E413C /* NICSSParser.h */,
-				66832CC3143D7898003E413C /* NICSSParser.m */,
-				66832D0C143E3C1C003E413C /* Styleable Components */,
+				668ECDC51455C17100455266 /* NIStylesheetCache.h */,
+				668ECDC61455C17100455266 /* NIStylesheetCache.m */,
+				66832D0C143E3C1C003E413C /* Styleable UIKit Views */,
 				66832D0B143E3C0E003E413C /* Tokenizer */,
-				66832E0314435020003E413C /* Chameleon */,
 			);
 			name = src;
 			sourceTree = "<group>";
@@ -1149,28 +1156,19 @@
 			name = Tokenizer;
 			sourceTree = "<group>";
 		};
-		66832D0C143E3C1C003E413C /* Styleable Components */ = {
+		66832D0C143E3C1C003E413C /* Styleable UIKit Views */ = {
 			isa = PBXGroup;
 			children = (
+				66B108FE144C931F004576D1 /* UIButton+NIStyleable.h */,
+				66B108FF144C931F004576D1 /* UIButton+NIStyleable.m */,
+				66832DA014421B4A003E413C /* UINavigationBar+NIStyleable.h */,
+				66832DA114421B4A003E413C /* UINavigationBar+NIStyleable.m */,
 				66832D0D143E3C32003E413C /* UILabel+NIStyleable.h */,
 				66832D0E143E3C32003E413C /* UILabel+NIStyleable.m */,
 				66832D1114416368003E413C /* UIView+NIStyleable.h */,
 				66832D1214416368003E413C /* UIView+NIStyleable.m */,
-				66832DA014421B4A003E413C /* UINavigationBar+NIStyleable.h */,
-				66832DA114421B4A003E413C /* UINavigationBar+NIStyleable.m */,
-				66B108FE144C931F004576D1 /* UIButton+NIStyleable.h */,
-				66B108FF144C931F004576D1 /* UIButton+NIStyleable.m */,
-			);
-			name = "Styleable Components";
-			sourceTree = "<group>";
-		};
-		66832E0314435020003E413C /* Chameleon */ = {
-			isa = PBXGroup;
-			children = (
-				66832E0414435071003E413C /* NIChameleonObserver.h */,
-				66832E0514435071003E413C /* NIChameleonObserver.m */,
 			);
-			name = Chameleon;
+			name = "Styleable UIKit Views";
 			sourceTree = "<group>";
 		};
 		66A03BFC13E6E84800B514F3 = {
@@ -1749,6 +1747,7 @@
 				66832DA214421B4A003E413C /* UINavigationBar+NIStyleable.h in Headers */,
 				66832E0614435071003E413C /* NIChameleonObserver.h in Headers */,
 				66B10900144C931F004576D1 /* UIButton+NIStyleable.h in Headers */,
+				668ECDC71455C17200455266 /* NIStylesheetCache.h in Headers */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -2717,6 +2716,7 @@
 				66832DA314421B4A003E413C /* UINavigationBar+NIStyleable.m in Sources */,
 				66832E0714435071003E413C /* NIChameleonObserver.m in Sources */,
 				66B10901144C931F004576D1 /* UIButton+NIStyleable.m in Sources */,
+				668ECDC81455C17200455266 /* NIStylesheetCache.m in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};

diff --git a/src/css/src/NICSSParser.h b/src/css/src/NICSSParser.h
@@ -24,6 +24,8 @@ extern NSString* const kDependenciesSelectorKey;
 /**
  * An Objective-C wrapper for the flex CSS parser.
  *
+ *      @ingroup CSS-Stylesheets
+ *
  * Generates a dictionary of raw CSS rules from a given CSS file.
  *
  * It is recommended that you do NOT use this object directly. Use NIStylesheet instead.

diff --git a/src/css/src/NICSSRuleset.h b/src/css/src/NICSSRuleset.h
@@ -19,6 +19,8 @@
 /**
  * A simple translator from raw CSS rulesets to Objective-C values.
  *
+ *      @ingroup CSS-Stylesheets
+ *
  * Objective-C values are created on-demand and cached. These ruleset objects are cached
  * by NIStylesheet for a given CSS scope. When a memory warning is received, all ruleset objects
  * are removed from every stylesheet.

diff --git a/src/css/src/NIChameleonObserver.h b/src/css/src/NIChameleonObserver.h
@@ -19,24 +19,54 @@
 #import "NISimpleRequest.h"
 #import "NICSSParser.h"
 
-extern NSString* const NIChameleonSkinDidChangeNotification;
-
 @class NIStylesheet;
+@class NIStylesheetCache;
 
+/**
+ * An observer for the Chameleon server.
+ *
+ *      @ingroup CSS-Stylesheets
+ *
+ * This observer connects to a Chameleon server and waits for changes in stylesheets. Once
+ * a stylesheet change has been detected, the new stylesheet is retrieved from the server
+ * and a notification is fired via NIStylesheetDidChangeNotification after the stylesheet
+ * has been reloaded.
+ */
 @interface NIChameleonObserver : NSObject <NISimpleRequestDelegate, NICSSParserDelegate> {
 @private
-  NSMutableDictionary* _stylesheets;
+  NIStylesheetCache* _stylesheetCache;
+  NSMutableArray* _stylesheetPaths;
   NSMutableArray* _activeRequests;
-  NSString* _pathPrefix;
   NSString* _host;
   NSInteger _retryCount;
 }
 
 // Designated initializer.
-- (id)initWithPathPrefix:(NSString *)pathPrefix host:(NSString *)host;
+- (id)initWithStylesheetCache:(NIStylesheetCache *)stylesheetCache host:(NSString *)host;
 
-- (NIStylesheet *)stylesheetForFilename:(NSString *)filename;
+- (NIStylesheet *)stylesheetForPath:(NSString *)path;
 
 - (void)watchSkinChanges;
 
 @end
+
+/**
+ * Initializes a newly allocated Chameleon observer with a given stylesheet cache and host.
+ *
+ *      @fn NIChameleonObserver::initWithStylesheetCache:host:
+ */
+
+/**
+ * Returns a loaded stylesheet from the given path.
+ *
+ *      @fn NIChameleonObserver::stylesheetForPath:
+ */
+
+/**
+ * Begins listening to the Chameleon server for changes.
+ *
+ * When changes are detected the Chameleon observer downloads the new CSS files, reloads them,
+ * and then fires the appropriate notifications.
+ *
+ *      @fn NIChameleonObserver::watchSkinChanges
+ */