Function EnumControlFind

source/window.cpp:926–996

BOOL CALLBACK EnumControlFind(HWND aWnd, LPARAM lParam)
{
	WindowSearch &ws = *(WindowSearch *)lParam;  // For performance and convenience.
	if (*ws.mCriterionClass) // Caller told us to search by class name and number.
	{
		int length = GetClassName(aWnd, ws.mCandidateTitle, WINDOW_CLASS_SIZE); // Restrict the length to a small fraction of the buffer's size (also serves to leave room to append the sequence number).
		// Below: i.e. this control's title (e.g. List) in contained entirely
		// within the leading part of the user specified title (e.g. ListBox).
		// Even though this is incorrect, the appending of the sequence number
		// in the second comparison will weed out any false matches.
		// Note: since some controls end in a number (e.g. SysListView32),
		// it would not be easy to parse out the user's sequence number to
		// simplify/accelerate the search here.  So instead, use a method
		// more certain to work even though it's a little ugly.  It's also
		// necessary to do this in a way functionally identical to the below
		// so that Window Spy's sequence numbers match the ones generated here:
		// Concerning strnicmp(), see lstrcmpi note below for why a locale-insensitive match isn't done instead.
		if (length && !_tcsnicmp(ws.mCriterionClass, ws.mCandidateTitle, length)) // Preliminary match of base class name.
		{
			// mAlreadyVisitedCount was initialized to zero by WindowSearch's constructor.  It is used
			// to accumulate how many quasi-matches on this class have been found so far.  Also,
			// comparing ws.mAlreadyVisitedCount to atoi(ws.mCriterionClass + length) would not be
			// the same as the below examples such as the following:
			// Say the ClassNN being searched for is List01 (where List0 is the class name and 1
			// is the sequence number). If a class called "List" exists in the parent window, it
			// would be found above as a preliminary match.  The below would copy "1" into the buffer,
			// which is correctly deemed not to match "01".  By contrast, the atoi() method would give
			// the wrong result because the two numbers are numerically equal.
			_itot(++ws.mAlreadyVisitedCount, ws.mCandidateTitle, 10);  // Overwrite the buffer to contain only the count.
			// lstrcmpi() is not used: 1) avoids breaking existing scripts; 2) provides consistent behavior
			// across multiple locales:
			if (!_tcsicmp(ws.mCandidateTitle, ws.mCriterionClass + length)) // The counts match too, so it's a full match.
			{
				ws.mFoundChild = aWnd; // Save this in here for return to the caller.
				return FALSE; // stop the enumeration.
			}
		}
	}
	else // Caller told us to search by the text of the control (e.g. the text printed on a button)
	{
		// Use GetWindowText() rather than GetWindowTextTimeout() because we don't want to find
		// the name accidentally in the vast amount of text present in some edit controls (e.g.
		// if the script's source code is open for editing in notepad, GetWindowText() would
		// likely find an unwanted match for just about anything).  In addition,
		// GetWindowText() is much faster.  Update: Yes, it seems better not to use
		// GetWindowTextByTitleMatchMode() in this case, since control names tend to be so
		// short (i.e. they would otherwise be very likely to be undesirably found in any large
		// edit controls the target window happens to own).  Update: Changed from strstr()
		// to strncmp() for greater selectivity.  Even with this degree of selectivity, it's
		// still possible to have ambiguous situations where a control can't be found due
		// to its title being entirely contained within that of another (e.g. a button
		// with title "Connect" would be found in the title of a button "Connect All").
		// The only way to address that would be to insist on an entire title match, but
		// that might be tedious if the title of the control is very long.  As alleviation,
		// the class name + seq. number method above can often be used instead in cases
		// of such ambiguity.  Update: Using IsTextMatch() now so that user-specified
		// TitleMatchMode will be in effect for this also.  Also, it's case sensitivity
		// helps increase selectivity, which is helpful due to how common short or ambiguous