MGCERichEdit - Windows CE Custom Control Objects
Written by Mark Gamber, September 1999

NS Basic is (c) NS Basic Corporation
Windows CE is (c) Microsoft Corporation

====================================================================================

MGCERichEdit provides a rich edit control to Windows CE applications capable of
making use of COM oriented controls such as NS Basic. Included in this package are:

MGCERichEdit object
Documentation and demonstration programs.

====================================================================================

Object Creation:
	AddObject "MGCERichEdit.RichEdit", "Name", x, y, xsize, ysize

====================================================================================

Properties:

*** BackColor
	Set and retrieve the RGB background color of the control. The default value
is the current system window color.

	cBack = REdit.BackColor
	REdit.BackColor = ( 256 * 255 ) + 255


*** Border
	Enable and disable a single-line border around the control. TRUE enables a
border, FALSE removes the border and the default value is TRUE.

	iHasBorder = REdit.Border
	REdit.Border = TRUE


*** Caption
	The Caption property is used to set and retrieve unformatted (plain) text to
and from the control.

	REdit.Caption = "Give the control some text"
	sText = REdit.Caption


*** FontBold
	Set and retrieve the default bold font setting for the control. TRUE enables
a bold font while FALSE enables a standard font.

	fType = REdit.FontBold
	REdit.FontBold = TRUE


*** FontItalic
	Set and retrieve the default italic font setting for the control. TRUE enables
an italic font, FALSE enables a standard font.

	fType = REdit.FontItalic
	REdit.FontItalic = TRUE


*** FontName
	The FontName property sets and retrieves the name of the control's default
font. The control default is "Arial".

	REdit.FontName = "Courier New"
	sFont = REdit.FontName


*** FontOffset
	This property sets and retrieves how far from the baseline text will be
displayed. This value is in Twips (1/1440 in.) and may be positive and negative. If
negative, text is displayed as subscript and a positive offset causes text to display
as superscript. The default value is zero.

	iOffset = REdit.FontOffset
	REdit.FontOffset = -30

*** FontSize
	Set and retrieve the default size of text displayed by the control. This value
is measured in Twips (1/1440 in).

	REdit.FontSize = 240
	fontSize = REdit.FontSize


*** FontStrikeout
	When TRUE, text is displayed with a line through the middle of a letter. FALSE
removes the strike-out appearance. The default value is FALSE.

	REdit.FontStrikeout = FALSE
	iStrike = REdit.FontStrikeout

*** FontUnderline
	Set this property to TRUE to underline text by default or FALSE to remove the
underline. The default value is FALSE.

	iUnderline = REdit.FontUnderline
	REdit.FontUnderline = TRUE

*** ForeColor
	Set and retrieve the default text color used by the control. The default value
is zero (black).

	cFont = REdit.ForeColor
	REdit.ForeColor = 128


*** LeftMargin
	Set and retrieve the left margin of the control in Twips (1/1440 in).

	iMargin = REdit.LeftMargin
	REdit.LeftMargin = 720     ' 1/2 inch

*** LineCount
	This read-only property retrieves the number of lines of text contained by the
control.

	iLines = REdit.LineCount


*** MaxLength
	Set and retrieve the maximum number of characters the control may hold. The default
value is 2137483646.

	REdit.MaxLength = 120
	iMaxCount = REdit.MaxLength


*** Modify
	Set, reset and retrieve the control's modify flag. When set (TRUE), the control's
contents have been modified since the property was last examined. FALSE indicates that the
contents have not changed.

	iCanSave = REdit.Modify
	REdit.Modify = FALSE


*** Multiline
	This property determines if the contro; is in single or multiple line mode. Set to
TRUE to enable multiple lines and FALSE for a single line control. NOTE: Because the control
needs to be destroyed and recreated when this property is changed, text formatting and other
style properties will be lost. Any text contained by the control at the time is retained.

	REdit.Multiline = TRUE
	iMLine = REdit.Multiline


*** ReadOnly
	Set to TRUE, the control is read-only and it's contents may not be modified by the
user. Set the property to FALSE to disable read-only mode.

	iNoModify = REdit.ReadOnly
	REdit.ReadOnly = TRUE


*** RightMargin
	Set and retrieve the right margin value, measured in Twips (1/1440 in).

	REdit.RightMargin = 260   ' 1/4 in
	iRightMargin = REdit.RightMargin


