Step 1: add setting to definition map
File: Telegram/SourceFiles/kotato/kotato_settings.cpp
Find the following:
const std::map<QString, Definition, std::greater<QString>> DefinitionMap
and add new definition to it:
{ "my_custom_setting", {
.scope = SettingScope::Global,
.storage = SettingStorage::MainJson,
.type = SettingType::BoolSetting,
.defaultValue = false,
.fillerValue = false,
.limitHandler = nullptr }},
- key (in this example
"my_custom_setting",QString): this is the name of option that will be used both in code and in JSON file. scope(enum SettingScope):SettingScope::Globalwill apply setting to all accounts,SettingScope::Accountwill apply to current account only. If not set,SettingScope::Globalis assumed.storage(enum SettingStorage):SettingStorage::MainJsonwill save it to JSON settings file,SettingStorage::Nonecan be used in app, but changes won't be saved. If not set,SettingStorage::MainJsonis assumed.type(enum SettingType): valuesSettingType::BoolSetting,SettingType::IntSetting,SettingType::QStringSetting,SettingType::QJsonArraySettingresemble the typesbool,int,QStringandQJsonArray. If not set,SettingType::BoolSettingis assumed.defaultValue(QVariant): sets default value that will be used if it wasn't set earlier. Will be null if it's not set.fillerValue(QVariant): used in default settings file as an example. If not set, it will usedefaultValue.limitHandler(CheckHandler, defined asFn<QVariant(QVariant)>): this function takes user-provided value (QVariant) and returns filtered version of this value (QVariant). If it'snullptr, only basic type will be checked. If not set,nullptris assumed.
Handler generators
Some handler generator functions that you can use as an example or value:
CheckHandler IntLimit(int min, int max, int defaultValue)
IntLimit generates handler that sets number to min if it's lower than min, and sets number to max if it's higher than max. If value can't be converted to int, sets it to defaultValue.
inline CheckHandler IntLimit(int min, int max)
Same IntLimit as previous one, but uses min instead of defaultValue.
CheckHandler IntLimitMin(int min)
Version of IntLimit that limits only from one side: it sets number to min if it's lower than min. If value can't be converted to int, sets it to min.
CheckHandler ScalesLimit()
Handler generator used specifically in "scales" option. Limits array to 6 values, and scales to range from style::kScaleMin to style::kScaleMax.
CheckHandler ReplacesLimit()
Handler generator used specifically in "replaces" option. Checks if sub-values are QJsonArray's with two QString elements (from, to).
CheckHandler FileDialogLimit()
Handler generator used specifically in "file_dialog_type" option. Converts integer values to Platform::FileDialog::ImplementationType enum.
CheckHandler NetSpeedBoostConv(CheckHandler wrapped = nullptr)
Handler generator used specifically in "net_speed_boost" option. Maps string values (low, medium, high) to integer values. wrapped used as post-filter. In "net_speed_boost" it's used NetSpeedBoostConv(IntLimit(0, 3)).
Step 2: use your option in code
First, you must include settings header file, if it's not included:
#include "kotato/kotato_settings.h"
Getting the value
To get the value, you can use this:
::Kotato::JsonSettings::Get("my_custom_setting")
There are also two additonal parameters: account id (uint64, default is 0, which means "all accounts"), and "is test server" (bool, default is false, but it is used only when account id is not 0).
Example for account id 777 on test server:
::Kotato::JsonSettings::Get("my_custom_setting", 777, true)
Example for account id 555 on production server:
::Kotato::JsonSettings::Get("my_custom_setting", 555)
or
::Kotato::JsonSettings::Get("my_custom_setting", 555, false)
Usually you don't need to set those by hand, these examples are just for demonstration.
Get function caveat
There's the one caveat. ::Kotato::JsonSettings::Get, returns QVariant, so to use it correctly you should use QVariant's methods .toBool(), .toInt(), .toString() and .toJsonArray(), depending on type. You can also use shorthand methods:
::Kotato::JsonSettings::GetBool("my_custom_setting"); // returns bool
::Kotato::JsonSettings::GetInt("my_custom_setting"); // returns int
::Kotato::JsonSettings::GetString("my_custom_setting"); // returns QString
::Kotato::JsonSettings::GetJsonArray("my_custom_setting"); // returns QJsonArray
Parameters are the same as in original Get, only difference is that shorthands return type you need.
Setting the value
To set an option you can use a following method:
::Kotato::JsonSettings::Set("my_custom_setting", true);
In that case true is the value (QVariant). QVariant will accept any supported value.
Warning!
Setis not doing type checks, so it's the developer responsiblity to use the correct type. You have been warned.
Set also supports account id and test server check parameters, explained in "Getting the value":
::Kotato::JsonSettings::Set("my_custom_setting", true /* value */, 777 /* account id */, true /* is test server */);
Don't forget to save your options after you've changed them:
::Kotato::JsonSettings::Write();
If called multiple times in short period of time, writing to file is delayed for 5 seconds to reduce file I/O operations, unless app is restarting.
Resetting the value to default
To reset an option you can use a following method:
::Kotato::JsonSettings::Reset("my_custom_setting");
Like with Set, account id and test server check parameters are also supported:
::Kotato::JsonSettings::Reset("my_custom_setting", 777 /* account id */, true /* is test server */);
Don't forget to save your options after you've changed them:
::Kotato::JsonSettings::Write();
After-restart options
Some options must be applied only after restart, because there are too many dependencies to change it on the go.
To set an option after restart you can use a following method:
::Kotato::JsonSettings::SetAfterRestart("my_custom_setting", true);
Reset also has AfterRestart version:
::Kotato::JsonSettings::ResetAfterRestart("my_custom_setting");
Note that Get method (along with shorthands) will return the value that was loaded on app start. If you want to know what value will be applied after restart, you can use GetWithPending method:
::Kotato::JsonSettings::GetWithPending("my_custom_setting");
Note that it returns QVariant that is needed to convert. Instead of that, you can use shorthands:
::Kotato::JsonSettings::GetBoolWithPending("my_custom_setting"); // returns bool
::Kotato::JsonSettings::GetIntWithPending("my_custom_setting"); // returns int
::Kotato::JsonSettings::GetStringWithPending("my_custom_setting"); // returns QString
::Kotato::JsonSettings::GetJsonArrayWithPending("my_custom_setting"); // returns QJsonArray
Account id and test server check parameters are also supported in all these methods.
RPL
TDesktop heavily relies on self-written RPL library. This library allows to listen to events, and do actions in widgets after they're triggered.
While RPL itself is out of scope of this page, there are methods that you can use.
::Kotato::JsonSettings::Events("my_custom_setting") // returns rpl::producer<QString>
This method, combined with, for example, rpl::start_with_next, will allow to run actions after it's changed. Actual implementation may be harder, so it's better to study code that already uses RPL. Also note that QString is not a value: it's a combined settings map key. Value should be obtained yourself by calling Get or GetWithPending (or their shorthands).
Events also supports account id and test server check parameters, explained in "Getting the value":
::Kotato::JsonSettings::Events("my_custom_setting", 777 /* account id */, true /* is test server */);
::Kotato::JsonSettings::RestartEvents() // returns rpl::producer<bool>
Triggers when SetAfterRestart/ResetAfterRestart is used. Contained value shows if restart is needed: true: needs restart, false: doesn't need restart.
This function is currently unused and may be changed or removed.
English
Русский