kdenlive/dev-docs/coding.md

0001 # Coding and Resources
0002
0003 * Qt5
0004   * [All Qt5 classes][qt5c]
0005   * [Signals and Slots][qt-sig]
0006 * [MLT introduction][mlt-intro].
0007 * [The KDE Frameworks][kf]
0008   * [XMLGUI Technology][xmlgui-tut] (e.g. for the `kdenliveui.rc` file)
0009
0010
0011 ## Locale handling
0012
0013 Locales are important e.g. for formatting numbers in a way that the user is
0014 familiar with. Some countries would write `12500.42` as `12.000,42`, for
0015 example.
0016
0017 Since 20.08, Kdenlive follows the following rules:
0018
0019 * When parsing data (by Kdenlive or by other libraries like MLT), **the `C`
0020   locale is used.** This is especially important for project files. The reason
0021   is that for passing data between programs, the format has to be well-defined
0022   and *not* depend on where the user happens to live.
0023 * When presenting data to the user, the user’s locale is used.
0024
0025 MLT uses the C locale which is set by `setlocale()` and which must be set to
0026 `C`. If it is set to e.g. `hu_HU.utf-8`, which uses `,` as decimal separator,
0027 properties are converted to this format upon saving the project file, and the
0028 project file ends up corrupted.
0029
0030 In Kdenlive, `QLocale` should only be used in one case: when data is shown to
0031 the user or read from the user. Usually that is handled by Qt already. A
0032 `QDoubleSpinBox`, for example, presents the double value in the user’s local
0033 number format.
0034
0035
0036 ## Configuration
0037
0038 Named settings are stored in [`kdenlivesettings.kcfg`][sett]. To add a new
0039 setting with default value, add an entry in the settings file, for example:
0040
0041 ```xml
0042 <entry name="logscale" type="Bool">
0043   <label>Use logarithmic scale</label>
0044   <default>true</default>
0045 </entry>
0046 ```
0047
0048 The setting can then be read and written as follows:
0049
0050 ```cpp
0051 // Read
0052 bool logScale = KdenliveSettings::logscale();
0053
0054 // Write
0055 KdenliveSettings::setLogscale(true);
0056 ```
0057
0058 ## Effects and Transitions
0059 Effects and Transitions are stored in subfolders of the  [`data`][data] folder.
0060 For a detailed description see [here][effect-readme].
0061
0062 [sett]: ../src/kdenlivesettings.kcfg
0063 [data]: ../data/
0064 [effect-readme]: ../data/README.md
0065 [mlt-intro]: mlt-intro.md
0066 [qt5c]: https://doc.qt.io/qt-5/classes.html
0067 [qt-sig]: https://doc.qt.io/qt-5/signalsandslots.html
0068 [kf]: https://api.kde.org/frameworks-api/frameworks-apidocs/frameworks/index.html
0069 [xmlgui-tut]: https://techbase.kde.org/Development/Architecture/KDE4/XMLGUI_Technology