home *** CD-ROM | disk | FTP | other *** search
/ QBasic & Borland Pascal & C / Delphi5.iso / C / BC_502 / ADDONINC.PAK / IEDITOR.H < prev    next >
Encoding:
C/C++ Source or Header  |  1997-05-06  |  19.3 KB  |  612 lines
  1. /*:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
  2.  
  3.    ieditor.h
  4.    Created: 09/18/95
  5.    Copyright (c) 1995, Borland International
  6.    $Header:   Y:/ADMIN/BRIDE/ADDON/DELIVER/INTERFAC/IEDITOR.H_V   1.21   15 Jan 1997 10:53:22   JDOUGLAS  $
  7.    $Revision:   1.21  $
  8.  
  9.    IDEHOOK-style editor interface
  10.  
  11.    IDEHOOK CHANGES (overview, see individual methods for specifics)
  12.    ---------------
  13.  
  14.       register_keyhit_handlers()
  15.       --------------------------
  16.       This is now obsolete. The same functionality
  17.       can and should be implemented through script, since all key handlers,
  18.       even those being used by the internal IDE clients, are now script-based.
  19.       Use the IScriptServer interface to run a script or script command that
  20.       works with the following classes and methods to set up keyboard handling:
  21.  
  22.          KeyboardManager::GetKeyboard()
  23.          Keyboard::Assign()
  24.  
  25.       Consult the cScript reference for more information regarding keyboard
  26.       handling.
  27.  
  28.       free_string()
  29.       -------------
  30.       Since we're now using IPolyString *'s, there is no longer a need for this 
  31.       method, follow normal reference counting rules and Release() the poly
  32.       string when you're done with it.
  33.  
  34.       New Methods
  35.       -----------
  36.       undo_available()
  37.       undo()
  38.       redo_available()
  39.       redo()
  40.  
  41.       return values
  42.       -------------
  43.       Several return values have been more clearly defined to return 1 for 
  44.       success and 0 for failure. These changes don't reflect any actual 
  45.       difference in the return values except where specifically noted in 
  46.       the individual method descriptions.
  47.       
  48.     Methods by Category
  49.     ------------------
  50.     Transaction Bracketing:
  51.         begin_edit()              
  52.         end_edit (void)          
  53.  
  54.     Cursor Movement Methods
  55.         beginning_of_line()            
  56.         end_of_line()                    
  57.         down()                            
  58.         goto_line()        
  59.         goto_old_line() 
  60.         left()                            
  61.         move_abs()
  62.         move_rel()
  63.         next_char()
  64.         prev_char()
  65.         right()
  66.         up()     
  67.         top_of_buffer()
  68.         end_of_buffer()
  69.  
  70.     Block Methods
  71.         drop_anchor()
  72.         raise_anchor()
  73.         delete_block()
  74.  
  75.     Editting Methods
  76.         backspace()
  77.         delete_char()
  78.         delete_line()
  79.         delete_to_eol()
  80.         insert()
  81.         translate()
  82.         undo_available()
  83.         undo()
  84.         redo_available()
  85.         redo()
  86.       
  87.     Buffer/View Methods 
  88.    Note: View-related results are based on and reflected in the top view of 
  89.    the buffer set with set_buffer.
  90.         create_buffer()
  91.         delete_buffer()
  92.         distance_to_tab()
  93.         inq_buffer()
  94.         inq_line_length()
  95.         inq_modified()
  96.         inq_names()
  97.         inq_position()
  98.         inq_views()
  99.         next_buffer()
  100.         read()
  101.         read_file()
  102.         refresh()
  103.         save_buffer()
  104.         search_back()
  105.         search_fwd()
  106.         set_buffer()
  107.         set_top_left()
  108.         show_buffer()
  109.         top_of_window()
  110.         end_of_window()
  111.         page_down()
  112.         page_up()  
  113.       reload_buffer()
  114.       
  115.  
  116. :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::*/  
  117.  
  118. #ifndef _IEDITOR_H_
  119. #define _IEDITOR_H_
  120.  
  121. #include <objbase.h>
  122. #include <ideaddon\IPolyStr.h>
  123. #include    <ideaddon\IEditor.uid>
  124. #include <ideaddon\common.h>
  125.  
  126. typedef DWORD BufferId;
  127.  
  128. //.............................................................................
  129. enum MarkType
  130. {
  131.    MT_Normal = 1,
  132.    MT_Column = 2,
  133.    MT_Line = 3,
  134.    MT_Noninclusive = 4
  135. };
  136.  
  137.  
  138. //.............................................................................
  139. class IEditorServer : public IUnknown 
  140. {
  141.  public:
  142.  
  143.     //
  144.     // Always bracket an editing "session" on a particular buffer with 
  145.     // begin_edit() and end_edit().
  146.    // 
  147.    // In other words, if you are going to use one or more edit functions 
  148.    // on one buffer inside a routine, start with begin_edit(), use any of the 
  149.    // other functions to do what you need to do, then call end_edit() when 
  150.    // you're done. begin_edit() and end_edit() should surround the edits
  151.    // to a single buffer only. You should only call set_buffer() after having
  152.    // called begin_edit().
  153.    //
  154.    // Here is an example of correct begin/end usage when iterating over 
  155.    // all open buffers
  156.    //
  157.    //      IEditorServer * editor = GET_INTERFACE( IEditorServer ); 
  158.    //      BufferId buf = editor->inq_buffer();
  159.    //      BufferId firstBuf = buf;
  160.    //      if ( buf ) {
  161.    //         do {
  162.    //            editor->begin_edit();
  163.    //            editor->set_buffer( buf );
  164.    //            //
  165.    //            // do stuff to the edit buffer...
  166.    //            //
  167.    //            editor->end_edit();
  168.    //            buf = editor->next_buffer();
  169.    //         } while ( buf != firstBuf );
  170.    //      }
  171.    //      editor->Release();
  172.    //
  173.    // 
  174.    
  175.     virtual void BCWADDON_CMETHOD begin_edit (void) = 0;
  176.     virtual void BCWADDON_CMETHOD end_edit (void) = 0;
  177.  
  178.    // 
  179.    // Moves the cursor to the first character of the current line
  180.    // Returns 1 when successful, else 0
  181.    //
  182.    virtual int BCWADDON_CMETHOD beginning_of_line() = 0;
  183.  
  184.    //
  185.    // Moves the cursor to the previous character on the current line and 
  186.    // deletes it.
  187.    // Returns 1 when successful, else 0
  188.    //
  189.    virtual int BCWADDON_CMETHOD backspace() = 0;
  190.  
  191.    //
  192.    // Creates a buffer containing an existing or new file.
  193.    // 'system' should be set to 1 to create a system buffer
  194.    //    - system buffers don't support undo, are not seen by the user
  195.    //      and can't be compiled. These are handy for saving a safety
  196.    //      a copy of a buffer before making masive changes.
  197.    // 
  198.    // Returns the BufferId or zero if unsuccessful.
  199.    // 
  200.    // IDEHOOK CHANGES:
  201.    //    - Since 'buffer_name' was ignored, we've removed it.
  202.    //    - the 'system' flag was not previously supported.
  203.    //    - File name is now a IPolyString *.
  204.    // 
  205.    virtual BufferId BCWADDON_CMETHOD create_buffer( IPolyString * file_name, int system ) = 0;
  206.  
  207.    //
  208.    // Deletes the marked block (if there is one) in the current buffer.
  209.    // Returns 1 if successful, else 0.
  210.    //
  211.    virtual int BCWADDON_CMETHOD delete_block() = 0;
  212.  
  213.    //
  214.    // Deletes a buffer from memory if there are no windows containing
  215.    // views on the buffer.
  216.    // Returns 1 if successful, else 0.
  217.    // 
  218.    virtual int BCWADDON_CMETHOD delete_buffer( BufferId buffer_id ) = 0;
  219.  
  220.    //
  221.    // Deletes one or more characters at the current position.
  222.    // Returns 1 when successful, else 0
  223.    //
  224.    virtual int BCWADDON_CMETHOD delete_char( int num_to_delete = 1 ) = 0;
  225.  
  226.    //
  227.    // Deletes the current line.
  228.    //
  229.    virtual void BCWADDON_CMETHOD delete_line() = 0;
  230.  
  231.    //
  232.    // Deletes from the current position to the end of the current line.
  233.    //
  234.    virtual void BCWADDON_CMETHOD delete_to_eol() = 0;
  235.  
  236.    //
  237.    // Returns the number of columns between the current position and the next
  238.    // tab stop.
  239.    //
  240.    virtual long BCWADDON_CMETHOD distance_to_tab() = 0;
  241.  
  242.    //
  243.    // Moves the current position one line down.
  244.    // Returns 1 if the position changed, else 0.
  245.    //
  246.    virtual int BCWADDON_CMETHOD down() = 0;
  247.  
  248.    //
  249.    // Starts marking a block at the current position in the current buffer.
  250.    // The mark types match the original brief mark types and are consistent
  251.    // with IDEHOOK (see the MarkType enum above).
  252.    //
  253.    virtual void BCWADDON_CMETHOD drop_anchor( MarkType mark_type = (MarkType) 1 ) = 0;
  254.  
  255.    //
  256.    // Moves to the last character in the current buffer.
  257.    // Returns 1 if the position has changed, else 0.
  258.    //
  259.    virtual int BCWADDON_CMETHOD end_of_buffer() = 0;
  260.  
  261.    //
  262.    // Moves to the last character on the current line.
  263.    // Returns 1 if the position has changed, else 0.
  264.    //
  265.    virtual int BCWADDON_CMETHOD end_of_line() = 0;
  266.  
  267.    //
  268.    // Moves to the last line of the current window.
  269.    // Returns 1 if the position has changed, else 0.
  270.    //
  271.    virtual int BCWADDON_CMETHOD end_of_window() = 0;
  272.  
  273.    //
  274.    // Moves the cursor to the beginning of a specific line.
  275.    // Returns 1 if successful, else 0.
  276.    //
  277.    virtual int BCWADDON_CMETHOD goto_line( long line ) = 0;
  278.  
  279.    //
  280.    // Moves the cursor as close as possible to a line in the original,
  281.    // unchanged file that is associated with the current buffer.
  282.    // Returns 1 if successful, else 0.
  283.    // 
  284.    // IDEHOOK_CHANGES:
  285.    //    - The original BRIEF doc states that the return from this function
  286.    //      will be zero or less if unsuccesful and, in fact, the return from 
  287.    //      this method used to be -1 when unsuccesful. Since this is in-
  288.    //      consistent with most of the other return values, it has been 
  289.    //      changed to return 0 if unsuccessful.
  290.    //
  291.    virtual int BCWADDON_CMETHOD goto_old_line( long line ) = 0;
  292.  
  293.    //
  294.    // Returns a buffer identifier associated with the current buffer,
  295.    // in which case 'filename' should be NULL, or that of the buffer 
  296.    // specified by 'filename'.
  297.    // 
  298.    // IDEHOOK CHANGES:
  299.    //    - fileName is now a IPolyString *
  300.    //
  301.    virtual BufferId BCWADDON_CMETHOD inq_buffer( IPolyString * fileName = NULL ) = 0;
  302.  
  303.    //
  304.    // Returns the length of the current line in characters.
  305.    //
  306.    virtual int BCWADDON_CMETHOD inq_line_length() = 0;
  307.  
  308.    //
  309.    // Returns the modification status of the current buffer.
  310.    // 
  311.    // Returns values: 
  312.    //   -1 if current buffer not found
  313.    //    0 if not modified 
  314.    //    1 if modified
  315.    //
  316.    virtual int BCWADDON_CMETHOD inq_modified() = 0;
  317.  
  318.    //
  319.    // Returns one or more strings associated with the current buffer:
  320.    //    full_name: File name with path and drive letter
  321.    //    extension: only the extension part of the file name
  322.    //    buffer_name: file name without the path
  323.    // 
  324.    // Pass in NULL for args you don't care to receive.
  325.    // Otherwise, use CreatePolyString() to get a pointer to an uninitialized
  326.    // poly string and pass a pointer to it to the arg, or pass a pointer to
  327.    // a NULL IPolyString pointer.
  328.    // In either case, you'll want to call Release() on the returned poly string 
  329.    // when you're done with it.
  330.    // 
  331.    // IDEHOOK CHANGES:
  332.    //    - String arguments are now all pointers to IPolyString *'s
  333.    //
  334.    virtual void BCWADDON_CMETHOD inq_names(    IPolyString * * full_name = NULL, 
  335.                               IPolyString * * extension = NULL, 
  336.                               IPolyString * * buffer_name = NULL ) = 0;
  337.  
  338.    //
  339.    // Returns zero if the current position is not past the end-of-buffer.
  340.    // Else, returns the number of lines between the end-of-buffer and the 
  341.    // current position.
  342.    // Line number and column are optionally returned in the 'line' and 'col' 
  343.    // arguments.
  344.    //
  345.    virtual int BCWADDON_CMETHOD inq_position( long * line = 0, long * col = 0 ) = 0;
  346.  
  347.    //
  348.    // Returns the number of windows that are viewing either the current
  349.    // or specified buffer.
  350.    //
  351.    virtual int BCWADDON_CMETHOD inq_views( BufferId buffer_id = 0 ) = 0;
  352.  
  353.    //
  354.    // Inserts 'string' into the current buffer
  355.    // 
  356.    // IDEHOOK CHANGES:
  357.    //    - the string arg is now a IPolyString *
  358.    //
  359.    virtual void BCWADDON_CMETHOD insert( IPolyString * string ) = 0;
  360.  
  361.  
  362.    //
  363.    // Moves the current position one column left.
  364.    // Returns 1 if the position has changed, else 0.
  365.    //
  366.    virtual int BCWADDON_CMETHOD left() = 0;
  367.  
  368.    //
  369.    // Move to the line/column specified.
  370.    // If zero is used for either arg, then the current position is used for
  371.    // that argument.
  372.    // Returns 1 if the position has changed, else 0.
  373.    //
  374.    virtual int BCWADDON_CMETHOD move_abs( long line = 0, long column = 0 ) = 0;
  375.  
  376.    //
  377.    // Move to the relative line/column position specified.
  378.    // Returns 1 if the position has changed, else 0.
  379.    //
  380.    virtual int BCWADDON_CMETHOD move_rel( long num_lines = 0, long num_columns = 0 ) = 0;
  381.  
  382.    //
  383.    // Returns the BufferId for the next buffer.
  384.    // 
  385.    // IDEHOOK CHANGES:
  386.    //    - the 'system_too' parameter was and will not be supported, so we've
  387.    //      removed it. (note: verified by looking in ferengi's 
  388.    //      ide\idecommon\ideedit.cpp implementation of this).
  389.    //
  390.    virtual BufferId BCWADDON_CMETHOD next_buffer() = 0;
  391.  
  392.    //
  393.    // Moves the current position to the next character, wrapping to the
  394.    // next line where appropriate. Optionally moves by 'num_chars' characters.
  395.    // 
  396.    // Returns 1 if the position has changed, else 0.
  397.    //
  398.    virtual int BCWADDON_CMETHOD next_char( int num_chars = 1 ) = 0;
  399.  
  400.    //
  401.    // Moves the cursor position down by one page.
  402.    //
  403.    // Returns 1 if the position has changed, else 0.
  404.    //
  405.    virtual int BCWADDON_CMETHOD page_down() = 0;
  406.  
  407.    //
  408.    // Moves the cursor position up by one page.
  409.    //
  410.    // Returns 1 if the position has changed, else 0.
  411.    //
  412.    virtual int BCWADDON_CMETHOD page_up() = 0;
  413.  
  414.    //
  415.    // Moves the current position to the previous character, wrapping to the
  416.    // previous line where appropriate. Optionally moves by 'num_chars' 
  417.    // characters.
  418.    // 
  419.    // Returns 1 if the position has changed, else 0.
  420.    //
  421.    virtual int BCWADDON_CMETHOD prev_char( int num_chars = 1 ) = 0;
  422.  
  423.    //
  424.    // Raises the last mark that was dropped with drop_anchor().
  425.    //
  426.    virtual void BCWADDON_CMETHOD raise_anchor() = 0;
  427.  
  428.    //
  429.    // Reads characters from the current buffer.
  430.    // If 'length' is specified, reads 'length' number of chars, including
  431.    // end-of-line chars. Otherwise, reads from the current position through
  432.    // the end-of-line. The current position remains unchanged.
  433.    // 
  434.    // IDEHOOK CHANGES:
  435.    //    - Returns a IPolyString * instead of a char *, therefore the 'free_string()'
  436.    //    method no longer exists and the caller should free the string using 
  437.    //    SysFreeString().
  438.    //
  439.    virtual IPolyString * BCWADDON_CMETHOD read( int length = 0 ) = 0;
  440.  
  441.    //
  442.    // Reads a copy of the file into the current buffer.
  443.    // 
  444.    // Returns 0 if the command failed, else 1.
  445.    //
  446.    // IDEHOOK CHANGES:
  447.    //    - 'filename' is now a IPolyString * instead of a char *
  448.    //    - Used to return -1 on failure. Changed in the interest of 
  449.    //      consistency with other methods.
  450.    // 
  451.    virtual int BCWADDON_CMETHOD read_file( IPolyString * filename ) = 0;
  452.  
  453.    //
  454.    // Redraws the current buffer
  455.    //
  456.    virtual void BCWADDON_CMETHOD refresh() = 0;
  457.  
  458.    //
  459.    // Moves the current position one column to the right.
  460.    // Returns 1 if the position has changed, else 0.
  461.    //
  462.    virtual int BCWADDON_CMETHOD right() = 0;
  463.  
  464.    //
  465.    // Saves the current buffer to disk (this is a quiet save).
  466.    // 
  467.    // Returns zero for failure, 1 for success.
  468.    // 
  469.    // IDEHOOK CHANGES:
  470.    //    - write_buffer() is now obsolete, use this instead
  471.    //
  472.    virtual int BCWADDON_CMETHOD save_buffer() = 0;
  473.  
  474.    //
  475.    // Searches the current buffer (back and forward methods). 
  476.    // 
  477.    // 'pattern': a string containing the pattern to search for
  478.    // 'regularExp': turn regular expression searching on (non-zero) or off (0)
  479.    // 'caseSen': turn case sensitivity on (non-zero) or off (0)
  480.    // 'block': confine the search to the current block (non-zero)
  481.    // 
  482.    // Returns zero if not found, otherwise the text length
  483.    // 
  484.    // IDEHOOK_CHANGES:
  485.    //    (the following don't represent any change in behavior or capabillity)
  486.    //    - 'pattern' is now a IPolyString *
  487.    //    - 'grep' has been dropped, and was not previously supported
  488.    //    - 'total_length' has been dropped and is now returned, this differs
  489.    //       from the original implementation in that (length + 1) used to be 
  490.    //       returned unless it was greater than 65,534, etc...
  491.    //
  492.    virtual int BCWADDON_CMETHOD search_back(   IPolyString * pattern,
  493.                               int regularExp = 1,
  494.                               int caseSen = 1,
  495.                               int block = 0 ) = 0;
  496.  
  497.    virtual int BCWADDON_CMETHOD search_fwd(    IPolyString * pattern,
  498.                               int regularExp = 1,
  499.                               int caseSen = 1,
  500.                               int block = 0 )= 0;
  501.  
  502.  
  503.    //
  504.    // Makes the specified buffer current.
  505.    // 
  506.    // Returns the previously current BufferId.
  507.    //
  508.    virtual BufferId BCWADDON_CMETHOD set_buffer( BufferId buffer_id ) = 0;
  509.  
  510.    //
  511.    // Sets the upper left corner of the current buffer to the line and/or 
  512.    // column specfied. 
  513.    //
  514.    // IDEHOOK CHANGES:
  515.    //    - 'window_id', 'line', 'col', and 'buffer_id' were all previously
  516.    //       ignored. They have been removed in the interest of clarity.
  517.    // 
  518.    virtual void BCWADDON_CMETHOD set_top_left( long top_line, long left_col ) = 0;
  519.    
  520.    //
  521.    // Moves an MDI window on the current buffer to the top of the window
  522.    // stack. If no such window exists, one is created.
  523.    //
  524.    virtual void BCWADDON_CMETHOD show_buffer() = 0;
  525.    
  526.    //
  527.    // Moves the current position to the first character in the current buffer.
  528.    //
  529.    // Returns 1 if the position has changed, else 0.
  530.    // 
  531.    virtual int BCWADDON_CMETHOD top_of_buffer() = 0;
  532.  
  533.    //
  534.    // Moves the current position to the top line of the current window.
  535.    // 
  536.    // Returns 1 if the position has changed, else 0.
  537.    //
  538.    virtual int BCWADDON_CMETHOD top_of_window() = 0;
  539.  
  540.    //
  541.    // Translates occurrences of a specified pattern to a replacement string.
  542.    //
  543.    // 'pattern': a string containing the pattern to search for
  544.    // 'replacement': the replacement string
  545.    // 'global_flag': translate all (non-zero) or first-only (0) occurances
  546.    // 'regularExp': turn regular expression searching on (non-zero) or off (0)
  547.    // 'caseSen': turn case sensitivity on (non-zero) or off (0)
  548.    // 'block': confine the search to the current block (non-zero)
  549.    // 'forward': search forward (non-zero) or backward (0)
  550.    // 
  551.    // Returns the number of translated occurences.
  552.    // 
  553.    // IDEHOOK_CHANGES:
  554.    //    - 'pattern' and 'replacement' are now IPolyString *'s
  555.    //    - 'grep' has been dropped, and was not previously supported
  556.    //
  557.    virtual int BCWADDON_CMETHOD translate(  IPolyString * pattern,
  558.                            IPolyString * replacement,
  559.                            int global_flag,
  560.                            int regularExp = 1,
  561.                            int caseSen = 1,
  562.                            int block = 0,
  563.                            int forward = 1 ) = 0;
  564.  
  565.  
  566.    //
  567.    // Moves the current position one line up.
  568.    // Returns 1 if the position has changed, else 0.
  569.    //
  570.    virtual int BCWADDON_CMETHOD up() = 0;
  571.  
  572.    //
  573.    // Returns TRUE if the current buffer currently supports a call to undo().
  574.    //
  575.    virtual BOOL BCWADDON_CMETHOD undo_available() = 0;
  576.    //
  577.    //
  578.    // Performs an undo on the current buffer.
  579.    // Returns 1 for success, 0 for failure.
  580.    //
  581.    virtual void BCWADDON_CMETHOD undo() = 0;
  582.    //
  583.    //
  584.    // Returns FALSE if the current buffer currently supports a call to redo().
  585.    //
  586.    virtual BOOL BCWADDON_CMETHOD redo_available() = 0;
  587.    //
  588.    //
  589.    // Performs a redo on the current buffer.
  590.    // Returns 1 for success, 0 for failure.
  591.    //
  592.    virtual void BCWADDON_CMETHOD redo() = 0;
  593.  
  594. };
  595.  
  596. class IEditorServer2 : public IEditorServer
  597. {
  598.  public:
  599.    // Reloads a buffer from disk, without asking the user whether to
  600.    // overwrite the currently loaded buffer.
  601.    //
  602.    // Returns zero for failure, 1 for success.
  603.    //
  604.    virtual int BCWADDON_CMETHOD reload_buffer(BufferId buffer_id) = 0;
  605.  
  606. };
  607.  
  608. #endif
  609.  
  610.  
  611.  
  612.