Functions | |
void | Begin_Color_Name_Search (void) |
These routines recall all the defined color names. More... | |
void | Show_Color_Name_Count (int *count) |
Finds out how many color names will be returned. This is useful for determining the size of a data structure needed to store incoming items. More... | |
HC_BOOLEAN | Find_Color_Name (char *name, char *er_name, char *ish_name) |
Retrieves the color names, one at a time. The function returns false when all color names have been returned. More... | |
void | End_Color_Name_Search (void) |
Terminates the color name search sequence and frees any involved memory. More... | |
void Begin_Color_Name_Search | ( | void | ) |
These routines recall all the defined color names.
These routines are used to find all the color definitions in the database. For example,
Begin_Color_Name_Search () while (Find_Color_Name (first, second, third) print (first, second, third) End_Color_Name_Search ()
prints all the known names, in the style in which they were originally defined. Begin_Color_Name_Search() initiates the search for color names.
If you need to know how many color definitions will be returned (possibly for allocating a data structure to hold them) call Show_Color_Name_Count() after initiating the search.
Find_Color_Name() returns the names (one set at a time). The function returns false when all color names have been returned.
End_Color_Name_Search() terminates the process and frees any involved memory. This last step can be done any time after the initial call to Begin_Color_Name_Search() .
If you want to examine the color name definitions, call Parse_String() (to take out the commas) on the results of Find_Color_Name() . Then call Show_Color_Name() on each name.
After calling Begin_Color_Name_Search() , if a color becomes undefined (via UnDefine_Color_Name() ), subsequent calls to Find_Color_Name() will not return it. If a color is redefined, the new definition will be returned. If a new color is defined, it will not be returned in this search sequence.
Show_Color_Name_Count() is only valid between Begin_Color_Name_Search() and End_Color_Name_Search() . It will always return the total number of colors defined, not the remaining number of color definitions.
Color name searches can be nested. A user program can call Begin_Color_Name_Search() and look at the defined color names without interfering with a color name search, which might have been activated by another portion of the program. When End_Color_Name_Search() is called, the previously active color name search (if any) becomes current.
void End_Color_Name_Search | ( | void | ) |
Terminates the color name search sequence and frees any involved memory.
No additional details. See Begin_Color_Name_Search()
HC_BOOLEAN Find_Color_Name | ( | char * | name, |
char * | er_name, | ||
char * | ish_name | ||
) |
Retrieves the color names, one at a time. The function returns false when all color names have been returned.
name | - Simple name from the list of definitions. Returned to user. Passed by reference always. |
er_name | - The "er" (1st degree) combining form (if any) of the name above. Returned to user. Passed by reference always. |
ish_name | - The "ish" (2nd degree) combining form (if any). Returned to user. Passed by reference always. |
No additional details. See Begin_Color_Name_Search()
void Show_Color_Name_Count | ( | int * | count | ) |
Finds out how many color names will be returned. This is useful for determining the size of a data structure needed to store incoming items.
count | - The total number of color names returned by Find_Color_Name() . Returned to user. Passed by reference always. |
No additional details. See Begin_Color_Name_Search()