Skip to main content

Resources (xtd.core)

When you create an application, you often need external resources such as images, icons, sounds or documents to accompany it. In general, for a GUI application, you use an icon associated with the main window. You may also want to add one or more images to enhance the visual or functional aspects of your application. This is where resources come in. In fact, thanks to its ultra-simplified resource management, xtd provides easy access to your resources. Through an automatically-generated static class, you can access your resources without worrying about their location, which may differ depending on the platform used.

Resources declaration​

In general, the best way to add resources is to create a resources folder next to the src folder. Copy your resources files into this folder. Then, using CMake commands specific to xtd, simply describe the resources to be added to your application.

Although you can add the resource command (which is the only command for adding a resource) in your CMakeLists.txt file, the best thing to do is to create a properties folder next to the src folder and describe your resources in the resources.cmake file. When CMake generates your xtd project, the properties/resources.cmake file will be detected automatically.

Below is an example of the properties/resources.cmake file with some specific CMake commands to describe your resources.

properties/resources.cmake​

# Resources file
# ==============

# Remarks
# This file generates the "properties/resources.hpp" file, which is used to access the resources.

# Icons
resource(xtd_forms "resources/xtd_forms.ico")

# Pictures
resource(gammasoft "resources/gammasoft.png")
resource(xtd "resources/xtd.gif")

# Documents
resource(information "resources/information.txt")
resource(readme "resources/readme.md")

# Sounds
resource(sound "resources/sound.wav")

Resources CMake Commands​

resource​

resource(NAME FILE)
  • Description Add resources to current project.
  • NAME param The resource name to add. This will be the name of the property in the generated static resources class your_project::properties::resources.
  • FILE param The resource file path.
  • remarks
    • This method can be called multiple times in the same project.
    • This method must be called before target_type().
    • This method is optional.
  • See resource command
  • See CMake commands

Resources generation​

Generating your xtd project with CMake will automatically generate a static class your_project::properties::resources containing the static properties for accessing resources. The resources class will be generated in the propertes/resources.hpp file. And this file will be automatically added to your project as a source.

properties/resources.hpp​

#pragma region xtd generated code
// This code was generated by CMake script.
//
// Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.

#pragma once

#include <xtd/drawing/bitmap>
#include <xtd/drawing/icon>
#include <xtd/io/binary_reader>
#include <xtd/io/file_info>
#include <xtd/io/path>
#include <xtd/environment>
#include <xtd/not_implemented_exception>
#include <xtd/string>

namespace your_project::properties {
  /// @brief A strongly-typed resource class, for looking up localized strings, etc.
  /// @details This class was auto-generated by CMake script. To add or remove a member, edit your CMakeList.txt or properties/resources.cmake file then rerun cmake tools.
  /// @remarks See [Resources](https://gammasoft71.github.io/xtd/docs/documentation/guides/xtd.core/resources) for more informations.
  class resources final static_ {
  public:
    /// @name Public Static Properties

    /// @{
    /// @brief Looks up a localized resource of type xtd::drawing::icon.
    static const xtd::drawing::icon& xtd_forms() {
      static auto icon = xtd::drawing::icon {xtd::io::path::combine(xtd::environment::get_folder_path(xtd::environment::special_folder::application_resources), "xtd_forms.ico")};
      return icon;
    }

    /// @brief Looks up a localized resource of type xtd::drawing::bitmap.
    static const xtd::drawing::bitmap& gammasoft() {
      static auto bitmap = xtd::drawing::bitmap {xtd::io::path::combine(xtd::environment::get_folder_path(xtd::environment::special_folder::application_resources), "gammasoft.png")};
      return bitmap;
    }

    /// @brief Looks up a localized resource of type xtd::drawing::bitmap.
    static const xtd::drawing::bitmap& xtd() {
      static auto bitmap = xtd::drawing::bitmap {xtd::io::path::combine(xtd::environment::get_folder_path(xtd::environment::special_folder::application_resources), "xtd.gif")};
      return bitmap;
    }

    /// @brief Looks up a localized resource of type xtd::string.
    static const xtd::string& information() {
      static auto text = xtd::io::file::read_all_text(xtd::io::path::combine(xtd::environment::get_folder_path(xtd::environment::special_folder::application_resources), "information.txt"));
      return text;
    }

