1/* This file is part of the KDE libraries
2 Copyright (C) 2000,2006 David Faure <faure@kde.org>
3
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
7
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
12
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
17*/
18#ifndef _KGLOBALSETTINGS_H
19#define _KGLOBALSETTINGS_H
20
21#include <kdeui_export.h>
22#include <ksharedconfig.h>
23#include <QtCore/QObject>
24#include <QtCore/QString>
25#include <QtGui/QPalette>
26
27#define KDE_DEFAULT_SINGLECLICK true
28#define KDE_DEFAULT_SMOOTHSCROLL true
29#define KDE_DEFAULT_INSERTTEAROFFHANDLES 0
30#define KDE_DEFAULT_AUTOSELECTDELAY -1
31#define KDE_DEFAULT_CHANGECURSOR true
32#define KDE_DEFAULT_LARGE_CURSOR false
33#define KDE_DEFAULT_WHEEL_ZOOM false
34#ifdef Q_WS_MAEMO_5
35#define KDE_DEFAULT_ICON_ON_PUSHBUTTON false
36#else
37#define KDE_DEFAULT_ICON_ON_PUSHBUTTON true
38#endif
39#define KDE_DEFAULT_OPAQUE_RESIZE true
40#define KDE_DEFAULT_BUTTON_LAYOUT 0
41#define KDE_DEFAULT_SHADE_SORT_COLUMN true
42#define KDE_DEFAULT_ALLOW_DEFAULT_BACKGROUND_IMAGES true
43#define KDE_DEFAULT_NATURAL_SORTING true
44
45class KUrl;
46
47class QColor;
48class QFont;
49class QPoint;
50class QRect;
51class QWidget;
52
53/**
54 * Access the KDE global configuration.
55 *
56 * @author David Faure \<faure@kde.org\>
57 */
58class KDEUI_EXPORT KGlobalSettings : public QObject
59{
60 Q_OBJECT
61
62public:
63 ~KGlobalSettings();
64
65 /**
66 * Returns a threshold in pixels for drag & drop operations.
67 * As long as the mouse movement has not exceeded this number
68 * of pixels in either X or Y direction no drag operation may
69 * be started. This prevents spurious drags when the user intended
70 * to click on something but moved the mouse a bit while doing so.
71 *
72 * For this to work you must save the position of the mouse (oldPos)
73 * in the QWidget::mousePressEvent().
74 * When the position of the mouse (newPos)
75 * in a QWidget::mouseMoveEvent() exceeds this threshold
76 * you may start a drag
77 * which should originate from oldPos.
78 *
79 * Example code:
80 * \code
81 * void KColorCells::mousePressEvent( QMouseEvent *e )
82 * {
83 * mOldPos = e->pos();
84 * }
85 *
86 * void KColorCells::mouseMoveEvent( QMouseEvent *e )
87 * {
88 * if( !(e->state() && LeftButton)) return;
89 *
90 * int delay = KGlobalSettings::dndEventDelay();
91 * QPoint newPos = e->pos();
92 * if(newPos.x() > mOldPos.x()+delay || newPos.x() < mOldPos.x()-delay ||
93 * newPos.y() > mOldPos.y()+delay || newPos.y() < mOldPos.y()-delay)
94 * {
95 * // Drag color object
96 * int cell = posToCell(mOldPos); // Find color at mOldPos
97 * if ((cell != -1) && colors[cell].isValid())
98 * {
99 * KColorDrag *d = KColorDrag::makeDrag( colors[cell], this);
100 * d->dragCopy();
101 * }
102 * }
103 * }
104 * \endcode
105 * @return the threshold for drag & drop in pixels
106 */
107
108 static int dndEventDelay();
109
110 /**
111 * Returns whether KDE runs in single (default) or double click
112 * mode.
113 * see http://developer.kde.org/documentation/standards/kde/style/mouse/index.html
114 * @return true if single click mode, or false if double click mode.
115 **/
116 static bool singleClick();
117
118 /**
119 * Returns if item views should force smooth scrolling.
120 * @return true if smooth scrolling is enabled for item view, false otherwise.
121 * @since 4.2
122 */
123 static bool smoothScroll();
124
125 /**
126 * This enum describes the return type for insertTearOffHandle() whether to insert
127 * a handle or not. Applications who independently want to use handles in their popup menus
128 * should test for Application level before calling the appropriate function in KMenu.
129 **/
130 enum TearOffHandle {
131 Disable = 0, ///< disable tear-off handles
132 ApplicationLevel, ///< enable on application level
133 Enable ///< enable tear-off handles
134 };
135
136 /**
137 * Returns whether tear-off handles are inserted in KMenus.
138 * @return whether tear-off handles are inserted in KMenus.
139 **/
140 static TearOffHandle insertTearOffHandle();
141
142 /**
143 * Checks whether the cursor changes over icons.
144 * @return the KDE setting for "change cursor over icon"
145 */
146 static bool changeCursorOverIcon();
147
148 /**
149 * Returns the KDE setting for the auto-select option.
150 *
151 * @return the auto-select delay or -1 if auto-select is disabled.
152 */
153 static int autoSelectDelay();
154
155 /**
156 * Returns the KDE setting for the shortcut key to open
157 * context menus.
158 *
159 * @return the key that pops up context menus.
160 * @deprecated Simply reimplement QWidget::contextMenuEvent() instead.
161 */
162#ifndef KDE_NO_DEPRECATED
163 static KDE_DEPRECATED int contextMenuKey ();
164#endif
165
166 /**
167 * Returns the KDE setting for context menus.
168 *
169 * @return whether context menus should be shown on button press
170 * or button release (click).
171 */
172 static bool showContextMenusOnPress ();
173
174 /**
175 * This enum describes the completion mode used for by the KCompletion class.
176 * See <a href="http://developer.kde.org/documentation/standards/kde/style/keys/completion.html">
177 * the styleguide</a>.
178 **/
179 enum Completion {
180 /**
181 * No completion is used.
182 */
183 CompletionNone=1,
184 /**
185 * Text is automatically filled in whenever possible.
186 */
187 CompletionAuto,
188 /**
189 * Same as automatic except shortest match is used for completion.
190 */
191 CompletionMan,
192 /**
193 * Complete text much in the same way as a typical *nix shell would.
194 */
195 CompletionShell,
196 /**
197 * Lists all possible matches in a popup list-box to choose from.
198 */
199 CompletionPopup,
200 /**
201 * Lists all possible matches in a popup list-box to choose from, and automatically
202 * fill the result whenever possible.
203 */
204 CompletionPopupAuto
205 };
206
207 /**
208 * Returns the preferred completion mode setting.
209 *
210 * @return Completion. Default is @p CompletionPopup.
211 */
212 static Completion completionMode();
213
214 /**
215 * Describes the mouse settings.
216 */
217 struct KMouseSettings
218 {
219 enum { RightHanded = 0, LeftHanded = 1 };
220 int handed; // left or right
221 };
222
223 /**
224 * This returns the current mouse settings.
225 * On Windows, settings are retrieved from the system.
226 * @return the current mouse settings
227 */
228 static KMouseSettings & mouseSettings();
229
230 /**
231 * The path to the desktop directory of the current user.
232 * @return the user's desktop directory
233 */
234 static QString desktopPath();
235
236 /**
237 * The path to the autostart directory of the current user.
238 * @return the path of the autostart directory
239 */
240 static QString autostartPath();
241
242 /**
243 * The path where documents are stored of the current user.
244 * @return the path of the document directory
245 */
246 static QString documentPath();
247
248 /**
249 * The path where music are stored of the current user.
250 * @return the path of the music directory
251 */
252 static QString musicPath();
253
254 /**
255 * The path where videos are stored of the current user.
256 * @return the path of the video directory
257 */
258 static QString videosPath();
259
260 /**
261 * The path where download are stored of the current user.
262 * @return the path of the download directory
263 */
264 static QString downloadPath();
265
266 /**
267 * The path where pictures are stored of the current user.
268 * @return the path of the pictures directory
269 */
270 static QString picturesPath();
271
272 /**
273 * The default color to use for inactive titles.
274 * @return the inactive title color
275 */
276 static QColor inactiveTitleColor();
277
278 /**
279 * The default color to use for inactive texts.
280 * @return the inactive text color
281 */
282 static QColor inactiveTextColor();
283
284 /**
285 * The default color to use for active titles.
286 * @return the active title color
287 */
288 static QColor activeTitleColor();
289
290 /**
291 * The default color to use for active texts.
292 * @return the active text color
293 */
294 static QColor activeTextColor();
295
296 /**
297 * Returns the contrast for borders.
298 * @return the contrast (between 0 for minimum and 10 for maximum
299 * contrast)
300 */
301 static int contrast();
302
303 /**
304 * Returns the contrast for borders as a floating point value.
305 * @param config pointer to the config from which to read the contrast
306 * setting (the default is to use KGlobal::config())
307 * @return the contrast (between 0.0 for minimum and 1.0 for maximum
308 * contrast)
309 */
310 static qreal contrastF(const KSharedConfigPtr &config = KSharedConfigPtr());
311
312 /**
313 * Returns if the sorted column in a K3ListView shall be drawn with a
314 * shaded background color.
315 * @return true if the sorted column shall be shaded
316 */
317 static bool shadeSortColumn();
318
319 /**
320 * Returns if default background images are allowed by the color scheme.
321 * A "default" background image is just that, i.e. the user has not
322 * actively selected a background image to use.
323 * @return true if default background images may be used
324 */
325 static bool allowDefaultBackgroundImages();
326
327 /**
328 * Returns the default general font.
329 * @return the default general font.
330 */
331 static QFont generalFont();
332
333 /**
334 * Returns the default fixed font.
335 * @return the default fixed font.
336 */
337 static QFont fixedFont();
338
339 /**
340 * Returns the default toolbar font.
341 * @return the default toolbar font.
342 */
343 static QFont toolBarFont();
344
345 /**
346 * Returns the default menu font.
347 * @return the default menu font.
348 */
349 static QFont menuFont();
350
351 /**
352 * Returns the default window title font.
353 * @return the default window title font.
354 */
355 static QFont windowTitleFont();
356
357 /**
358 * Returns the default taskbar font.
359 * @return the default taskbar font.
360 */
361 static QFont taskbarFont();
362
363 /**
364 * Returns a font of approx. 48 pt. capable of showing @p text.
365 * @param text the text to test
366 * @return the font that is capable to show the text with 48 pt
367 */
368 static QFont largeFont(const QString &text = QString());
369
370 /**
371 * Returns the smallest readable font. This can be used in dockers,
372 * rulers and other places where space is at a premium.
373 */
374 static QFont smallestReadableFont();
375
376 /**
377 * Returns if the user specified multihead. In case the display
378 * has multiple screens, the return value of this function specifies
379 * if the user wants KDE to run on all of them or just on the primary
380 * On Windows, settings are retrieved from the system.
381 * @return true if the user chose multi head
382 */
383 static bool isMultiHead();
384
385 /**
386 * Typically, QScrollView derived classes can be scrolled fast by
387 * holding down the Ctrl-button during wheel-scrolling.
388 * But QTextEdit and derived classes perform zooming instead of fast
389 * scrolling.
390 *
391 * This value determines whether the user wants to zoom or scroll fast
392 * with Ctrl-wheelscroll.
393 * @return true if the user wishes to zoom with the mouse wheel,
394 * false for scrolling
395 */
396 static bool wheelMouseZooms();
397
398 /**
399 * This function returns the desktop geometry for an application's splash
400 * screen. It takes into account the user's display settings (number of
401 * screens, Xinerama, etc), and the user's preferences (if KDE should be
402 * Xinerama aware).
403 *
404 * @return the geometry to use for the desktop. Note that it might not
405 * start at (0,0).
406 */
407 static QRect splashScreenDesktopGeometry();
408
409 /**
410 * This function returns the desktop geometry for an application that needs
411 * to set the geometry of a widget on the screen manually. It takes into
412 * account the user's display settings (number of screens, Xinerama, etc),
413 * and the user's preferences (if KDE should be Xinerama aware).
414 *
415 * Note that this can break in multi-head (not Xinerama) mode because this
416 * point could be on multiple screens. Use with care.
417 *
418 * @param point a reference point for the widget, for instance one that the
419 * widget should be adjacent or on top of.
420 *
421 * @return the geometry to use for the desktop. Note that it might not
422 * start at (0,0).
423 */
424 static QRect desktopGeometry(const QPoint& point);
425
426 /**
427 * This function returns the desktop geometry for an application that needs
428 * to set the geometry of a widget on the screen manually. It takes into
429 * account the user's display settings (number of screens, Xinerama, etc),
430 * and the user's preferences (if KDE should be Xinerama aware).
431 *
432 * @param w the widget in question. This is used to determine which screen
433 * to use in Xinerama or multi-head mode.
434 *
435 * @return the geometry to use for the desktop. Note that it might not
436 * start at (0,0).
437 */
438 static QRect desktopGeometry(const QWidget* w);
439
440 /**
441 * This function determines if the user wishes to see icons on the
442 * push buttons.
443 *
444 * @return Returns true if user wants to show icons.
445 */
446 static bool showIconsOnPushButtons();
447
448 /**
449 * Returns true, if user visible strings should be sorted in a natural way:
450 * image 1.jpg
451 * image 2.jpg
452 * image 10.jpg
453 * image 11.jpg
454 * If false is returned, the strings are sorted by their unicode values:
455 * image 1.jpg
456 * image 10.jpg
457 * image 11.jpg
458 * image 2.jpg
459 *
460 * @since 4.4
461 */
462 static bool naturalSorting();
463
464 enum GraphicEffect {
465 NoEffects = 0x0000, ///< GUI with no effects at all.
466 GradientEffects = 0x0001, ///< GUI with only gradients enabled.
467 SimpleAnimationEffects = 0x0002, ///< GUI with simple animations enabled.
468 ComplexAnimationEffects = 0x0006 ///< GUI with complex animations enabled.
469 ///< Note that ComplexAnimationsEffects implies SimpleAnimationEffects.
470 };
471
472 Q_DECLARE_FLAGS(GraphicEffects, GraphicEffect)
473
474 /**
475 * This function determines the desired level of effects on the GUI.
476 *
477 * @since 4.1
478 */
479 static GraphicEffects graphicEffectsLevel();
480
481 /**
482 * This function determines the default level of effects on the GUI
483 * depending on the system capabilities.
484 *
485 * @since 4.1
486 */
487 static GraphicEffects graphicEffectsLevelDefault();
488
489 /**
490 * This function determines if the user wishes to see previews
491 * for the selected url
492 *
493 * @return Returns true if user wants to show previews.
494 */
495 static bool showFilePreview(const KUrl &);
496
497 /**
498 * Whether the user wishes to use opaque resizing. Primarily
499 * intended for QSplitter::setOpaqueResize()
500 *
501 * @return Returns true if user wants to use opaque resizing.
502 */
503 static bool opaqueResize();
504
505 /**
506 * The layout scheme to use for dialog buttons
507 *
508 * @return Returns the number of the scheme to use.
509 */
510 static int buttonLayout();
511
512 /**
513 * Used to obtain the QPalette that will be used to set the application palette.
514 *
515 * This is only useful for configuration modules such as krdb and should not be
516 * used in normal circumstances.
517 * @param config KConfig from which to load the colors (passed as-is to
518 * ::KColorScheme).
519 *
520 * @return the QPalette
521 */
522 static QPalette createApplicationPalette(const KSharedConfigPtr &config = KSharedConfigPtr());
523
524 /**
525 * Used to obtain the QPalette that will be used to set the application palette.
526 *
527 * This is only useful for configuration modules such as krdb and should not be
528 * used in normal circumstances.
529 * @param config KConfig from which to load the colors (passed as-is to
530 * ::KColorScheme).
531 *
532 * @note The difference between this and the previous is that this never caches.
533 * @since 4.6.3
534 *
535 * @return the QPalette
536 */
537 static QPalette createNewApplicationPalette(const KSharedConfigPtr &config = KSharedConfigPtr());
538
539 /**
540 * An identifier for change signals.
541 * \see emitChange
542 */
543 enum ChangeType { PaletteChanged = 0, FontChanged, StyleChanged,
544 SettingsChanged, IconChanged, CursorChanged,
545 ToolbarStyleChanged, ClipboardConfigChanged,
546 BlockShortcuts, NaturalSortingChanged };
547
548 /**
549 * Notifies all KDE applications on the current display of a change.
550 *
551 * This is typically called by kcontrol modules after changing the corresponding
552 * config file. Do not call this from a normal KDE application.
553 */
554 static void emitChange(ChangeType changeType, int arg = 0);
555
556 /**
557 * Return the KGlobalSettings singleton.
558 * This is used to connect to its signals, to be notified of changes.
559 */
560 static KGlobalSettings* self();
561
562 /**
563 * Specifies options passed to activate().
564 *
565 * @since 4.6
566 */
567 enum ActivateOption {
568 ApplySettings = 0x1, ///< Make all globally applicable settings take effect.
569 ListenForChanges = 0x2 ///< Listen for changes to the settings.
570 };
571 Q_DECLARE_FLAGS(ActivateOptions, ActivateOption)
572
573 /**
574 * Makes all globally applicable settings take effect
575 * and starts listening for changes to these settings.
576 *
577 * This is usually called only by the KApplication constructor.
578 *
579 * @since 4.3.3
580 */
581 void activate(); //KDE5: Merge with the overloaded method below
582
583 /**
584 * @overload
585 *
586 * @since 4.6
587 */
588 void activate(ActivateOptions options);
589
590 /**
591 * Valid values for the settingsChanged signal
592 */
593 enum SettingsCategory { SETTINGS_MOUSE, SETTINGS_COMPLETION, SETTINGS_PATHS,
594 SETTINGS_POPUPMENU, SETTINGS_QT, SETTINGS_SHORTCUTS,
595 SETTINGS_LOCALE, SETTINGS_STYLE };
596
597Q_SIGNALS:
598 /**
599 * Emitted when the application has changed its palette due to a KControl request.
600 *
601 * Normally, widgets will update their palette automatically, but you
602 * should connect to this to program special behavior.
603 *
604 * Note: If you derive from a QWidget-based class, a faster method is to
605 * reimplement QWidget::changeEvent() and catch QEvent::PaletteChange.
606 * This is the preferred way to get informed about palette updates.
607 */
608 void kdisplayPaletteChanged();
609
610 /**
611 * Emitted when the application has changed its GUI style in response to a KControl request.
612 *
613 * Normally, widgets will update their styles automatically (as they would
614 * respond to an explicit setGUIStyle() call), but you should connect to
615 * this to program special behavior.
616 *
617 * Note: If you derive from a QWidget-based class, a faster method is to
618 * reimplement QWidget::changeEvent() and catch QEvent::StyleChange.
619 * This is the preferred way to get informed about style updates.
620 */
621 void kdisplayStyleChanged();
622
623 /**
624 * Emitted when the application has changed its font in response to a KControl request.
625 *
626 * Normally widgets will update their fonts automatically, but you should
627 * connect to this to monitor global font changes, especially if you are
628 * using explicit fonts.
629 *
630 * Note: If you derive from a QWidget-based class, a faster method is to
631 * reimplement QWidget::changeEvent() and catch QEvent::FontChange.
632 * This is the preferred way to get informed about font updates.
633 */
634 void kdisplayFontChanged();
635
636 /**
637 * Emitted when the application has changed either its GUI style, its font or its palette
638 * in response to a kdisplay request. Normally, widgets will update their styles
639 * automatically, but you should connect to this to program special
640 * behavior.
641 */
642 void appearanceChanged();
643
644 /**
645 * Emitted when the settings for toolbars have been changed. KToolBar will know what to do.
646 */
647 void toolbarAppearanceChanged(int);
648
649 /**
650 * Emitted when the global settings have been changed.
651 * KGlobalSettings takes care of calling reparseConfiguration on KGlobal::config()
652 * so that applications/classes using this only have to re-read the configuration
653 * @param category the category among the SettingsCategory enum.
654 */
655 void settingsChanged(int category);
656
657 /**
658 * Emitted when the global icon settings have been changed.
659 * @param group the new group
660 */
661 void iconChanged(int group);
662
663 /**
664 * Emitted when the cursor theme has been changed.
665 */
666 void cursorChanged();
667
668 /**
669 * Emitted by BlockShortcuts
670 */
671 void blockShortcuts(int data);
672
673 /**
674 * Emitted when the natural sorting has been changed.
675 * @since 4.4
676 */
677 void naturalSortingChanged();
678
679private:
680 friend class KApplication;
681
682 KGlobalSettings();
683
684 class Private;
685 Private* const d;
686
687 Q_PRIVATE_SLOT(d, void _k_slotNotifyChange(int, int))
688};
689
690Q_DECLARE_OPERATORS_FOR_FLAGS(KGlobalSettings::GraphicEffects)
691Q_DECLARE_OPERATORS_FOR_FLAGS(KGlobalSettings::ActivateOptions)
692
693#endif
694