]>

# The KWrite Handbook

Thad
McGinnis

    jamcgin@racsa.co.cr

Jochen
Wilhelmy
Principal Developer

    digisnap@cs.tu-berlin.de

Glen
Parker
Additional Development

    glenebob@nwlink.com

Michael
Koch
Additional Development

    koch@kde.org

Christian
Tibirna
Original Help Document

    tibirna@kde.org

Lauri
Watts
Reviewer

    vampyr@atconnex.net

26/05/2000
1.0.0

This handbook describes KWrite Version 1.0.0

&kwrite; is a text editor for KDE 2.0

KDE
KWrite
text
editor
2000
Thad McGinnis

## Introduction

&kwrite; is more than a text editor for the KDE Desktop. It is meant to be a programmer's editor, and could be considered as at least a partial alternative to more powerful editors. It may be best used in conjunction with Konqueror for source file browsing for different languages. &kwrite; also works very well as a simple text editor. One of &kwrite;'s main features is the colorized syntax, customized for many different programming languages such as: C/C++, Java, Python, Perl, Bash, Modula 2, HTML, and Ada.

### Installation

&kwrite; is packaged as part of the kdeutils package. For more information on installing and compiling KDE please see www.kde.org.

## Some Fundamentals

&kwrite; is very simple to use. Anyone that has used a text editor should have no problems.

### Drag and Drop

&kwrite; uses the KDE Drag and Drop protocol. Files may be dragged and dropped onto &kwrite; from the Desktop, Konqueror, or some remote ftp site opened in one of Konqueror's windows.

### Command Line Options

Though &kwrite; may most often be started from the KDE program menu, or a desktop icon, it can also be opened at the command line prompt of a terminal window. There are a few useful options that are available when doing this.

#### Specify a File

By specifying the path and name of a particular file the user can have &kwrite; open (or create) that file immediately upon startup. This option might look something like the following:

    % kwrite /home/myhome/docs/myfile.txt

#### Specify a file on the internet

The above-mentioned method could even be used to open files on the internet (if the user has an active connection at the time.) An example of this might look like the following:

    % kwrite ftp://ftp.kde.org/pub/kde/Welcome.msg

#### Other Command Line Options

The following command line help options are available

`kwrite `--help``

  This lists the most basic options available at the command line.

`kwrite `--help-qt``

  This lists the options available for changing the way &kwrite; interacts with Qt.

`kwrite `--help-kde``

  This lists the options available for changing the way &kwrite; interacts with KDE.

`kwrite `--help-all``

  This lists all of the command line options.

`kwrite `--author``

  Lists &kwrite;'s authors in the terminal window

`kwrite `--version``

  Lists version information for Qt, KDE, and &kwrite;. Also available through `kwrite `-V``

### Key Bindings

Many of the key bindings (shortcuts) are configurable by way of the Settings menu. By default &kwrite; honors the following key bindings.

Insert | Toggle between Insert and Overwrite mode. When in insert mode the editor will add any typed characters to the text while pushing along any data to the right of the text cursor. Overwrite mode causes the entry of each character to eliminate the character immediately to the right of the text cursor.
Left Arrow | Move the cursor one character to the left
Right Arrow | Move the cursor one character to the right
Up Arrow | Move the cursor up one line
Down Arrow | Move the cursor down one line
Page Up | Move the cursor up one page
Page Down | Move the cursor down one page
Backspace | Delete the character to the left of the cursor
Home | Move the cursor to the beginning of the line
End | Move the cursor to the end of the line
Delete | Delete the character to the right of the cursor (or any selected text)
ShiftLeft Arrow | Mark text one character to the left
ShiftRight Arrow | Mark text one character to the right
AltB | Set Bookmark
F1 | Help
ShiftF1 | What's this?
CtrlF | Find
F3 | Find again
CtrlC | Copy the marked text to the clipboard.
CtrlN | New document
CtrlP | Print
CtrlR | Replace
CtrlW | Close - close active copy of editor
CtrlQ | Quit - close active copy of editor
CtrlV | Paste the clipboard text into line edit.
CtrlX | Delete the marked text and copy it to the clipboard.
CtrlZ | Undo
CtrlShiftZ | Redo

## The Menu Entries

### The File Menu

CtrlN File New

  This starts a new Document in the editor. If there is a current document with unsaved changes the user is given a chance to save it.

