On this page you will find complete information about Prometheus' binding system.

Namespace alias

Works only for WPF and SilverLight
Because of system is distributed to several CLR-namespaces - for your convinience alias http://prometheustoolkit.codeplex.com is decalred. Declare XAML alias with xmlns:
<UserControl x:Class="Prometheus.Binding.Stuff.MultiBinding"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:pro="http://prometheustoolkit.codeplex.com">

proBindingBase

proBindingBase is main class which defines all basic binding rules. It is abstract and can not be instantiated, but every binding is derived from it. This class defines several members which you will work with:
  • Path - path to datacontext property. Dots are allowed: Order.Customer.Name
  • ElementPropertyPath - path to element property. Used only for WP7. Please, read about proForm.proBindingProperty for more information
  • BindingGroup - name of the group in which binding exists. Grouping allows you to manage all bindings in group together. You can call proForm.UpdateTarget(string groupName) , proForm.Validate(string groupName) . If your datacontext does not implement INotifyPropertyChanged or you don't have datacontext (in case of proNullContextBinding) you can setup autoupdating (use proReadOnlyBinding.UpdateGroupMode and proValidationBinding.UpdateGroupOnToData)
  • Mode property defines when binding should bring data from target to source. Possible values are:
    • Default (by default) - update rule is defined using proBindingBase.RegisterControlForBindingInitialization method. If you are developing your own control you might use this method passing appropriate Action which will be called during binding initializition
    • OnKeyUpAndLostFocus - updating occures when KeyUp or FocusLost events is raised
    • OnFocusChanged - the same as previos but only for focus change
    • OnUpdateCall - value will go from source to target only when proForm.Validate is being called
  • Bind is called when datacontext is changed. You have to call it if it was overrided and binding does not use datacontext anymore. For example, you wrote your own binding that works with current user's permissions. You should call Bind when permission set was changed, or when user was loged out or loged in.
Here is overriding for proConvertableBinding - next binding class in hierarchy:
public override void Bind()
{
    if (uiElement != null) _culture = new CultureInfo(uiElement.Language.IetfLanguageTag);
    base.Bind();
}
  • Kill - call it if there is no need in binding any more.
  • FromData() and ToData() are protected virtual methods, that you want to override when developing your own bindings
  • RegisterControlForBindingInitialization is static method. You should pass an action of type Action<UIElement, bool, proBindingBase> . Boolean value indicates whether binding is initializing or deinitializing.

proConvertableBinding

Abstract class proConvertableBinding introduces Converter and related protected methods.
  • Converter - set any converter of type IValueConverter to convert value, when it goes from source to target and back. Please, refer to IValueConverter Interface at MSDN. Prometheus toolkit also introduces proChainConverter which can be used to create chain of converters, like this:
<TextBlock>
    <TextBlock.Text>
        <pro:proReadOnlyBinding Path="Price">
            <pro:proAddTextConverter AddText="$">
                <pro:proCurrencyConverter/>
            </pro:proAddTextConverter>
        </pro:proReadOnlyBinding>
    </TextBlock.Text>
</TextBlock>
Every built-in Prometheus converter is proChainConverter and you can use it as a container for another converter
  • Convert and ConvertBack could be used by inheritor to convert any value using converter

proReadOnlyBinding

This is the first binding class that really do the job. It can bind to control, read it datacontext,subscribe to PropertyChanged event, read value, convert it and set to control property. This class would be used by you most intensively.
  • UpdateGroupMode setup how binding must react on something in current group of bindings occured:
    • None
    • UpdateTargetWhenGroupFromData - current binding target will be updated if any binding in group processed value from source to target
    • UpdateTargetWhenGroupToData - current binding target will be updated if any binding in group processed value from target to source
    • Both
  • FromDataProcessed event is raised when value is sailing from source to target

proMultiBinding

... allows more then one binding to connect to one target property.
  • MultiConverter - set any object of type IMultiConverter which will describe how values from multiple bindings will be combined to scalar value
  • BindingWrappers - you can not define binding list directly, but instead you must wrap them to proBindingWrapper:
<TextBlock>
    <TextBlock.Text>
        <pro:proMultiBinding>
            <pro:proMultiBinding.MultiConverter>
                <pro:MaxMultiConverter/>
            </pro:proMultiBinding.MultiConverter>
            <pro:proBindingWrapper>
                <pro:proReadOnlyBinding Path="Price1"/>
            </pro:proBindingWrapper>
            <pro:proBindingWrapper>
                <pro:proReadOnlyBinding Path="Price2"/>
            </pro:proBindingWrapper>
        </pro:proMultiBinding>
    </TextBlock.Text>
