FCCtrlTextEditor Class Reference

UI class that handles a multiline edit control for viewing or modifying text (optionally formatted with font information). It has a vertical scroll bar when needed and captures the Enter and Tab keys when it has focus. The text either wraps horizontally within the control or scrolls to the left, depending on the value specified in SetWordWrap. (The default is to wrap.) More...

#include <ff_dialogs.h>

Inheritance diagram for FCCtrlTextEditor:

Public Types
enum	STRINGFINDOPTIONS { STRFINDOPT_IGNORECASE = 0x01 , STRFINDOPT_WHOLEWORDS = 0x02 , STRFINDOPT_REGEX = 0x04 }
	Bitwise option codes for the CreateRangesForString method. More...
Public Types inherited from FCControl
enum	CONTROL_ACTIONS { ACTION_NONE = 0 , ACTION_OK = 1 , ACTION_CLOSE = 2 , ACTION_CANCEL = 3 }
	Predefined actions for controls. More...
Public Types inherited from __FCBase
enum	PDKFRAMEWORK_CLASSID {   FCID_UNKNOWN = 0 , FCID_ACCIDENTALMOD , FCID_ACTIVELYRIC , FCID_ALLOTMENT ,   FCID_ARTICULATION , FCID_ARTICULATIONDEF , FCID_BACKWARDREPEAT , FCID_BASELINE ,   FCID_BEAMMOD , FCID_BEATCHARTELEMENT , FCID_BOOKMARK , FCID_BROKENBEAMMOD ,   FCID_CATEGORYDEF , FCID_CELLCLEFCHANGE , FCID_CELLFRAMEHOLD , FCID_CELLGRAPHIC ,   FCID_CELLTEXT , FCID_CENTERSMARTSHAPE , FCID_CHORD , FCID_CHORDPREFS ,   FCID_CHORDSUFFIXELEMENT , FCID_CHORUSSYLLABLE , FCID_CLEFDEF , FCID_COMPOSITETIMESIGBOTTOMELEMENT ,   FCID_COMPOSITETIMESIGTOPELEMENT , FCID_CROSSSTAFFMOD , FCID_CUSTOMSMARTLINEDEF , FCID_CUSTOMSTEMMOD ,   FCID_DISTANCEPREFS , FCID_DOTMOD , FCID_ENCLOSURE , FCID_ENDINGREPEAT ,   FCID_ENIGMATEXTSTYLE , FCID_ENTRYALTERMOD , FCID_EXECUTABLESHAPEDEF , FCID_EXPRESSION ,   FCID_FONTINFO , FCID_FONTPREFS , FCID_FREEZESYSTEM , FCID_FRETBOARDSTYLEDEF ,   FCID_FRETBOARDSTYLEDEFS , FCID_FRETBOARDGROUPDEF , FCID_FRETBOARDGROUPDEFS , FCID_FRETINSTRUMENTDEF ,   FCID_GENERALPREFS , FCID_GRIDSGUIDESPREFS , FCID_GROUP , FCID_GROUPNAMEPOSITIONPREFS ,   FCID_HUMANPLAYBACKPREFS , FCID_INDEPENDENTCELLDETAIL , FCID_INSTRUMENTDEF , FCID_INSTRUMENTPLAYBACKDATA ,   FCID_KEYMODEDEF , FCID_KEYSIGNATURE , FCID_LAYERPREFS , FCID_LYRICSBASELINE ,   FCID_LYRICSPREFS , FCID_MEASURE , FCID_MEASURENUMBERREGION , FCID_METATOOLASSIGNMENT ,   FCID_MIDIEXPRESSION , FCID_MISCDOCPREFS , FCID_MULTIMEASUREREST , FCID_MULTIMEASURERESTPREFS ,   FCID_MULTISTAFFINSTRUMENT , FCID_MULTISTAFFINSTRUMENTS , FCID_MUSICCHARACTERPREFS , FCID_MUSICSPACINGPREFS ,   FCID_NUMBER , FCID_NOTEHEADMOD , FCID_OTHERINCI , FCID_PERCUSSIONLAYOUTNOTE ,   FCID_PERCUSSIONSTAFF , FCID_PERFORMANCEMOD , FCID_PAGE , FCID_PAGEFORMATPREFS ,   FCID_PAGEGRAPHIC , FCID_PAGETEXT , FCID_PART , FCID_PARTEXTRACTPREFS ,   FCID_PARTSCOPEPREFS , FCID_PARTSTAFFVOICING , FCID_PERCUSSIONNOTEMOD , FCID_PIANOBRACEPREFS ,   FCID_PLAYBACKPREFS , FCID_RAWTEXT , FCID_REPEATPREFS , FCID_SECONDARYBEAMBREAKMOD ,   FCID_BEAMEXTENSIONMOD , FCID_SECTIONSYLLABLE , FCID_SEPARATEMEASURENUMBER , FCID_SEPARATEPLACEMENT ,   FCID_SHAPEDEF , FCID_SHAPEEXPRESSIONDEF , FCID_SLURCONTOURPREFS , FCID_SIZEPREFS ,   FCID_SMARTSHAPE , FCID_SMARTSHAPEENTRYMARK , FCID_SMARTSHAPEMEASUREMARK , FCID_SMARTSHAPEPREFS ,   FCID_STAFF , FCID_STAFFLIST , FCID_STAFFNAMEPOSITION , FCID_STAFFNAMEPOSITIONPREFS ,   FCID_STAFFSTYLEASSIGN , FCID_STAFFSTYLEDEF , FCID_STAFFSYSTEM , FCID_STEMCONNECTIONTABLE ,   FCID_STEMMOD , FCID_STRING , FCID_SYLLABLEENTRYMOD , FCID_SYSTEMSTAFF ,   FCID_TABLATURENOTEMOD , FCID_TEMPOELEMENT , FCID_TEXTBLOCK , FCID_TEXTEXPRESSIONDEF ,   FCID_TEXTREPEAT , FCID_TEXTREPEATDEF , FCID_TIEMOD , FCID_TIEPREFS ,   FCID_TIECONTOURPREFS , FCID_TIEPLACEMENTPREFS , FCID_TIMESIGNATURE , FCID_TUPLET ,   FCID_TUPLETPREFS , FCID_VERSESYLLABLE }
	Constants for the GetClassID method. More...
enum	MEASUREMENTUNITS {   MEASUREMENTUNIT_DEFAULT = UNIT_DEFAULT , MEASUREMENTUNIT_EVPUS = UNIT_EVPUS , MEASUREMENTUNIT_INCHES = UNIT_INCHES , MEASUREMENTUNIT_CENTIMETERS = UNIT_CENTS ,   MEASUREMENTUNIT_POINTS = UNIT_POINTS , MEASUREMENTUNIT_PICAS = UNIT_PICAS , MEASUREMENTUNIT_SPACES = UNIT_SPACES , MEASUREMENTUNIT_MILLIMETERS = 100 }
	Constants for Finale's standard measurement units. More...

Public Member Functions
const char *	ClassName () const override
	Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child class.
	FCCtrlTextEditor (twobyte id)
	The constructor.
void	SetParent (__FCUserWindow *parentptr) override
	For internal use only. Overriden SetParent.
bool	GetTotalTextRange (FCRange *pRange) const
	Gets the total range of text on the control.
