Edit Library v2.0

Summary
Edit Library v2.0
IntroductionThis library is designed for use on the standard Edit control.
Issues/ConsiderationA few considerations...
CreditThis library was inspired by the Edit mini-library created by Lexikos and the HiEditor library created by majkinetor.
Functions
Edit_ActivateParentActivates (makes foremost) the parent window of the Edit control if needed.
Edit_CanUndoReturns TRUE if there are any actions in the Edit control’s undo queue, otherwise FALSE.
Edit_CharFromPosGets information about the character and/or line closest to a specified point in the the client area of the Edit control.
Edit_ClearClear (delete) the current selection, if any, from the Edit control.
Edit_ContainsSoftLineBreaksReturns TRUE if the Edit control contains any soft line-break characters in the text.
Edit_Convert2DOSConverts Unix, DOS/Unix mix, and Mac EOL formats to DOS format.
Edit_Convert2MacConvert DOS, DOS/Unix mix, and Unix EOL formats to Mac format.
Edit_Convert2UnixConvert DOS, DOS/Unix mix, and Mac formats to Unix format.
Edit_ConvertCaseConvert case of selected text.
Edit_CopyCopy the current selection to the clipboard in CF_TEXT format.
Edit_CutDelete the current selection, if any, and copy the deleted text to the clipboard in CF_TEXT format.
Edit_DisableDisables (“greys out”) an Edit control.
Edit_DisableAllScrollBarsDisables the horizontal and vertical scroll bars.
Edit_DisableHScrollBarDisables the horizontal scroll bar.
Edit_DisableVScrollBarDisables the vertical scroll bar.
Edit_EmptyUndoBufferResets the undo flag of the Edit control.
Edit_EnableEnables a Edit control if it was previously disabled.
Edit_EnableAllScrollBarsEnables the horizontal and vertical scroll bars.
Edit_EnableHScrollBarEnables the horizontal scroll bar.
Edit_EnableVScrollBarEnables the vertical scroll bar.
Edit_EnableScrollBarEnables or disables one or both scroll bar arrows.
Edit_FindTextFind text within the Edit control.
Edit_FindTextResetClears the saved text created by the “Static” flag.
Edit_FmtLinesSets a flag that determines whether a multiline Edit control includes soft line-break characters.
Edit_GetActiveHandlesFinds the handles for the active control and active window.
Edit_GetComboBoxEditReturns the handle to the Edit control attached to a combo box.
Edit_GetCueBannerGets the text that is displayed as the textual cue, or tip, in an edit control.
Edit_GetFirstVisibleLineReturns the zero-based index of the uppermost visible line.
Edit_GetFontGets the font with which the Edit control is currently drawing its text.
Edit_GetLastVisibleLineReturns the zero-based line index of the last visible line on the edit control.
Edit_GetLimitTextReturns the current text limit for the Edit control.
Edit_GetLineGet the text of the desired line from the Edit control.
Edit_GetLineCountReturns an integer specifying the total number of text lines in a multiline Edit control.
Edit_GetMarginsGets the widths of the left and right margins for the Edit control.
Edit_GetModifyGets the state of the Edit control’s modification flag.
Edit_GetPasswordCharGets the password character that an Edit control displays when the user enters text.
Edit_GetPosGets the position and size of the Edit control.
Edit_GetRectGets the formatting rectangle of the Edit control.
Edit_GetScrollBarInfoGets information about the specified scroll bar.
Edit_GetScrollBarStateGets the state of specified scroll bar.
Edit_GetSelGets the starting and ending character positions of the current selection in the Edit control.
Edit_GetSelTextReturns the currently selected text (if any).
Edit_GetStyleReturns an integer that represents the styles currently set for the Edit control.
Edit_GetTextReturns all text from the control up to p_Length length.
Edit_GetTextLengthReturns the length, in characters, of the text in the Edit control.
Edit_GetTextRangeGet a range of characters.
Edit_HasFocusDetermines if the Edit control has functional input focus, aka “keyboard focus”.
Edit_HideHides a Edit control.
Edit_HideAllScrollBarsHides the horizontal and vertical scroll bars on a Edit control.
Edit_HideBalloonTipHides any balloon tip associated with an Edit control.
Edit_HideHScrollBarHides the horizontal scroll bar on a Edit control.
Edit_HideVScrollBarHides the vertical scroll bar on a Edit control.
Edit_IsDisabledReturns TRUE if the Edit control is disabled.
Edit_IsHScrollBarEnabledDetermines if the horizontal scroll bar is enabled.
Edit_IsHScrollBarVisibleDetermines if the horizontal scroll bar is visible.
Edit_IsMultilineReturns TRUE if the Edit control is multiline, otherwise FALSE.
Edit_IsReadOnlyReturns TRUE if the ES_READONLY style has been set, otherwise FALSE.
Edit_IsStyleReturns TRUE if the specified style has been set, otherwise FALSE.
Edit_IsVScrollBarEnabledDetermines if the vertical scroll bar is enabled.
Edit_IsVScrollBarVisibleDetermines if the vertical scroll bar is visible.
Edit_IsWordWrapReturns TRUE if word wrap is enabled on the Edit control.
Edit_LineFromCharGets the index of the line that contains the specified character index.
Edit_LineFromPosThis function is the same as Edit_CharFromPos except the line index (r_LineIdx) is returned.
Edit_LineIndexGets the character index of the first character of a specified line.
Edit_LineLengthGets the length of a line.
Edit_LineScrollScrolls the text vertically or horizontally in a multiline Edit control.
Edit_LoadFileCalls Edit_ReadFile to load the contents of a file to the Edit control.
Edit_MouseInSelectionDetermines if the mouse is somewhere within selected text of a specified Edit control.
Edit_PasteCopies the current content of the clipboard to the Edit control at the current caret position.
Edit_PosFromCharGets the client area coordinates of a specified character in the edit control.
Edit_ReadFileReads the contents of a file into the Edit control.
Edit_ReplaceSelReplaces the selected text with the specified text.
Edit_SaveFileCalls Edit_WriteFile to save the contents of the Edit control to a file.
Edit_SelectAllSelects all characters in an Edit control.
Edit_ScrollScrolls the text vertically in a multiline Edit control.
Edit_ScrollCaretScrolls the caret into view in an Edit control.
Edit_ScrollPageScrolls the Edit control by page.
Edit_SetCueBannerSets the textual cue, or tip, that is displayed by the Edit control to prompt the user for information.
Edit_SetFocusSets input focus to the specified Edit control.
Edit_SetFontSets the font that the Edit control is to use when drawing text.
Edit_SetLimitTextSets the text limit of the Edit control.
Edit_SetMarginsSets the width of the left and/or right margin, in pixels, for the edit control.
Edit_SetModifySets or clears the modification flag for the Edit control.
Edit_SetPasswordCharSets or removes the password character for a single-line Edit control.
Edit_SetReadOnlySets or removes the read-only style (ES_READONLY) of the Edit control.
Edit_SetRectSets the formatting rectangle of a multiline Edit control.
Edit_SetTabStopsSets the tab stops in a multiline Edit control.
Edit_SetTextSet the text of the Edit control.
Edit_SetSelSelects a range of characters.
Edit_SetStyleAdds, removes, or toggles a style for an Edit control.
Edit_ShowShows a Edit control if it was previously hidden.
Edit_ShowAllScrollBarsShows the horizontal and vertical scroll bars on a Edit control.
Edit_ShowBalloonTipDisplays a balloon tip associated with an Edit control.
Edit_ShowHScrollBarShows the horizontal scroll bar on a Edit control.
Edit_ShowScrollBarShows or hides the specified scroll bar on a Edit control.
Edit_ShowVScrollBarShows the vertical scroll bar.
Edit_SystemMessageConverts a system message number into a readable message.
Edit_TextIsSelectedReturns TRUE if text is selected, otherwise FALSE.
Edit_UndoUndo the last operation.
Edit_WriteFileWrite the contents of the Edit control to a file.
Add-On Functions
Functions
Edit_AutoSetTabStops v0.2 (Preview)Automatically sets the tab stops for an Edit control by examining the tab-delimited data in the control and then setting the tabs stops so that each column is wide enough to show all fields in the column.
Edit_BlockMoveMove selected text (one or more lines) up or down in a multiline edit control.
Edit_CutLineCuts (delete and copy the deleted text to the clipboard) the specified zero-based line.
Edit_DeleteLineDeletes the specified zero-based line.
Edit_DuplicateDuplicate selected text.
Edit_SelectLineSelects the specified zero-based line.
Edit_SortSort selected text (one or more lines) using the p_SortOptions options.
Edit_SpellCheckGUI v0.2.5 (Preview)A specialty function that performs a spell check on the designated edit control using the dictionary as defined by the hSpell variable.
Edit_TTSGUI v0.5This function displays a Text-To-Speech player window to speak text from an Edit control.

Introduction

This library is designed for use on the standard Edit control.

Issues/Consideration

A few considerations...

  • Some of functions are only for use on single-line Edit controls and some are only for use on multiline Edit controls.  See the documentation for each function for any restrictions.
  • AutoHotkey supports the creation and manipulation of the standard edit control.  For this reason, there are a small number functions that were intentionally left out of this library because they provide no additional value to what the standard AutoHotkey commands provide.
  • The Edit control does not support several key messages that are needed by this library.  Absent messages include EM_GETSELTEXT, EM_GETTEXTRANGE, and EM_FINDTEXT.  These messages have been replaced with AutoHotkey commands or with other messages.  Although the substitute code/messages are very capable, they are not quite as efficient (memory and/or speed) as the messages they replace (if they existed).  These inefficiencies are not really noticable if the control only contains a limited amount of text (~512K or less), but they become more pronounced with increasing text sizes.  Efficiency also depends on the where work in the control is being done.  For example, extracting text from the top of the control uses less resources that extracting text from the end of the control.

Credit

This library was inspired by the Edit mini-library created by Lexikos and the HiEditor library created by majkinetor.  Some of the syntax and code ideas were extracted from these libraries.  Thanks to these authors for sharing their work.

Functions

Edit_ActivateParent

Edit_ActivateParent(hEdit)

Description

Activates (makes foremost) the parent window of the Edit control if needed.  If the window is minimized, it is automatically restored prior to being activated.

Returns

TRUE if successful, or FALSE otherwise.

Remarks

This function only actives the parent window of the Edit control.  It does not give focus to the Edit control.  If needed, call Edit_SetFocus instead of (or in addition to) this function.

Edit_CanUndo

Edit_CanUndo(hEdit)

Description

Returns TRUE if there are any actions in the Edit control’s undo queue, otherwise FALSE.

Edit_CharFromPos

Edit_CharFromPos( hEdit,  
 X,  
 Y,  
ByRef r_CharPos = "",
ByRef r_LineIdx = "")

Description

Gets information about the character and/or line closest to a specified point in the the client area of the Edit control.

Parameters

