suggestion for Color, $COLOR:0, $COLOR:32 pages

[madscijr]

In the past few months I noticed programs using actual color names in the color statements, 
I guess these were added to QB64PE somewhere along the way? 

This is great since I can eliminate those color name functions I'd been using!

I googled QB64PE color names and found them documented at 
$COLOR:0
$COLOR:32

however there wasn't any example or explanation that to get them to work you have to use the command 
e.g., $COLOR:0

Also the entry for Color in the wiki doesn't really mention them or have any examples with them. 
$COLOR:0 and $COLOR:32 are in the "see also" list at the bottom, but it's kind of left to the reader to figure that out. 

I would suggest adding them to the examples and/or explanation of those pages...

Code: (Select All)

' $COLOR:0 Name Table
' https://qb64phoenix.com/qb64wiki/resources/Color0.html

' compare the built in $COLOR:0 colors
' with the functions I was using as a sanity check

Dim RowNum As Integer
$Color:0
Cls , Black

RowNum = 0
Color cWhiteT&: PrintCol1 "$Color:0 NAMES", RowNum
Color cWhiteT&: PrintCol1 "--------------", RowNum
Color Black, White: PrintCol1 "Black", RowNum
Color Blue, Black: PrintCol1 "Blue", RowNum
Color Green: PrintCol1 "Green", RowNum
Color Cyan: PrintCol1 "Cyan", RowNum
Color Red: PrintCol1 "Red", RowNum
Color Magenta: PrintCol1 "Magenta", RowNum
Color Brown: PrintCol1 "Brown", RowNum
Color White: PrintCol1 "White", RowNum
Color Gray: PrintCol1 "Gray", RowNum
Color LightBlue: PrintCol1 "LightBlue", RowNum
Color LightGreen: PrintCol1 "LightGreen", RowNum
Color LightCyan: PrintCol1 "LightCyan", RowNum
Color LightRed: PrintCol1 "LightRed", RowNum
Color LightMagenta: PrintCol1 "LightMagenta", RowNum
Color Yellow: PrintCol1 "Yellow", RowNum
Color BrightWhite: PrintCol1 "BrightWhite", RowNum

RowNum = 0
Color cWhiteT&: PrintCol2 "MADSCIJR COLORS", RowNum
Color cWhiteT&: PrintCol2 "---------------", RowNum
Color cBlackT&, cWhiteT&: PrintCol2 "cBlackT&", RowNum
Color cBlueT&, cBlackT&: PrintCol2 "cBlueT&", RowNum
Color cGreenT&: PrintCol2 "cGreenT&", RowNum
Color cLtBlueT&: PrintCol2 "cLtBlueT&", RowNum
Color cRedT&: PrintCol2 "cRedT&", RowNum
Color cPurpleT&: PrintCol2 "cPurpleT&", RowNum
Color cOrangeT&: PrintCol2 "cOrangeT&", RowNum
Color cWhiteT&: PrintCol2 "cWhiteT&", RowNum
Color cGrayT&: PrintCol2 "cGrayT&", RowNum
Color cPeriwinkleT&: PrintCol2 "cPeriwinkleT&", RowNum
Color cLtGreenT&: PrintCol2 "cLtGreenT&", RowNum
Color cCyanT&: PrintCol2 "cCyanT&", RowNum
Color cLtRedT&: PrintCol2 "cLtRedT&", RowNum
Color cPinkT&: PrintCol2 "cPinkT&", RowNum
Color cYellowT&: PrintCol2 "cYellowT&", RowNum
Color cLtGrayT&: PrintCol2 "cLtGrayT&", RowNum

PrintCol1 "PRESS ANY KEY TO EXIT", RowNum + 1
Sleep: System

Sub PrintCol1 (MyString$, RowNum%)
    RowNum% = RowNum% + 1
    Locate RowNum%, 1: Print MyString$;
End Sub

Sub PrintCol2 (MyString$, RowNum%)
    RowNum% = RowNum% + 1
    Locate RowNum%, 20: Print MyString$;