int	GetLineForPosition (int pos) const
	Returns the 1-based line number for the specified character position.
int	GetCurrentLine () const
	Returns the current line number, starting with line 1. The current line is the line of text where the cursor is or the beginning of the selected region.
bool	GetLineRangeForLine (int line, FCRange *pRange) const
	Returns the range of the specified line (1-based).
FCRanges *	CreateLineRanges (const FCRange *pRange=nullptr) const
	Returns FCRanges for all lines that overlap the specified range.
bool	GetLineRangeForPosition (int pos, FCRange *pRange) const
	Returns the range of the specified line (1-based) for the specified character position. On macOS this function is usually much more efficient than calling GetLineForPosition followed by GetLineRangeForLine. At worst it is the same on either platform.
bool	GetSelection (FCRange *pRange) const
	Gets the selected range on the control.
bool	SetSelection (const FCRange *pRange)
	Sets the selected range on the control.
bool	SelectAll ()
	Selects the entire text.
bool	GetTextInRange (FCString *pText, const FCRange *pRange) const
	Gets the text on the control corresponding to the input range.
bool	ReplaceTextInRange (const FCString *pText, const FCRange *pRange)
	Replaces the specified range of text with the contents of the input string. If the length of the range is zero, the text is inserted starting at FCRange::GetStart. Upon successful completion, the cursor is moved to the end of the newly inserted text.
bool	ReplaceTextInRangeWithFormat (const FCString *pText, const FCEnigmaTextStyle *pStyle, const FCRange *pRange)
	Replaces the specified range of text with the input string and formats it with the specified text style. If GetUseRichText is false, the function is the same as ReplaceTextInRange. If the length of the range is zero, the text is inserted starting at FCRange::GetStart. Upon successful completion, the cursor is moved to the end of the newly inserted text.
bool	ReplaceTextInRangeWithEnigmaString (const FCString *pString, const FCRange *pRange)
	Replaces the specified range of text with the input text and formatting specified by the input enigma string If GetUseRichText is false, the function copies the raw text, stripped of Enigma tags for font and style. If the length of the range is zero, the text is inserted starting at FCRange::GetStart. Upon successful completion, the cursor is moved to the end of the newly inserted text.
bool	GetSelectedText (FCString *pText) const
	Gets the selected text on the control.
bool	ReplaceSelectedText (const FCString *pText)
	Replaces the currently selected text with the contents of the input string. If no selection exists, the text is inserted at the cursor. Upon successful completion, the cursor is moved to the end of the newly inserted text.
void	InsertTextAtCursor (const FCString *pText)
	Inserts text at the current cursor location or at the end of the current selection if there is one. The cursor is moved to just after the inserted text.
void	AppendText (const FCString *pText)
	Appends the input string to the end of the text on the control.
void	AppendTextWithFormat (const FCString *pText, const FCEnigmaTextStyle *pStyle)
	Appends the input string to the end of the text on the control and formats it with the specified text style. If GetUseRichText is false, the function is the same as AppendText.
FCString *	CreateRTFString () const
	Returns an instance of FCString containing the text formatted as a Rich Text File (RTF). Note that the RTF specification represents text entirely with 8-bit ASCII characters, so you should use FCString::GetUTF8String or FCString::GetLuaString to write the contents to a file.
FCString *	CreateEnigmaString (const FCRange *pRange=nullptr) const
	Returns an instance of FCString containing the text with Enigma tags that represent the font formatting and style of the text in the control.
bool	SetRTFString (const FCString *pString)
	Sets the contents of the control from the input Rich Text Format string. Any previous text in the control is deleted. SetUseRichText is also set to true. Note that RTF is an ASCII format and encodes non-ASCII characters as escape sequences.
bool	SetEnigmaString (const FCString *pString, int rawtexttype=0)
	Sets the contents of the control based on the input Enigma string. Any previous text in the control is deleted. If GetUseRichText is true, all Enigma font and text styles are transferred to the control as text formatting. If it is false, the function copies the raw text, stripped of Enigma tags.
FCFontInfo *	CreateFontInfoAtIndex (int index) const
	Returns the font information at a specific 0-based index.
bool	SetFontInRange (const FCFontInfo *pFont, const FCRange *pRange)
	Sets the font for a specified range of text in the control.
bool	SetFontForSelection (const FCFontInfo *pFont)
	Sets the font for the currently selected range of text in the control.
bool	SetFontSizeInRange (int size, const FCRange *pRange)
	Sets the font size for the specified range without modifying other font formatting.
bool	SetFontSizeForSelection (int size)
	Sets the font size for the currently selected range of text in the control.
bool	SetFontBoldInRange (bool state, const FCRange *pRange)
	Sets the font bold for the specified range without modifying other font formatting.
bool	SetFontBoldForSelection (bool state)
	Sets the font bold for the currently selected range of text in the control.
bool	SetFontItalicInRange (bool state, const FCRange *pRange)
	Sets the font italic for the specified range without modifying other font formatting.
bool	SetFontItalicForSelection (bool state)
	Sets the font italic for the currently selected range of text in the control.
void	SetReadOnly (bool readonly)
	Sets the edit text field to be read-only or editable.
bool	GetReadOnly () const
	Gets the current read-only state of the edit text field.
void	SetWordWrap (bool wordwrap)
	Sets the edit text field to wrap or to have horizontal scrollers and not wrap.
bool	GetWordWrap () const
	Gets the edit text field's setting to wrap or to have horizontal scrollers and not wrap.
void	SetUseRichText (bool state)
	Sets the control's Rich Text state. See comments at GetUseRichText for more information about this setting.
bool	GetUseRichText () const
	Gets the control's Rich Text state. The control displays plain text or text with multiple fonts, styles, and sizes, based on this setting. If GetUseRichText is false, text pasted into the control assumes the control's font setting (set with SetFont). If GetUseRichText is true, text pasted into the control retains its font, size, and effects.
void	SetAutomaticEditing (bool state)
	Sets whether the control should use automatic editing features.
bool	GetAutomaticEditing () const
	Sets whether the control should use automatic editing features.
void	SetTabstopWidth (double value)
	Sets the tabstop width.
int	GetConvertTabsToSpaces () const
	Gets the number of spaces to which to convert tab characters. If this value is zero or negative, tabs are not converted.
void	SetConvertTabsToSpaces (int value)
	Sets the number of spaces to which to convert tab characters. If this value is zero or negative, tabs are not converted.
bool	GetAutomaticallyIndent () const
	Gets whether to automatically indent to the same tab level when hitting the Enter key.
void	SetAutomaticallyIndent (bool state)
	Sets whether to automatically indent to the same tab level when hitting the Enter key.
FCRanges *	CreateRangesForString (const FCString *pSearchString, FLAG_32 options, const FCRange *pRange=nullptr) const
	Returns a FCRanges collection with all occurrences of the search string. This function must be run while the window is active.
void	ResetUndoState ()
	Resets the undo state for the control. This prevents the user from undoing changes past the current state of text in the control.
bool	SetTextColorInRange (int red, int green, int blue, const FCRange *pRange)
	Sets the text color in a given range. If the range is to the end of the control, it also sets the default color for the control.
bool	SetBackgroundColorInRange (int red, int green, int blue, const FCRange *pRange)
	Sets the background color in a given range. If the range is to the end of the control, it also sets the default background color for the control.
