Closes #11

Lawo · Oct 28, 2015 · cc3eaca · cc3eaca
1 parent 72875dc
commit cc3eaca
Show file tree

Hide file tree

Showing 7 changed files with 80 additions and 452 deletions.
diff --git a/Doc/DoxygenLayout.txt b/Doc/DoxygenLayout.txt
@@ -1,5 +1,3 @@
   <tab type="usergroup" title="Ember+ Sharp">
-    <tab type="usergroup" title="Tutorials">
-      <tab type="user" url="http://lawo.github.io/ember-plus-sharp/html/915a270d-2a20-432f-9531-ce6aa3260566.htm" title="Ember+ Sharp Library"/>
-    </tab>
+    <tab type="user" url="http://lawo.github.io/ember-plus-sharp/html/915a270d-2a20-432f-9531-ce6aa3260566.htm" title="Ember+ Sharp Library"/>
   </tab>
diff --git a/Doc/Tutorials/MVVM/MVVM.md b/Doc/Tutorials/MVVM/MVVM.md
diff --git a/...erPlusDoc/Content/Library/ComponentModelNamespace/Example/View/BindingToViewModelData.aml b/...erPlusDoc/Content/Library/ComponentModelNamespace/Example/View/BindingToViewModelData.aml
@@ -23,21 +23,82 @@
     <section address="PrimitiveProperties">
       <title>Primitive Properties</title>
       <content>
+        <code source="..\Lawo.GlowAnalyzerProxy.Main\MainWindow.xaml" region="PrimitivePropertyBinding" language="xaml"/>
         <para>
+          The <codeInline>Text="{Binding ProviderHostName}"</codeInline> part in the code above establishes a two-way
+          binding between <codeInline>MainWindowViewModel.ProviderHostName</codeInline> and
+          <codeEntityReference linkText="TextBox.Text">P:System.Windows.Controls.TextBox.Text</codeEntityReference>. This
+          means that the following operations take place automatically:
         </para>
+        <list class="bullet">
+          <listItem>
+            <para>
+              Initialization: When the
+              <codeEntityReference linkText="DataContext">P:System.Windows.FrameworkElement.DataContext</codeEntityReference>
+              is set, <codeInline>MainWindow</codeInline> automatically calls the
+              <codeInline>MainWindowViewModel.ProviderHostName</codeInline> getter and assigns the value to
+              <codeEntityReference linkText="TextBox.Text">P:System.Windows.Controls.TextBox.Text</codeEntityReference>.
+              <codeInline>MainWindow</codeInline> also automatically subscribes to
+              <codeEntityReference qualifyHint="true">E:Lawo.ComponentModel.NotifyPropertyChanged.PropertyChanged</codeEntityReference>.
+            </para>
+          </listItem>
+          <listItem>
+            <para>
+              Change Propagation from <application>View</application> to <application>ViewModel</application>: When the
+              user changes the text in the
+              <codeEntityReference>T:System.Windows.Controls.TextBox</codeEntityReference>,
+              <codeInline>MainWindow</codeInline> automatically sets the new value on
+              <codeInline>MainWindowViewModel.ProviderHostName</codeInline>.
+            </para>
+          </listItem>
+          <listItem>
+            <para>
+              Change Propagation from <application>ViewModel</application> to <application>View</application>: When the
+              business logic changes <codeInline>MainWindowViewModel.ProviderHostName</codeInline>, the
+              <codeEntityReference qualifyHint="true">E:Lawo.ComponentModel.NotifyPropertyChanged.PropertyChanged</codeEntityReference>
+              event is raised. Since <codeInline>MainWindow</codeInline> is subscribed to the event it then
+              automatically calls the <codeInline>MainWindowViewModel.ProviderHostName</codeInline> property getter and
+              sets the value on
+              <codeEntityReference linkText="TextBox.Text">P:System.Windows.Controls.TextBox.Text</codeEntityReference>.
+            </para>
+          </listItem>
+        </list>
       </content>
     </section>
     <section address="CompositeProperties">
       <title>Composite Properties</title>
       <content>
+        <code source="..\Lawo.GlowAnalyzerProxy.Main\MainWindow.xaml" region="CompositePropertyBinding" language="xaml"/>
         <para>
