Lesson 3: Specify Form Layout
- 5 minutes to read
This document contains an overview of the data form’s layout settings and an example on how to arrange editors and manage their labels.
Form Layout - Overview
When a data form is generated based on a bound object’s properties, it arbitrarily positions editors vertically, and displays the corresponding property name next to the input box. You can change the form’s default layout. To adjust layout settings for individual editors, use attributes or data form item properties. The DataFormView class has a set of properties for layout customization at the form level.
Reorder Editor
You can locate multiple editors in a single row and specify editor order. To do this, use the following parameters of the DataFormItemPositionAttribute attribute or properties of the DataFormItem descendant object:
- RowOrder - a row where the editor is located.
- ItemOrderInRow - the editor position within a row.
If two items have the same RowOrder value, they are located in the same row in the order specified by their ItemOrderInRow values. The DataFormView.EditorHorizontalSpacing and DataFormGroup.EditorHorizontalSpacing properties specify the distance between editors in a row for an entire form or a specific group.
Items with unspecified RowOrder are displayed at the bottom of the data form.
Manage Labels
The data form can display strings or icons as editor labels. To specify an editor label and its position, use the following parameters of the DataFormDisplayOptionsAttribute attribute or properties of the DataFormItem descendant object:
- LabelText - label text.
- LabelIcon - the label icon.
- LabelPosition - the label position relative to the editor.
- LabelIndent - the distance between the label and the editor.
- IsLabelVisible - label visibility.
You can also use the following properties of the DataFormView object to specify layout settings for all editor labels on the form:
Change Editor and Label Width
To change the width of editors and their labels, use the following parameters of the DataFormDisplayOptionsAttribute attribute or properties of the DataFormItem descendant object:
- EditorWidth, EditorMinWidth, EditorMaxWidth
- LabelWidth, LabelMinWidth, LabelMaxWidth
You can also use the following properties of the DataFormView to set the width for all editors and labels on the data form:
- EditorWidth, EditorMinWidth, EditorMaxWidth
- EditorLabelWidth, EditorLabelMinWidth, EditorLabelMaxWidth
These properties allow you to define absolute or proportional (*) width values.
Group Editors
You can organize editors into groups. To place an editor in a group, assign the group name to the GroupName property of the DataFormDisplayOptionsAttribute attribute or data form item object. Editors with an undefined GroupName are placed in a default group that is displayed at the top of the form without a header.
The data form stores groups in the Groups collection. When you specify the GroupName parameter for an editor, a group with this name is added to this collection. You can also add items to the collection directly.
An individual item of the Groups collection is a DataFormGroup object that stores group settings:
- HeaderBackgroundColor / HeaderTextColor - specify group header colors.
- HeaderFontSize/HeaderFontFamily/HeaderFontAttributes- adjust group header font settings.
- IsHeaderVisible - shows or hides a group header.
- IsCollapsed, AllowCollapse - collapses or expands a group and prevents a user from collapsing a group.
The DataFormView class also has corresponding properties to specify similar settings for all groups on the form.
Example
Open the solution created in Lesson 2 and arrange data form editors and labels as follows:
- Place editors bound to the data object’s FirstName and LastName properties in the first row.
- Hide the Gender editor.
- Replace text labels with icons.
- Organize editors into two groups: Profile and Contact Info.
- Specify the same header appearance for both groups.
Before | After |
|---|---|
|
|
In XAML markup, use DataFormView properties to set the width and color of editor labels and specify group header appearance.
<dxdf:DataFormView x:Name="dataForm" EditorLabelWidth="40" EditorLabelColor="Gray" GroupHeaderBackgroundColor="#e9e9e9" GroupHeaderTextColor="#f05b41"> <!-- ... --> </dxdf:DataFormView>To specify the position, label icon and group name for each editor, apply attributes to the PersonalInfo class properties in C# code or set up data form item objects in XAML markup.
Note
To use icons in this example, add the images to the the Android project’s Resources/drawable folder or the iOS project’s Assets.xcassets asset catalog.
Use Attributes
- Use the DataFormItemPositionAttribute attribute with the specified RowOrder and ItemOrderInRow parameters to arrange editors.
- Use the DataFormDisplayOptionsAttribute attribute with the specified LabelIcon and GroupName parameters to set an editor label icon and place an editor in a group.
- For the PersonalInfo.Gender property, set the DataFormDisplayOptionsAttribute.IsVisible parameter to false to hide the corresponding editor on the form.
using DevExpress.XamarinForms.DataForm;
// ...
namespace DataFormExample {
public class PersonalInfo {
[DataFormItemPosition(RowOrder = 1, ItemOrderInRow = 1)]
[DataFormDisplayOptions(LabelIcon = "editors_name", GroupName="Profile")]
public string FirstName { get; set; }
[DataFormItemPosition(RowOrder = 1, ItemOrderInRow = 2)]
[DataFormDisplayOptions(IsLabelVisible = false, GroupName="Profile")]
public string LastName { get; set; }
[DataFormDisplayOptions(LabelIcon = "editors_birthdate", GroupName="Profile")]
public DateTime BirthDate { get; set; }
[DataFormDisplayOptions(IsVisible =false)]
public virtual Gender Gender { get; set; }
[DataFormPasswordEditor]
[DataFormDisplayOptions(LabelIcon = "editors_password", GroupName="Profile")]
public string Password { get; set; }
[DataFormDisplayOptions(LabelIcon = "editors_email", GroupName="Contact Info")]
public string Email { get; set; }
[DataFormMaskedEditor(Mask = "(000) 000-0000", Keyboard = "Telephone")]
[DataFormDisplayOptions(LabelIcon = "editors_phone", GroupName="Contact Info")]
public string Phone { get; set; }
}
public enum Gender { Female, Male, RatherNotSay }
}
Set Up Data Form Items
- Populate the Items collection with data form items that correspond to the PersonalInfo class properties.
- Specify RowOrder/ItemOrderInRow, LabelIcon and GroupName properties for each data form item.
- To hide the form’s Gender input field, set the IsVisible property to false for the data form item that corresponds to the PersonalInfo.Gender property.
<dxdf:DataFormView x:Name="dataForm"
EditorLabelWidth="40"
GroupHeaderBackgroundColor="#e9e9e9"
GroupHeaderTextColor="#f05b41"
EditorLabelColor="Gray">
<dxdf:DataFormTextItem FieldName="FirstName"
RowOrder="1"
ItemOrderInRow="1"
LabelIcon="editors_name"
GroupName="Profile"/>
<dxdf:DataFormTextItem FieldName="LastName"
RowOrder="1"
ItemOrderInRow="2"
IsLabelVisible="False"
GroupName="Profile"/>
<dxdf:DataFormDateItem FieldName="BirthDate"
RowOrder="2"
DisplayFormat="d"
LabelIcon="editors_birthdate"
GroupName="Profile"/>
<dxdf:DataFormComboBoxItem FieldName="Gender"
IsVisible="False"/>
<dxdf:DataFormPasswordItem FieldName="Password"
RowOrder="3"
LabelIcon="editors_password"
GroupName="Profile"/>
<dxdf:DataFormTextItem FieldName="Email"
RowOrder="4"
LabelIcon="editors_email"
GroupName="Contact Info"/>
<dxdf:DataFormMaskedItem FieldName="Phone"
RowOrder="5"
Mask="(000) 000-0000"
Keyboard="Telephone"
LabelIcon="editors_phone"
GroupName="Contact Info"/>
</dxdf:DataFormView>