bool	ResetTextColorInRange (const FCRange *pRange)
	Resets the text color in a given range to the system default color. On macOS, this is a dynamic color that supports switching between Dark Mode and Light Mode. On Windows, this setting allows hidden text to appear as grayed out. This is the default text color of the control.
bool	ResetBackgroundColorInRange (const FCRange *pRange)
	Resets the background color in a given range to the system default color. On macOS, this is a dynamic color that supports switching between Dark Mode and Light Mode.
bool	ResetColors ()
	Resets text and background colors to their default system colors for the entire control.
std::tuple< int, int, int >	GetTextColorAtIndex (int index) const
	Gets the text color at the specified index. On macOS, the value for the default color may differ depending on whether the system is in Light Mode or Dark Mode. (Note that it also may not match the currently displayed color if the mode switched while Finale was running.) However, if you are retrieving a color set with SetTextColorInRange, the color will be the same regardless of which mode the system is in.
std::tuple< int, int, int >	GetBackgroundColorAtIndex (int index) const
	Gets the background color at the specified index. On macOS, the value for the default color may differ depending on whether the system is in Light Mode or Dark Mode. (Note that it also may not match the currently displayed color if the mode switched while Finale was running.) However, if you are retrieving a color set with SetBackgroundColorInRange, the color will be the same regardless of which mode the system is in.
FCRanges *	CreateTextColorChanges () const
	Returns an FCRanges collection containing the range in the text where the color changes.
FCRanges *	CreateBackgroundColorChanges () const
	Returns an FCRanges collection containing the range in the text where the background color changes.
int	GetNumberOfLines () const
	Returns the number of lines of text currently displayed in the control.
double	GetVerticalScrollPosition () const
	Gets the current vertical position of the scrollbar.
void	ScrollToTop ()
	Scrolls the control to show the first character of text.
void	ScrollToBottom ()
	Scrolls the control to show the last character of text.
void	ScrollToVerticalPosition (double vpos)
	Scrolls the control to the speficied vertical position.
void	ScrollLineIntoView (int line)
	Scrolls the control so that the specified line comes into view.
double	GetLineSpacing () const
	Returns the distance in points between the bottom of one line and the top of the next.
void	SetLineSpacing (double value)
	Sets the distance in points between the bottom of one line and the top of the next.
FCString *	CreateCharacterAtIndex (int pos) const
	Returns the Unicode character at the given index. If the character at the given index is part of a surrogate pair, it returns the full Unicode code point even if the index points to the low surrogate.
bool	TextToClipboard () const
	Copies the formatted text to the clipboard. This function differs from FCUI::TextToClipboard in that it includes all the font, color, and other text formatting in the control along with the text.
Public Member Functions inherited from FCControl
	FCControl (twobyte id, const __FCControlTypedPtr &subclassPtr)
	The constructor.
	FCControl (twobyte id)
	The constructor for external C++ subclasses.
virtual	~FCControl ()
	Destructor.
bool	GetPointsMeasurement ()
	Returns if the measurements and positioning is in points or in a system-native unit.
__FCUserWindow *	GetParent () const
	Returns the parent window object for the control.
bool	WindowExists () const
	Returns true if a valid parent window handle (and control handle) is available.
HWND	_GetWinControlHandle () const
	For internal use only. Returns the handle for the control.
virtual void	Repaint ()
	Force a visual update of the control.
int	GetControlID () const
	Returns the control ID for the control.
int	GetAssignedID () const
	Gets the connected ID regardless of platform.
CONTROL_ACTIONS	GetAction () const
	Returns the dialog acction assigned to the control.
void	SetAction (CONTROL_ACTIONS action)
	Sets the dialog acction assigned to the control.
virtual void	SetEnable (bool state)
	Sets the enable/grayed state of the control (if user input should be allowed or not).
virtual bool	GetEnable () const
	Returns the enable/grayed state of the control (if user input should be allowed or not).
virtual void	SetVisible (bool bShow)
	Sets the visibility of the control.
virtual void	SetBold (bool state)
	Sets the boldface appearance for the control.
virtual void	SetFont (const FCFontInfo *fontInfo)
	Sets the font information for the text of the control.
virtual FCFontInfo *	CreateFontInfo () const
	Creates font information from the current text font of the control.
virtual void	SetKeyboardFocus ()
	Sets the keyboard focus to the control.
void	SetTextAndResize (FCString *pString)
	Cocoa only: Sets the text and resizes the view inside a NSScrollView.
virtual bool	AssureWidthForText ()
	Lengthens the width of the control to the extent necessary to display all the text in the control.
void	AssureNoHorizontalOverlap (const FCControl &control, int padding)
	Shift the control right as needed to the extent necessary so that its GetLeft position will accommodate the width of the specified control plus the specified padding. You can call this function with more than one reference control.
void	HorizontallyAlignLeftWith (const FCControl *pControl, double offset=0)
	Specifies a control with which to horizontally align left. All controls set to align with this control align at the location of the one with the largest GetLeft value. This function replaces any previous horizontal alignment options.
void	HorizontallyAlignRightWith (const FCControl *pControl, double offset=0)
	Specifies a control with which to horizontally align right. All controls set to align with this control align at the location of the one with the largest right value (GetLeft + GetWidth). This function replaces any previous horizontal alignment options.
void	HorizontallyAlignRightWithFurthest (double offset=0)
	Specifies that this control should align with the control that extends furthest to the right. Calling this function replaces any other control that has been set for horizontal alignment.
void	DoAutoResizeWidth (std::optional< double > minimumwidth=std::nullopt)
	Sets the autoresize width option for the control. When this value is set, the control calls AssureWidthForText automatically when the window initializes and every time SetText is called while the window is running.
void	StretchToAlignWithRight ()
	Sets a control to stretch its width to align with the furthest right control.
virtual void	SetText (const FCString *pString)
	Sets the text for the control.
virtual void	GetText (FCString *pString) const
	Gets the text of the control.
void	SetLeft (float pos)
	Sets the left position of the control.
float	GetLeft ()
	Returns the left position of the control.
void	SetTop (float pos)
	Sets the top position of the control.
float	GetTop ()
	Returns the top position of the control.
float	GetHeight ()
	Returns the height of the control.
float	GetWidth ()
	Returns the width of the control.
bool	GetVisible ()
	Returns the visibility state of a control.
void	SetWidth (float width)
	Sets the width of the control.
void	SetHeight (float height)
	Sets the height of the control.
void	MoveRelative (float horizmove, float vertmove)
	Moves the control relatively to the current position.
void	MoveAbsolute (float x, float y)
	Moves the control in absolute coordinates.
virtual void	ResizeRelative (float horizresize, float vertresize)
	Resizes the control relatively to the current size. Top left corner will stay fixed.
bool	RedrawImmediate () const
	Redraws the control immediately. Calling this allows your program that has blocked the main thread to show immediate results without relinquishing control back to the operating system.
Public Member Functions inherited from __FCBase
virtual const PDKFRAMEWORK_CLASSID	GetClassID () const
	Returns the internal class ID for the PDK Framework class. This is implemented mostly because Lua has problems to resolve the true classes of inherited objects.
virtual	~__FCBase ()
	Virtual destructor, so all inherited classes get the virtual destructor.