X, YThe coordinates of a point in the Edit control’s client area relative to the upper-left corner of the client area.
r_CharPos[Output] The zero-based index of the character nearest the specified point.  [Optional] This index is relative to the beginning of the control, not the beginning of the line.  If the specified point is beyond the last character in the Edit control, the return value indicates the last character in the control.  See the Remarks section for more information.
r_LineIdx[Output] Zero-based index of the line that contains the character.  [Optional] For single-line Edit controls, this value is zero.  The index indicates the line delimiter if the specified point is beyond the last visible character in a line.  See the Remarks section for more information.

Returns

The value of the r_CharPos variable.

Calls To Other Functions

Remarks

If the specified point is outside the bounds of the Edit control, the return value and all output variables (r_CharPos and r_LineIdx) are set to -1.

Edit_Clear

Edit_Clear(hEdit)

Description

Clear (delete) the current selection, if any, from the Edit control.

Remarks

Undo can be used to reverse this action.

Edit_ContainsSoftLineBreaks

Edit_ContainsSoftLineBreaks(hEdit)

Description

Returns TRUE if the Edit control contains any soft line-break characters in the text.

Type

Experimental/Preview.  Subject to change.

Calls To Other Functions

Remarks

This function is resource intensive.  The entire document is formatted to include soft line-break characters (if any) and then reverted back to the original format.  Use sparingly.  When used on large documents, performance can be significantly improved by setting SetBatchLines to a high value before calling this function.  For example:

SetBatchLines 100ms  ;-- Large bump in priority
RC:=Edit_ContainsSoftLineBreaks(hEdit)
SetBatchLines 10ms   ;-- Default priority

Warning: There is an extremely remote possiblity that a library function that uses the WM_GETTEXT message (Ex: Edit_GetSelText) can collect formatted text, i.e. text that includes soft line-break characters, while this function is running.  This can occur if the the thread running this function is interrupted by another thread immediately after formatting the Edit control to include soft line-break characters.  In this scenario, the interrupting thread uses a function that uses the WM_GETTEXT message and collects formatted text.  The chances of this occurring are virtually nil for small and medium-sized documents but the chances increase (although still very unlikely) as the size of the document increases.  To significantly reduce the chance of interruption, set SetBatchLines to a high value (or -1) before calling this function.

Edit_Convert2DOS

Edit_Convert2DOS(p_Text)

Description

Converts Unix, DOS/Unix mix, and Mac EOL formats to DOS format.

Edit_Convert2Mac

Edit_Convert2Mac(p_Text)

Description

Convert DOS, DOS/Unix mix, and Unix EOL formats to Mac format.

Edit_Convert2Unix

Edit_Convert2Unix(p_Text)

Description

Convert DOS, DOS/Unix mix, and Mac formats to Unix format.

Edit_ConvertCase

Edit_ConvertCase(hEdit,
p_Case)

Description

Convert case of selected text.

Parameters

p_CaseSet to “Upper”, “Lower”, “Capitalize”, “Sentence”, or “Toggle”.

Calls To Other Functions

Edit_Copy

Edit_Copy(hEdit)

Description

Copy the current selection to the clipboard in CF_TEXT format.

Edit_Cut

Edit_Cut(hEdit)

Description

Delete the current selection, if any, and copy the deleted text to the clipboard in CF_TEXT format.

Edit_Disable

Edit_Disable(hEdit)

Description

Disables (“greys out”) an Edit control.

Returns

TRUE if successful, otherwise FALSE.

Remarks

For AutoHotkey GUIs, use the GUIControl command for improved efficiency.  Ex: GUIControl 24:Disable,MyEdit

Edit_DisableAllScrollBars

Edit_DisableAllScrollBars(hEdit)

Description

Disables the horizontal and vertical scroll bars.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_EnableScrollBar for more information.

Edit_DisableHScrollBar

Edit_DisableHScrollBar(hEdit)

Description

Disables the horizontal scroll bar.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_EnableScrollBar for more information.

Edit_DisableVScrollBar

Edit_DisableVScrollBar(hEdit)

Description

Disables the vertical scroll bar.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_EnableScrollBar for more information.

Edit_EmptyUndoBuffer

Edit_EmptyUndoBuffer(hEdit)

Description

Resets the undo flag of the Edit control.  The undo flag is set whenever an operation within the Edit control can be undone.

Edit_Enable

Edit_Enable(hEdit)

Description

Enables a Edit control if it was previously disabled.

Returns

TRUE if successful, otherwise FALSE.

Remarks

For AutoHotkey GUIs, use the GUIControl command for improved efficiency.  Ex: GUIControl 12:Enable,MyEdit

Edit_EnableAllScrollBars

Edit_EnableAllScrollBars(hEdit)

Description

Enables the horizontal and vertical scroll bars.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_EnableScrollBar for more information.

Edit_EnableHScrollBar

Edit_EnableHScrollBar(hEdit)

Description

Enables the horizontal scroll bar.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_EnableScrollBar for more information.

Edit_EnableVScrollBar

Edit_EnableVScrollBar(hEdit)

Description

Enables the vertical scroll bar.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_EnableScrollBar for more information.

Edit_EnableScrollBar

Edit_EnableScrollBar(hEdit,
wSBflags,
wArrows)

Description

Enables or disables one or both scroll bar arrows.

Parameters

wSBflagsSpecifies the scroll bar type.  See the function’s static variables for a list of possible values.
wArrowsSpecifies whether the scroll bar arrows are enabled or disabled and indicates which arrows are enabled or disabled.  See the function’s static variables for a list of possible values.

Returns

TRUE if successful, otherwise FALSE.

Remarks

The function will return FALSE (not successful) if the scroll bar(s) are already in the requested state (enabled/disabled).  To determine if a scroll bar is already enabled, use Edit_IsHScrollBarEnabled and/or Edit_IsVScrollBarEnabled.

Edit_FindText

Edit_FindText( hEdit,  
 p_SearchText,  
 p_Min = 0,
 p_Max = -1,
 p_Flags = "",
ByRef r_RegExOut = "")

Description

Find text within the Edit control.

Parameters

p_SearchTextSearch text.
p_Min, p_MaxZero-based search range within the Edit control.  p_Min is the character index of the first character in the range and p_Max is the character index immediately following the last character in the range.  (Ex: To search the first 5 characters of the text, set p_Min to 0 and p_Max to 5) Set p_Max to -1 to search to the end of the text.  To search backward, the roles and descriptions of the p_Min and p_Max are reversed.  (Ex: To search the first 5 characters of the control in reverse, set p_Min to 5 and p_Max to 0)
p_FlagsValid flags are as follows:
Flag        Description
----        -----------
MatchCase   Search is case sensitive.  This flag is ignored if the
            "RegEx" flag is also defined.

RegEx       Regular expression search.

Static      [Advanced feature]
            Text collected from the Edit control remains in memory is
            used to satisfy the search request.  The text remains in
            memory until the "Reset" flag is used or until the
            "Static" flag is not used.

            Advantages: Search time is reduced 10 to 60 percent
            (or more) depending on the size of the text in the control.
            There is no speed increase on the first use of the "Static"
            flag.

            Disadvantages: Any changes in the Edit control are not
            reflected in the search.

            Hint: Don't use this flag unless performing multiple search
            requests on a control that will not be modified while
            searching.

Reset       [Advanced feature]
            Clears the saved text created by the "Static" flag so that
            the next use of the "Static" flag will get the text directly
            from the Edit control.  To clear the saved memory without
            performing a search, use the following syntax:

                Edit_FindText("","",0,0,"Reset")
r_RegExOutputVariable that contains the part of the source text that matched the RegEx pattern.  [Optional]

Returns

Zero-based character index of the first character of the match or -1 if no match is found.

Calls To Other Functions

Programming Notes

Searching using regular expressions (RegEx) can produce results that have a dynamic number of characters.  For this reason, searching for the “next” pattern (forward or backward) may produce different results from developer to developer depending on how the values of p_Min and p_Max are determined.

Edit_FindTextReset

Edit_FindTextReset()

Description

Clears the saved text created by the “Static” flag.

Calls To Other Functions

Edit_FmtLines

Edit_FmtLines(hEdit,
p_Flag)

Description

Sets a flag that determines whether a multiline Edit control includes soft line-break characters.  A soft line break consists of two carriage return characters and a line feed character (CR+CR+LF) and is inserted at the end of a line that is broken because of word wrapping.

Parameters

p_FlagSet to TRUE to insert soft line-break characters characters, FALSE to removes them.

Returns

The value of p_Flag.

Remarks

This message has no effect on the display of the text within the edit control.  It affects the buffer returned by the EM_GETHANDLE message and the text returned by the WM_GETTEXT message.  Since the WM_GETTEXT message is used by other functions in this library, be sure to un-format the text as soon as possible.  Example of use:

Edit_FmtLines(hEdit,True)
FormattedText:=Edit_GetText(hEdit)
Edit_FmtLines(hEdit,False)

Edit_GetActiveHandles

Edit_GetActiveHandles(ByRef hEdit = "",
ByRef hWindow = "",
 p_MsgBox = False)

Description

Finds the handles for the active control and active window.

Type

Helper function.

Parameters

hEditVariable that contains the handle of the active Edit control.  [Optional] Value is zero if the active control is not an Edit control.
hWindowVariable that contains the handle of the active window.  [Optional]
p_MsgBoxDisplay error message.  [Optional] If TRUE, an error MsgBox is displayed if the active control is not an Edit control.

Returns

Handle of the active Edit control or FALSE (0) if the active control is not an Edit control.

Edit_GetComboBoxEdit

Edit_GetComboBoxEdit(hCombo)

Description

Returns the handle to the Edit control attached to a combo box.

Parameters

hComboHandle to a combo box control.

Credit

Code adapted from an example posted by just me.  Post: http://www.autohotkey.com/community/viewtopic.php?p=569444#p569444

Edit_GetCueBanner

Edit_GetCueBanner(hEdit,  
p_MaxSize = 1024)

Description

Gets the text that is displayed as the textual cue, or tip, in an edit control.

Parameters

p_MaxSizeThe maximum number of characters including the terminating null.  [Optional] The default is 1024.

Returns

Cue bannter text from the designated control.

Requirements

Documented: Windows XP+, Observation: Vista+

Remarks

Single-line Edit control only.

Edit_GetFirstVisibleLine

Edit_GetFirstVisibleLine(hEdit)

Description

Returns the zero-based index of the uppermost visible line.  For single-line Edit controls, the return value is the zero-based index of the first visible character.

Edit_GetFont

Edit_GetFont(hEdit)

Description

Gets the font with which the Edit control is currently drawing its text.

Parameters

hEditHandle to the Edit control.

Returns

The handle to the font (HFONT) used by the Edit control or 0 if the using the system font.

Remarks

This function can be used to get the font of any control.  Just specify the handle to the desired control as the first parameter.  Ex: Edit_GetFont(hLV) where “hLV” is the handle to a ListView control.

Edit_GetLastVisibleLine

Edit_GetLastVisibleLine(hEdit)

Description

Returns the zero-based line index of the last visible line on the edit control.

Calls To Other Functions

