~kubuntu-members/kmag/4.11

<?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 id="kmag" 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>

<!--FIXME missing:
"&Follow Focus Mode" 
qaccessibilityclient  <https://projects.kde.org/projects/playground/accessibility/libkdeaccessibilityclient>
KDE client-side accessibility library
Required to enable keyboard focus tracking

commit 035090bca3a3065800c6d9ff1862167170a0e939
Author: Sebastian Sauer mail@dipe.org
Date:   Tue Jul 20 20:33:23 2010 +0000
    Add a new 'Follow Focus' mode to KMag that uses the just new kaccessible QAccessibleBridgePlugin for providing keyboard cursor focus tracking.
    svn path=/trunk/KDE/kdeaccessibility/kmag/; revision=1152354
commit 2278a10a069ed436d0167ae3ef099b020e35f663
Author: Amandeep Singh aman.dedman@gmail.com
Date:   Wed Sep 26 02:46:22 2012 +0530
    Allowing KMag to follow both mouse + kbd-focus together
       -Made the followMouseMode + followFocusMode selectable together.
       -With just followMouseMode checked, Kmag follows mouse,
         and with followFocusMode checked, Kmag follows focus.
       -And when both are selected, it follows both the mouse,
         and the keyboard focus, whichever is relevant.
-->

<date>2013-05-31</date>
<releaseinfo>1.0 &kde; 4.11</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 
(<guilabel>Selection Window Mode</guilabel>) or the whole screen 
(<guilabel>Whole Screen Mode</guilabel>) into the zoom window.
</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 zoom window and the selection window can be moved and resized
using the &LMB; like any window.
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>, &LMB; or &MMB;</term>
<listitem>
<para>By keeping the &LMB; or &MMB; pressed in the zoom window and moving the
mouse, you can move the selection window.
You can also use the arrow keys if the selection window has the focus.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><keycombo>&Ctrl;<keycap>Arrow Keys</keycap></keycombo> or
<keycombo>&Ctrl;<mousebutton>&LMB;</mousebutton></keycombo></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. It is 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 used later to paste in other applications),
rotate the magnification image and more.
</para>

</sect1>
</chapter>


<chapter id="menu-shortcuts"> 
<title>Menus and Shortcuts</title> 
 
<sect1 id="menus"> 
<title>Menu Reference</title> 

<sect2 id="the-file-menu">
<title>The File 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> 
</sect2> 
 
<sect2 id="the-edit-menu"> 
<title>The Edit 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> 
</sect2> 
 
<sect2 id="the-view-menu"> 
<title>The View 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> 
<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>

<varlistentry> 
<term><menuchoice> 
<guimenu>View</guimenu> 
<guisubmenu>Colors</guisubmenu> 
</menuchoice></term> 
<listitem><para>Select different color vision deficiencies to simulate
color blindness. This is not useful for people with color 
blindness, but good for designing accessible interfaces.</para></listitem> 
</varlistentry> 
 
</variablelist>
</sect2>

<sect2 id="the-settings-menu">
<title>The Settings Menu</title>

<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">
<keycap>F2</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>F3</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>
<shortcut>
<keycombo action="simul">
<keycap>F4</keycap></keycombo>
</shortcut>
<guimenu>Settings</guimenu>
<guimenuitem>Whole Screen Mode</guimenuitem>
</menuchoice></term>
<listitem><para>In this mode the whole screen is magnified in the zoom window.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">
<keycap>F6</keycap></keycombo>
</shortcut>
<guimenu>Settings</guimenu>
<guimenuitem>Hide Mouse Cursor</guimenuitem>
</menuchoice></term>
<listitem><para>Show or hide the mouse cursor in the magnified image.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut>
<keycombo action="simul">
<keycap>F7</keycap></keycombo>
</shortcut>
<guimenu>Settings</guimenu>
<guimenuitem>Stays On Top</guimenuitem>
</menuchoice></term>
<listitem><para>The &kmag; window stays on top of other windows.</para></listitem>
</varlistentry>
</variablelist>

<para>
Additionally &kmag; has the common &kde; <guimenu>Settings</guimenu> and <guimenu>Help</guimenu>
menu items, for more information read the sections about the <ulink url="help:/fundamentals/ui.html#menus-settings"
>Settings Menu</ulink> and <ulink url="help:/fundamentals/ui.html#menus-help">Help Menu</ulink>
of the &kde; Fundamentals.
</para>

</sect2>

</sect1>

<sect1 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>F2</keycap></entry>
<entry><para>Switch to "Follow Mouse Mode".</para>
</entry>
</row>
<row>
<entry><keycap>F3</keycap></entry>
<entry><para>Switch to "Selection Window Mode".</para>
</entry>
</row>
<row>
<entry><keycap>F4</keycap></entry>
<entry><para>Switch to "Whole Screen Mode".</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>Show or hide the mouse cursor in the magnified image.</para>
</entry>
</row>
<row>
<entry><keycap>F7</keycap></entry>
<entry><para>The &kmag; window stays on top of other windows.</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>
</sect1>
</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:
-->