xtd::forms::settings Class Reference

Inheritance diagram for xtd::forms::settings:

Definition

Represent settings associate to the application.

Header

#include <xtd/configuration/settings>

Namespace

xtd

Library

xtd.core

Remarks

The basic settings path can be obtained with the command : xtd::environment::get_know_folder_path(xtd::environment::special_folder::application_data);.

On Windows settings are stored in /Users/($USER)/AppData/Roaming/company_name/product_name.ini file.

On macos settings are stored in ~/Library/Preferences/company_name/product_name Preferences file.

On linux settings are stored in ~/.config/company_name/product_name.conf file.

The product_name is equal to the xtd::reflection::assembly::product() property of the xtd::reflection::assembly::get_executing_assembly() assembly if not empty; otherwise is equal to the filename of the first arguemnt of main.

The company_name is equal to the xtd::reflection::assembly::company() property of the xtd::reflection::assembly::get_executing_assembly() assembly if not empty; otherwise is equal to product_name.

Examples

The following code example demonstrates the use of xtd::configuration::settings class with CMake setting commands.

• application_Settings.cpp :

#include "../properties/settings.hpp"
#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/color_picker>
#include <xtd/forms/form>
 
using namespace application_settings::properties;
using namespace xtd::forms;
 
auto main() -> int {
  auto main_form = form::create(settings::default_settings().text(), form_start_position::manual);
  
  auto back_color_picker = color_picker::create(main_form, main_form.back_color(), {10, 10}, {75, 25});
  back_color_picker.color_picker_changed += [&] {
    main_form.back_color(back_color_picker.color());
  };
  
  auto save_button = button::create(main_form, "&Save", {90, 10});
  save_button.click += [&] {
    settings::default_settings().size(main_form.client_size());
    settings::default_settings().location(main_form.location());
    settings::default_settings().back_color(main_form.back_color());
    settings::default_settings().save();
  };
  
  auto reload_button = button::create(main_form, "&Reload", {170, 10});
  reload_button.click += [&] {
    main_form.client_size(settings::default_settings().size());
    main_form.location(settings::default_settings().location());
    main_form.back_color(settings::default_settings().back_color());
    back_color_picker.color(settings::default_settings().back_color());
  };
  
  auto reset_button = button::create(main_form, "R&eset", {250, 10});
  reset_button.click += [&] {
    settings::default_settings().reset();
    reload_button.perform_click();
  };
  
  reload_button.perform_click();
  
  application::run(main_form);
}

• properties/settings.cmake :

setting_include(xtd/drawing/point)
setting_include(xtd/drawing/size)
setting_include(xtd/drawing/system_colors)
setting(back_color xtd::drawing::color USER "xtd::drawing::system_colors::control()")
setting(location xtd::drawing::point USER "{100, 50}")
setting(size xtd::drawing::size USER "{335, 45}")
setting(text xtd::string APPLICATION "\"Settings example\"")

• The generated properties/settings.h :

#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/point>
#include <xtd/drawing/size>
#include <xtd/drawing/system_colors>
#include <xtd/configuration/settings>
 
namespace application_settings::properties {
  // @brief A strongly typed settings class, for storing user and system settings
  // @details This class was auto-generated by CMake script. To add or remove a member, edit your CMakeList.txt or properties/settings.cmake file then rerun cmake tools.
  // @remarks See [Settings](https://gammasoft71.github.io/xtd/docs/documentation/guides/xtd.core/settings) for more informations.
  class settings : public xtd::object {
  public:
    // @name Public Constructors
 
    // @{
    // @brief Initializes a new instance of the application_settings::properties::settings class.
    // @remarks All properties are reloaded with the last saved value.
    settings() noexcept : settings {true} {}
    // @brief Initializes a new instance of the application_settings::properties::settings class.
    // @param load If `true` all properties are reloaded with the last saved values; otherwise none.
    explicit settings(bool load) noexcept {
      if (load) reload();
    }
    // @}
 
    // cond
    settings(settings&&) noexcept = default;
    settings(const settings&) noexcept = default;
    settings& operator =(const settings&) noexcept = default;
    // endcond
 
    // @name Public Properties
 