    /// @brief Looks up a localized resource of type xtd::string.
    static const xtd::string& readme() {
      static auto text = xtd::io::file::read_all_text(xtd::io::path::combine(xtd::environment::get_folder_path(xtd::environment::special_folder::application_resources), "readme.md"));
      return text;
    }

    /// @brief Looks up a localized resource of type xtd::forms::sound.
    static const xtd::object& sound() {
      xtd::helpers::throw_helper::throws(xtd::helpers::exception_case::not_implemented);
    }

    /// @}
  };
}

#pragma endregion

Resources usage​

All that's left is to exploit your resources in a way that's simple and transparent to your environment and OS. Just include the inlcude file propertes/resources.hpp and use its properties. By the way, a resource is always read-only.

your_project.cpp​

#include "../properties/resources.hpp"
#include <xtd/xtd>

namespace your_project {
  class form1 : public xtd::forms::form {
  public:
    form1() {
      // Initialising form1 control.
      text("form1");
      client_size({800, 450});
      
      // Initialising main_tab_control control.
      main_tab_control.dock(xtd::forms::dock_style::fill).parent(*this);
      main_tab_control.tab_pages().push_back("Information");
      main_tab_control.tab_pages().push_back("Gammasoft");
      main_tab_control.tab_pages().push_back("Read me");
      main_tab_control.tab_pages().push_back("xtd");
      
      // Initialising information_label control.
      information_label.parent(main_tab_control.tab_pages()[0]);
      information_label.dock(xtd::forms::dock_style::fill);
      
      // Initialising gammasoft_picture_box control.
      gammasoft_picture_box.parent(main_tab_control.tab_pages()[1]);
      gammasoft_picture_box.dock(xtd::forms::dock_style::fill);
      gammasoft_picture_box.size_mode(picture_box_size_mode::center_image);

      // Initialising readme_label control.
      readme_label.parent(main_tab_control.tab_pages()[2]);
      readme_label.dock(xtd::forms::dock_style::fill);
      
      // Initialising xtd_picture_box control.
      xtd_picture_box.parent(main_tab_control.tab_pages()[3]);
      xtd_picture_box.dock(xtd::forms::dock_style::fill);
      xtd_picture_box.size_mode(picture_box_size_mode::center_image);
      
      // Filling controls from resources
      information_label.text(properties::resources::information());
      gammasoft_picture_box.image(properties::resources::gammasoft());
      readme_label.text(properties::resources::readme());
      xtd_picture_box.image(properties::resources::xtd());
    }
    
    static auto main() -> void {
      application::run(form1 {});
    }
    
  private:
    tab_control main_tab_control;
    label information_label;
    picture_box gammasoft_picture_box;
    label readme_label;
    picture_box xtd_picture_box;
  };
}

startup_(your_project::form1::main);

Resources types​

xtd resources can handle different types of resources: audio, icons, images and text.

Audio​

FormatFile extensions
Wave.wav

Icon​

FormatFile extensions
Window icon.ico
macOS icon.icns

Image​

FormatFile extensions
ANImation.ani
BitMaP.bmp
CURsor.cur
Embeded Map File.emf
Exchangeable Image File Format.exif
Graphics Interchange Format.gif
Intuit Interchange Format.iif
JPEG file.jpg
JPEG file.jpeg
apple PiCTure.pct
PCX file.pcx
apple PICTure.pict
Portable Network Graphics.png
Portable aNy Map.pnm
Portable PixMap.ppm
TGA file.tga
Tag Image File format.tif
Tag Image File Format.tiff
Windows MetaFile.wmf
X BitMap.xbm
X PixMap.xpm

Text​

FormatFile extensions
MarkDown.md
TeXT.txt
TEXT.text

Remarks​

  • If you add a resource whose extension is not known, the resource will automatically be converted to an array of bytes xtd::array<xtd::byte>.
  • If you pass an invalid filename or a checmin that is erroneous or not present, project generation will fail on the problematic line.
  • If you don't add a resource command to your CMakeLists.txt and don't add a properties/resources.cmake file, then xtd won't generate anything.
  • The simplified use of xtd resources is totally optional. You can use your own method.

Examples​

Some xtd examples use resources :

and more see xtd.examples.

See also

​