diff options
Diffstat (limited to 'component')
| -rwxr-xr-x | component/Details.md | 35 | ||||
| -rwxr-xr-x | component/GettingStarted.md | 108 | ||||
| -rwxr-xr-x | component/License.md | 15 | ||||
| -rw-r--r-- | component/README | 7 | ||||
| -rw-r--r-- | component/build-package.sh | 19 | ||||
| -rw-r--r-- | component/rx_128x128.png | bin | 0 -> 12929 bytes |
6 files changed, 184 insertions, 0 deletions
diff --git a/component/Details.md b/component/Details.md new file mode 100755 index 0000000..4f34acd --- /dev/null +++ b/component/Details.md @@ -0,0 +1,35 @@ +The Reactive Extensions (Rx) is a library for composing asynchronous +and event-based programs using observable sequences and LINQ-style +query operators. Using Rx, developers represent asynchronous data +streams with Observables , query asynchronous data streams using LINQ +operators , and parameterize the concurrency in the asynchronous data +streams using Schedulers . Simply put, Rx = Observables + LINQ + +Schedulers. + +Whether you are authoring a traditional desktop or web-based +application, you have to deal with asynchronous and event-based +programming from time to time. Desktop applications have I/O +operations and computationally expensive tasks that might take a long +time to complete and potentially block other active +threads. Furthermore, handling exceptions, cancellation, and +synchronization is difficult and error-prone. + +Using Rx, you can represent multiple asynchronous data streams (that +come from diverse sources, e.g., stock quote, tweets, computer events, +web service requests, etc., and subscribe to the event stream using +the IObserver<T> interface. The IObservable<T> interface notifies the +subscribed IObserver<T> interface whenever an event occurs. + +Because observable sequences are data streams, you can query them +using standard LINQ query operators implemented by the Observable +extension methods. Thus you can filter, project, aggregate, compose +and perform time-based operations on multiple events easily by using +these standard LINQ operators. In addition, there are a number of +other reactive stream specific operators that allow powerful queries +to be written. Cancellation, exceptions, and synchronization are also +handled gracefully by using the extension methods provided by Rx. + +To learn more about the Reactive Extensions, see Microsoft's +RX open source site: + + http://rx.codeplex.com diff --git a/component/GettingStarted.md b/component/GettingStarted.md new file mode 100755 index 0000000..9cc1bee --- /dev/null +++ b/component/GettingStarted.md @@ -0,0 +1,108 @@ +This Reactive Extensions (Rx) component is to package Reactive Extensions (version 2.x) from Microsoft. + +Rx is published as an open source project and you can pick up sources from CodePlex (http://rx.codeplex.com). There is a dedicated web page section for Rx on MSDN website too: http://msdn.microsoft.com/en-us/data/gg577609.aspx + +This component contains Rx libraries that are suited for Xamarin.Android and Xamarin.iOS. + +We are not going to explain what is Rx and how the library works. To begin with basics of Rx, their website has lots of introductory materials on those websites. On this document, we explain how to use Rx in Xamarin products. + +# Adjusting Library References + +After adding this component to your project, you would notice that there are several dlls in this package. You would however most likely need to use the following four assemblies: + +* System.Reactive.Interfaces.dll +* System.Reactive.Core.dll +* System.Reactive.Linq.dll +* System.Reactive.PlatformServices.dll + +All other assemblies are optional and you would like to use them only in certain scenarios. On the other hand, those four assemblies are essential. So far let's remove other assemblies in this package. + + + +(Note that Rx version 2.x is very different from Rx v1.0 in terms of assemblies; Rx 1.0 consists only of System.Reactive.dll, which does not exist in Rx v2.x.) + +# Sample: Transforming touch events into another event + +Here I show an example use of Observable.FromEventPattern() and Observable.ToEventPattern() methods to turn View.Touch event into "notify only when three fingers are moving" event (here I named it as "TripleTouch"). + +Let's begin with a simple application project. After you created one, you will need some using statements for Rx: + + using System.Reactive; + using System.Reactive.Linq; + +The "TripleTouch" event is defined and implemented as follows: + + IEventPatternSource<View.TouchEventArgs> triple_touch_source; + + public event EventHandler<View.TouchEventArgs> TripleTouch { + add { triple_touch_source.OnNext += value; } + remove { triple_touch_source.OnNext -= value; } + } + +This event is populated when the View is set up. In the simple application sample, I wrote this in the Activity's OnCreate(): + + ... + // this "surface" is the target View here. + // It can be "this" when you implement a custom component. + var surface = FindViewById<View> (Resource.Id.theToucheable); + + triple_touch_source = Observable.FromEventPattern<View.TouchEventArgs> (surface, "Touch") + .Where (ev => ev.EventArgs.Event.Action == MotionEventActions.Move) + .Where (ev => ev.EventArgs.Event.PointerCount == 3) + .ToEventPattern (); + ... + +Then it could be consumed by the View users (in the sample, the first line of code is in OnCreate() method): + + ... + TripleTouch += (sender, ev) => this.RunOnUiThread (() => text.Text = GetEventDescription (ev.Event)); + ... + + static string GetEventDescription (MotionEvent e) + { + return string.Format ("({0}, {1})", e.RawX, e.RawY); + } + +In the sample app project, we defined very simple UI in Main.axml: + + <LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:orientation="vertical" + android:layout_width="fill_parent" + android:layout_height="fill_parent"> + <View + android:id="@+id/theToucheable" + android:layout_width="fill_parent" + android:layout_height="440.7dp" + android:layout_marginBottom="0.0dp" /> + <TextView + android:id="@+id/theText" + android:layout_width="fill_parent" + android:layout_height="wrap_content" + android:text="(touch corrdinates shown here)" /> + </LinearLayout> + +The sample is all done. Build and run the app on device. Then touch one finger. Nothing happens. Touch with one more finger. Still nothing happens. Add another finger. Then it starts showing the coordinate (of the first finger; this is just a sample so it doesn't give complicated action). + +What implements such behavior? Let's see the Observable part: + + triple_touch_source = Observable.FromEventPattern<View.TouchEventArgs> (surface, "Touch") + +This converts View.Touch event into an IObservable. + + .Where (ev => ev.EventArgs.Event.Action == MotionEventActions.Move) + +This filters out events that are not move events. + + .Where (ev => ev.EventArgs.Event.PointerCount == 3) + +This filters out events that don't detect three fingers. Now that we have only three-fingered events, we want to convert this observables into another event source: + + .ToEventPattern (); + +Once it's done, we use it to process the actual event. Note that since we are going to control UI, we need to invoke RunOnUiThread(): + + TripleTouch += (sender, ev) => this.RunOnUiThread (() => text.Text = GetEventDescription (ev.Event)); + +Actually, if you don't convert the filtered observables into another event, you might want to use SynchronizationContext instead (we didn't do that in this example because having event processing all within the UI thread is not good): + + (...) .SubscribeOn (Android.App.Application.SynchronizationContext) (...) diff --git a/component/License.md b/component/License.md new file mode 100755 index 0000000..5b47fbd --- /dev/null +++ b/component/License.md @@ -0,0 +1,15 @@ +Copyright (c) Microsoft Open Technologies, Inc. All rights reserved. +Microsoft Open Technologies would like to thank its contributors, a list +of whom are at http://rx.codeplex.com/wikipage?title=Contributors. + +Licensed under the Apache License, Version 2.0 (the "License"); you +may not use this file except in compliance with the License. You may +obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +implied. See the License for the specific language governing permissions +and limitations under the License.
\ No newline at end of file diff --git a/component/README b/component/README new file mode 100644 index 0000000..229e3ab --- /dev/null +++ b/component/README @@ -0,0 +1,7 @@ +run: + + ln -s path/to/mono/mcs mcs + ln -s path/to/mono/external external + ./build-package.sh + + diff --git a/component/build-package.sh b/component/build-package.sh new file mode 100644 index 0000000..6d6c389 --- /dev/null +++ b/component/build-package.sh @@ -0,0 +1,19 @@ +#!/bin/sh + +mono xpkg.exe create ReactiveExtensionsForXamarin-1.0.xam \ + --name="Reactive Extensions (Rx)" \ + --publisher="Xamarin, Inc." \ + --website="http://www.xamarin.com" \ + --summary="A library for composing asynchronous and event-based programs using observable sequences and LINQ-style query operators." \ + --license="external/rx/Rx/NET/Source/license.txt" \ + --library=android:external/rx/Rx/NET/Source/Rx_Xamarin/android/libs/System.Reactive.Interfaces.dll \ + --library=android:external/rx/Rx/NET/Source/Rx_Xamarin/android/libs/System.Reactive.Core.dll \ + --library=android:external/rx/Rx/NET/Source/Rx_Xamarin/android/libs/System.Reactive.Linq.dll \ + --library=android:external/rx/Rx/NET/Source/Rx_Xamarin/android/libs/System.Reactive.PlatformServices.dll \ + --library=android:external/rx/Rx/NET/Source/Rx_Xamarin/android/libs/System.Reactive.Experimental.dll \ + --library=android:external/rx/Rx/NET/Source/Rx_Xamarin/android/libs/System.Reactive.Debugger.dll \ + --library=android:external/rx/Rx/NET/Source/Rx_Xamarin/android/libs/System.Reactive.Providers.dll \ + --details=Details.md \ + --getting-started=Details.md \ + --icon=logo_128x128.png \ + --sample="GitHub API Client Sample. GitHub API client sample demonstrates use of Rx API with GitHub:external/rx/Rx/NET/Source/Rx_Xamarin/android/samples/GithubApiClientSample/GithubApiClientSample.sln" diff --git a/component/rx_128x128.png b/component/rx_128x128.png Binary files differnew file mode 100644 index 0000000..9da8fee --- /dev/null +++ b/component/rx_128x128.png |
