XYplorer Beta Club

; copyright: autocart/Stephan Bartl (besides most of the included lib content)
; script name: XYAHK_clipboardHelper_and_XYEscToList
; version 0.03 - 200203

; changes 0.01: first version
; changes 0.02: some corrections in the comments (spelling, wrong word, shorter formulation, order of content)
; changes 0.03: ... The content of the AB did not always get resolved correctly for functionality "(5)".

...

;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
;~~~~~~~~~~~ CUSTOM SETTINGS START ~~~~~~~~~~~~~
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

...

; The detailed behaviour of the script can be fine tuned with the settings within the next chapters. The details are explained in these chapters as well.


;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; (1) Automatic or manual (Esc under defined circumstances) restoration of the latest text, image, ... clipboard content (generally none-file-system content) during or after file-system cut/copy operations
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

; Normally, if files/folders are cut/copied using the clipboard (usually from inside a file explorer window), then the previous text, image, ... (none-file-system) clipboard content is lost. In order *not* to loose that content, this script will temporarily save any new text, image, ... (none-file-system) clipboard content and then later restore this content (during or after a files/folders cut/copy operation) either (A) automatically whenever the files/folders, which are defined on the clipboard, don't exits (anymore) or (B) manually, upon pressing Esc under defined circumstances. These two cases are described below in more detail.


; >> Case A) Automatic clipboard restoration after a files/folders cut/copy operation (meaning whenever the files/folders, which are defined on the clipboard, don't exists anymore in their original location)
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

; Files/folders, which have been cut or copied using the clipboard, might get deleted from their original location either automatically e.g. if they are moved with cut/paste or also if a cut *or* copy was initiated but the files/folders are then moved with a drag-and-drop operation. Or, of course, they could also be deleted manually at any time. But regardless of how they might get deleted, if such source files/folders, which are defined on the clipboard, *all* get deleted and *none* of them exist anymore in the file system, then their information on the clipboard most likey is of no further use and thus this script restores the original text, image, ... (none-file-system) clipboard content from before the latest file/folder cut/copy operations. (If the script should act like that or not, can be defined below for cut and copy operations separately.)

; For that purpose, as soon as files/folders have been cut or copied using the clipboard, the script checks in specified intervals (which can be defined below, e.g. 500 ms) whether the source files/folders, which are defined on the clipboard, still exist or not. If the clipboard is changed while at least one of the source files/folders still exists, the script will stop checking for their existence and *not* do any clipboard restauration at this time - otherwise it might overwrite the new changed clipboard content with a restore action.

; The following 3 variables define, whether or not (during cut and copy operations) and how often the existence of the source files/folders should be checked, in order to restore the clipboard automatically once they don't exist anymore.

v_arr_cbhxetl.restoreCB_ifNONEFilesFoldersFromCBExist__forCUT := 1 ;0 or 1 ;0 => deactive ;1 => activate
v_arr_cbhxetl.restoreCB_ifNONEFilesFoldersFromCBExist__forCOPY := 1 ;0 or 1 ;0 => deactive ;1 => activate
v_arr_cbhxetl.lengthOfInterval_forCheckingExistence_ofSourceFilesFoldersOnCB_inMilliSeconds := 500 ;integer >= 0


; >> Case B) Manual clipboard restoration by pressing the Esc key under specific circumstances
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

; The clipboard can be restored manually by pressing the Esc key while
; (a) the clipboard contains definitions of cut/copied files/folders or is empty *AND*
; (b) one of the windows, defined below, is active (usually a file explorer window) *AND*
; (c) the detailed settings for the applicable window, defined below, allow it.

; Each window, in which the Esc key should potentially restore the clipboard, and its detailed settings must be defined in a window definition block as shown in 3 examples below. These 3 examples show how such a window definition block must look like: for Windows Explorer (on Win 8.1), for XYplorer (version 20) and for Directory Opus 12. The window definition and its detailed settings are explained in the comments of the first example next to each setting.

; Most likely, this script is already useable with the 3 window definition block examples, but of course the values of each setting can be adapted. (In some cases RegEx skills and/or ahk (AutoHotkey) coding skills are required for making adaptions.) For each further program, in which the Esc key should behave as described, define a new window definition block according to the pattern of the given examples.