void	DebugMsgInt (const char *pszPrefixText, int i)
	Creates a simple Message Box for debug purposes. The text appears with the extra digit (in decimal presentation) appearing afterwards.
void	DebugMsgHex (const char *pszPrefixText, int i)
	Creates a simple Message Box for debug purposes. The text appears with the extra digit (as a hexadecimal number) appearing afterwards.
void	DebugMsgString (const char *pszPrefixText, const char *thestring)
	Creates a simple Message Box for debug purposes. The text appears with the extra string appearing afterwards.
void	DebugMsg (const char *pszMsg)
	Creates a simple Message Box for debug purposes with just one text string.
void	DebugOutMenuInfo (FCUI *pUI, int menuixd_horiz, int menuixd_vert) const
	Outputs the menu command info for debugging purposes.
int	DebugOutFormat (const char *fmt,...)
	Outputs debug text using C style "printf" syntax.
virtual void	DebugDump ()
	Outputs the class data/information for debugging purposes.
virtual void	DebugDataDump ()
	Outputs a memory dump of the data block in the object for debugging purposes.
virtual void	DebugDataByteArrayDump ()
	Outputs a memory dump of the data block in the object for debugging purposes, as a C++ byte array.
void	Set16BitFlag (FLAG_16 *flag, FLAG_16 flagbits, bool state)
	Sets a 16 bit flag.
void	Set32BitFlag (FLAG_32 *flag, FLAG_32 flagbits, bool state)
	Sets/resets a 32 bit flag, by using a bit mask.
bool	GetBitFlag (FLAG_32 flag, FLAG_32 flagbits) const
	Gets a state from flag bits. Returns true if any bit in the mask is set.
int	GetBitCount (FLAG_32 flag)
	Returns the total number of set bits in a 32-bit unsigned int.
void	SetSpecific32Bit (FLAG_32 *flag, int bitnumber, bool state)
	Sets/resets a single bit in a 32 bit flag, by specifying one specific bit.
void	SetUserData (void *pData)
	Sets the user data attached to the instance of an object.
void	SetUserData2 (void *pData)
	Sets the additional user data attached to the instance of an object.
void *	GetUserData () const
	Gets the user data attached to the instance of an object.
void *	GetUserData2 () const
	Gets the additional user data attached to the instance of an object.
virtual bool	IsIdentical (const __FCBase *pCompareObject) const
	Returns true if the data in the passed object is considered to be identical to the current object, otherwise false.
void	StoreXML_String (tinyxml2::XMLElement *pParentNode, const char *pszElementName, FCString *pStringValue)
	Helper function to store FCString objects in the XML file.
void	StoreXML_Integer (tinyxml2::XMLElement *pParentNode, const char *pszElementName, int value)
	Helper function to store integer objects in the XML file.
void	StoreXML_Bool (tinyxml2::XMLElement *pParentNode, const char *pszElementName, bool value)
	Helper function to store boolean objects in the XML file.
void	StoreXML_StringAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, FCString *pStringValue)
	Helper function to store FCString objects in the XML file, as an attribute to a node.
void	StoreXML_IntegerAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, int value)
	Helper function to store integer objects in the XML file, as an attribute to a node.
void	StoreXML_BoolAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, bool value)
	Helper function to store boolean objects in the XML file, as an attribute to a node.
void	StoreXML_FloatAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, float value)
	Helper function to store floating point objects in the XML file, as an attribute to a node.
virtual void	StoreToXML (tinyxml2::XMLElement *pParentNode)
	Virtual method that is used to store an object's data.
bool	ReadXML_String (tinyxml2::XMLElement *pParentNode, const char *pszElementName, FCString *pStringValue)
	Helper method to read FCString objects from the XML file.
bool	ReadXML_Integer (tinyxml2::XMLElement *pParentNode, const char *pszElementName, int *pValue)
	Helper method to read integer objects from the XML file.
bool	ReadXML_Bool (tinyxml2::XMLElement *pParentNode, const char *pszElementName, bool *pValue)
	Helper method to read boolean objects from the XML file.
bool	ReadXML_StringAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, FCString *pStringValue)
	Helper method to read FCString objects from the XML file, as an attribute to a node.
bool	ReadXML_IntegerAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, int *pValue)
	Helper method to read integer objects from the XML file, as an attribute to a node.
bool	ReadXML_BoolAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, bool *pValue)
	Helper method to read boolean objects from the XML file, as an attribute to a node.
bool	ReadXML_FloatAttribute (tinyxml2::XMLElement *pNode, const char *pszAttributeName, float *pValue)
	Helper method to read floating point objects from the XML file, as an attribute to a node.
virtual bool	ReadFromXML (tinyxml2::XMLElement *pParentNode)
	Virtual method that is used to read object data.

Additional Inherited Members
Static Public Member Functions inherited from __FCBase
static void	DebugOutPtr (const char *pszPrefixText, void *ptr)
	Static method that outputs a line for debugging purposes. The prefix text appears with the extra ptr (in hexadeximal representation) appearing afterwards.
static void	DebugOutInt (const char *pszPrefixText, int i)
	Static method that outputs a line for debugging purposes. The text appears with the extra digit (in decimal presentation) appearing afterwards.
static void	DebugOutFloat (const char *pszPrefixText, double f)
	Static method that outputs a line for debugging purposes. The text appears with the extra float value appearing afterwards.
static void	DebugOutTag (const char *pszPrefixText, EXTAG extag)
	Static method that outputs a line for debugging purposes. The text appears with the EXTAG (in text) appearing afterwards.
static void	DebugOutHex (const char *pszPrefixText, int i)
	Static method that outputs a line for debugging purposes. The text appears with the extra digit (in hexadecimal presentation) appearing afterwards.
static void	DebugOutBin (const char *pszPrefixText, int i)
	Static method that outputs a line for debugging purposes. The text appears with the extra digit (in binary presentation) appearing afterwards.
static void	DebugOutString (const char *pszPrefixText, const char *thestring)
	Static method that outputs a line for debugging purposes (C string version). The text appears with the extra string appearing afterwards.
static void	DebugOutString (const char *pszPrefixText, FCString *pString)
	Static method that outputs a line for debugging purposes (FCString version). The text appears with the extra string appearing afterwards.
static void	DebugOutBool (const char *pszPrefixText, bool state)
	Static method that outputs a line for debugging purposes. The boolean state appears afterwards as either "TRUE" or "FALSE".
static void	DebugOutBlock (const void *pBuffer, int startoffset, int size)
	Static method that outputs a memory block for debugging purposes. Eight bytes per line will appear (as hex digits) until the whole memory block is dumped.
static void	DebugOutByteArrayBlock (const void *pBuffer, int startoffset, int size)
	Static method that outputs a memory block for debugging purposes. Eight bytes per line will appear (as hex digits) as a C++ onebyte array, until the whole memory block is dumped.
static void	DebugOut (const char *pszLine)
	Static method to output a line of text for debugging purposes.
Protected Member Functions inherited from __FCBase
	__FCBase ()
	The constructor.

Detailed Description

UI class that handles a multiline edit control for viewing or modifying text (optionally formatted with font information). It has a vertical scroll bar when needed and captures the Enter and Tab keys when it has focus. The text either wraps horizontally within the control or scrolls to the left, depending on the value specified in SetWordWrap. (The default is to wrap.)