CtrlO File Open

  This command opens a file. It does this by means of a dialog box which allows the user to navigate the file system. The dialog operates like a small file manager. Double clicking on directories displayed in the central window directs the dialog to enter that directory - displaying its contents. There is an entry/dropdown box which can be used to type in directly the location and name of the file or by clicking the arrow at the side choose from a dropdown list of recently used locations. Below this is a filter which similarly may have data entered directly or chosen from a dropdown list of recent filter types. The filter facility lets only files that meet its specifications be displayed in the central window. If the filter contained text such as '`*.txt`' then only files with the txt extension would be visible in the selection window. The toolbar has left and right arrow buttons that let the user move back and forth through previously selected directories as well as an up arrow button for moving up the directory tree. The button with the little house takes the user to his or her home directory and the one with the two arrows curved in on each other updates the view of the current directory. The flag button lets the user set a new bookmark at the current directory or go to one that was previously set. The button with the wrench (spanner) icon even permits the user to change a few basic settings for the dialog box. Finally there is dropdown box on the toolbar with a list of some commonly frequented directories.

File Open Recent

  This is a shortcut to open recently saved documents. Clicking on this item opens a list to the side of the menu with a list of several of the most recently saved files. Clicking on a specific file will open it in &kwrite; - if the file still resides at the same location.

CtrlS File Save

  This saves the current document. If there has already been a save of the document then this will overwrite the previously saved file without asking for the user's consent. If it is the first save of a new document the save as dialog (described below) will be invoked.

File Save As

  This allows a document to be saved with a new file name. This is done by means of the file dialog box described above in the Open section of this help file.

File Revert

  This will reload the last saved instance of the current document. Any changes made since the last save will be lost - with the document reverting to its previous state.

CtrlP File Print

  Opens a simple print dialog allowing the user to specify what, where, and how to print

File New Window

  This creates a new window, i.e., a new instance of &kwrite;. In this way the user can easily work on more than one file at a time with &kwrite;.

File New View

  This creates a new view of the current document, i.e., a new instance of &kwrite; (as explained in the previous entry) but containing the same document.

CtrlW File Close

  This will close the editor window, if you have more than one instance of &kwrite; running, through the New View" or "New Window" menu items, those instances will not be closed.

CtrlQ File Quit

  This closes KWrite.

### The Edit Menu

CtrlZ Edit Undo

  This is used to eliminate or reverse the most recent user action or operation. Just what constitutes such an action may be better understood by referring to the Group Undos portion of this help file.

CtrlShiftZ Edit Redo

  This will reverse the most recent change (if any) made using Undo

Edit Undo History

  This will call a display box showing a list of the most recent actions on the left and another list of actions which have been 'undone' on the right. There are also three buttons at the right of the box labeled Undo, Redo, and Close. Clicking on the Undo button will cause the action at the top of the Undo list to be reversed which will place that particular action at the top of the Redo list. Likewise, clicking on the Redo button will reinstate the reversed action and move it back to the top of the Undo list. Clicking on an item below the top item in either list will select all the items from the top down to that point. A subsequent click on the corresponding button will cause all the selected actions to be undone or redone accordingly. This would be particularly useful when the user knows precisely the point to which she or he would like to proceed - making it unnecessary to go through a series of single undo or redo actions.

CtrlX Edit Cut

  This command deletes the current selection and places it on the clipboard. The clipboard is a feature of KDE that works invisibly to provide a way to transfer data between applications.

CtrlC Edit Copy

  This copies the currently selected text to the clipboard so that it may be pasted elsewhere. The clipboard is a feature of KDE that works invisibly to provide a way to transfer data between applications.

CtrlV Edit Paste

  This will insert the contents of the clipboard at the cursor position. The clipboard is feature of KDE that works invisibly to provide a way to transfer data between applications.

Tools Indent

  This increases the paragraph's indentation by one step. The size of the step depends on the indentation settings.

Tools Unindent

  This reduces the paragraph's indentation by one step. The size of the step depends on the indentation settings.

Tools Clean Indent

  Not yet implemented

Edit Select All

  This will select the entire document. This could be very useful for copying the entire file to another application.

Edit Invert Selection

  This selects any unselected text while unselecting any selected text - effectively reversing the current state of selection.

### The Search Menu

CtrlF Edit Find

  This opens the find dialog which is used to specify the Text to Find in the document. There is small text box for entering the search pattern which also doubles as a dropdown box. Clicking on the dropdown arrow at the side of the box makes available other recent search patterns. Other parameters are included to make the search more efficient. Selecting Case Sensitive will limit finds to entries that match the case (upper or lower) of each of the characters in the search pattern. Find Backwards directs the search to proceed in an upwardly direction. The Selected Text option keeps the search within currently selected text. Checking Whole Words Only prevents the search from stopping on words that contain the searched for pattern. The Search from Cursor option begins the search from the current position of the cursor within the document rather than from the beginning.

