controls/EDIT.TODO

   1 This file gives some information about the code in edit.c.  If you want to
   2 change, add, or fix code, please read this text.  If you're not interested
   3 in doing actual work on edit.c only C & D will be of interest to you.
   4
   5 A) basic policy
   6 B) special functions
   7 C) not implemented
   8 D) known bugs
   9
  10 A) Basic Policy
  11
  12 The code has been made in such a way, that functions try to call other
  13 (documented) functions if that is sufficient.  This might sometimes not be
  14 the most efficient way, but it keeps the code clear.  This way I tried to keep
  15 the number of functions that rely on the internal EDITSTATE structure as
  16 low as possible.  For instance EDIT_WM_Cut() simply calls EDIT_WM_Copy() and
  17 EDIT_WM_Clear().  The latter two are well documented message handlers, so
  18 as long as they are right EDIT_WM_Cut() will never have to change again.
  19
  20 Example:
  21 The best thing to do, when you want to know the offset of line 3, is calling
  22 EDIT_EM_LineIndex().  Again this is a well documented message handler.  Don't
  23 look at es->LineDefs[2].offset.  It would just be another reference to the
  24 internal structure, and that would make it more difficult to change things.
  25 Refer to EDIT_WM_???? and EDIT_EM_????? functions as much as possible.
  26
  27 The WND * pointer is used internally whenever possible.  Although it is not
  28 the real HWND, it improves performance enough to use it.
  29
  30 All displaying is done by invalidating regions / rects.  Only
  31 EDIT_EM_LineScroll() uses direct painting.  This way things become much
  32 faster.  Although sometimes the response time might appear to be slow, it
  33 would be much slower even, when everything would be painted instantly.  This
  34 is especially true for scrollbar tracking and selection changes..
  35
  36
  37
  38 B) Special functions
  39
  40 The edit control needs to use local heap memory because applications may
  41 rely on EM_GETHANDLE.  This is bad, but it can't be helped, we have to live
  42 with that.  For this reason there is a nice EDIT_GetPointer() function,
  43 which locks the heap buffer *only once*, no matter how often it is called.
  44 Only at the end of the message handler EDIT_ReleasePointer() is called.  You
  45 don't have to worry about unlocking the heap.  Calling EDIT_GetPointer() is
  46 very fast if the buffer is already locked.
  47 This way, the buffer gets locked / unlock only once every message, although
  48 EDIT_GetPointer() may actually have been called a hundred times.
  49 Only when the actual HLOCAL is needed (for example to ReAlloc), a call to
  50 EDIT_ReleasePointer() is needed.  Look for instance in EDIT_MakeFit().
  51
  52 This brings us to EDIT_MakeFit().  It automatically re-allocates the buffer
  53 if the size parameter > buffersize.  If everything is successful TRUE is
  54 returned, otherwise FALSE.  Only when the buffer contents may grow you need
  55 to call EDIT_MakeFit().  Currently this is only in EDIT_ReplaceSel() and
  56 EDIT_WM_SetText().
  57
  58 EDIT_BuildLineDefs() is the most important function in edit.c.  It builds
  59 the internal EDITSTATE structure.  As soon as text *might* have changed, or
  60 when the appearance of the text on the screen *might* have changed, call
  61 this function !  This includes changes of screen size, change of the font,
  62 clipboard actions, etc. etc.  Most other functions that rely on EDITSTATE,
  63 rely on the stuff this function builds.
  64
  65
  66
  67 C) Not Implemented
  68
  69 - ES_PASSWORD
  70 - ES_CENTER
  71 - ES_RIGHT
  72 - EM_SETRECT
  73 - EM_SETRECTNP
  74 - EM_FMTLINES
  75 - ES_AUTOVSCROLL (every multi line *is* auto vscroll)
  76 - ES_AUTOHSCROLL (multi line can be yes or no, but single line only yes)
  77 - WM_UNDO (=EM_UNDO)
  78 - EM_CANUNDO
  79 - EM_SCROLL (scrolling works, but this appears to be an undocumented message)
  80 - ES_LOWERCASE
  81 - ES_UPPERCASE
  82 - ES_OEMCONVERT
  83 - ES_WANTRETURN
  84 - probably much, MUCH more
  85
  86 I encountered several undocumented messages, or message parameters.
  87 EditWndProc() reports any unknown message with an id > WM_USER.
  88
  89
  90
  91 D) Known bugs.
  92
  93 -       Scrolling is weird, sometimes.  The current code makes the scrollbar
  94         of Notepad work, but the scrollbar code itself is broken.  Currently
  95         the scroll code of edit.c is *not* according to specs.  Instead, it
  96         is according to the broken scrollbar code.  If that gets fixed, this
  97         should be fixed, too.
  98 -       The clipboard is broken.  Whenever things go wrong with
  99         cut/copy/paste, it is probably the clipboard that messes up things,
 100         not edit.c.
 101 -       Turning on WordWrap with Notepad leaves part of the horizontal
 102         scrollbar visible (problem with WM_ERASEBKGND ???).
 103
 104
 105 I am still very actively changing things.  Especially I am working
 106 on Undo capabilities.  If you want to do things, other than bug fixes,
 107 please mail me so we can synchronize.
 108
 109 Frans van Dorsselaer
 110 dorssel@rulhm1.LeidenUniv.nl