NZ Text Editor

This version is a big ugly but at least it't up-to-date. The documentation below was copied out of XSTC 7.2 I will be cleaning it up soon, but its more useful at least having the docs availible even if they are a mess.

XSTC is a wrapper for wxScintilla and wxStyledTextCtrl. It manages most of the coloring options within Scintilla for you and supports configuration files. All settings that XSTC looks up are assumed to be strings, only a small number of them only handle a numeric value, many support two ways to define a value. for example a boolean can be a word or a number.

a set of bookmarks is managed, one for clicking on the margin, 10 are activated by keyboard. the keyboard markers will only allow one instance at a time per marker. folding is managed automatically as well as lexer properties and keywords. two utility functions also exist, one for converting spaces to tabs or tabs to spaces and the other for trimming whitespace. a few behavioral settings are managed by XSTC that deal mainly with appearance of the editor. word wrap, whitespace visibiity and a few others. also EOL mode is set in the constructor and paste convert line endings is set to true. The idea is that XSTC can make the tedious part of building an editor especially with Scintilla much easier. with just a few lines of code in your application Scintilla will magically be ready for use, however it may not be for everyone depending on your needs.

A port of XSTC to generically work directly on top of Scintilla is under way. This will allow for XSTC to be used on platforms and toolkits that Scitilla supports and you will not be stuck with wxWidgets. There are a few things that must be changed for that to work however. events are platform specific, so you will have to call the brace matching/folding/numbered bookmark functions yourself. also a couple of callback functions for converting strings to and from utf8 that scintilla understands to the appropriate type for your application. also the scintilla message proc may not be directly avialible so that will need to be set up as well, if the message proc is availible for direct calling that would work too.



getting a simple editor ready for use:
XSTC *editor = new XSTC(parentwin, wxID_ANY, wxPoint(0, 0), wxSize(200, 150), 0, wxT("myeditorwin"));

if creating using wxSidgets RTTI Create() only calls on wxScintilla's constructor, in order to initialize the document like the creation constructor does call AfterCreate() immediatly before doing anything with the editor and everything will be ready to go. the events are connedted in that function, if you don't call it XSTC will be broken.

using configuration settings:
a default wxColourDatabase is created automatically but SetColorDbase() allows you to replace the intance XSTC uses to look up name strings so custom names will work. any names loaded from the config database will be converted to html color strings before calling StyleSetSpec().

SetConfigObj() passes a handle of your wxConfig instance to XSTC so that config based coloring will work. all built in themes will still work correctly without it.

SetColorDbaseD()
SetConfigObjD()
both functions are a variation of the above that delete the current object rather than NULLing it when replacing the handle.

theme functions:
DarkStyle()
VisualStudioStyle()
BorlandStyle()
JeffStyle()
ZenburnStyle()
MatrixStyle()


each of these sets up coloring for a consistent look across all languages. they also support loading settings from configs if XSTC has a handle to your wxConfig instance. they have a place in the config based theme section and like the config based themes fall back on the global colors if the theme style(s) are missing. then the hardcoded settings are used. if the configs are shut off the hard coded settings are used no matter what.

ConfigStyle() loads a theme that is defined in the config database, it accepts the internal names of the built in themes and will call the respective theme function if one of those names is passed to it, otherwise it will try to load from the theme section and fall back to config globals then the iitial editor state settings.

GetConfigThemes() loads a wxArrayString of theme names in configs. this settings is not essential, but is a simple way to check what themes are present. it may hold the built in theme names which will not hurt anything if those are passed to ConfigStyle(). XSTC does not enumerate any settings so this is a simple way for the user to get the theme selection.

ResetStyles() this resets the editor to its default state

FoldConfig() will load settings for the fold margin symbols
MarkerConfig() will load colors for the bookmarks and the mouse bookmark shape
ResetMarkers() will apply any manual changes you make to the state variables

SetBraceColors() this allows you to define one color per brace type and a single bad style (no matching brace)
<> () [] {} are the supported braces

SetLexerX() sets the lexer to use and calls the lexcolor function that handles the styles for that lexer
LexCPP() for example handles setting all colors for the cpp lexer using the theme settings, it also has support for loading styles from configs as do all lexcolor functions.
SetLexerX() also loads keywords if there is a config database and the flag is set to true it will load lexer properties as well if the properties flag is set to true

XSTC flags:
use_lexer_ext if true this will tell XSTC to try to look for extensions in configs, the lexer can be defined and a language which allows for setting lexer styles, properties and keywords, if the extension is not present in configs none of those will work
use_coloring all config based coloring will be disabled if this is false, also the few noncoloring states like wrapping and right edge column will not load either.
use_props if true lexer properties will be loaded if the extension is defined. either the extension or a language it maps to must have the properties
use_keys if true the keywords defined in the language sectin will be loaded, they will not load from the extension area like properties will