Remarks

To calculate the total number of visible lines, use the following...

Edit_GetLastVisibleLine(hEdit) - Edit_GetFirstVisibleLine(hEdit) + 1

Edit_GetLimitText

Edit_GetLimitText(hEdit)

Description

Returns the current text limit for the Edit control.

Remarks

Windows NT+: The maximum text length is 0x7FFFFFFE (2,147,483,646) characters for single-line Edit controls and 0xFFFFFFFF (4,294,967,295) for multiline Edit controls.  These values are returned if no limit has been set on the Edit control.

Edit_GetLine

Edit_GetLine(hEdit,  
p_LineIdx = -1,
p_Length = -1)

Description

Get the text of the desired line from the Edit control.

Parameters

p_LineIdxThe zero-based index of the line to retrieve.  [Optional] Use -1 (the default) to get the current line.  This parameter is ignored if used for a single-line Edit control.
p_LengthLength of the line or length of the text to be extracted.  [Optional] Use -1 (the default) to automatically determine the length of the line.

Returns

The text of the specified line up to the length (p_Length) specified.  An empty string is returned if the line number specified by p_LineIdx is greater than the number of lines in the Edit control.

Calls To Other Functions

Edit_GetLineCount

Edit_GetLineCount(hEdit)

Description

Returns an integer specifying the total number of text lines in a multiline Edit control.  If the control has no text, the return value is 1.  The return value will never be less than 1.

Remarks

The value returned is for the number of lines in the Edit control.  Very long lines (>1024 characters) or word wrap may introduce additional lines to the control.

Edit_GetMargins

Edit_GetMargins( hEdit,  
ByRef r_LeftMargin = "",
ByRef r_RightMargin = "")

Description

Gets the widths of the left and right margins for the Edit control.  If defined, these values are returned in the r_LeftMargin and r_RightMargin variables.

Parameters

r_LeftMarginLeft margin, in pixels.  [Optional]
r_RightMarginRight margin, in pixels.  [Optional]

Returns

The Edit control’s left margin.

Edit_GetModify

Edit_GetModify(hEdit)

Description

Gets the state of the Edit control’s modification flag.  The flag indicates whether the contents of the Edit control have been modified.

Returns

TRUE if the Edit control has been modified, otherwise FALSE.

Edit_GetPasswordChar

Edit_GetPasswordChar(hEdit)

Description

Gets the password character that an Edit control displays when the user enters text.

Returns

The decimal value of the character that is displayed in place of the characters typed by the user.  If a password character has not been set, 0 is returned.

Remarks

  • Single-line Edit controls only.
  • If the return value is an ANSI value (between 1 and 255), the built-in AutoHotkey Chr function can be used to convert the value to a character.  For example:
Character:=Chr(Edit_GetPasswordChar(hEdit))
  • For most versions of Windows, the default password character decimal value is 9679 (black circle).

Requirements

Windows 2000+

Edit_GetPos

Edit_GetPos( hEdit,  
ByRef X = "",
ByRef Y = "",
ByRef W = "",
ByRef H = "")

Description

Gets the position and size of the Edit control.  See the Remarks section for more information.

Parameters

X, Y, W, HOutput variables.  [Optional] If defined, these variables contain the coordinates of the Edit control relative to the client-area of the parent window (X and Y), and the width and height of the Edit control (W and H).

Remarks

This function returns the same values as the GUIControlGet,OutputVar,Pos command and can be used when the GUIControlGet command is not available (non-AutoHotkey GUI, GUI name unknown, variable name unknown, etc.)

If only interested in the W (Width) and/or H (Height) values, the AutoHotkey ControlGetPos or WinGetPos commands can be used instead.

Hint: The built-in AutoHotkey GUIControlGet, ControlGetPos, and WinGetPos commands are more efficient and should be used whenever possible.

Edit_GetRect

Edit_GetRect( hEdit,  
ByRef r_Left = "",
ByRef r_Top = "",
ByRef r_Right = "",
ByRef r_Bottom = "")

Description

Gets the formatting rectangle of the Edit control.

Parameters

r_Left..r_BottomOutput variables.  [Optional]

Returns

The address to a RECT structure that contains the formatting rectangle.

Edit_GetScrollBarInfo

Edit_GetScrollBarInfo(hEdit,
idObject)

Description

Gets information about the specified scroll bar.

Type

Internal function.  Subject to change.  Do not use.

Parameters

idObjectSpecifies the scroll bar object.  See the function’s static variables for a list of possible values.

Returns

The address to a SCROLLBARINFO structure that contains the information requested.

Edit_GetScrollBarState

Edit_GetScrollBarState(hEdit,
idObject)

Description

Gets the state of specified scroll bar.

Type

Internal function.  Subject to change.  Do not use.

Parameters

idObjectSpecifies the scroll bar object.  See the function’s static variables for a list of possible values.

Returns

The state of the specified scrollbar.  See the function’s static variables for a list of possible return values.

Remarks

This function returns the state of the scroll bar itself.  It does not include the state of the arrow buttons, scroll box, etc.  If needed, use Edit_GetScrollBarInfo to get this information.

Edit_GetSel

Edit_GetSel( hEdit,  
ByRef r_StartSelPos = "",
ByRef r_EndSelPos = "")

Description

Gets the starting and ending character positions of the current selection in the Edit control.  If defined, these values are returned in the r_StartSelPos and r_EndSelPos variables.

Parameters

r_StartSelPos[Output] Variable that contains the starting position of the selection.  [Optional]
r_EndSelPos[Output] Variable that contains the end position of the selection.  [Optional]

Returns

Starting position of the selection.

Edit_GetSelText

Edit_GetSelText(hEdit)

Description

Returns the currently selected text (if any).

Calls To Other Functions

Remarks

Since the Edit control does not support the EM_GETSELTEXT message, the EM_GETLINE (if the selection is on one line) and the WM_GETTEXT messages are used instead.

Edit_GetStyle

Edit_GetStyle(hEdit)

Description

Returns an integer that represents the styles currently set for the Edit control.

Remarks

For a complete list of syles

http://msdn.microsoft.com/en-us/library/windows/desktop/bb775464(v=vs.85).aspx

Edit_GetText

Edit_GetText(hEdit,  
p_Length = -1)

Description

Returns all text from the control up to p_Length length.  If p_Length=-1 (the default), all text is returned.

Calls To Other Functions

Remarks

This function is similar to the AutoHotkey GUIControlGet command (for AHK GUIs) and the ControlGetText command except that end-of-line (EOL) characters from the retrieved text are not automatically converted (CR+LF to LF).  If needed, use Edit_Convert2Unix to convert the text to the AutoHotkey text format.

Edit_GetTextLength

Edit_GetTextLength(hEdit)

Description

Returns the length, in characters, of the text in the Edit control.

Edit_GetTextRange

Edit_GetTextRange(hEdit,  
p_Min = 0,
p_Max = -1)

Description

Get a range of characters.

Parameters

p_MinCharacter position index immediately preceding the first character in the range.
p_MaxCharacter position immediately following the last character in the range.  Set to -1 to indicate the end of the text.

Calls To Other Functions

Remarks

Since the Edit control does not support the EM_GETTEXTRANGE message, Edit_GetText (WM_GETTEXT message) is used to collect the desired range of of characters.

Edit_HasFocus

Edit_HasFocus(hEdit)

Description

Determines if the Edit control has functional input focus, aka “keyboard focus”.

Returns

TRUE if the Edit control has functional input focus, otherwise FALSE.

Credit

Adapted from an example in the AutoHotkey documentation.

Edit_Hide

Edit_Hide(hEdit)

Description

Hides a Edit control.

Returns

TRUE if successful, otherwise FALSE.

Remarks

  • For AutoHotkey GUIs, use the GUIControl command for improved efficiency.  Ex: GUIControl 33:Hide,MyEdit
  • This command only hides the control, it does not disable it.  To prevent use of the control’s shortcut keys, be sure to disable the control as well.

Edit_HideAllScrollBars

Edit_HideAllScrollBars(hEdit)

Description

Hides the horizontal and vertical scroll bars on a Edit control.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_ShowScrollBar for more information.

Edit_HideBalloonTip

Edit_HideBalloonTip(hEdit)

Description

Hides any balloon tip associated with an Edit control.

Returns

TRUE if successful, otherwise FALSE.

Remarks

This function is usually unnecessary.  A balloon tip will usually auto-hide after short period of time (5 to 15 seconds).  In addition, the balloon tip will auto-hide if the contents of the control are changed or if focus is moved to another control.

Requirements

Windows XP+

Edit_HideHScrollBar

Edit_HideHScrollBar(hEdit)

Description

Hides the horizontal scroll bar on a Edit control.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_ShowScrollBar for more information.

Edit_HideVScrollBar

Edit_HideVScrollBar(hEdit)

Description

Hides the vertical scroll bar on a Edit control.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_ShowScrollBar for more information.

Edit_IsDisabled

Edit_IsDisabled(hEdit)

Description

Returns TRUE if the Edit control is disabled.

Calls To Other Functions

Edit_IsHScrollBarEnabled

Edit_IsHScrollBarEnabled(hEdit)

Description

Determines if the horizontal scroll bar is enabled.

Returns

TRUE if the horizontal scroll bar is enabled, otherwise FALSE.

Calls To Other Functions

Observation

  • The return value from this function is unusable (always returns TRUE) if the scroll bar is hidden.  The scroll bar can still be enabled or disabled while the scroll bar is hidden.  There is just no way to determine the current enabled/disabled status while the scroll bar is hidden.

Edit_IsHScrollBarVisible

Edit_IsHScrollBarVisible(hEdit)

Description

Determines if the horizontal scroll bar is visible.

Returns

TRUE if the horizontal scroll bar is visible, otherwise FALSE.

Calls To Other Functions

Edit_IsMultiline

Edit_IsMultiline(hEdit)

Description

Returns TRUE if the Edit control is multiline, otherwise FALSE.

Edit_IsReadOnly

Edit_IsReadOnly(hEdit)

Description

Returns TRUE if the ES_READONLY style has been set, otherwise FALSE.

Edit_IsStyle

Edit_IsStyle(hEdit,
p_Style)

Description

Returns TRUE if the specified style has been set, otherwise FALSE.

Parameters

p_StyleStyle of the Edit control.

Some common Edit control styles...

ES_LEFT       :=0x0         ;-- Can't actually check this style.  It's the absence of ES_CENTER or ES_RIGHT.
ES_CENTER     :=0x1
ES_RIGHT      :=0x2
ES_MULTILINE  :=0x4
ES_UPPERCASE  :=0x8
ES_LOWERCASE  :=0x10
ES_PASSWORD   :=0x20        ;-- Single-line Edit control only
ES_AUTOVSCROLL:=0x40
ES_AUTOHSCROLL:=0x80
ES_NOHIDESEL  :=0x100
ES_COMBO      :=0x200
ES_OEMCONVERT :=0x400
ES_READONLY   :=0x800
ES_WANTRETURN :=0x1000
ES_NUMBER     :=0x2000
WS_TABSTOP    :=0x10000
WS_HSCROLL    :=0x100000
WS_VSCROLL    :=0x200000

Edit_IsVScrollBarEnabled

Edit_IsVScrollBarEnabled(hEdit)

Description

Determines if the vertical scroll bar is enabled.

Returns

TRUE if the vertical scroll bar is enabled, otherwise FALSE.

Calls To Other Functions

Observation

The return value from this function is unusable (always returns TRUE) if the scroll bar is hidden.  The scroll bar can still be enabled and/or disabled while the scroll bar is hidden.  There is just no way to determine the current enabled/disabled status while the scroll bar is hidden.

Edit_IsVScrollBarVisible

Edit_IsVScrollBarVisible(hEdit)

Description

Determines if the vertical scroll bar is visible.

Returns

TRUE if the vertical scroll bar is visible, otherwise FALSE.

Calls To Other Functions

Edit_IsWordWrap

Edit_IsWordWrap(hEdit)

Description

Returns TRUE if word wrap is enabled on the Edit control.

Remarks

This function may return a false positive, i.e. Word Wrap is enabled, by hiding the horizontal scroll bar after the Edit control has been created.  Although this situation is rare, it is a possiblity.  One way to ensure that the function always returns FALSE correctly (i.e.  Word Wrap is not enabled) is to always include the ES_AUTOHSCROLL style (0x80 or -Wrap) when the WS_HSCROLL style (0x100000) is also included.

Edit_LineFromChar

Edit_LineFromChar(hEdit,  
p_CharPos = -1)

Description

Gets the index of the line that contains the specified character index.

Parameters

p_CharPosThe character index of the character contained in the line whose number is to be retrieved.  [Optional] If –1 (the default), the function retrieves either the line number of the current line (the line containing the caret) or, if there is a selection, the line number of the line containing the beginning of the selection.

Returns

The zero-based line number of the line containing the character index specified by p_CharPos.

Edit_LineFromPos

Edit_LineFromPos( hEdit,  
 X,  
 Y,  
ByRef r_CharPos = "",
ByRef r_LineIdx = "")

Description

This function is the same as Edit_CharFromPos except the line index (r_LineIdx) is returned.

Edit_LineIndex

Edit_LineIndex(hEdit,  
p_LineIdx = -1)

Description

Gets the character index of the first character of a specified line.

Parameters

p_LineIdxZero-based line number.  [Optional] Use -1 (the default) for the current line.

Returns

The character index of the specified line or -1 if the specified line is greater than the total number of lines in the Edit control.

Edit_LineLength

Edit_LineLength(hEdit,  
p_LineIdx = -1)

Description

Gets the length of a line.

Parameters

p_LineIdxThe zero-based line index of the desired line.  Use -1 (the default) for the current line.

Returns

The length, in characters, of the specified line.  If p_LineIndex is greater than the total number of lines in the Edit control, the length of the last (or only) line is returned.

Calls To Other Functions

Edit_LineScroll

Edit_LineScroll(hEdit,  
xScroll = 0,
yScroll = 0)

Description

Scrolls the text vertically or horizontally in a multiline Edit control.

Parameters

xScroll, yScrollThe number of characters to scroll horizontally (xScroll) or vertically (yScroll).  Use a negative number to scroll to the left (xScroll) or up (yScroll) and a positive number to scroll to the right (xScroll) or to scroll down (yScroll).  Alternatively, these parameters can contain one or more of the following values:
Option  Description
------   -----------
Left    Scroll to the left edge of the control.
Right   Scroll to the right edge of the control.
Top     Scroll to the top of the control.
Bottom  Scroll to the bottom of the control.

If more than one option is specified, the options must be delimited by a
space.  Ex: "Top Left".  See the *Remarks* section for more information.

Remarks

The xScroll parameter is processed first and then yScroll.  If either of these parameters contains multiple values (Ex: “Top Left”), the values are processed individually from left to right.  If there are conflicting values (Ex: “Top Bottom”), the last value specified will take precedence.

Edit_LoadFile

Edit_LoadFile( hEdit,  
 p_File,  
 p_Convert2DOS = False,
ByRef r_EOLFormat = "")

Description

Calls Edit_ReadFile to load the contents of a file to the Edit control.  See Edit_ReadFile for the requirements.

Returns

TRUE if successful, otherwise FALSE.

Remarks

This function is deprecated.  Use Edit_ReadFile instead.

Edit_MouseInSelection

Edit_MouseInSelection(hEdit)

Description

Determines if the mouse is somewhere within selected text of a specified Edit control.

Returns

Returns TRUE if the mouse is somewhere within selected text of the edit control, otherwise FALSE.

Calls To Other Functions

Edit_Paste

Edit_Paste(hEdit)

Description

Copies the current content of the clipboard to the Edit control at the current caret position.  Data is inserted only if the clipboard contains data in CF_TEXT format.

Edit_PosFromChar

Edit_PosFromChar( hEdit,  
 p_CharPos,  
ByRef X = "",
ByRef Y = "")

Description

Gets the client area coordinates of a specified character in the edit control.

Parameters

p_CharPosThe zero-based index of the character.
X, YOutput variables.  [Optional] These variables are used to return the x/y-coordinates of a point in the Edit control’s client relative to the upper-left corner of the client area.

Returns

Address to a POINT structure.

Remarks

If p_CharPos is greater than the index of the last character in the control, the returned coordinates are of the position just past the last character of the control.

Edit_ReadFile

Edit_ReadFile( hEdit,  
 p_File,  
 p_Encoding = "",
 p_Convert2DOS = False,
ByRef r_EOLFormat = "")

Description

Reads the contents of a file into the Edit control.

Parameters

p_FileThe path of the file.
p_EncodingThe code page to use if the file does not contain a UTF-8 or UTF-16 byte order mark.  [Optional] If omitted or set to null (the default), the current value of A_FileEncoding is used.  Set to “CP0” to force the program to use the system default ANSI code page.
p_Convert2DOSIf set TRUE, the text will be converted from Unix, DOS/Unix mix, or Mac format, to DOS format before it is loaded to the edit control.  [Optional]
r_EOLFormatContains the end-of-line (EOL) format variable.  [Optional] This variable is set to the EOL format of the loaded file which will be “DOS”, “Unix”, or “Mac”.  This information is useful if the contents of the Edit control will be be converted back to the original EOL format when the file is saved.

Returns

The number of characters loaded to Edit control (can be 0) if successful, otherwise -1 if the file could not be found, -2 if the file could not be opened, or -3 if the text could not be loaded to the Edit control (very rare).

Calls To Other Functions

Convert To DOS

For text computing, a new line, also known as end of line (EOL) or line break, is a special character or sequence of characters signifying the end of a line of text and the start of a new line.  Internally, the Edit control only supports the DOS EOL format which consists of a carriage return and line feed (CR+LF) characters.  If a file is not already in the the DOS format, the text will not display correctly when it loaded to the Edit control unless it is first converted to the DOS format.

If the p_Convert2DOS parameter is set to TRUE, the text read from the file is converted into the DOS format before the text is loaded to the Edit control.  This will ensure that the text is the correct format for the Edit control.  This conversion is essential if the file is in a Unix (EOL=LF) or Mac (EOL=CR) format but it can also be beneficial if the file is in a DOS/Unix mix where the DOS and Unix new line sequences are both used.

Conversion requires additional processing.  The extra processing is not noticeable for small files, barely noticeable for medium-sized files, but may be very noticeable for large and very-large text files.  When conversion is performed on a large text file, performance can be significantly improved by setting SetBatchLines to a high value before calling this function.  For example:

SetBatchLines 100ms  ;-- Large bump in priority
RC:=Edit_ReadFile(hEdit,...)
SetBatchLines 10ms   ;-- Default priority

Note: The Mac EOL format (CR) is only used on Mac OS version 9 and earlier.  Mac OS 10+ uses the Unix (LF) format.

Encoding

When reading a text file using AutoHotkey’s standard file commands (FileRead, FileReadLine, the Read method of AutoHotkey’s File object, etc.), the file’s byte order mark (BOM), if it exists, takes precedence over whatever encoding the developer may specify, if anything.  However, if the file has been encoding in some non-ANSI way and file does not contain a byte order mark (BOM), the file will not decoded correctly.  This is mentioned because many common programs/utilities will automatically detect and decode a text file without a BOM, especially if the file contains UTF-8 characters.  AutoHotkey file commands do not include a mechanism to automatically identify and decode a non-ANSI file so specifying the correct encoding whether the file has a BOM or not is good practice.

Remarks

This request will replace the entire Edit control with the contents of the the specified file.  Consequently, the Undo buffer is flushed.

If the p_Convert2DOS paramter is set to TRUE, the number of characters loaded to the Edit control can be different that the number characters read from the file.

If this function fails, i.e. returns a negative value, a developer-friendly message is dumped to the debugger.  Use a debugger or debug viewer to see the message.

Edit_ReplaceSel

Edit_ReplaceSel(hEdit,  
p_Text = "",
p_CanUndo = True)

Description

Replaces the selected text with the specified text.  If there is no selection, the replacement text is inserted at the caret.

Parameters

p_TextText to replace selection with.
p_CanUndoIf TRUE (the default), replace can be undone.

Edit_SaveFile

Edit_SaveFile(hEdit,  
p_File,  
p_Convert = "")

Description

Calls Edit_WriteFile to save the contents of the Edit control to a file.  See Edit_WriteFile for the requirements.

Returns

TRUE if successful, otherwise FALSE.

Remarks

[v2.0+] In previous versions of the library, this function created a new file in all situations, deleting the old file first if needed.  This function now calls Edit_WriteFile which will overwrite the file if it already exist.

This function is deprecated.  Use Edit_WriteFile instead.

Edit_SelectAll

Edit_SelectAll(hEdit)

Description

Selects all characters in an Edit control.

Edit_Scroll

Edit_Scroll(hEdit,  
p_Pages = 0,
p_Lines = 0)

Description

Scrolls the text vertically in a multiline Edit control.

Parameters

p_PagesThe number of pages to scroll.  Use a negative number to page up and a positive number to page down.
p_LinesThe number of lines to scroll.  Use a negative number to scroll up and a positive number to scroll down.

Returns

The number of lines that the command scrolls.  The value will be negative if scrolling up, positive if scrolling down, and zero (0) if no scrolling occurred.

Edit_ScrollCaret

Edit_ScrollCaret(hEdit)

Description

Scrolls the caret into view in an Edit control.

Edit_ScrollPage

Edit_ScrollPage(hEdit,  
p_HPages = 0,
p_VPages = 0)

Description

Scrolls the Edit control by page.

Parameters

p_HPagesThe number of horizontal pages to scroll.  Use a postive number to page right and a negative number to page left.
p_VPagesThe number of vertical pages to scroll.  [Optional] Use a positive number to page down and a negative number to page up.

Remarks

This function duplicates some of the functionality of Edit_Scroll.  If scrolling vertically and the return value is needed, use the Edit_Scroll function instead.

