From bc8bd37c801d0a8c88052c323b780e88fb2ec13b Mon Sep 17 00:00:00 2001 From: nyamatongwe Date: Mon, 24 Jul 2000 12:16:35 +0000 Subject: Updated documentation for removal of WM_* and EM_* and addition of direct features. --- doc/ScintillaDoc.html | 173 +++++++++++++++++++++++++++++++++----------------- 1 file changed, 115 insertions(+), 58 deletions(-) (limited to 'doc/ScintillaDoc.html') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 0cfae5b05..7fc43f4ea 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -37,9 +37,11 @@

The Windows version of Scintilla is a Windows Control. As such, its primary programming - interface is through Windows messages. It responds to many of the messages defined for the - standard Edit and Richedit controls as well as a suite of its own for controlling syntax - styling, markers, auto-completion and call tips. + interface is through Windows messages. Early versions of Scintilla emulated much of the + API defined by the standard Windows Edit and Richedit controls but those APIs are now + deprecated in favour of Scintilla's own, more consistent API. + In addition to messages performing the actions of a normal Edit control, Scintilla + allows control of syntax styling, markers, auto-completion and call tips.

The GTK+ version also uses messages in a similar way to the Windows version. This is different to normal GTK+ practice but made it easier to implement rapidly. @@ -50,13 +52,13 @@ Text retrieval and modification. 
-WM_GETTEXT(int length, char *text)
-WM_SETTEXT(<unused>, char *text)
-EM_GETLINE(int line, char *text)
-EM_REPLACESEL(<unused>, char *text)
-EM_SETREADONLY
+SCI_GETTEXT(int length, char *text)
+SCI_SETTEXT(<unused>, char *text)
+SCI_GETLINE(int line, char *text)
+SCI_REPLACESEL(<unused>, char *text)
+SCI_SETREADONLY
 SCI_GETREADONLY
-EM_GETTEXTRANGE(<unused>, TEXTRANGE *tr)
+SCI_GETTEXTRANGE(<unused>, TEXTRANGE *tr)
 SCI_ADDTEXT(int length, char *s)
 SCI_ADDSTYLEDTEXT(int length, cell *s)
 SCI_INSERTTEXT(int pos, char *text)
@@ -99,18 +101,19 @@ SCI_GETSTYLEBITS
        Standard commands
     
 
-WM_CUT
-WM_COPY
-WM_PASTE
-WM_CLEAR
+SCI_CUT
+SCI_COPY
+SCI_PASTE
+SCI_CLEAR
+SCI_CANPASTE
 

     

        Undo and Redo
     

 
-WM_UNDO
-EM_CANUNDO
-EM_EMPTYUNDOBUFFER
+SCI_UNDO
+SCI_CANUNDO
+SCI_EMPTYUNDOBUFFER
 SCI_REDO
 SCI_CANREDO
 SCI_SETUNDOCOLLECTION(bool collectUndo)
@@ -130,30 +133,21 @@ SCI_ENDUNDOACTION
        Selection and information
     
 
-WM_GETTEXTLENGTH
-EM_GETFIRSTVISIBLELINE
-EM_GETLINECOUNT
-EM_GETMODIFY
-EM_SETMODIFY(bool ismodified)
-EM_GETRECT(RECT *rect)
-EM_GETSEL(int *start, int *end)
-EM_EXGETSEL(<unused>, CHARRANGE *cr)
-EM_SETSEL(int start, int end)
-EM_EXSETSEL(<unused>, CHARRANGE *cr)
-EM_GETSELTEXT(<unused>, char *text)
-EM_LINEFROMCHAR(int position)
-EM_EXLINEFROMCHAR(int position)
-EM_LINEINDEX(int line)
-EM_LINELENGTH(int position)
-EM_SCROLL(int line)
-EM_LINESCROLL(int column, int line)
-EM_SCROLLCARET()
-EM_CANPASTE
-EM_CHARFROMPOS(<unused>, POINT *location)
-SCI_POSITIONFROMPOINT(<unused>, POINT *location)
-EM_POSFROMCHAR(int position, POINT *location)
-EM_SELECTIONTYPE
-EM_HIDESELECTION(bool hide)
+SCI_GETTEXTLENGTH
+SCI_GETFIRSTVISIBLELINE
+SCI_GETLINECOUNT
+SCI_GETMODIFY
+SCI_SETSEL(int start, int end)
+SCI_GETSELTEXT(<unused>, char *text)
+SCI_LINEFROMPOSITION(int position)
+SCI_POSITIONFROMLINE(int line)
+SCI_LINELENGTH(int line)
+SCI_LINESCROLL(int column, int line)
+SCI_SCROLLCARET
+SCI_POSITIONFROMPOINT(int x, int y)
+SCI_POINTXFROMPOSITION(<unused>, int position)
+SCI_POINTYFROMPOSITION(<unused>, int position)
+SCI_HIDESELECTION(bool hide)
 SCI_GETLENGTH
 SCI_SETCURRENTPOS(int position)
 SCI_GETCURRENTPOS