XSTC manager variables:
bk_mark_outline if true it will reverse the foreground and background colors to create a bookmark that looks outlined
bk_mark_shape holds the mouse bookmark shape, this can be applied by changing the cariable then calling ResetMarkers()
bk_mark_color mouse bookmark color
mark_bg_color background color for both the mouse and numbered bookmarks
num_mark_color numbred bookmarks foreground color, these bookmarks are not affected by bk_mark_outline
foldfg_clr these two are generic color settings for the fold margin symbols, the only way to set eash style seperatly is by calling
foldbg_clr FoldConfig() which will in also load settings for these.
folded_line mode for the line that appears after folding a block of text
trim_spaces a flag that tells XSTC whether to call TrimWhite() in SaveFileX()
trim_mode mode for TrimWhite()
space_convert mode for TabSpace(), can be off
tab_spaces number of spaces to equal a tab
brace_line if true which is the default the fold block that the caret is in will be lighlighted
color_style name of the theme in use
edge_color right edge column colot
edge_column the column in characters to set the right edge column
edge_mode mode for diaplaying the right edge column
wrap_mode mode for wordwrap
wrap_vflags mode for wrapping visual flags, a small arrow that appears in the margins
cache_mode document color caching mode
caret_line_hilite flag telling XSTC whether to show the caret line background in a different color (hilighted)
alphalvl geneic alpha blending level, if a setting is not loaded in configs this is used
breakpoint_color active_breakpoint_color error_line_color these are colors managed by the themes, thay are not used by XSTC
but may be useful in some way. they are named after IDE breakpoint and error line settings but you can use them as you see fit.



the following functions set the symbols in the folding margin, they are shape scemes. using them makes the symbol defining easy, you can change up a few symbols right after calling it if you wish, like everything in XSTC they are here for convienience.
FoldBox()
FoldCircle()
FoldArrow()
FoldSimple()


to get a lexer number call one of these
GetLexerByName()
LexerByEXT some extensions are defined in the function, if extension lookup is active then it will check for them in configs before looking at the built ins, it will return a -1 if nothing matches so you can decide how to proceed

these three functions handle converting string color representation
ConvertColor() string to color, any of the 3 string formats supported by wxColour
ConvertColorStr() changes a string to another format
StylePreSpec() changes any rgb triplets or name strings to html type for StyleSetSpec so that the coloring will always work

two utility functions trim whitespace and convert tabs to spaces and vice versa
TrimWhite()
TabSpace()

config database layout:
all global settings have been moded into the /GLOBAL directory
/XSTC/COLOR/GLOBAL/
themes are all placed under this directory
/XSTC/COLOR/COLORSTYLE/
the theme name would be next in the path string and all settings then would be defined under it
for properties, extensions, keywords:
/XSTC/EXT/[file extension]/LANGUAGE this hold a setting naming a language, the language can manage several extensions
/XSTC/EXT/LANG/[file extension]/LEXPROPS/
XSTC/EXT/LANG/[language name]/LEXPROPS/
both of the above directories are valid locations to set properties, the lang location takes precidence
/XSTC/EXT/LANG/[file extension]
XSTC/EXT/LANG/[language name]
the lexer can be set in either location, however it makes no sense to have a different lexer set in both
LEXER= this setting will define the lexer, either a string name that XSTC recognises or the integer representing it
XSTC/EXT/LANG/[language name]/KEYWORDS/
the above is the path for keywords, up to 9 sets are supported by some lexers the sceme is as follows:
KEY0= list of space delimited keywords is defined here
KEY0_FILE list of coma delimited file names is defined here
the number suffix incriments for each keyword set, 8 being the highest number


for folding and marker colors the global path is used

for now you will need to check the sources for the exact key names, I will be making a comprehensive list.

other notes:
when using numbered bookmarks
CTRL+number 0-9 will add a bookmark to the current line unless it is defined elsewhere, then it will delete that one doing it again will then add the marker to the current line
ALT+number 0-9 will jump to the numbered bookmark
only 1 numbered bookmark will exsist in the document

LoadFileX() will call SetLexerX()
SaveFileX() will call TrimWhite() and TabSpace()
CloseFile() will reset the editor
the three of these functions make the automation of setting things up very easy but are not essential, if you need more control call on the respective functions as you need.

a callback based keywords setting function is availible, you fill a Keywords_Set structure yourself in the callback function you can also turn off use_keys and handle all keywords manually