1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2012 Benjamin Port <benjamin.port@ben2367.fr>
4
5 SPDX-License-Identifier: LGPL-2.1-only OR LGPL-3.0-only OR LicenseRef-KDE-Accepted-LGPL
6*/
7
8#ifndef KWINDOWCONFIG_H
9#define KWINDOWCONFIG_H
10
11#include <kconfiggroup.h>
12#include <kconfiggui_export.h>
13
14class QWindow;
15class QScreen;
16
17/*!
18 * \namespace KWindowConfig
19 * \inmodule KConfigGui
20 *
21 * \brief Save and load window sizes into a config.
22 */
23namespace KWindowConfig
24{
25/*!
26 * Saves the window's size dependent on the screen dimension either to the
27 * global or application config file.
28 *
29 * \note the group must be set before calling
30 *
31 * \a window The window to save size.
32 *
33 * \a config The config group to read from.
34 *
35 * \a options passed to KConfigGroup::writeEntry()
36 *
37 * \since 5.0
38 */
39KCONFIGGUI_EXPORT void saveWindowSize(const QWindow *window, KConfigGroup &config, KConfigGroup::WriteConfigFlags options = KConfigGroup::Normal);
40
41/*!
42 * Returns whether a given KConfig group has any saved window size data.
43 *
44 * \a config The config group to read from.
45 *
46 * \since 6.0
47 */
48KCONFIGGUI_EXPORT bool hasSavedWindowSize(KConfigGroup &config);
49
50/*!
51 * Restores the dialog's size from the configuration according to
52 * the screen size.
53 *
54 * If you're calling this from a constructor (for a mainwindow or dialog, for instance)
55 * you should first call winId() so that a QWindow is created, then you can call windowHandle()
56 * to pass to this method.
57 *
58 * Example code:
59 * \code
60 * create(); // ensure there's a window created
61 * const QSize availableSize = windowHandle()->screen()->availableSize();
62 * windowHandle()->resize(availableSize.width() * 0.7, availableSize.height() * 0.5); // default size
63 * KWindowConfig::restoreWindowSize(windowHandle(), KSharedConfig::openConfig()->group("MyDialog"));
64 * resize(windowHandle()->size()); // workaround for QTBUG-40584
65 * \endcode
66 *
67 * \note the group must be set before calling
68 *
69 * \a window The window to restore size.
70 *
71 * \a config The config group to read from.
72 *
73 * \since 5.0.
74 */
75KCONFIGGUI_EXPORT void restoreWindowSize(QWindow *window, const KConfigGroup &config);
76
77/*!
78 * Saves the window's position either to the global or application config file.
79 * This function has no effect on Wayland, where the compositor is responsible
80 * for window positioning.
81 *
82 * \note the group must be set before calling
83 *
84 * \a window The window whose position to save.
85 *
86 * \a config The config group to read from.
87 *
88 * \a options passed to KConfigGroup::writeEntry()
89 *
90 * \since 5.74
91 */
92KCONFIGGUI_EXPORT void saveWindowPosition(const QWindow *window, KConfigGroup &config, KConfigGroup::WriteConfigFlags options = KConfigGroup::Normal);
93
94/*!
95 * Returns whether a given KConfig group has any saved window position data.
96 *
97 * \note: always returns false on Wayland where saving and restoring window
98 * position data is not supported.
99 *
100 * \a config The config group to read from.
101 *
102 * \since 6.0
103 */
104KCONFIGGUI_EXPORT bool hasSavedWindowPosition(KConfigGroup &config);
105/*!
106 * Restores the window's screen position from the configuration and calls restoreWindowScreenPosition.
107 * This function has no effect on Wayland, where the compositor is responsible
108 * for window positioning.
109 *
110 * \note the group must be set before calling
111 *
112 * \a window The window whose position to restore.
113 *
114 * \a config The config group to read from.
115 *
116 * \since 5.74
117 */
118KCONFIGGUI_EXPORT void restoreWindowPosition(QWindow *window, const KConfigGroup &config);
119
120/*!
121 * Restores the window's position on provided screen from the configuration.
122 * This function has no effect on Wayland, where the compositor is responsible
123 * for window positioning.
124 *
125 * \note the group must be set before calling
126 *
127 * \a window The window whose position to restore.
128 *
129 * \a screen Screen on which window should be placed.
130 *
131 * \a config The config group to read from.
132 *
133 * \since 5.99
134 */
135KCONFIGGUI_EXPORT void restoreWindowScreenPosition(QWindow *window, const QScreen *screen, const KConfigGroup &config);
136}
137#endif // KWINDOWCONFIG_H
138

source code of kconfig/src/gui/kwindowconfig.h