@@ -167,7 +161,6 @@ SCI_SELECTALL
 SCI_GOTOLINE(int line)
 SCI_GOTOPOS(int position)
 SCI_GETCURLINE(int textlen, char *text)
-SCI_LINELENGTH(int line)
 SCI_SETCARETPOLICY(int policy)
 SCI_LINESONSCREEN
 SCI_SELECTIONISRECTANGLE
@@ -179,8 +172,8 @@ SCI_GETHSCROLLBAR
       current position.
     

     

-       EM_SETMODIFY is no longer supported as whether the document is modified is determined by
-      whether the undo position is at the save point.
+       It is not possible to change the modified status as whether the document is modified is 
+       determined by whether the undo position is at the save point.
     

     

        SCI_GETCURLINE retrieves the text of the line containing the caret and returns the position
@@ -195,8 +188,7 @@ SCI_GETHSCROLLBAR
        Searching
     
 
-EM_FINDTEXT(int flags, FINDTEXTEX *ft)
-EM_FINDTEXTEX(int flags, FINDTEXTEX *ft)
+SCI_FINDTEXT(int flags, FINDTEXTEX *ft)
 

     

        Scintilla can find where a string is present in its document.
@@ -344,16 +336,14 @@ SCI_SETCARETPERIOD(int milliseconds)
        Margins
     
 
-EM_GETMARGINS 
-EM_SETMARGINS(EC_LEFTMARGIN or EC_RIGHTMARGIN or EC_USEFONTINFO, int val)
+SCI_SETMARGINLEFT(int width)
+SCI_GETMARGINLEFT 
+SCI_SETMARGINRIGHT(int width)
+SCI_GETMARGINRIGHT
 

     

        Gets or sets the width of the blank margin on both sides of the text. This defaults to one
-      pixel on each side. val contains a left margin size in its low word and a right margin size
-      in its high word. This is also the way that EM_GETMARGINS returns the current setting.
-      EC_LEFTMARGIN and EC_RIGHTMARGIN are bit flags that can be used individually or combined to
-      set both margins at once. EC_USEFONTINFO ignores val and sets both margins to be half the
-      average character width in the current default font.
+      pixel on each side. 
     

 
 SCI_SETMARGINTYPEN(int margin, SC_MARGIN_SYMBOL | SC_MARGIN_NUMBER)
@@ -729,14 +719,14 @@ SCI_STOPRECORD
        Printing
     
 
-EM_FORMATRANGE
+SCI_FORMATRANGE
 SCI_SETPRINTMAGNIFICATION(int magnification)
 SCI_GETPRINTMAGNIFICATION
 SCI_SETPRINTCOLOURMODE(int mode)
 SCI_GETPRINTCOLOURMODE
 

     

-       On Windows EM_FORMATRANGE can be used to draw the text onto a display context which can
+       On Windows SCI_FORMATRANGE can be used to draw the text onto a display context which can
       include a printer display context.
     

     

@@ -749,6 +739,25 @@ SCI_GETPRINTCOLOURMODE
        white background. If intermediate tones are used on screen then black on white print can be 
        chosen with SCI_SETPRINTCOLOURMODE(SC_PRINT_BLACKONWHITE).
     

+    

+       Direct Access
+    

+
+SCI_GETDIRECTFUNCTION
+SCI_GETDIRECTPOINTER
+

