Date: 02-16-2022
Return to Index
created by gbSnippets
'Working with strings in PowerBASIC often involves variable or fixed length
'strings which are not zero-terminated (last character is not Chr$(0) or $Nul).
'But when working with Scintilla messages strings are almost always terminated
'with $Nul. The $Nul character is typically used to indicated the end of a
'string.
'In the few cases where a non-zero-terminated String is used, the message
'will have a "length" argument which will specify the length of the string.
'For example, this message requires a zero-terminated string:
SendMessage %Sci_SetText, 0, StrPTR(txt)
'And this one does not:
SendMessage %Sci_AppendText, iLength, StrPTR(txt)
'In all messages, a pointer to the string is passed as an argument to the
'message.
'In the case where you are sending a string to Scintilla, and the string
'is not zero-terminated, you must pass a value specifying how many character
'are in the string.
'In the case where you are receiving a string from Scintilla, one of these
'will be true, depending on the message used:
'1. Pass Scintilla an argument specifiying how many characters to return
'2. Pass a buffer whose length matches the number of characters Scintilla will return
'More often than not, option #2 is used, where you must set the buffer to
'the length of the string that Scintilla will return. In such cases, Scintilla
'will tell you how wide to make the string by returning the width when the
'message is passed to Scintilla with a nul pointer.
'For example, the first message below passes a null pointer (0), telling Scintilla
'to return the length of the string it will return (including the $nul character)
'if the same message is sent with a valid string pointer. The second message uses
'that value to set the length of the string buffer in which Scintilla will place
'the returned string.
iLen = SendMessage( hSci, %SCI_GetSelText, 0, 0) 'get required buffer length
txt = String(iLen-1," ") + Chr$(0) 'size the buffer
SendMessage hSci, %SCI_GetSelText, 0, StrPTR(txt) 'get the text
'Of the almost 500 Scintilla messages, here are the ~50 messages which send or
'receive text.
'Send Text
'These messages pass text to Scintilla. If the non-text argument is "length",
'then Scintilla returns that many character and the passed string does not
'need a $nul character at the end. If the non-text argument is not "length",
'then the passed string must be zero-terminated.
===================================================
SCI_ADDSTYLEDTEXT(Int length, cell *s) 'length
SCI_ADDTEXT(Int length, const char *s) 'length
SCI_ANNOTATIONSETSTYLES(Int Line, char *styles)
SCI_ANNOTATIONSETTEXT(Int Line, char *Text)
SCI_APPENDTEXT(Int length, const char *s) 'length
SCI_AUTOCSELECT(<unused>, const char *Select)
SCI_AUTOCSHOW(Int lenEntered, const char *list)
SCI_AUTOCSTOPS(<unused>, const char *chars)
SCI_CALLTIPSHOW(Int posStart, const char *definition)
SCI_COPYTEXT(Int length, const char *Text) 'length
SCI_FINDTEXT(Int flags, Sci_TextToFind *ttf)
SCI_GETPROPERTYEXPANDED(const char *key, char *value)
SCI_GETPROPERTYINT(const char *key, Int Default)
SCI_INSERTTEXT(Int Pos, const char *Text)
SCI_LOADLEXERLIBRARY(<unused>, const char *path)
SCI_MARGINSETSTYLES(Int Line, char *styles)
SCI_MARGINSETTEXT(Int Line, char *Text)
SCI_MARKERDEFINEPIXMAP(Int markerNumber, const char *xpm)
SCI_REGISTERIMAGE(Int Type, const char *xpmData)
SCI_REPLACESEL(<unused>, const char *Text)
SCI_REPLACETARGET(Int length, const char *Text) 'length (can be either, see Help)
SCI_REPLACETARGETRE(Int length, const char *Text) 'length (can be either, see Help)
SCI_SEARCHINTARGET(Int length, const char *Text) 'length
SCI_SEARCHNEXT(Int searchFlags, const char *Text)
SCI_SEARCHPREV(Int searchFlags, const char *Text)
SCI_SETKEYWORDS(Int keyWordSet, const char *keyWordList)
SCI_SETLEXERLANGUAGE(<unused>, const char *Name)
SCI_SETPROPERTY(const char *key, const char *value)
SCI_SETTEXT(<unused>, const char *Text)
SCI_SETWHITESPACECHARS(<unused>, const char *chars)
SCI_SETWORDCHARS(<unused>, const char *chars)
SCI_STYLESETFONT(Int styleNumber, const char *fontName)
SCI_TEXTWIDTH(Int styleNumber, const char *Text)
SCI_USERLISTSHOW(Int listType, const char *list)
'Return Text
'These messages receive text from Scintilla. The passed string must be
'zero-terminated and must be long enough to handle the returned number
'of characters (one exception - Sci_GetLine returned string does not include null)
==================================================
SCI_ANNOTATIONGETSTYLES(Int Line, char *styles)
SCI_ANNOTATIONGETTEXT(Int Line, char *Text)
SCI_AUTOCGETCURRENTTEXT(<unused>, char *Text
SCI_ENCODEDFROMUTF8(const char *utf8, char *encoded)
SCI_GETCURLINE(Int textLen, char *Text)
SCI_GETLEXERLANGUAGE(<unused>, char *Name)
SCI_GETLINE(Int Line, char *Text) 'returned string does not include null
SCI_GETPROPERTY(const char *key, char *value)
SCI_GETPROPERTYEXPANDED(const char *key, char *value)
SCI_GETSELTEXT(<unused>, char *Text)
SCI_GETSTYLEDTEXT(<unused>, Sci_TextRange *tr)
SCI_GETTAG(Int tagNumber, char *tagValue)
SCI_GETTEXT(Int length, char *Text)
SCI_GETTEXTRANGE(<unused>, Sci_TextRange *tr)
SCI_MARGINGETSTYLES(Int Line, char *styles)
SCI_MARGINGETTEXT(Int Line, char *Text)
SCI_STYLEGETFONT(Int styleNumber, char *fontName)
SCI_TARGETASUTF8(<unused>, char *s)
'PowerBASIC allows you to handle zero-terminated strings in two ways:
'The first is to use a dynamic string and simply add a $nul to the
'string before passing it to Scintilla.
Local txt As String
txt = "my text" + $nul
'If you use this approach, the string is passed like this:
StrPTR(txt)
'The second approach is to use a PowerBASIC AsciiZ string, which handles
'inclusion of the terminating $nul for you
Local txt As AsciiZ * 50
txtZ = "my text"
'If you use this approach, the string is passed like this:
VarPTR(txtZ)
'gbs_00678
'Date: 03-10-2012
http://www.garybeene.com/sw/gbsnippets.htm