widget/LookAndFeel.h

   1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef __LookAndFeel
   7 #define __LookAndFeel
   8
   9 #ifndef MOZILLA_INTERNAL_API
  10 #  error "This header is only usable from within libxul (MOZILLA_INTERNAL_API)."
  11 #endif
  12
  13 #include "nsDebug.h"
  14 #include "nsColor.h"
  15 #include "nsTArray.h"
  16
  17 struct gfxFontStyle;
  18
  19 struct LookAndFeelInt {
  20   int32_t id;
  21   union {
  22     int32_t value;
  23     nscolor colorValue;
  24   };
  25 };
  26
  27 namespace mozilla {
  28
  29 enum class StyleSystemColor : uint8_t;
  30
  31 class LookAndFeel {
  32  public:
  33   using ColorID = StyleSystemColor;
  34
  35   // When modifying this list, also modify nsXPLookAndFeel::sIntPrefs
  36   // in widget/xpwidgts/nsXPLookAndFeel.cpp.
  37   enum IntID {
  38     // default, may be overriden by OS
  39     eIntID_CaretBlinkTime,
  40     // pixel width of caret
  41     eIntID_CaretWidth,
  42     // show the caret when text is selected?
  43     eIntID_ShowCaretDuringSelection,
  44     // select textfields when focused via tab/accesskey?
  45     eIntID_SelectTextfieldsOnKeyFocus,
  46     // delay before submenus open
  47     eIntID_SubmenuDelay,
  48     // can popups overlap menu/task bar?
  49     eIntID_MenusCanOverlapOSBar,
  50     // should overlay scrollbars be used?
  51     eIntID_UseOverlayScrollbars,
  52     // allow H and V overlay scrollbars to overlap?
  53     eIntID_AllowOverlayScrollbarsOverlap,
  54     // show/hide scrollbars based on activity
  55     eIntID_ShowHideScrollbars,
  56     // skip navigating to disabled menu item?
  57     eIntID_SkipNavigatingDisabledMenuItem,
  58     // begin a drag if the mouse is moved further than the threshold while the
  59     // button is down
  60     eIntID_DragThresholdX,
  61     eIntID_DragThresholdY,
  62     // Accessibility theme being used?
  63     eIntID_UseAccessibilityTheme,
  64
  65     // position of scroll arrows in a scrollbar
  66     eIntID_ScrollArrowStyle,
  67     // is scroll thumb proportional or fixed?
  68     eIntID_ScrollSliderStyle,
  69
  70     // each button can take one of four values:
  71     eIntID_ScrollButtonLeftMouseButtonAction,
  72     // 0 - scrolls one  line, 1 - scrolls one page
  73     eIntID_ScrollButtonMiddleMouseButtonAction,
  74     // 2 - scrolls to end, 3 - button ignored
  75     eIntID_ScrollButtonRightMouseButtonAction,
  76
  77     // delay for opening spring loaded folders
  78     eIntID_TreeOpenDelay,
  79     // delay for closing spring loaded folders
  80     eIntID_TreeCloseDelay,
  81     // delay for triggering the tree scrolling
  82     eIntID_TreeLazyScrollDelay,
  83     // delay for scrolling the tree
  84     eIntID_TreeScrollDelay,
  85     // the maximum number of lines to be scrolled at ones
  86     eIntID_TreeScrollLinesMax,
  87     // What type of tab-order to use
  88     eIntID_TabFocusModel,
  89     // Should menu items blink when they're chosen?
  90     eIntID_ChosenMenuItemsShouldBlink,
  91
  92     /*
  93      * A Boolean value to determine whether the Windows accent color
  94      * should be applied to the title bar.
  95      *
  96      * The value of this metric is not used on other platforms. These platforms
  97      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
  98      */
  99     eIntID_WindowsAccentColorInTitlebar,
 100
 101     /*
 102      * A Boolean value to determine whether the Windows default theme is
 103      * being used.
 104      *
 105      * The value of this metric is not used on other platforms. These platforms
 106      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 107      */
 108     eIntID_WindowsDefaultTheme,
 109
 110     /*
 111      * A Boolean value to determine whether the DWM compositor is being used
 112      *
 113      * This metric is not used on non-Windows platforms. These platforms
 114      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 115      */
 116     eIntID_DWMCompositor,
 117
 118     /*
 119      * A Boolean value to determine whether Windows is themed (Classic vs.
 120      * uxtheme)
 121      *
 122      * This is Windows-specific and is not implemented on other platforms
 123      * (will return the default of NS_ERROR_FAILURE).
 124      */
 125     eIntID_WindowsClassic,
 126
 127     /*
 128      * A Boolean value to determine whether the current Windows desktop theme
 129      * supports Aero Glass.
 130      *
 131      * This is Windows-specific and is not implemented on other platforms
 132      * (will return the default of NS_ERROR_FAILURE).
 133      */
 134     eIntID_WindowsGlass,
 135
 136     /*
 137      * A Boolean value to determine whether the device is a touch enabled
 138      * device. Currently this is only supported by the Windows 7 Touch API.
 139      *
 140      * Platforms that do not support this metric should return
 141      * NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 142      */
 143     eIntID_TouchEnabled,
 144
 145     /*
 146      * A Boolean value to determine whether the Mac graphite theme is
 147      * being used.
 148      *
 149      * The value of this metric is not used on other platforms. These platforms
 150      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 151      */
 152     eIntID_MacGraphiteTheme,
 153
 154     /*
 155      * A Boolean value to determine whether the Mac OS X Yosemite-specific
 156      * theming should be used.
 157      *
 158      * The value of this metric is not used on non-Mac platforms. These
 159      * platforms should return NS_ERROR_NOT_IMPLEMENTED when queried for this
 160      * metric.
 161      */
 162     eIntID_MacYosemiteTheme,
 163
 164     /*
 165      * eIntID_AlertNotificationOrigin indicates from which corner of the
 166      * screen alerts slide in, and from which direction (horizontal/vertical).
 167      * 0, the default, represents bottom right, sliding vertically.
 168      * Use any bitwise combination of the following constants:
 169      * NS_ALERT_HORIZONTAL (1), NS_ALERT_LEFT (2), NS_ALERT_TOP (4).
 170      *
 171      *       6       4
 172      *     +-----------+
 173      *    7|           |5
 174      *     |           |
 175      *    3|           |1
 176      *     +-----------+
 177      *       2       0
 178      */
 179     eIntID_AlertNotificationOrigin,
 180
 181     /**
 182      * If true, clicking on a scrollbar (not as in dragging the thumb) defaults
 183      * to scrolling the view corresponding to the clicked point. Otherwise, we
 184      * only do so if the scrollbar is clicked using the middle mouse button or
 185      * if shift is pressed when the scrollbar is clicked.
 186      */
 187     eIntID_ScrollToClick,
 188
 189     /**
 190      * IME and spell checker underline styles, the values should be
 191      * NS_DECORATION_LINE_STYLE_*.  They are defined below.
 192      */
 193     eIntID_IMERawInputUnderlineStyle,
 194     eIntID_IMESelectedRawTextUnderlineStyle,
 195     eIntID_IMEConvertedTextUnderlineStyle,
 196     eIntID_IMESelectedConvertedTextUnderline,
 197     eIntID_SpellCheckerUnderlineStyle,
 198
 199     /**
 200      * If this metric != 0, support window dragging on the menubar.
 201      */
 202     eIntID_MenuBarDrag,
 203     /**
 204      * Return the appropriate WindowsThemeIdentifier for the current theme.
 205      */
 206     eIntID_WindowsThemeIdentifier,
 207     /**
 208      * Return an appropriate os version identifier.
 209      */
 210     eIntID_OperatingSystemVersionIdentifier,
 211     /**
 212      * 0: scrollbar button repeats to scroll only when cursor is on the button.
 213      * 1: scrollbar button repeats to scroll even if cursor is outside of it.
 214      */
 215     eIntID_ScrollbarButtonAutoRepeatBehavior,
 216     /**
 217      * Delay before showing a tooltip.
 218      */
 219     eIntID_TooltipDelay,
 220     /*
 221      * A Boolean value to determine whether Mac OS X Lion style swipe animations
 222      * should be used.
 223      */
 224     eIntID_SwipeAnimationEnabled,
 225
 226     /*
 227      * Controls whether overlay scrollbars display when the user moves
 228      * the mouse in a scrollable frame.
 229      */
 230     eIntID_ScrollbarDisplayOnMouseMove,
 231
 232     /*
 233      * Overlay scrollbar animation constants.
 234      */
 235     eIntID_ScrollbarFadeBeginDelay,
 236     eIntID_ScrollbarFadeDuration,
 237
 238     /**
 239      * Distance in pixels to offset the context menu from the cursor
 240      * on open.
 241      */
 242     eIntID_ContextMenuOffsetVertical,
 243     eIntID_ContextMenuOffsetHorizontal,
 244
 245     /*
 246      * A boolean value indicating whether client-side decorations are
 247      * supported by the user's GTK version.
 248      */
 249     eIntID_GTKCSDAvailable,
 250
 251     /*
 252      * A boolean value indicating whether GTK+ system titlebar should be
 253      * disabled by default.
 254      */
 255     eIntID_GTKCSDHideTitlebarByDefault,
 256
 257     /*
 258      * A boolean value indicating whether client-side decorations should
 259      * have transparent background.
 260      */
 261     eIntID_GTKCSDTransparentBackground,
 262
 263     /*
 264      * A boolean value indicating whether client-side decorations should
 265      * contain a minimize button.
 266      */
 267     eIntID_GTKCSDMinimizeButton,
 268
 269     /*
 270      * A boolean value indicating whether client-side decorations should
 271      * contain a maximize button.
 272      */
 273     eIntID_GTKCSDMaximizeButton,
 274
 275     /*
 276      * A boolean value indicating whether client-side decorations should
 277      * contain a close button.
 278      */
 279     eIntID_GTKCSDCloseButton,
 280
 281     /*
 282      * A boolean value indicating whether titlebar buttons are located
 283      * in left titlebar corner.
 284      */
 285     eIntID_GTKCSDReversedPlacement,
 286
 287     /*
 288      * A boolean value indicating whether or not the OS is using a dark theme,
 289      * which we may want to switch to as well if not overridden by the user.
 290      */
 291     eIntID_SystemUsesDarkTheme,
 292
 293     /**
 294      * Corresponding to prefers-reduced-motion.
 295      * https://drafts.csswg.org/mediaqueries-5/#prefers-reduced-motion
 296      * 0: no-preference
 297      * 1: reduce
 298      */
 299
 300     eIntID_PrefersReducedMotion,
 301     /**
 302      * Corresponding to PointerCapabilities in ServoTypes.h
 303      * 0: None
 304      * 1: Coarse
 305      * 2: Fine
 306      * 4: Hover
 307      */
 308     eIntID_PrimaryPointerCapabilities,
 309     /**
 310      * Corresponding to union of PointerCapabilities values in ServoTypes.h
 311      * E.g. if there is a mouse and a digitizer, the value will be
 312      * 'Coarse | Fine | Hover'.
 313      */
 314     eIntID_AllPointerCapabilities,
 315   };
 316
 317   /**
 318    * Windows themes we currently detect.
 319    */
 320   enum WindowsTheme {
 321     eWindowsTheme_Generic = 0,  // unrecognized theme
 322     eWindowsTheme_Classic,
 323     eWindowsTheme_Aero,
 324     eWindowsTheme_LunaBlue,
 325     eWindowsTheme_LunaOlive,
 326     eWindowsTheme_LunaSilver,
 327     eWindowsTheme_Royale,
 328     eWindowsTheme_Zune,
 329     eWindowsTheme_AeroLite
 330   };
 331
 332   /**
 333    * Operating system versions.
 334    */
 335   enum OperatingSystemVersion {
 336     eOperatingSystemVersion_Windows7 = 2,
 337     eOperatingSystemVersion_Windows8,
 338     eOperatingSystemVersion_Windows10,
 339     eOperatingSystemVersion_Unknown
 340   };
 341
 342   enum {
 343     eScrollArrow_None = 0,
 344     eScrollArrow_StartBackward = 0x1000,
 345     eScrollArrow_StartForward = 0x0100,
 346     eScrollArrow_EndBackward = 0x0010,
 347     eScrollArrow_EndForward = 0x0001
 348   };
 349
 350   enum {
 351     // single arrow at each end
 352     eScrollArrowStyle_Single =
 353         eScrollArrow_StartBackward | eScrollArrow_EndForward,
 354     // both arrows at bottom/right, none at top/left
 355     eScrollArrowStyle_BothAtBottom =
 356         eScrollArrow_EndBackward | eScrollArrow_EndForward,
 357     // both arrows at both ends
 358     eScrollArrowStyle_BothAtEachEnd =
 359         eScrollArrow_EndBackward | eScrollArrow_EndForward |
 360         eScrollArrow_StartBackward | eScrollArrow_StartForward,
 361     // both arrows at top/left, none at bottom/right
 362     eScrollArrowStyle_BothAtTop =
 363         eScrollArrow_StartBackward | eScrollArrow_StartForward
 364   };
 365
 366   enum { eScrollThumbStyle_Normal, eScrollThumbStyle_Proportional };
 367
 368   // When modifying this list, also modify nsXPLookAndFeel::sFloatPrefs
 369   // in widget/xpwidgts/nsXPLookAndFeel.cpp.
 370   enum FloatID {
 371     eFloatID_IMEUnderlineRelativeSize,
 372     eFloatID_SpellCheckerUnderlineRelativeSize,
 373
 374     // The width/height ratio of the cursor. If used, the CaretWidth int metric
 375     // should be added to the calculated caret width.
 376     eFloatID_CaretAspectRatio
 377   };
 378
 379   // These constants must be kept in 1:1 correspondence with the
 380   // NS_STYLE_FONT_* system font constants.
 381   enum FontID {
 382     eFont_Caption = 1,  // css2
 383     FontID_MINIMUM = eFont_Caption,
 384     eFont_Icon,
 385     eFont_Menu,
 386     eFont_MessageBox,
 387     eFont_SmallCaption,
 388     eFont_StatusBar,
 389
 390     eFont_Window,  // css3
 391     eFont_Document,
 392     eFont_Workspace,
 393     eFont_Desktop,
 394     eFont_Info,
 395     eFont_Dialog,
 396     eFont_Button,
 397     eFont_PullDownMenu,
 398     eFont_List,
 399     eFont_Field,
 400
 401     eFont_Tooltips,  // moz
 402     eFont_Widget,
 403     FontID_MAXIMUM = eFont_Widget
 404   };
 405
 406   /**
 407    * GetColor() return a native color value (might be overwritten by prefs) for
 408    * aID.  Some platforms don't return an error even if the index doesn't
 409    * match any system colors.  And also some platforms may initialize the
 410    * return value even when it returns an error.  Therefore, if you want to
 411    * use a color for the default value, you should use the other GetColor()
 412    * which returns nscolor directly.
 413    *
 414    * NOTE:
 415    *   ColorID::TextSelectForeground might return NS_DONT_CHANGE_COLOR.
 416    *   ColorID::IME* might return NS_TRANSPARENT, NS_SAME_AS_FOREGROUND_COLOR or
 417    *   NS_40PERCENT_FOREGROUND_COLOR.
 418    *   These values have particular meaning.  Then, they are not an actual
 419    *   color value.
 420    */
 421   static nsresult GetColor(ColorID aID, nscolor* aResult);
 422
 423   /**
 424    * This variant of GetColor() takes an extra Boolean parameter that allows
 425    * the caller to ask that hard-coded color values be substituted for
 426    * native colors (used when it is desireable to hide system colors to
 427    * avoid system fingerprinting).
 428    */
 429   static nsresult GetColor(ColorID aID, bool aUseStandinsForNativeColors,
 430                            nscolor* aResult);
 431
 432   /**
 433    * GetInt() and GetFloat() return a int or float value for aID.  The result
 434    * might be distance, time, some flags or a int value which has particular
 435    * meaning.  See each document at definition of each ID for the detail.
 436    * The result is always 0 when they return error.  Therefore, if you want to
 437    * use a value for the default value, you should use the other method which
 438    * returns int or float directly.
 439    */
 440   static nsresult GetInt(IntID aID, int32_t* aResult);
 441   static nsresult GetFloat(FloatID aID, float* aResult);
 442
 443   static nscolor GetColor(ColorID aID, nscolor aDefault = NS_RGB(0, 0, 0)) {
 444     nscolor result = NS_RGB(0, 0, 0);
 445     if (NS_FAILED(GetColor(aID, &result))) {
 446       return aDefault;
 447     }
 448     return result;
 449   }
 450
 451   static nscolor GetColorUsingStandins(ColorID aID,
 452                                        nscolor aDefault = NS_RGB(0, 0, 0)) {
 453     nscolor result = NS_RGB(0, 0, 0);
 454     if (NS_FAILED(GetColor(aID,
 455                            true,  // aUseStandinsForNativeColors
 456                            &result))) {
 457       return aDefault;
 458     }
 459     return result;
 460   }
 461
 462   static int32_t GetInt(IntID aID, int32_t aDefault = 0) {
 463     int32_t result;
 464     if (NS_FAILED(GetInt(aID, &result))) {
 465       return aDefault;
 466     }
 467     return result;
 468   }
 469
 470   static float GetFloat(FloatID aID, float aDefault = 0.0f) {
 471     float result;
 472     if (NS_FAILED(GetFloat(aID, &result))) {
 473       return aDefault;
 474     }
 475     return result;
 476   }
 477
 478   /**
 479    * Retrieve the name and style of a system-theme font.  Returns true
 480    * if the system theme specifies this font, false if a default should
 481    * be used.  In the latter case neither aName nor aStyle is modified.
 482    *
 483    * Size of the font should be in CSS pixels, not device pixels.
 484    *
 485    * @param aID    Which system-theme font is wanted.
 486    * @param aName  The name of the font to use.
 487    * @param aStyle Styling to apply to the font.
 488    */
 489   static bool GetFont(FontID aID, nsString& aName, gfxFontStyle& aStyle);
 490
 491   /**
 492    * GetPasswordCharacter() returns a unicode character which should be used
 493    * for a masked character in password editor.  E.g., '*'.
 494    */
 495   static char16_t GetPasswordCharacter();
 496
 497   /**
 498    * If the latest character in password field shouldn't be hidden by the
 499    * result of GetPasswordCharacter(), GetEchoPassword() returns TRUE.
 500    * Otherwise, FALSE.
 501    */
 502   static bool GetEchoPassword();
 503
 504   /**
 505    * The millisecond to mask password value.
 506    * This value is only valid when GetEchoPassword() returns true.
 507    */
 508   static uint32_t GetPasswordMaskDelay();
 509
 510   /**
 511    * When system look and feel is changed, Refresh() must be called.  Then,
 512    * cached data would be released.
 513    */
 514   static void Refresh();
 515
 516   /**
 517    * GTK's initialization code can't be run off main thread, call this
 518    * if you plan on using LookAndFeel off main thread later.
 519    *
 520    * This initialized state may get reset due to theme changes, so it
 521    * must be called prior to each potential off-main-thread LookAndFeel
 522    * call, not just once.
 523    */
 524   static void NativeInit();
 525
 526   /**
 527    * If the implementation is caching values, these accessors allow the
 528    * cache to be exported and imported.
 529    */
 530   static nsTArray<LookAndFeelInt> GetIntCache();
 531   static void SetIntCache(const nsTArray<LookAndFeelInt>& aLookAndFeelIntCache);
 532   /**
 533    * Set a flag indicating whether the cache should be cleared in RefreshImpl()
 534    * or not.
 535    */
 536   static void SetShouldRetainCacheForTest(bool aValue);
 537 };
 538
 539 }  // namespace mozilla
 540
 541 // On the Mac, GetColor(ColorID::TextSelectForeground, color) returns this
 542 // constant to specify that the foreground color should not be changed
 543 // (ie. a colored text keeps its colors  when selected).
 544 // Of course if other plaforms work like the Mac, they can use it too.
 545 #define NS_DONT_CHANGE_COLOR NS_RGB(0x01, 0x01, 0x01)
 546
 547 // Similar with NS_DONT_CHANGE_COLOR, except NS_DONT_CHANGE_COLOR would returns
 548 // complementary color if fg color is same as bg color.
 549 // NS_CHANGE_COLOR_IF_SAME_AS_BG would returns
 550 // ColorID::TextSelectForegroundCustom if fg and bg color are the same.
 551 #define NS_CHANGE_COLOR_IF_SAME_AS_BG NS_RGB(0x02, 0x02, 0x02)
 552
 553 // ---------------------------------------------------------------------
 554 //  Special colors for ColorID::IME* and ColorID::SpellCheckerUnderline
 555 // ---------------------------------------------------------------------
 556
 557 // For background color only.
 558 #define NS_TRANSPARENT NS_RGBA(0x01, 0x00, 0x00, 0x00)
 559 // For foreground color only.
 560 #define NS_SAME_AS_FOREGROUND_COLOR NS_RGBA(0x02, 0x00, 0x00, 0x00)
 561 #define NS_40PERCENT_FOREGROUND_COLOR NS_RGBA(0x03, 0x00, 0x00, 0x00)
 562
 563 #define NS_IS_SELECTION_SPECIAL_COLOR(c)                          \
 564   ((c) == NS_TRANSPARENT || (c) == NS_SAME_AS_FOREGROUND_COLOR || \
 565    (c) == NS_40PERCENT_FOREGROUND_COLOR)
 566
 567 // ------------------------------------------
 568 //  Bits for eIntID_AlertNotificationOrigin
 569 // ------------------------------------------
 570
 571 #define NS_ALERT_HORIZONTAL 1
 572 #define NS_ALERT_LEFT 2
 573 #define NS_ALERT_TOP 4
 574
 575 #endif /* __LookAndFeel */