From 475450c76ceef43a7f5b2c68ed5848baee96b6dc Mon Sep 17 00:00:00 2001 From: Neil Date: Tue, 17 May 2022 08:52:34 +1000 Subject: Duplicate APIs to support 64-bit document positions on Win32: SCI_GETTEXTRANGEFULL, SCI_FINDTEXTFULL, and SCI_FORMATRANGEFULL. --- doc/ScintillaDoc.html | 63 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 55 insertions(+), 8 deletions(-) (limited to 'doc/ScintillaDoc.html') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index 782f299eb..ea85686aa 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -129,7 +129,7 @@

Scintilla Documentation

-

Last edited 9 March 2022 NH

+

Last edited 15 May 2022 NH

Scintilla 5 has moved the lexers from Scintilla into a new Lexilla project.
@@ -531,6 +531,7 @@ SCI_SETREADONLY(bool readOnly)
SCI_GETREADONLY → bool
SCI_GETTEXTRANGE(<unused>, Sci_TextRange *tr) → position
+ SCI_GETTEXTRANGEFULL(<unused>, Sci_TextRangeFull *tr) → position
SCI_ALLOCATE(position bytes)
SCI_ALLOCATELINES(line lines)
SCI_ADDTEXT(position length, const char *text)
@@ -614,13 +615,17 @@ only, attempts to modify the text cause the SCN_MODIFYATTEMPTRO notification.

-

SCI_GETTEXTRANGE(<unused>, Sci_TextRange *tr) → position
+

+ SCI_GETTEXTRANGE(<unused>, Sci_TextRange *tr) → position
+ SCI_GETTEXTRANGEFULL(<unused>, Sci_TextRangeFull *tr) → position
This collects the text between the positions cpMin and cpMax and copies it to lpstrText (see struct Sci_TextRange in Scintilla.h). If cpMax is -1, text is returned to the end of the document. The text is 0 terminated, so you must supply a buffer that is at least 1 character longer than the number of characters you wish to read. The return value is the length of the returned text not including the terminating 0.

+

SCI_GETTEXTRANGEFULL uses 64-bit positions on all platforms so is safe for documents larger than 2GB. + It should always be used in preference to SCI_GETTEXTRANGE which will be deprecated in a future release.

See also: SCI_GETSELTEXT, SCI_GETLINE, @@ -721,8 +726,9 @@ These structures are defined to be exactly the same shape as the Win32 TEXTRANGE and CHARRANGE, so that older code that treats Scintilla as a RichEdit will work.

-

In a future release the type Sci_PositionCR will be redefined to be 64-bits when Scintilla is - built for 64-bits on all platforms.

+

In a future release, these types will be deprecated. + SCI_GETTEXTRANGEFULL, Sci_TextRangeFull + and Sci_CharacterRangeFull should be used instead.

 typedef long Sci_PositionCR;
 
@@ -735,6 +741,23 @@ struct Sci_TextRange {
     struct Sci_CharacterRange chrg;
     char *lpstrText;
 };
+
+ +

Sci_TextRangeFull and Sci_CharacterRangeFull
+ These structures are the same as Sci_TextRange and Sci_CharacterRange except that positions are + always 64-bit in 64-bit builds so will work on documents larger than 2GB.

+
+typedef ptrdiff_t Sci_Position;
+
+struct Sci_CharacterRangeFull {
+	Sci_Position cpMin;
+	Sci_Position cpMax;
+};
+
+struct Sci_TextRangeFull {
+	struct Sci_CharacterRangeFull chrg;
+	char *lpstrText;
+};

Specific to GTK, Cocoa and Windows only: Access to encoded text

