From 2b7d0f1089c7517dc02972cb6dfdb6b2623c9985 Mon Sep 17 00:00:00 2001 From: Neil Date: Tue, 18 Jun 2019 11:51:08 +1000 Subject: Feature [feature-requests:#1297] 3: Use pointer type in documentation. --- doc/ScintillaDoc.html | 59 ++++++++++++++++++++++++++++----------------------- 1 file changed, 32 insertions(+), 27 deletions(-) (limited to 'doc') diff --git a/doc/ScintillaDoc.html b/doc/ScintillaDoc.html index fc7ebe424..9d7dce4b1 100644 --- a/doc/ScintillaDoc.html +++ b/doc/ScintillaDoc.html @@ -227,6 +227,14 @@ not: to generically handle both types, allocate one more byte than indicated and set it to NUL. + + pointer + + A memory address. + In some cases this is a pointer to a sequence of char inside Scintilla that will only be available for a limited period. + Equivalent to void *. + + colour @@ -5721,10 +5729,10 @@ struct Sci_RangeToFormat { between words.

Direct access

- SCI_GETDIRECTFUNCTION → int
- SCI_GETDIRECTPOINTER → int
- SCI_GETCHARACTERPOINTER → int
- SCI_GETRANGEPOINTER(position start, position lengthRange) → int
+ SCI_GETDIRECTFUNCTION → pointer
+ SCI_GETDIRECTPOINTER → pointer
+ SCI_GETCHARACTERPOINTER → pointer
+ SCI_GETRANGEPOINTER(position start, position lengthRange) → pointer
SCI_GETGAPPOSITION → position
 @@ -5760,18 +5768,18 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ SCI_GETDIRECTFUNCTION and the need to call Scintilla indirectly via the function pointer.

-

SCI_GETDIRECTFUNCTION → int
+

SCI_GETDIRECTFUNCTION → pointer
This message returns the address of the function to call to handle Scintilla messages without the overhead of passing through the Windows messaging system. You need only call this once, regardless of the number of Scintilla windows you create.

-

SCI_GETDIRECTPOINTER → int
+

SCI_GETDIRECTPOINTER → pointer
This returns a pointer to data that identifies which Scintilla window is in use. You must call this once for each Scintilla window you create. When you call the direct function, you must pass in the direct pointer associated with the target window.

-

SCI_GETCHARACTERPOINTER → int
- SCI_GETRANGEPOINTER(position start, position lengthRange) → int
+

SCI_GETCHARACTERPOINTER → pointer
+ SCI_GETRANGEPOINTER(position start, position lengthRange) → pointer
SCI_GETGAPPOSITION → position
Grant temporary direct read-only access to the memory used by Scintilla to store the document.

@@ -5813,26 +5821,23 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ documents in a single Scintilla window and so you can display a single document in multiple windows (for use with splitter windows).

-

Although these messages use document *doc, to ensure compatibility with future - releases of Scintilla you should treat doc as an opaque void*. That +

These messages use pointer returns and arguments to refer to documents. + They point to internal objects inside Scintilla and should be treated as an opaque void*. That is, you can use and store the pointer as described in this section but you should not dereference it.

- SCI_GETDOCPOINTER → document *
- SCI_SETDOCPOINTER(<unused>, document - *doc)
- SCI_CREATEDOCUMENT(position bytes, int documentOptions) → document *
- SCI_ADDREFDOCUMENT(<unused>, document - *doc)
- SCI_RELEASEDOCUMENT(<unused>, document - *doc)
+ SCI_GETDOCPOINTER → pointer
+ SCI_SETDOCPOINTER(<unused>, pointer doc)
+ SCI_CREATEDOCUMENT(position bytes, int documentOptions) → pointer
+ SCI_ADDREFDOCUMENT(<unused>, pointer doc)
+ SCI_RELEASEDOCUMENT(<unused>, pointer doc)
SCI_GETDOCUMENTOPTIONS → int
 -

SCI_GETDOCPOINTER → document *
+

SCI_GETDOCPOINTER → pointer
This returns a pointer to the document currently in use by the window. It has no other effect.

-

SCI_SETDOCPOINTER(<unused>, document *doc)
+

SCI_SETDOCPOINTER(<unused>, pointer doc)
This message does the following:
1. It removes the current window from the list held by the current document.
2. It reduces the reference count of the current document by 1.
@@ -5842,7 +5847,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ window.
6. If doc was not 0, its reference count is increased by 1.

-

SCI_CREATEDOCUMENT(position bytes, int documentOptions) → document *
+

SCI_CREATEDOCUMENT(position bytes, int documentOptions) → pointer
This message creates a new, empty document and returns a pointer to it. This document is not selected into the editor and starts with a reference count of 1. This means that you have ownership of it and must either reduce its reference count by 1 after using @@ -5909,7 +5914,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ -

SCI_ADDREFDOCUMENT(<unused>, document *doc)
+

SCI_ADDREFDOCUMENT(<unused>, pointer doc)
This increases the reference count of a document by 1. If you want to replace the current document in the Scintilla window and take ownership of the current document, for example if you are editing many documents in one window, do the following:
@@ -5919,7 +5924,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ 3. Use SCI_SETDOCPOINTER(0, docNew) to set a different document or SCI_SETDOCPOINTER(0, 0) to set a new, empty document.

-

SCI_RELEASEDOCUMENT(<unused>, document *doc)
+

SCI_RELEASEDOCUMENT(<unused>, pointer doc)
This message reduces the reference count of the document identified by doc. doc must be the result of SCI_GETDOCPOINTER or SCI_CREATEDOCUMENT and must point at a document that still exists. If you call this on a document with a reference @@ -5937,7 +5942,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){

Loading in the background

- SCI_CREATELOADER(position bytes, int documentOptions) → int
+ SCI_CREATELOADER(position bytes, int documentOptions) → pointer

An application can load all of a file into a buffer it allocates on a background thread and then add the data in that buffer @@ -5946,7 +5951,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){

To avoid these issues, a loader object may be created and used to load the file. The loader object supports the ILoader interface.

-

SCI_CREATELOADER(position bytes, int documentOptions) → int
+

SCI_CREATELOADER(position bytes, int documentOptions) → pointer
Create an object that supports the ILoader interface which can be used to load data and then be turned into a Scintilla document object for attachment to a view object. The bytes argument determines the initial memory allocation for the document as it is more efficient @@ -6836,7 +6841,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ SCI_GETSTYLEFROMSUBSTYLE(int subStyle) → int
SCI_GETPRIMARYSTYLEFROMSTYLE(int style) → int
SCI_SETIDENTIFIERS(int style, const char *identifiers)
- SCI_PRIVATELEXERCALL(int operation, int pointer) → int
+ SCI_PRIVATELEXERCALL(int operation, pointer pointer) → pointer
SCI_GETNAMEDSTYLES → int
SCI_NAMEOFSTYLE(int style, char *name) → int
SCI_TAGSOFSTYLE(int style, char *tags) → int
@@ -7015,7 +7020,7 @@ sptr_t CallScintilla(unsigned int iMessage, uptr_t wParam, sptr_t lParam){ Similar to SCI_SETKEYWORDS but for substyles. The prefix feature available with SCI_SETKEYWORDS is not implemented for SCI_SETIDENTIFIERS.

-

SCI_PRIVATELEXERCALL(int operation, int pointer) → int
+

SCI_PRIVATELEXERCALL(int operation, pointer pointer) → pointer
Call into a lexer in a way not understood by Scintilla.

Style Metadata

-- cgit v1.2.3