[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]Office File API
[Expand]Reporting
[Expand]Report and Dashboard 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
    Ways to Access UI Elements and Their Controls
    Add and Override Images
    Text Notifications
    Ways to Show a Confirmation Dialog
    ASP.NET Web Application Appearance
    Ways to Customize a Mobile Application
    Application Personalization
    Using a Custom Control that is not Integrated by Default
    XAF Mobile Wrappers for DevExtreme Widgets
   [Expand]Splash Forms
  [Expand]Controllers and Actions
  [Expand]Data Manipulation and Business Logic
  [Expand]Security System
  [Expand]Localization
  [Expand]System Module
  [Expand]Extra Modules
  [Expand]Debugging, Testing and Error Handling
  [Expand]Filtering
  [Expand]Application Life Cycle
 [Expand]Design-Time Features
 [Expand]Deployment
 [Expand]Task-Based Help
  Frequently Asked Questions (FAQ)
 [Expand]API Reference
[Expand]eXpress Persistent Objects
[Expand]CodeRush
[Expand]CodeRush Classic
[Expand]Cross-Platform Core Libraries
[Expand]Tools and Utilities
 End-User Documentation
View this topic on docs.devexpress.com (Learn more)

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.

Expanded Images Concept Overview

In XAF, there are three 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.

  • DevExpress.Images Assembly Resource Image Source

    This default source provides access to all images from the DevExpress.Images assembly.

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. The following image demonstrates the auto-generated image sources from which images are loaded to the Windows Forms version of the Main Demo.

The following image sources are available:

  • 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 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 automatically generated for the Images folder located in the referenced assembly.

  • 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.Images.v19.1: Assembly Resource Image Source

    This image source is generated for the DevExpress.Images.dll assembly WinForms, ASP.NET and Mobile application projects reference. Images from this image source are installed as separate files into the %PROGRAMFILES(x86)%\DevExpress 19.1\Components\Sources\DevExpress.Images\Images folder. 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.

  • The DevExpress.Images Resource Image Source for the DevExpress.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

Supported Image File Formats

All XAF applications support raster images and SVG images (recommended for High DPI screens). To enable SVG images in a WinForms application, set the UseSvgImages (see ImageLoader.UseSvgImages) property to true.

The recommended raster image format is PNG. However, you can use other raster image file formats like JPG, BMP, etc.

Raster Image Size Guidelines

Image size Image suffix Platform Description
12x12 "12x12" ASP.NET Used by Web Property Editors (see PropertyEditor) in Classic Web UI.
16x16 none WinForms, ASP.NET Standard-sized images used for Business Classes.
24x24 "24x24" ASP.NET Used in New Web UI for menu items. If the image is not available, XAF uses a 16x16 image.
32x32 "32x32" WinForms, Mobile Used as Large Icons in the Navigation Bar and Ribbon UI (WinForms), and used for Business Classes in Mobile applications.
48x48 "48x48" WinForms, ASP.NET Used by the Validation Module (WinForms) and in dialog windows (ASP.NET).

SVG Image Sizing

In ASP.NET and Mobile applications the viewBox attribute determines SVG images' display size. SVG icons are always resized to fit a specific position in a UI. In WinForms applications, an SVG image size is determined by a control or set in the Model Editor.

Naming Images

Image Names Guidelines

Follow the guidelines below when naming new images in C# projects.

Image Name Description
Employee.png Do not include a size suffix for 16x16 raster images.
Employee_32x32.png Add a size suffix to 12x12, 24x24, 32x32 and 48x48 raster images.
Office2013\Employee.png Raster images are loaded from the DevExpress.Images's Colored collection. To use images from other collections, add its name without spaces to an image name as prefix.
Employee.svg SVG images.
Employee_Active.svg Add the Active suffix to SVG images intended for selected navigation items in ASP.NET applications.
Employee_Disabled.svg Add the Disabled suffix to show a grayed-out image for disabled Actions in ASP.NET applications. Mobile applications do not support disabled Actions.
Important

You should also add the current module assembly name and the folder name to the image's name in VB.NET projects: MySolution.Module.Images.Employee.png, MySolution.Module.Images.Employee_Active.svg. For images to work correctly in XAF, capitalize "Images" in the the image file's name.

Using Images in XAF Applications

Two PNG images represent a business class in a UI: ImageName.png and ImageName_32x32.png. Use one SVG image (ImageName.svg) for a business class if you want to use vector images. ASP.NET applications may require two more SVG images - for the icon's active and disabled states.

Note

We recommend that you embed custom images into assemblies as resources to use them in an XAF application. When you use image files, the filename should be less than 260 characters. This can cause an issue if you use ClickOnce deployment because it creates long paths when you install an application. In this case, if the path to an image is longer than 260 characters, the image is not available in the application and a corresponding entry is created in the application Log File.

Expanded Set Images

To enable images for the Navigation System and Tabbed MDI tabs, set the IModelRootNavigationItems.ShowImages and IModelOptionsWin.ShowTabImage properties to true. You can also use the IModelLayoutManagerOptions.EnableLayoutGroupImages property to enable images for tabbed layout groups.

The Application Model displays the ImageName property for UI elements that can show images. 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 Picker dialog and browse available images.

Note

  • The Image Picker does not display images from a custom image source if an Assembly Resource Image Source was added in the same model differences file. However, you 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. Add the "devextreme" prefix to the image name if this name coincides with a name of an image from the DevExpress.Images assembly (for example, For example, "devextereme\edit").

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 is 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 (for example, 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

Is this topic helpful?​​​​​​​