Bulletcode.NET

Controls

The Bulletcode.UI.Controls namespace contains UI elements, converters, behaviors and markup extensions for desktop and mobile applications using MAUI. This namespace can be imported into a XAML file:

<ContentView
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:ctrl="clr-namespace:Bulletcode.UI.Controls;assembly=Bulletcode.UI"
    x:Class="App.Views.ExampleControl"
    >
    <!-- TODO -->
</ContentView>

Fields

Fields are UI elements which consist of a label, input element and validation message and are bound to a property of the view model. For example:

<EntryField for="Name"/>

The field’s label is based on the Display attribute. It can also be specified directly using the Label property. The IsLabelVisible property can be set to false to hide the label.

There are several field types available which contain different input elements:

• EntryField — field for entering single lines of text and numbers. It automatically sets the Keyboard and IsPassword properties based on the DataType attribute. It also sets the MaxLength based on the StringLength and MaxLength attributes. In addition, it passes the IsReadOnly, Placeholder and TextTransform properties to the entry element. When using a numeric property, the value is automatically converted to and from a string, and conversion errors are handled. An optional StringFormat can be set for converting the number to a string.
• EditorField — field for entering multiple lines of text. It works in a similar way to the EntryField.
• PickerField — drop-down list of items. The ItemsSource property specifies the items. The optional ItemDisplayPath, ItemConverter and ItemNullValue properties can be used to modify the binding used for displaying the items.
• CheckBoxField — checkbox for editing Boolean properties. The label is displayed next to the checkbox.
• SwitchField — switch element for editing Boolean properties. The OnText and OffText properties can be used to alter the text displayed next to the switch.
• SliderField — slider element for editing numeric properties. The Minimum and Maximum properties are passed to the slider; they are automatically retrieved from the Range attribute. The IsValueVisible property can be set to false to hide the value and the ValueFormat can be used to change its format. The ValueWidth property can be used to specify a fixed width for the value label.
• StepperField — stepper element for editing numeric properties. It works in a similar way to the SliderField. The Increment property is based on the Step attribute.
• DatePickerField — date picker for editing DateTime properties. The Format, MinimumDate and MaximumDate properties are passed to the date picker.
• TimePickerField — time picker for editing TimeSpan properties. The Format property is passed to the time picker.
• RadioButtonsField — field containing a group of radio buttons. The ItemsSource property specifies the items. The optional ItemDisplayPath and ItemConverter properties can be used to modify the binding used for displaying the radio button content.

The base Field class can be inherited to create custom field types. This element can also be used directly to add a label and validation message to any content.

DataGrid

The DataGrid element can be used to display tabular data. It must contain one or more columns, for example:

<ctrl:DataGrid ItemsSource="{Binding Rows}">
    <ctrl:DataGrid.Columns>
        <ctrl:DataGridTextColumn For="Name" Header="{i18n:Translate Name}" Width="200"/>
        <ctrl:DataGridTextColumn For="Email" Header="{i18n:Translate Email}" Width="300"/>
    </ctrl:DataGrid.Columns>
</ctrl:DataGrid>

The grid can be scrolled both horizontally and vertically. It uses a list of objects as the ItemsSource and it doesn’t automatically provide any paging or sorting. It supports both single and multiple SelectionMode, and the SelectedItem and SelectedItems properties can be used to bind the selection state to the view model.

The IsHeaderVisible property can be set to false to hide the grid’s header.

Each column has the Header property, which specifies the header text, and the Width property, which can be an absolute value in device-independent units, or a fraction of the leftover space (a number followed by a * in XAML).

The following types of columns are available:

• DataGridTextColumn — displays text values using the For property of the view model. An optional Converter and StringFormat can be specified.
• DataGridColumn — displays cell content using the specified CellTemplate.

Custom columns can be implemented by inheriting the DataGridBaseColumn class and implementing the CreateCell() method.

The appearance of the grid can be customized by overriding the default colors in the resource dictionary, for example DataGridAlternatingRowLightBackgroundColor. It is also possible to customize the RowStyle and HeaderRowStyle used by the grid, the HeaderLabelStyle for both the grid and individual columns, and the LabelStyle for an individual text column.

Other elements

The Expander element displays a button with the specified Header text, which can be used to show or hide the element’s content. For example:

<ctrl:Expander Header="{i18n:Translate Exception Details}">
    <Editor IsReadOnly="True" HeightRequest="300" Text="{Binding ErrorDetails, Mode=OneWay}"/>
</ctrl:Expander>

The Icon element is an image which displays the icon with the specified IconName. A custom IconColor and IconSize can also be specified.

The IconButton element is a button which displays the icon with the specified IconName next to the button’s text. By default the TextColor and FontSize are used for the icon, but they can also be customized.

The application must register an IIconProvider service for the Icon and IconButton elements to work. See Icon provider for more information.

The MainWindow inherits the Window class from MAUI. It creates a custom title bar, and binds its title to the Title property of the content page, which is usually the AppShell. It also has a MaximizeAtStartup property which causes the window to be maximized at startup when it’s set to true; this is only supported on Windows.

Behaviors

The InfiniteRotationBehavior adds an animation to the target element which causes it to rotate. The Duration of the animation can be customized.

The KeyboardBehavior makes it possible to handle Enter and Escape keys. It is used internally by BasePage and DialogPage.

Markup extensions

The IconSource markup extension can be used to pass the icon created by the IIconProvider service to another element. For example, an icon can be specified for a ShellContent element:

<ShellContent
    Title="{i18n:Translate Project}"
    Icon="{ctrl:IconSource file}"
    Route="Project"
    ContentTemplate="{shell:PageTemplate v:ProjectPage}"
    />

The shell:PageTemplate markup extension can be used to register a page as a static route. See Static routes for more information.

The i18n:Translate, i18n:Format and i18n:MultiFormat markup extensions are used to provide translations in XAML files. See Internationalization for more information.

Converters

The following value converters are provided by Bulletcode.UI:

• AndConverter — a multi-value converter which combines multiple Boolean values using the logical AND operator.
• AreObjectsEqualConverter — a multi-value converter which returns true when two values are equal.
• BooleanConverter — converts a Boolean value to the value corresponding to the TrueValue and FalseValue properties.
• CoalesceConverter — a multi-value converter which returns the first value which is not null.
• ConstNameConverter — returns the localized display name of a class constant with the specified value using the IConstHelper service. This is a generic converter which can be used in XAML in the following way:

<ctrl:PickerField For="Role" ItemsSource="{Binding Roles}">
    <ctrl:PickerField.ItemConverter>
        <ctrl:ConstNameConverter x:TypeArguments="auth:Role"/>
    </ctrl:PickerField.ItemConverter>
</ctrl:PickerField>

• CustomValueConverter — a converter which can be created programmatically using the specified conversion function, for example:

var converter = new CustomValueConverter<double, bool>( width => width >= 0 );

• EnumNameConverter — returns the localized display name of an enumeration value using the IConstHelper service.
• IsNotNullConverter — return true if the value is not null.
• IsNotNullOrEmptyConverter — return true if the value is not null or an empty string or collection.