Edit_SetCueBanner

Edit_SetCueBanner(hEdit,  
p_Text,  
p_ShowWhenFocused = False)

Description

Sets the textual cue, or tip, that is displayed by the Edit control to prompt the user for information.

Parameters

p_TextCue banner text.
p_ShowWhenFocused[Vista+] Set to TRUE to show the cue banner even if the Edit control has focus.  The default is FALSE (don’t show when the edit control has focus).

Returns

TRUE if successful, otherwise FALSE.

Remarks

Single-line Edit control only.

Requirements

Windows XP+

Edit_SetFocus

Edit_SetFocus(hEdit,  
p_ActivateParent = False)

Description

Sets input focus to the specified Edit control.

Parameters

p_ActivateParentIf TRUE, the function will call Edit_ActivateParent which will activate the parenet window if it is not already active.  The default is FALSE.

Returns

TRUE if successful, or FALSE otherwise.

Calls To Other Functions

Remarks

  • Functional input focus, aka “keyboard focus”, can only be achieved if the control has focus AND the parent window is active (foremost).  If requested, this function will activate the parent window if is not already active.
  • For AutoHotkey GUIs, use the GUIControl command for improved efficiency.  Ex: GUIControl 32:Focus,MyEdit
  • This function uses the AutoHotKey ControlFocus command.  See the AHK documentation for additional restrictions (Ex: SetControlDelay).
  • This function can be used to set focus on any control.  Just specify the handle to the desired control as the first parameter.  Ex: Edit_SetFocus(hLV) where “hLV” is the handle to a ListView control.

Edit_SetFont

Edit_SetFont(hEdit,  
hFont,  
p_Redraw = False)

Description

Sets the font that the Edit control is to use when drawing text.

Parameters

hEditHandle to the Edit control.
hFontHandle to the font (HFONT).  Set to 0 to use the default system font.
p_RedrawSpecifies whether the control should be redrawn immediately upon setting the font.  If set to TRUE, the control redraws itself.

Remarks

  • This function can be used to set the font on any control.  Just specify the handle to the desired control as the first parameter.  Ex: Edit_SetFont(hLV,hFont) where “hLV” is the handle to ListView control.
  • The size of the control does not change as a result of receiving this message.  To avoid clipping text that does not fit within the boundaries of the control, the program should set/correct the size of the control before the font is set.

Edit_SetLimitText

Edit_SetLimitText(hEdit,
p_Limit)

Description

Sets the text limit of the Edit control.

Parameters

p_LimitThe maximum number of characters the user can enter.  Windows NT+: If this parameter is zero, the text length is set to 0x7FFFFFFE (2,147,483,646) characters for single-line Edit controls and 0xFFFFFFFF (4,294,967,295) for multiline Edit controls.

Remarks

  • This message limits only the text the user can enter.  It does not affect any text already in the Edit control when the message is sent, nor does it affect the length of the text copied to the Edit control by the WM_SETTEXT message.  For more information:

http://msdn.microsoft.com/en-us/library/bb761607(VS.85).aspx

  • For AutoHotkey GUI’s, use the +Limitnn and -Limit options.
  • Warning: Although this message can be sent to any Edit control, not all programs will respond well to a limit change.

Edit_SetMargins

Edit_SetMargins(hEdit,  
p_LeftMargin = "",
p_RightMargin = "")

Description

Sets the width of the left and/or right margin, in pixels, for the edit control.  The message automatically redraws the control to reflect the new margins.

Parameters

p_LeftMarginLeft margin, in pixels.  If blank/null, the left margin is not set.  Specify the EC_USEFONTINFO value (0xFFFF or 65535) to set the left margin to a narrow width calculated using the text metrics of the control’s current font.
p_RightMarginRight margin, in pixels.  If blank/null, the right margin is not set.  Specify the EC_USEFONTINFO value (0xFFFF or 65535) to set the right margin to a narrow width calculated using the text metrics of the control’s current font.

Observations

The documentation states that the EM_SETMARGINS message automatically redraws the control to reflect the new margins.  However, only the left margin is set correctly if the control contains text.  The only way to get the right margin to show correctly is to reload the text to the control.  This is messy becase all selected data and the modify status of the Edit control is lost when then data is reloaded to the control.  If possible, set the margins before text is loaded to the control.  If this is not possible, see the “Set Margins” example script for one way to work around the problem.

For the EM_SETMARGINS message, the Edit control does not appear to be DPI aware.  The control assumes that the screen always has 96 pixels per inch, i.e.  96 DPI.  This makes conversion from inches to pixel easy.  Simply multiply inches by 96 to get the number of pixels.  Ex: 0.5 inches * 96 = 48 pixels.

Edit_SetModify

Edit_SetModify(hEdit,
p_Flag)

Description

Sets or clears the modification flag for the Edit control.  The modification flag indicates whether the text within the control has been modified.

Parameters

p_FlagSet to TRUE to set the modification flag.  Set to FALSE to clear the modification flag.

Edit_SetPasswordChar

Edit_SetPasswordChar(hEdit,  
p_CharValue = 9679)

Description

Sets or removes the password character for a single-line Edit control.

Parameters

p_CharValueThe decimal value of the character that is displayed in place of the characters typed by the user.  [Optional] The default is an 9679 (black circle).  Set to 0 (null) to remove the password character.

Returns

Documented: This message does not return a value.  Undocumented and/or does not apply to all OS versions: Returns TRUE if successful or “FAIL” if unsuccessful.

Remarks

Observations

  • On Windows 2000+, the ES_Password style cannot be removed once added unless the request is made from the same process that created the control.
  • This style is not supposed to work on multiline Edit control but it appears work on more recent versions of Windows (tested on Windows 7) if the style is added after the Edit control is created.  Probably should still assume that the style is only good for single-line Edit controls.

Edit_SetReadOnly

Edit_SetReadOnly(hEdit,
p_Flag)

Description

Sets or removes the read-only style (ES_READONLY) of the Edit control.

Parameters

p_FlagSet to TRUE to add the ES_READONLY style.  Set to FALSE to remove the ES_READONLY style.

Returns

TRUE if successful, otherwise FALSE.

Remarks

For AutoHotkey GUIs, this is same as using the +ReadOnly or -ReadOnly option when creating the Edit control or using the GUIControl command after the Edit control has been created.  Ex: GUIControl +ReadOnly,Edit1

Edit_SetRect

Edit_SetRect(hEdit,
p_Left,
p_Top,
p_Right,
p_Bottom)

Description

Sets the formatting rectangle of a multiline Edit control.  The formatting rectangle is the limiting rectangle into which the control draws the text.  The limiting rectangle is independent of the size of the Edit control window.

Parameters

p_Left..p_BottomRectangle coordinates.

Remarks

Advanced feature.  For additional information, see the following...

http://msdn.microsoft.com/en-us/library/bb761657(VS.85).aspx

Edit_SetTabStops

Edit_SetTabStops(hEdit,  
p_NbrOfTabStops = 0,
p_DTU = 32)

Description

Sets the tab stops in a multiline Edit control.  When text is copied to the control, any tab character in the text causes space to be generated up to the next tab stop.

Parameters

