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