Differentiate preselected from just selected text

source/appModules/kindle.py

@@ -137,7 +137,7 @@ def script_showSelectionOptions(self, gesture):
 		# so retrieve and report the selection from Kindle.
 		# we can't just use self.makeTextInfo, as that will use our fake selection.
 		realSel = self.rootNVDAObject.makeTextInfo(textInfos.POSITION_SELECTION)
-		speech.speakSelectedText(realSel.text)
+		speech.speakTextSelected(realSel.text)
 		# Remove our virtual selection and move the caret to the active end.
 		fakeSel.innerTextInfo = realSel
 		fakeSel.collapse(end=not self._lastSelectionMovedStart)

source/appModules/powerpnt.py

@@ -1081,7 +1081,7 @@ def event_treeInterceptor_gainFocus(self):
 		else:
 			info = self.selection
 			if not info.isCollapsed:
-				speech.speakSelectedText(info.text)
+				speech.speakPreselectedText(info.text)
 			else:
 				info.expand(textInfos.UNIT_LINE)
 				speech.speakTextInfo(info, reason=controlTypes.REASON_CARET, unit=textInfos.UNIT_LINE)

source/browseMode.py

@@ -1221,7 +1221,7 @@ def event_treeInterceptor_gainFocus(self):
 						speech.speakObject(self.rootNVDAObject, reason=controlTypes.REASON_FOCUS)
 				info = self.selection
 				if not info.isCollapsed:
-					speech.speakSelectedText(info.text)
+					speech.speakPreselectedText(info.text)
 				else:
 					info.expand(textInfos.UNIT_LINE)
 					speech.speakTextInfo(info, reason=controlTypes.REASON_CARET, unit=textInfos.UNIT_LINE)

source/compoundDocuments.py

@@ -446,7 +446,7 @@ def event_treeInterceptor_gainFocus(self):
 				info.expand(textInfos.UNIT_LINE)
 				speech.speakTextInfo(info, unit=textInfos.UNIT_LINE, reason=controlTypes.REASON_CARET)
 			else:
-				speech.speakSelectedText(info.text)
+				speech.speakPreselectedText(info.text)
 			braille.handler.handleGainFocus(self)
 			self.initAutoSelectDetection()
 

source/globalCommands.py

@@ -210,7 +210,7 @@ def script_reportCurrentSelection(self,gesture):
 		if not info or info.isCollapsed:
 			speech.speakMessage(_("No selection"))
 		else:
-			speech.speakSelectedText(info.text)
+			speech.speakTextSelected(info.text)
 	# Translators: Input help mode message for report current selection command.
 	script_reportCurrentSelection.__doc__=_("Announces the current selection in edit controls and documents. If there is no selection it says so.")
 	script_reportCurrentSelection.category=SCRCAT_SYSTEMCARET

source/speech.py

@@ -421,7 +421,7 @@ def speakObject(obj,reason=controlTypes.REASON_QUERY,index=None):
 			info=obj.makeTextInfo(textInfos.POSITION_SELECTION)
 			if not info.isCollapsed:
 				# if there is selected text, then there is a value and we do not report placeholder
-				speakSelectedText(info.text)
+				speakPreselectedText(info.text)
 			else:
 				info.expand(textInfos.UNIT_LINE)
 				_speakPlaceholderIfEmpty(info, obj, reason)
@@ -586,12 +586,34 @@ def speak(speechSequence,symbolLevel=None):
 				speechSequence[index]+=CHUNK_SEPARATOR
 	getSynth().speak(speechSequence)
 
-def speakSelectedText(text):
-	""" Helper method to speak the provided text with the word "selected" appended.
-	Implemented using L{speakSelectionMessage}, which allows for speaking text with an arbitrary attached message.
+def speakPreselectedText(text):
+	""" Helper method to announce that a newly focused control already has
+	text selected. This method is in contrast with L{speakTextSelected}.
+	The method will speak the word "selected" with the provided text appended.
+	The announcement order is different from L{speakTextSelected} in order to
+	inform a user that the newly focused control has content that is selected,
+	which they may unintentionally overwrite.
+
+	@remarks: Implemented using L{speakSelectionMessage}, which allows for
+		speaking text with an arbitrary attached message.
+	"""
+	# Translators: This is spoken to indicate that some text is already selected.
+	# 'selected' preceding text is intentional.
+	# For example 'selected hello world'
+	speakSelectionMessage(_("selected %s"), text)
+
+def speakTextSelected(text):
+	""" Helper method to announce that the user has caused text to be selected.
+	This method is in contrast with L{speakPreselectedText}.
+	The method will speak the provided text with the word "selected" appended.
+
+	@remarks: Implemented using L{speakSelectionMessage}, which allows for
+		speaking text with an arbitrary attached message.
 	"""
-	# Translators: This is spoken to indicate what has been selected. for example 'hello world selected'
-	speakSelectionMessage(_("%s selected"),text)
+	# Translators: This is spoken to indicate what has just been selected.
+	# The text preceding 'selected' is intentional.
+	# For example 'hello world selected'
+	speakSelectionMessage(_("%s selected"), text)
 
 def speakSelectionMessage(message,text):
 	if len(text) < 512:
@@ -650,12 +672,12 @@ def speakSelectionChange(oldInfo,newInfo,speakSelected=True,speakUnselected=True
 			for text in selectedTextList:
 				if  len(text)==1:
 					text=characterProcessing.processSpeechSymbol(locale,text)
-				speakSelectedText(text)
+				speakTextSelected(text)
 		elif len(selectedTextList)>0:
 			text=newInfo.text
 			if len(text)==1:
 				text=characterProcessing.processSpeechSymbol(locale,text)
-			speakSelectedText(text)
+			speakTextSelected(text)
 	if speakUnselected:
 		if not generalize:
 			for text in unselectedTextList: