# wxStEditor

Copyright : 2006, John Labenski, Otto Wyss.
License : wxWindows license.
This library/program is free software; you can redistribute it and/or modify it under the terms of the wxWindows License; either version 3 of the License, or (at your option) any later version.
This library/program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the wxWindows License for more details.
If you use this program/library and find any bugs or have added any features that you feel may be generally useful, please feel free to contact the author by e-mail at jrl1[at]sourceforge[dot]net.

## Overview :

The wxStEditor is a library and sample program for the wxWidgets's wxStyledTextCtrl wrapper around the Scintilla text editor widget. This program is meant to be a demonstration of the wxStEdit library and has turned out to be a fairly capable syntax highlighting text editor with a number of advanced features.
What does the ST in wxStEditor stand for? Either styled text or Scintilla text, your choice.
The core for the editor was originally based on Otto Wyss's wxGuide editor.

## References :

http://wxcode.sourceforge.net
http://www.wxwidgets.org
http://www.scintilla.org
http://bakefile.sourceforge.net

## Features : (at a glance)

- Loading and saving text files as ASCII or Unicode
- Exporting as HTML, HTML w/ CSS, PDF, RTF, TEX, XML
- Printing with styling or as black & white
- Syntax highlighting for over 70 different programming languages or document types
- Rectangular selection, copy, and paste
- Various text tools

- Indent/Unindent blocks of lines
- Join/Split selected lines
- Tabs <--> Spaces
- Convert End Of Line (EOL) characters for DOS/Win, UNIX, Mac
- Remove trailing whitespace on save
- Columnize selected blocks of text

- Margins for line numbers, bookmarks, code folding
- View special characters, whitespace, and EOL chars
- Bookmarks
- Styles and colors for different text elements can all be changed
- Documents can be split vertically or horizontally to show two parts at once

## Running the Editor

The editor accepts a few command line options. In MS Window the options are /x while in UNIX they use -x, where 'x' is the option.

- -h : Show help on running the editor from the command line
- -1 : Run the editor in a single file mode
- -r [filename wildcards] : Recursively load file using wildcards