For the techinally minded, the Windows control is a Rich Edit control, and the macOS control is NSTextView.

A fully functioning sample script may be found here.

Member Enumeration Documentation

STRINGFINDOPTIONS

enum FCCtrlTextEditor::STRINGFINDOPTIONS

Bitwise option codes for the CreateRangesForString method.

Lua-supported.

Enumerator
STRFINDOPT_IGNORECASE	Ignore case.
STRFINDOPT_WHOLEWORDS	Only match whole words.
STRFINDOPT_REGEX	Regular expressions. (Overrides STRFINDOPT_WHOLEWORDS.)

Member Function Documentation

AppendText()

void FCCtrlTextEditor::AppendText

(

const FCString *

pText

)

Appends the input string to the end of the text on the control.

This function must be called while the window is running.

Lua-supported (0.68).

AppendTextWithFormat()

void FCCtrlTextEditor::AppendTextWithFormat	(	const FCString *	pText,
		const FCEnigmaTextStyle *	pStyle )

Appends the input string to the end of the text on the control and formats it with the specified text style. If GetUseRichText is false, the function is the same as AppendText.

This function must be called while the window is running.

Lua-supported (0.68).

ClassName()

const char * FCCtrlTextEditor::ClassName ( ) const

inlineoverridevirtual

Returns the name of the class, for diagnostic purposes. This method MUST be overwritten in each child class.

Lua-supported.

Reimplemented from FCControl.

CreateBackgroundColorChanges()

FCRanges * FCCtrlTextEditor::CreateBackgroundColorChanges ( ) const

inline

Returns an FCRanges collection containing the range in the text where the background color changes.

C++ callers must dispose of the returned value either with delete or with a smart pointer.

Lua-supported (0.68).

Returns

a collection of ranges where a new color applies, or NULL if window is inactive or error.

CreateCharacterAtIndex()

FCString * FCCtrlTextEditor::CreateCharacterAtIndex

(

int

pos

)

const

Returns the Unicode character at the given index. If the character at the given index is part of a surrogate pair, it returns the full Unicode code point even if the index points to the low surrogate.

Note

The most efficient way to iterate the characters is to start from 0 or from the start position of an instance of FCRange returned by the control. Then increment your index by the length of the string returned using FCString::GetLength.

Use FCString::AppendString to build up a string of characters returned by this function.

Lua-supported (0.71)

Parameters

pos	0-based index of the character inside the text of the control. one when the character is outside the Basic Multilingual Plane (BMP).

Returns

character string or NULL if not found or the window is not running or other error.

CreateEnigmaString()

FCString * FCCtrlTextEditor::CreateEnigmaString

(

const FCRange *

pRange = nullptr

)

const

Returns an instance of FCString containing the text with Enigma tags that represent the font formatting and style of the text in the control.

Note

When the window closes, FCCtrlTextEditor makes a copy of its contents as an enigma string to allow callers to retrieve it. Creating the enigma string is compute-intensive, especially for long text on Windows. If your application does not require the enigma string, it is recommended to clear the text out of the control in a FCCustomLuaWindow::CloseWindow handler as the window closes.

Warning

CreateEnigmaString only returns font, size, effects, and text style Enigma tags. If you used SetEnigmaString to set the string, you will have lost any other Enigma tags that were in the string unless you took steps to preserve them. See the comments at SetEnigmaString for more information.

If the window is not running, the pRange parameter must be NULL.

C++ callers must dispose of the result, either with delete or smart pointers.

Lua-supported (0.68).

Parameters

pRange

(optional) Range from which to create the enigma string or NULL for the entire contents.

Returns

Enigma string or NULL if error

CreateFontInfoAtIndex()

FCFontInfo * FCCtrlTextEditor::CreateFontInfoAtIndex

(

int

index

)

const

Returns the font information at a specific 0-based index.

C++ callers must dispose of the returned value either with delete or with a smart pointer.

Lua-supported (0.68).

Parameters

index

0-based index relative to the plain text in the control. The safest value to use is a start value from an FCRange instance returned by the control.

Returns

the font at the index or NULL if the index is invalid or the window is inactive.

CreateLineRanges()

FCRanges * FCCtrlTextEditor::CreateLineRanges

(

const FCRange *

pRange = nullptr

)

const

Returns FCRanges for all lines that overlap the specified range.

C++ callers must dispose of the result either with delete or with a smart pointer.

Lua-supported (0.68).

Parameters

pRange

(optional) the range for which to get lines. If omitted or NULL, lines for the entire control are returned

Returns

the lines in the control or NULL if the window is not running or other error.

CreateRangesForString()

FCRanges * FCCtrlTextEditor::CreateRangesForString	(	const FCString *	pSearchString,
		FLAG_32	options,
		const FCRange *	pRange = nullptr ) const

Returns a FCRanges collection with all occurrences of the search string. This function must be run while the window is active.

Warning

To use ReplaceTextInRange to replace the occurrences with a different string value, Lua programmers should iterate the collection with eachbackwards to avoid invalidating the range elements that haven't yet been processed.

C++ callers must dispose of the returned pointer either with delete or with a smart pointer.

Lua-supported (0.68).

Parameters

pSearchString	The string to search for.
options	Any of the STRINGFINDOPTIONS constants. Multiple options may be specified with logical or.
pRange	(optional) the range in which to search. If omitted, the entire text in the control is searched.

Returns

the set of ranges in the control where the search string is, or null if error or not found.

CreateRTFString()

FCString * FCCtrlTextEditor::CreateRTFString

(

)

const

Returns an instance of FCString containing the text formatted as a Rich Text File (RTF). Note that the RTF specification represents text entirely with 8-bit ASCII characters, so you should use FCString::GetUTF8String or FCString::GetLuaString to write the contents to a file.

The function uses APIs in the operating system to generate the string, so the results will likely be substantially different on each operating system. (The results of CreateEnigmaString are often the same, if the same fonts are available on both systems.)

Warning

You may wish to avoid using CreateRTFString to retrieve text that was entered into the control with SetEnigmaString. CreateEnigmaString provides more accurate results in this case. The reason is that Enigma has formatting features that are not directly supported by the operating systems. To preserve them, the FCCtrlTextEditor modifies the text attributes to make it possible to extract the same Enigma formatting that was sent to the control. CreateEnigmaString backs the changes out to recover the clean Enigma formatting. That said, as long as your Enigma string does not use the following format options, it should render correctly as RTF.

• Absolute font effect.
• Hidden font effect.
• Superscript. (Baseline adjustments are okay.)
• Interletter Spacing (called "Tracking" in Finale.)

C++ callers must dispose of the result, either with delete or smart pointers.

Lua-supported (0.68).

Returns

RTF-formatted string or NULL if error or the window is not running.

CreateTextColorChanges()

FCRanges * FCCtrlTextEditor::CreateTextColorChanges ( ) const

inline

Returns an FCRanges collection containing the range in the text where the color changes.

C++ callers must dispose of the returned value either with delete or with a smart pointer.

Lua-supported (0.68).

Returns

a collection of ranges where a new color applies, or NULL if window is inactive or error.

GetAutomaticallyIndent()

bool FCCtrlTextEditor::GetAutomaticallyIndent ( ) const

inline

Gets whether to automatically indent to the same tab level when hitting the Enter key.

Lua-supported (0.68)

