Log In
Home
Support
Demos
Documentation
Blogs
Training
Webinars
[Expand]General Information
[Expand]WinForms Controls
[Expand]ASP.NET Controls and MVC Extensions
[Expand]ASP.NET Bootstrap Controls
[Expand]ASP.NET Core 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
   [Expand]View Items
    List Editors
    Add and Override Images
    Text Notifications
    Ways to Show a Confirmation Dialog
    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
  Frequently Asked Questions
 [Expand]API Reference
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation

Add and Override Images

An application is more attractive if UI elements are associated with images. In eXpressApp Framework applications, images display or accompany default Actions, navigation control items, Detail View captions, etc. You can replace the built-in images with custom ones, and provide special images for custom features implemented in separate modules. This topic provides information on how to add and override images in XAF applications.

Note

The standard image library is demonstrated in the Feature Center demo, installed with XAF.

Expanded Images Concept Overview

In XAF, there are two types of image sources.

  • File Image Source
    For this source, a folder with images is specified. For each image, the Copy to Output Directory option must be set to Copy always, so the images will always be copied to the output directory.
  • Assembly Resource Image Source
    This source stores the name of the assembly and the folder containing the images. For each image, the Build Action option must be set to Embedded Resource. So, the images will be embedded in the project's build output.

An application can have several image sources distributed between solution projects. To examine the image sources that will be available when running your application, invoke the Model Editor for an application project (Windows Forms, ASP.NET or Mobile). Locate the ImageSources node. Its child nodes represent image sources (File Image Source or Assembly Resource Image Source). The following image demonstrates the auto-generated image sources from which images are loaded to the Windows Forms version of the Main Demo.

In this screenshot, you can see the following image sources.

  • Images: File Image Source
    This image source is generated for the Images folder located in the application project. By default, this folder is added to the Web and Mobile application project. It contains images specific to the ASP.NET and Mobile application. In a Windows Forms application project, there is no Images folder by default. However, you can add it. The images added to this folder as embedded resources will be found by the system when required, since an image source is created for this folder automatically.
  • DevExpress.ExpressApp.<AssemblyName>: Assembly Resource Image Source
    This image source is generated for the Images folder located in the referenced assembly. This folder may not be in the assembly. However, if it is, the images added to it will be found, since an image source is automatically generated.
  • MainDemo.Module: Assembly Resource Image Source
    This image source is generated for the Images folder located in the application module. You can add this folder and populate it with custom UI specific images, representing embedded resources.
  • MainDemo.Module.Win: Assembly Resource Image Source
    This image source is generated for the Images folder in the Window Forms module. You can add this folder and populate it with custom UI specific images, representing embedded resources.
  • DevExpress.ExpressApp.Images.v17.2: Assembly Resource Image Source
    This image source is generated for the DevExpress.ExpressApp.Images.dll assembly, which is referenced in Windows Forms, ASP.NET Web and Mobile application projects. It contains the images represented as embedded resources. They are installed as separate files into the %PROGRAMFILES(x86)%\DevExpress 17.2\Components\Sources\DevExpress.ExpressApp\DevExpress.ExpressApp.Images\Images folder by default. So, you can access them if required.
  • DevExtreme Icon Library: Assembly Resource Image Source
    Built-in icon library which provides a large number of icons for Mobile applications.

In any XAF application, the set of auto-generated image sources will be as specified above.

  • An Assembly Resource Image Source for each module referenced in the current application project
    The modules include the built-in XAF or 3d-party modules, and the modules from the current solution.
  • An Assembly Resource Image Source for the DevExpress.ExpressApp.Images.dll assembly
  • A File Image Source for the current application project's Images folder

To find the required image, the framework looks through the image sources listed in the Application Model's ImageSources node. The first image found by the specified name is loaded for the target control. Since images can be named similarly in different sources, the order in which image sources are listed is important. You can examine or change this order via the Model Editor invoked for an application project. In the image above, you can see that each node has the IModelNode.Index property. This property specifies the order of access to the current image source, among others.

