Proposal for API finder_proc()

API

finder_proc(id_finder, id_action, value="", setcaret=True)

Param “id_finder” is int handle of finder object to work with.

All find/replace actions return error values, in addition to normal results:

• None, if search-text is empty, or editor is not set, or editor has no carets.
• False, if RegEx is incorrect.

Possible values of “id_action”:

• FINDER_CREATE: Creates new finder object and returns its int handle. Param “id_finder” must be 0 here.

• FINDER_FREE: Deallocates finder object, you cannot use handle after this call.

• FINDER_CLEAR: Clears/resets finder object (text strings, editor handle, options, etc).

• FINDER_SET_FINDTEXT: Sets string to search for.

• FINDER_GET_FINDTEXT: Returns string to search for.

• FINDER_SET_REPTEXT: Sets string to replace with.

• FINDER_GET_REPTEXT: Returns string to replace with.

• FINDER_SET_ED: Sets int handle of Editor object, to perform search/replace in this editor. Handle of “ed” and other special objects is allowed, it will be resolved to real handle (memory address), and FINDER_GET_ED will get the real handle. So, if you pass ed’s handle (ed.h==0), don’t work with the finder after the editor is deleted (ui-tab is closed).

• FINDER_GET_ED: Returns int handle of Editor object.

• FINDER_SET_OPT: Sets search options as string.

• FINDER_GET_OPT: Returns search options as string.

• FINDER_SET_MAXLEN: Sets maximal length of line, which is handled by finder (longer lines are skipped). It is 0x7FFFFFFF by default.

• FINDER_GET_MAXLEN: Returns maximal length of line.

• FINDER_SET_CARETS: Sets virtual carets as string. When this value is not empty, finder object uses caret positions from this value, instead of real editor’s carets. Instead of first editor caret, finder will use first virtual caret (first by text position). This way plugin can search/replace from custom position, and inside custom ranges (using search options “from caret”, “in selection”). ** Value must be “;”-separated items, each item must be in the form “x,y,x2,y2” or just “x,y” (0-based text coordinates). ** Fields (x2, y2) can be skipped and can be -1, to set caret without selection. ** Trailing chars “,” and “;” are optional. ** Finder will sort carets anyway. First caret will be taken from the sorted list.

• FINDER_GET_CARETS: Returns virtual carets as string.

• FINDER_SET_INDENTS: Sets indents, used to scroll editor on setting caret. Param “value” must be tuple (indent_horz, indent_vert), meaning of values is like for CudaText options “find_indent_horz”/“find_indent_vert”.

• FINDER_GET_INDENTS: Returns indents, as tuple (indent_horz, indent_vert).

• FINDER_SET_TAG: Sets tag string. It’s any plugin-defined string, not used by program.

• FINDER_GET_TAG: Returns tag string.

• FINDER_SET_ON_REPLACE: Sets callback to handle confirmations. It is used with finder option “confirm on replace”. ** It must be a string in only one format: “module.method” (method in “Command” class). ** Method signature and example are shown below. ** Possible return values in method: HOWREP_CANCEL, HOWREP_REPLACE, HOWREP_SKIP. ** Also method can return string, to change the replacement string. Default replacement string is in the “text” param.

• FINDER_GET_ON_REPLACE: Returns callback to handle confirmations.

• FINDER_FIND: Finds a match. ** Start position: if “from caret” option is on, then position of first caret; otherwise document begin (or end, for backward search). ** Param “setcaret” is bool: place caret/selection on found position. ** Returns position as 4-tuple (x1, y1, x2, y2), or None if not found.

• FINDER_FIND_REP: Finds and replaces a match. ** Params are the same as for FINDER_FIND. ** Returns tuple (x1, y1, x2, y2, x_after, y_after), or None if not found. ** Fields (x_after, y_after) are position after replaced block, or (-1, -1) if no replace was made (due to replace confirmation).

• FINDER_FIND_ALL: Finds all matches. ** Returns list of position 4-tuple (x1, y1, x2, y2).

• FINDER_COUNT: Counts all matches. It is faster than FINDER_FIND_ALL. ** Returns number of matches.

• FINDER_REP_ALL: Replaces all matches. ** Returns number of replaces made. ** Number of replaces can be less than number of found matches, due to canceled replace confirmations.

• FINDER_REP_ALL_EX: Replaces all matches. Returns detailed report. ** Returns list of tuples (x1, y1, x2, y2, x_after, y_after). ** Fields (x_after, y_after) are position after replaced block, or (-1, -1) if no replace was made (due to replace confirmation).

Confirmation callback example:

class Command:
    def finder_confirm(self, ed_self, x1, y1, x2, y2, text):
        if x1==0:
            return '(replacement at line start)'            
                    
        r = msg_box('Replace text at (%d,%d)-(%d,%d) ?'%(x1, y1, x2, y2),
                    MB_YESNOCANCEL+MB_ICONQUESTION) 
                    
        if r==ID_CANCEL:
            return HOWREP_CANCEL
        elif r==ID_YES:
            return HOWREP_REPLACE
        else:
            return HOWREP_SKIP

[Alexey-T]

Added useful feature- virtual carets! See FINDER_SET_CARETS. added in proposal only.

[Alexey-T]

@kvichans Апи обсудим в отдельном топике, тут слиш. жарко.