F3 Edit Find Next

  This repeats the last find operation, if any, without calling the find dialog box.

CtrlR Edit Replace

  This command opens the replace dialog box. The replace dialog is identical to the above-mentioned find diolog with the addition of a Replace With: text entry/dropdown box. Using this dialog the user can specify both the text to be found and text with which to replace it.

Edit Go to line

  This opens the goto line dialog box which is used to have the cursor jump to a particular line (specified by number) in the document. The line number may be entered directly into the text box or graphically by clicking on the up or down arrow spin controls at the side of the text box. The little up arrow will decrease the line number and the down arrow increase it. There is also a slide control to the right of the text box which allows the user to move the goto point in the document in an analog manner.

### The Bookmarks Menu

Bookmarks are points within a &kwrite; document marked for easy return. If the user thinks (s)he may need to return to a specific point (s)he may by way of this feature instruct &kwrite; to remember it.

CtrlB Bookmarks Set Bookmark

  This creates a bookmark in the document at the line where the cursor is located, and allows the user to choose its position in the list of bookmarks which is appended at the bottom of this menu item.

CtrlB Bookmarks Add Bookmark

  This creates a bookmark in the document at the line where the cursor is located and places it at the bottom of the list of bookmarks.

Bookmarks Clear Bookmarks

  This command will remove the list of bookmarks which is appended at the bottom of this menu item.

At the bottom of this menu, a submenu of bookmarks becomes active, if any bookmarks are available for this window.

### The Tools Menu

Tools Set Highlighting

  This allows the user to choose the style of color highlighting which the editor uses to display the text The styles are selected by programming language. The font/color information is not stored with the document.

### The Settings Menu

Settings Show Toolbar

  When checked, this displays a movable toolbar containing buttons used to initiate frequently used commands. When unchecked the toolbar is hidden.

Settings Show Statusbar

  When checked, this displays a small bar at the bottom of the editor containing information about the status of the current document. When unchecked the statusbar is hidden.

Settings Show Path

  When checked, this displays the path (its location in the file system) of the current document. When unchecked the path is hidden.

Settings Vertical Selection

  This is used to turn on or off the vertical selection feature. Vertical selection allows text to be selected by column as well as by row. In other words with this feature the user is able to select text contained in only particular contiguous columns and rows. In affect the user can select a rectangular area of text anywhere in the document.

Settings End of Line

  This opens a sub-menu from which the user can select the type of 'end of line' code for &kwrite; to use, i.e., the accepted standard used by Unix, MacIntosh, or Ms Windows systems.

Settings Save Options

  This saves the current editor settings to be used for future documents.

Settings Configure Key Bindings

  This command opens a dialog box whereby the key bindings may be changed. A display window at the top of the dialog box shows the list of commands available. Below the display are three radio buttons. The user may choose between No Key, Default Key, and Custom Key. (Note that a set of radio buttons only allows the selection of one of the offered items - in the way that buttons on a car radio only offer the selection of one preset station. Also, the Default Key selection is only available for those commands that actually have a 'default' shortcut.) Selecting the Default Key option activates the three check boxes and key button at the bottom of the dialog. The user may then select a combination of key combinations for the command in question by means of the check boxes and key button. For example, with the About KDE command selected in the display window, the user could select Ctrl and Alt, click on the key button, and then press the K key on the keyboard. This would mean that anytime he or she held down the Ctrl and Alt buttons and pressed K (while using &kwrite;) the About KDE display box would be called.

Settings Configure Toolbars

  This will open the dialog whereby the toolbar configuration may be changed. The user can choose which shortcut buttons should appear on the toolbar, as well as whether and where any text should appear with the buttons. Other choices include button (icon) size and toolbar location (top, left, right, floating, or flat.) Flat causes the toolbar to be retracted. A click on the striated grip icon will extend it for use and another click retract it again. A display window on the left lists the commands available to placed on the toolbar. A display on the right lists those commands already on the toolbar. A set of four arrow buttons between the two displays manipulates the selections. The right pointing arrow places any command selected in the left pane onto the right pane, i.e., it is added to the toolbar. The left arrow does just the opposite, removing any action selected in the right window from the toolbar. The up and down pointing arrows change the position of an action selected in the right window which changes the position of its button in the toolbar.

Settings Preferences

  This menu item opens a dialog whereby a host of different settings may be adjusted.

