Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars

Expanded DetailViewLayout Attribute

You can customize the Detail View's default layout in a business class code using the DetailViewLayoutAttribute applied to required properties.

[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]WPF Controls
[Expand]Xamarin Controls
[Expand]Windows 10 App Controls
[Expand]Document Server
[Expand]Reporting
[Expand]Report Server
[Expand]Dashboard
[Collapse]eXpressApp Framework
 [Expand]Fundamentals
 [Expand]Getting Started
 [Collapse]Concepts
  [Expand]Application Solution Components
  [Expand]Business Model Design
  [Expand]Application Model
  [Collapse]UI Construction
    UI Element Overview
    Windows and Frames
   [Expand]Templates
    Action Containers
   [Expand]Views
   [Collapse]View Items
     Implement Custom View Items
     Implement Custom Property Editors
     View Items Layout Generation
     View Items Layout Customization
    List Editors
    Add and Override Images
    Text Notifications
    ASP.NET Web Application Appearance
    Application Personalization
    Using a Custom Control that is not Integrated by Default
  [Expand]Extend Functionality
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]Localization
  [Expand]System Module
  [Expand]Extra Modules
  [Expand]Debugging and Error Handling
  [Expand]Filtering
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Functional Testing
 [Expand]Deployment
 [Expand]Task-Based Help
 [Expand]Frequently Asked Questions
 [Expand]API Reference
[Expand]CodeRush
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
[Expand]End-User Documentation

View Items Layout Customization


The eXpressApp Framework was designed to help you focus your efforts on your business model and minimize the amount of time spent on the layout of individual UI controls within your application.

Though XAF’s auto-generated layout is sufficient for most use-cases, the flexibility built into the framework gives you the ability to customize the layout whenever necessary, using one of the following methods.

Expanded Design-Time Customization

Design-time layout customizations are performed using the Model Editor. The DashboardView and DetailView nodes have a Layout child node, which grants you access to the layout settings. When the Layout node is selected, the property list to the right is replaced with a design surface that imitates the current View. This allows you to see how the View will be displayed at runtime. The Layout node exposes a tree of nodes that comprises groups, tabbed groups, layout items, labels, separators, etc.

To modify default View Items layout, right-click on an empty space and choose Customize Layout. This will invoke the Customization form allowing you to drag View Items where required. The graphical prompts will display the item's target position.

When customizing at design-time, you can also remove and restore View Items by dragging the required items from the View to the Customization form, and vice versa.

To see the View Items layout tree, use the Layout Tree View tab on the Customization form. Invoke the context menu for additional customization options.

To learn more about the Customization form, the Layout Tree View tab and its context menu, refer to the Default Runtime Customization link.

Additional customization options, which are listed below, can be accessed using the Layout node’s child nodes.

  • Reorder Layout Groups and Layout Items
    The LayoutGroup, TabbedGroup and LayoutItem nodes have the Index property. Use this property to set the order within specific levels, Layout Groups or Layout Items.
  • Modify a Caption
    Specify whether or not a Caption is displayed for a Layout Group, Tabbed Group or Layout Item using the ShowCaption property.
    Specify a Caption for a group or item if you have made it visible. To do this, use the Caption property.
    Specify the location of a group or item caption using the CaptionLocation property.
  • Specify the direction of nested Layout Groups or Layout Items
    Specify whether the groups (or items) within one level are arranged consecutively from left to right or from top to bottom. To do that, use the Layout Group's Direction property.
  • Move a Layout Item to another Layout Group
    Use the drag-and-drop operation to move a Layout Item to the desired Layout Group.

You can add new items to a Detail View. Right-click the DetailView | Items node, navigate to the Add... group, choose the required View Item type and customize the newly added item as needed.

After the new item is added, put it on the Detail View as described above.

If you require layout customizations to affect both WinForms and ASP.NET applications, then perform these customizations at the Module Project level. To customize a WinForms application only, perform these customizations at the WinForms Module Project level. To customize an ASP.NET Web application only, do so at the ASP.NET Web Module Project level.

