the kwrite handbook
thad mcginnis<ctmcginnis@compuserve.com>jochenwilhelmyprincipal developerdigisnap@cs.tu-berlin.deglenparkeradditional developmentglenebob@nwlink.commichaelkochadditional developmentkoch@kde.orgchristiantibirnaoriginal help documenttibirna@kde.orglauriwattsreviewervampyr@atconnex.net
the kwrite handbook
by thad mcginnisjochen wilhelmy<digisnap@cs.tu-berlin.de>glen parker<glenebob@nwlink.com>michael koch<koch@kde.org>christian tibirna<tibirna@kde.org>lauri watts<vampyr@atconnex.net>
Copyright © 2000, 2001 thad mcginnis
this handbook describes kwrite version 2.0
kwrite is a text editor for kde 2.0
permission is granted to copy, distribute and/or modify this
document under the terms of the gnu free documentation license,
version 1.1 or any later version published by the free software
foundation; with no invariant sections, with no front-cover texts, and
with no back-cover texts. a copy of the license is included in the section entitled gnu free documentation license.
Table of Contents
1 introduction
2 some fundamentals
drag and drop
command line options
specify a file
specify a file on the internet
other command line options
key bindings
3 the menu entries
the file menu
the edit menu
the go menu
the tools menu
the settings menu
the help menu
4 configure kwrite
colors
indent
select
edit
spelling
5 highlighting
6 credits and licenses
A installation
Chapter 1. introduction
Chapter 1. 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.
Chapter 2. some fundamentals
Chapter 2. 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)
shift-left arrow
mark text one character to the left
shift-right arrow
mark text one character to the right
f1
help
shift-f1
what's this?
ctrl-f
find
f3
find again
ctrl-c
copy the marked text to the clipboard.
ctrl-m
set a bookmark
ctrl-n
new document
ctrl-p
print
ctrl-q
quit - close active copy of editor
ctrl-r
replace
ctrl-s
invokes the save command.
ctrl-v
paste the clipboard text into line edit.
ctrl-x
delete the marked text and copy it to the clipboard.
ctrl-z
undo
ctrl-shift-z
redo
Chapter 4. configure kwrite
Chapter 4. configure kwrite
selecting
settings->configure
kwrite from the menu brings up the configure-kwrite
dialog box. this dialog can be used to alter a number of different settings. the
settings available for change vary according to which category the user chooses from
a vertical list on the left side of the dialog. by means of three buttons
along the bottom of the box the user can control the process. she or he may invoke
the help system, accept the current settings and close the
dialog by means of the ok button, or
cancel the process. the categories
colors, indent,
select, edit, and
spelling are detailed below.
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.
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
(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
word wrap is a feature that causes the editor to
automatically start a new line of text and move (wrap) the cursor to the
beginning of that new line. 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 ([,(, or {) kwrite automatically
enters the right bracket (}, ), or ]) 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
this option changes the behavior of the cursor when
the user presses the page up or page down key. if
unselected the text cursor will maintain its relative position within the visible
text in kwrite as new text becomes visible as a result of the operation. so if
the cursor is in the middle of the visible text when the operation occurs it will
remain there (except when one reaches the beginning or end.) with this
option selected, the first key press will cause the cursor to move to either the top
or bottom of the visible text as a new page of text is displayed.
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.i>, click the undo
button 10 times and obtain results.
spelling
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 important 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.
Chapter 5. highlighting
Chapter 5. highlighting
the configure highlighting dialog consists of two
pages, defaults and highlighting
modes. the user can select which page to view by clicking on the
appropriate tab at the top of the dialog
items available on the defaults page are as
follows:
default item styles
the user can configure the default appearance for particular items.
this would allow a programmer to more easily identify different items (types of
entries) in his or her code.
item
this drop down list offers a variety of items that the user
might want to highlight. they include normal for
text does not fit in any of the other categories, comment,
string, keyword and many more. not
all of these entries will need to be configured for every language and so may be
selected as needed. the options in the rest of this section apply
to the entry selected in this box.
normal
this allows the user to choose the item's normal
(unselected) color. this is done by means of a color selection
dialog box, a further explanation of which may be found in the colors section of configure kwrite.
bold
this option determines whether or not the item should be displayed in
bold text.
italic
this option determines whether or not the item should be displayed in italic
text.
selected
this allows the user to choose the item's color
when selected. this is done by means of a color selection
dialog box, a further explanation of which may be found in the colors section of configure kwrite.
default font
here the user can choose the default font for all
text.
family
this is used to choose the font family. the default is fixed.
for most programming purposes, a monospaced font (one in which a w takes up the same
amount of space as an i) may be the best choice.
size
the font size can be changed here. the default is 12
points.
charset
here the user can choose which character set to work in.
items on the highlight modes tab allow the user to define
more specific highlighting depending on the language style.
one need not set every available option, items not configured
specifically will use the default configuration specified on the previous
(defaults tab.
config select
this group of options is used to customize the highlighting styles
for each programming language type. any changes you made in
other areas of this dialog apply only to this type.
highlight
this is used to choose the language type to
configure
item
this is to choose the syntax item to configure. remember
this only configures this item for this
language.
as an example, if the user wished to configure the appearance of
“comments” while writing c++, she or he could choose c++ in the
highlight drop down list, and then choose comment in the
item drop down list. to have “comments” look
the same across all languages, the user would need to configure this in the
defaults page of this dialog box while leaving
“comments” unconfigured within the more specific
highlight modes page.
item style
here the user can configure the general appearance of the above
selected item. checking the default checkbox causes the default
style as configured on the previous tab to be set, or the
appearance can be configured directly. the available options are the same as on the
defaults tab: normal,
selected, bold and
italic.
highlight auto select
kwrite can apply syntax highlighting automatically, depending
on the file extension or mime-type of the opened file. the defaults are fairly
comprehensive, but users that regularly edit files with non-standard extensions
can add them here. wildcards are allowed in the file
extensions text box. for example, the default entry for the c++
language is *.cpp;*.cc;*.c;*.h. opening a file called
foo.h would automatically apply the c++ style to it.
item font
here the user can choose the font for the selected item.
the default style can be applied by checking the
default checkbox or the user can choose a specific font
family, size and
charset. the available options are the same as those on
the defaults tab.
Chapter 6. credits and licenses
Chapter 6. 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 <ctmcginnis@compuserve.com>
•
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 documentation is licensed under the terms of the gnu free documentation
license [common/fdl-license.html].
this program is licensed under the terms of the gnu general public license [common/gpl-translated.html].
Appendix A. installation
Appendix A. installation
kwrite is packaged as part of the kdebase package. for more information
on installing and compiling kde please see www.kde.org [http://www.kde.org].