jsRTB2 Usage - Updated August, 2012 - v. 1.12.829

---

Introduction Properties: RTBhWnd Enabled WordWrap CanUndo CanRedo HideSel BackColor FontColor FontName FontSize Text TextRTF (write only)

Properties: SelFont SelColor SelSize SelBold SelStart SelLength SelText LenText TopLine TotalLines BottomLine • HTML Properties: NoVScroll, NoHScroll

Methods: LoadFile(FilePath, AsRTF) SaveFile(FilePath, AsRTF) Cut Copy Paste LockRTB UnLockRTB Scroll(NumLines) SetFocus Undo ClearUndoBuffer SetUndoLimit Redo ClearAll SelAll SelNone HideSel

Methods: GetLineLength(Offset) GetLineIndex(LineNumber) GetCurLineNum() GetLineNumFromChar(Offset) GetLine(LineNumber) GetTrimLine(LineNumber) Find(Txt, StartPoint, EndPoint, Opts) FindBack(Txt, StartPoint, EndPoint, Opts) GetSelRange(StartPoint) SetSelRange(Start, Length) SetSelection(Start, End) GetTextRange(StartPoint, EndPoint) GetNextWord(StartPoint, StartWord) GetLastWord(StartPoint, StartWord)

Events: FileDrop(FilePath) KeyDown(Keycode, Shift) KeyPress(KeyAscii) KeyUp(Keycode, Shift) MouseDown(Button, PosX, PosY) MouseMove(PosX, PosY) MouseUp(Button, PosX, PosY) OnChange OnSelChange(StartPoint, SelType) Context Menu: Context Menu Update Notes License

Introduction

   jsRTB2.ocx is a RichEdit component for VBScript and browser use. Microsoft Windows, from Windows 95, has always included a pre-installed "RichEdit" library that provides the functionality to system RichEdit or "RichTextBox" (RTB) windows. An RTB window is used by Wordpad and many other text editors. A plain text window, such as the window in Notepad, does not provide formatting options. It has only one option for font name, size, etc. An RTB provides the ability to use colors, bold, different sizes, etc. An RTB actually contains RichText, a text-based form of encoding that specifies how the window should display the text content.

   Microsoft has an RTB ActiveX control but it requires a license and does not seem to work in a webpage context. jsRTB2 is nearly the same thing as the Microsoft control, but it does not require a license, is significantly more compact, offers more functionality, and is especially designed for use by script in a webpage. jsRTB2 is like embedding a Wordpad object in a webpage.

   jsRTB2.ocx can be used in compiled software, but is not optimized for that purpose. All property, method and event parameters have been structured as variants in order to accomodate VBScript. The data type conversion requirement will result in slightly slowed operation. It's not a concern in a script context but might be noticeable with intensive operations in compiled software where speed is important.

Requirements and Limitations:

   jsRTB2 uses v. 2 or 3 of the Windows RichEdit library. (The Microsoft control uses v. 1.) There should be no problem with missing files on any current system. Most people have had at least v. 3 installed since Windows 98.

Registering the Component:    jsRTB2 must be registered before use. Put a copy in the System folder and then drop it onto the RegSvr.vbs script to register. jsRTB2 is not "marked as safe", so it will show a security warning unless used in an HTA webpage.
   jsRTB2 cannot be made "safe for scripting" because it includes functions to read and write files on disk. However, if you are on a closed network or safe system, and you want to set jsRTB2 "safe for scripting" in order to bypass Internet Explorer warnings, create the following 2 Registry keys:

HKCR\CLSID\{6B237EFC-0B7C-11DB-B5C3-EA2610DB1053}\Implemented Categories\{7DD95802-9882-11CF-9FA9-00AA006C42C4}\
HHCR\CLSID\{6B237EFC-0B7C-11DB-B5C3-EA2610DB1053}\Implemented Categories\{7DD95801-9882-11CF-9FA9-00AA006C42C4}\

Properties

R: property can be read.    W: property can be written.    R/W: property is read/write.

NoVScroll and NoHScroll (W) - (HTML Properties)

NoVScroll and NoHScroll are properties that must be set in HTML because they specify properties set at creation time of the control. By default the RTB has both a vertical and horizontal scroll bar. Either or both scroll bars can be removed by using these properties in the HTML OBJECT tag. The following example will result in an RTB with a vertical scroll bar but no horizontal scroll bar.:

< OBJECT CLSID..............etc..... >
<PARAM NAME="NoHScroll" VALUE="True">
</OBJECT>

See the file "rtb ops demo.hta" for information and a demo of complications involved with using the scrollbar properties.

RTBhWnd (R)

