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 "nsString.h"
  16 #include "nsTArray.h"
  17 #include "mozilla/Maybe.h"
  18 #include "mozilla/widget/ThemeChangeKind.h"
  19
  20 struct gfxFontStyle;
  21
  22 class nsIFrame;
  23
  24 namespace mozilla {
  25
  26 struct StyleColorSchemeFlags;
  27
  28 namespace dom {
  29 class Document;
  30 }
  31
  32 namespace widget {
  33 class FullLookAndFeel;
  34 }  // namespace widget
  35
  36 enum class StyleSystemColor : uint8_t;
  37 enum class StyleSystemColorScheme : uint8_t;
  38 enum class StyleSystemFont : uint8_t;
  39
  40 class LookAndFeel {
  41  public:
  42   using ColorID = StyleSystemColor;
  43
  44   // When modifying this list, also modify nsXPLookAndFeel::sIntPrefs
  45   // in widget/xpwidgts/nsXPLookAndFeel.cpp.
  46   enum class IntID {
  47     // default, may be overriden by OS
  48     CaretBlinkTime,
  49     // Amount of blinks that happen before the caret stops blinking.
  50     CaretBlinkCount,
  51     // pixel width of caret
  52     CaretWidth,
  53     // show the caret when text is selected?
  54     ShowCaretDuringSelection,
  55     // select textfields when focused via tab/accesskey?
  56     SelectTextfieldsOnKeyFocus,
  57     // delay before submenus open
  58     SubmenuDelay,
  59     // can popups overlap menu/task bar?
  60     MenusCanOverlapOSBar,
  61     // should overlay scrollbars be used?
  62     UseOverlayScrollbars,
  63     // allow H and V overlay scrollbars to overlap?
  64     AllowOverlayScrollbarsOverlap,
  65     // skip navigating to disabled menu item?
  66     SkipNavigatingDisabledMenuItem,
  67     // begin a drag if the mouse is moved further than the threshold while the
  68     // button is down
  69     DragThresholdX,
  70     DragThresholdY,
  71     // Accessibility theme being used?
  72     UseAccessibilityTheme,
  73
  74     // position of scroll arrows in a scrollbar
  75     ScrollArrowStyle,
  76     // is scroll thumb proportional or fixed?
  77     ScrollSliderStyle,
  78
  79     // each button can take one of four values:
  80     ScrollButtonLeftMouseButtonAction,
  81     // 0 - scrolls one  line, 1 - scrolls one page
  82     ScrollButtonMiddleMouseButtonAction,
  83     // 2 - scrolls to end, 3 - button ignored
  84     ScrollButtonRightMouseButtonAction,
  85
  86     // delay for opening spring loaded folders
  87     TreeOpenDelay,
  88     // delay for closing spring loaded folders
  89     TreeCloseDelay,
  90     // delay for triggering the tree scrolling
  91     TreeLazyScrollDelay,
  92     // delay for scrolling the tree
  93     TreeScrollDelay,
  94     // the maximum number of lines to be scrolled at ones
  95     TreeScrollLinesMax,
  96     // What type of tab-order to use
  97     TabFocusModel,
  98     // Should menu items blink when they're chosen?
  99     ChosenMenuItemsShouldBlink,
 100
 101     /*
 102      * A Boolean value to determine whether the Windows accent color
 103      * should be applied to the title bar.
 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     WindowsAccentColorInTitlebar,
 109
 110     /*
 111      * A Boolean value to determine whether the Windows default theme is
 112      * being used.
 113      *
 114      * The value of this metric is not used on other platforms. These platforms
 115      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 116      */
 117     WindowsDefaultTheme,
 118
 119     /*
 120      * A Boolean value to determine whether the DWM compositor is being used
 121      *
 122      * This metric is not used on non-Windows platforms. These platforms
 123      * should return NS_ERROR_NOT_IMPLEMENTED when queried for this metric.
 124      */
 125     DWMCompositor,
 126
 127     /*
 128      * A Boolean value to determine whether Windows is themed (Classic vs.
 129      * uxtheme)
 130      *
 131      * This is Windows-specific and is not implemented on other platforms
 132      * (will return the default of NS_ERROR_FAILURE).
 133      */
 134     WindowsClassic,
 135
 136     /*
 137      * A Boolean value to determine whether the current Windows desktop theme
 138      * supports Aero Glass.
 139      *
 140      * This is Windows-specific and is not implemented on other platforms
 141      * (will return the default of NS_ERROR_FAILURE).
 142      */
 143     WindowsGlass,
 144
 145     /*
 146      * A Boolean value to determine whether the Mac graphite theme is
 147      * being used.
 148      */
 149     MacGraphiteTheme,
 150
 151     /*
 152      * A Boolean value to determine whether the macOS Big Sur-specific
 153      * theming should be used.
 154      */
 155     MacBigSurTheme,
 156
 157     /*
 158      * A Boolean value to determine whether macOS is in RTL mode or not.
 159      */
 160     MacRTL,
 161
 162     /*
 163      * AlertNotificationOrigin indicates from which corner of the
 164      * screen alerts slide in, and from which direction (horizontal/vertical).
 165      * 0, the default, represents bottom right, sliding vertically.
 166      * Use any bitwise combination of the following constants:
 167      * NS_ALERT_HORIZONTAL (1), NS_ALERT_LEFT (2), NS_ALERT_TOP (4).
 168      *
 169      *       6       4
 170      *     +-----------+
 171      *    7|           |5
 172      *     |           |
 173      *    3|           |1
 174      *     +-----------+
 175      *       2       0
 176      */
 177     AlertNotificationOrigin,
 178
 179     /**
 180      * If true, clicking on a scrollbar (not as in dragging the thumb) defaults
 181      * to scrolling the view corresponding to the clicked point. Otherwise, we
 182      * only do so if the scrollbar is clicked using the middle mouse button or
 183      * if shift is pressed when the scrollbar is clicked.
 184      */
 185     ScrollToClick,
 186
 187     /**
 188      * IME and spell checker underline styles, the values should be
 189      * NS_DECORATION_LINE_STYLE_*.  They are defined below.
 190      */
 191     IMERawInputUnderlineStyle,
 192     IMESelectedRawTextUnderlineStyle,
 193     IMEConvertedTextUnderlineStyle,
 194     IMESelectedConvertedTextUnderline,
 195     SpellCheckerUnderlineStyle,
 196
 197     /**
 198      * If this metric != 0, support window dragging on the menubar.
 199      */
 200     MenuBarDrag,
 201     /**
 202      * Return the appropriate WindowsThemeIdentifier for the current theme.
 203      */
 204     WindowsThemeIdentifier,
 205     /**
 206      * Return an appropriate os version identifier.
 207      */
 208     OperatingSystemVersionIdentifier,
 209     /**
 210      * 0: scrollbar button repeats to scroll only when cursor is on the button.
 211      * 1: scrollbar button repeats to scroll even if cursor is outside of it.
 212      */
 213     ScrollbarButtonAutoRepeatBehavior,
 214     /**
 215      * Delay before showing a tooltip.
 216      */
 217     TooltipDelay,
 218     /*
 219      * A Boolean value to determine whether Mac OS X Lion style swipe animations
 220      * should be used.
 221      */
 222     SwipeAnimationEnabled,
 223
 224     /*
 225      * Controls whether overlay scrollbars display when the user moves
 226      * the mouse in a scrollable frame.
 227      */
 228     ScrollbarDisplayOnMouseMove,
 229
 230     /*
 231      * Overlay scrollbar animation constants.
 232      */
 233     ScrollbarFadeBeginDelay,
 234     ScrollbarFadeDuration,
 235
 236     /**
 237      * Distance in pixels to offset the context menu from the cursor
 238      * on open.
 239      */
 240     ContextMenuOffsetVertical,
 241     ContextMenuOffsetHorizontal,
 242
 243     /*
 244      * A boolean value indicating whether client-side decorations are
 245      * supported by the user's GTK version.
 246      */
 247     GTKCSDAvailable,
 248
 249     /*
 250      * A boolean value indicating whether GTK+ system titlebar should be
 251      * disabled by default.
 252      */
 253     GTKCSDHideTitlebarByDefault,
 254
 255     /*
 256      * A boolean value indicating whether client-side decorations should
 257      * have transparent background.
 258      */
 259     GTKCSDTransparentBackground,
 260
 261     /*
 262      * A boolean value indicating whether client-side decorations should
 263      * contain a minimize button.
 264      */
 265     GTKCSDMinimizeButton,
 266
 267     /*
 268      * A boolean value indicating whether client-side decorations should
 269      * contain a maximize button.
 270      */
 271     GTKCSDMaximizeButton,
 272
 273     /*
 274      * A boolean value indicating whether client-side decorations should
 275      * contain a close button.
 276      */
 277     GTKCSDCloseButton,
 278
 279     /**
 280      * An Integer value that will represent the position of the Minimize button
 281      * in GTK Client side decoration header. Its value will be between 0 and 2
 282      * if it is on the left side of the tabbar, otherwise it will be between
 283      * 3 and 5.
 284      */
 285     GTKCSDMinimizeButtonPosition,
 286
 287     /**
 288      * An Integer value that will represent the position of the Maximize button
 289      * in GTK Client side decoration header. Its value will be between 0 and 2
 290      * if it is on the left side of the tabbar, otherwise it will be between
 291      * 3 and 5.
 292      */
 293     GTKCSDMaximizeButtonPosition,
 294
 295     /**
 296      * An Integer value that will represent the position of the Close button
 297      * in GTK Client side decoration header. Its value will be between 0 and 2
 298      * if it is on the left side of the tabbar, otherwise it will be between
 299      * 3 and 5.
 300      */
 301     GTKCSDCloseButtonPosition,
 302
 303     /*
 304      * A boolean value indicating whether titlebar buttons are located
 305      * in left titlebar corner.
 306      */
 307     GTKCSDReversedPlacement,
 308
 309     /*
 310      * A boolean value indicating whether or not the OS is using a dark theme,
 311      * which we may want to switch to as well if not overridden by the user.
 312      */
 313     SystemUsesDarkTheme,
 314
 315     /**
 316      * Corresponding to prefers-reduced-motion.
 317      * https://drafts.csswg.org/mediaqueries-5/#prefers-reduced-motion
 318      * 0: no-preference
 319      * 1: reduce
 320      */
 321
 322     PrefersReducedMotion,
 323     /**
 324      * Corresponding to PointerCapabilities in ServoTypes.h
 325      * 0: None
 326      * 1: Coarse
 327      * 2: Fine
 328      * 4: Hover
 329      */
 330     PrimaryPointerCapabilities,
 331     /**
 332      * Corresponding to union of PointerCapabilities values in ServoTypes.h
 333      * E.g. if there is a mouse and a digitizer, the value will be
 334      * 'Coarse | Fine | Hover'.
 335      */
 336     AllPointerCapabilities,
 337     /** The vertical scrollbar width, in CSS pixels. */
 338     SystemVerticalScrollbarWidth,
 339
 340     /** The horizontal scrollbar height, in CSS pixels. */
 341     SystemHorizontalScrollbarHeight,
 342
 343     /** A boolean value to determine whether a touch device is present */
 344     TouchDeviceSupportPresent,
 345
 346     /*
 347      * Not an ID; used to define the range of valid IDs.  Must be last.
 348      */
 349     End,
 350   };
 351
 352   // This is a common enough integer that seems worth the shortcut.
 353   static bool UseOverlayScrollbars() {
 354     return GetInt(IntID::UseOverlayScrollbars);
 355   }
 356
 357   /**
 358    * Windows themes we currently detect.
 359    */
 360   enum WindowsTheme {
 361     eWindowsTheme_Generic = 0,  // unrecognized theme
 362     eWindowsTheme_Classic,
 363     eWindowsTheme_Aero,
 364     eWindowsTheme_LunaBlue,
 365     eWindowsTheme_LunaOlive,
 366     eWindowsTheme_LunaSilver,
 367     eWindowsTheme_Royale,
 368     eWindowsTheme_Zune,
 369     eWindowsTheme_AeroLite
 370   };
 371
 372   /**
 373    * Operating system versions.
 374    */
 375   enum class OperatingSystemVersion {
 376     Windows7 = 2,
 377     Windows8,
 378     Windows10,
 379     Unknown
 380   };
 381
 382   enum {
 383     eScrollArrow_None = 0,
 384     eScrollArrow_StartBackward = 0x1000,
 385     eScrollArrow_StartForward = 0x0100,
 386     eScrollArrow_EndBackward = 0x0010,
 387     eScrollArrow_EndForward = 0x0001
 388   };
 389
 390   enum {
 391     // single arrow at each end
 392     eScrollArrowStyle_Single =
 393         eScrollArrow_StartBackward | eScrollArrow_EndForward,
 394     // both arrows at bottom/right, none at top/left
 395     eScrollArrowStyle_BothAtBottom =
 396         eScrollArrow_EndBackward | eScrollArrow_EndForward,
 397     // both arrows at both ends
 398     eScrollArrowStyle_BothAtEachEnd =
 399         eScrollArrow_EndBackward | eScrollArrow_EndForward |
 400         eScrollArrow_StartBackward | eScrollArrow_StartForward,
 401     // both arrows at top/left, none at bottom/right
 402     eScrollArrowStyle_BothAtTop =
 403         eScrollArrow_StartBackward | eScrollArrow_StartForward
 404   };
 405
 406   enum { eScrollThumbStyle_Normal, eScrollThumbStyle_Proportional };
 407
 408   // When modifying this list, also modify nsXPLookAndFeel::sFloatPrefs
 409   // in widget/nsXPLookAndFeel.cpp.
 410   enum class FloatID {
 411     IMEUnderlineRelativeSize,
 412     SpellCheckerUnderlineRelativeSize,
 413
 414     // The width/height ratio of the cursor. If used, the CaretWidth int metric
 415     // should be added to the calculated caret width.
 416     CaretAspectRatio,
 417
 418     // GTK text scale factor.
 419     TextScaleFactor,
 420
 421     // Not an ID; used to define the range of valid IDs.  Must be last.
 422     End,
 423   };
 424
 425   using FontID = mozilla::StyleSystemFont;
 426
 427   // Whether we should use a light or dark appearance.
 428   enum class ColorScheme : uint8_t { Light, Dark };
 429
 430   static ColorScheme SystemColorScheme() {
 431     return GetInt(IntID::SystemUsesDarkTheme) ? ColorScheme::Dark
 432                                               : ColorScheme::Light;
 433   }
 434
 435   static ColorScheme ColorSchemeForChrome();
 436   static ColorScheme ColorSchemeForStyle(const dom::Document&,
 437                                          const StyleColorSchemeFlags&);
 438   static ColorScheme ColorSchemeForFrame(const nsIFrame*);
 439
 440   // Whether standins for native colors should be used (that is, colors faked,
 441   // taken from win7, mostly). This forces light appearance, effectively.
 442   enum class UseStandins : bool { No, Yes };
 443   static UseStandins ShouldUseStandins(const dom::Document&, ColorID);
 444   static UseStandins ShouldAlwaysUseStandinsForColorInContent(ColorID);
 445
 446   // Returns a native color value (might be overwritten by prefs) for a given
 447   // color id.
 448   //
 449   // NOTE:
 450   //   ColorID::TextSelectForeground might return NS_SAME_AS_FOREGROUND_COLOR.
 451   //   ColorID::IME* might return NS_TRANSPARENT, NS_SAME_AS_FOREGROUND_COLOR or
 452   //   NS_40PERCENT_FOREGROUND_COLOR.
 453   //   These values have particular meaning.  Then, they are not an actual
 454   //   color value.
 455   static Maybe<nscolor> GetColor(ColorID, ColorScheme, UseStandins);
 456
 457   // Gets the color with appropriate defaults for UseStandins, ColorScheme etc
 458   // for a given frame.
 459   static Maybe<nscolor> GetColor(ColorID, const nsIFrame*);
 460
 461   // Versions of the above which returns the color if found, or a default (which
 462   // defaults to opaque black) otherwise.
 463   static nscolor Color(ColorID aId, ColorScheme aScheme,
 464                        UseStandins aUseStandins,
 465                        nscolor aDefault = NS_RGB(0, 0, 0)) {
 466     return GetColor(aId, aScheme, aUseStandins).valueOr(aDefault);
 467   }
 468
 469   static nscolor Color(ColorID aId, nsIFrame* aFrame,
 470                        nscolor aDefault = NS_RGB(0, 0, 0)) {
 471     return GetColor(aId, aFrame).valueOr(aDefault);
 472   }
 473
 474   /**
 475    * GetInt() and GetFloat() return a int or float value for aID.  The result
 476    * might be distance, time, some flags or a int value which has particular
 477    * meaning.  See each document at definition of each ID for the detail.
 478    * The result is always 0 when they return error.  Therefore, if you want to
 479    * use a value for the default value, you should use the other method which
 480    * returns int or float directly.
 481    */
 482   static nsresult GetInt(IntID, int32_t* aResult);
 483   static nsresult GetFloat(FloatID aID, float* aResult);
 484
 485   static int32_t GetInt(IntID aID, int32_t aDefault = 0) {
 486     int32_t result;
 487     if (NS_FAILED(GetInt(aID, &result))) {
 488       return aDefault;
 489     }
 490     return result;
 491   }
 492
 493   static float GetFloat(FloatID aID, float aDefault = 0.0f) {
 494     float result;
 495     if (NS_FAILED(GetFloat(aID, &result))) {
 496       return aDefault;
 497     }
 498     return result;
 499   }
 500
 501   /**
 502    * Retrieve the name and style of a system-theme font.  Returns true
 503    * if the system theme specifies this font, false if a default should
 504    * be used.  In the latter case neither aName nor aStyle is modified.
 505    *
 506    * Size of the font should be in CSS pixels, not device pixels.
 507    *
 508    * @param aID    Which system-theme font is wanted.
 509    * @param aName  The name of the font to use.
 510    * @param aStyle Styling to apply to the font.
 511    */
 512   static bool GetFont(FontID aID, nsString& aName, gfxFontStyle& aStyle);
 513
 514   /**
 515    * GetPasswordCharacter() returns a unicode character which should be used
 516    * for a masked character in password editor.  E.g., '*'.
 517    */
 518   static char16_t GetPasswordCharacter();
 519
 520   /**
 521    * If the latest character in password field shouldn't be hidden by the
 522    * result of GetPasswordCharacter(), GetEchoPassword() returns TRUE.
 523    * Otherwise, FALSE.
 524    */
 525   static bool GetEchoPassword();
 526
 527   /**
 528    * The millisecond to mask password value.
 529    * This value is only valid when GetEchoPassword() returns true.
 530    */
 531   static uint32_t GetPasswordMaskDelay();
 532
 533   /** Gets theme information for about:support */
 534   static void GetThemeInfo(nsACString&);
 535
 536   /**
 537    * When system look and feel is changed, Refresh() must be called.  Then,
 538    * cached data would be released.
 539    */
 540   static void Refresh();
 541
 542   /**
 543    * GTK's initialization code can't be run off main thread, call this
 544    * if you plan on using LookAndFeel off main thread later.
 545    *
 546    * This initialized state may get reset due to theme changes, so it
 547    * must be called prior to each potential off-main-thread LookAndFeel
 548    * call, not just once.
 549    */
 550   static void NativeInit();
 551
 552   static void SetData(widget::FullLookAndFeel&& aTables);
 553   static void NotifyChangedAllWindows(widget::ThemeChangeKind);
 554 };
 555
 556 }  // namespace mozilla
 557
 558 // ---------------------------------------------------------------------
 559 //  Special colors for ColorID::IME* and ColorID::SpellCheckerUnderline
 560 // ---------------------------------------------------------------------
 561
 562 // For background color only.
 563 constexpr nscolor NS_TRANSPARENT = NS_RGBA(0x01, 0x00, 0x00, 0x00);
 564 // For foreground color only.
 565 constexpr nscolor NS_SAME_AS_FOREGROUND_COLOR = NS_RGBA(0x02, 0x00, 0x00, 0x00);
 566 constexpr nscolor NS_40PERCENT_FOREGROUND_COLOR =
 567     NS_RGBA(0x03, 0x00, 0x00, 0x00);
 568
 569 #define NS_IS_SELECTION_SPECIAL_COLOR(c)                          \
 570   ((c) == NS_TRANSPARENT || (c) == NS_SAME_AS_FOREGROUND_COLOR || \
 571    (c) == NS_40PERCENT_FOREGROUND_COLOR)
 572
 573 // ------------------------------------------
 574 //  Bits for IntID::AlertNotificationOrigin
 575 // ------------------------------------------
 576
 577 #define NS_ALERT_HORIZONTAL 1
 578 #define NS_ALERT_LEFT 2
 579 #define NS_ALERT_TOP 4
 580
 581 #endif /* __LookAndFeel */