+          The <codeInline>DataContext="{Binding ConsumerConnection}"</codeInline> and
+          <codeInline>DataContext="{Binding ProviderConnection}"</codeInline> parts in the code above bind the
+          <codeInline>ConnectionViewModel</codeInline> values returned by the properties to the
+          <codeEntityReference linkText="DataContext">P:System.Windows.FrameworkElement.DataContext</codeEntityReference>
+          of the two <codeInline>ConnectionStatusUserControl</codeInline> instances. This allows
+          <codeInline>ConnectionStatusUserControl</codeInline> to bind directly to
+          <codeInline>ConnectionViewModel</codeInline> properties:
+        </para>
+        <code source="..\Lawo.GlowAnalyzerProxy.Main\ConnectionStatusUserControl.xaml" region="PrimitivePropertyBinding" language="xaml"/>
+        <para>
+          Note how we have used <codeInline>ConnectionStatusUserControl</codeInline> in
+          <codeInline>MainWindow</codeInline> and <codeInline>ConnectionViewModel</codeInline> in
+          <codeInline>MainWindowViewModel</codeInline> to avoid duplicating identical parts.
         </para>
       </content>
     </section>
     <section address="CollectionProperties">
       <title>Collection Properties</title>
       <content>
+        <code source="..\Lawo.GlowAnalyzerProxy.Main\MainWindow.xaml" region="CollectionPropertyBinding" language="xaml"/>
         <para>