*** RTFText
	The RTFText property sets and retrieves RTF formatted text which includes the RTF
tags themselves. This is opposed to the Caption property which simply sets and gets plain
text.

	REdit.RTFText = "Could have tags here, but I don't know what they are."
	rtfText = REdit.RTFText


*** Scrollbars
	Set and retrieve the scrollbar types in use by the control. These are:
	0: None
	1: Vertical
	2: Horizontal
	3: Both
	The default value is zero.

	REdit.Scrollbars = 2
	iScroll = REdit.Scrollbars


*** SelectionDisplay
	When this property is TRUE, the control does not hide any selected text when it
loses focus. When set to FALSE, the default, the selection is hidden, not lost, when focus
is switched away from the control.

	iSelDisp = REdit.SelectionDisplay
	REdit.SelectionDisplay = TRUE


*** SelectionFontBold
	This property determines if the currently selected text is bold or normal. TRUE
indicates bold text and FALSE, the default, indicates standard text. If there is no selected
text at the time, this property determines how additional text will appear.

	REdit.SelectionFontBold = TRUE
	iType = REdit.SelectionFontBold


*** SelectionFontFlags
	This property is a combination of the SelectionFontBold, SelectionFontItalic,
SelectionFontUnderline and SelectionFontStrikeout properties and allows you to set and
retrieve the status of all four properties at one time, increasing performance. 
Individual items are set using a combination of the following values:
	1: Bold
	2: Italic
	4: Underline
	8: Strikeout
Bitwise operations may be carried out on the property to determine which properties
are set and which are not.

	iFlags = REdit.SelectionFontFlags
	REdit.SelectionFontFlags = 1 + 4   ' Bold & underlined


*** SelectionFontItalic
	This property determines if the currently selected text is italic or normal. TRUE
indicates italic text and FALSE, the default, indicates standard text. If there is no selected
text at the time, this property determines how additional text will appear.

	REdit.SelectionFontItalic = TRUE
	iType = REdit.SelectionFontItalic


*** SelectionFontName
	Set and retrieve the name of the font used with selected text. If there is no selected
text at the time, this property determines the font to use with inserted and appended text.
The default is "Arial".

	REdit.SelectionFontName = "Courier New"
	fName = REdit.SelectionFontName


*** SelectionFontOffset
	Measured in Twips (1/1440 in), this property determines how far above or below the
font baseline selected text will appear and may be positive for superscript text or
negative for subscript text. The default value is zero. If there is no selected text at the
time, the setting determines the appearance of inserted and appended text.

	iOffset = REdit.SelectionFontOffset
	REdit.SelectionFontOffset = 30


*** SelectionFontSize
	Set and retrieve the size, measured in Twips, of the font used in a text selection.
If there is no selection at the time, this determines the size of inserted and appended text.

	REdit.SelectionFontSize = 240
	iSize = REdit.SelectionFontSize


*** SelectionFontStrikeout
	When set to TRUE, selected text will appear as "struck out" with a line through
the middle of each character. FALSE removes the struck out appearance. If no text is
selected at the time, inserted and appended text takes on the property value.

	REdit.SelectionFontStrikeout = TRUE
	iLined = REdit.SelectionFontStrikeout


*** SelectionFontUnderline
	When set to TRUE, selected text is underlined and FALSE removes any underlines
from selected text. If nothing is selected at the time, inserted and appended text takes
on the appearance as set by this property.

	REdit.SelectionFontUnderline = TRUE
	iUnderlined = REdit.SelectionFontUnderline


*** SelectionFontColor
	Set and retrieve the RGB color value of currently selected text. If no text is
selected, inserted and appended text takes on this property value.

	REdit.SelectionFontColor = ( 128 * 65536 )
	selColor = REdit.SelectionFontColor


*** SelLength
	Use this property along with the SetStart property to set and get the length of
selected text. For example, if SetStart is 10 and SelLength is 5, then 5 characters will
be selected starting with character 11 (the first character is in position zero). Setting
SelLength to -1 and SetStart to zero selects all text in the control.

	REdit.SelLength = 10
	iSelLength = REdit.SelLength


*** SetStart
	This property determines the position of the first character of a text selection,
starting with character zero, and is used with SelLength to select text.

	REdit.SetStart = 0
	iSelStart = REdit.SetStart