GetAutomaticEditing()

bool FCCtrlTextEditor::GetAutomaticEditing ( ) const

inline

Sets whether the control should use automatic editing features.

The default is true.

Lua-supported (0.68).

GetBackgroundColorAtIndex()

std::tuple< int, int, int > FCCtrlTextEditor::GetBackgroundColorAtIndex ( int index ) const

inline

Gets the background color at the specified index. On macOS, the value for the default color may differ depending on whether the system is in Light Mode or Dark Mode. (Note that it also may not match the currently displayed color if the mode switched while Finale was running.) However, if you are retrieving a color set with SetBackgroundColorInRange, the color will be the same regardless of which mode the system is in.

Lua-supported (0.68)

Parameters

index

the index at which to get the color

Returns

A tuple (C++) or table (Lua) containing the three color vales for red, green, and blue. If the window is inactive or if there is an error, all three are set to -1.

GetConvertTabsToSpaces()

int FCCtrlTextEditor::GetConvertTabsToSpaces ( ) const

inline

Gets the number of spaces to which to convert tab characters. If this value is zero or negative, tabs are not converted.

Lua-supported (0.68).

GetCurrentLine()

int FCCtrlTextEditor::GetCurrentLine ( ) const

inline

Returns the current line number, starting with line 1. The current line is the line of text where the cursor is or the beginning of the selected region.

Lua-supported (0.68).

Returns

the 1-based current line number, or 0 if error or the window is not active.

GetLineForPosition()

int FCCtrlTextEditor::GetLineForPosition

(

int

pos

)

const

Returns the 1-based line number for the specified character position.

If GetWordWrap is true, this function counts each wrapped line of text as a new line.

Lua-supported (0.68).

Parameters

pos	the 0-based character position within the text.

Returns

the 1-based current line number, or 0 if error or the window is not active.

GetLineRangeForLine()

bool FCCtrlTextEditor::GetLineRangeForLine	(	int	line,
		FCRange *	pRange ) const

Returns the range of the specified line (1-based).

Lua-supported (0.68).

Parameters

line	the 1-based line number to find.
pRange	the range of characters on the line, not including the line-ending (if there is one).

Returns

true if found, false if the window is not running or the line number is out of range.

GetLineRangeForPosition()

bool FCCtrlTextEditor::GetLineRangeForPosition	(	int	pos,
		FCRange *	pRange ) const

Returns the range of the specified line (1-based) for the specified character position. On macOS this function is usually much more efficient than calling GetLineForPosition followed by GetLineRangeForLine. At worst it is the same on either platform.

Lua-supported (0.68).

Parameters

pos	the 0-based character position within the text.
pRange	the range of characters on the line, not including the line-ending (if there is one).

Returns

true if found, false if the window is not running or the position is out of range.

GetLineSpacing()

double FCCtrlTextEditor::GetLineSpacing

(

)

const

Returns the distance in points between the bottom of one line and the top of the next.

See comments at SetLineSpacing for more information.

Lua-supported (0.71)

Returns

the line spacing value in points (72dpi).

GetNumberOfLines()

int FCCtrlTextEditor::GetNumberOfLines

(

)

const

Returns the number of lines of text currently displayed in the control.

Remarks

This function counts visible lines. If SetWordWrap is enabled, a wrapped line counts as 2 or more lines even if it contains no line breaks. If SetWordWrap is not enabled, then this number corresponds to the number of hard line breaks plus one.

Lua-supported (0.68).

Returns

number of lines of text in the control, or zero if the window is not running.

GetReadOnly()

bool FCCtrlTextEditor::GetReadOnly

(

)

const

Gets the current read-only state of the edit text field.

Lua-supported (0.68).

GetSelectedText()

bool FCCtrlTextEditor::GetSelectedText ( FCString * pText ) const

inline

Gets the selected text on the control.

On Windows, all line endings are converted to CRLF.

Lua-supported (0.68).

Parameters

pText

receives the selected text. If no selection exists, it is not changed.

Returns

true if a selection existed.

GetSelection()

bool FCCtrlTextEditor::GetSelection

(

FCRange *

pRange

)

const

Gets the selected range on the control.

Warning

On Windows, this range only includes one character per line break. To get the text for this range with correct linebreaks, call GetTextInRange.

Lua-supported (0.68).

Parameters

pRange

receives the range text. If no selection exists, the range is set to the current cursor location with zero length.

Returns

true if no error.

GetTextColorAtIndex()

std::tuple< int, int, int > FCCtrlTextEditor::GetTextColorAtIndex ( int index ) const

inline

Gets the text color at the specified index. On macOS, the value for the default color may differ depending on whether the system is in Light Mode or Dark Mode. (Note that it also may not match the currently displayed color if the mode switched while Finale was running.) However, if you are retrieving a color set with SetTextColorInRange, the color will be the same regardless of which mode the system is in.

Lua-supported (0.68)

Parameters

index

the index at which to get the color

Returns

A tuple (C++) or table (Lua) containing the three color vales for red, green, and blue. If the window is inactive or if there is an error, all three are set to -1.

GetTextInRange()

bool FCCtrlTextEditor::GetTextInRange	(	FCString *	pText,
		const FCRange *	pRange ) const

Gets the text on the control corresponding to the input range.

Generally you should only pass in instances of FCRange created by FCCtrlTextEditor. These are guaranteed to be correct for UTF-16 encoding of characters outside the Basic Multilingual Plane (BMP) and to handle line endings correctly for other calls to methods on the control.

Warning

On Windows, all line endings are converted to CRLF. That means the length of the returned string may be greater than the length of the input FCRange instance.

Lua-supported (0.68).

Parameters

pText	receives the text.
pRange	the range from which to get the text

Returns

false the specified range does not overlap the range of the string returned by GetTotalTextRange.

GetTotalTextRange()

bool FCCtrlTextEditor::GetTotalTextRange

(

FCRange *

pRange

)

const

Gets the total range of text on the control.

Warning

On Windows, this range only includes one character per line break. The main reason you might call this method is to get an FCRange instance for calling other methods on FCCtrlTextEditor with a range parameter for the entire control (for example, SetSelection).

Lua-supported (0.68).

Parameters

pRange

receives the range

Returns

true if range was found, false if error or there is no running window

GetUseRichText()

bool FCCtrlTextEditor::GetUseRichText

(

)

const

Gets the control's Rich Text state. The control displays plain text or text with multiple fonts, styles, and sizes, based on this setting. If GetUseRichText is false, text pasted into the control assumes the control's font setting (set with SetFont). If GetUseRichText is true, text pasted into the control retains its font, size, and effects.

Beyond this, the restrictions on formatting placed on text when this value is false vary signficantly between Windows and macOS. Windows is generally much more restrictive, preventing any changes in color, font, or line spacing.

The default value is true.

Lua-supported (0.68).

GetVerticalScrollPosition()

double FCCtrlTextEditor::GetVerticalScrollPosition

(

)

const

Gets the current vertical position of the scrollbar.

Lua-supported (0.68)

Returns

os-dependent vertical scroll position, or negative value if window is not running or error.

GetWordWrap()

bool FCCtrlTextEditor::GetWordWrap ( ) const

inline

Gets the edit text field's setting to wrap or to have horizontal scrollers and not wrap.

Lua-supported (0.68).

