|
|
[[_TOC_]]
|
|
|
|
|
|
## Coding style
|
|
|
|
|
|
KMyMoney uses KDE Frameworks style described here:
|
|
|
|
|
|
<https://techbase.kde.org/Policies/Frameworks_Coding_Style> <https://community.kde.org/Policies/Frameworks_Coding_Style>
|
|
|
|
|
|
## Overridden Qt types
|
|
|
|
|
|
KMyMoney has overridden some of the Qt types for our own convenience.
|
|
|
|
|
|
### `QSqlQuery` as `KMMSqlQuery`
|
|
|
|
|
|
`KMMSqlQuery` is a convenience class overridden to enable advanced SQL tracing for debugging purposes. Disabled by default, enabled with `ENABLE_SQLTRACER` [CMake switch](#cmake-switches).
|
|
|
|
|
|
### `QUrl` as `KMMUrl`
|
|
|
|
|
|
Makes `fromUserInput()` and `toLocalFile()` handle the Qt Resources URLs ("`qrc:/`").
|
|
|
|
|
|
###
|
|
|
|
|
|
## Icons
|
|
|
|
|
|
### Using icons in the code
|
|
|
|
|
|
1. `#include "icons/icons.h"`
|
|
|
2. Reference an icon of choice using `QIcon Icons::get(Icons::Icon icon)`, where `Icons::Icon icon` is a key value of one the `iconMappings` pre-defined in [icons.cpp](https://invent.kde.org/office/kmymoney/-/tree/master/kmymoney/icons/icons.cpp), e.g.:\
|
|
|
`ui->m_updateButton->setIcon(Icons::get(Icon::DialogOK));`
|
|
|
|
|
|
### Adding a new icon
|
|
|
|
|
|
1. Add a new entry to the `iconMappings` hash table in [icons.cpp](https://invent.kde.org/office/kmymoney/-/tree/master/kmymoney/icons/icons.cpp)
|
|
|
* Value must be a name of an icon from the [Breeze iconset](https://invent.kde.org/frameworks/breeze-icons/-/tree/master/icons)
|
|
|
* For the Key, think of a name that accurately describes an actual action in the context it will be used, as opposed to just mirroring the filename of the Breeze icon you chose to represent it. This in particular applies when you're being creative and repurpose an icon to use it out of its original context. For example, an entry for an action that downloads online statements for all accounts is defined as:\
|
|
|
`{Icon::AccountUpdate, QStringLiteral("edit-download")}`
|
|
|
* Such approach allows us to easily refactor it in the future, should we e.g. decide that `edit-download` doesn't really cut it and we want to work with Breeze VDG team to come up with a unique, non-generic icon for this action.
|
|
|
* That having said, some keys will naturally match the name of icons used, e.g.\
|
|
|
`{Icon::DialogOK, QStringLiteral("dialog-ok")}`.
|
|
|
* NOTE: it is OK if for several Keys to reference the same Breeze icon (have same value). It is also OK to add a placeholder Key and not reference any Breeze icon at all.
|
|
|
2. Copy the referenced Breeze icon(s) to the source code. The [copy_from_breeze.sh](https://invent.kde.org/office/kmymoney/-/blob/master/kmymoney/icons/copy_from_breeze.sh) script will do that automatically for both regular and dark icons:
|
|
|
* checkout out the [breeze-icons](https://invent.kde.org/frameworks/breeze-icons) repository
|
|
|
* `cd ~/sourcecode/kmymoney/icons` and run `./copy_from_breeze.sh ~/sourcecode/breeze-icons`
|
|
|
* this will not only copy your newly added icons, but may also potentially update some of the previously checked-in icons that had since been updated in `breeze-icons` repository by the KDE VDG team. In such case, `git add` and commit _your_ icons only, and consider filing a separate Merge Request to also update other icons.
|
|
|
|
|
|
### Packaging specifics
|
|
|
|
|
|
1. **5.1 stable branch**: depends on the platform and packaging:
|
|
|
* For macOS and Windows builds, packaged by Craft, we rely on Craft linking the binaries to the `KIconThemes` library, which, in turn, sources the upstream Breeze icons into `icontheme.rcc` and bundles it with the packages built.
|
|
|
* icon theme cannot be changed, hardcoded to Breeze
|
|
|
* the minGW cross-compiled Windows package does not ship binary `.rcc` file like Craft packages do, and relies on the icons provided in `kmymoney\icons`.
|
|
|
* icon theme cannot be changed, hardcoded to Breeze
|
|
|
* Currently broken, will be fixed by [!110](https://invent.kde.org/office/kmymoney/-/merge_requests/110)
|
|
|
* On Linux (including AppImage), we use icons shipped by the distribution
|
|
|
* icon theme can be changed, either in system settings or explicitly in the app's settings
|
|
|
* if Breeze icon theme is used, see https://bugs.kde.org/show_bug.cgi?id=440060
|
|
|
* this will be fixed by [!110](https://invent.kde.org/office/kmymoney/-/merge_requests/110),
|
|
|
2. **master branch**: embeds the Breeze icons using Qt Resources directly, as described [above](#adding-a-new-icon), and does _not_ rely on `icontheme.rcc` nor `kmymoney\icons`. This applies to all platforms. On macOS and Windows, the icon theme cannot be changed and is hardcoded to Breeze. |