Note

  • The Splitter, Separator and Label items are specific to a WinForms XtraLayoutControl. These items are not available in the Model Editor invoked for an ASP.NET or platform-independent project, nor are they available in the Customization form or in the LayoutGroup node's Add... context menu. This behavior protects you from errors during layout customization. Add and customize these items (splitter, separator, label) at the WinForms project level.

  • There are several WinForms specific properties that are not available in the Model Editor invoked for an ASP.NET or platform-independent project.

    Perform the customization of these properties at the WinForms project level. To learn more about the size constraints for WinForms controls, refer to the Default Size Constraints topic.

The changes that you perform in the Model Editor invoked for a module (application project) are saved to the Model.DesignedDiffs.xafml (Model.xafml) file located in this module project. These changes will rewrite previous values when you run the application. It is important for you to ensure that values from other *.xafml files will not rewrite your values. To do this, review the *.xafml files that are loaded after your *.xafml file, including the Model.User.xafml generated at runtime. For details on the layer structure of the Application Model, refer to the Application Model Basics topic.

General Layout Settings

A number of layout options that affect all Views are available in the Model Editor’s Options | LayoutManagerOptions node. For example, you can disable the colon sign that is added to item captions using the IModelLayoutManagerOptions.EnableCaptionColon property, or use a custom separator instead of a colon (see IModelLayoutManagerOptions.CaptionColon.)

Refer to this attribute description to see more examples.

Expanded Runtime Customization

You can customize the layout by using the Model Editor at run time or design time (see above). To invoke the Model Editor, use the EditModel Action located in the root window's Tools main menu. Note that the EditModel Action is available when the user logged on to the application has permission to customize the Application Model. For details, refer to the Security System section.

In WinForms applications, you can customize the View Items layout by using the Customization form invoked at runtime. To display this form, right-click on an empty space in the Detail View and select Customize Layout in the invoked context menu.

The actions that can be performed when the Customization form is invoked are identical to those available when it is invoked at design time in the Model Editor (see above).

Note

You can merge run time customizations into a module of the application solution. See the How to: Merge End-User Customizations into the XAF Solution topic for details.

The changes that you perform at runtime are saved to the Model.User.xafml. This means that the next time you invoke the customized View, its items will be arranged according to the most recent changes you made. If, however, you need to invoke the View in its pre-customization state, right-click on an empty space in the View at run-time, and select Reset Layout in the invoked context menu. Alternatively, you can use the ResetViewSettings Action.

As a result, all changes made at run time to the corresponding Views | DashboardView or DetailView | Layout node will be reverted.

Note

In ASP.NET applications, the View Items layout cannot be customized at runtime.

Expanded Access the Layout Control

Use the Layout Control to arrange View Items (from the CompositeView.Items collection). With the Layout Control, a new Layout Item is created for every View Item. Layout Item settings allow you to modify the caption, caption visibility and alignment, set Item size and size constraints, indents and appearance settings, etc. In addition, a Layout Item contains the View Item's control (animation). However, you cannot specify this control’s size, docking style and position. All these settings are entirely managed by the Layout Item. You can set the Layout Item's size to a specific value (using the BaseLayoutItem.Size property). A portion of the Layout Item's area will be occupied by the Item's caption, indents and borders, while the Layout Item's control will occupy the remaining region. Note that some controls do not support resizing - for example, a text box or check box. So, setting a size for a Layout Item with these controls will have no effect, because the control has a fixed size, despite the fact that the Layout Item allows resizing.

To access the Layout Control and its Layout Items, do the following.

  • Create a new View Controller in your WinForms module.
  • Invoke the Designer for the new Controller. Since this Controller must be activated for Dashboard Views or Detail Views, set the Controller's ViewController.TypeOfView property to the required value.
  • Subscribe to the Controller.Activated event using the Properties window.
  • Replace the automatically generated Activated event handler with the following.

    Since the goal is to customize the Layout Control, you need to access it directly after it is created. The best way is to subscribe to the current View's View.ControlsCreated event.

  • Implement the View.ControlsCreated event handler, as shown below.

    To compile this code, add a reference to the DevExpress.XtraLayout.v17.1 assembly in your WinForms module.

