Document new rgb_color apis, apply their usage.

Change-Id: I48f1bedd3abfb3b445c1c7090ce43504bcff4537
Reviewed-on: https://review.haiku-os.org/c/haiku/+/7485
Reviewed-by: waddlesplash <waddlesplash@gmail.com>

docs/user/interface/GraphicsDefs.dox

@@ -7,7 +7,7 @@
  *		Niels Sascha Reedijk, niels.reedijk@gmail.com
  *
  * Corresponds to:
- *		headers/os/interface/GraphicsDefs.h	hrev54374
+ *		headers/os/interface/GraphicsDefs.h	hrev57597
  *		src/kits/interface/GraphicsDefs.cpp	hrev49977
  */
 
@@ -202,14 +202,45 @@
 	\fn int32 rgb_color::Brightness() const
 	\brief Calculates a value representing the brightness of this color.
 
-	This method uses a fast algorithm to calculate the brightness in Luma of
+	This method calculates the perceptual brightness of a color.
-	the color.
 
-	\return A value representing the brightness.
+	\return A value representing the brightness. (0-255)
 
 	\since Haiku R1
 */
 
+/*!
+	\fn bool rgb_color::IsLight() const
+	\brief Determines if the color is light.
+
+	A color is considered 'light' if its Brightness() is > 127.
+
+	\since Haiku R1
+*/
+
+/*!
+	\fn bool rgb_color::IsDark() const
+	\brief Determines if the color is dark.
+
+	A color is considered 'dark' if its Brightness() is <= 127.
+
+	\since Haiku R1
+*/
+
+/*!
+	\fn static int32 rgb_color::Contrast(rgb_color colorA, rgb_color colorB)
+	\brief Calculates the contrast between two colors.
+
+	This method compares the Brightness of colorA and colorB and returns
+	the Contrast that is between them.
+
+	For example this can used to make sure a color combination is legible
+	on a specifc background.
+
+	\return A value representing the Contrast. (0-255)
+
+	\since Haiku R1
+*/
 
 /*!
 	\fn rgb_color make_color(uint8 red, uint8 green, uint8 blue, uint8 alpha=255)

src/add-ons/control_look/BeControlLook/BeControlLook.cpp

@@ -1952,7 +1952,7 @@ BeControlLook::DrawBorder(BView* view, BRect& rect, const BRect& updateRect,
 
 	rgb_color lightColor;
 	rgb_color shadowColor;
-	if (base.Brightness() > 128) {
+	if (base.IsLight()) {
 		lightColor = tint_color(base, B_DARKEN_2_TINT);
 		shadowColor = tint_color(base, B_LIGHTEN_2_TINT);
 	} else {
@@ -2221,7 +2221,7 @@ BeControlLook::DrawLabel(BView* view, const char* label, const rgb_color& base,
 
 	if (isDesktop) {
 		// enforce proper use of desktop label colors
-		if (low.Brightness() < 100) {
+		if (low.IsDark()) {
 			if (textColor == NULL)
 				color = make_color(255, 255, 255);
 
@@ -2259,7 +2259,7 @@ BeControlLook::DrawLabel(BView* view, const char* label, const rgb_color& base,
 			view->SetDrawingMode(B_OP_ALPHA);
 			view->SetBlendingMode(B_CONSTANT_ALPHA, B_ALPHA_OVERLAY);
 			// Draw glow or outline
-			if (glowColor.Brightness() > 128) {
+			if (glowColor.IsLight()) {
 				font.SetFalseBoldWidth(2.0);
 				view->SetFont(&font, B_FONT_FALSE_BOLD_WIDTH);
 

src/add-ons/control_look/FlatControlLook/FlatControlLook.cpp

@@ -366,7 +366,6 @@ FlatControlLook::DrawScrollBarButton(BView* view, BRect rect,
 	if (!ShouldDraw(view, rect, updateRect))
 		return;
 
-	bool dark = (base.Brightness() < 127);
 	rgb_color arrowColor;
 
 	bool isEnabled = (flags & B_DISABLED) == 0;
@@ -374,13 +373,13 @@ FlatControlLook::DrawScrollBarButton(BView* view, BRect rect,
 	if (isEnabled) {
 		arrowColor = tint_color(ui_color(B_CONTROL_TEXT_COLOR), 0.6);
 		// if the base color is too dark, then lets make it lighter
-		if (dark) {
+		if (base.IsDark()) {
 			arrowColor = tint_color(ui_color(B_CONTROL_TEXT_COLOR), 1.3);;
 		}
 	} else {
 		arrowColor = tint_color(ui_color(B_CONTROL_TEXT_COLOR), 0.4);
 		// if the base color is too dark, then lets make it lighter
-		if (dark) {
+		if (base.IsDark()) {
 			arrowColor = tint_color(ui_color(B_CONTROL_TEXT_COLOR), 1.5);;
 		}
 	}
@@ -718,13 +717,8 @@ FlatControlLook::DrawScrollViewFrame(BView* view, BRect& rect,
 rgb_color
 FlatControlLook::SliderBarColor(const rgb_color& base)
 {
-	rgb_color customColor = tint_color(ui_color(B_PANEL_BACKGROUND_COLOR), 1.05);
+	return base.IsLight() ? tint_color(ui_color(B_PANEL_BACKGROUND_COLOR), 1.05) :
-	// if the color BACKGROUND used is too dark, then make it lighter using the
+		tint_color(ui_color(B_PANEL_BACKGROUND_COLOR), 0.95);
-	// same as B_CONTROL_TEXT_COLOR
-	if (base.Brightness() < 127)
-		customColor = tint_color(ui_color(B_PANEL_BACKGROUND_COLOR), 0.95);
-
-	return customColor;
 }
 
 
@@ -936,11 +930,11 @@ FlatControlLook::DrawSliderThumb(BView* view, BRect& rect, const BRect& updateRe
 	// figure out frame color
 	rgb_color frameLightColor;
 	rgb_color frameShadowColor;
-	rgb_color shadowColor = tint_color(ui_color(B_CONTROL_TEXT_COLOR), 0.5);
+	rgb_color shadowColor;
 
-	// If the color BACKGROUND used is too dark, then make it lighter using the same as
+	if (base.IsLight())
-	// B_CONTROL_TEXT_COLOR
+		shadowColor = tint_color(ui_color(B_CONTROL_TEXT_COLOR), 0.5);
-	if (base.Brightness() < 127)
+	else
 		shadowColor = tint_color(ui_color(B_CONTROL_TEXT_COLOR), 1.55);
 
 	if ((flags & B_FOCUSED) != 0) {
@@ -1339,7 +1333,7 @@ FlatControlLook::DrawTextControlBorder(BView* view, BRect& rect,
 	dark1BorderColor = tint_color(customColor2, 0.5);
 
 	if ((flags & B_DISABLED) == 0 && (flags & B_FOCUSED) != 0) {
-		if (base.Brightness() < 127)
+		if (base.IsDark())
 			documentBackground = tint_color(documentBackground, 0.9);
 		else
 			documentBackground = tint_color(documentBackground, 1.5);
@@ -1370,8 +1364,7 @@ FlatControlLook::DrawGroupFrame(BView* view, BRect& rect, const BRect& updateRec
 {
 	rgb_color frameColor = tint_color(base, 1.1);
 
-	// if the base color is too dark, then lets make it lighter
+	if (base.IsDark())
-	if (base.Brightness() < 127)
 		frameColor = tint_color(base, 0.95);
 
 	// Draws only one flat frame:
@@ -1427,9 +1420,7 @@ FlatControlLook::_DrawButtonFrame(BView* view, BRect& rect,
 	rgb_color customColor = background; // custom color for borders
 	rgb_color customColor2 = tint_color(background, 1.3);
 
-	// if the color BACKGROUND used is too dark, then make it lighter using
+	if (base.IsDark())
-	// the same as B_CONTROL_TEXT_COLOR
-	if (base.Brightness() < 127)
 		customColor2 = tint_color(ui_color(B_CONTROL_TEXT_COLOR), 1.5);
 
 
@@ -1842,10 +1833,12 @@ FlatControlLook::_DrawMenuFieldBackgroundOutside(BView* view, BRect& rect,
 	if (!ShouldDraw(view, rect, updateRect))
 		return;
 
-	bool dark = (base.Brightness() < 127);
+	rgb_color indicatorColor;
-	rgb_color indicatorColor = tint_color(base, 1.05);
+
-	if (dark)
+	if (base.IsDark())
 		indicatorColor = tint_color(base, 0.95);
+	else
+		indicatorColor = tint_color(base, 1.05);
 
 	if (popupIndicator) {
 		const float indicatorWidth = ComposeSpacing(kButtonPopUpIndicatorWidth);

src/apps/deskbar/Switcher.cpp

@@ -1345,7 +1345,7 @@ TBox::Draw(BRect update)
 	rgb_color veryDarkGray = {128, 128, 128, 255};
 	rgb_color darkGray = tint_color(panelColor, B_DARKEN_1_TINT);
 
-	if (panelColor.Brightness() < 100) {
+	if (panelColor.IsDark()) {
 		standardGray = tint_color(panelColor, 0.8);
 		darkGray = tint_color(panelColor, 0.85);
 		white = make_color(200, 200, 200, 255);
@@ -1435,7 +1435,7 @@ TBox::DrawIconScrollers(bool force)
 	rgb_color backgroundColor;
 	rgb_color dark;
 
-	if (panelColor.Brightness() > 100) {
+	if (panelColor.IsLight()) {
 		backgroundColor = tint_color(panelColor, B_DARKEN_1_TINT);
 		dark = tint_color(backgroundColor, B_DARKEN_3_TINT);
 	} else {
@@ -1517,7 +1517,7 @@ TBox::DrawWindowScrollers(bool force)
 	rgb_color backgroundColor;
 	rgb_color dark;
 
-	if (panelColor.Brightness() > 100) {
+	if (panelColor.IsLight()) {
 		backgroundColor = tint_color(panelColor, B_DARKEN_1_TINT);
 		dark = tint_color(backgroundColor, B_DARKEN_2_TINT);
 	} else {
@@ -1940,8 +1940,7 @@ TIconView::AnimateIcon(const BBitmap* start, const BBitmap* end)
 	fOffBitmap->Lock();
 
 	rgb_color bg = ui_color(B_PANEL_BACKGROUND_COLOR);
-	fOffView->SetHighColor(tint_color(bg, bg.Brightness() > 100
+	fOffView->SetHighColor(tint_color(bg, bg.IsLight() ? B_DARKEN_1_TINT : 0.85));
-		? B_DARKEN_1_TINT : 0.85));
 
 	// animate start icon
 	for (int i = 0; i < 2; i++) {
@@ -2093,7 +2092,7 @@ TIconView::DrawTeams(BRect update)
 	float tint = B_NO_TINT;
 	rgb_color panelColor = ui_color(B_PANEL_BACKGROUND_COLOR);
 
-	if (panelColor.Brightness() < 100)
+	if (panelColor.IsDark())
 		tint = 0.85;
 	else
 		tint = B_DARKEN_1_TINT;

src/apps/deskcalc/CalcView.cpp

@@ -1378,13 +1378,13 @@ CalcView::_Colorize()
 {
 	if (fHasCustomBaseColor) {
 		// keypad text color
-		if (fBaseColor.Brightness() > 100)
+		if (fBaseColor.IsLight())
 			fButtonTextColor = (rgb_color){ 0, 0, 0, 255 };
 		else
 			fButtonTextColor = (rgb_color){ 255, 255, 255, 255 };
 
 		// expression text color
-		if (fExpressionBGColor.Brightness() > 100)
+		if (fExpressionBGColor.IsLight())
 			fExpressionTextColor = (rgb_color){ 0, 0, 0, 255 };
 		else
 			fExpressionTextColor = (rgb_color){ 255, 255, 255, 255 };

src/apps/drivesetup/DiskView.cpp

@@ -546,7 +546,7 @@ DiskView::Draw(BRect updateRect)
 
 	FillRoundRect(messageBounds, 4, 4, B_SOLID_LOW);
 	rgb_color color = LowColor();
-	if (color.Brightness() > 100)
+	if (color.IsLight())
 		color = tint_color(color, B_DARKEN_4_TINT);
 	else
 		color = tint_color(color, B_LIGHTEN_2_TINT);

src/apps/powerstatus/PowerStatusView.cpp

@@ -181,7 +181,7 @@ PowerStatusView::_DrawBattery(BView* view, BRect rect)
 	lightningRect.left = rect.left;
 	lightningRect.InsetBy(0.0f, 5.0f * rect.Height() / 16);
 
-	if (view->LowColor().Brightness() > 100)
+	if (view->LowColor().IsLight())
 		view->SetHighColor(0, 0, 0);
 	else
 		view->SetHighColor(128, 128, 128);
@@ -219,7 +219,7 @@ PowerStatusView::_DrawBattery(BView* view, BRect rect)
 	if (fHasBattery) {
 		// draw unfilled area
 		rgb_color unfilledColor = make_color(0x4c, 0x4c, 0x4c);
-		if (view->LowColor().Brightness() < 128) {
+		if (view->LowColor().IsDark()) {
 			unfilledColor.red = 256 - unfilledColor.red;
 			unfilledColor.green = 256 - unfilledColor.green;
 			unfilledColor.blue = 256 - unfilledColor.blue;

src/apps/webpositive/URLInputGroup.cpp

@@ -376,7 +376,7 @@ URLInputGroup::URLTextView::InsertText(const char* inText, int32 inLength,
 	GetFont(&font);
 	const rgb_color hostColor = ui_color(B_DOCUMENT_TEXT_COLOR);
 	const rgb_color urlColor = tint_color(hostColor,
-		(hostColor.Brightness() < 128 ? B_LIGHTEN_1_TINT : B_DARKEN_1_TINT));
+		(hostColor.IsDark() ? B_LIGHTEN_1_TINT : B_DARKEN_1_TINT));
 	if (baseUrlStart > 0)
 		SetFontAndColor(0, baseUrlStart, &font, B_FONT_ALL, &urlColor);
 	if (baseUrlEnd > baseUrlStart) {

src/kits/interface/HaikuControlLook.cpp

@@ -2232,7 +2232,7 @@ HaikuControlLook::DrawLabel(BView* view, const char* label, const rgb_color& bas
 
 	if (isDesktop) {
 		// enforce proper use of desktop label colors
-		if (low.Brightness() < 100) {
+		if (low.IsDark()) {
 			if (textColor == NULL)
 				color = make_color(255, 255, 255);
 
@@ -2270,7 +2270,7 @@ HaikuControlLook::DrawLabel(BView* view, const char* label, const rgb_color& bas
 			view->SetDrawingMode(B_OP_ALPHA);
 			view->SetBlendingMode(B_CONSTANT_ALPHA, B_ALPHA_OVERLAY);
 			// Draw glow or outline
-			if (glowColor.Brightness() > 128) {
+			if (glowColor.IsLight()) {
 				font.SetFalseBoldWidth(2.0);
 				view->SetFont(&font, B_FONT_FALSE_BOLD_WIDTH);
 

src/kits/interface/StatusBar.cpp

@@ -323,7 +323,7 @@ BStatusBar::Draw(BRect updateRect)
 		rgb_color textColor = ui_color(B_PANEL_TEXT_COLOR);
 
 		if (backgroundColor != ui_color(B_PANEL_BACKGROUND_COLOR)) {
-			if (backgroundColor.Brightness() > 100)
+			if (backgroundColor.IsLight())
 				textColor = make_color(0, 0, 0, 255);
 			else
 				textColor = make_color(255, 255, 255, 255);

src/kits/tracker/TextWidget.cpp

@@ -667,7 +667,7 @@ BTextWidget::Draw(BRect eraseRect, BRect textRect, float, BPoseView* view,
 		drawView->GetFont(&font);
 
 		rgb_color textColor = view->TextColor();
-		if (textColor.Brightness() < 100) {
+		if (textColor.IsDark()) {
 			// dark text on light outline
 			rgb_color glowColor = ui_color(B_SHINE_COLOR);