Begin_Highlight_Search

Functions

void Begin_Highlight_Search (int count, const HC_KEY *keys, const char *list)
 Searches for all highlights. More...
 
void Determine_Highlight_Status (int count, HC_KEY const *keys, int *results, char const *options)
 Determines if a particular key path invokes highlights. More...
 
void End_Highlight_Search ()
 Discards any remaining results from this search. More...
 
bool Find_Highlight (int *count, HC_KEY *keys, char *options)
 Returns the next highlight that was collected. More...
 
void Show_Highlight_Count (int *count, int *max_keys)
 Returns the number of distinct highlights collected, and the maximum number of keys that will be returned in the results to Find_Highlight(). More...
 

Detailed Description

Function Documentation

◆ Begin_Highlight_Search()

void Begin_Highlight_Search ( int  count,
const HC_KEY *  keys,
const char *  list 
)

Searches for all highlights.

Parameters
countLength of 'keys' array in parameter 2. Set count to zero if no path filtering is desired; otherwise the specified key path will be used to filter the results.
keysAn array of HC_KEYs defining an unambiguous path to the highlighted object. Set keys to zero if count is zero and no path filtering is desired.
listlist of styles, drawing mode, or passive/active highlight. See DETAILS section below.

DETAILS

Using the list parameter, the following filters can be applied to the highlight search:

  • style = (style name,...)
    • only collects highlights which match one of the specified style names
  • quick moves [=(off | inplace | overlay | spriting,...)]
    • only collect highlights which match one of the specified drawing modes; if no modes are specified (i.e., simply "quick moves"), (overlay,spriting) is assumed
  • passive = on | off
    • only highlights matching the specified passive state are collected
  • path match [= exact | above | below]
    • may be used to indicate whether the search only matches the path exactly (the default), matches highlights at or above the target along the path, or at or below the target along the path.
See also
Define_Highlight()

◆ Determine_Highlight_Status()

void Determine_Highlight_Status ( int  count,
HC_KEY const *  keys,
int *  results,
char const *  options 
)

Determines if a particular key path invokes highlights.

Parameters
countLength of 'keys' array in parameter 2
keysAn array of HC_KEYs defining an unambiguous path to the highlighted object
resultsReturns a bit-encoded integer for each of the input keys. See below for specific values.
optionsOptions to control the behavior of the function, can filter highlights in the same manner as in Begin_Highlight_Search()

DETAILS

The parameter results will be populated with a bit-encoded integer for each of the input keys, or a combination of these bitwise OR'd together:

  • 0 the corresponding key is NOT highlighted
  • 1 the corresponding key is the target of a highlight
  • 2 the key receives the effect of a tree highlight
  • 4 the key is along the path to the highlighted item(s)
  • 8 this bit is currently not in use
  • 16 the key is geometry with highlighted components

◆ End_Highlight_Search()

void End_Highlight_Search ( )

Discards any remaining results from this search.

DETAILS

No additional details.

◆ Find_Highlight()

bool Find_Highlight ( int *  count,
HC_KEY *  keys,
char *  options 
)

Returns the next highlight that was collected.

Parameters
count- count of distinct highlights collected. The count returned is the number of keys filled in for the highlight path.
keys- keys returned.
options- Options used to filter results. Can use "style=style name", "passive" to find only passive highlights, and "geometry" if Define_Geometry_Highlight() was used to specify highlighting of parts of a shell or mesh.
Returns
true if any keys were found, otherwise false

◆ Show_Highlight_Count()

void Show_Highlight_Count ( int *  count,
int *  max_keys 
)

Returns the number of distinct highlights collected, and the maximum number of keys that will be returned in the results to Find_Highlight().

Parameters
count- count of distinct highlights collected.
max_keys- maximum number of keys that will be returned in the results from a call to Find_Highlight().

DETAILS

No additional details.