Add-On Functions for the Edit Library

Summary

Add-On Functions for the Edit Library
Functions
Edit_BlockMove	Move selected text (one or more lines) up or down in a multiline edit control.
Edit_CutLine	Cuts (delete and copy the deleted text to the clipboard) the specified zero-based line.
Edit_DeleteLine	Deletes the specified zero-based line.
Edit_Duplicate	Duplicate selected text.
Edit_SelectLine	Selects the specified zero-based line.
Edit_Sort	Sort selected text (one or more lines) using the p_SortOptions options.
Edit_SpellCheckGUI (Preview)	This function performs a Spell Check on the designated edit control using dictionary as defined by the hSpell variable and the custom dictionary as defined by the p_CustomDic parameter.
Edit_TTSGUI (Preview)	This function displays a Text-To-Speech player window to speak text from an Edit control.

Functions

Edit_BlockMove

Edit_BlockMove( hEdit,
p_Cmd = "" )

Description

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

Parameters

p_Command

Command 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.

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.

Parameters

p_LineIdx

The 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.

Remarks

Undo can be used to reverse this action.
This function uses the Edit_SelectLine add-on function.

Edit_DeleteLine

Edit_DeleteLine( hEdit,
p_LineIdx = -1 )

Description

Deletes the specified zero-based line.

Parameters

p_LineIdx

The 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.

Remarks

Undo can be used to reverse this action.
This function uses the Edit_SelectLine add-on function.

Edit_Duplicate

Edit_Duplicate( hEdit )

Description

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

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.

Parameters

p_LineIdx	The zero-based index of the line to select. [Optional] Use -1 (the default) to select the current line.
p_IncludeEOL	Include 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.

Remarks

This function may not work correctly 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.

Parameters

p_SortOptions

AutoHotkey sort options. [Optional]

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 (Preview)

Edit_SpellCheckGUI( p_Owner,
hEdit,
byRef hSpell,
p_CustomDic,
p_Title = "" )

Description

This function performs a Spell Check on the designated edit control using dictionary as defined by the hSpell variable and the custom dictionary as defined by the p_CustomDic parameter. A dialog is displayed to prompt the user when a misspelled word is found.

Parameters

p_Owner	The GUI owner of the Edit_SpellCheckGUI window. If not defined (set to blank or 0), the AlwaysOnTop attribute is added to the Edit_SpellCheckGUI window to make sure that the window is not lost.
hEdit	Handle to the edit control that will be checked for spelling errors.
hSpell	Variable that contains Spell handle and function addresses.
p_CustomDic	Path to the custom dictionary file.
p_Title	Window title. [Optional] The default is “Spell Check” (sans quotes).

Calls To Other Functions

Edit [Library]
PopupXY (Optional)
Spell [Library]

Remarks

The function does not return until the the Spell Check is finished.

The function uses the first GUI window that is available in the s_StartGUI to 99 range. If an available window cannot be found, an error message is displayed.

Edit_TTSGUI (Preview)

Edit_TTSGUI( p_Owner,
hEdit,
p_Options = "",
p_Title = "" )

Description

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

Parameters

p_Owner	The GUI owner of the Edit_TTSGUI window. [Optional] The default is 0 (no owner). If not defined, the AlwaysOnTop attribute is added to the Edit_TTSGUI window to make sure that the window is not lost.
hEdit	Handle to the Edit control.
p_Options	Valid options include the following:

Option
------
    Description
    -----------

Voice=x
Voice='x y'
Voice="x y"

    Specify a 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.

Volume=n

    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.

Rate=n

    Specify a rate from -10 to 10.  For example: Rate=3.  The user can
    override the rate if the "Rate" option is displayed.

Skip=n

    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.

TrackWord=n

    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.

Speak

    Begin speaking immediately.

-COM

    Do not initialize or terminate COM.  Use this option when the parent
    script uses COM for other reasons.  Important: If this option is used,
    COM must be initialized (COM_Init) before calling this function.

-Options

    Hide all Text-To-Speech options.  The following options are redundant if
    this option is used.

-Voice

    Hide the "Voice" option.

-Volume

    Hide the "Volume" option.

-Rate

    Hide the "Rate" option.

-Format

    Hide the "Format" option.

-Skip

    Hide the "Skip" option.

-TrackWord

    Hide the "Word tracking" option.  Don't confuse this option with the
    "TrackWord=0" option.

To use more than one option, include a space between each option.  For
example:

    "Voice='Microsoft Mary' Rate=3 -Format Speak"

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.

If the function is unable to create an Edit_TTSGUI window for any reason, ErrorLevel is set to the word FAIL.

Calls To Other Functions

AddTooltip
COM [Library]
Edit [Library]
PopupXY (Optional)

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 1: If closing the Edit_TTSGUI window just before ending the parent script, be sure to allow enough time for this function to release COM and Speech resources.

Important 2: 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.