### The Help Menu

F1 Help Contents

  This invokes the KDE help system starting at the &kwrite; help pages (this document).

ShiftF1 Help What's This?

  This changes the mouse cursor to a combination arrow and question mark. Clicking on items within KWrite with this arrow will open a help window (if one exists for the particular item) explaining the item's function.

Help About KWrite

  This will displays version and author information

Help About KDE

  This displays the KDE version and other basic information.

## The Preferences Dialog

### Indent

Auto Indent

  This causes new lines to begin with the same indentation level as the previous line.

Indent With Spaces

  This replaces tabs with the number of spaces selected in the Tab Width window in the Edit section of the preferences dialog.

Backspace Key Indents

  This allows the backspace key to be used to indent.

Tab Key Indents

  This allows the tab key to be used to indent.

Keep Indent Profile

  This retains current indentation settings for future documents.

Keep Extra Spaces

  Indentations of more than the selected number of spaces will not be shortened.

### Select

Persistent Selections

  This prevents key input or cursor movement by way of the arrow keys from causing the elimination of text selection.

  (Note: If the Overwrite Selections option is activated then any typed character input or paste operation will replace the selected text.)

Overwrite Selections

  Any keyed character input or paste operation will replace the selected text.

Mouse Autocopy

  Any text selected with the mouse will be automatically copied to the clipboard.

X11-like Single Selection

  Not implemented yet.

Vertical Selections

  This activates the Vertical Selection option.

Toggle Old

  Not yet implemented

### Edit

Word Wrap

  &kwrite; will automatically start a new line of text when the current line reaches the length specified by the Wrap Words At: option.

Wrap Words At:

  If the Word Wrap option is selected this entry determines the length (in characters) at which the editor will automatically start a new line.

Replace Tabs By Spaces

  &kwrite; will replace any tabs with the number of spaces indicated in the Tab Width: entry.

Tab Width

  If the Replace Tabs By Spaces option is selected this entry determines the number of spaces with which the editor will automatically replace tabs.

Remove Trailing Spaces

  &kwrite; will automatically eliminate extra spaces at the ends of lines of text.

Auto Brackets

  When the user types a left bracket &kwrite; automatically enters the right bracket to the right of the cursor.

Group Undos

  Groups of similar actions are to be considered a single Undo step by &kwrite;. In other words, a series of regular character keystrokes (words or expressions) would be considered one step and therefore be removed by a single undo operation. If the series of character entries were interrupted by a non-character entry operation (such as a backspace), invoking undo would only remove the entries made since that operation. The next undo would then reverse that operation and so on.

  When this option is not selected &kwrite; considers each keystroke to be a single step. So if the user (with this option active) were to type several words or even sentences without having to make corrections or cut or paste or some other non-character entry operation then a click of the undo button would eliminate all that had been typed since the last non-entry operation. A second click would eliminate that operation and a third any operation or series of entries that occurred before the operation and so on. When not selected three clicks of the undo button would only remove the last three letters typed, or the last three operations.

Show Tabs

  The editor will display a symbol to indicate the presence of a tab in the text.

Smart Home

  Not yet implemented

Page Up/Down Moves Cursor

  Not implemented yet.

Wrap Cursor

  When this option is chosen, moving the cursor with the arrow keys off the end of a line (to the right) causes it to jump down to the beginning of the next line. Likewise when the cursor is moved past the beginning of a line (to the left) it jumps up to the end of the preceding line. When this option is not selected, moving the cursor right past the end of a line merely causes it to continue horizontally in the same line and trying to move it left past the beginning does nothing.

Undo steps:

  Here the user may specify the number of steps &kwrite; will retain in memory for purposes of undoing entries and actions. This means that the higher the number of steps set the more memory &kwrite; will use for this. Setting this entry to 10 would mean that the user would be be able reverse the last ten operations, i.e., click the undo button 10 times and obtain results.

### Colors

This section provides access to five different color settings, described below. Each of these settings may be changed by clicking on its corresponding button. These are special wide buttons that are the color of the current setting. Clicking on one of the buttons calls a special color dialog box used to change the setting.