Alternatively, you can override the CreateLayoutManagerCore virtual metod of the XafApplication class in the WinApplication.cs (WinApplication.vb) file. For instance, you can use the following code to enable the OptionsView.DrawAdornerLayer option

Note

In ASP.NET applications, you cannot access the layout control in code. All editors are placed on a page as specified by the Application Model's Views | DashboardView or DetailView | Layout node. However, you can access certain editor controls to customize them. Refer to the Access Editor Settings tutorial for details.

Expanded Important Notes

The following are important notes concerning Layout Items.

  1. When you add a new property and thus make a change to the business class structure you created at the very beginning of this XAF application, the Detail View layout of the business class is programed to automatically regenerate. If this occurs, all your manually applied customizations to the Detail View layout will disappear. To prevent this from happening, set the IModelDetailView.FreezeLayout property to true. This will allow you to freeze the Detail View layout according to the very last saved changes, thus prohibiting regeneration. Make a note, however, that if you use this property, then you are responsible for manually adding new layout items to your Detail View layout.

    If you set the IModelDetailView.FreezeLayout property to true, then the Model Editor copies the current state of the layout to the currently edited Application Model layer. Note that you can still remove a child node from the Items child node of the DetailView node. In this instance, however, it will be impossible to retain a frozen layout. Thus, the View Item corresponding to the removed node will be replaced by an empty space item in the Detail View. Setting the FreezeLayout property to false is analogous to executing the Model Editor's "Reset Differences" command, which will revert all customizations to their original default state.

    Note

    After manually customizing the layout of a business class View, you must set the FreezeLayout property to true if you plan to introduce additional properties to the business class later. If you do not set the property to true, the layout may become corrupted after introducing new business class properties. In this scenario, based on the layout rules, the layout generator may create a default layout that differs greatly from the original default layout. After applying your manual layout customizations stored in the Application Model differences file, the resulting layout will also be completely different from the original layout. The resulting layout may even become corrupted. To prevent this, always set the FreezeLayout property to true before introducing new business class properties if you have previously customized the default layout. Generally, any changes to the BO class may affect the layout generation - the FieldSizeAttribute attribute on string type properties, the Aggreagted attribute on reference type properties, the ExpandObjectMembersAttribute attribute, etc.

  2. By default, the width of Layout Items is not locked and is calculated according to the width of the Layout Group it belongs to. Thus, Layout Items belonging to different Layout Groups will have different alignments.

    Place Items in the same Group to keep them aligned.

  3. When you rearrange a layout by moving a Layout Item to a higher-level group, additional spacing between the Item moved and the next Item appears, as illustrated by the image below

    If you wish to keep equal spacing between Items, keep them in the same Group.

  4. Items and nested Groups inside each Group can be arranged either vertically or horizontally (see IModelLayoutGroup.Direction). The following image illustrates a layout fragment with complex nesting.

    All components within the same group have the same orientation, as shown by dual arrows. In order to arrange two groups horizontally, thus forming two columns of Items, you must put these two groups into another group. This process is called wrapping. You should note that extra wrapping groups can be created automatically when you drag items on the Layout design surface.

  5. When you move or hide a Layout Item, its Layout Group stays on the form. In the image below, the "Notes" Item is moved from the "Notes" Group to the "Photo" Group.

    The "Notes" Group becomes empty. This empty Layout Group may interfere with your layout. So, you may need to remove the empty Layout Group. You can also use the IModelWinLayoutManagerOptions.InvisibleGroupVerticalDistance property to specify how the empty group affects the vertical space between visible items.

  6. The Application Model's Options node contains the LayoutManagerOptions child node. As the name implies, this node's properties allow you to customize certain settings concerning layout generation.

    Note

    The LayoutManagerOptions node exposes several WinForms specific properties (see the IModelWinLayoutManagerOptions interface's members list). Perform the customizations of these properties at the WinForms project level.

To learn more about the Layout Control and Layout Items, refer to Layout Manager documentation.

Expanded See Also

How would you rate this topic?​​​​​​​