Color Functionality as a Book Name

A color can be one of the following:

Unnamed color — An integer value that directly stores information about a color. An unnamed color is represented as a packed 32-bit integer value that stores the color method and color components. Assignment of components depends on the color method defined by RGB-value, index of a palette, or color of other object.
Named color — A string value that references a list which stores information about how to display a color. A named color represents a record of a color book that stores the corresponding color components and color names associated with them.

The OdCmEntityColor class supports only unnamed colors; the OdCmColor class supports both unnamed and named colors.

Color books contain third-party and user-defined swatches of custom colors, such as the DIC color guide or RAL color sets. Each color has a unique name in the book. Color books are organized alphabetically into pages, and a page holds up to ten colors. A color instance stores the color name that refers to the color definition in the color book. A color name is an arbitrary string that can be up to 255 characters long and can contain letters, digits, blank spaces, underscores, and some special characters, but can not contain inadmissible letters (see Naming objects). Color books are placed in special files, and one or more color books can be loaded in a program. Color books are used to enhance the presentation of drawings, to work with specific devices, and to optimize the ways of using colors.

The color object is declared by the following line:


OdCmColor nColor;

To get the color name, use the colorName() method that returns the color name as a value of the OdString type. For example:


odPrintConsoleString(L"\nColor name = %s", nColor.colorName().c_str());

To get the book name, use the colorBook() method that returns the book name as a value of the OdString type. For example:


odPrintConsoleString(L"\nBook name = %s", nColor.bookName().c_str());

To set the color name and color book together, use the setNames() method that requires the color name as a first argument of the OdString type, the color book as a second argument of the OdString type, and returns True when the result is successful. When the book name is not specified, the method assigns the book name as "UNNAMED". When the color name is not specified, the method ignores the specified values. For example:


nColor.colorNames(L"blue_gray", L"color_book");

To clear the color name and color book properties, pass empty strings as arguments of the setNames() method. As a result, the color instance becomes unnamed. For example:


nColor.colorNames(L"", L"");

An alternate way represents a color as an item of a dictionary, where the color is a keyword of a dictionary. The OdCmColor class uses the default implementation of this color format.

To get the color keyword, use the getDictionaryKey() method that returns the keyword associated with a color. This method has the default implementation that returns the combination of the book name and color name joined by the dollar '$' symbol as a value of the OdString type. For example:


odPrintConsoleString(L"\nDictionary Key = %s", nColor.getDictionaryKey().c_str());

To set the color keyword, use the setNamesFromDictionaryKey() method that sets the keyword for the color instance. This method has the default implementation that sets the book name and color name using the string of their combination joined by the dollar '$' symbol as a value of the OdString type. For example:


nColor.setNamesFromDictionaryKey(L"my_book$my_gray");

Note: The color name must be present in a color keyword. If the book name is not present in the color keyword, this method sets the "UNNAMED" book name.

The database color requirement has a name called the display name. When a color instance is named, its display name coincides with its color name in the color book. When a color instance is unnamed, its name depends on the color method. If the color method is byLayer, the display name is "BYLAYER". If the color method is byBlock, the display name is "BYBLOCK". If the color method is byColor, the display name is the three integer values separated by commas in order of red, green, and blue components. If the color method is byACI, the display name is the color index or one of the predefined names: "red", "yellow", "green", "cyan", "blue", "magenta", "white". If the color method is None, the display name is "None". To get the display name, use the colorNameForDisplay() method that returns the display name of a color as a value of the OdString type. For example:


odPrintConsoleString(L"\nDisplay name = %s", nColor.colorNameForDisplay().c_str());

To convert the named color to an entity color, use the entityColor() method that returns the color as the OdCmEntityColor object. For example:


OdCmEntityColor eColor = nColor.entityColor();

odPrintConsoleString(L"\nColor integer value = %x", eColor.color());

Note: The getDescription() and getExplanation() methods do not have a specific implementation and return an empty string.

The comparing of named colors differs from comparing unnamed colors and entity colors. When the (==) and (!=) operators compare two named color instances, they take into account the book name, color name, color method, and color components. If two named color instances have the same integer values, that is, their color methods and color components coincide, but they differ by color names or book names, they are different. If two named color instances have the same name, they are compared as entity colors, that is, by integer values. For example:


OdCmColor nColorX, nColorY; 

nColorX.setRGB(10, 11, 12);
nColorY.setRGB(12, 11, 10);
odPrintConsoleString(L"\n[%x] (%s) == [%x] (%s) => %s", nColorX.color(), nColorX.getDictionaryKey().c_str(),
            nColorY.color(), nColorY.getDictionaryKey().c_str(), ((nColorX == nColorY) ? L"true" : L"false"));

// [0xC20A0B0C] () == [0xC20C0B0A] () => false

nColorX.setRGB(6, 10, 14);
nColorY.setRGB(6, 10, 14);
odPrintConsoleString(L"\n[%x] (%s) == [%x] (%s) => %s", nColorX.color(), nColorX.getDictionaryKey().c_str(),
            nColorY.color(), nColorY.getDictionaryKey().c_str(), ((nColorX == nColorY) ? L"true" : L"false"));

// [0xC2060A0E] () == [0xC2060A0E] () => true

nColorX.setNames(L"xname", L"mybook");
nColorX.setNames(L"xname", L"mybook");

odPrintConsoleString(L"\n[%x] (%s) == [%x] (%s) => %s", nColorX.color(), nColorX.getDictionaryKey().c_str(),
            nColorY.color(), nColorY.getDictionaryKey().c_str(), ((nColorX == nColorY) ? L"true" : L"false"));

// [0xC2060A0E] (mybook$xname) == [0xC2060A0E] (mybook$xname) => true

nColorX.setNames(L"aaa", L"mybook");
nColorX.setNames(L"bbb", L"mybook");

odPrintConsoleString(L"\n[%x] (%s) == [%x] (%s) => %s", nColorX.color(), nColorX.getDictionaryKey().c_str(),
            nColorY.color(), nColorY.getDictionaryKey().c_str(), ((nColorX == nColorY) ? L"true" : L"false"));

// [0xC2060A0E] (mybook$aaa) == [0xC2060A0E] (mybook$bbb) => false

nColorX.nColorX.setRGB(10, 11, 12);
nColorX.setNames(L"aaa", L"mybook");

odPrintConsoleString(L"\n[%x] (%s) == [%x] (%s) => %s", nColorX.color(), nColorX.getDictionaryKey().c_str(),
            nColorY.color(), nColorY.getDictionaryKey().c_str(), ((nColorX == nColorY) ? L"true" : L"false"));

// [0xC20A0B0C] (mybook$aaa) == [0xC2060A0E] (mybook$aaa) => false

To compare two named color instances as integer values, use the entityColor() method to get their entity colors and the (==) and (!=) operators to compare them as integer values. For example:


odPrintConsoleString(L"\n[%x] == [%x] => %s", nColorX.entityColor().color(), nColorY.entityColor().color(),
                     ((nColorX.entityColor() == nColorY.entityColor()) ? L"true" : L"false"));

The assignment operator of named colors copies the color value from one instance to another instance, keeping the color name, book name, color method, and color components.

See Also