Handle of RTB window.

Enabled (R/W)

Boolean.

WordWrap (W)

Boolean. Toggle wordwrap on or off.

BackColor (W)

Set back color. Must be 6-character hex code (RRGGBB format as in HTML).
Ex.: rtb.BackColor = "FFFFFF"

FontColor (W)

Set default text color. Must be 6-character hex code (RRGGBB format as in HTML).
Ex.: rtb.FontColor = "000000"

FontName (R/W)

Get or Set default font for RTB.
Ex.: rtb.FontName = "Verdana"
sFont = rtb.FontName

FontSize (W)

Set default font size for RTB.
Ex.: rtb.FontSize = 10

Text (R/W)

Get or set the text in RTB. Text is the text displayed in RTB, without the RichText encoding.
Ex.: rtb.Text = "blah blah"
s = rtb.Text

TextRTF (W)

Set text in RTB as RTF (rich text format). TextRTF includes the RichText encoding. The RTF encoding tells the RTB how to display the text, in terms of font, color, size, etc. RTF encoding is, itself, text-based, but it is not visible in the RTB window. So there are actually always 2 different text strings in an RTB: The basic text that you see, and that same text wrapped in its RTF encoding.

SelFont (W)

Set font for selected text only. Ex.: rtb.SelFont = "Verdana"

SelSize (W)

Set font size for selected text only. Ex.: rtb.SelSize = 10

SelColor (W)

Set color of selected text only. Must be 6-character hex code. Ex.: rtb.SelColor = "FF0000"

SelBold (W)

Boolean. Toggle Bold property for selected text only. Ex.: rtb.SelBold = True

SelStart (R/W)

Get or set offset of input prompt. Note that text offset in RTB begins at 0, not 1.
Ex.: rtb.SelStart = 0 '-- Sets input at beginning of file.
x = rtb.SelStart

SelLength (R/W)

Get or set current length of selection.
Ex.: rtb.SelLength = 100 '-- extends selection 100 characters, beginning at SelStart.
Num = rtb.SelLength '-- returns current length of selection.

SelText (R/W)

Return current selected text or replace current selection with new text.
Ex.: rtb.SelText = "blah" '-- replaces selection with "blah". If there is no current selection, "blah" is inserted at SelStart.
s = rtb.SelText '-- returns currently selected text as string variant.

LenText (R)

Returns length of text in RTB.
Ex.: LenT = rtb.LenText

TopLine (R/W)

Get or set top line number displayed in RTB window. (Line numbers begin at 0.)
Ex.: rtb.TopLine = 0 '-- scroll to top.
num = rtb.TopLine '-- returns top line currently visible.

TotalLines (R)

Returns total number of lines in RTB.

BottomLine (R)

Returns number of bottom line displayed in RTB window. (Line numbers begin at 0.)

CanUndo (R)

Boolean. Returns whether an undo operation is currently possible.

CanUndo (R)

Boolean. Returns whether an undo operation can be reversed.

Methods

Sub Cut()

Removes selected text and puts it on Clipboard.

Sub Copy()

Copies selected text to Clipboard.

Sub Paste()

Pastes any text content in Clipboard into RTB.

Sub LockRTB()

Locks display. For use when carrying out numerous operations in RTB. LockRTB will not only stop graphical updating but also speeds up operations by waiting until operations are finished to update display. For example, if you want to render every instance of the word "house" as bold in a large file, you can do it by using a loop with Find:
Dim Pt1, Pt2, LenT
  Pt1 = 0
  LenT = rtb.LenText
  rtb.LockRTB
  Do
   Pt2 = rtb.Find("house", Pt1, LenT, 1)
    If Pt2 = -1 Then Exit Do
   rtb.SelStart = Pt2
   rtb.SelLength = 5
   rtb.SelBold = True
   Pt1 = Pt2 + 5
    If Pt1 >= LenT Then Exit Do
  Loop
  rtb.UnLockRTB

By using LockRTB before the loop, updating of the RTB is blocked. The result is more attractive and faster. If LockRTB were not used the RTB window would be seen scrolling itself wildly as each instance of the word "house" was set to bold.

Sub UnLockRTB()

Unlocks display.

Sub Undo()

Undo last change to RTB if possible. Undo is built into the system RichEdit library. The ability to undo is determined by the library itself. It can be checked at a given time via the Boolean CanUndo property.

Sub ClearUndoBuffer()

Empties Undo buffer and resets CanUndo flag.

Sub SetUndoLimit(LimitNumber)

Sets the Undo limit. The default is 100. If memory is an issue it can be set lower. Setting it to 0 will disable Undo.