End Sub

' ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
' BEGIN TEXT MODE COLOR CODE FUNCTIONS <- these can be eliminated with $Color:0 !!!
' ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Function cBlackT&
    cBlackT& = 0
End Function

Function cBlueT&
    cBlueT& = 1
End Function

Function cGreenT&
    cGreenT& = 2
End Function

Function cLtBlueT&
    cLtBlueT& = 3
End Function

Function cRedT&
    cRedT& = 4
End Function

Function cPurpleT&
    cPurpleT& = 5
End Function

Function cOrangeT&
    cOrangeT& = 6
End Function

Function cWhiteT&
    cWhiteT& = 7
End Function

Function cGrayT&
    cGrayT& = 8
End Function

Function cPeriwinkleT&
    cPeriwinkleT& = 9
End Function

Function cLtGreenT&
    cLtGreenT& = 10
End Function

Function cCyanT&
    cCyanT& = 11
End Function

Function cLtRedT&
    cLtRedT& = 12
End Function

Function cPinkT&
    cPinkT& = 13
End Function

Function cYellowT&
    cYellowT& = 14
End Function

Function cLtGrayT&
    cLtGrayT& = 15
End Function
' ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
' END TEXT MODE COLOR CODE FUNCTIONS
' ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

[SMcNeill]

You missed their entry in the wiki apparently:  https://qb64phoenix.com/qb64wiki/index.php/$COLOR

[RhoSigma]

And the $COLOR meta-command is mentioned 1st in the "See also" section of the COLOR page.

[madscijr]

Yes, but I would argue that including an example on the page for Color would be helpful, since it directly relates to that command...

[RhoSigma]

Yes, but I would argue that including an example on the page for Color would be helpful, since it directly relates to that command...

Rather no, it does not directly relate to COLOR, it's an far later convenience feature added with the $COLOR meta-command (and there are the examples), but as it indirectly relates to the legacy COLOR command, as it makes things easier, it's also added to the "See also" section of COLOR.

The real problem I see here is that people doesn't take the time to read a wiki page carefully from top 'til bottom and by that they are missing the essential bits of information they really look for. I already thought about reformatting all wiki pages placing the "See also" section at the top.

[madscijr]

That sounds like someone more interested in being semantically correct but missing the bigger point - good documentation makes it EASY for the reader. 

I think if we have a Color command that accepts color values, and there is a way to use the color word instead of a number, it is perfectly logical and helpful to have that information on the Color command's page. Why would a person click "see also" on Color$ when that link doesn't indicate anything about what it's for? Like maybe it could say, "Click here to learn about how to use the word Red for this command instead of the number 4"? 

Many "see also" links are useful, but if the reader is trying trying to zero in on specific information, they might not think to miander around and do a depth-first read of everything. 

To help, you put in a little more description.

[SMcNeill]

Honestly, in my opinion, the COLOR page should be purged of most of the junk on it on.  MY idea color page?

COLOR can be used to set the Foreground and Background colors.

That's it.  All the junk about Screen Mode Attributes should go to its own page.  Read & write color port intensities with INP & OUT... is again, NOT really about COLOR at all but about one use for INP and OUT.  Those should be gone, with nothing more than a link referring to them on their own respective page.

Example 1 on the page... DOESN'T EVEN HAVE THE COLOR command in it!  WTF is it there??  Example 1: Reading the default RGB color settings of color attribute 15.

Same with Example 2.

As for $COLOR, it needs to stay on its own separate page as well.  There's just too much info jumbled onto the page that has nothing to do with the command itself.

Why document COLOR Red to be red with $COLOR:32, and then not bother to document:
COLOR 4 is RED in SCREEN 0
COLOR 40 is RED in SCREEN 12
COLOR _RGB32(255, 0, 0) is RED in 32-bit SCREENS.
COLOR _RGB(255, 0, 0) is the closest approximation to red in any screen mode that has red in its palette.
COLOR Red is Red in SCREEN 0 *IF* $COLOR:0 is set, and is Red in 32-bit screens *IF* $COLOR:32 is set, otherwise it defaults to color 0...

