BarManager.LayoutUpgrading Event
Allows you to customize the layout of bar objects being loaded from a stream or XML file.
Namespace: DevExpress.Xpf.Bars
Assembly: DevExpress.Xpf.Core.v21.2.dll
NuGet Package: DevExpress.Wpf.Core
Declaration
Event Data
The LayoutUpgrading event's data class is LayoutUpgradingEventArgs. The following properties provide information specific to this event:
| Property | Description |
|---|---|
| Handled | Gets or sets a value that indicates the present state of the event handling for a routed event as it travels the route. Inherited from RoutedEventArgs. |
| NewItems | Provides access to a collection of actions used to create new bar objects (bars, bar items and bar item links). New bar objects are those that are not defined in the layout being loaded. |
| OriginalSource | Gets the original reporting source as determined by pure hit testing, before any possible Source adjustment by a parent class. Inherited from RoutedEventArgs. |
| RoutedEvent | Gets or sets the RoutedEvent associated with this RoutedEventArgs instance. Inherited from RoutedEventArgs. |
| Source | Gets or sets a reference to the object that raised the event. Inherited from RoutedEventArgs. |
The event data class exposes the following methods:
| Method | Description |
|---|---|
| InvokeEventHandler(Delegate, Object) | When overridden in a derived class, provides a way to invoke event handlers in a type-specific way, which can increase efficiency over the base implementation. Inherited from RoutedEventArgs. |
| OnSetSource(Object) | When overridden in a derived class, provides a notification callback entry point whenever the value of the Source property of an instance changes. Inherited from RoutedEventArgs. |
Remarks
A layout of bar objects can be loaded via the BarManager.RestoreLayoutFromStream and BarManager.RestoreLayoutFromXml methods. If layout versions of the current BarManager and the loaded layout do not match, the LayoutUpgrading event fires, allowing you to customize the layout of bar objects. When this event fires, its NewItems parameter contains actions that will create new bar objects (new bar objects are bars, bar items and bar item links that were defined in a BarManager after a layout has been saved to a data store). You can remove any existing action or add new actions to create custom bar objects during the layout load.
For the LayoutUpgrading event to be fired, layout versions of the current BarManager and loaded layout must not match. To specify a layout version for a BarManager, use the DXSerializer.LayoutVersion attached property.
Consider a situation where you provided an end-user with the first version of your application with bars as part of the application’s UI. An end-user runs the application and saved the layout of bars to an XML file. Then, you are planning to release a new version of this application, extending the UI with new bar objects. When designing the application, set the BarManager.AddNewItems property to true. Otherwise, the new bar objects will be discarded when an end-user loads the saved layout.
The LayoutUpgrading event will fire during layout loading if you specify a different layout version for your BarManager via the DXSerializer.LayoutVersion attached property. If you set the BarManager.AddNewItems property to true, the event’s NewItems collection will contain actions used to create new bar objects. New bar objects are those that have the DXSerializer.LayoutVersion attached property set to the same value as the BarManager’s DXSerializer.LayoutVersion attached property. So, to make bar objects appear in the event’s NewItems collection, ensure that the BarManager.AddNewItems property is enabled, and these bar objects have the same layout version as the BarManager. If the BarManager.AddNewItems property is disabled, the NewItems collection will be empty and the layout will be loaded from a data store as is, discarding the new bar objects, if any.
If a layout version is assigned to a BarManager and you add a new bar or bar item link to a bar at design time, the same layout version is automatically assigned to these new bar objects in XAML.
Note
For the layout of bars to be saved, set the DevExpress.Xpf.Core.Serialization.DXSerializer.DXSerializer.SerializationID attached property for a BarManager to any object (for example, a string).