<page xmlns="http://projectmallard.org/1.0/"
      type="topic" style="task"
      id="keyboard-layouts">
  <info>
    <link type="guide" xref="prefs-language"/>
    <link type="guide" xref="keyboard" group="i18n"/>

    <revision pkgversion="3.2.1" date="2011-10-03" status="final"/>

    <credit type="author">
      <name>Shaun McCance</name>
      <email>shaunm@gnome.org</email>
    </credit>

    <desc>Make your keyboard behave like a keyboard for another language.</desc>
    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>
  </info>

  <title>Use alternate keyboard layouts</title>

  <p>Keyboards come in hundreds of different layouts for different languages.
  Even for a single language, there are often multiple keyboard layouts, such
  as the Dvorak layout for English. You can make your keyboard behave like a
  keyboard with a different layout, regardless of the letters and symbols
  printed on the keys. This is useful if you often switch between multiple
  languages.</p>

  <steps>
    <item><p>Click your name on the top bar and select <gui>System Settings</gui>.</p></item>
    <item><p>Open <gui>Region and Language</gui> and select the <gui>Layouts</gui> tab.</p></item>
    <item><p>Click the <gui>+</gui> button, select a layout, and click <gui>Add</gui>.
    You can add at most four layouts.</p></item>
    <!--
    https://bugzilla.gnome.org/show_bug.cgi?id=640774
    -->
  </steps>

  <note style="sidebar">
    <p>You can preview an image of any layout by selecting it in the list and clicking
    <gui><media type="image" src="figures/input-keyboard-symbolic.png" width="16" height="16">preview</media></gui>,
    or by clicking <gui>Preview</gui> in the pop-up window when adding a layout.</p>
  </note>

  <p>When you add multiple layouts, you can quickly switch between them using
  the keyboard layout icon on the top bar. The top bar will display a short
  identifier for the current layout, such as <gui>en</gui> for the standard
  English layout. Click the layout indicator and select the layout you want to
  use from the menu.</p>

  <p>When you use multiple layouts, you can choose to have all windows use the
  same layout or to set a different layout for each window. Using a different
  layout for each window is useful, for example, if you're writing an article
  in another language in a word processor window. Your keyboard selection will
  be remembered for each window as you switch between windows.</p>

  <p>By default, new windows will use the default keyboard layout. You can
  instead choose to have them use the layout of the window you were last
  using. The default layout is the layout at the top of the list. Use the
  <gui>↑</gui> and <gui>↓</gui> buttons to move layouts up and down in
  the list.</p>

  <comment>
    <cite date="2011-09-24">shaunm</cite>
    <p>We're totally copping out on the custom options. That dialog is a
    monster, and needs a reference. Note that the options in there are
    dynamic from the X server. We might not get a definitive reference
    of everything ever, but let's do our best. Make a separate page.
    Don't clutter this page with that crap.</p>
    <p>Also, we should identify common uses of those options and create
    task pages for them.</p>
  </comment>

  <note>
   <title>Custom options</title>
   <p>
     You may want to add certain symbols to specific keys or adjust custom option and behaviors.  You can do this by clicking <gui>Options</gui>. 
   </p>
  </note>

  <section id="system">
    <info>
      <link type="seealso" xref="session-language#system"/>
    </info>
    <title>Change the system keyboard</title>

    <p>When you change your keyboard layout, you only change it for your account
    after you log in. You can also change the <em>system layouts</em>, the keyboard
    layouts used in places like the login screen.</p>

    <steps>
      <item><p>Change your keyboard layout, as described above.</p></item>
      <item><p>Select the <gui>System</gui> tab.</p></item>
      <item><p>Click <gui>Copy Settings</gui>.</p></item>
      <item><p><link xref="user-admin-explain">Administrative privileges</link> are
      required. Enter your password, or the password for the requested administrator
      account.</p></item>
    </steps>

    <p>The layouts are shown next to the <gui>Input source</gui> label.</p>

    <p>If you use multiple layouts, the login screen will present the keyboard
    layout menu on the top bar.</p>
  </section>
</page>