InsertTextAtCursor()

void FCCtrlTextEditor::InsertTextAtCursor

(

const FCString *

pText

)

Inserts text at the current cursor location or at the end of the current selection if there is one. The cursor is moved to just after the inserted text.

This function must be called while the window is running.

Lua-supported (0.68).

Parameters

pText

the text that replaces the selection.

ReplaceSelectedText()

bool FCCtrlTextEditor::ReplaceSelectedText ( const FCString * pText )

inline

Replaces the currently selected text with the contents of the input string. If no selection exists, the text is inserted at the cursor. Upon successful completion, the cursor is moved to the end of the newly inserted text.

Lua-supported (0.68).

Parameters

pText

the text that replaces the selection.

Returns

true if a selection existed.

ReplaceTextInRange()

bool FCCtrlTextEditor::ReplaceTextInRange	(	const FCString *	pText,
		const FCRange *	pRange )

Replaces the specified range of text with the contents of the input string. If the length of the range is zero, the text is inserted starting at FCRange::GetStart. Upon successful completion, the cursor is moved to the end of the newly inserted text.

Lua-supported (0.68).

Parameters

pText	the text that replaces the selection.
pRange	the range of text to replace in the control.

Returns

true if text was replaced.

ReplaceTextInRangeWithEnigmaString()

bool FCCtrlTextEditor::ReplaceTextInRangeWithEnigmaString ( const FCString * pString, const FCRange * pRange )

inline

Replaces the specified range of text with the input text and formatting specified by the input enigma string If GetUseRichText is false, the function copies the raw text, stripped of Enigma tags for font and style. If the length of the range is zero, the text is inserted starting at FCRange::GetStart. Upon successful completion, the cursor is moved to the end of the newly inserted text.

Lua-supported (0.68).

ReplaceTextInRangeWithFormat()

bool FCCtrlTextEditor::ReplaceTextInRangeWithFormat	(	const FCString *	pText,
		const FCEnigmaTextStyle *	pStyle,
		const FCRange *	pRange )

Replaces the specified range of text with the input string and formats it with the specified text style. If GetUseRichText is false, the function is the same as ReplaceTextInRange. If the length of the range is zero, the text is inserted starting at FCRange::GetStart. Upon successful completion, the cursor is moved to the end of the newly inserted text.

This function must be called while the window is running.

Lua-supported (0.68).

ResetBackgroundColorInRange()

bool FCCtrlTextEditor::ResetBackgroundColorInRange ( const FCRange * pRange )

inline

Resets the background color in a given range to the system default color. On macOS, this is a dynamic color that supports switching between Dark Mode and Light Mode.

Lua-supported (0.68).

Parameters

pRange

the range in which to set the text color.

Returns

true if successful, false if window is not running or error.

ResetColors()

bool FCCtrlTextEditor::ResetColors ( )

inline

Resets text and background colors to their default system colors for the entire control.

Lua-supported (0.68)

Returns

true if successful, false if window is not running or error.

ResetTextColorInRange()

bool FCCtrlTextEditor::ResetTextColorInRange ( const FCRange * pRange )

inline

Resets the text color in a given range to the system default color. On macOS, this is a dynamic color that supports switching between Dark Mode and Light Mode. On Windows, this setting allows hidden text to appear as grayed out. This is the default text color of the control.

Lua-supported (0.68).

Parameters

pRange

the range in which to set the text color.

Returns

true if successful, false if window is not running or error.

ResetUndoState()

void FCCtrlTextEditor::ResetUndoState

(

)

Resets the undo state for the control. This prevents the user from undoing changes past the current state of text in the control.

For usability, the primary use case for calling this is after initializing the control when the window opens.

Lua-supported (0.68)

ScrollLineIntoView()

void FCCtrlTextEditor::ScrollLineIntoView

(

int

line

)

Scrolls the control so that the specified line comes into view.

Lua-supported (0.68)

Parameters

line	the 1-based line number

ScrollToBottom()

void FCCtrlTextEditor::ScrollToBottom

(

)

Scrolls the control to show the last character of text.

Lua-supported (0.68)

ScrollToTop()

void FCCtrlTextEditor::ScrollToTop

(

)

Scrolls the control to show the first character of text.

Lua-supported (0.68)

ScrollToVerticalPosition()

void FCCtrlTextEditor::ScrollToVerticalPosition

(

double

vpos

)

Scrolls the control to the speficied vertical position.

Lua-supported (0.68)

Parameters

vpos	os-dependent vertical scroll position. The best way to get a valid value is to start by calling GetVerticalScrollPosition.

SelectAll()

bool FCCtrlTextEditor::SelectAll ( )

inline

Selects the entire text.

Lua-supported (0.68).

SetAutomaticallyIndent()

void FCCtrlTextEditor::SetAutomaticallyIndent ( bool state )

inline

Sets whether to automatically indent to the same tab level when hitting the Enter key.

Lua-supported (0.68)

SetAutomaticEditing()

void FCCtrlTextEditor::SetAutomaticEditing

(

bool

state

)

Sets whether the control should use automatic editing features.

The features are macOS-specific. They include automatic quote conversion, dash conversion, spell checking, etc. This function has no effect on Windows.

Lua-supported (0.68).

SetBackgroundColorInRange()

bool FCCtrlTextEditor::SetBackgroundColorInRange ( int red, int green, int blue, const FCRange * pRange )

inline

Sets the background color in a given range. If the range is to the end of the control, it also sets the default background color for the control.

Lua-supported (0.68).

Parameters

red	a value from 0-255.
green	a value from 0-255.
blue	a value from 0-255.
pRange	the range in which to set the text color.

Returns

true if successful, false if window is not running or error.

SetConvertTabsToSpaces()

void FCCtrlTextEditor::SetConvertTabsToSpaces ( int value )

inline

Sets the number of spaces to which to convert tab characters. If this value is zero or negative, tabs are not converted.

Remarks

You can set this value before the window is running or while it is running. However, it does not convert any tab characters that are already in the text.

Lua-supported (0.68).

SetEnigmaString()

bool FCCtrlTextEditor::SetEnigmaString ( const FCString * pString, int rawtexttype = 0 )

inline

Sets the contents of the control based on the input Enigma string. Any previous text in the control is deleted. If GetUseRichText is true, all Enigma font and text styles are transferred to the control as text formatting. If it is false, the function copies the raw text, stripped of Enigma tags.

Text marked with the "Hidden" attribute appears grayed-out. Text marked with the "Fixed" attribute appears slightly larger than text not marked as Fixed.

Warning

This function removes all Enigma tags but only represents the Enigma tags for text formatting visually in the control. Other Enigma tags (such as text inserts for sharps, flats, controller values, etc.) are stripped from the text silently and non-recoverable. The reason for this behavior is that the control does not have access to the data or context it needs to convert other Enigma tags to the correct text. This is left up to the caller.

You can preserve any tag that should not be either stripped or processed by replacing the single caret ("^") with a double caret ("^^"). This will cause single-caret Enigma tags to appear as normal text in the control. When you get back the Enigma string with CreateEnigmaString, the single carets are converted back to double carets, and you can then identify and process them as needed. However, presenting Enigma tags to the user may not be the optimal solution.

Lua-supported (0.68).

Parameters

pString

the string to use as a source.

rawtexttype

