Finale PDK Framework 0.71
Classes | Public Types | Public Member Functions | List of all members
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:
FCControl __FCBase

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_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. More...
 
 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. More...
 
int GetLineForPosition (int pos) const
 Returns the 1-based line number for the specified character position. More...
 
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. More...
 
bool GetLineRangeForLine (int line, FCRange *pRange) const
 Returns the range of the specified line (1-based). More...
 
FCRangesCreateLineRanges (const FCRange *pRange=nullptr) const
 Returns FCRanges for all lines that overlap the specified range. More...
 
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. More...
 
bool GetSelection (FCRange *pRange) const
 Gets the selected range on the control. More...
 
bool SetSelection (const FCRange *pRange)
 Sets the selected range on the control. More...
 
bool SelectAll ()
 Selects the entire text. More...
 
bool GetTextInRange (FCString *pText, const FCRange *pRange) const
 Gets the text on the control corresponding to the input range. More...
 
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. More...
 
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. More...
 
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. More...
 
bool GetSelectedText (FCString *pText) const
 Gets the selected text on the control. More...
 
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. More...
 
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. More...
 
void AppendText (const FCString *pText)
 Appends the input string to the end of the text on the control. More...
 
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. More...
 
FCStringCreateRTFString () 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. More...
 
FCStringCreateEnigmaString (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. More...
 
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. More...
 
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. More...
 
FCFontInfoCreateFontInfoAtIndex (int index) const
 Returns the font information at a specific 0-based index. More...
 
bool SetFontInRange (const FCFontInfo *pFont, const FCRange *pRange)
 Sets the font for a specified range of text in the control. More...
 
bool SetFontForSelection (const FCFontInfo *pFont)
 Sets the font for the currently selected range of text in the control. More...
 
bool SetFontSizeInRange (int size, const FCRange *pRange)
 Sets the font size for the specified range without modifying other font formatting. More...
 
bool SetFontSizeForSelection (int size)
 Sets the font size for the currently selected range of text in the control. More...
 
bool SetFontBoldInRange (bool state, const FCRange *pRange)
 Sets the font bold for the specified range without modifying other font formatting. More...
 
bool SetFontBoldForSelection (bool state)
 Sets the font bold for the currently selected range of text in the control. More...
 
bool SetFontItalicInRange (bool state, const FCRange *pRange)
 Sets the font italic for the specified range without modifying other font formatting. More...
 
bool SetFontItalicForSelection (bool state)
 Sets the font italic for the currently selected range of text in the control. More...
 
void SetReadOnly (bool readonly)
 Sets the edit text field to be read-only or editable. More...
 
bool GetReadOnly () const
 Gets the current read-only state of the edit text field. More...
 
void SetWordWrap (bool wordwrap)
 Sets the edit text field to wrap or to have horizontal scrollers and not wrap. More...
 
bool GetWordWrap () const
 Gets the edit text field's setting to wrap or to have horizontal scrollers and not wrap. More...
 
void SetUseRichText (bool state)
 Sets the control's Rich Text state. See comments at GetUseRichText for more information about this setting. More...
 
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. More...
 
void SetAutomaticEditing (bool state)
 Sets whether the control should use automatic editing features. More...
 
bool GetAutomaticEditing () const
 Sets whether the control should use automatic editing features. More...
 
void SetTabstopWidth (double value)
 Sets the tabstop width. More...
 
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. More...
 
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. More...
 
bool GetAutomaticallyIndent () const
 Gets whether to automatically indent to the same tab level when hitting the Enter key. More...
 
void SetAutomaticallyIndent (bool state)
 Sets whether to automatically indent to the same tab level when hitting the Enter key. More...
 
FCRangesCreateRangesForString (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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
bool ResetColors ()
 Resets text and background colors to their default system colors for the entire control. More...
 
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. More...
 
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. More...
 
FCRangesCreateTextColorChanges () const
 Returns an FCRanges collection containing the range in the text where the color changes. More...
 
FCRangesCreateBackgroundColorChanges () const
 Returns an FCRanges collection containing the range in the text where the background color changes. More...
 
int GetNumberOfLines () const
 Returns the number of lines of text currently displayed in the control. More...
 
double GetVerticalScrollPosition () const
 Gets the current vertical position of the scrollbar. More...
 
void ScrollToTop ()
 Scrolls the control to show the first character of text. More...
 
void ScrollToBottom ()
 Scrolls the control to show the last character of text. More...
 
void ScrollToVerticalPosition (double vpos)
 Scrolls the control to the speficied vertical position. More...
 
void ScrollLineIntoView (int line)
 Scrolls the control so that the specified line comes into view. More...
 
double GetLineSpacing () const
 Returns the distance in points between the bottom of one line and the top of the next. More...
 
void SetLineSpacing (double value)
 Sets the distance in points between the bottom of one line and the top of the next. More...
 
FCStringCreateCharacterAtIndex (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. More...
 
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. More...
 
- Public Member Functions inherited from FCControl
 FCControl (twobyte id, const __FCControlTypedPtr &subclassPtr)
 The constructor. More...
 
 FCControl (twobyte id)
 The constructor for external C++ subclasses. More...
 
virtual ~FCControl ()
 Destructor.
 
bool GetPointsMeasurement ()
 Returns if the measurements and positioning is in points or in a system-native unit. More...
 
__FCUserWindowGetParent () 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. More...
 
int GetControlID () const
 Returns the control ID for the control. More...
 
int GetAssignedID () const
 Gets the connected ID regardless of platform. More...
 
CONTROL_ACTIONS GetAction () const
 Returns the dialog acction assigned to the control. More...
 
void SetAction (CONTROL_ACTIONS action)
 Sets the dialog acction assigned to the control. More...
 
virtual void SetEnable (bool state)
 Sets the enable/grayed state of the control (if user input should be allowed or not). More...
 
virtual bool GetEnable () const
 Returns the enable/grayed state of the control (if user input should be allowed or not). More...
 
virtual void SetVisible (bool bShow)
 Sets the visibility of the control. More...
 
virtual void SetBold (bool state)
 Sets the boldface appearance for the control. More...
 
virtual void SetFont (const FCFontInfo *fontInfo)
 Sets the font information for the text of the control. More...
 
virtual FCFontInfoCreateFontInfo () const
 Creates font information from the current text font of the control. More...
 
virtual void SetKeyboardFocus ()
 Sets the keyboard focus to the control. More...
 
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. More...
 
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. More...
 
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 alignment options. More...
 
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 alignment options. More...
 
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. More...
 
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. More...
 
void StretchToAlignWithRight ()
 Sets a control to stretch its width to align with the furthest right control. More...
 
virtual void SetText (const FCString *pString)
 Sets the text for the control. More...
 
virtual void GetText (FCString *pString) const
 Gets the text of the control. More...
 
void SetLeft (float pos)
 Sets the left position of the control. More...
 
float GetLeft ()
 Returns the left position of the control. More...
 
void SetTop (float pos)
 Sets the top position of the control. More...
 
float GetTop ()
 Returns the top position of the control. More...
 
float GetHeight ()
 Returns the height of the control. More...
 
float GetWidth ()
 Returns the width of the control. More...
 
bool GetVisible ()
 Returns the visibility state of a control. More...
 
void SetWidth (float width)
 Sets the width of the control. More...
 
void SetHeight (float height)
 Sets the height of the control. More...
 
void MoveRelative (float horizmove, float vertmove)
 Moves the control relatively to the current position. More...
 
void MoveAbsolute (float x, float y)
 Moves the control in absolute coordinates. More...
 
virtual void ResizeRelative (float horizresize, float vertresize)
 Resizes the control relatively to the current size. Top left corner will stay fixed. More...
 
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. More...
 
- 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. More...
 
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. More...
 
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. More...
 
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. More...
 
void DebugMsg (const char *pszMsg)
 Creates a simple Message Box for debug purposes with just one text string. More...
 
void DebugOutMenuInfo (FCUI *pUI, int menuixd_horiz, int menuixd_vert) const
 Outputs the menu command info for debugging purposes. More...
 
int DebugOutFormat (const char *fmt,...)
 Outputs debug text using C style "printf" syntax. More...
 
virtual void DebugDump ()
 Outputs the class data/information for debugging purposes. More...
 
virtual void DebugDataDump ()
 Outputs a memory dump of the data block in the object for debugging purposes. More...
 
virtual void DebugDataByteArrayDump ()
 Outputs a memory dump of the data block in the object for debugging purposes, as a C++ byte array. More...
 
void Set16BitFlag (FLAG_16 *flag, FLAG_16 flagbits, bool state)
 Sets a 16 bit flag. More...
 
void Set32BitFlag (FLAG_32 *flag, FLAG_32 flagbits, bool state)
 Sets/resets a 32 bit flag, by using a bit mask. More...
 
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. More...
 
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. More...
 
void SetUserData (void *pData)
 Sets the user data attached to the instance of an object. More...
 
void SetUserData2 (void *pData)
 Sets the additional user data attached to the instance of an object. More...
 
void * GetUserData () const
 Gets the user data attached to the instance of an object. More...
 
void * GetUserData2 () const
 Gets the additional user data attached to the instance of an object. More...
 
virtual bool IsIdentical (__FCBase *pCompareObject)
 Returns true if the data in the passed object is considered to be identical to the current object, otherwise false. More...
 
void StoreXML_String (tinyxml2::XMLElement *pParentNode, const char *pszElementName, FCString *pStringValue)
 Helper function to store FCString objects in the XML file. More...
 
void StoreXML_Integer (tinyxml2::XMLElement *pParentNode, const char *pszElementName, int value)
 Helper function to store integer objects in the XML file. More...
 
void StoreXML_Bool (tinyxml2::XMLElement *pParentNode, const char *pszElementName, bool value)
 Helper function to store boolean objects in the XML file. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
virtual void StoreToXML (tinyxml2::XMLElement *pParentNode)
 Virtual method that is used to store an object's data. More...
 
bool ReadXML_String (tinyxml2::XMLElement *pParentNode, const char *pszElementName, FCString *pStringValue)
 Helper method to read FCString objects from the XML file. More...
 
bool ReadXML_Integer (tinyxml2::XMLElement *pParentNode, const char *pszElementName, int *pValue)
 Helper method to read integer objects from the XML file. More...
 
bool ReadXML_Bool (tinyxml2::XMLElement *pParentNode, const char *pszElementName, bool *pValue)
 Helper method to read boolean objects from the XML file. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
virtual bool ReadFromXML (tinyxml2::XMLElement *pParentNode)
 Virtual method that is used to read object data. More...
 

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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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. More...
 
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". More...
 
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. More...
 
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. More...
 
static void DebugOut (const char *pszLine)
 Static method to output a line of text for debugging purposes. More...
 
- 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

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
pos0-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
index0-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
pSearchStringThe string to search for.
optionsAny 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
indexthe 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
posthe 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
linethe 1-based line number to find.
pRangethe 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
posthe 0-based character position within the text.
pRangethe 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
pTextreceives 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
pRangereceives 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
indexthe 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
pTextreceives the text.
pRangethe 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
pRangereceives 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
pTextthe 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
pTextthe 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
pTextthe text that replaces the selection.
pRangethe 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
pRangethe 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
pRangethe 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
linethe 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
vposos-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
reda value from 0-255.
greena value from 0-255.
bluea value from 0-255.
pRangethe 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
pStringthe 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
statetrue 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
statetrue turns on bold and false turns it off
pRangethe 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
pFontthe 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
pFontthe font information to use.
pRangethe 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
statetrue 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
statetrue turns on italic and false turns it off
pRangethe 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
sizethe 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
sizethe new font size in points.
pRangethe 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
valueline 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
pStringthe 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
pRangethe 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
valueThe 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
reda value from 0-255.
greena value from 0-255.
bluea value from 0-255.
pRangethe 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