<page xmlns="http://projectmallard.org/1.0/" type="topic" id="preferences_magnifier">
  <info>
    <link type="guide" xref="preferences#orca" />
    <link type="next" xref="preferences_key_bindings" />
    <title type="sort">5. Magnifier</title>
    <title type="link">Magnifier</title>
    <desc>
      Configuring the zoom window appearance
    </desc>
    <credit type="author">
      <name>Joanmarie Diggs</name>
      <email>joanied@gnome.org</email>
    </credit>
    <license>
      <p>Creative Commons Share Alike 3.0</p>
    </license>
  </info>
  <title>Magnifier Preferences</title>
  <section id="enable_magnifier">
    <title>Enable Magnifier</title>
    <media type="image" mime="image/png" src="figures/preferences_enable_magnifier.png"/>
    <p>
      The <gui>Enable magnifier</gui> check box enables and disables
      <app>Orca</app>'s magnification support. When it is unchecked,
      the other widgets on this page become unavailable.
    </p>
    <p>
      Default value: not checked
    </p>
  </section>
  <section id="zoomer">
    <title>Zoomer</title>
    <media type="image" mime="image/png" src="figures/preferences_zoomer.png"/>
    <p>
      The <gui>Zoomer</gui> options allow you to customize the magnifier's
      level, position, and size, as well as to hide the system pointer.
    </p>
    <section>
      <title>Scale factor</title>
      <p>
        <gui>Scale factor</gui> can be used to set the magnification
        level from 1.0x to 16.0x (fractional values are supported).
      </p>
    </section>
    <section>
      <title>Position</title>
      <p>
        <gui>Position</gui> can be used to specify the placement of the
        magnifier on your screen. The available positions are: <gui>Full
        Screen</gui>, <gui>Left Half</gui>, <gui>Right Half</gui>, <gui>Top
        Half</gui>, <gui>Bottom Half</gui>, and <gui>Custom</gui>.
      </p>
      <p>
        Default value: <gui>Full Screen</gui>
      </p>
    </section>
    <section>
      <title>Specifying the Bounds of a "Custom" Zoomer</title>
      <p>
        Choosing a <gui>Position</gui> of <gui>Custom</gui> causes four spin
        buttons to become available: <gui>Top</gui>, <gui>Left</gui>, <gui>Right
        </gui>, and <gui>Bottom</gui>.
      </p>
      <p>
        These spin buttons allow you to define the location of each edge of the
        zoom window. Units are in pixels.
      </p>
    </section>
    <section>
      <title>Hide system pointer</title>
      <p>
        The <gui>Hide system pointer</gui> checkbox will hide the unmagnified
        pointer, leaving just the magnified one visible.
      </p>
      <p>
        Default value: unchecked
      </p>
    </section>
  </section>
  <section id="tracking_and_alignment">
      <title>Tracking and Alignment</title>
      <media type="image" mime="image/png" src="figures/preferences_tracking_and_alignment.png"/>
      <p>These options control the tracking of the mouse cursor.</p>
      <section id="mouse_pointer">
        <title>Mouse Pointer</title>
        <p>
          The <gui>Mouse Pointer</gui> combo box allows you to select
          your tracking and alignment from the following options:
        </p>
        <list>
          <item>
            <p>
              <gui>Centered</gui>: Keeps the mouse pointer at the center
              of the screen whenever possible.
            </p>
          </item>
          <item>
            <p>
              <gui>Proportional</gui>: Positions the mouse pointer in the
              zoom window relative to its actual, unmagnified position. For
              instance, if the mouse pointer is 25% away from the left edge
              of the desktop, <app>Orca</app> positions the magnified mouse
              pointer 25% from the left edge of the zoom window.
           </p>
         </item>
         <item>
            <p>
              <gui>Push</gui>: Moves the zoomer window the least amount
              necessary to keep the mouse pointer on the screen.
            </p>
        </item>
        <item>
          <p>
            <gui>None</gui>: Moving the mouse pointer has no impact on
            what the zoomer window displays.
          </p>
        </item>
      </list>
      <p>
        Default value: <gui>Centered</gui>
      </p>
    </section>
    <section>
      <title>Pointer follows zoomer</title>
      <p>
        The <gui>Pointer follows zoomer</gui> checkbox allows you to
        customize what should occur if the mouse pointer is not on the
        screen when you initially move the mouse. With this option
        enabled, if the mouse pointer is not on the screen when you
        initially move the mouse, it will be moved into the zoomer
        so that you can continue to see what you were working on. If
        your preferred mouse tracking mode is centered, the pointer
        will be moved to the center; otherwise it will be moved to the
        item with focus.
      </p>
      <p>
        Default value: checked
      </p>
    </section>
    <section id="control_and_menu_item">
      <title>Control and menu item</title>
      <p>These options control additional behavior of the magnifier.</p>
      <list>
        <item>
          <p>
            <gui>Centered</gui>: When navigating via keyboard, keep
            the focused dialog box control or menu item at the center
            of the screen whenever possible.
          </p>
        </item>
        <item>
          <p>
            <gui>Push</gui>: When navigating via keyboard, move the
            zoomer window the least amount necessary to display the
            focused dialog box control or menu item.
          </p>
        </item>
        <item>
          <p>
            <gui>None</gui>: Using the keyboard to navigate among
            dialog box controls and menu items will have no impact
            on what the zoomer window displays.
          </p>
        </item>
      </list>
      <p>
        Default value: <gui>Push</gui>
      </p>
    </section>
    <section>
      <title>Pointer follows focus</title>
      <p>
        <gui>Pointer follows focus</gui>: If this option is enabled,
        the mouse pointer will follow you as you arrow through menu
        items and move among controls in dialog boxes. 
      </p>
      <p>
        Default value: not checked
      </p>
    </section>
    <section id="text_cursor">
      <title>Text cursor</title>
      <p>These options control how the text cursor behaves.</p>
      <list>
        <item>
          <p>
            <gui>Centered</gui>: As the text cursor moves, keep it at
            the center of the screen whenever possible.
          </p>
        </item>
        <item>
          <p>
            <gui>Push</gui>: As the text cursor moves, move the zoomer
            window the least amount necessary to display it.
          </p>
        </item>
        <item>
          <p>
            <gui>None</gui>: Moving the text cursor will have no impact
            on what the zoomer window displays.
          </p>
        </item>
      </list>
      <p>
        Default value: <gui>Push</gui>
      </p>
    </section>
    <section>
      <title>Edge margin</title>
      <p>
        The <gui>Edge margin</gui> is how close the caret should be allowed to
        get to the edge of the screen before it's time to "push" the zoomer
        window. The margin can range from 0 to 50%, with 50% being the
        equivalent of choosing centering.
      </p>
      <note style="tip">
        <p>
          This option is only available if "Push" is your text cursor tracking
          mode.
        </p>
      </note>
      <p>
        Default value: 0
      </p>
    </section>
  </section>
  <section id="color">
    <title>Color</title>
    <media type="image" mime="image/png" src="figures/preferences_color.png"/>
    <p>
      The <gui>Color</gui> options allow you to do some rough color
      adjustments of the magnified region.
    </p>
    <section>
      <title>Invert colors</title>
      <p>
        <gui>Invert colors</gui>: Creates a reverse or negative-image effect.
      </p>
      <p>
        Default value: not checked
      </p>
    </section>
    <section>
      <title>Brightness</title>
      <p>
        <gui>Brightness</gui>: Ranges from -1 to 1 (-1 is black/no
        brightness; 1 is white/total brightness; 0 is "normal"/unchanged).
      </p>
      <p>
        Default value: 0.00
      </p>
    </section>
    <section>
      <title>Contrast</title>
      <p>
        <gui>Contrast</gui>: Ranges from -1 to 1 (-1 is grey/no contrast;
        1 is maximum contrast; 0 is "normal"/unchanged).
      </p>
      <p>
        Default value: 0.00
      </p>
    </section>
  </section>
  <section id="border">
    <media type="image" mime="image/png" src="figures/preferences_border.png"/>
    <title>Border</title>
    <p>
      The <gui>Border</gui> options can be used to customize the border
      which separates the magnified region from the non-magnified region.
      As such, these options are not available when <gui>Full Screen</gui>
      is selected.
    </p>
    <section>
      <title>Enable border</title>
      <p>
        <gui>Enable border</gui>: This option determines if a window
        border is visible for the magnifier.
      </p>
      <p>
        Default value: not checked
      </p>
    </section>
    <section>
      <title>Border size</title>
      <p>
        This value determines the size of the border in pixels.
      </p>
      <p>
        Default value: 1
      </p>
    </section>
    <section>
      <title>Border color</title>      
      <p>
        This value determines the color of the border.
      </p>
      <p>
        Default value: black
      </p>
    </section>
  </section>
  <section id="cursor">
    <title>Cursor</title>
    <media type="image" mime="image/png" src="figures/preferences_cursor.png"/>
    <p>
      These controls can be used to customize the size and color of the
      magnifier's cursor.
    </p>
    <section>
      <title>Enable cursor</title>
      <p>
        If this checkbox is checked then a cursor is visible and the size and
        color options become available.
      </p>
      <p>
        Default value: checked
      </p>
    </section>
    <section>
      <title>Custom size</title>
      <p>
        Check this checkbox if you would like to make the mouse pointer larger
        than it normally is.
      </p>
      <p>
        Default value: not checked
      </p>
    </section>
    <section>
      <title>Cursor size</title>
      <p>
        This value determines the size of the cursor in pixels.
      </p>
      <p>
        Default value: 32
      </p>
    </section>
    <section>
      <title>Cursor color</title>      
      <p>
        This value determines the color of the cursor.
      </p>
      <p>
        Default value: black
      </p>
    </section>
  </section>
  <section id="crosshair">
    <title>Cross-hair</title>
    <media type="image" mime="image/png" src="figures/preferences_cross-hair.png"/>
    <p>
      This set of controls can be used to customize the magnifier's optional
      area-targeting cursor.
    </p>
    <section>
      <title>Enable cross-hair</title>
      <p>
        If this checkbox is checked then the cross-hair is visible and the size
        and color options become available.
      </p>
      <p>
        Default value: checked
      </p>
    </section>
    <section>
      <title>Enable cross-hair clip</title>
      <p>
        If checked, the cross-hair will be "clipped" (removed) in the area
        immediately surrounding the mouse pointer.
      </p>
      <p>
        Default value: not checked
      </p>
    </section>
    <section>
      <title>Cross-hair size</title>
      <p>
        This control sets the thickness of the cross-hair in pixels.
      </p>
      <p>
        Default value: 16
      </p>
    </section>
    <section>
      <title>Cross-hair color</title>      
      <p>
        This value determines the color of the cross-hair.
      </p>
      <p>
        Default value: black
      </p>
    </section>
  </section>
  <section id="advanced">
    <title>Advanced</title>
    <media type="image" mime="image/png" src="figures/preferences_advanced_button.png"/>
    <p>
      If you press the <gui>Advanced</gui> button located near the bottom
      of the Magnifier page, you can further customize <app>Orca</app>'s
      magnification support.
    </p>
    <media type="image" mime="image/png" src="figures/preferences_magnifier_advanced.png"/>
    <list>
      <item><p><gui>Smoothing</gui>: Bilinear or none.</p></item>
      <item>
        <p>
          <gui>Brightness</gui>: Choosing different brightness levels
          for red, blue, and green allows you to create the color scheme
          that works best for you.
        </p>
      </item>
      <item>
        <p>
          <gui>Contrast</gui>: While not as significant as changes to
          brightness, choosing different contrast levels for red, blue,
          and green helps you to create the color scheme that works best
          for you.
        </p>
      </item>
      <item>
        <p>
          <gui>Color Filtering</gui>: Allows you to pick one of the
          colorblind filters available through libcolorblind. In order
          to take advantage of this feature you will need to install
          libcolorblind and then rebuild gnome-mag.
        </p>
      </item>
      <item>
        <p>
          <gui>Multi-Monitor Settings - Source Display</gui>: X Window
          System DISPLAY of what should be magnified. Written in the form
          ":0.x" where x is the number of the screen whose contents should
          be magnified.
        </p>
      </item>
      <item>
        <p>
          <gui>Multi-Monitor Settings - Target Display</gui>: X Window
          System DISPLAY of where to put the zoomer window. Written in
          the form ":0.y" where y is the number of the screen where the
          zoomer window should appear.
        </p>
      </item>
    </list>
  </section>
</page>