Sub Redo()

Reverse an Undo operation.

Sub ClearAll()

Clears RTB text.

Sub SelAll()

Selects all text.

Sub SelNone()

Removes selection. (Sets selection to zero-length but does not affect text.)

Sub HideSel(IfHide)

Boolean. Whether to hide selection when RTB loses focus.

Function GetLineLength(Offset)

Returns length of line (in characters) for line containing character at offset Offset.
Ex.: n = RTB.GetLineLength(0) will return length of first line in RTB.

Function GetLineIndex(LineNumber)

Returns offset of 1st character in line # LineNumber. Offset of text in RTB begins at 0.

Function GetCurLineNum()

Returns line number of line where cursor is positioned.

Function GetLineNumFromChar(Offset)

Returns line number containing specified offset. Line numbers begin at 0.

Function Find(Txt, StartPoint, EndPoint, Opts)

Find specific text in RTB. Txt is text to find. StartPoint is offset to begin search. Use 0 to start at beginning of text. EndPoint is end point of search. Use -1 to search to end.

Opts is optional parameters:
default(match any occurence of string, regardless of case): 1
match whole-word only: 3
case must match: 5
match both whole word and case: 7

Returns offset of found text or -1 if not found.

Function FindBack(Txt, StartPoint, EndPoint, Opts)

Same as Find, but searches backward. StartPoint and EndPoint are still beginning and end points in text, in relation to the beginning of text. They are not reversed. In other words, If StartPoint is 10 and EndPoint is 100, Find will find the first instance from offset 10 to 100, while FindBack will find the last instance from offset 10 to 100. Do not use: FindBack("blah", 100, 10, 1). Use FindBack("blah", 10, 100, 1). Use -1 to start search at end. As with Find, to search the whole range use FindBack("blah", 0, -1, 1)

Function GetSelRange(StartPoint)

Returns selection information. StartPoint returns the offset of the beginning of the selection. Function return is length of the selection.
Ex.: LenSel = RTB.GetSelRange(PtSt)

Sub SetSelRange(StartPoint, Length)

Sets the selection, beginning at StartPoint and extending Length number of characters.

Sub SetSelection(StartPoint, EndPoint)

Sets the selection, beginning at StartPoint and extending to EndPoint. Note that this is not quite the same thing as SetSelRange. If the start point is 200 and the end point is 300, that will be a selection of 101 characters because the selection is inclusive of start and end points. To do the same thing with SetSelRange would require parameters of 200, 101.

Function GetTextRange(StartPoint, EndPoint)

Returns text from offset StartPoint to offset EndPoint.
Ex.: s = RTB.GetTextRange(0, 99) will return the first 100 characters.

Function GetNextWord(StartPoint, StartWord)

Returns text of next whole word from StartPoint offset. StartWord returns the offset of the first character of the next word. (Note: See update notes below for important information about this function.)

Function GetLine(LineNumber)

Returns text of line, given line number.
Ex.: s = RTB.GetLine(30)

Function GetTrimLine(LineNumber)

Returns text of line, given line number. This is the same as GetLine but with an added function: the line is returned trimmed of bracketing spaces, vbCr and vbLf. GetTrimLine is just an easy way to make sure you're getting only the actual text of the line.

Function GetLastWord(StartPoint, StartWord)

Returns last complete word before StartPoint offset. StartWord returns offset of beginning of last word. In the case of GetLastWord, if StartPoint is within a word, that word will be returned. (In other words, this function might be thought of as "Get current word or last word". Whereas GetNextWord returns the next full word after the given offset.) (Note: See update notes below for important information about this function.)

Sub LoadFile(FilePath, AsRTF)

Loads a file into RTB. FilePath is full path. AsRTF is true to load as RTF text, false to load as plain text. (Only a valid RTF file should be loaded as RTF text.) If the file does not exist the method fails without error. The file is not created.

Sub SaveFile(FilePath, AsRTF)

Save text of RTB to file. FilePath is full path of file to save. AsRTF is true to save RTF text, false to save plain text (as it shows in RTB). If the file already exists it will be overwritten.

Sub Scroll(NumLines)

Scroll the RTB window NumLines number of lines. (May be positive or negative.)
Ex.: rtb.Scroll -5 '-- scrolls up 5 lines.

Sub SetFocus()

Events

MouseMove(PosX, PosY)

Occurs when mouse moves over RTB.

OnChange()

Occurs when a change occurs in RTB. Use of this event should be avoided in most cases because it will noticeably slow down operations in the RTB. The reason for that is because if you write an RTB_OnChange() sub it will be called every time a letter is typed.