And, of course, one would have to do that same breakdown for every color and every value and... /gah!!

And none of that has to do with the simpleness of what color actually does!!

COLOR can be used to set the Foreground and Background colors.

That's basically all that page needs to tell you.  The rest is just SEE ALSO.

Folks miss the really important stuff because it just gets buried beneath all the other crap. 

---

   

Also, see the highlighted version of the text above.  $COLOR is mentioned right there in the Description, along with what it does.  What more info does one need to realize, "Hey, I can use named colors with $COLOR"?

[RhoSigma]

Being systematicly, guilty your honor I'm german, and I guess nothing is more german than being systematicly.

Let's say I place a simple example on the COLOR page, eg:

COLOR White, Red
PRINT "this is white text on red background"

now someone like you comes and thinks oh cool, I didn't know this works, I'll copy the example and paste it in the IDE to try it out. But what, I only get a black screen, not even the "Press any key..." to end the program is there, does it hang.

No, White and Red are not defined, hence 0. So it sets COLOR 0,0 and prints the text.

You need the $COLOR:0|32 first, so that the color names get included and defined.

Now indeed, I certainly would include the $COLOR:0 in the beginning of my example, so it works. But now an unexperienced user wouldn't get the connection between the $COLOR metacommand and the color names, but would likely think he always needs to include the $COLOR in the beginning so he's able to use the COLOR command (like a main switch), but that's not true either. COLOR works without the $COLOR metacommand.

Doesn't matter of your POV, the COLOR command and the $COLOR metacommand serve two totally different purposes. One does actually set the colors in your program and the other just defines some named color CONSTs for your convenience, which you also could do yourself.

As a convenience addition $COLOR is mentioned several times on the COLOR page, but the examples regarding the use of the color names definitly belong to the $COLOR metacommand page, because only with that metacommand in effect COLOR White, Red works.

[PhilOfPerth]

Being systematicly, guilty your honor   I'm german, and I guess nothing is more german than being systematicly.

Let's say I place a simple example on the COLOR page, eg:

COLOR White, Red
PRINT "this is white text on red background"

now someone like you comes and thinks oh cool, I didn't know this works, I'll copy the example and paste it in the IDE to try it out. But what, I only get a black screen, not even the "Press any key..." to end the program is there, does it hang.

No, White and Red are not defined, hence 0. So it sets COLOR 0,0 and prints the text.

You need the $COLOR:0|32 first, so that the color names get included and defined.

Now indeed, I certainly would include the $COLOR:0 in the beginning of my example, so it works. But now an unexperienced user wouldn't get the connection between the $COLOR metacommand and the color names, but would likely think he always needs to include the $COLOR in the beginning so he's able to use the COLOR command (like a main switch), but that's not true either. COLOR works without the $COLOR metacommand.

Doesn't matter of your POV, the COLOR command and the $COLOR metacommand serve two totally different purposes. One does actually set the colors in your program and the other just defines some named color CONSTs for your convenience, which you also could do yourself.

As a convenience addition $COLOR is mentioned several times on the COLOR page, but the examples regarding the use of the color names definitly belong to the $COLOR metacommand page, because only with that metacommand in effect COLOR White, Red works.

Probably over-simplistic, but for my progs, I just add 3 or 4 Subs that define the colours I want to use:

Sub Red: 
Color _rgb(255,0,0)
End Sub

Then, in the prog I just write

Red: Print? "This is red"

Works for me! 

[madscijr]

All good points, I think removing extra stuff is fine, and putting the $color on its own page is fine, just as long as it's linked to with some context to give the reader a clue for what it's for. Microsoft's docs do that pretty well, like if a function accepts a parameter that has enumerated values, they say the name so you can go to the enumeration page and see what all the possible values are.