*** Style
	The Style property determines how the control appears and uses the following values:
	0: No style
	1: Sunken appearance
	2: Raised appearance

	REdit.Style = 1
	iStyle = REdit.Style


*** Tabstop
	Set this property to TRUE (the default) to include the control in the tabstop order
of an application. FALSE removes the control from the tabstop order.

	REdit.Tabstop = FALSE
	iCanTab = REdit.Tabstop


*** Version
	A read-only property used to determine the current version of this control.

	iVer = REdit.Version
	
====================================================================================

Methods:

*** CharLine
	This method retrieves the line on which a specified character appears. The parameter
determines the zero based index of the character in question.

	iLine = REdit.CharLine( 145 )  ' What line is char 145 on?


*** Copy
	Causes the control to copy selected text to the clipboard.

	Redit.Copy


*** Cut
	Causes the control to remove selected text and place it in the clipboard.

	REdit.Cut


*** EmptyUndo
	Calling this method removes anything in the control's undo buffer. You cannot undo
any changes to control text after this method has been called.

	Redit.EmptyUndo


*** FindText
	Use FontText to locate text within the control. You may specify an optional starting
position, an optional length and search type. If any of these are specified, the search will
be contained to the selected range of characters and follow the specified search type. Possible
search types may be a combination of these values:
	1: Move down through the control
	2: Must match specified text entirely
	4: Case must match
The return value is the character position of found text. If no match was found, -1 is returned
by the control.

	iPos = FindText( 1, 0, 100, "Find This" )


*** GetTextRange
	Retrieve a selection of text from the control as determined by a start position and
length parameter.

	sText = REdit.GetTextRange( 100, 110 )


*** Hide
	Remove the control from the display.

	REdit.Hide


*** LineChar
	Retrieve the current position of the first character of a specified line.

	iCharPos = REdit.LineChar( 12 )


*** LineScroll
	Causes the control to scroll by a specified amount horizontally and vertically.

	REdit.LineScroll hAmt, vAmt


*** Load
	Load the contents of a file into the control. Because most applications read and write
single byte character files and single byte character strings are not easily dealt with by
Basic, this method will load a single byte character file and translate it into unicode which
is easily manipulated from within Basic. The return value is the number of bytes read by the
control, if any.

	REdit.Load "rtffile.txt"


*** Paste
	The contents of the clipboard, if any, will be pasted into the control at the current
insertion point upon calling this method.

	REdit.Paste


*** Redo
	The opposite of Undo, calling this method will put back any changes that were removed
by calling Undo.

	REdit.Redo


*** ReplaceSelection
	This method will replace selected text with a string passed through the method.

	REdit.ReplaceSelection "Replaced with this"


*** Save
	Save the contents of the control to a file by calling this method. The contents are
saved, including FTP formatting, as a single-byte character file. An optional second parameter
may be set to one to overwrite an existing file of the same name as that specified or zero,
the default, to throw an error if the file already exists. The return value is the number of
bytes that were saved, if any.

	iSaved = REdit.Save( "rtffile.rtf", 1 )    ' Overwrite if already there


*** SetFocus
	Call this method to set input focus to the control.

	REdit.SetFocus


*** Show
	Display the control if hidden.

	REdit.Show


*** Undo
	Call this method to undo any changes made to the control contents.

	REdit.Undo

====================================================================================

Events:

*** GotFocus
	This event is triggered when the control gets input focus.

	sub REdit_GotFocus
		Redit.BackColor = ( 255 * 65536 )+ ( 255 * 256 ) + 255
	end sub


*** LostFocus
	This event is trigged when the control loses input focus

	sub REdit_GotFocus
		Redit.BackColor = ( 128 * 65536 )+ ( 128 * 256 ) + 128
	end sub


*** SelectionChange
	This event is triggered when the current text selection is changed or the
caret is moved within the control's contained text. The parameters passed to this event
are the starting position or current caret position, starting with zero,  the length
of the selection and style flags used in the selection. If the event was fired because
the caret was moved and there is no selection, the length is zero. See SelectionFontFlags
for a description of the bit values used by the flags parameter.

	sub REdit_SelectionChange( startpos, sellength, flags )
		Label1.Caption = CStr( sellength ) & " characters are selected"
	end sub

====================================================================================