@@ -1033,13 +1056,15 @@ struct Sci_TextRange { See the documentation of your C++ runtime for details on what is supported.

SCI_FINDTEXT(int searchFlags, Sci_TextToFind *ft) → position
+ SCI_FINDTEXTFULL(int searchFlags, Sci_TextToFindFull *ft) → position
SCI_SEARCHANCHOR
SCI_SEARCHNEXT(int searchFlags, const char *text) → position
SCI_SEARCHPREV(int searchFlags, const char *text) → position

SCI_FINDTEXT(int searchFlags, Sci_TextToFind *ft) → position
- This message searches for text in the document. It does not use or move the current selection. + SCI_FINDTEXTFULL(int searchFlags, Sci_TextToFindFull *ft) → position
+ These messages search for text in the document. They do not use or move the current selection. The searchFlags argument controls the search type, which includes regular expression searches.

@@ -1047,13 +1072,14 @@ struct Sci_TextRange { search backwards to find the previous occurrence of a search string by setting the end of the search range before the start.

-

The Sci_TextToFind structure is defined in Scintilla.h; set +

The Sci_TextToFind and Sci_TextToFindFull structures are defined in Scintilla.h; set chrg.cpMin and chrg.cpMax with the range of positions in the document to search. You can search backwards by setting chrg.cpMax less than chrg.cpMin. Set the lpstrText member of Sci_TextToFind to point at a zero terminated text string holding the search pattern. If your language makes the use of Sci_TextToFind - difficult, you should consider using SCI_SEARCHINTARGET instead.

+ difficult, you should consider using SCI_SEARCHINTARGET instead. + On 64-bit Win32, SCI_FINDTEXT is limited to the first 2G of text and SCI_FINDTEXTFULL removes this limitation.

The return value is -1 if the search fails or the position of the start of the found text if it succeeds. The chrgText.cpMin and chrgText.cpMax members of @@ -1071,6 +1097,16 @@ struct Sci_TextToFind { const char *lpstrText; // the search pattern (zero terminated) struct Sci_CharacterRange chrgText; // returned as position of matching text }; + + +

Sci_TextToFindFull
+ This structure extends Sci_TextToFind to support huge documents on Win32.

+
+struct Sci_TextToFindFull {
+    struct Sci_CharacterRangeFull chrg;     // range to search
+    const char *lpstrText;                // the search pattern (zero terminated)
+    struct Sci_CharacterRangeFull chrgText; // returned as position of matching text
+};

SCI_SEARCHANCHOR
@@ -6633,6 +6669,7 @@ struct Sci_TextToFind { and on Cocoa CGContextRef is used.

SCI_FORMATRANGE(bool draw, Sci_RangeToFormat *fr) → position
+ SCI_FORMATRANGEFULL(bool draw, Sci_RangeToFormatFull *fr) → position
SCI_SETPRINTMAGNIFICATION(int magnification)
SCI_GETPRINTMAGNIFICATION → int
@@ -6643,6 +6680,7 @@ struct Sci_TextToFind {

SCI_FORMATRANGE(bool draw, Sci_RangeToFormat *fr) → position
+ SCI_FORMATRANGEFULL(bool draw, Sci_RangeToFormatFull *fr) → position
This call renders a range of text into a device context. If you use this for printing, you will probably want to arrange a page header and footer; Scintilla does not do this for you. See SciTEWin::Print() in SciTEWinDlg.cxx for an @@ -6651,7 +6689,8 @@ struct Sci_TextToFind {

draw controls if any output is done. Set this to false if you are paginating (for example, if you use this with MFC you will need to paginate in - OnBeginPrinting() before you output each page.

+ OnBeginPrinting() before you output each page. + On 64-bit Win32, SCI_FORMATRANGE is limited to the first 2G of text and SCI_FORMATRANGEFULL removes this limitation.

 struct Sci_Rectangle { int left; int top; int right; int bottom; };
 
@@ -6662,6 +6701,14 @@ struct Sci_RangeToFormat {
     Sci_Rectangle rcPage;     // Physically printable page size
     Sci_CharacterRange chrg;  // Range of characters to print
 };
+
+struct Sci_RangeToFormatFull {
+    Sci_SurfaceID hdc;        // The Surface ID we print to
+    Sci_SurfaceID hdcTarget;  // The Surface ID we use for measuring (may be same as hdc)
+    Sci_Rectangle rc;         // Rectangle in which to print
+    Sci_Rectangle rcPage;     // Physically printable page size
+    Sci_CharacterRangeFull chrg;  // Range of characters to print
+};

On Windows, hdc and hdcTarget should both be set to the device context handle -- cgit v1.2.3