doc/kmag/index.docbook

   1 <?xml version="1.0" ?>
   2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
   3   <!ENTITY kmag "<application>KMagnifier</application>">
   4   <!ENTITY kappname "&kmag;">
   5   <!ENTITY package "kdeaccessibility">
   6   <!ENTITY % addindex "IGNORE">
   7   <!ENTITY % English "INCLUDE"><!-- change language only here -->
   8 ]>
   9
  10 <!-- The language must NOT be changed here. -->
  11
  12 <book lang="&language;">
  13
  14
  15 <bookinfo>
  16 <title>The &kmag; Handbook</title>
  17
  18 <authorgroup>
  19 <author>
  20 <firstname>Sarang</firstname>
  21 <surname>Lakare</surname>
  22 <affiliation>
  23 <address><email>sarang@users.sf.net</email></address>
  24 </affiliation>
  25 </author>
  26 <author>
  27 <firstname>Olaf</firstname>
  28 <surname>Schmidt</surname>
  29 <affiliation>
  30 <address><email>ojschmidt@kde.org</email></address>
  31 </affiliation>
  32 </author>
  33 <!-- TRANS:ROLES_OF_TRANSLATORS -->
  34 </authorgroup>
  35
  36
  37 <copyright>
  38 <year>2000</year>
  39 <year>2002</year>
  40 <holder>Sarang Lakare</holder>
  41 </copyright>
  42
  43 <copyright>
  44 <year>2004</year>
  45 <year>2005</year>
  46 <holder>Olaf Schmidt</holder>
  47 </copyright>
  48
  49 <legalnotice>&FDLNotice;</legalnotice>
  50
  51
  52
  53 <date>2006-05-25</date>
  54 <releaseinfo>1.0</releaseinfo>
  55
  56 <!-- Abstract about this handbook -->
  57
  58 <abstract>
  59 <para>
  60 &kmag; is a screen magnifier. You can use
  61 &kmag; to magnify a part of the screen just as you would use a lens to magnify
  62 a newspaper fine-print or a photograph. This application is useful for a
  63 variety of people: from researchers to artists to web-designers to people with
  64 low vision. This document will try to be a complete reference manual for using
  65 &kmag;.
  66 </para>
  67
  68 </abstract>
  69
  70 <keywordset>
  71 <keyword>KDE</keyword>
  72 <keyword>kmag</keyword>
  73 <keyword>K Magnifier</keyword>
  74 </keywordset>
  75
  76 </bookinfo>
  77
  78 <chapter id="introduction">
  79 <title>Introduction</title>
  80
  81 <para>
  82 &kmag; is a screen magnifier for the K Desktop Environment (&kde;). It can be used
  83 to magnify a part of the screen. This application can be useful to various people:
  84 People with low vision can use this application to magnify a part of the screen which they
  85 are unable to view clearly,
  86 artists can use this application to zoom into the graphics they produce and verify it
  87 at the pixel level,
  88 image-processing researchers can use this application to zoom into images and study them closely.
  89 Other than these, &kmag; can be used for various other purposes &eg; is possible to use the
  90 application for grabbing a portion of the screen and saving it to the disk (with an option of
  91 zooming the screen captured).
  92 </para>
  93 <para>
  94 &kmag; is a very powerful application with new features being added all the time. It is optimized
  95 for use on low processing power machines.
  96 </para>
  97 </chapter>
  98
  99 <chapter id="using-kmag">
 100 <title>Using &kmag;</title>
 101
 102 <screenshot>
 103 <screeninfo>Here's a screen shot of &kmag;</screeninfo>
 104         <mediaobject>
 105           <imageobject>
 106             <imagedata fileref="screenshot.png" format="PNG"/>
 107           </imageobject>
 108           <textobject>
 109             <phrase>Screen shot of &kmag;</phrase>
 110           </textobject>
 111         </mediaobject>
 112 </screenshot>
 113
 114 <para>
 115 After running &kmag; you will get a window similar to the one show above. The main window of
 116 &kmag; shows the magnified (or zoomed) contents.
 117 We refer to this window as the <quote>zoom window</quote>. The zoomed image shown inside the zoom window is
 118 captured from a part of the screen. The part of the screen which is magnified is referred to
 119 as the <quote>selection window</quote>.
 120 </para>
 121 <para>
 122 By default, &kmag; magnifies the region around the mouse cursor into the zoom window (think of it as a moving lens).
 123 Alternatively, you can ask &kmag; to magnify an chosen area of the screen into the zoom window
 124 (<guilabel>Selection Window Mode</guilabel>), or the area around the mouse cursur to one of the screen edges
 125 (e.g. <guilabel>Left Screen Edge Mode</guilabel>).
 126 </para>
 127 <para>
 128 If you would prefer not to see the mouse cursor in the zoomed image, select
 129 <guilabel>Hide Mouse Cursor</guilabel>. Please note that &kmag; cannot yet find out the current cursor shape.
 130 Thus, it shows the default &kde;/&Qt; cursor.
 131 </para>
 132
 133 <sect1 id="changing-selection-window">
 134 <title>Changing the part of the screen to be magnified</title>
 135 <para>
 136 When in <guilabel>Selection Window Mode</guilabel>, the selection window can be moved and resized.
 137 You can also change the position and size of the selection window using the arrow keys on the keyboard,
 138 or by clicking into the zoom window:
 139 </para>
 140
 141 <variablelist>
 142 <varlistentry>
 143 <term><keycap>Arrow keys</keycap> or &LMB;</term>
 144 <listitem>
 145 <para>By keeping the left mouse button pressed and moving the
 146 mouse, you can grab and drag the contents of the zoom window.
 147 You can also use the arrow keys.</para>
 148 </listitem>
 149 </varlistentry>
 150 <varlistentry>
 151 <term><keycombo>&Shift;<keycap>Arrow Keys</keycap></keycombo> or
 152 &Shift;&LMB; or &MMB;.</term>
 153 <listitem>
 154 <para>By additionally pressing &Shift; or using the &MMB;,
 155 you can move the selection window.
 156 </para>
 157 </listitem>
 158 </varlistentry>
 159 <varlistentry>
 160 <term><keycombo>&Ctrl;<keycap>Arrow Keys</keycap></keycombo> or
 161 &Ctrl;&LMB;</term>
 162 <listitem>
 163 <para>By using this combination, you can resize the selection
 164 window. Keep in mind that the top-left corner of the selection window
 165 is kept constant and the bottom-right corner is movable.</para>
 166 </listitem>
 167 </varlistentry>
 168 </variablelist>
 169
 170 </sect1>
 171
 172 <sect1 id="kmag-features">
 173 <title>More &kmag; features</title>
 174
 175 <para>&kmag; comes with lots of features. Its possible to print the zoomed
 176 image directly to a printer, save the image to a file, copy the zoomed
 177 image to the clipboard (which can be later used to paste in other applications),
 178 rotate the magnification image and more.
 179 </para>
 180
 181 </sect1>
 182 </chapter>
 183
 184
 185 <chapter id="menus">
 186 <title>Menu Reference</title>
 187
 188 <sect1 id="the-file-menu">
 189 <title>The <guimenu>File</guimenu> Menu</title>
 190
 191 <variablelist>
 192
 193 <varlistentry>
 194 <term><menuchoice>
 195 <shortcut>
 196 <keycombo action="simul">&Ctrl;
 197 <keycap>N</keycap></keycombo>
 198 </shortcut>
 199 <guimenu>File</guimenu>
 200 <guimenuitem>New Window</guimenuitem>
 201 </menuchoice></term>
 202 <listitem><para>Opens a new &kmag; window.</para></listitem>
 203 </varlistentry>
 204
 205 <varlistentry>
 206 <term><menuchoice>
 207 <shortcut>
 208 <keycombo action="simul">&Ctrl;
 209 <keycap>S</keycap></keycombo>
 210 </shortcut>
 211 <guimenu>File</guimenu>
 212 <guimenuitem>Save Snapshot As...</guimenuitem>
 213 </menuchoice></term>
 214 <listitem><para>Saves the zoomed view to an image file.</para></listitem>
 215 </varlistentry>
 216
 217 <varlistentry>
 218 <term><menuchoice>
 219 <shortcut>
 220 <keycombo action="simul">&Ctrl;
 221 <keycap>P</keycap></keycombo>
 222 </shortcut>
 223 <guimenu>File</guimenu>
 224 <guimenuitem>Print...</guimenuitem>
 225 </menuchoice></term>
 226 <listitem><para>Prints the current zoomed view.</para></listitem>
 227 </varlistentry>
 228
 229 <varlistentry>
 230 <term><menuchoice>
 231 <shortcut>
 232 <keycombo action="simul">&Ctrl;
 233 <keycap>Q</keycap></keycombo>
 234 </shortcut>
 235 <guimenu>File</guimenu>
 236 <guimenuitem>Quit</guimenuitem>
 237 </menuchoice></term>
 238 <listitem><para>Quits the application</para></listitem>
 239 </varlistentry>
 240 </variablelist>
 241 </sect1>
 242
 243 <sect1 id="the-edit-menu">
 244 <title>The <guimenu>Edit</guimenu> Menu</title>
 245
 246 <variablelist>
 247
 248 <varlistentry>
 249 <term><menuchoice>
 250 <shortcut>
 251 <keycombo action="simul">&Ctrl;
 252 <keycap>C</keycap></keycombo>
 253 </shortcut>
 254 <guimenu>Edit</guimenu>
 255 <guimenuitem>Copy</guimenuitem>
 256 </menuchoice></term>
 257 <listitem><para>Copy the current zoomed view to the clipboard which
 258 you can paste in other applications.</para></listitem>
 259 </varlistentry>
 260 </variablelist>
 261 </sect1>
 262
 263 <sect1 id="the-view-menu">
 264 <title>The <guimenu>View</guimenu> Menu</title>
 265
 266 <variablelist>
 267
 268 <varlistentry>
 269 <term><menuchoice>
 270 <shortcut>
 271 <keycombo action="simul">
 272 <keycap>F5</keycap></keycombo>
 273 </shortcut>
 274 <guimenu>View</guimenu>
 275 <guimenuitem>Start/Stop</guimenuitem>
 276 </menuchoice></term>
 277 <listitem><para>Start/Stop updating of the display.
 278 Stopping the update will zero the processing power required (CPU
 279 usage)</para></listitem>
 280 </varlistentry>
 281
 282 <varlistentry>
 283 <term><menuchoice>
 284 <guimenu>View</guimenu>
 285 <guimenuitem>Zoom</guimenuitem>
 286 </menuchoice></term>
 287 <listitem><para>Select the zoom factor.</para></listitem>
 288 </varlistentry>
 289
 290 <varlistentry>
 291 <term><menuchoice>
 292 <shortcut>
 293 <keycombo action="simul">&Ctrl;
 294 <keycap>-</keycap></keycombo>
 295 </shortcut>
 296 <guimenu>View</guimenu>
 297 <guimenuitem>Zoom Out</guimenuitem>
 298 </menuchoice></term>
 299 <listitem><para>Click on this button to zoom-out on the selected region.</para></listitem>
 300 </varlistentry>
 301
 302 <varlistentry>
 303 <term><menuchoice>
 304 <shortcut>
 305 <keycombo action="simul">&Ctrl;
 306 <keycap>+</keycap></keycombo>
 307 </shortcut>
 308 <guimenu>View</guimenu>
 309 <guimenuitem>Zoom In</guimenuitem>
 310 </menuchoice></term>
 311 <listitem><para>Click on this button to zoom-in on the selected region.</para></listitem>
 312 </varlistentry>
 313
 314 <varlistentry>
 315 <term><menuchoice>
 316 <shortcut>
 317 <keycombo action="simul">
 318 <keycap>F6</keycap></keycombo>
 319 </shortcut>
 320 <guimenu>View</guimenu>
 321 <guimenuitem>Invert Colors</guimenuitem>
 322 </menuchoice></term>
 323 <listitem><para><action>Inverts</action> colors on the view, &ie; black things will be shown white.</para></listitem>
 324 </varlistentry>
 325
 326 <varlistentry>
 327 <term><menuchoice>
 328 <guimenu>View</guimenu>
 329 <guimenuitem>Rotation</guimenuitem>
 330 </menuchoice></term>
 331 <listitem><para>Select the rotation degree (<guimenuitem>No Rotation (0 Degrees)</guimenuitem>,
 332 <guimenuitem>Left (90 Degrees)</guimenuitem>, <guimenuitem>Upside Down (180 Degrees)</guimenuitem>,
 333 <guimenuitem>Right (270 Degrees)</guimenuitem>.</para></listitem>
 334 </varlistentry>
 335
 336 <varlistentry>
 337 <term><menuchoice>
 338 <guimenu>View</guimenu>
 339 <guimenuitem>Refresh</guimenuitem>
 340 </menuchoice></term>
 341 <listitem><para>Select the refresh rate (<guimenuitem>Very Low</guimenuitem>,
 342 <guimenuitem>Low</guimenuitem>, <guimenuitem>Medium</guimenuitem>,
 343 <guimenuitem>High</guimenuitem>, <guimenuitem>Very High</guimenuitem>).
 344 The higher the rate, the more computing power (CPU)
 345 will be needed.</para></listitem>
 346 </varlistentry>
 347 </variablelist>
 348 </sect1>
 349
 350 <sect1 id="the-settings-menu">
 351 <title>The <guimenu>Settings</guimenu> Menu</title>
 352
 353 <variablelist>
 354
 355 <varlistentry>
 356 <term><menuchoice>
 357 <shortcut>
 358 <keycombo action="simul">&Ctrl;
 359 <keycap>M</keycap></keycombo>
 360 </shortcut>
 361 <guimenu>Settings</guimenu>
 362 <guimenuitem>Show/Hide Menu</guimenuitem>
 363 </menuchoice></term>
 364 <listitem><para>Toggles the menubar on/off.</para></listitem>
 365 </varlistentry>
 366
 367 <varlistentry>
 368 <term><menuchoice>
 369 <guimenu>Settings</guimenu>
 370 <guimenuitem>Show/Hide Main Toolbar</guimenuitem>
 371 </menuchoice></term>
 372 <listitem><para>Toggles the main toolbar on/off.</para></listitem>
 373 </varlistentry>
 374
 375 <varlistentry>
 376 <term><menuchoice>
 377 <guimenu>Settings</guimenu>
 378 <guimenuitem>Show/Hide View Toolbar</guimenuitem>
 379 </menuchoice></term>
 380 <listitem><para>Toggles the view toolbar on/off.</para></listitem>
 381 </varlistentry>
 382
 383 <varlistentry>
 384 <term><menuchoice>
 385 <guimenu>Settings</guimenu>
 386 <guimenuitem>Show/Hide Settings Toolbar</guimenuitem>
 387 </menuchoice></term>
 388 <listitem><para>Toggles the settings toolbar on/off.</para></listitem>
 389 </varlistentry>
 390
 391 <varlistentry>
 392 <term><menuchoice>
 393 <shortcut>
 394 <keycombo action="simul">
 395 <keycap>F1</keycap></keycombo>
 396 </shortcut>
 397 <guimenu>Settings</guimenu>
 398 <guimenuitem>Follow Mouse Mode</guimenuitem>
 399 </menuchoice></term>
 400 <listitem><para>In this mode the area around the mouse cursor is shown in a normal window.</para></listitem>
 401 </varlistentry>
 402
 403 <varlistentry>
 404 <term><menuchoice>
 405 <shortcut>
 406 <keycombo action="simul">
 407 <keycap>F2</keycap></keycombo>
 408 </shortcut>
 409 <guimenu>Settings</guimenu>
 410 <guimenuitem>Selection Window Mode</guimenuitem>
 411 </menuchoice></term>
 412 <listitem><para>In this mode a selection window is opened. The selected area is shown in a normal window.</para></listitem>
 413 </varlistentry>
 414
 415 <varlistentry>
 416 <term><menuchoice>
 417 <guimenu>Settings</guimenu>
 418 <guimenuitem>Top Screen Edge Mode</guimenuitem>
 419 </menuchoice></term>
 420 <listitem><para>In this mode the area around the mouse is magnified to the top screen edge.</para></listitem>
 421 </varlistentry>
 422
 423 <varlistentry>
 424 <term><menuchoice>
 425 <guimenu>Settings</guimenu>
 426 <guimenuitem>Left Screen Edge Mode</guimenuitem>
 427 </menuchoice></term>
 428 <listitem><para>In this mode the area around the mouse is magnified to the left screen edge.</para></listitem>
 429 </varlistentry>
 430
 431 <varlistentry>
 432 <term><menuchoice>
 433 <guimenu>Settings</guimenu>
 434 <guimenuitem>Right Screen Edge Mode</guimenuitem>
 435 </menuchoice></term>
 436 <listitem><para>In this mode the area around the mouse is magnified to the right screen edge.</para></listitem>
 437 </varlistentry>
 438
 439 <varlistentry>
 440 <term><menuchoice>
 441 <guimenu>Settings</guimenu>
 442 <guimenuitem>Bottom Screen Edge Mode</guimenuitem>
 443 </menuchoice></term>
 444 <listitem><para>In this mode the area around the mouse is magnified to the bottom screen edge.</para></listitem>
 445 </varlistentry>
 446
 447 <varlistentry>
 448 <term><menuchoice>
 449 <shortcut>
 450 <keycombo action="simul">
 451 <keycap>F4</keycap></keycombo>
 452 </shortcut>
 453 <guimenu>Settings</guimenu>
 454 <guimenuitem>Show/Hide Mouse Cursor</guimenuitem>
 455 </menuchoice></term>
 456 <listitem><para>Show or hide the mouse cursor in the magnified image.</para></listitem>
 457 </varlistentry>
 458
 459 <varlistentry>
 460 <term><menuchoice>
 461 <guimenu>Settings</guimenu>
 462 <guimenuitem>Configure Shortcuts...</guimenuitem>
 463 </menuchoice></term>
 464 <listitem><para>Opens a window that lets you configure the keyboard
 465 shortcuts for many menu commands.</para></listitem>
 466 </varlistentry>
 467
 468 <varlistentry>
 469 <term><menuchoice>
 470 <guimenu>Settings</guimenu>
 471 <guimenuitem>Configure Toolbars...</guimenuitem>
 472 </menuchoice></term>
 473 <listitem><para>Opens a window that lets you choose which icons are visible
 474 in the toolbar.</para></listitem>
 475 </varlistentry>
 476 </variablelist>
 477 </sect1>
 478
 479 <sect1 id="the-help-menu">
 480 <title>The <guimenu>Help</guimenu> Menu</title>
 481
 482 &help.menu.documentation;
 483
 484 </sect1>
 485 </chapter>
 486
 487 <chapter id="commands">
 488 <title>Command Reference</title>
 489
 490 <para>&kmag; automatically uses all your default shortcuts for saving
 491 file, opening new window, printing, starting/stopping refresh (reload
 492 button in &konqueror;), zoom-in, zoom-out &etc;</para>
 493
 494 <table>
 495 <title>Default Keyboard Shortcuts</title>
 496 <tgroup cols="2">
 497 <tbody>
 498 <row>
 499 <entry><keycombo>&Ctrl;<keycap>S</keycap></keycombo></entry>
 500 <entry><para>This will save the contents of the zoom window to a
 501 file.</para>
 502 </entry>
 503 </row>
 504 <row>
 505 <entry><keycap>F1</keycap></entry>
 506 <entry><para>Switch to "Follow Mouse Mode".</para>
 507 </entry>
 508 </row>
 509 <row>
 510 <entry><keycap>F2</keycap></entry>
 511 <entry><para>Switch to "Selection Window Mode".</para>
 512 </entry>
 513 </row>
 514 <row>
 515 <entry><keycap>F4</keycap></entry>
 516 <entry><para>Show or hide the mouse cursor in the magnified image.</para>
 517 </entry>
 518 </row>
 519 <row>
 520 <entry><keycap>F5</keycap></entry>
 521 <entry><para>This will start the refresh of the zoom window if it is
 522 stopped, or stops the refresh of the zoom window if the refresh is
 523 currently on.</para>
 524 </entry>
 525 </row>
 526 <row>
 527 <entry><keycap>F6</keycap></entry>
 528 <entry><para>Invert Colors</para>
 529 </entry>
 530 </row>
 531 <row>
 532 <entry><keycombo>&Ctrl;<keycap>N</keycap></keycombo></entry>
 533 <entry><para>This will open a new &kmag; window.</para></entry>
 534 </row>
 535 <row>
 536 <entry><keycombo>&Ctrl;<keycap>P</keycap></keycombo></entry>
 537 <entry><para>This will open the print dialog for printing the contents
 538 of the zoom window.</para></entry>
 539 </row>
 540 <row>
 541 <entry><keycombo>&Ctrl;<keycap>C</keycap></keycombo></entry>
 542 <entry><para>This will copy the zoom window contents to the
 543 clipboard.</para>
 544 </entry>
 545 </row>
 546 <row>
 547 <entry><keycombo>&Ctrl;<keycap>M</keycap></keycombo></entry>
 548 <entry><para>Show/Hide the menubar.</para>
 549 </entry>
 550 </row>
 551 <row>
 552 <entry><keycombo>&Ctrl;<keycap>-</keycap></keycombo></entry>
 553 <entry><para>Zoom out</para></entry>
 554 </row>
 555 <row>
 556 <entry><keycombo>&Ctrl;<keycap>+</keycap></keycombo></entry>
 557 <entry><para>Zoom in</para></entry>
 558 </row>
 559 <row>
 560 <entry><keycombo>&Ctrl;<keycap>Q</keycap></keycombo></entry>
 561 <entry><para>Quits the application.</para></entry>
 562 </row>
 563 </tbody>
 564 </tgroup>
 565
 566 </table>
 567
 568 </chapter>
 569
 570 <!--
 571 <chapter id="faq">
 572 <title>Questions and Answers</title>
 573
 574 &reporting.bugs;
 575 &updating.documentation;
 576
 577 <para>
 578 This section is currently empty as I have not received any questions from any users! I
 579 will add some FAQ if I hear from any of the users.
 580 </para>
 581
 582 </chapter>
 583 -->
 584 <chapter id="credits">
 585
 586 <!-- Include credits for the programmers, documentation writers, and
 587 contributors here. The license for your software should then be included below
 588 the credits with a reference to the appropriate license file included in the KDE
 589 distribution. -->
 590
 591 <title>Credits and License</title>
 592
 593 <para>
 594 &kmag;
 595 </para>
 596 <para>
 597 Program copyright 2001-2003 Sarang Lakare <email>sarang@users.sf.net</email> and 2003-2005 Olaf Schmidt <email>ojschmidt@kde.org</email>.
 598 </para>
 599 <para>
 600 Contributors:
 601 <itemizedlist>
 602 <listitem><para>Michael Forster <email>forster@fmi.uni-passau.de</email> (original author)</para></listitem>
 603 </itemizedlist>
 604 </para>
 605
 606
 607 <para>
 608 Documentation copyright 2002 Sarang Lakare <email>sarang@users.sf.net</email> and
 609 2004-2005 Olaf Schmidt <email>ojschmidt@kde.org</email>
 610 </para>
 611
 612 <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
 613 &underFDL;               <!-- FDL: do not remove. Commercial development should -->
 614 &underGPL;               <!-- GPL License -->
 615
 616 </chapter>
 617
 618 <appendix id="installation">
 619 <title>Installation</title>
 620
 621 <sect1 id="getting-kmag">
 622 <title>How to obtain &kmag;</title>
 623
 624 &install.intro.documentation;
 625
 626 </sect1>
 627
 628 <sect1 id="compilation">
 629 <title>Compilation and Installation</title>
 630
 631 &install.compile.documentation;
 632
 633 </sect1>
 634
 635 </appendix>
 636
 637 &documentation.index;
 638 </book>
 639 <!--
 640 Local Variables:
 641 mode: sgml
 642 sgml-minimize-attributes:nil
 643 sgml-general-insert-case:lower
 644 sgml-indent-step:0
 645 sgml-indent-data:nil
 646 End:
 647 -->