Expanded Image Source Customizations

  • Add Image Sources

    In addition to the auto-generated image sources, you can add custom Assembly Resource Image Sources to your modules, and File Image Sources to your application project.

    To create an Assembly Resource Image Source for a referenced assembly with images, add a new AssemblyResourceImageSource node to the ImageSources node in the Model Editor, invoked in the module project. Specify the Assembly and Folder properties of the newly added node. Then, add references to your image assembly to all your module and application projects.

    To create a File Image Source, add a new FileImageSource node to the ImageSources node in the Model Editor, invoked for your application project. Set the Folder property of the newly added node to the name of your folder in the application project.

  • Add Images
    Add the required images to the Images folder located in a module (if there is no such folder, create it). These images will be found if the image source generated for the module has a lower index than the image source where there are images with the same names.
    Do not forget that images that are added to the Images folder in a module must represent embedded resources.
  • Replace Individual Images
    Add the required images to the Images folder located in a module (if there is no such folder, create it). These images will substitute for the corresponding default images if they are called by the same names, and the image source generated for the module has a lower index than the image source where there are images to be substituted.
    Do not forget that images that are added to the Images folder in a module must represent embedded resources.
  • Reorder Image Sources
    Invoke the Model Editor for the required application project and specify the Index property for the ImageSource node's child nodes as required.
  • Note

    You can add custom images to the Images folder located in the application project instead. However, this is not recommended, because working with resources is a more reliable method than working with individual folders.

Expanded Rules for Image Files

In a C# project, name images in the following way: Employee.png. In a VB.NET project, the name must be prefixed with the current module assembly name and the folder name: MySolution.Module.Images.Employee.png.

The recommended format is PNG. However, you can assign an image in any format. The Image Loader will convert it to PNG format.

Images that form the standard image library are named using the following convention:

MainCategory[_AdditionalCategories]_SizeSuffix.extension

If there are multiple additional categories, they are also separated by the "_" sign.

XAF uses images of four standard sizes. The following table lists them.

Image sizeImage suffixDescription
12x12"12x12"Used by ASP.NET Web Property Editors.
16x16noneStandard-sized images.
32x32"32x32"Large images.
48x48"48x48"Used in dialog windows.

As a general rule, if you need a custom image to represent a business class in a UI, ensure that there are at least two versions of the image: ImageName.png and ImageName_32x32.png.

You can specify a different image for a selected navigation item. For this purpose, add the _Active suffix to the image name.

In ASP.NET and Mobile applications, SVG images are also supported. Their display size is determined by the viewBox attribute. Note that SVG icons are not grayed out automatically for disabled Actions. You should manually add a disabled variant of an SVG icon with the _Disabled suffix (e.g., MyIcon_Disabled.svg).

In Mobile applications, we recommend using large images (32x32) from the DevExpress.ExpressApp.Images.v17.2 assembly or SVG images.

In Visual Basic, capitalize "Images".

Note

The recommended way of using custom images in an XAF application is embedding them into assemblies as resources. When using image files instead, you may run into the .NET limitation, which states that a fully qualified file name must be less than 260 characters long. This can be an issue, for instance, when ClickOnce deployment is used. When installing an application, ClickOnce can create long paths. In this case, if the path to an image used in the XAF application is longer than 260 characters, the image will not be available in the application and the corresponding entry will be created in the application Log File.

Expanded Set Images

UI elements that can be displayed by images are defined in the Application Model via nodes with the ImageName property. For example, the ImageName property of the BOModel | <Class> node is used to represent a business object with an image in the detail form and other UI elements. When the ImageName property is focused, the ellipsis button () is displayed to the right of the property value. You can click this button to invoke the Image gallery dialog and browse available images.

Note

  • Images from an external assembly are not displayed in the Image Gallery dialog when the Assembly Resource Image Source was added in the current model differences file. However, you still can type the ImageName property value manually.
  • To use an image from the DevExtreme Icon Library in your Mobile application, type the image name in the ImageName property manually.

Images can be specified directly in the Model Editor via the ImageName property of the required node (see the image above). However, there are ways to specify these images in code. For instance, you can apply the ImageNameAttribute to a business class. The image name specified as the attribute's parameter will be loaded to the ImageName property of the appropriate BOModel | <Class> node. The images representing Actions in a UI can be set in code via the ActionBase.ImageName property. The property value will be loaded to the ImageName property of the appropriate Action Design | Actions | Action node.

The following are the rules for setting an image name in the Model Editor and in code.

  • If an image (resource) is located in the folder that is specified by an Assembly Resource Image Source, set the image name in the following manner. ImageName (e.g. Department).
  • If an image (resource) is located in a subfolder of the folder specified by an Assembly Resource Image Source, set the image name in the following manner. SubfolderName.ImageName (e.g. MyBusinessClasses.Department).

Expanded See Also

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