p_NbrOfTabStopsNumber of tab stops.  [Optional] Set to 0 (the default) to set the tab stops to the system default.  Set to 1 to have all tab stops set to the value of the p_DTU parameter or 32 if the p_DTU parameter is not specified.  Any value greater than 1 will set that number of tab stops.
p_DTUDialog Template Units.  [Optional] This parameter can contain a single value (Ex: 32), a comma-delimited list of values (Ex: “29,72,122,174”) or an AutoHotkey object with an array of values (Ex: [150,180,205,255].  If p_NbrOfTabStops=0, this parameter is ignored.  If this parameter contains a single value (Ex: 30), all tab stops will be set to a factor of that value (Ex: 30, 60, 90, etc.).  Otherwise, this parameter should contain values for all requested tab stops.

Returns

TRUE if all the tabs are set, otherwise FALSE.

Edit_SetText

Edit_SetText(hEdit,  
p_Text,  
p_SetModify = False)

Description

Set the text of the Edit control.

Parameters

p_TextText to set the Edit control.
p_SetModifyIf set to TRUE, the modification flag is set after the text is set.  If FALSE (the default), the modification flag is not set (remains cleared) after the text is set.

Returns

TRUE if successful, otherwise FALSE.

Remarks

  • The system automatically clears the modification flag whenever an edit control receives a WM_SETTEXT message.  Set the p_SetModify parameter to TRUE to set the modification flag after the text is set.
  • The system automatically resets the undo flag whenever an Edit control receives a WM_SETTEXT message.  Use Edit_SetSel (select all) and Edit_ReplaceSel to populate the control if undo is desired.
  • This function is similar to the AutoHotkey ControlSetText command except there is no delay after the command has executed.

Edit_SetSel

Edit_SetSel(hEdit,  
p_StartSelPos = 0,
p_EndSelPos = -1)

Description

Selects a range of characters.

Parameters

p_StartSelPosStarting character position of the selection.  If set to -1, the current selection (if any) will be deselected.
p_EndSelPosEnding character position of the selection.  Set to -1 to use the position of the last character in the control.

Edit_SetStyle

Edit_SetStyle(hEdit,  
p_Style,  
p_Option = "+")

Description

Adds, removes, or toggles a style for an Edit control.

Parameters

p_StyleStyle to set.
p_OptionUse “+” (the default) to add, “-” to remove, and “^” to toggle.

Returns

TRUE if the request completed successfully, otherwise FALSE.

Remarks

Styles that can be modified after the Edit control has been created include the following:

ES_UPPERCASE  :=0x8
ES_LOWERCASE  :=0x10
ES_PASSWORD   :=0x20    ;-- Use the Edit_SetPasswordChar function
ES_OEMCONVERT :=0x400
ES_READONLY   :=0x800   ;-- Use the Edit_SetReadOnly function
ES_WANTRETURN :=0x1000
ES_NUMBER     :=0x2000

Use Edit_IsStyle to determine if a style is currently set.

Edit_Show

Edit_Show(hEdit)

Description

Shows a Edit control if it was previously hidden.

Returns

TRUE if successful, otherwise FALSE.

Remarks

For AutoHotkey GUIs, use the GUIControl command for improved efficiency.  Ex: GUIControl MyGUI:Show,MyEdit

Edit_ShowAllScrollBars

Edit_ShowAllScrollBars(hEdit)

Description

Shows the horizontal and vertical scroll bars on a Edit control.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_ShowScrollBar for more information.

Edit_ShowBalloonTip

Edit_ShowBalloonTip(hEdit,  
p_Title,  
p_Text,  
p_Icon = )

Description

Displays a balloon tip associated with an Edit control.

Parameters

p_TitleBalloon tip title.  Can be empty/null.
p_TextBalloon tip text.
p_IconType of icon to associate with the balloon tip.  [Optional] The default is 0 (No icon).  See the function’s static variables for a list of possible values.

Returns

TRUE if successful, otherwise FALSE.

Requirements

Windows XP+

Remarks

  • Sending the EM_SHOWBALLOONTIP message will automatically move focus to the designated Edit control.
  • A balloon tip will not show if the “EnableBalloonTips” registry key is disabled (set to 0).  The key can be found here: HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced\
  • The balloon tip icon (if specified) will not be displayed unless a title (p_Title) is also specified.

Observations

The EM_SHOWBALLOONTIP message does not fail (return FALSE) if the “EnableBalloonTips” registry key is disabled (set to 0).

Edit_ShowHScrollBar

Edit_ShowHScrollBar(hEdit)

Description

Shows the horizontal scroll bar on a Edit control.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_ShowScrollBar for more information.

Edit_ShowScrollBar

Edit_ShowScrollBar(hEdit,  
wBar,  
p_Show = True)

Description

Shows or hides the specified scroll bar on a Edit control.

Parameters

wBarSpecifies the scroll bar(s) to be shown or hidden.  See the function’s static variables for a list of possible values.
p_ShowDetermines whether the scroll bar is shown or hidden.  If set to TRUE (the default), the scroll bar is shown; otherwise, it is hidden.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

Do not call this function to show or hide a scroll bar while processing a scroll bar message.

Observations

Unlike Edit_EnableScrollBar, this function returns TRUE (successful) even if the scroll bar(s) are already in the requested state (showing/hidden).  To determine if a scroll bar is showing, use Edit_IsHScrollBarVisible or Edit_IsVScrollBarVisible.

Edit_ShowVScrollBar

Edit_ShowVScrollBar(hEdit)

Description

Shows the vertical scroll bar.

Returns

TRUE if successful, otherwise FALSE.

Calls To Other Functions

Remarks

See Edit_ShowScrollBar for more information.

Edit_SystemMessage

Edit_SystemMessage(p_MessageNbr)

Description

Converts a system message number into a readable message.

Type

Internal function.  Subject to change.

Edit_TextIsSelected

Edit_TextIsSelected( hEdit,  
ByRef r_StartSelPos = "",
ByRef r_EndSelPos = "")

Description

Returns TRUE if text is selected, otherwise FALSE.

Parameters

r_StartSelPos, r_EndSelPos[Output] Variables that contains the starting and ending position of the selection.  [Optional]

Calls To Other Functions

Edit_Undo

Edit_Undo(hEdit)

Description

Undo the last operation.

Returns

For a single-line Edit control, the return value is always TRUE.  For a multiline Edit control, the return value is TRUE if the undo operation is successful, otherwise FALSE.

Edit_WriteFile

Edit_WriteFile(hEdit,  
p_File,  
p_Encoding = "",
p_Convert = "")

Description

Write the contents of the Edit control to a file.  See the File Processing section for more information.

Parameters

p_FileThe file path.
p_EncodingThe code page for character encoding.  [Optional] If omitted or if set to null (the default), the current value of A_FileEncoding is used.  Set to “CP0” to force the program to use the system default ANSI code page.
p_ConvertConvert end-of-line (EOL) format.  [Optional] If omitted or if set to null (the default), no conversion is performed.  The EOL format will remain in the DOS format which is the EOL format used by the Edit control.  Set to “M” or “Mac” to convert to Mac.  Set to “U” or “Unix” to convert to Unix.

Returns

The number bytes (not characters) written to the file (can be zero), otherwise -1 if the file could not be created or opened.

Calls To Other Functions

File Processing

If the file (p_File parameter) does not exist, it will be created and the contents of the Edit control will be written to the file.

If the file already exists, the contents of the file will be overwritten with the contents of the Edit control.  All other attributes of the file are not modified.  This includes the standard attributes like creation date but if the file is on NTFS, it can include permissions, compression, encryption, properties, etc.  To force a new file to be created, the existing file must be deleted before calling this function.

In all cases, a byte order mark (BOM) is automatically added to the beginning of the file if encoding (p_Encoding parameter or A_FileEncoding if p_Encoding is null) is set to UTF-8 or UTF-16.

Remarks

If the function fails, i.e. returns -1, a developer-friendly message is dumped to the debugger.  Use a debugger or debug viewer to see the message.

Add-On Functions

Summary
Functions
Edit_AutoSetTabStops v0.2 (Preview)Automatically sets the tab stops for an Edit control by examining the tab-delimited data in the control and then setting the tabs stops so that each column is wide enough to show all fields in the column.
Edit_BlockMoveMove selected text (one or more lines) up or down in a multiline edit control.
Edit_CutLineCuts (delete and copy the deleted text to the clipboard) the specified zero-based line.
Edit_DeleteLineDeletes the specified zero-based line.
Edit_DuplicateDuplicate selected text.
Edit_SelectLineSelects the specified zero-based line.
Edit_SortSort selected text (one or more lines) using the p_SortOptions options.
Edit_SpellCheckGUI v0.2.5 (Preview)A specialty function that performs a spell check on the designated edit control using the dictionary as defined by the hSpell variable.
Edit_TTSGUI v0.5This function displays a Text-To-Speech player window to speak text from an Edit control.

Functions

Edit_AutoSetTabStops v0.2 (Preview)

Description

Automatically sets the tab stops for an Edit control by examining the tab-delimited data in the control and then setting the tabs stops so that each column is wide enough to show all fields in the column.

Type

Add-on function.

Parameters

p_ColumnGapThe amount of empty space, in dialog template units, to separate each column.  The minimum is 1.  The default is 6 which is equal to the width of 1.5 average characters of the edit control’s font.
p_MaxSampleThe maximum number of records to sample.  The default is 0 which indicates that all records will be sampled.

Returns

An AutoHotkey object that contains a simple array of tab stops (measured in dialog template units) that were set for the edit control.  If the MaxIndex property is null (tests as FALSE) then no data was found in the Edit control and the tab stops were set to the system default.  Otherwise, the MaxIndex property contains the number of elements in the array.

Calls to other functions

Remarks

The p_MaxSample parameter contains the maximum number of records to read in order to determine the maximum width of the columns.  The default is 0 which indicates that all records will be processed.  For large or very large files, setting a value to this parameter will ensure that the function will return in a timely manner.  However, the results cannot be assured unless all of the records are processed.

To correctly format tab-delimited data in an edit control, the minimum number of tab stops that can be set is equal to the number of tab-delimited columns minus 1.  So for 3 columns, 2 tab stops must be set.  There are two problems with this approach.  First, the tab stop following the last column is not set so if the user wants to manually add a column to the data, the data will not be positioned correctly which is relative to the widest field from the previous column.  Next, the last tab stop set also establishes the default size for all subsequent tab stops.  This can be problematic, or awkward at least, if the last tab stop set is unusually large or small.  To resolve these problems, the number of tab stops set is equal to the number of tab-delimited columns plus 1.  So for 3 columns, 4 tab stops are set.  The next-to-last tab stop establishes the width of the right-most column and the final tab stop is set to 32 dialog template units which is the system default.

Edit_BlockMove

Edit_BlockMove(hEdit,  
p_Command = "")

Description

Move selected text (one or more lines) up or down in a multiline edit control.

Type

Add-on function.

Parameters

p_CommandCommand to perform.  Use “Up” or “Down” to move the current or selected line(s) up/down 1 line.

Returns

TRUE if the move was performed, otherwise FALSE.

Calls To Other Functions

Remarks

  • Undo can be used to reverse this action.
  • This function does not work correctly if Word Wrap is enabled unless all affected lines are not wrapped.

Edit_CutLine

Edit_CutLine(hEdit,  
p_LineIdx = -1)

Description

Cuts (delete and copy the deleted text to the clipboard) the specified zero-based line.

Type

Add-on function.

Parameters

p_LineIdxThe zero-based index of the line to delete.  [Optional] Use -1 (the default) to delete the current line.

Returns

TRUE if the requested line is deleted, otherwise FALSE.

Calls To Other Functions

Remarks

  • Undo can be used to reverse this action.

Edit_DeleteLine

Edit_DeleteLine(hEdit,  
p_LineIdx = -1)

Description

Deletes the specified zero-based line.

Type

Add-on function.

Parameters

p_LineIdxThe zero-based index of the line to delete.  [Optional] Use -1 (the default) to delete the current line.

Returns

TRUE if the requested line is deleted, otherwise FALSE.

Calls To Other Functions

Remarks

  • Undo can be used to reverse this action.

Edit_Duplicate

Edit_Duplicate(hEdit)

Description

Duplicate selected text.  If nothing is selected, the entire line is duplicated.

Type

Add-on function.

Calls To Other Functions

Remarks

  • Undo can be used to reverse this action.
  • If the selection includes end-of-line (EOL) characters, i.e. the selection and the caret are on more than one line, the text will be reselected (if necessary) to include the entire line(s).
  • If duplicating lines, this function may not work correctly if word wrap is enabled unless all affected lines are not wrapped.

Edit_SelectLine

Edit_SelectLine(hEdit,  
p_LineIdx = -1,
p_IncludeEOL = False)

Description

Selects the specified zero-based line.

Type

Add-on function.

Parameters

p_LineIdxThe zero-based index of the line to select.  [Optional] Use -1 (the default) to select the current line.
p_IncludeEOLInclude end-of-line (EOL) characters.  [Optional] If set to TRUE, the EOL characters (CR+LF) after the line are also selected if they exist.

Returns

TRUE if the requested line is selected, otherwise FALSE.

Calls To Other Functions

Remarks

This function may not work as expected if word wrap is used or if selecting a very long (>1024) line.

Edit_Sort

Edit_Sort(hEdit,  
p_SortOptions = "")

Description

Sort selected text (one or more lines) using the p_SortOptions options.

Type

Add-on function.

Parameters

p_SortOptionsAutoHotkey sort options.  [Optional]

Calls To Other Functions

Remarks

  • Undo can be used to reverse this action.
  • If selecting more than one line, this function may not work correctly if word wrap is enabled unless all selected lines are not wrapped.
  • Hint: Don’t specify a delimiter if sorting more than one line.

Edit_SpellCheckGUI v0.2.5 (Preview)

Description

A specialty function that performs a spell check on the designated edit control using the dictionary as defined by the hSpell variable.  A dialog is displayed to prompt the user when a misspelled word is found.

Type

Add-on function.

Parameters

p_OwnerOwner GUI.  Set to 0 for no owner.  See the Owner section for more information.
hEditHandle to the edit control that will be checked for spelling errors.
hSpellVariable that contains Spell handle and function addresses.  See the Setup and Shutdown section for more information.
p_CustomDicPath to the custom dictionary file.  [Optional] See the Custom Dictionary section for more information.
p_TitleWindow title.  [Optional] The default is “Spell Check”.
p_FontTypeface name and/or font options.  [Optional] See the Font section for more information.

Calls To Other Functions

  • Edit [Library]
  • Fnt [Library]
  • MoveChildWindow
  • Spell v2.0+ [Library]
  • WinGetPosEx (used by MoveChildWindow)

Returns

TRUE if the Spell Check window was created normally and the spell check ended normally or was canceled by the user, otherwise FALSE if there was error.  Use a debugger or debug viewer to see the details if an error occurs.

Custom Dictionary

The p_CustomDic parameter contains the path to a custom dictionary file.  If blank/null or not specified, the “Add Word” button on the Edit_SpellCheckGUI dialog is not enabled.

Important 1: This function will only add words to the custom dictionary file specified in the p_CustomDic parameter.  Words that are already in the custom dictionary should be pre-loaded by the parent script by using the Spell_InitCustom function.

Important 2: Some of the errors that occur with/because of the path/file specified in the p_CustomDic parameter are handled internally by the function and are treated as non-critical errors.  The function will continue to operate in these cases.  Be sure to test thoroughly and use a debugger or debug viewer to see any errors that may occur.

Font

p_Font is an optional parameter that allows the developer to set a specific font for the Edit_SpellCheckGUI window.  The syntax is: {FontName}:{FontOptions}.  Ex: “Arial:s10 bold”.  All components of this parameter are optional.  If a typeface name is not specified (Ex: “:s12 bold”), the default system GUI font is used.  If no font options are specified (Ex: “Arial” or “Arial:”), the default font options are used.  See the AutoHotkey documentation for a list of (and syntax of) font options.

Exception/Feature: If the p_Font parameter is set to “Message”, the system font used for Message Box dialog is used.  In general, this font is a bit larger and easier to read than the default GUI font.

Owner

The p_Owner parameter is used to specify the owner of the Edit_SpellCheckGUI window.  Set to 0 for no owner.

For an AutoHotkey owner window, specify a valid GUI number (1-99), GUI name, or handle to the window.  When the Edit_SpellCheckGUI window is created, the owner window is disabled and ownership of the Edit_SpellCheckGUI window is assigned to the owner window.  This makes makes the Edit_SpellCheckGUI window modal which prevents the user from interacting with the owner window until the Edit_SpellCheckGUI window is closed.

For a non-AutoHotkey owner window, specify the handle to the window.  Ownership is not assigned but the window’s position and size is use to position the Edit_SpellCheckGUI window.

If p_Owner is not specified or is set to the handle of a non-AutoHotkey window, the AlwaysOnTop attribute is added to the Edit_SpellCheckGUI window to ensure that the dialog is not lost.

For all owner windows, the Edit_SpellCheckGUI window is positioned in the center of the owner window by default.

If p_Owner is zero (0), null, or contains a non-AutoHotkey GUI window handle, the function will still work but the user will have the ability to update the edit control while the spell check is running.  The function has been designed to deal will most idiosyncrasies but there is still a chance that changes to the edit control will interfere with the spell check operation.  Since the function does not return until the spell check is finished or is canceled, consider setting the edit control to read-only while the spell check is operating if p_Owner is undefined.  Changes to the document, if any, will still occur but the user will be blocked from making manual changes.  For example:

Edit_SetReadOnly(hEdit,True)
Edit_SpellCheckGUI(0,...)
Edit_SetReadOnly(hEdit,False)

Setup and Shutdown

This function uses v2.0+ of the Spell library to check the spelling of the words in an Edit control.  This function only uses an existing spell object.  The parent script (i.e. your script) is responsible for creating, populating (initially), and destroying the spell object.

To initialize the spell object, call the Spell_Init function.  This command will create the spell object and will populate it with words and rules from the specified Hunspell dictionary.  To load one or more custom dictionaries to the spell object, call the Spell_InitCustom function.

The Spell_Uninit function is used to destroy the spell object and free up all the memory used by the Hunspell API.  It can be called at any time after this function ends but it should, at the least, be called before the script ends.

See the example script for this function for an example of how to add the necessary commands to initialize and destroy the spell object.

Remarks

  • The function does not return until the Spell Check is finished or is cancelled.
  • Although not a requirement, adding the ES_NOHIDESEL style to the Edit control when it is created improves usability by continuing to show the selected text on the Edit control even when the Edit_SpellCheckGUI dialog is active.  Note that the ES_NOHIDESEL style cannot be added after the Edit control has been created.
  • Checking the spelling of a document is a resource intensive process.  If the document is relatively small (<15K, ~2,500 words or less), response from this module is nearly instananeous -- much less that 1 second on the high end.  However, the response will start to degrade more and more as the document size increases past this threshhold.  To improve performance, set SetBatchLines to a high value before calling this function.  For example:
SetBatchLines 200ms  ;-- Significant bump in priority
Edit_SpellCheckGUI(...)
SetBatchLines 10ms   ;-- This is the system default

Edit_TTSGUI v0.5

This function displays a Text-To-Speech player window to speak text from an Edit control.

Type

Add-on function.

Parameters

p_OwnerOwner GUI.  Set to 0 for no owner.  See the Owner section for more information.
hEditHandle to the Edit control.
p_OptionsProgram options.  [Optional] Valid options include the following:
p_TitleTitle to the Text-To-Speech window.  [Optional] If not defined or null then “Text-To-Speech” is used.

Returns

If a Edit_TTSGUI window is created, the handle to the window is returned, otherwise FALSE (0) is returned.  See the “Remarks” for more information.

Calls To Other Functions

  • AddTooltip
  • Edit [Library]
  • Fnt [Library]
  • MoveChildWindow
  • WinGetPosEx

Font

The Font option in the p_Options parameter allows for a specific logical font to specified when creating all GUI controls except for the buttons that control playback.  The syntax is as follows: {OptionName}={FontName}:{FontOptions}.  Ex: Font=”Arial:s10 bold”.  Most components of the option value are optional.  If a typeface name is not specified (Ex: “:s12 bold”), the default GUI font is used.  If no font options are specified (Ex: “Arial” or “Arial:”), the default font options are used.  See the AutoHotkey documentation for a list of (and syntax of) font options.

Exception: If the option value is set to “Message” (Ex: Font=Message), the system font used for Message Box dialog is used.  In general, the Message font is a bit larger and easier to read than the default GUI font and it is commonly used in dialogs.

Options

The p_Options parameter contains options for the display and operation of the Edit_TTSGUI window.  Valid options include the following:

-OptionsHide all Text-To-Speech options.  If this option is set, the “Show Options” button is hidden so that the user cannot show any of of the dialog’s Text-To-Speech options.  If specified, this option makes all options that begin with the negative character (Ex: -Rate) redundant.
Font={Font}Allows the developer to set a specific font for the GUI objects.  See the Font section for the syntax of this option.  If this option is not specified, the default GUI font is used.
-FormatHide the “Format” option.
Rate={PlaybackRate}Specify a playback rate from -10 to 10.  For example: Rate=3.  The user can override the rate if the “Rate” option is displayed.
-RateHide the “Rate” option.
Skip={NumberOfSentencesToSkip}Specify the number of sentences to skip forward when the Skip button is pressed.  For example: Skip=3.  The user can override this value if the “Skip” option is displayed.
-SkipHide the “Skip” option.
SpeakBegin to speak immediately.
TrackWord={EnableOrDisable}Specify whether the program will track the word on the edit control when speaking.  Set to 1 to enable.  Set to 0 to disable.  For example: TrackWord=1.  The user can override this value if the “TrackWord” option is displayed.
-TrackWordHide the “Word tracking” option.  Don’t confuse this option with the TrackWord=0” option.
Voice={NameOfVoice}Specify a Text-To-Speech voice.  For example: Voice=”Microsoft Mary”.  The user can override this voice if the “Voice” option is displayed.  If the specified voice is not found, the default voice is used.
-VoiceHide the “Voice” option.
Volume={VolumeLevel}Specify a volume level from 0 to 100.  For example: Volume=80.  The user can override the volume level if the “Volume” option is displayed.
-VolumeHide the “Volume” option.

To use more than one option, include a space between each option.  For example: Volume=80 Rate=3 -Format.  If an option value contains one or more space characters, enclose the entire value in single or double quote characters.  Ex: Voice=’Microsoft Mike’ or Voice=”Microsoft Mary”.  IMPORTANT: Only options that can possibly contain space characters will support the value enclosed single or double quote characters.

Owner

The p_Owner parameter is used to specify the owner of the Edit_TTSGUI window.  Set to 0 for no owner.  For an AutoHotkey GUI, specify a valid GUI number (1-99), a GUI name, or the handle to the GUI.  For a non-AutoHotkey window, specify the handle to the window.  For all owner windows, the Edit_TTSGUI window is positioned in the center of the owner window or as close to the center as possible.  If no owner is specified or if a non-AutoHotkey window is specified, the AlwaysOnTop attribute is added to the Edit_TTSGUI dialog to make sure that the dialog is not lost.

Remarks

Since the Edit_TTSGUI window remains open until the user closes it or until the developer closes it (for whatever reason), it’s best to check to see if the Edit_TTSGUI window is already open before calling this function.  For example:

IfWinNotExist ahk_id %hEdit_TTSGUI%
    hEdit_TTSGUI:=Edit_TTSGUI(...
    .
    .

The correct way to force the Edit_TTSGUI window to close is the WinClose command.  For example:

WinClose ahk_id %hEdit_TTSGUI%

The WinClose command will automatically trigger the standard GUIClose label which will destroy the Edit_TTSGUI window and release COM and Speech resources.

Important: Some voices do not support all of the features of this Text-To-Speech player.  Examples: 1) Most voices allow the volume and rate to be changed while the voice is speaking but some do not.  2) Most voices support the Skip command but some do not.  For some voices, pressing the Skip button will lock the player until the voice is done speaking.