    // @{
    // @brief Gets the back_color user setting property.
    // @return A xtd::drawing::color value.
    xtd::drawing::color back_color() const noexcept {return back_color_;}
    // @brief Sets the back_color user setting property.
    // @param value A xtd::drawing::color value.
    settings& back_color(xtd::drawing::color value) noexcept {
      back_color_ = value;
      return *this;
    }
 
    // @brief Gets the location user setting property.
    // @return A xtd::drawing::point value.
    xtd::drawing::point location() const noexcept {return location_;}
    // @brief Sets the location user setting property.
    // @param value A xtd::drawing::point value.
    settings& location(xtd::drawing::point value) noexcept {
      location_ = value;
      return *this;
    }
 
    // @brief Gets the size user setting property.
    // @return A xtd::drawing::size value.
    xtd::drawing::size size() const noexcept {return size_;}
    // @brief Sets the size user setting property.
    // @param value A xtd::drawing::size value.
    settings& size(xtd::drawing::size value) noexcept {
      size_ = value;
      return *this;
    }
 
    // @brief Gets the text system setting property.
    // @return A xtd::string value.
    xtd::string text() const noexcept {return "Settings example";}
 
    // @}
 
    // @name Public Methods
 
    // @{
    // @brief Reload all properties with the last saved values.
    // @remarks See [Settings](https://gammasoft71.github.io/xtd/docs/documentation/guides/xtd.core/settings) for more informations.
    void reload() noexcept {
      back_color_ = settings_.read("back_color", back_color_);
      location_ = settings_.read("location", location_);
      size_ = settings_.read("size", size_);
    }
 
    // @brief Reset all properties to their default values.
    // @remarks See [Settings](https://gammasoft71.github.io/xtd/docs/documentation/guides/xtd.core/settings) for more informations.
    void reset() noexcept {
      settings_.reset();
      *this = settings {false};
    }
 
    // @brief Save all properties.
    // @remarks See [Settings](https://gammasoft71.github.io/xtd/docs/documentation/guides/xtd.core/settings) for more informations.
    void save() noexcept {
      settings_.write("back_color", back_color_);
      settings_.write("location", location_);
      settings_.write("size", size_);
      settings_.save();
    }
    // @}
 
    // @name Public Static Properties
 
    // @{
    // @brief Gets the default instance of settings.
    // @return The default instance.
    // @remarks At the first call all properties are reloaded with the last saved values.
    static settings& default_settings() noexcept {
      static auto default_settings = settings {};
      return default_settings;
    }
    // @}
 
  private:
    xtd::configuration::settings settings_;
    xtd::drawing::color back_color_ {xtd::drawing::system_colors::control()};
    xtd::drawing::point location_ {{100, 50}};
    xtd::drawing::size size_ {{335, 45}};
  };
}
 
#pragma endregion

The following code example demonstrates the use of xtd::configuration::settings class without CMake setting commands.

#include <xtd/configuration/settings>
#include <xtd/forms/application>
#include <xtd/forms/button>
#include <xtd/forms/color_picker>
#include <xtd/forms/form>
 
using namespace xtd::drawing;
using namespace xtd::forms;
 
auto main() -> int {
  auto settings = xtd::configuration::settings {};
  auto main_form = form::create("Settings example", form_start_position::manual);
  
  auto back_color_picker = color_picker::create(main_form, main_form.back_color(), {10, 10}, {75, 25});
  back_color_picker.color_picker_changed += [&] {
    main_form.back_color(back_color_picker.color());
  };
  
  auto save_button = button::create(main_form, "&Save", {90, 10});
  save_button.click += [&] {
    settings.write("size", main_form.client_size());
    settings.write("location", main_form.location());
    settings.write("back_color", main_form.back_color());
    settings.save();
  };
  
  auto reload_button = button::create(main_form, "&Reload", {170, 10});
  reload_button.click += [&] {
    main_form.client_size(settings.read("size", drawing::size {335, 45}));
    main_form.location(settings.read("location", point {100, 50}));
    main_form.back_color(settings.read("back_color", main_form.back_color()));
    back_color_picker.color(main_form.back_color());
  };
  
  auto reset_button = button::create(main_form, "R&eset", {250, 10});
  reset_button.click += [&] {
    settings.reset();
    reload_button.perform_click();
  };
  
  reload_button.perform_click();
  
  application::run(main_form);
}

Public Constructors
	settings ()
	Initializes a new instance of settings class.

Public Properties
const xtd::string &	file_path () const noexcept
	Gets the file path of the application settings.

Public Methods
xtd::string	read (const xtd::string &key, const xtd::string &default_value)
	Reads a value for specified key. If not found default value is used.
template<class type_t>
type_t	read (const xtd::string &key, const type_t &default_value)
	Reads a value for specified key. If not found default value is used.
void	reset ()
	Reset application settings.
void	save ()
	Save application settings.
void	write (const xtd::string &key, const xtd::string &value)
	Writes a specified value for specified key.
template<class type_t>
void	write (const xtd::string &key, type_t &&value)
	Writes a specified value for specified key.

Additional Inherited Members
	object ()=default
	Create a new instance of the ultimate base class object.
virtual bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual xtd::size	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<class object_t>
xtd::unique_ptr_object< object_t >	memberwise_clone () const
	Creates a shallow copy of the current object.
virtual xtd::string	to_string () const noexcept
	Returns a xtd::string that represents the current object.
template<class object_a_t, class object_b_t>
static bool	equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are considered equal.
template<class object_a_t, class object_b_t>
static bool	reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
	Determines whether the specified object instances are the same instance.

Constructor & Destructor Documentation

settings()

xtd::configuration::settings::settings

(

)

Initializes a new instance of settings class.

Member Function Documentation

file_path()

const xtd::string & xtd::configuration::settings::file_path ( ) const

noexcept

Gets the file path of the application settings.

Returns

The file path of the application settings.

Remarks

The basic settings path can be obtained with the command : xtd::environment::get_know_folder_path(xtd::environment::special_folder::application_data);.

On Windows settings are stored in /Users/($USER)/AppData/Roaming/company_name/product_name.ini file.

On macos settings are stored in ~/Library/Preferences/company_name/product_name Preferences file.

On linux settings are stored in ~/.consig/company_name/product_name.conf file.

The product_name is equal to the xtd::reflection::assembly::product() property of the xtd::reflection::assembly::get_executing_assembly() assembly if not empty; otherwise is equal to the filename of the first arguemnt of main.

The company_name is equal to the xtd::reflection::assembly::company() property of the xtd::reflection::assembly::get_executing_assembly() assembly if not empty; otherwise is equal to product_name.

Warning

Don't manipulate the file yourself, otherwise the expected result may be undefined.

read() [1/2]

xtd::string xtd::configuration::settings::read	(	const xtd::string &	key,
		const xtd::string &	default_value )

Reads a value for specified key. If not found default value is used.

Parameters

key	The key used to read a value.
default_value	A string used if value not found.

Returns

A string that represent the value associate to the key.

read() [2/2]

template<class type_t>

type_t xtd::configuration::settings::read ( const xtd::string & key, const type_t & default_value )

inline

Reads a value for specified key. If not found default value is used.

Template Parameters

type_t

The type of value to read.

Parameters

key	The key used to read a value.
default_value	A string used if value not found.

Returns

A type_t that represent the value associate to the key.

reset()

void xtd::configuration::settings::reset

(

)

Reset application settings.

Remarks

The settings are cleared and the application settings file is removed.

To write permanently use the xtd::configuration::settings::save method.

save()

void xtd::configuration::settings::save

(

)

Save application settings.

Remarks

The settings are saved in the application settings file.

write() [1/2]

void xtd::configuration::settings::write	(	const xtd::string &	key,
		const xtd::string &	value )

Writes a specified value for specified key.

Parameters

key	The key used to write a value.
value	A string to write.

Remarks

To write permanently use the xtd::configuration::settings::save method.

write() [2/2]

template<class type_t>

void xtd::configuration::settings::write ( const xtd::string & key, type_t && value )

inline

Writes a specified value for specified key.

Template Parameters

type_t

The type of value to write.

Parameters

key	The key used to write a value.
value	A type_t to write.

Remarks

To write permanently use the xtd::configuration::settings::save method.

---

The documentation for this class was generated from the following file:

• xtd.core/include/xtd/configuration/settings.hpp