OnSelChange(StartPoint, SelType)

Returns information about the current selection when selection changes. StartPoint is the offset of beginning of selection. SelType returns one or more numeric values indicating the type of selection. Possible values:
0- no selection 1- Text 2- At least one OLE object 4- More than one character of text 8- More than one OLE object

Ex.: If SelType And 1 = 1 then '-- there is a text selection.

This event can also be used as a "SelStart Change" event. Whenever SelStart changes this event will occur, providing the new SelStart offset in the first parameter. If the SelType parameter is 0 it indicates the cursor has moved. If it is 1 there is a 1-character selection. If it is 5 (4 + 1) that indicates there is a text selection of more than one character.

FileDrop(FilePath)

FilePath returns the full path of dropped file. Using this event allows you to load dropped files into the RTB by using something like:
RTB.LoadFile FilePath, False
in the FileDrop event sub.

KeyDown(Keycode, Shift)

KeyCode is keyboard code. Shift: Shift is the status of Shift and Control keys: Shift-1. Control-2. If both Shift and Control are depressed, Shift will return 3.

KeyPress(KeyAscii)

KeyAscii is ASCII character code.

KeyUp(Keycode, Shift)

KeyCode is keyboard code. Unlike KeyAscii, there is a KeyCode for all keys. Shift: Shift is the status of Shift and Control keys: Shift-1. Control-2. If both Shift and Control are depressed, Shift will return 3.

MouseDown(Button, PosX, PosY)

Button: Left-1. Right-2. Middle-4.
PosX and PosY return the mouse coordinates at time of click.

MouseUp(Button, PosX, PosY)

Button: Left-1. Right-2. Middle-4.
PosX and PosY return the mouse coordinates at time of click.

Context Menu

Context Menu

The RTB has a built-in context menu that appears at MouseUp when the right mouse button is clicked. The menu includes: Undo, Cut, Copy, Paste and Select All. There are no specific operations for the context menu. It is integral to the RTB. However, the menu can be blocked by setting MenuVisible = False.

MenuVisible (W)

Sets whether context menu is operational. By default the menu pops up on right mouse click. Setting MenuVisible to False will prevent the menu from showing.

Update Notes

Current version: 1.12.829

   jsRTB2 is an extensive rebuild of jsRTB. It is a new component with a separate registration. That's why it's version 1 rather than jsRTB v. 2.

• Bugfix: jsRTB was unable to offer a Tab character due to conflicts with Internet Explorer. That is fixed.

• DEP safe. DEP (Data Execution Prevention) was introduced, and then enforced, in later versions of Windows. It is aimed at reducing risks from malware by restricting how executable code can run. jsRTB was not DEP-safe. jsRTB2 is DEP-safe.

• A handful of new methods and events have been added: EmptyUndoBuffer, Redo, CanRedo, GetCurLineNum, GetSelRange, SetSelRange, SetSelection and OnSelChange.

• Bugfix: GetLastWord and GetNextWord did not work properly in jsRTB. That functionality has been improved. But it can never be perfect. The functions return strings based on system-defined delimiters, which may sometimes act unexpectedly. For example, if the next word is "add-on" then "add" may be returned. Yet if the next word is "apple" followed by a comma, the comma may be included in the returned string. Also, when the cursor is in the middle of a word, GetLastWord will return that word, while GetNextWord will return the next word. These functions are meant for special-purpose use. For instance, GetLastWord will act dependably if one is trying to provide spellcheck by checking the last word every time a space is entered. But in less defined usage it will require more careful handling.

• Compatible with Vista/7/8. jsRTB supported up to Windows XP. jsRTB2 supports up to Windows 8. It has been tested on Windows 7, running an HTA in IE8.

License:

   You use all script code and components from JSWare at your own risk.

   The components (compiled DLL and EXE files) may be used for personal or commercial purposes. No payment or attribution is required for either use. The components may be redistributed if they are required as support files for scripts or software that you have written.
   Also, the script code may be used freely, in part or as whole scripts, for any purpose, personal or commercial, without payment or attribution.

   I ask only that you not redistribute these scripts and components, except as required for your direct use. Instead, please direct others to obtain copies of JSWare scripts and components directly from www.jsware.net.

   Also, none of the code here may be redistributed under another license. If a work using code from JSWare is distributed with restrictions of any kind the code from JSWare must be kept exempt from those restrictions. This includes, but is not limited to, code sold for profit, code with usage restrictions and code distributed as so-called "Open Source" with redistribution restrictions.

    Joe Priestley

jsRTB2.ocx  •  JSWare  •  www.jsware.net  •  jsware@jsware.net