Brief Index      Full Index      Events Index      I.M. Reference

Begin_Color_Name_Search


Functions

void Begin_Color_Name_Search (void)
void Show_Color_Name_Count (int *count)
HC_BOOLEAN Find_Color_Name (char *name, char *er_name, char *ish_name)
void End_Color_Name_Search (void)

Function Documentation

void Begin_Color_Name_Search ( void   ) 

These routines recall all the defined color names.

DETAILS

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() .

NOTES

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.

RESTRICTIONS

See also:
Define_Color_Name, Show_Color_Name, Parse_String

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.

Parameters:
count - The total number of color names returned by Find_Color_Name() . Returned to user. Passed by reference always.

DETAILS

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.

Parameters:
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.
Returns:
flag

DETAILS

No additional details. See Begin_Color_Name_Search()

void End_Color_Name_Search ( void   ) 

Terminates the color name search sequence and frees any involved memory.

DETAILS

No additional details. See Begin_Color_Name_Search()

Brief Index      Full Index      Events Index      I.M. Reference