(may be omitted). One of the FCRawText::RAWTEXTTYPES contants. This value is used to initialize the font information with default font info that is appropriate to the specified raw text type. Default font information is only needed if the Enigma string lacks font tags at the beginning, which cannot happen for Enigma strings created with CreateEnigmaString. It rarely if ever happens out of Finale either, but it might be important if pString can be empty. If you omit the parameter, FCRawText::RAWTEXTTYPE_TEXTBLOCK is used.

Returns

true if success, false if error.

SetFontBoldForSelection()

bool FCCtrlTextEditor::SetFontBoldForSelection

(

bool

state

)

Sets the font bold for the currently selected range of text in the control.

Lua-supported (0.68)

Parameters

state

true turns on bold and false turns it off

Returns

true if success, false if the window is not active, there is no selection, or other error

SetFontBoldInRange()

bool FCCtrlTextEditor::SetFontBoldInRange	(	bool	state,
		const FCRange *	pRange )

Sets the font bold for the specified range without modifying other font formatting.

Lua-supported (0.68).

Parameters

state	true turns on bold and false turns it off
pRange	the range of text to set. The safest values to use are instances returned by the control.

Returns

true if success, false if the window is not active, range is zero-length, or other error

SetFontForSelection()

bool FCCtrlTextEditor::SetFontForSelection

(

const FCFontInfo *

pFont

)

Sets the font for the currently selected range of text in the control.

Lua-supported (0.68)

Parameters

pFont

the new font to set

Returns

true if success, false if the window is not active, there is no selection, or other error

SetFontInRange()

bool FCCtrlTextEditor::SetFontInRange	(	const FCFontInfo *	pFont,
		const FCRange *	pRange )

Sets the font for a specified range of text in the control.

Lua-supported (0.68).

Parameters

pFont	the font information to use.
pRange	the range of text to set. The safest values to use are instances returned by the control.

Returns

true if success, false if the window is not active or other error

SetFontItalicForSelection()

bool FCCtrlTextEditor::SetFontItalicForSelection

(

bool

state

)

Sets the font italic for the currently selected range of text in the control.

Lua-supported (0.68)

Parameters

state

true turns on bold and false turns it off

Returns

true if success, false if the window is not active, there is no selection, or other error

SetFontItalicInRange()

bool FCCtrlTextEditor::SetFontItalicInRange	(	bool	state,
		const FCRange *	pRange )

Sets the font italic for the specified range without modifying other font formatting.

Lua-supported (0.68).

Parameters

state	true turns on italic and false turns it off
pRange	the range of text to set. The safest values to use are instances returned by the control.

Returns

true if success, false if the window is not active, range is zero-length, or other error

SetFontSizeForSelection()

bool FCCtrlTextEditor::SetFontSizeForSelection

(

int

size

)

Sets the font size for the currently selected range of text in the control.

Lua-supported (0.68)

Parameters

size	the new font size in points.

Returns

true if success, false if the window is not active, there is no selection, or other error

SetFontSizeInRange()

bool FCCtrlTextEditor::SetFontSizeInRange	(	int	size,
		const FCRange *	pRange )

Sets the font size for the specified range without modifying other font formatting.

Lua-supported (0.68).

Parameters

size	the new font size in points.
pRange	the range of text to set. The safest values to use are instances returned by the control.

Returns

true if success, false if the window is not active, range is zero-length, or other error

SetLineSpacing()

void FCCtrlTextEditor::SetLineSpacing

(

double

value

)

Sets the distance in points between the bottom of one line and the top of the next.

Remarks

Windows and macOS treat this value differently. On Windows it is the distance between the top of one line to the top of the next. On macOS it is the distance between the bottom of one line and the top of next. Values on macOS will need to be considerably smaller than on Windows to achieve a similar look-and-feel.

On Windows, SetLineSpacing has no effect if GetUseRichText is false.

Lua-supported (0.71)

Parameters

value

line spacing value in points (72 dpi).

SetReadOnly()

void FCCtrlTextEditor::SetReadOnly

(

bool

readonly

)

Sets the edit text field to be read-only or editable.

Lua-supported (0.68).

SetRTFString()

bool FCCtrlTextEditor::SetRTFString

(

const FCString *

pString

)

Sets the contents of the control from the input Rich Text Format string. Any previous text in the control is deleted. SetUseRichText is also set to true. Note that RTF is an ASCII format and encodes non-ASCII characters as escape sequences.

Warning

Rich Text Format provides many more formatting options than Enigma strings do. If you extract the text with CreateEnigmaString, you will lose formatting that is not supported by Enigma. Some examples of formatting that will be lost are color and paragraph formatting.

To process the RTF text, SetRTFString uses built-in APIs provided by each respective OS.

Lua-supported (0.68)

Parameters

pString

the string containing RTF text to use as the source.

Returns

true if success, false if the windows is not running or error.

SetSelection()

bool FCCtrlTextEditor::SetSelection

(

const FCRange *

pRange

)

Sets the selected range on the control.

Warning

On Windows, this range only includes one character per line break. To get the text for this range call GetTextInRange.

Lua-supported (0.68).

Parameters

pRange

the range of text to select.

Returns

true if a selection was set, false if error.

SetTabstopWidth()

void FCCtrlTextEditor::SetTabstopWidth

(

double

value

)

Sets the tabstop width.

You can modify the tabstob width while the window is running, and it redisplays the text with the new tabstobs. Note that this method only affects actual tab characters. If GetConvertTabsToSpaces is greater than zero, then SetTabstopWidth has no effect on any tabs that were converted to spaces.

Lua-supported (0.68)

Parameters

value

The new tabstop width in points (72 per inch).

SetTextColorInRange()

bool FCCtrlTextEditor::SetTextColorInRange ( int red, int green, int blue, const FCRange * pRange )

inline

Sets the text color in a given range. If the range is to the end of the control, it also sets the default color for the control.

Lua-supported (0.68).

Parameters

red	a value from 0-255.
green	a value from 0-255.
blue	a value from 0-255.
pRange	the range in which to set the text color.

Returns

true if successful, false if window is not running or error.

Todo

Show hidden text with more faded color in Windows (like the default black color already does). This is already implemented on the macOS side using alpha, but the solution on Windows introduces a lot of complexity for a feature that is probably rarely used.

SetUseRichText()

void FCCtrlTextEditor::SetUseRichText

(

bool

state

)

Sets the control's Rich Text state. See comments at GetUseRichText for more information about this setting.

The default value is true.

Lua-supported (0.68).

SetWordWrap()

void FCCtrlTextEditor::SetWordWrap

(

bool

wordwrap

)

Sets the edit text field to wrap or to have horizontal scrollers and not wrap.

Warning

The Windows version of the control can only be set to wrap or not wrap before the dialog is running. After that, SetWordWrap has no effect. The macOS version of the control can toggle wordwrap on-the-fly.

Lua-supported (0.68).

TextToClipboard()

bool FCCtrlTextEditor::TextToClipboard

(

)

const

Copies the formatted text to the clipboard. This function differs from FCUI::TextToClipboard in that it includes all the font, color, and other text formatting in the control along with the text.

Several formats are copied to the clipboard, including plain text, RTF format, and Enigma string format. The receiver into which the user pastes determines which one to use.

Lua-supported (0.68)

Returns

true if copied, false if error or the window is not running