+    

+      On Windows, the message passing scheme used to communicate between the container and
+      Scintilla is mediated by the operating system SendMessage function which can lead to bad 
+      performance when calling intensively. 
+      To avoid this overhead a pointer to a message handling function inside Scintilla
+      can be retrieved with SCI_GETDIRECTFUNCTION. The first argument to use when calling
+      the returned function is the value retrieved from SCI_GETDIRECTPOINTER. After that go 
+      the message number, wParam, and lParam.
+    

+    

+      This feature also works on GTK+ but has no significant impact on speed.
+    

     

        Multiple Views
     

@@ -902,7 +911,8 @@ SCI_SETKEYWORDS(int keywordset, char *keywordlist)
     

        Notifications are sent (fired) from the Scintilla control to its container when an event has
       occurred that may interest the container. Notifications are sent using the WM_NOTIFY message
-      with a structure containing information about the event.
+      on Windows and the "notify" signal on GTK+ with a structure containing information 
+      about the event.
     

 
 SCN_STYLENEEDED(int endstyleneeded)
@@ -968,7 +978,7 @@ SCN_KEY
     

 
 SCN_MODIFIED
-EN_CHANGE
+SCEN_CHANGE
 SCI_SETMODEVENTMASK(int eventmask)
 SCI_GETMODEVENTMASK
 

@@ -979,7 +989,8 @@ SCI_GETMODEVENTMASK
     

     

        EN_CHANGE is fired when the text of the document has been changed for any reason. This
-      notification is sent using the WM_COMMAND message as this is the behaviour of the standard
+      notification is sent using the WM_COMMAND message on Windows and the "Command" signal 
+      on GTK+ as this is the behaviour of the standard
       edit control.
     

     

@@ -1013,7 +1024,53 @@ SCN_NEEDSHOWN
       will just ensure each line in the range is visible by calling SCI_ENSUREVISIBLE.
     

     

-       Edit messages not supported by Scintilla
+       Edit messages currently supported by Scintilla which will be removed in the future.
+    

+
+WM_GETTEXT(int length, char *text)
+WM_SETTEXT(<unused>, char *text)
+EM_GETLINE(int line, char *text)
+EM_REPLACESEL(<unused>, char *text)
+EM_SETREADONLY
+EM_GETTEXTRANGE(<unused>, TEXTRANGE *tr)
+WM_CUT
+WM_COPY
+WM_PASTE
+WM_CLEAR
+WM_UNDO
+EM_CANUNDO
+EM_EMPTYUNDOBUFFER
+WM_GETTEXTLENGTH
+EM_GETFIRSTVISIBLELINE
+EM_GETLINECOUNT
+EM_GETMODIFY
+EM_SETMODIFY(bool ismodified)
+EM_GETRECT(RECT *rect)
+EM_GETSEL(int *start, int *end)
+EM_EXGETSEL(<unused>, CHARRANGE *cr)
+EM_SETSEL(int start, int end)
+EM_EXSETSEL(<unused>, CHARRANGE *cr)
+EM_GETSELTEXT(<unused>, char *text)
+EM_LINEFROMCHAR(int position)
+EM_EXLINEFROMCHAR(int position)
+EM_LINEINDEX(int line)
+EM_LINELENGTH(int position)
+EM_SCROLL(int line)
+EM_LINESCROLL(int column, int line)
+EM_SCROLLCARET()
+EM_CANPASTE
+EM_CHARFROMPOS(<unused>, POINT *location)
+EM_POSFROMCHAR(int position, POINT *location)
+EM_SELECTIONTYPE
+EM_HIDESELECTION(bool hide)
+EM_FINDTEXT(int flags, FINDTEXTEX *ft)
+EM_FINDTEXTEX(int flags, FINDTEXTEX *ft)
+EM_GETMARGINS 
+EM_SETMARGINS(EC_LEFTMARGIN or EC_RIGHTMARGIN or EC_USEFONTINFO, int val)
+EM_FORMATRANGE
+

+    

+       Edit messages never supported by Scintilla
     

 
 EM_GETWORDBREAKPROC EM_GETWORDBREAKPROCEX
-- 
cgit v1.2.3