Edit_ActivateParent(hEdit)
Activates (makes foremost) the parent window of the Edit control if needed.
Edit_CanUndo(hEdit)
Returns TRUE if there are any actions in the Edit control’s undo queue, otherwise FALSE.
Edit_CharFromPos( hEdit,  
 X,  
 Y,  
ByRef r_CharPos = "",
ByRef r_LineIdx = "")
Gets information about the character and/or line closest to a specified point in the the client area of the Edit control.
Edit_Clear(hEdit)
Clear (delete) the current selection, if any, from the Edit control.
Edit_ContainsSoftLineBreaks(hEdit)
Returns TRUE if the Edit control contains any soft line-break characters in the text.
Edit_Convert2DOS(p_Text)
Converts Unix, DOS/Unix mix, and Mac EOL formats to DOS format.
Edit_Convert2Mac(p_Text)
Convert DOS, DOS/Unix mix, and Unix EOL formats to Mac format.
Edit_Convert2Unix(p_Text)
Convert DOS, DOS/Unix mix, and Mac formats to Unix format.
Edit_ConvertCase(hEdit,
p_Case)
Convert case of selected text.
Edit_Copy(hEdit)
Copy the current selection to the clipboard in CF_TEXT format.
Edit_Cut(hEdit)
Delete the current selection, if any, and copy the deleted text to the clipboard in CF_TEXT format.
Edit_Disable(hEdit)
Disables (“greys out”) an Edit control.
Edit_DisableAllScrollBars(hEdit)
Disables the horizontal and vertical scroll bars.
Edit_DisableHScrollBar(hEdit)
Disables the horizontal scroll bar.
Edit_DisableVScrollBar(hEdit)
Disables the vertical scroll bar.
Edit_EmptyUndoBuffer(hEdit)
Resets the undo flag of the Edit control.
Edit_Enable(hEdit)
Enables a Edit control if it was previously disabled.
Edit_EnableAllScrollBars(hEdit)
Enables the horizontal and vertical scroll bars.
Edit_EnableHScrollBar(hEdit)
Enables the horizontal scroll bar.
Edit_EnableVScrollBar(hEdit)
Enables the vertical scroll bar.
Edit_EnableScrollBar(hEdit,
wSBflags,
wArrows)
Enables or disables one or both scroll bar arrows.
Edit_FindText( hEdit,  
 p_SearchText,  
 p_Min = 0,
 p_Max = -1,
 p_Flags = "",
ByRef r_RegExOut = "")
Find text within the Edit control.
Edit_FindTextReset()
Clears the saved text created by the “Static” flag.
Edit_FmtLines(hEdit,
p_Flag)
Sets a flag that determines whether a multiline Edit control includes soft line-break characters.
Edit_GetActiveHandles(ByRef hEdit = "",
ByRef hWindow = "",
 p_MsgBox = False)
