I'm enhancing some existing text editor functionality in my app, and I'm adding support for the UIStandardEditActions method useSelectionForFind. The docs on the method say:
UIKit calls this method when the user selects the Use Selection For Find command from an editing menu. Your implementation should present the UI for finding textual content in your view and use the selected text for the search.
For example, a view using a find interaction might call presentFindNavigator(showingReplace:) and pass the selected text as the query string.
Reading this, I'd expect that selecting text and pressing Cmd-E on an attached keyboard should display the Find UI and prefill the selected text.
But in a couple of Apple apps that I tried on my iPad, Pages and Notes, pressing Cmd-E doesn't actually do anything visible, even if I hold Command to show the keyboard shortcut HUD and manually tap "Use Selection for Find". If I trigger the Find UI using Cmd-F, it does prefill the selected text, which it doesn't if I select text and press Cmd-F without pressing Cmd-E first.
I tried a couple of apps on my Mac, too - Xcode, TextEdit, TextMate - and they do the same thing. Pressing Cmd-E or triggering the command via the menu item does nothing visible, but when I then bring up the find UI the text is there. Or if the find UI is already visible when I press Cmd-E, the selected text is inserted there.
So, what's up here? Is that suggestion in the docs just wrong / out of step with what the standard behavior is? Or are all these apps wrong?
The documentation here is actually incorrect (I have filed a report for this, and we will follow up with a change), thanks for bringing this to our attention.
The expected behavior of "Use Selection for Find" is simply to take the currently selected string and use it as the current find session's search string, and not present any UI. The use case we're optimizing for here is the same as macOS's; enabling a user to select a bit of text, press Cmd+E, then Cmd+G to find the next occurrence of that string, all without presenting the find panel UI.
So, for example, if you have your own custom find session, a call to -useSelectionForFind should assign the currently selected string to some variable that you maintain (e.g., a property on your UIFindSession subclass), and when the system sends -highlightNextResultInDirection: (in response to a Cmd+G, for instance), you should perform a search using that string and highlight the next nearest result.
If you're using a standard UITextSearchingFindSession and UIFindInteraction provided by UIKit, you actually don't need to do anything to make this work. Leave -useSelectionForFind unimplemented, and the system will automatically do the right thing.