;************** BLOCK START ********************
; Windows Explorer (in Windows 8.1):
v_arr_cbhxetl_windowData.Push({use_this_definition_block : 1 ;0 or 1 ;0 => do not use this definition block (for being able to keep the data but temporarily disable this block) ;1 => use this definition block
,regEx_ahk_mainTitlePattern : "ahk_class ^CabinetWClass$ ahk_exe \\explorer\.exe$" ;a string: ahk title pattern in RegEx (PCRE) style ;to identify the main window for this definition block
,use_EscToRestoreCB_duringCut : 1 ;0 or 1 ;when files/folders have been *cut* using the clipboard: 0 => do not use Esc ;1 => use Esc
,use_EscToRestoreCB_duringCopy : 1 ;0 or 1 ;when files/folders have been *copied* using the clipboard: 0 => do not use Esc ;1 => use Esc
,regEx_controlNames_forEscKey : "DirectUIHWND3|SysTreeView321" ;a string: window control name patterns in RegEx (PCRE) style
;(see the next setting "...prevent_0_or_limit_1..." for details); To specify more than one control name pattern use the RegEx alternation character ("|").
,definedControls_prevent_0_or_allow_1_EscKeyToRestoreClipboard_ifFilesOnCB : 1 ;0 or 1
;0 => The Esc key is allowed to restore the clipboard only if *no* controls, which are defined above, have focus. (If one of these controls *has* focus, then the Esc key behaves normally.)
;1 => If the clipboard contains file/folder definitions, then the Esc key is allowed to restore the clipboard only if one of these controls *has* focus. (If *none* of these controls has focus then the Esc key always behaves normally.)
;NOTE: If no controls are defined in "regEx_controlNames_forEscKey", then this setting here does not matter and all controls will allow Esc to restore the clipboard. (Although, other options may still prevent this.)
,expressionString_ifTrue_thenEscKeyAllowed_toRestoreClipboard : "" ;a string representing an ahk expression
;If the tuning of the Esc key's behaviour by defining window controls with the "regEx_controlNames_forEscKey" setting is not good enough, then an ahk expression can be defined here as a string. If the expression inside the string evaluates to true, then the Esc key is allowed to restore the clipboard. Otherwise the Esc key behaves normally. (The resulting *string* representing the expression should not contain variable names, however variables can of course be used to create the string. If variables are wanted as part of the expression-string, then, instead, a function should be defined somewhere in the code of this script, which can then handle the variables and which returns 0 (false) or 1 (true), and the expression-string should be a call to this function.)
;NOTE: In case that both this expression-sting and the "regEx_controlNames_forEscKey" setting is defined then both settings are respected.
,array_regEx_ahk_windowTitlePatterns_toPreventEscCBRestore : [ "ahk_class ^OperationStatusWindow$ ahk_exe \\explorer\.exe" ] }) ;a simple array of strings: ahk title patterns in RegEx (PCRE) style
;If one of the windows, which are defined in this array exists, it prevents the Esc key from clipboard restore actions. Such windows could be e.g. none-standard context/pop-up menus (see note below) or move/copy progess windows indicating that a move or copy operation is being processed right now. If such windows prevent Esc from clipboard restore actions, then the Esc key will behave normally instead. In order to not use this setting, define an empty array.
;NOTE: The script should detect standard pop-up/context menus (class #32768) belonging to the main window by default, which, again, if found, prevent the Esc key from clipboard restore actions but instead make it behave normally. Therefore pop-up/context menu window title patterns only need to be defined, if the program uses *none-standard* pop-up/context menus.
;NOTE: If the window has a standard main menu and this has focus, then that prevents the Esc key from clipboard restore actions by default. Instead, the Esc key will behave normally.
;*************** BLOCK END *********************

;************** BLOCK START ********************
; XYplorer (version 20)
v_arr_cbhxetl_windowData.Push({use_this_definition_block : 1
,regEx_ahk_mainTitlePattern : "- XYplorer ahk_class ^ThunderRT6FormDC$ ahk_exe \\XYplorer\.exe$"
,use_EscToRestoreCB_duringCut : 1
,use_EscToRestoreCB_duringCopy : 1
,regEx_controlNames_forEscKey : "Edit"
,definedControls_prevent_0_or_allow_1_EscKeyToRestoreClipboard_ifFilesOnCB : 0
,expressionString_ifTrue_thenEscKeyAllowed_toRestoreClipboard : "_XYmessenger_get(""strpos('|C|L|T|', '|' . get('FocusedControl') . '|') >= 0 && get('#178', 'Floating On', 'Floating Off') == 'Floating Off'"", , " v_arr_cbhxetl.msToWait_forReplyFromXY ")"
,array_regEx_ahk_windowTitlePatterns_toPreventEscCBRestore : [ "^$ ahk_class ^Edit$ ahk_exe \\XYplorer.exe$"
, "^$ ahk_class ^ComboLBox$ ahk_exe \\XYplorer.exe$"
, "(Move|Copy) ahk_class ^ThunderRT6Form$ ahk_exe \\XYcopy\.exe$" ] })
;*************** BLOCK END *********************

;************** BLOCK START ********************
; Directory Opus 12
v_arr_cbhxetl_windowData.Push({use_this_definition_block : 1
,regEx_ahk_mainTitlePattern : "ahk_class ^dopus\.lister$ ahk_exe \\dopus\.exe$"
,use_EscToRestoreCB_duringCut : 1
,use_EscToRestoreCB_duringCopy : 1
,regEx_controlNames_forEscKey : "dopus\.filedisplay|SysTreeView32"
,definedControls_prevent_0_or_allow_1_EscKeyToRestoreClipboard_ifFilesOnCB : 1
,expressionString_ifTrue_thenEscKeyAllowed_toRestoreClipboard : ""
,array_regEx_ahk_windowTitlePatterns_toPreventEscCBRestore : [ "^$ ahk_class ^dopus\.button\.display\.popup$ ahk_exe \\dopus\.exe$"
, "(Moving|Copying) - Directory Opus$ ahk_class ^#32770$ ahk_exe \\dopus\.exe$" ] })
;*************** BLOCK END *********************


; Finally, for both clipboard restoration options, the following variable defines up to which size (in Bytes) the clipboard content should be kept or if it should be kept at all.

; NOTE: If the clipboard content is not kept (because of this setting), then instead of any later clipboard restore action, the clipboard would simply be cleared.

v_arr_cbhxetl.maxSizeClipboardToSave_inBytes := -1 ;-1 or size in Bytes (e.g. 1000000 is 1 MB, 100000000 is 100 MB)
; This setting refers to the latest clipboard content which does *not* contain cut or copied files and is not empty; (Content which *contains* cut or copied files or an empty clipboard is anyway never saved and thus not affected by this variable):
; 1 or higher => The latest text, image, ... (none-file-system) clipboard content is saved to a variable (any previous clipboard content in that variable is discarded) and if it is smaller or equal than the specified size (in Bytes) then it is kept for later clipboard restoration. However, if it is larger than the specified size (in Bytes) then the clipboard content in that variable is immediately discarded again in order to free system memory.
; 0 => The clipboard content is never even saved.
; -1 => The latest text, image, ... (none-file-system) clipboard content is always saved for later clipboard restoration, regardless of its size (but any previously saved clipboard content is discarded).


;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; (2) Toggling the cut/copy effect on the clipboard with a user-definable keyboard shortcut
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

; If one of the windows defined in the window definition blocks above is active (and the block is used, but not caring about the other detailed window settings), then the keyboard shortcut (ahk hotkey) defined on the following line toggles the cut or copy state of file/folder definitions on the clipboard. This can be useful, if one changes his/her mind and wants to toggle the cut/copy state after having deselected the originally selected files or while having file/folder definitions on the clipboard from different paths.

v_hotkeyToUse_toToggleCBDropEffect := "^y" ;a string: a keyboard shortcut (ahk hotkey)
; This string should consist of a combination of "^"(Ctrl), "!"(Alt), "+"(Shift) and/or "#"(WinKey) followed by a "normal" key on the keyboard. (Of course, Esc should not be used, since the script uses it for other things. Other limits, enforced by your Windows OS, might also apply.) Define a blank string in order not to use this feature.


;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; (3) Automatic clean-up of outdated file/folder definitions on the clipboard
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

; When the clipboard contains cut/copied file/folder definitions, these files/folders can of course still be deleted in the file system. If that happens, then the clipboard would contain file/folder definitions of none-existend files/folders. This, again, could lead to potentially undesired, error messages, like "Item not found", when performing paste operations.

; If this setting is active, then the information of files/folders, which are deleted from the file system, is automatically removed from the clipboard as well (if present) in order to avaid error messages on pasting. For that purpose the clipboard content, if it contains cut/copied file/folder definitions, is checked periodically for existence in the file system. The interval for the checks is the same as defined in the setting "lengthOfInterval_forCheckingExistence_ofSourceFilesFoldersOnCB_inMilliSeconds" above.

; NOTE: If this setting is active and *all* files/folders, which are defined on the clipboard, are deleted or moved then ...
; (#) if the settings "restoreCB_ifNONEFilesFoldersFromCBExist__forCUT" and/or "restoreCB_ifNONEFilesFoldersFromCBExist__forCOPY" are active as well, then the latter take precedence and the latest text, image, ... (none-file-system) clipboard content is restored (for cut and/or copy, depending on which settings are active).
; (#) if the settings "restoreCB_ifNONEFilesFoldersFromCBExist__forCUT" and/or "restoreCB_ifNONEFilesFoldersFromCBExist__forCOPY" are *not* active, then the clipboard simply gets cleared without an automatic clipboard restore action (for cut and/or copy, depending on which of these two settings are *not* active). However, in this case the clipboard can potentially still be restored by pressing Esc.

; CAUTION: If this setting is active and files/folders, which are defined on the clipboard, are deleted from the file system *accidentially* before a paste operation, then, of course, these files/folders would not be pasted and the error messages would still be avoided on pasting. Therefore some folks would prefer to leave this setting deactivated, because they prefer error messages regarding the deleted files on pasting, showing them that something was potentially wrong.

v_arr_cbhxetl.removeFilesFoldersfromClipboard_ifNotExisting := 1 ;0 or 1 ;0 => deactive ;1 => activate

;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; (4) Automatic removal of duplicate file/folder definitions on the clipboard (e.g. if such get appended to the clipboard)
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

; Some programs might support appending file/folder definitions to the current clipboard (if it already contains cut/copied file/folder definitions), such as XYplorer.
; However, not all programs check for duplicate entries in order to avoid duplicate file/folder definitions on the clipboard. (At least XYplorer does not do so.)
; With the following setting, such duplicates can now be avoided.

v_arr_cbhxetl.avoidDuplicateFilesFoldersOnCB := 1 ;0 or 1 ;0 => do not check the clipboard for duplicate file/folder definitions ;1 => check and avoid duplicates

;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
; (5) Only for XYplorer: Use Esc to set focus to the list of the current pane IF the Address Bar (depending on its content), Tree, Catalog or certain controls in the X-Areas have focus
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

; With the following settings - only for XYplorer - the Esc key can be defined separately for the Address Bar (depending on its content), the Tree, the Catalog and certain controls in the "X" areas of XYplorer to set focus to the file list of the currently active pane. (The "X" areas of XYplorer are areas, which are not the Address Bar, Tree, Catalog, List, of Live Filter Box.) If a pop-up/context menu or the floating preview is visible or the main menu of XYplorer has focus, then Esc behaves normally by default.
; If active, this setting takes precedence over the clipboard restore behaviour of the Esc key. This means that focus would first switch to the file list. Pressing Esc again in the file list might then trigger the clipboard restore action or not, depending on the other settings.

v_arr_cbhxetl.XY_EscFocusesListFromAB_ifABCorrespondsToList := 1 ;0 or 1 ;0 => deactive ;1 => activate
; If the content of the Address Bar corresponds to the location shown in the list, then Escape focuses the list from inside the Address Bar.
v_arr_cbhxetl.XY_regEx_ABContent_ifMatching_EscFocusesListFromAB := "" ;a string: Address Bar content in RegEx (PCRE) style
; If the content of the Address Bar matches this RegEx string, then Escape focuses the list from inside the Address Bar. To specify an exact term, don't forget to prefix it with "^" and suffix it with "$", e.g. "^EXACTTERM$". To specify more than one text pattern use the RegEx alternation character ("|"). If Esc should always focus the list from inside the Address Bar, regardless of its content (which is not advised), then a ".*" can be specified or (for a temporary solution) a ".*|" prefixed to the rest of the value.
v_arr_cbhxetl.XY_EscFocusesList_fromTree := 1 ;0 or 1 ;0 => deactive ;1 => activate
v_arr_cbhxetl.XY_EscFocusesList_fromCatalog := 1 ;0 or 1 ;0 => deactive ;1 => activate
v_arr_cbhxetl.XY_EscFocusesList_fromXAreas := 1 ;0 or 1 ;0 => deactive ;1 => activate ;see next setting
v_arr_cbhxetl.XY_regEx_allowedControlsForXAreas := "Edit|TextBox|ComboBox|CheckBox|CommandButton|OptionButton|PictureBox" ;a string: window control name patterns in RegEx (PCRE) style
; Valid only in connection with "XY_EscFocusesList_fromXAreas" being active. If the currently focused control in XYplorer matches the defined pattern and the control lies inside an "X" area of XYplorer, then Esc sets focus to the list of the currently active pane. To specify more than one control name pattern use the RegEx alternation character ("|"). If this setting is an empty string, then "XY_EscFocusesList_fromXAreas" will not work even if activated. If "XY_EscFocusesList_fromXAreas" should work regardless of which control is active, set this setting to ".*". However, this is not advised.

;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
;~~~~~~~~~~~~ CUSTOM SETTINGS END ~~~~~~~~~~~~~~
;~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~