Finds the handles for the active control and active window.
Edit_GetComboBoxEdit(hCombo)
Returns the handle to the Edit control attached to a combo box.
Edit_GetCueBanner(hEdit,  
p_MaxSize = 1024)
Gets the text that is displayed as the textual cue, or tip, in an edit control.
Edit_GetFirstVisibleLine(hEdit)
Returns the zero-based index of the uppermost visible line.
Edit_GetFont(hEdit)
Gets the font with which the Edit control is currently drawing its text.
Edit_GetLastVisibleLine(hEdit)
Returns the zero-based line index of the last visible line on the edit control.
Edit_GetLimitText(hEdit)
Returns the current text limit for the Edit control.
Edit_GetLine(hEdit,  
p_LineIdx = -1,
p_Length = -1)
Get the text of the desired line from the Edit control.
Edit_GetLineCount(hEdit)
Returns an integer specifying the total number of text lines in a multiline Edit control.
Edit_GetMargins( hEdit,  
ByRef r_LeftMargin = "",
ByRef r_RightMargin = "")
Gets the widths of the left and right margins for the Edit control.
Edit_GetModify(hEdit)
Gets the state of the Edit control’s modification flag.
Edit_GetPasswordChar(hEdit)
Gets the password character that an Edit control displays when the user enters text.
Edit_GetPos( hEdit,  
ByRef X = "",
ByRef Y = "",
ByRef W = "",
ByRef H = "")
Gets the position and size of the Edit control.
Edit_GetRect( hEdit,  
ByRef r_Left = "",
ByRef r_Top = "",
ByRef r_Right = "",
ByRef r_Bottom = "")
Gets the formatting rectangle of the Edit control.
Edit_GetScrollBarInfo(hEdit,
idObject)
Gets information about the specified scroll bar.
Edit_GetScrollBarState(hEdit,
idObject)
Gets the state of specified scroll bar.
Edit_GetSel( hEdit,  
ByRef r_StartSelPos = "",
ByRef r_EndSelPos = "")
Gets the starting and ending character positions of the current selection in the Edit control.
Edit_GetSelText(hEdit)
Returns the currently selected text (if any).
Edit_GetStyle(hEdit)
Returns an integer that represents the styles currently set for the Edit control.
Edit_GetText(hEdit,  
p_Length = -1)
Returns all text from the control up to p_Length length.
Edit_GetTextLength(hEdit)
Returns the length, in characters, of the text in the Edit control.
Edit_GetTextRange(hEdit,  
p_Min = 0,
p_Max = -1)
Get a range of characters.
Edit_HasFocus(hEdit)
Determines if the Edit control has functional input focus, aka “keyboard focus”.
Edit_Hide(hEdit)
Hides a Edit control.
Edit_HideAllScrollBars(hEdit)
Hides the horizontal and vertical scroll bars on a Edit control.
Edit_HideBalloonTip(hEdit)
Hides any balloon tip associated with an Edit control.
Edit_HideHScrollBar(hEdit)
Hides the horizontal scroll bar on a Edit control.
Edit_HideVScrollBar(hEdit)
Hides the vertical scroll bar on a Edit control.
Edit_IsDisabled(hEdit)
Returns TRUE if the Edit control is disabled.
Edit_IsHScrollBarEnabled(hEdit)
Determines if the horizontal scroll bar is enabled.
Edit_IsHScrollBarVisible(hEdit)
Determines if the horizontal scroll bar is visible.
Edit_IsMultiline(hEdit)
Returns TRUE if the Edit control is multiline, otherwise FALSE.
Edit_IsReadOnly(hEdit)
Returns TRUE if the ES_READONLY style has been set, otherwise FALSE.
Edit_IsStyle(hEdit,
p_Style)
Returns TRUE if the specified style has been set, otherwise FALSE.
Edit_IsVScrollBarEnabled(hEdit)
Determines if the vertical scroll bar is enabled.
Edit_IsVScrollBarVisible(hEdit)
Determines if the vertical scroll bar is visible.
Edit_IsWordWrap(hEdit)
Returns TRUE if word wrap is enabled on the Edit control.
Edit_LineFromChar(hEdit,  
p_CharPos = -1)
Gets the index of the line that contains the specified character index.
Edit_LineFromPos( hEdit,  
 X,  
 Y,  
ByRef r_CharPos = "",
ByRef r_LineIdx = "")
This function is the same as Edit_CharFromPos except the line index (r_LineIdx) is returned.
Edit_LineIndex(hEdit,  
p_LineIdx = -1)
Gets the character index of the first character of a specified line.
Edit_LineLength(hEdit,  
p_LineIdx = -1)
Gets the length of a line.
Edit_LineScroll(hEdit,  
xScroll = 0,
yScroll = 0)
Scrolls the text vertically or horizontally in a multiline Edit control.
Edit_LoadFile( hEdit,  
 p_File,  
 p_Convert2DOS = False,
ByRef r_EOLFormat = "")
Calls Edit_ReadFile to load the contents of a file to the Edit control.
Edit_ReadFile( hEdit,  
 p_File,  
 p_Encoding = "",
 p_Convert2DOS = False,
ByRef r_EOLFormat = "")
Reads the contents of a file into the Edit control.
Edit_MouseInSelection(hEdit)
Determines if the mouse is somewhere within selected text of a specified Edit control.
Edit_Paste(hEdit)
Copies the current content of the clipboard to the Edit control at the current caret position.
Edit_PosFromChar( hEdit,  
 p_CharPos,  
ByRef X = "",
ByRef Y = "")
Gets the client area coordinates of a specified character in the edit control.
Edit_ReplaceSel(hEdit,  
p_Text = "",
p_CanUndo = True)
Replaces the selected text with the specified text.
Edit_SaveFile(hEdit,  
p_File,  
p_Convert = "")
Calls Edit_WriteFile to save the contents of the Edit control to a file.
Edit_WriteFile(hEdit,  
p_File,  
p_Encoding = "",
p_Convert = "")
Write the contents of the Edit control to a file.
Edit_SelectAll(hEdit)
Selects all characters in an Edit control.
Edit_Scroll(hEdit,  
p_Pages = 0,
p_Lines = 0)
Scrolls the text vertically in a multiline Edit control.
Edit_ScrollCaret(hEdit)
Scrolls the caret into view in an Edit control.
Edit_ScrollPage(hEdit,  
p_HPages = 0,
p_VPages = 0)
Scrolls the Edit control by page.
Edit_SetCueBanner(hEdit,  
p_Text,  
p_ShowWhenFocused = False)
Sets the textual cue, or tip, that is displayed by the Edit control to prompt the user for information.
Edit_SetFocus(hEdit,  
p_ActivateParent = False)
Sets input focus to the specified Edit control.
Edit_SetFont(hEdit,  
hFont,  
p_Redraw = False)
Sets the font that the Edit control is to use when drawing text.
Edit_SetLimitText(hEdit,
p_Limit)
Sets the text limit of the Edit control.
Edit_SetMargins(hEdit,  
p_LeftMargin = "",
p_RightMargin = "")
Sets the width of the left and/or right margin, in pixels, for the edit control.
Edit_SetModify(hEdit,
p_Flag)
Sets or clears the modification flag for the Edit control.
Edit_SetPasswordChar(hEdit,  
p_CharValue = 9679)
Sets or removes the password character for a single-line Edit control.
Edit_SetReadOnly(hEdit,
p_Flag)
Sets or removes the read-only style (ES_READONLY) of the Edit control.
Edit_SetRect(hEdit,
p_Left,
p_Top,
p_Right,
p_Bottom)
Sets the formatting rectangle of a multiline Edit control.
Edit_SetTabStops(hEdit,  
p_NbrOfTabStops = 0,
p_DTU = 32)
Sets the tab stops in a multiline Edit control.
Edit_SetText(hEdit,  
p_Text,  
p_SetModify = False)
Set the text of the Edit control.
Edit_SetSel(hEdit,  
p_StartSelPos = 0,
p_EndSelPos = -1)
Selects a range of characters.
Edit_SetStyle(hEdit,  
p_Style,  
p_Option = "+")
Adds, removes, or toggles a style for an Edit control.
Edit_Show(hEdit)
Shows a Edit control if it was previously hidden.
Edit_ShowAllScrollBars(hEdit)
Shows the horizontal and vertical scroll bars on a Edit control.
Edit_ShowBalloonTip(hEdit,  
p_Title,  
p_Text,  
p_Icon = )
Displays a balloon tip associated with an Edit control.
Edit_ShowHScrollBar(hEdit)
Shows the horizontal scroll bar on a Edit control.
Edit_ShowScrollBar(hEdit,  
wBar,  
p_Show = True)
Shows or hides the specified scroll bar on a Edit control.
Edit_ShowVScrollBar(hEdit)
Shows the vertical scroll bar.
Edit_SystemMessage(p_MessageNbr)
Converts a system message number into a readable message.
Edit_TextIsSelected( hEdit,  
ByRef r_StartSelPos = "",
ByRef r_EndSelPos = "")
Returns TRUE if text is selected, otherwise FALSE.
Edit_Undo(hEdit)
Undo the last operation.
Edit_BlockMove(hEdit,  
p_Command = "")
Move selected text (one or more lines) up or down in a multiline edit control.
Edit_CutLine(hEdit,  
p_LineIdx = -1)
Cuts (delete and copy the deleted text to the clipboard) the specified zero-based line.
Edit_DeleteLine(hEdit,  
p_LineIdx = -1)
Deletes the specified zero-based line.
Edit_Duplicate(hEdit)
Duplicate selected text.
Edit_SelectLine(hEdit,  
p_LineIdx = -1,
p_IncludeEOL = False)
Selects the specified zero-based line.
Edit_Sort(hEdit,  
p_SortOptions = "")
Sort selected text (one or more lines) using the p_SortOptions options.
Close