- Example : 'wxstedit -r *.h *.cpp' will load all files in the current and child directories that have the .h and .cpp extensions
- If it fails to load your files you may need to put double quotes (") around your filenames.

- -c [config filename] : Load the configuration options from the given file, if no file is given then do not load the configuration at all.

## Editors

You enter text in the editors as you would with any typical editor. A popup menu is shown by right clicking the mouse in the editor window, please review the "Menu Items" section for details.

## Key and Mouse Mapping

The keys used for editing are typical, arrow keys move around, page up/down to move by full pages. Some of the more specialized keys are shown below, other "hotkeys" are shown in the menu items of the editor.

- Selecting text : Hold down Shift when moving the cursor or drag the mouse with the left button down. Many of the accelerators below work with Shift key to quickly select blocks of text.
- Rectangular selection : Hold down Shift+Alt when moving the cursor or dragging the mouse
- Duplicate selection : Ctrl+D
- Move by full words

- Move to end of current word : Ctrl+Right arrow
- Move to start of current word : Ctrl+Left arrow
- Move to end of current word part : Ctrl+/
- Move to start of current word part : Ctrl+\

- Paragraph movement

- Move up a paragraph : Ctrl+[
- Move down a paragraph : Ctrl+]

- Move left by tabs : Shift+Tab
- Goto start of text : Ctrl+Home
- Goto end of text : Ctrl+End
- Goto start of display line : Alt+Home
- Goto end of display line : Alt+End
- Clear selection : Escape or left click the mouse in an unselected region of the editor.
- Cut : Ctrl+X or Ctrl+Delete
- Copy : Ctrl+C or Ctrl+Insert
- Paste : Ctrl+V or Shift+Insert
- Delete to word edge

- Shift+Backspace deletes word to left
- Ctrl+Delete deletes word to right

- Delete to text edge

- Ctrl+Shift+Backspace deletes line to beginning
- Ctrl+Shift+Delete deletes line to end

- Block (un)indentation

- Indent block : Select multiple lines and press Tab

- Undent block : Select multiple lines and press Shift+Tab

- Changing font size

- Increase font size : Ctrl+Numpad+

- Decrease font size : Ctrl+Numpad-

- Default font size : Ctrl+Numpad/

- Scrolling

- Scroll up : Ctrl+Up arrow
- Scroll down : Ctrl+Down arrow

- Line editing

- Line cut : Ctrl+L
- Line copy : Ctrl+Shift+T
- Line delete : Ctrl+Shift+L
- Line transpose (swap) : Ctrl+T

## Splitting Editors

The editors can be split vertically or horizontally to view two parts of the same document at once. You can edit in either part. There are menu items to do this in the "Window" menu or you can use the splitter buttons located on top of the vertical scrollbar or on the right of the horizontal scrollbar. To unsplit the editor just drag the splitter bar to the side so that that editor in the position you want to save takes the full window.

## Notebook

The notebook menu is accessed by right clicking the mouse on the notebook tabs. The items in this menu are fairly straightforward, please review the "Menu Items" section for details.
You can close a notebook page quickly by middle clicking on the tab you want to close.

## Menu Items :

Help is also given for the menu items in the statusbar. Note that menu items that end with "..." will popup a dialog which you can cancel to not take any action.

- ### File

- New... : Create a new empty document.
- Open... : Open a document from disk.
- Close current page : If you have multiple documents open, close the focused one.
- Close all pages... : Close all currently opened documents.
- Save : Save the currently focused document.

- If you try to save a document created using "New" you will be asked what name and directory to save it with as a precaution that you won't overwrite an existing file with the same name.

- Save as... : Save the currently focused document to a different filename.
- Save all : Save all opened documents if they have been modified.
- Export... : Export the document to a HTML, HTML w/ CSS, PDF, RTF, TEX, XML file.
- Document properties... : Show properties about the current document, filename, size, disk properties (if loaded/saved from/to disk), word count...
- Print... : Print the current document.
- Print preview... : Preview what the current document would look like if printed.
- Printer setup... : Setup the printer to use for printing.
- Printer page setup... : Setup the page properties for the printer.
- Printer options... : Options on how to print the document, colorized or not, font scaling, line wrap, line numbers.
- Exit : Exit the program, you will be asked to save any modified documents.
- Recent files : Recently opened files are stored in this list for easy access.

- ### Edit

- Cut : Cut the selected text to the clipboard.
- Copy : Copy the selected text to the clipboard.
- Copy primary : UNIX only, copy the selected text to the primary clipboard which you can typically use the middle mouse button to paste it with.
- Paste : Paste text from the clipboard at the cursor location. In Unix you can paste from the primary clipboard using the middle mouse button.
- Paste rect : Paste text from the clipboard at the cursor location, preserving the linefeeds in the text so that the left hand side always starts at the cursor column. Rectangular selection is made by holding down Shift+Alt while dragging with the left mouse button down or moving the cursor with the keyboard.
- Select all : Select all the text in the document.
- Line editing

- Line cut : Cut the current whole line to the clipboard.
- Line copy : Copy the current whole line to the clipboard.
- Line delete : Delete the current whole line.
- Line transpose : Swap the current line with the line above it.
- Line duplicate : Add another copy of the current line below the current line.

- Find... : Popup a dialog to find text with.
- Find next : Find the next occurrence of the last found find string.
- Search forward : Which direction to search next in, either up or down the page.
- Replace... : Popup a dialog to replace text with.
- Go to... : Goto a specific line in the document.
- Undo : Undo the last change made to the document.
- Redo : Redo the last undo.
- Readonly : Make the document readonly so that no changes can be made by typing.

- ### Tools

- Selection uppercase : Convert the currently selected text to all uppercase letters.
- Selection lowercase : Convert the currently selected text to all lowercase letters.
- Increase indent : Indent the selected lines by the indentation setting, see "Set indent width".
- Decrease indent : Unindent the selected lines by the indentation setting, see "Set indent width".
- Join selected lines : Make a number of selected lines into a single line.
- Split selected lines : Split selected lines or the current line at the "Long line guide column".
- Convert tabs to spaces : Convert tab characters into a number space characters set by "Set tab width". If no selection then convert only the current line, else the selected text.
- Convert spaces to tabs : Convert a number space characters set by "Set tab width" into tab characters. If no selection then convert only the current line, else the selected text.
- Convert EOL characters... : Convert the End Of Line characters for the whole document into the EOL characters for different operating systems.

- [CR = Carriage Return, LF = Line Feed] DOS/Win = CRLF, UNIX = LF, Mac = CR

- Remove trailing whitespace : Remove any whitespace, tabs or spaces, at the end of the current line if no selection or in the selected lines.
- Insert text... : Popup a dialog to automate inserting text into the document in a variety of ways.

- Prepend : Insert the text at the start of the selected lines or the current line.
- Append : Insert the text at the end of the selected lines or the current line.
- At column : Insert at a specified column of the selected lines or the current line.
- Surround selection : Insert text at the start and end of the selection of the selected lines or the current line.

- Columnize... : Popup a dialog to turn the selected lines, must be more than one, into equally spaced columns.

- Split before chars : Enter a list of characters to split the text into columns before.

- Example : '-' will break the text 'how-are you' into 'how -are you'

- Split after chars : Enter a list of characters to split the text into columns after.

- Example : '-' will break the text 'how-are you' into 'how- are you'
- If both split before and after are '-' the result is 'how - are you'

- Preserve matching : Enter a space separated list of characters to maintain the original formatting between.

- Example: '"" ()' will preserve the formatting and treat as a single column "quoted text" even if it has spaces and also (text between opening and closing parentheses).

- ### View

- Wrap text to window : Wrap the text in the document to fit in the window, the text itself isn't modified only how it's displayed.
- Show EOL : Show what characters are used for the End Of Line characters.
- Show whitespace : Show markings for whitespace characters like spaces and tabs.
- Guides

- Show indent guides : Show vertical lines set every "Set indent width" to denote indentation level.
- Show long line guides : Show a marker at the "Long line guide column", typically 80 so you know if you're beyond it.
- Long line guide column : Set the column to show a marker for long lines.

- Margins

- Show line number margin : Show the line numbers on the left hand side.
- Show marker margin : Show a margin for markers like bookmarks.
- Show folding margin : Show a margin for code folding. Some lexers for the programming languages allow for hiding or showing code between if...else...end statements for example. If you have this margin shown and have selected the appropriate language in the preferences, but no folding symbols appear then unfortunately it's not supported for that language.

- Folding

- Toggle current fold : Expand or collapse the fold on the cursor line if any.
- Collapse folds below level... : Hide all code that can be folded below this level.
- Expand folds above level... : Show all code that can be folded above this level.
- Collapse all folds : Hide all code that can be folded.
- Expand all folds : Show all folded code.

- Scale font size : Add or subtract the point size to the current size of the font. This is useful for temporarily increasing or decreasing the size. You can change it more permanently in the preferences dialog. Note that some fonts do not support all point sizes and so if you increment this and nothing happens, the font has reverted to one of the available sizes.
- Show fullscreen : Expand the window to take the size of the desktop, uncheck this to restore the original size.

- ### Bookmarks

- Toggle bookmark : Place or remove a bookmark for this line, see "Show marker margin".
- First bookmark : Go to the first bookmark in the document.
- Previous bookmark : Go to a bookmark higher up in the document than the cursor line.
- Next bookmark : Go to a bookmark after the cursor line.
- Last bookmark : Go to the last bookmark in the document.
- Clear all bookmarks : Remove all bookmarks in the current document.

- ### Preferences

- Show preferences dialog... : Show a dialog to set a variety of preferences for the editor. See the "Preferences Dialog" section of this document.
- Use tabs : The tab key inserts a tab character instead of spaces, see "Set tab width".
- Tab indents : The tab key indents to the "Set indent width" instead of a fixed tab width.
- Backspace unindents : If indented, the backspace key moves to the previous indentation level instead of back a single space.
- Auto indent : When pressing enter, the next line is indented to the previous line's indentation level.
- Set tab width : Set the number of spaces to show for tab characters or to insert for a tab character. Tab characters are typically eight characters, but sometimes that's too wide.
- Set indent width : Set the number of spaces to show for the indent level or to use for indentation.
- EOL Mode : Set what End Of Line characters to use from this point on, see "Convert EOL characters..." to change the mode for whole document.
- Save preferences : Save the currently selected preferences. When you have the editor setup in a way that you'll be using it most often you should save your preferences and it will always start in that state. The editor does not save the preferences every time you exit to preserve your "default" settings.

- ### Window

- Unsplit editor : If the current editor is split, then return it back to a single pane.
- Split editor horizontally : Divide the current editor horizontally, you can edit in both parts.
- Split editor vertically : Divide the current editor vertically, you can edit in both parts.
- Show sidebar : Show a listbox of the currently opened files to make switching between them easier.
- Previous page : Go to the previous page in the notebook.
- Next page : Go to the next page in the notebook.
- Windows... : Show a dialog to select a different page in the notebook or to save the selected pages.

- ### Help

- About... : A simple about dialog.
- Test STE Shell... : Just for programmers, this demonstrates a "shell" type widget that the wxStEditor library provides for use as a console type widget, like a DOS prompt. This demo does nothing "useful".

## Preferences Dialog

The preferences dialog allows you to change a variety of preferences for the editor.

- ### View

- Font scaling : Add or subtract the point size to the current size of the font. This is useful for temporarily increasing or decreasing the size. You can change it more permanently in the preferences dialog. Note that some fonts do not support all point sizes and so if you increment this and nothing happens, the font has reverted to one of the available sizes.
- Edge marker : A "Long line marker" can be set at any column to mark it to aid in formatting your text. The marker can either be a vertical line or text beyond the line can be highlighted with the "Edge style" foreground color.
- Margins : Show or hide the line and marker margins, see "Folding and Wrapping" for code folding margin.
- Cursor

- You can choose to highlight the background of the whole line that the cursor is on using the "Caret color" style.
- Set the width and blinking rate of the cursor, set the blinking period to 0 turn blinking off. Note 1000 milliseconds = 1 second.

- ### Tabs and EOL

- These topics are covered in "Menu Items" under "Preferences".

- ### Folding and Wrapping

- Show code folding margin : Show a margin to hide/show code between if...else...end statements for example.

- Compact : Also fold in the empty lines.
- Comment : Allow folding of block (multiline) comments.
- Preprocessor : Allow folding of preprocessor statements if the programming language selected has them.
- At "else" : Add another fold marker at "else" statements instead of just at the toplevel "if" statement.
- HTML : Allow folding for HTML.
- HTML preprocessor : Allow folding for HTML preprocessor code.
- Directive : Allow folding of directive lines in POVray.
- Python comment : Allow folding of python comments.
- Python quote : Allow folding of quoted text in python.
- Python index : Allow folding of indented text in python.

- Fold margin style : A variety of symbols sets to use for marking folded lines, choose the one you like.
- Wrap text to window : Wrap the text in the document to fit in the window, the text itself isn't modified only how it's displayed.

- Marker position : Where put to the marker to indicate that the line has been wrapped.
- Marker style : How to mark the line to indicate that it's been wrapped.
- Indent wrapped : How many spaces to indent wrapped lines.

- ### Printing

- Setup how the document is to be printed.
- Note about font scaling : See also the note in "View - Font scaling". If the printing layout detects that the currently used font is not scaled to the calculated value a dialog is shown to warn you that the layout may not be correct. In some cases you can ignore this warning since the font is nearly scaled correctly and the result will look ok, in other cases it may be necessary to choose a different font in the "Styles" tab that can be scaled correctly for the printout.

- ### Loading and Saving

- Set language highlighting from file extension : When loading a file try to detect the file type from the extension and choose the appropriate language to use. See "Languages" tab.
- Load Unicode : When loading files "default" means try to detect if the file is Unicode and load it as such, else you can have it ask what to do, always load files as ASCII, or always load files as Unicode.
- Remove trailing whitespace : When saving always remove any extra whitespace at the end of lines to "clean up" the document.
- Convert all EOL characters : When saving always convert all EOL characters to the currently set EOL character, see "Tabs and EOL" tab, to "clean up" the document.

- ### Highlighting

- Enable syntax highlighting : Highlight (colorize) the document based on the currently selected language.
- Highlight preprocessor code : If the selected language supports preprocessor code, highlight it.
- Highlight braces : When editing and moving the cursor around hilight matching and mismatched braces using the "Brace hilight" and "Brace mismatch" styles.
- Set language highlighting from file extension : See "Loading and Saving".

- ### Styles

- This editor supports syntax highlighting for a number of different programming languages. In order to make it easy to create your own color and style theme, a single generic list of styles is used. This is because some languages have rather esoteric idioms and if this editor catered to each and every one there would be hundreds of different styles to have to adjust. The list tries to encompass most of the common styles for all the language lexers (code parsers). Therefore, the names given to the styles are meant only as hints as to what the style will be used for and you can map any editor style to any lexer style. For more information you should examine the "Languages" tab where you can change the mapping of the editor and lexer styles.
- Select the style you want to change by clicking on the margin or double clicking the line. You can change the individual attributes for a style by checking the checkboxes to the left or uncheck them to use the attribute value from the "Default Style" in the "Lexer Styles". It is a good idea to set the "Default Style" first so that you only set the values for the other styles that you want to be different. Attributes that do not apply for specific styles are disabled.
- The "Editor Colors" page allows you to change the overall appearance of the editor for any language.
- The "Lexer Styles" page shows a list of styles to allow you to adjust them all at once to easily create a theme that'll look good for any language. You can also select particular languages to see what styles they use and get a feel for what they would look like. The styles that are used for the currently set lexer in the "Languages" tab are shown with a white cross in the margin.

- ### Languages

- Language : Choose a language to highlight the current document with.
- File patterns : A semicolon ';' separated list of file patterns to use to detect what language to use for that type of file.

- Example : "*.c;*.cpp;*.h" for C/C++ will treat any file name that ends with .c, .cpp, or .h as a C/C++ file.

- This editor supports syntax highlighting for a number of different programming languages. Choose the language lexer you want to use for the current document using the "Language" choice control. The file patterns are a semicolon ';' separated list of file patterns to detect what language to use for different file types. For example; C/C++ has the patterns '*.c;*.cpp;*.h' which means that files ending with .c, .cpp, .h will be lexed using C/C++ programming language.
- The "Styles" tab allows you to change the mapping between the editor styles on the left and the lexer styles on the right. See the overall "Styles" tab to adjust the look of the editor styles and to learn about the names given to the editor styles. Use the "Choose style" choice control to select a different editor style, note that the names of the editor styles are just hints for what they're most used for and can be arbitrarily mapped to any lexer style. Select a different lexer style to modify by clicking on the margin or double clicking on the appropriate line.
- The "Keywords" tab allows you to view the special keywords for the language. Different languages may have different numbers of keyword sets and each one can be given their own styling. You may add your own additional keywords by entering them as a space separated list into the "Additional keywords" text control.