+          The <codeInline>ItemsSource="{Binding Events}"</codeInline> part ensures that the elements in the
+          <codeEntityReference>T:System.Collections.ObjectModel.ReadOnlyObservableCollection`1</codeEntityReference>
+          are shown in the <codeEntityReference>T:System.Windows.Controls.DataGrid</codeEntityReference>. Since the
+          collection implements
+          <codeEntityReference>T:System.Collections.Specialized.INotifyCollectionChanged</codeEntityReference>,
+          any changes to the collection are immediately reflected in the GUI. The
+          <codeInline>SelectedItem="{Binding SelectedEvent}"</codeInline> part makes the currently selected
+          <codeInline>Event</codeInline> available in the <codeInline>MainWindowViewModel</codeInline>.
         </para>
       </content>
     </section>

diff --git a/...rPlusDoc/Content/Library/ComponentModelNamespace/Example/View/CallingViewModelMethods.aml b/...rPlusDoc/Content/Library/ComponentModelNamespace/Example/View/CallingViewModelMethods.aml
@@ -6,7 +6,11 @@
   <developerConceptualDocument
     xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
     <introduction>
+      <code source="..\Lawo.GlowAnalyzerProxy.Main\MainWindow.xaml" region="CallViewModelMethod" language="xaml"/>
       <para>
+        The above is <application>WPF</application>-specific, similar mechanisms exist for <application>Windows Store
+        Apps</application>, see
+        <codeEntityReference>T:Microsoft.Xaml.Interactions.Core.CallMethodAction</codeEntityReference>
       </para>
     </introduction>
     <relatedTopics/>

diff --git a/...rPlusDoc/Content/Library/ComponentModelNamespace/Example/ViewModel/BindingToModelData.aml b/...rPlusDoc/Content/Library/ComponentModelNamespace/Example/ViewModel/BindingToModelData.aml
@@ -16,7 +16,7 @@
         <codeEntityReference>N:Lawo.Reflection</codeEntityReference> namespaces offer a few tools to make this
         process much easier.
       </para>
-      <para>Bindings are typically created in the ViewModel constructor.</para>
+      <para>Bindings are typically created in the <application>ViewModel</application> constructor.</para>
       <alert class="note">
         <para>
           All the binding methods discussed below return an object that represents the newly created binding. The
@@ -120,7 +120,9 @@
           <para>
             This problem can easily be avoided by only ever calling
             <codeEntityReference qualifyHint="true" autoUpgrade="true">M:Lawo.ComponentModel.CalculatedProperty.Create``1(Lawo.Reflection.IProperty{System.ComponentModel.INotifyPropertyChanged,``0},Lawo.Reflection.IProperty{Lawo.ComponentModel.NotifyPropertyChanged,``0})</codeEntityReference>
-            inside a constructor and immediately assigning the resulting instance to a <codeInline>private readonly</codeInline> field.
+            inside a constructor and immediately assigning the resulting instance to a <codeInline>private
+            readonly</codeInline> field. In scenarios where this is not possible,
+            <codeEntityReference>T:Lawo.ComponentModel.MultiBinding</codeEntityReference> should be used instead.
           </para>
         </alert>
       </content>

diff --git a/Lawo.GlowAnalyzerProxy.Main/ConnectionStatusUserControl.xaml b/Lawo.GlowAnalyzerProxy.Main/ConnectionStatusUserControl.xaml
@@ -23,14 +23,14 @@
                     <ColumnDefinition Width="{StaticResource GridMargin}"/>
                     <ColumnDefinition/>
                 </Grid.ColumnDefinitions>
-                <!-- [PrimitivePropertyBinding] -->
+                <!-- #region PrimitivePropertyBinding -->
                 <Label Grid.Row="0" Grid.Column="0">Connection Count:</Label>
                 <TextBox Grid.Row="0" Grid.Column="2" IsReadOnly="True" Text="{Binding ConnectionCount, Mode=OneWay}"/>
                 <Label Grid.Row="2" Grid.Column="0">Bytes Received:</Label>
                 <TextBox Grid.Row="2" Grid.Column="2" IsReadOnly="True" Text="{Binding BytesReceived, Mode=OneWay}"/>
                 <Label Grid.Row="4" Grid.Column="0">Seconds Since Last Byte:</Label>
                 <TextBox Grid.Row="4" Grid.Column="2" IsReadOnly="True" Text="{Binding SecondsSinceLastReceived, Mode=OneWay}"/>
-                <!-- [PrimitivePropertyBinding] -->
+                <!-- #endregion -->
             </Grid>
         </GroupBox>
     </Grid>

diff --git a/Lawo.GlowAnalyzerProxy.Main/MainWindow.xaml b/Lawo.GlowAnalyzerProxy.Main/MainWindow.xaml
@@ -81,12 +81,12 @@
                     ToolTip="The port on which this proxy listens for a connection request from the Ember+ consumer."
                     ToolTipService.ShowOnDisabled="True" Text="{Binding ListeningPort, ValidatesOnDataErrors=True}"/>
                 <Label Grid.Row="2" Grid.Column="0">Provider Host Name:</Label>
-                <!-- [PrimitivePropertyBinding] -->
+                <!-- #region PrimitivePropertyBinding -->
                 <TextBox
                     Grid.Row="2" Grid.Column="2" Grid.ColumnSpan="2" IsEnabled="{Binding CanEditSettings}"
                     ToolTip="The host name or IP address of the Ember+ provider."
                     ToolTipService.ShowOnDisabled="True" Text="{Binding ProviderHostName}"/>
-                <!-- [PrimitivePropertyBinding] -->
+                <!-- #endregion -->
                 <Label Grid.Row="4" Grid.Column="0">Provider Port:</Label>
                 <TextBox
                     Grid.Row="4" Grid.Column="2" Grid.ColumnSpan="2" IsEnabled="{Binding CanEditSettings}"
@@ -112,7 +112,7 @@
                 <ColumnDefinition Width="{StaticResource GridMargin}"/>
                 <ColumnDefinition/>
             </Grid.ColumnDefinitions>
-            <!-- [CallViewModelMethod] -->
+            <!-- #region CallViewModelMethod -->
             <Button
                 Grid.Column="0" IsEnabled="{Binding CanStart}" ToolTip="Start the proxy."
                 ToolTipService.ShowOnDisabled="True" Content="Start">
@@ -122,7 +122,7 @@
                     </i:EventTrigger>
                 </i:Interaction.Triggers>
             </Button>
-            <!-- [CallViewModelMethod] -->
+            <!-- #endregion -->
             <Button
                 Grid.Column="2" IsEnabled="{Binding CanStop}" ToolTip="Stop the proxy."
                 ToolTipService.ShowOnDisabled="True" Content="Stop">
@@ -134,14 +134,14 @@
             </Button>
         </Grid>
         <GroupBox Grid.Row="4" Header="Events">
-            <!-- [CollectionPropertyBinding] -->
+            <!-- #region CollectionPropertyBinding -->
             <DataGrid
                 Margin="{StaticResource Margin}" SelectionMode="Single" CanUserResizeRows="False"
                 CanUserResizeColumns="False" CanUserReorderColumns="False" CanUserSortColumns="False"
                 ToolTip="Lists events in chronological order." ItemsSource="{Binding Events}"
                 SelectedItem="{Binding SelectedEvent}" AutoGeneratingColumn="OnDataGrid_AutoGeneratingColumn"
                 x:Name="EventsDataGrid"/>
-            <!-- [CollectionPropertyBinding] -->
+            <!-- #endregion -->
         </GroupBox>
         <Grid Grid.Row="0" Grid.RowSpan="5" Grid.Column="2" >
             <Grid.RowDefinitions>
@@ -154,14 +154,14 @@
                 <ColumnDefinition Width="{StaticResource GridMargin}"/>
                 <ColumnDefinition/> 
             </Grid.ColumnDefinitions>
-            <!-- [CompositePropertyBinding] -->
+            <!-- #region CompositePropertyBinding -->
             <local:ConnectionStatusUserControl
                 Grid.Row="0" Grid.Column="0" DataContext="{Binding ConsumerConnection}"
                 Header="Consumer to Proxy Connection Status"/>
             <local:ConnectionStatusUserControl
                 Grid.Row="0" Grid.Column="2" DataContext="{Binding ProviderConnection}"
                 Header="Proxy to Provider Connection Status"/>
-            <!-- [CompositePropertyBinding] -->
+            <!-- #endregion -->
             <GroupBox Grid.Row="2" Grid.Column="0" Grid.ColumnSpan="3" Header="Event Detail">
                 <Grid Margin="{StaticResource Margin}">
                     <Grid.RowDefinitions>