The color dialog box provides a convenient and graphical way to select a color. In the upper left of the box is a rectangular display of a spectrum of colors. To the immediate right of this, is vertical bar displaying a range of intensity from the most dark at the bottom to the most light at the top. The user may select and adjust a color by clicking in these two boxes. Clicking in the rectangular display selects a particular mix of red, green, and blue colors and in the vertical bar selects a level of intensity (value). The various color attributes are displayed in numerical form in small text boxes located directly below the spectral rectangle and the user can see them change as the color is adjusted. These attributes include the mix of the basic color components (red, green, and blue) as well as hue and saturation levels. Alternatively the user can enter figures directly in these boxes. There is also a square at the bottom center of the dialog box which displays the color which is under consideration at any time. To the right of this display is another text box labeled 'HTML:' This shows the user the color code that would be used to specify the particular displayed color in HTML code which is widely used for web pages.

In addition to the above the color dialog allows the capture of any color currently displayed on the desktop or in another program. Clicking on the button with the dropper icon (located on the right side of the dialog box,) changes the shape of the mouse cursor to a set of crosshairs. Clicking again will pick up the color attributes of whatever color is displayed under the cross hairs.

Furthermore the user has the option of adding any color to a personal palette of 'Custom Colors' by clicking on the wide button labeled 'Add to Custom Colors' (which is located directly above the display square.) This adds the current color to the custom color palette. This palette and any other available palettes can be displayed using the drop down selection box located directly above the palette display at the top right of the dialog box. Besides the custom colors, the user can access a number of pre-prepared palettes.

Background

  Here the user can specify a color for the general background of &kwrite;.

Text Background

  This is used to set a particular color to display in the background of those areas of the document containing text.

Selected

  This allows the user to select a color to be used for indicating selected (or highlighted) portions of the document.

Found

  This specifies the preferred color with which to mark text encountered as the result of a find operation.

Selected + Found

  This sets the color for text that has not only been found as in the previous entry above but that has also been selected.

### Highlighting

Not yet implemented

### Key Bindings

By selecting this option, the user can view and change the key bindings (shortcuts) used to initiate various commands in &kwrite;. The sections that the preferences dialog displays to make this possible are described below.

Group

  This is a drop down box used to select which group of commands to display or change. The commands are grouped according to the type of action they entail such as Cursor Movement, Editing, and Bookmarking.

Commands:

  The commands belonging to the group selected in the above-mentioned drop down box are listed in this section. Clicking on a particular command causes any shortcuts associated with the command to be listed in the Current Keys display - detailed below.

Current Keys:

  In this box (located in the top right portion of the preferences dialog) the user can see a list of shortcut key combinations (if any) that are associated with the command selected above-mentioned Commands display. Clicking on any existing shortcut will select it and allow it to be eliminated with the Remove button just to the right.

Press New Shortcut Key:

  Located just below the list of current keys this entry is used to associate a new shortcut with the currently selected command. By clicking in this box and then pressing the desired key combination, the new shortcut can be easily chosen. If the combination happens to be associated with another command the pertinent details will be displayed just below this entry. If there are no conflicts, the user may click the Assign button (located just to the right) to associate the newly created key combination with the command being considered.

Defaults Button

  Located on the right side of the dialog box, this button will reset &kwrite;'s key bindings to what they were when &kwrite; was first installed. This will also cause the loss of any previous changes.

### Spell Checker

A spell checker is a program designed to help the user catch and correct any spelling errors. This section of the preferences dialog allows certain key settings to be adjusted in this regard.

Create root/affix combinations not in dictionary

  Selecting this option allows the spell checker to register as 'correct' combinations of root words with suffixes or prefixes even if the particular combination is not listed in its dictionary data base of words.

Consider run-together words as spelling errors

  Selecting this will cause the spell checker to register as 'misspelled' two or more correctly spelled words that are 'run-together', i.e., that do not have spaces separating them.

Dictionary:

  Depending on the user's installation one or more different language spelling dictionaries may be available. This drop down box allows the user to choose which language the spell checker should use.

Encoding:

  There are different coding systems used to associate particular codes with particular characters and symbols. If the user knows which code he or she is using this drop down box allows this code to be specified so that the spell checker can do its job correctly.

Client:

  Since &kwrite; does not contain its own spell checker, an external one must be chosen. This is where the user may specify which spell check program to use.

## Credits and Licenses

&kwrite; Copyright 2000 by Jochen Wilhelmy digisnap@cs.tu-berlin.de

Contributions:

- Additional contributions by Glen Parker glenebob@nwlink.com

- Michael Koch koch@kde.org

Documentation by Thad McGinnis jamcgin@racsa.co.cr

- This version of the &kwrite; Handbook is based on the original by Cristian Tibirna tibirna@kde.org

Converted to docbook/proofreading by Lauri Watts vampyr@atconnex.net

This program is licensed under the terms of the GNU General Public License. The documentation is licensed under the terms of the GNU Free Documentation License.