コミット: 44ade61ed2aede69aefea7a4206543c732ebc00f - CDEvents (git)

An Objective-C wrapper for Mac OS X’s FSEvents C API.

コミットメタ情報

• リビジョン: 44ade61ed2aede69aefea7a4206543c732ebc00f (tree)
• 日時: 2011-10-25 06:05:56
• 作者: Aron Cedercrantz <aron@cede...>
• コミッター: Aron Cedercrantz

ログメッセージ

Update the read me to reflect the new changes.

変更サマリ

• modified: README.mdown

差分

--- a/README.mdown
+++ b/README.mdown
@@ -1,55 +1,86 @@
 # CDEvents ![Project status](http://stillmaintained.com/rastersize/CDEvents.png) #
-***Note:*** Experimental ARC branch
+***Note:*** The `develop` branch **requires Mac OS X 10.6 or newer** as the framework relies on  [ARC](http://clang.llvm.org/docs/AutomaticReferenceCounting.html "Automatic Reference Counting Technical Specification") and [blocks](http://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/Blocks/Articles/00_Introduction.html "Blocks Programming Topics").
+
 
 ## What is this? ##
-It's an Objective-C wrapper for Mac OS X's [FSEvents C API](http://developer.apple.com/mac/library/documentation/Darwin/Reference/FSEvents_Ref/FSEvents_h/index.html). Inspired and based upon the ([MIT-licensed](http://www.opensource.org/licenses/mit-license.php)) open source project [SCEvents](http://stuconnolly.com/projects/code/) created by [Stuart Connolly](http://stuconnolly.com/).
+It's an Objective-C wrapper for Mac OS X's [FSEvents C API](http://developer.apple.com/mac/library/documentation/Darwin/Reference/FSEvents_Ref/FSEvents_h/index.html) with support for blocks. Furthermore, all the classes are immutable and it should be thread-safe.
+
 
 ## Requirements ##
-Requires Mac OS X 10.6 (Snow Leopard) and an Intel 64-bit CPU. The requirements stems from that automatic reference counting (ARC) is supported from 10.6 and up as long as the modern (i.e. 64-bit) Objective-C runtime is used. (ARC requires the non-fragile ABI.) Although the built product should work on 10.6 and up it must be built on a machine running 10.7 (Lion) using Xcode 4.2 and the 10.7 SDK as the 10.6 SDK does not include ARC. Supports both manual memory management and automatic reference counting.
+Requires Mac OS X 10.6 (Snow Leopard) and an Intel 64-bit CPU. The requirements stems from that automatic reference counting (ARC) is supported from 10.6 and up as long as the modern (i.e. 64-bit) Objective-C runtime is used since ARC requires the non-fragile ABI. Although the built product works on 10.6 and up it must be built on a machine running 10.7 (Lion) using Xcode 4.2 and the 10.7 SDK as the 10.6 SDK does not include ARC. The built product support both manual memory management and automatic reference counting.
+
+If you need to support older versions of OS X or garbage collection please see the branch `support/1.1`. All _1.1.x_ version will support garbage collection and OS X 10.5.
 
-If you need to support older versions of OS X please see the non-ARC branch, currently `develop` and `master`. Though which branch is the non-ARC will probably change in the future.
 
 ## Usage ##
+You can use either the block based version (recommended) or the delegate based. Using both systems at the same time is not supported.
+
+### Block based (recommended) ###
+1. Add CDEvents to your project,
+ * either by compiling the project and dragging the `CDEvents.framework` into your project or
+ * by dragging the entire CDEvents project into your project as a sub-project.
+2. Import the `CDEvents.h` header where you need it.
+3. Set up your `CDEvents` instance and give it a block to execute when a event occurs.
+
+Easy example code:
+
+    self.events = [[CDEvents alloc]] initWithURLs:<NSArray of URLs to watch>
+                                            block:^(CDEvents *watcher, CDEvent *event) {
+	                                            <Your code here>
+	                                        }];
+
+Or use all the glory-all-options initiator:
+
+    self.events = [[CDEvents alloc] initWithURLs:<NSArray of URLs to watch>
+                                           block:^(CDEvents *watcher, CDEvent *event) {
+                                               <Your code here>
+                                           }
+                                       onRunLoop:[NSRunLoop currentRunLoop]
+                            sinceEventIdentifier:kCDEventsSinceEventNow
+                            notificationLantency:CD_EVENTS_DEFAULT_NOTIFICATION_LATENCY
+                         ignoreEventsFromSubDirs:CD_EVENTS_DEFAULT_IGNORE_EVENT_FROM_SUB_DIRS
+                                     excludeURLs:<NSArray of URLs to exlude>
+                             streamCreationFlags:kCDEventsDefaultEventStreamFlags];
+
+See the test app (`TestApp`) for an example on how to use the framework.
+
+### Delegate based ###
+***This is the same behavior as pre ARC and blocks.***
 
 1. Add CDEvents to your project,
  * either by compiling the project and dragging the `CDEvents.framework` into your project or
  * by dragging the entire CDEvents project into your project as a sub-project.
 2. Import the `CDEvents.h` header where you need it.
 3. Import the `CDEventsDelegate.h` header where you need it (i.e. in the file which declares your delegate).
-4. See the test app (`TestApp`) for details on how to use the framework. Essentially it boils down to,
- 1. Implement the delegate method `-URLWatcher:eventOccurred:`.
- 2. Set up your `CDEvents` instance.
+4. Implement the delegate (`-URLWatcher:eventOccurred:`) and create your `CDEvents` instance.
+5. Zero out the delegate when you no longer need it.
 
-` `
+Example code:
 
     self.events = [[CDEvents alloc] initWithURLs:<NSArray of URLs to watch>
-										delegate:<Your delegate>
-									   onRunLoop:[NSRunLoop currentRunLoop]
-							sinceEventIdentifier:kCDEventsSinceEventNow
-							notificationLantency:CD_EVENTS_DEFAULT_NOTIFICATION_LATENCY
-						 ignoreEventsFromSubDirs:CD_EVENTS_DEFAULT_IGNORE_EVENT_FROM_SUB_DIRS
-									 excludeURLs:<NSArray of URLs to exlude>
-							 streamCreationFlags:kCDEventsDefaultEventStreamFlags];
-							
-**Important:** Since we have 10.6 set as the deployment target automatic zeroing of weak references is not available and as such you must set the `delegate` of  `CDEvents` to `nil` when you no longer want to receive events. That is, at least in your `-dealloc` method. This is also required when using 10.7 and up!
+                                        delegate:<Your delegate>
+                                       onRunLoop:[NSRunLoop currentRunLoop]
+                            sinceEventIdentifier:kCDEventsSinceEventNow
+                            notificationLantency:CD_EVENTS_DEFAULT_NOTIFICATION_LATENCY
+                         ignoreEventsFromSubDirs:CD_EVENTS_DEFAULT_IGNORE_EVENT_FROM_SUB_DIRS
+                                     excludeURLs:<NSArray of URLs to exlude>
+                             streamCreationFlags:kCDEventsDefaultEventStreamFlags];
 
-For more details please refer to the documentation in the header files and the section "API documentation" below.
+See the test app (`TestApp`) for an example on how to use the framework.
 
-## What differentiates CDEvents from SCEvents then? ##
-Not all that much but a few things differentiate the two. The (event data wrapper) class `CDEvent` is immutable in contrast to `SCEvent` which is mutable. The next difference, which were the initial reason why I decided to rewrite `SCEvents` is that the class `SCEvents`' is a singleton class, where's `CDEvents` is a "normal" class. I couldn't find a good reason as to why `SCEvents` had been designed that way and for my project a "normal" non-singleton class would be and is better.
+**Important:** Since Mac OS X 10.6 is set as the deployment target automatic zeroing of weak references is not available. Thus you must set the `delegate` of  `CDEvents` to `nil` when you no longer want to receive events. That is, at least in your `-dealloc` method. This is also required when using 10.7 and up! (`delegate` is an `unsafe_unretained` property.)
 
-Another difference between `CDEvents` and `SCEvents` is that `CDEvents` is available for both manual memory management and environments using garbage collection.
+For more details please refer to the documentation in the header files and the section "API documentation" below.
 
-So I've written some of the code from scratch and "borrowed" some from `SCEvents`.
 
 ## API documentation ##
 You can generate API documentation with the help of [Doxygen](http://www.stack.nl/~dimitri/doxygen/). In Doxygen open the file `api.doxygen`, click the `Run` tab and then the `Run doxygen` button. When it's done you should have a directory (ignored by git) in the root of the project named `api` with a sub-directory `html` in which you will find `index.html` double-click and enjoy.
 
-## Authors ##
+## Author ##
 
-* Aron Cedercrantz
+* [Aron Cedercrantz](http://github.com/rastersize) 
 
 ## License ##
 The code is released under the [MIT-license](http://www.opensource.org/licenses/mit-license.php).
 
-If you want, even though you really don't have to, I would love hearing what you use CDEvents for! Send me an email (first name @ last name dot se) or a [message via GitHub](http://github.com/inbox/new/rastersize).
+If you want, even though you really don't have to, I would love to hear what you use CDEvents for! Send me an email (first name (i.e. aron) @ last name (i.e. cedercrantz) dot se) or a [message via GitHub](http://github.com/inbox/new/rastersize).