Perceptual Color

initializetranslation.h
1// SPDX-FileCopyrightText: Lukas Sommer <sommerluk@gmail.com>
2// SPDX-License-Identifier: BSD-2-Clause OR MIT
3
4#ifndef INITIALIZETRANSLATION_H
5#define INITIALIZETRANSLATION_H
6
7#include <optional>
8
9#include <qglobal.h>
10#if (QT_VERSION >= QT_VERSION_CHECK(6, 0, 0))
11#include <qcontainerfwd.h>
12#else
13class QStringList;
14#endif
15
17
18/** @internal @file
19 *
20 * Provides the @ref PerceptualColor::initializeTranslation() function.
21 *
22 * @internal
23 *
24 * @todo Call <tt>
25 * <a href="https://doc.qt.io/qt-5/qmetatype.html#qRegisterMetaType-1">
26 * qRegisterMetaType()</a></tt> for all our data types during initialization!?
27 *
28 * @todo Provide an own documentation page for initialization and localization.
29 *
30 * @todo Investigate automatic initialization. We definitely
31 * need to call the @ref PerceptualColor::initializeTranslation()
32 * function, but having to call it manually might be
33 * cumbersome. It would be more comfortable if the initialization
34 * would happen automatically. Apparently, if we want to support both, SHARED
35 * <a href="https://www.volkerkrause.eu/2018/10/13/kf5-static-builds.html">
36 * and STATIC libraries, we have to</a>
37 * - either <a href="https://phabricator.kde.org/D13816">request the library
38 * user to call manually</a> @ref PerceptualColor::initializeTranslation()
39 * on both, STATIC and SHARED libraries. This gives us uniform behavior
40 * between STATIC and SHARED builds and makes bug-tracking easier.
41 * - or use <tt>
42 * <a href="http://doc.qt.io/qt-5/qcoreapplication.html#Q_COREAPP_STARTUP_FUNCTION">
43 * Q_COREAPP_STARTUP_FUNCTION</a></tt> to call
44 * @ref PerceptualColor::initializeTranslation() on SHARED
45 * libraries automatically when QCoreApplication starts (works
46 * only for SHARED libraries, and not for STATIC libraries, and
47 * and <a href="https://stackoverflow.com/questions/43333151"> there
48 * seems to be no workaround</a>) and request the library user to
49 * call @ref PerceptualColor::initializeTranslation() manually
50 * only on STATIC libraries.
51 * - or make @ref PerceptualColor::initializeTranslation() private and call it
52 * <a href="https://github.com/KDE/kitinerary/commit/72326ed">
53 * in our library code whenever our code is about to do
54 * something that requires previous initialization</a>. To not call it
55 * too often or call it within functions that are executed often, it
56 * might be better to call it in the constructor of <em>all</em> our classes
57 * that need previous initialization. This approach would be more comfortable
58 * for the library user. The disadvantage is that we have to pay attention
59 * to never use <tt>tr()</tt> without calling the initialization first, and
60 * forgetting about this might introduce subtile and difficult-to-discover
61 * bugs.
62 * - or make @ref PerceptualColor::initializeTranslation() private and
63 * use the solution that <a href="https://stackoverflow.com/a/1420261">
64 * instantiates a special class as global variable in every translation
65 * unit</a>, and this class makes sure that the initialization
66 * happens also for static libraries. But wouldn’t this mean that
67 * @ref PerceptualColor::initializeTranslation() is called at program
68 * startup, while still no QApplication object is available, and
69 * therefore our @ref PerceptualColor::initializeTranslation()
70 * function will crash? And anyway, when the QApplication object is
71 * destroyed and re-created, this pattern will not help. (Might
72 * https://doc.qt.io/qt-5/qglobalstatic.html#Q_GLOBAL_STATIC help?) See
73 * also https://isocpp.org/wiki/faq/ctors#static-init-order for useful
74 * information about static initialization.
75 *
76 * @todo Do not reload translations in one thread while another thread
77 * uses tr(). But how to make this sure, also because the library user
78 * could also reload its own translations while we are using tr(). At least,
79 * we could make sure our classes that use translations (widget classes but
80 * also @ref PerceptualColor::RgbColorSpace) cannot be instantiated outside
81 * of the main thread. But @ref PerceptualColor::RgbColorSpace is
82 * meant as thread-safe, so it would be strange if its constructor
83 * (and maybe the properties that return translated text) is
84 * the own function that is not thread-safe…
85 *
86 * @todo LocaleChange could be important for spin boxes to accept the new
87 * QLocale’s number format.
88 *
89 * @todo Catch QEvent::LayoutDirectionChange in all widgets? Or the signal
90 * QGuiApplication::layoutDirectionChanged()? */
91
92namespace PerceptualColor
93{
94
95void initializeTranslation(QCoreApplication *instance, std::optional<QStringList> newUiLanguages);
96
97} // namespace PerceptualColor
98
99#endif // INITIALIZETRANSLATION_H
The namespace of this library.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri May 24 2024 11:48:43 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.