<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
<title>Property Events</title>
</head>
<body>
<h2>Introduction</h2>
<p>XAML is going to introduce something called "property triggers" to components
as part of their visual style definition. You can read more about XAML's
property triggers on Joe Marini's blog
<a href="http://www.joemarini.com/tutorials/tutorialpages/xamlpropertytriggers.php">
here</a>. What I want to introduce, instead of the XAML-like property
trigger implementation, is a similar, but in my opinion more powerful, concept
that I have called "property events". Property events have the following
features:</p>
<ul>
<li>Wired up to an object's events</li>
<li>Therefore, triggered not just by changes to a property but any event
source</li>
<li>Has a clearly stated collection of setters that affect the state of
other objects (including the object that fired the event)</li>
<li>Has a clearly stated collection of conditions that qualify the execution
of the setters</li>
<li>The setters are easily extended with the IAction interface</li>
<li>The conditions are easily extended with the ICondition interface</li>
<li>Property events can be applied to any object, not just visual ones</li>
</ul>
<p>It is pointless to compare and contrast my implementation of property events
with XAML's implementation of property triggers, if for no other reason than, as
Joe has stated in
<a href="http://www.mezzoblue.com/archives/2005/04/14/avalonxaml_f/comments">
this blog</a> that XAML is pre-alpha software and that "Things are going to
change dramatically between now and shipping." (Please be aware, for those
in the future, that this article was written on 5/1/05.) So, rather than a
pointless comparison of which is better, let's simply consider that this article
presents a solution available to .NET 1.1 and 2.0 programmers and offers some advice on
the declarative programming best practices. This isn't XAML property
triggers, which is why I've called it "property events".</p>
<h3>Declarative Programming</h3>
<p>The imperative code is written in such a way as to support the declarative
expression of the property events. For the purposes of this article, I'm
illustrating the concept of property events using <a href="http://www.codeproject.com/dotnet/MycroXaml.asp">MycroXaml</a>, a simple xml object
graph instantiator that I wrote a while back. It doesn't have all the
features of MyXaml, but it is sufficient to demonstrate the concept. The
imperative code can be instantiated with the full
<a href="http://www.myxaml.com">MyXaml</a> parser without
modification.</p>
<p>One thing to consider when balancing the objectives of imperative and
declarative programming is that there are many different architectures that
could be implemented to express a certain concept. Because the
declarative code instantiates an object graph that represents the imperative
architecture, some thought needs to go into the design of the imperative
architecture.</p>
<h3>Best Practices</h3>
<p>For example, we could create an architecture in which property events can be
applied to classes derived from various .NET controls and implement an object
graph similar to this:</p>
<p>
<img border="0" src="PropertyEvents/propertyEvents.png" width="361" height="193"></p>
<p>The problem with this architecture is that the xml to instantiate this object
graph would look a bit like this:</p>
<pre><MyButton Location="10, 10" Size="80, 25" Text="Click Me!">
<PropertyEvents>
<PropertyEvent Event="MouseOver">
<Conditions>
<Condition Property="IsMouseOver" Value="True"/>
</Conditions>
<Setters>
<Set Property="ForegroundColor" Value="Red"/>
</Setters>
</PropertyEvent>
</PropertyEvents>
</MyButton></pre>
<p>The problem with this declarative markup is that it entangles:</p>
<ul>
<li>The visual presentation of the control</li>
<li>The conditions (aka application specific rules) that qualify the event</li>
<li>The actions (aka application specific actions) that are performed when
the conditions are qualfied</li>
</ul>
<p>In my experience with declarative programming, it can easily suffer the same
problems of imperative programming, making it difficult to change and extend the
application's implementation. Entangling presentation, rule, and actions
(or state) layers of the application is usually not a good idea, whether
implementing imperative code or instantiating an object graph declaratively.</p>
<p>In this article you will see what I consider to be the best practices in
declarative programming--defining presentation, rules, actions, and other
elements such as containers as separate object graphs and gluing them together,
so to speak, with "controllers" that manage the interaction between the
elements, such as is done here for property events and can be done for things
like data binding. The result is a clean, readable xml document in which
each object graph expresses only the concepts within its own domain. In
the past, the object graphs I've put together, while "cool" and completely
viable given the classes and properties that are being instantiated, are an
entangled mess of cross-domain concepts. Interestingly, this also gives us
a clue as to why the applications that we build slowly become
calcified--difficult to change and extend.</p>
<h2>Architecture</h2>
<p>Rather than use the architecture illustrated above, I prefer a much looser
coupling of the different "layers", as illustrated here:</p>
<p><img border="0" src="PropertyEvents/decoupled.png" width="551" height="457"></p>
<p>I'm sure you're saying, geez, this looks a lot more complicated! Not
really. The benefit to this approach is that I can vary the implementation of the
different layers without adversely affecting other layers. Since
interfaces are used for managing the concrete classes, I achieve further
decoupling of the actual condition and action interfaces. The tradeoff to
reduce the dependencies is that this architecture requires individual
classes to manage the different collections plus the addition of a "controller"
to glue the decoupled classes together. Also note that the controller has
to reference each of the containers. Since these are simple containers, I
didn't feel it was necessary to implement interfaces for them. However,
the instances that the containers manage all have interfaces so that it's easy
to extend the behavior of the property trigger system with your own classes.</p>
<h3>OnEvent</h3>
<p>Most of the real work is done in the interaction between the OnEvent,
Controller, and MxController classes. The class that sources the event
(here drawn as ".NET Control", but it can be any event source) references the
event object--it has to, in order to use reflection to wire up the event to its
own handler. OnEvent also has its own multicast event. Each
Controller instance that is interested in the event handled by OnEvent adds an
event handler to this multicast event.</p>
<h3>MxController</h3>
<p>The MxController instance is responsible for invoking all the controllers
interested in the event. When the source object event fires, it gets
handled by a method in OnEvent. This method, in turn, calls back to the
MxController (via the IMxController interface). The MxController then
requests the invocation list--all the Controller's that have subscribed to this
event. The MxController provided in the download has the behavior that it
stops processing the invocation list as soon as a controller's rules are
qualified. The only exception is that it also processes controllers that
do not have any condition set, meaning that these controllers always process
their associated actions. However, since the OnEvent works through the
IMxController interface, you can use different master controllers for different
behaviors. The only restriction (tested for and will throw an exception if
violated) is that an OnEvent, which can be subscribed to by more than one
controller, must be managed by the same MxController. You cannot have the
same OnEvent being handled by two different master controller "domains", as it
were.</p>
<h3>Controller</h3>
<p>The controller subscribes to the events that it's interested in, using the
event supplied by the OnEvent class (not the source object's event handler).
When the controller's event handler is fired (by a DynamicInvoke call from the
MxController) the controller tests to see if the condition set is qualified, and
if so, it tells the action set to perform its actions. The controller also
returns a status, as part of the ControllerEventArgs, indicating whether or not
it's particular condition set was qualified.</p>
<h2>Demonstrations</h2>
<p>There are three demonstrations:</p>
<ul>
<li>A simple mouse-over event capture demonstrating affecting the property
of the object sourcing the event</li>
<li>A simple checkbox state event capture demonstrating affecting the
property of another object</li>
<li>A more complex traffic light example, in which a checkbox and a timer
source the events</li>
</ul>
<p>In each example, you will see markup defines five specific application
layers:</p>
<ul>
<li>Presentation Layer</li>
<li>Event Definitions</li>
<li>Rule Definitions</li>
<li>Action Definitions</li>
<li>Control Logic</li>
</ul>
<p>You should find yourself quickly becoming comfortable with the syntax in each
of the layers. If you are unfamiliar with how xml is used to declaratively
instantiate an object graph and the various syntactical elements, such as xml
namespaces and prefixes, I suggest you first read my article on
<a href="http://www.codeproject.com/dotnet/MycroXaml.asp">MycroXaml</a>.</p>
<h3>Button Mouse Over</h3>
<p>Let's start with a simple demonstration. In this example, we're going
to change the color of the button text to red when the mouse pointer is over the
button but it is does not have focus, and green when the mouse is over the
button and it does have focus. Finally, when the mouse leaves the control,
we'll explicitly set the text color to black.</p>
<h4>Presentation Layer</h4>
<p>Besides the usual riffraff of xml namespace mapping and form definition, we
need a line of declarative code to instantiate the button:</p>
<pre><wf:Button Name="btnMouseOver" Location="10, 15" Size="120, 25" Text="Mouse Over Me"/></pre>
<h4>Event Definitions</h4>
<p>We need to capture two events: MouseEnter and MouseLeave. We
declaratively establish that we are interested in these two events:</p>
<pre><mxh:MxEvents>
<mxh:Events>
<mxh:OnEvent Name="OnMouseEnter" Object="{btnMouseOver}" EventName="MouseEnter"/>
<mxh:OnEvent Name="OnMouseLeave" Object="{btnMouseOver}" EventName="MouseLeave"/>
</mxh:Events>
</mxh:MxEvents></pre>
<h4>Conditions</h4>
<p>We're also interested in two conditions: the button is focused, or it is not
focused. We declaratively describe these two conditions:</p>
<pre><mxh:MxConditions>
<mxh:ConditionSets>
<mxh:ConditionSet Name="MouseFocused">
<mxh:Conditions>
<mxh:OnCondition Property="Focused" Value="true"/>
</mxh:Conditions>
</mxh:ConditionSet>
</mxh:ConditionSets>
</mxh:MxConditions></pre>
<p>Since "not focused" is the opposite of "focused", we actually only need to
defined the condition for focused, and let the control logic handle the "else"
condition. </p>
<p>Also note that we're not specifying the object on which to test the
condition. By default, the condition is tested on the object that sourced
the event. Since this is the button, we don't need to explicitly state the
object.</p>
<h4>Actions</h4>
<p>Next, we're going to describe, declaratively, the actions that are taken when
the different conditions are qualified. Note that we have one action that
simply happens when the event is fired--the MouseLeave event does not have any
qualifying conditions. The actions describe what we want the button to
look like when the mouse enters the button and is focused, not focused, and when
the mouse leaves the button:</p>
<pre><mxh:MxActions>
<mxh:ActionSets>
<mxh:ActionSet Name="MouseEnterFocused">
<mxh:Actions>
<mxh:Set Property="ForeColor" Value="Green"/>
</mxh:Actions>
</mxh:ActionSet>
<mxh:ActionSet Name="MouseEnterNotFocused">
<mxh:Actions>
<mxh:Set Property="ForeColor" Value="Red"/>
</mxh:Actions>
</mxh:ActionSet>
<mxh:ActionSet Name="MouseLeave">
<mxh:Actions>
<mxh:Set Property="ForeColor" Value="Black"/>
</mxh:Actions>
</mxh:ActionSet>
</mxh:ActionSets>
</mxh:MxActions></pre>
<p>As with the conditions, note that the object whose property value we are
setting is not specified. The default is the event sender.</p>
<h4>Control Logic</h4>
<p>At this point, all we've established is the UI presentation, the events we're
interested in, what the rules are, and things we want done. The control
logic glues this all together by saying "when <i>this</i> event happens,
qualified by <i>that</i> rule, do the things specified <i>here</i>." This
is expressed declaratively (and remember, this is only one of many different
ways you can do this, depending of course on your underlying imperative code):</p>
<pre><mxh:MxController>
<mxh:Controllers>
<mxh:Controller Description="On Mouse Enter Focused"
OnEvent="{OnMouseEnter}"
QualifiedBy="{MouseFocused}"
Action="{MouseEnterFocused}"
ElseAction="{MouseEnterNotFocused}"/>
<mxh:Controller Description="On Mouse Leave"
OnEvent="{OnMouseLeave}"
Action="{MouseLeave}"/>
</mxh:Controllers>
</mxh:MxController></pre>
<p>That's it. The result is:</p>
<p>on mouse leave:
<img border="0" src="PropertyEvents/mouseLeave.png" width="127" height="33"></p>
<p>on mouse enter, focused:
<img border="0" src="PropertyEvents/mouseEnterFocused.PNG" width="125" height="32"></p>
<p>on mouse enter, not focused:
<img border="0" src="PropertyEvents/mouseEnterNotFocused.PNG" width="126" height="32"></p>
<h3>CheckBox State</h3>
<p>In this example, I'm going to demonstrate hooking the CheckedChanged property
event of a CheckBox to change the Enabled visual style of a Button.</p>
<h4>Presentation Layer</h4>
<p>For this demo, we need two controls--a CheckBox and a Button:</p>
<pre><wf:CheckBox Name="ckEmailMe" Location="10, 105" Size="160, 15" Text="I want lots of junk email" Checked="true"/>
<wf:Button Name="btnCheckOut" Location="200, 100" Size="80, 25" Text="Check Out" Enabled="true"/></pre>
<h4>Event Definition</h4>
<p>The event we're interested in is the CheckedChanged event of the CheckBox:</p>
<pre><mxh:OnEvent Name="OnCheckedChanged" Object="{ckEmailMe}" EventName="CheckedChanged"/></pre>
<h4>Conditions</h4>
<p>There are two conditions we are interested in--whether the checkbox is
checked or unchecked. As with the button focused state example above, we
only need to test for whether the checkbox is checked:</p>
<pre><mxh:ConditionSet Name="Checked">
<mxh:Conditions>
<mxh:OnCondition Property="Checked" Value="true"/>
</mxh:Conditions>
</mxh:ConditionSet></pre>
<p>Again, we don't need to explicitly state that the object whose property we
are testing is the checkbox, because that object is the source of the event.</p>
<h4>Actions</h4>
<p>The actions are straightfoward--if the checkbox is checked, the button
becomes enabled, otherwise it is disabled:</p>
<pre><mxh:ActionSet Name="EnableCheckOut">
<mxh:Actions>
<mxh:Set Object="{btnCheckOut}" Property="Enabled" Value="true"/>
</mxh:Actions>
</mxh:ActionSet>
<mxh:ActionSet Name="DisableCheckOut">
<mxh:Actions>
<mxh:Set Object="{btnCheckOut}" Property="Enabled" Value="false"/>
</mxh:Actions>
</mxh:ActionSet></pre>
<p>Notice here that the object whose property value we are setting is specified.
This is because the object whose style we are affecting is not the same object
as the sender of the event.</p>
<h4>Controller</h4>
<p>A one line controller glues the event, rule, and actions together:</p>
<pre><mxh:Controller Description="Validate Check Out"
OnEvent="{OnCheckedChanged}"
QualifiedBy="{Checked}"
Action="{EnableCheckOut}"
ElseAction="{DisableCheckOut}"/></pre>
<p>The result is:</p>
<p><img border="0" src="PropertyEvents/checked.PNG" width="278" height="34"></p>
<p><img border="0" src="PropertyEvents/unchecked.PNG" width="276" height="36"></p>
<h3>Traffic Light Example</h3>
<p><img border="0" src="PropertyEvents/traffic.PNG" width="193" height="179"></p>
<p>In this example, the events that are being monitored are the CheckedChanged
event of the CheckBox control and the Tick event of a System.Windows.Forms.Timer
instance. Note that this example (as with the others) implements all the
logic declaratively--the only thing written in code is the generic classes and
algorithms. It is possible to write simple but complete applications
completely declaratively.</p>
<p>I'm not going to show all of the xml here because it gets a bit
tedious. However, this example illustrates using a container to hold some
state information:</p>
<pre><mxh:MxContainer Name="stateInfo">
<mxh:MxObjects>
<mxh:MxObject Name="nsState" Type="System.String" Default="g"/>
<mxh:MxObject Name="nsGo" Type="System.Boolean" Default="true"/>
</mxh:MxObjects>
</mxh:MxContainer></pre>
<p>Some slightly more interesting rules, such as:</p>
<pre><mxh:ConditionSet Name="nsGreen">
<mxh:Conditions>
<mxh:OnCondition Object="{nsState}" Property="AsString" Value="g"/>
<mxh:OnCondition Object="{nsGo}" Property="AsBool" Value="true"/>
</mxh:Conditions>
</mxh:ConditionSet></pre>
<p>And some more interesting actions, such as:</p>
<pre><mxh:ActionSet Name="nsGreenToYellow">
<mxh:Actions>
<mxh:Set Object="{sg}" Property="BackColor" Value="Gray"/>
<mxh:Set Object="{sy}" Property="BackColor" Value="Yellow"/>
<mxh:Set Object="{nsState}" Property="Value" Value="y"/>
<mxh:Set Object="{nsTimer}" Property="Interval" Value="1000"/>
<mxh:Set Object="{nsTimer}" Property="Enabled" Value="true"/>
</mxh:Actions>
</mxh:ActionSet></pre>
<p>This illustrates how multiple conditions are always logical and'ed together.
Also note how the actions involve many different objects--some are the UI
objects, some are objects created declaratively by the container to manage
state, and we're also setting the properties of the timer to change time
interval and restart the timer. Nifty stuff!</p>
<h2>Implementation</h2>
<p>The interesting thing about all of this is that the MxEvents, MxConditions,
MxActions, and MxController classes are nothing more than containers for
collections and property values. The real work is being done entirely in
the OnEvent class. There are two salient processes that OnEvent handles:
initialization and actual event processing.</p>
<h3>Initialization</h3>
<p>The OnEvent derives from ISupportInitialize, which the MycroXaml parser tests
for when constructing objects and invokes the BeginInit and EndInit methods of
the class immediately after instantiation and after all properties have been
set, respectively. In the EndInit implementation, the object's event is
wired up to a generic handler implemented in the OnEvent class:</p>
<pre>public virtual void EndInit()
{
WireUp(this, "Fire");
}
protected void WireUp(object handler, string methodName)
{
if (obj==null)
{
throw(new EventTargetNullException("Event target is null."));
}
EventInfo ei=obj.GetType().GetEvent(eventName, BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Static);
if (ei==null)
{
throw(new EventBindingException("Can't find event "+eventName));
}
Delegate dlgt=null;
try
{
dlgt=Delegate.CreateDelegate(ei.EventHandlerType, handler, methodName);
}
catch {}
if (dlgt==null)
{
throw(new EventBindingException("Can't create generic delegate for event "+eventName));
}
ei.AddEventHandler(obj, dlgt);
}</pre>
<h3>The Event Handler</h3>
<p>The OnEvent.Fire event handler invokes the event handler for each controller
interested in the event:</p>
<pre>public void Fire(object sender, EventArgs e)
{
ControllerEventArgs cea=new ControllerEventArgs(e);
object[] args=new object[] {sender, cea};
foreach(Delegate sink in Triggered.GetInvocationList())
{
try
{
// process any controller that is unqualified or has no qualifying logic.
if ( (((IController)sink.Target).QualifiedBy == null) || (!cea.IsQualified) )
{
sink.DynamicInvoke(args);
}
}
catch(Exception ex)
{
throw(new ControllerEventException(ex.InnerException.ToString()));
}
}
}</pre>
<p>You will note that the controller's handler is fired if:</p>
<ul>
<li>the controller does not specify a qualifier rule</li>
<li>or, as long as no other controller has been qualified.</li>
</ul>
<p>The second condition ensures that only one qualifying condition is executed
per event. Otherwise, it is possible to change the value of a property so
that the next controller in the multicast event handler is also qualifiied, and
thus executes its action list. To see this happen, remove the " || (!cea.IsQualified)"
and run the traffic light demo. You will see that it completely skips the
yellow light state.</p>
<h3>Interfaces</h3>
<p>The actions, conditions, and controller classes implement the following
interfaces:</p>
<pre>public interface IAction
{
void Update();
}
public interface ICondition
{
bool IsMet(bool curState);
}
public interface IController
{
ConditionSet QualifiedBy
{
get;
set;
}
}</pre><p>By implementing these interfaces in your own classes, it is very easy
to extend the functionality of the actions, conditions, and controllers. </p>
<h3>The Other Files</h3>
<p>The MxHelpers assembly contains additional files (MxObject, MxContainer, and
MxBinding) that I haven't discussed in this article--those are for a future
article!</p>
<h2>Conclusion</h2>
<p>Property events, declaratively coded, is a flexible way of describing how
events should affect the property values of objects. The examples I've
provided here are fairly simplistic. Other uses include
enabling/disabling/hiding controls and menus based on the user's role. The
kinds of actions, conditions, and controllers can be easily extended to provide
considerable more functionality--for example, the actions can be extended to
execute MyXaml workflows. Hopefully this article has given you some ideas
as to what can be done with a few lines of general purpose code and some xml,
rather than hard coding all the visual style logic imperatively. And don't
forget that this code works not just for visual objects but for any objects that
provide property change events.</p>
<p>And that brings up two points--one, is that we've identified a best practice
with regards to imperative code--consider the appropriateness of firing an event in
your property setters associated with a change in value. The second is the exploration of best practices
with regards to declarative programming--specifically, in this article,
preventing the entanglement of the presentation layer, rule definition, and
state control.</p>
</body>
</html>
Submit an article or tip