</TextBlock>

proBooleansBinding

proBooleansBinding is one of proMultiBinding realization with MultiConverter predefined: proBooleansMultiConverter. It can combine boolean values using 'Or' or 'And' operator

proBindingCollection

proBindingCollection is special binding. It does not do anything, it can only contains another bindings, like proMultiBinding. It allows you to create multiple bindings connected to one target. Every binding works by itself. You can create one read-only binding to read data from datacontext and one proNullContextBinding to validate user input without processing value to datacontext

proDelegateValueBinding

proDelegateValueBinding looks like proReadOnlyBinding, but it does not read value from datacontext. Instead it uses ProvideValue delegate, which you must handle and set value, which then will go to target.

proValidationBinding

proValidationBinding is proReadOnlyBinding inheritor with posibility to write value to source, validate it and show error or warning on bound control. It works great with proErrorBlock control.
  • NotifyOnSetterValidationException - whether handled proValidationException exception from property setter at datacontext must be treated as validation error (true by default)
  • NotifyOnSetterException - as NotifyOnSetterValidationException but for all types of exception
  • NotifyOnIDataErrorException - you can derive your datacontext object from interface "IDataError" (true by default)
  • NotifyWhenInvisible - false (by default) means that data will not be validated if control is invisible
  • UpdateGroupOnToData - if true - all bindings in group will be updated after current binding processes value to source
  • ValidationRules - setup as many validation rules as you want. Validation rule must be of type IValidationRule, where Validate method implementation must throw proValidationException in case of validation error. You can setup ValidationOrder for any rule:
    • ValueFromTarget - value will be validated exactyle after is was read from target
    • AfterConvert (by default) - value will be validated only after Converter.ConvertBack
You can use predefined abstract class proValidationRuleBase for your own rules
You can use any of built-in rules: proNotNullRule, proNotEmptyStringRule, proRegexMatchRule and much more...
There is speacial validation rule - jDelegateValidationRule. This rule does not implement actuall validation, but it declares delegate ValidateBy. By handling it you can implement validation directly in code-behind
  • ToDataProcessed event is raised when data has flew from target to source
  • RegisterControlToShowError is static method which you can use to define how validation error must be shown in your control. This is usefull when control is not standart control and system does not know how to show the user that control is in invalid state. In addition you can wrap your control in to proErrorBorder - it will do the job for you. If target control is yours, implement IShowError interface and describe how to show the error
  • Validate - call this to validate data and process it from target to source

proNullContextBinding

or anti-MVVM pattern. This binding works with our of datacontextm it does all things that proValidationBinding does except setting value to property in source. Use it to validate user input by setting validation rules and converter. Note that ConvertBack will be invoked, not Convert

proForm

Wrap your bound controls to proForm. It gives you access to group managment:
  • Bind - in WP7 you should call bind manually directly after settings datacontext. WPF and SilverLight will bind it automatically
  • Validate - validates all bindings in group or in all groups
  • IsValid, HasErrors - whether any of bindings inside this proForm is valid
  • GetFirstError - this methods returns first error in provided group
  • FirstErrorChanged - is raised, when FirstError changed
  • CustomError - dependency property, you can setup any custom error for this form.
  • GetjBindingByParentIsThis and GetjBindingByParentIsThisAndBindingGroup - get bindings inside this form
  • UpdateTarget - raise flowing value from source to target
  • proBindingProperty,SetproBinding and GetproBinding - attached property, which can be used to setup binding in platforms, where custom markup is no allowed (WP7). For this case you should setup property ElementPropertyPath or register it with proBindingBase.RegisterDefaultElementPropertyPath. Some built-in controls has already been registered by system. If there is not default path registered for control system tries to detect it by ContentPropertyAttribute or by Type.GetDefaultMembers.
Setting up binding as attached property looks like this:
<Grid x:Name="ContentPanel" Grid.Row="1" Margin="12,0,12,0">
    <pro:proForm x:Name="form">
        <StackPanel Orientation="Vertical">
            <TextBlock>
                <pro:proForm.proBinding>
                    <ReadOnly:proReadOnlyBinding ElementPropertyPath="Text"/>
                </pro:proForm.proBinding>
            </TextBlock>
        </StackPanel>
    </pro:proForm>
</Grid>

Last edited Sep 11, 2012 at 8:51 AM by jinek, version 16

Comments

No comments yet.