Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdeaccessibility@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 647 insertions, 0 deletions

diff --git a/doc/kmag/index.docbook b/doc/kmag/index.docbook
new file mode 100644
index 0000000..0faf531
--- /dev/null
+++ b/doc/kmag/index.docbook
@@ -0,0 +1,647 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+  <!ENTITY kmag "<application>KMagnifier</application>">
+  <!ENTITY kappname "&kmag;">
+  <!ENTITY package "kdeaccessibility">
+  <!ENTITY % addindex "IGNORE">
+  <!ENTITY % English "INCLUDE"><!-- change language only here -->
+]>
+
+<!-- The language must NOT be changed here. -->
+
+<book lang="&language;">
+
+
+<bookinfo>
+<title>The &kmag; Handbook</title>
+
+<authorgroup>
+<author>
+<firstname>Sarang</firstname>
+<surname>Lakare</surname>
+<affiliation>
+<address><email>sarang@users.sf.net</email></address>
+</affiliation>
+</author>
+<author>
+<firstname>Olaf</firstname>
+<surname>Schmidt</surname>
+<affiliation>
+<address><email>ojschmidt@kde.org</email></address>
+</affiliation>
+</author>
+<!-- TRANS:ROLES_OF_TRANSLATORS -->
+</authorgroup>
+
+
+<copyright>
+<year>2000</year>
+<year>2002</year>
+<holder>Sarang Lakare</holder>
+</copyright>
+
+<copyright>
+<year>2004</year>
+<year>2005</year>
+<holder>Olaf Schmidt</holder>
+</copyright>
+
+<legalnotice>&FDLNotice;</legalnotice>
+
+
+
+<date>2006-05-25</date>
+<releaseinfo>1.0</releaseinfo>
+
+<!-- Abstract about this handbook -->
+
+<abstract>
+<para>
+&kmag; is a screen magnifier. You can use
+&kmag; to magnify a part of the screen just as you would use a lens to magnify
+a newspaper fine-print or a photograph. This application is useful for a
+variety of people: from researchers to artists to web-designers to people with
+low vision. This document will try to be a complete reference manual for using
+&kmag;.
+</para>
+
+</abstract>
+
+<keywordset>
+<keyword>KDE</keyword>
+<keyword>kmag</keyword>
+<keyword>K Magnifier</keyword>
+</keywordset>
+
+</bookinfo>
+
+<chapter id="introduction">
+<title>Introduction</title>
+
+<para>
+&kmag; is a screen magnifier for the K Desktop Environment (&kde;). It can be used
+to magnify a part of the screen. This application can be useful to various people:
+People with low vision can use this application to magnify a part of the screen which they
+are unable to view clearly,
+artists can use this application to zoom into the graphics they produce and verify it
+at the pixel level,
+image-processing researchers can use this application to zoom into images and study them closely.
+Other than these, &kmag; can be used for various other purposes &eg; is possible to use the
+application for grabbing a portion of the screen and saving it to the disk (with an option of
+zooming the screen captured).
+</para>
+<para>
+&kmag; is a very powerful application with new features being added all the time. It is optimized
+for use on low processing power machines.
+</para>
+</chapter>
+
+<chapter id="using-kmag">
+<title>Using &kmag;</title>
+
+<screenshot>
+<screeninfo>Here's a screen shot of &kmag;</screeninfo>
+	<mediaobject>
+	  <imageobject>
+	    <imagedata fileref="screenshot.png" format="PNG"/>
+	  </imageobject>
+	  <textobject>
+	    <phrase>Screen shot of &kmag;</phrase>
+	  </textobject>
+	</mediaobject>
+</screenshot>
+
+<para>
+After running &kmag; you will get a window similar to the one show above. The main window of
+&kmag; shows the magnified (or zoomed) contents.
+We refer to this window as the <quote>zoom window</quote>. The zoomed image shown inside the zoom window is
+captured from a part of the screen. The part of the screen which is magnified is referred to
+as the <quote>selection window</quote>.
+</para>
+<para>
+By default, &kmag; magnifies the region around the mouse cursor into the zoom window (think of it as a moving lens).
+Alternatively, you can ask &kmag; to magnify an chosen area of the screen into the zoom window
+(<guilabel>Selection Window Mode</guilabel>), or the area around the mouse cursur to one of the screen edges
+(e.g. <guilabel>Left Screen Edge Mode</guilabel>).
+</para>
+<para>
+If you would prefer not to see the mouse cursor in the zoomed image, select
+<guilabel>Hide Mouse Cursor</guilabel>. Please note that &kmag; cannot yet find out the current cursor shape.
+Thus, it shows the default &kde;/&Qt; cursor.
+</para>
+
+<sect1 id="changing-selection-window">
+<title>Changing the part of the screen to be magnified</title>
+<para>
+When in <guilabel>Selection Window Mode</guilabel>, the selection window can be moved and resized.
+You can also change the position and size of the selection window using the arrow keys on the keyboard,
+or by clicking into the zoom window:
+</para>
+
+<variablelist>
+<varlistentry>
+<term><keycap>Arrow keys</keycap> or &LMB;</term>
+<listitem>
+<para>By keeping the left mouse button pressed and moving the
+mouse, you can grab and drag the contents of the zoom window.
+You can also use the arrow keys.</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><keycombo>&Shift;<keycap>Arrow Keys</keycap></keycombo> or
+&Shift;&LMB; or &MMB;.</term>
+<listitem>
+<para>By additionally pressing &Shift; or using the &MMB;,
+you can move the selection window.
+</para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term><keycombo>&Ctrl;<keycap>Arrow Keys</keycap></keycombo> or
+&Ctrl;&LMB;</term>
+<listitem>
+<para>By using this combination, you can resize the selection
+window. Keep in mind that the top-left corner of the selection window
+is kept constant and the bottom-right corner is movable.</para>
+</listitem>
+</varlistentry>
+</variablelist>
+
+</sect1>
+
+<sect1 id="kmag-features">
+<title>More &kmag; features</title>
+
+<para>&kmag; comes with lots of features. Its possible to print the zoomed
+image directly to a printer, save the image to a file, copy the zoomed
+image to the clipboard (which can be later used to paste in other applications),
+rotate the magnification image and more.
+</para>
+
+</sect1>
+</chapter>
+
+
+<chapter id="menus"> 
+<title>Menu Reference</title> 
+ 
+<sect1 id="the-file-menu"> 
+<title>The <guimenu>File</guimenu> Menu</title> 
+ 
+<variablelist> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<shortcut> 
+<keycombo action="simul">&Ctrl; 
+<keycap>N</keycap></keycombo> 
+</shortcut> 
+<guimenu>File</guimenu> 
+<guimenuitem>New Window</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Opens a new &kmag; window.</para></listitem> 
+</varlistentry> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<shortcut> 
+<keycombo action="simul">&Ctrl; 
+<keycap>S</keycap></keycombo> 
+</shortcut> 
+<guimenu>File</guimenu> 
+<guimenuitem>Save Snapshot As...</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Saves the zoomed view to an image file.</para></listitem> 
+</varlistentry> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<shortcut> 
+<keycombo action="simul">&Ctrl; 
+<keycap>P</keycap></keycombo> 
+</shortcut> 
+<guimenu>File</guimenu> 
+<guimenuitem>Print...</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Prints the current zoomed view.</para></listitem> 
+</varlistentry> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<shortcut> 
+<keycombo action="simul">&Ctrl; 
+<keycap>Q</keycap></keycombo> 
+</shortcut> 
+<guimenu>File</guimenu> 
+<guimenuitem>Quit</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Quits the application</para></listitem> 
+</varlistentry> 
+</variablelist> 
+</sect1> 
+ 
+<sect1 id="the-edit-menu"> 
+<title>The <guimenu>Edit</guimenu> Menu</title> 
+ 
+<variablelist> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<shortcut> 
+<keycombo action="simul">&Ctrl; 
+<keycap>C</keycap></keycombo> 
+</shortcut> 
+<guimenu>Edit</guimenu> 
+<guimenuitem>Copy</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Copy the current zoomed view to the clipboard which 
+you can paste in other applications.</para></listitem> 
+</varlistentry> 
+</variablelist> 
+</sect1> 
+ 
+<sect1 id="the-view-menu"> 
+<title>The <guimenu>View</guimenu> Menu</title> 
+ 
+<variablelist> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<shortcut> 
+<keycombo action="simul"> 
+<keycap>F5</keycap></keycombo> 
+</shortcut> 
+<guimenu>View</guimenu> 
+<guimenuitem>Start/Stop</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Start/Stop updating of the display. 
+Stopping the update will zero the processing power required (CPU 
+usage)</para></listitem> 
+</varlistentry> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<guimenu>View</guimenu> 
+<guimenuitem>Zoom</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Select the zoom factor.</para></listitem> 
+</varlistentry> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<shortcut> 
+<keycombo action="simul">&Ctrl; 
+<keycap>-</keycap></keycombo> 
+</shortcut> 
+<guimenu>View</guimenu> 
+<guimenuitem>Zoom Out</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Click on this button to zoom-out on the selected region.</para></listitem> 
+</varlistentry> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<shortcut> 
+<keycombo action="simul">&Ctrl; 
+<keycap>+</keycap></keycombo> 
+</shortcut> 
+<guimenu>View</guimenu> 
+<guimenuitem>Zoom In</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Click on this button to zoom-in on the selected region.</para></listitem> 
+</varlistentry> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<shortcut> 
+<keycombo action="simul"> 
+<keycap>F6</keycap></keycombo> 
+</shortcut> 
+<guimenu>View</guimenu> 
+<guimenuitem>Invert Colors</guimenuitem> 
+</menuchoice></term> 
+<listitem><para><action>Inverts</action> colors on the view, &ie; black things will be shown white.</para></listitem> 
+</varlistentry> 
+ 
+<varlistentry> 
+<term><menuchoice> 
+<guimenu>View</guimenu> 
+<guimenuitem>Rotation</guimenuitem> 
+</menuchoice></term> 
+<listitem><para>Select the rotation degree (<guimenuitem>No Rotation (0 Degrees)</guimenuitem>, 
+<guimenuitem>Left (90 Degrees)</guimenuitem>, <guimenuitem>Upside Down (180 Degrees)</guimenuitem>, 
+<guimenuitem>Right (270 Degrees)</guimenuitem>.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>View</guimenu>
+<guimenuitem>Refresh</guimenuitem>
+</menuchoice></term>
+<listitem><para>Select the refresh rate (<guimenuitem>Very Low</guimenuitem>, 
+<guimenuitem>Low</guimenuitem>, <guimenuitem>Medium</guimenuitem>, 
+<guimenuitem>High</guimenuitem>, <guimenuitem>Very High</guimenuitem>).
+The higher the rate, the more computing power (CPU)
+will be needed.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="the-settings-menu">
+<title>The <guimenu>Settings</guimenu> Menu</title>
+
+<variablelist>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">&Ctrl;
+<keycap>M</keycap></keycombo>
+</shortcut>
+<guimenu>Settings</guimenu> 
+<guimenuitem>Show/Hide Menu</guimenuitem>
+</menuchoice></term>
+<listitem><para>Toggles the menubar on/off.</para></listitem>
+</varlistentry>
+ 
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show/Hide Main Toolbar</guimenuitem>
+</menuchoice></term>
+<listitem><para>Toggles the main toolbar on/off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show/Hide View Toolbar</guimenuitem>
+</menuchoice></term>
+<listitem><para>Toggles the view toolbar on/off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show/Hide Settings Toolbar</guimenuitem>
+</menuchoice></term>
+<listitem><para>Toggles the settings toolbar on/off.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">
+<keycap>F1</keycap></keycombo>
+</shortcut>
+<guimenu>Settings</guimenu>
+<guimenuitem>Follow Mouse Mode</guimenuitem>
+</menuchoice></term>
+<listitem><para>In this mode the area around the mouse cursor is shown in a normal window.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">
+<keycap>F2</keycap></keycombo>
+</shortcut>
+<guimenu>Settings</guimenu>
+<guimenuitem>Selection Window Mode</guimenuitem>
+</menuchoice></term>
+<listitem><para>In this mode a selection window is opened. The selected area is shown in a normal window.</para></listitem>
+</varlistentry>
+
+<varlistentry> 
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Top Screen Edge Mode</guimenuitem>
+</menuchoice></term>
+<listitem><para>In this mode the area around the mouse is magnified to the top screen edge.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Left Screen Edge Mode</guimenuitem>
+</menuchoice></term>
+<listitem><para>In this mode the area around the mouse is magnified to the left screen edge.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Right Screen Edge Mode</guimenuitem>
+</menuchoice></term>
+<listitem><para>In this mode the area around the mouse is magnified to the right screen edge.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Bottom Screen Edge Mode</guimenuitem>
+</menuchoice></term>
+<listitem><para>In this mode the area around the mouse is magnified to the bottom screen edge.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<shortcut>
+<keycombo action="simul">
+<keycap>F4</keycap></keycombo>
+</shortcut>
+<guimenu>Settings</guimenu>
+<guimenuitem>Show/Hide Mouse Cursor</guimenuitem>
+</menuchoice></term>
+<listitem><para>Show or hide the mouse cursor in the magnified image.</para></listitem>
+</varlistentry>
+
+<varlistentry> 
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Shortcuts...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Opens a window that lets you configure the keyboard
+shortcuts for many menu commands.</para></listitem>
+</varlistentry>
+
+<varlistentry>
+<term><menuchoice>
+<guimenu>Settings</guimenu>
+<guimenuitem>Configure Toolbars...</guimenuitem>
+</menuchoice></term>
+<listitem><para>Opens a window that lets you choose which icons are visible
+in the toolbar.</para></listitem>
+</varlistentry>
+</variablelist>
+</sect1>
+
+<sect1 id="the-help-menu">
+<title>The <guimenu>Help</guimenu> Menu</title>
+
+&help.menu.documentation;
+
+</sect1>
+</chapter>
+
+<chapter id="commands">
+<title>Command Reference</title>
+
+<para>&kmag; automatically uses all your default shortcuts for saving
+file, opening new window, printing, starting/stopping refresh (reload
+button in &konqueror;), zoom-in, zoom-out &etc;</para>
+
+<table>
+<title>Default Keyboard Shortcuts</title>
+<tgroup cols="2">
+<tbody>
+<row>
+<entry><keycombo>&Ctrl;<keycap>S</keycap></keycombo></entry>
+<entry><para>This will save the contents of the zoom window to a
+file.</para>
+</entry>
+</row>
+<row>
+<entry><keycap>F1</keycap></entry>
+<entry><para>Switch to "Follow Mouse Mode".</para>
+</entry>
+</row>
+<row>
+<entry><keycap>F2</keycap></entry>
+<entry><para>Switch to "Selection Window Mode".</para>
+</entry>
+</row>
+<row>
+<entry><keycap>F4</keycap></entry>
+<entry><para>Show or hide the mouse cursor in the magnified image.</para>
+</entry>
+</row>
+<row>
+<entry><keycap>F5</keycap></entry>
+<entry><para>This will start the refresh of the zoom window if it is
+stopped, or stops the refresh of the zoom window if the refresh is
+currently on.</para>
+</entry>
+</row>
+<row>
+<entry><keycap>F6</keycap></entry>
+<entry><para>Invert Colors</para>
+</entry>
+</row>
+<row>
+<entry><keycombo>&Ctrl;<keycap>N</keycap></keycombo></entry>
+<entry><para>This will open a new &kmag; window.</para></entry>
+</row>
+<row>
+<entry><keycombo>&Ctrl;<keycap>P</keycap></keycombo></entry>
+<entry><para>This will open the print dialog for printing the contents
+of the zoom window.</para></entry>
+</row>
+<row>
+<entry><keycombo>&Ctrl;<keycap>C</keycap></keycombo></entry>
+<entry><para>This will copy the zoom window contents to the
+clipboard.</para>
+</entry>
+</row>
+<row>
+<entry><keycombo>&Ctrl;<keycap>M</keycap></keycombo></entry> 
+<entry><para>Show/Hide the menubar.</para> 
+</entry>
+</row>
+<row>
+<entry><keycombo>&Ctrl;<keycap>-</keycap></keycombo></entry>
+<entry><para>Zoom out</para></entry>
+</row>
+<row>
+<entry><keycombo>&Ctrl;<keycap>+</keycap></keycombo></entry>
+<entry><para>Zoom in</para></entry>
+</row>
+<row>
+<entry><keycombo>&Ctrl;<keycap>Q</keycap></keycombo></entry> 
+<entry><para>Quits the application.</para></entry> 
+</row>
+</tbody>
+</tgroup>
+
+</table>
+
+</chapter>
+
+<!--
+<chapter id="faq">
+<title>Questions and Answers</title>
+
+&reporting.bugs;
+&updating.documentation;
+
+<para>
+This section is currently empty as I have not received any questions from any users! I
+will add some FAQ if I hear from any of the users.
+</para>
+
+</chapter>
+-->
+<chapter id="credits">
+
+<!-- Include credits for the programmers, documentation writers, and
+contributors here. The license for your software should then be included below
+the credits with a reference to the appropriate license file included in the KDE
+distribution. -->
+
+<title>Credits and License</title>
+
+<para>
+&kmag;
+</para>
+<para>
+Program copyright 2001-2003 Sarang Lakare <email>sarang@users.sf.net</email> and 2003-2005 Olaf Schmidt <email>ojschmidt@kde.org</email>.
+</para>
+<para>
+Contributors:
+<itemizedlist>
+<listitem><para>Michael Forster <email>forster@fmi.uni-passau.de</email> (original author)</para></listitem>
+</itemizedlist>
+</para>
+
+
+<para>
+Documentation copyright 2002 Sarang Lakare <email>sarang@users.sf.net</email> and
+2004-2005 Olaf Schmidt <email>ojschmidt@kde.org</email>
+</para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+&underFDL;               <!-- FDL: do not remove. Commercial development should -->
+&underGPL;        	 <!-- GPL License -->
+
+</chapter>
+
+<appendix id="installation">
+<title>Installation</title>
+
+<sect1 id="getting-kmag">
+<title>How to obtain &kmag;</title>
+
+&install.intro.documentation;
+
+</sect1>
+
+<sect1 id="compilation">
+<title>Compilation and Installation</title>
+
+&install.compile.documentation;
+
+</sect1>
+
+</appendix>
+
+&documentation.index;
+</book>
+<!--
+Local Variables:
+mode: sgml
+sgml-minimize-attributes:nil
+sgml-general-insert-case:lower
+sgml-indent-step:0
+sgml-indent-data:nil
+End:
+-->