path: root/preferences.page

<page xmlns="http://projectmallard.org/1.0/"
      xmlns:e="http://projectmallard.org/experimental/"
      type="topic"
      id="preferences">

  <info>
    <link type="guide" xref="index#panel"/>
    <desc>Configure the <app>Xfce Panel</app></desc>
    <credit type="author">
      <name>Nick Schermer</name>
      <email>nick@xfce.org</email>
    </credit>
    <license>
      <p>Creative Commons Share Alike 3.0</p>
    </license>
  </info>

  <title>Preferences</title>

   <p>
     The Xfce panel preferences dialog gives you the ability
     to customize your panel. You can change the size, appearance,
     and orientation of your panels. You can also add or remove extra
     panels on your desktop.  
   </p> 

  <figure>
    <title>Panel Preferences Dialog</title>
    <media type="image" src="figures/preferences.png" mime="image/png" style="right"/>
  </figure>

  <section>
    <title>Accessing Panel Preferences</title>

    <p>
      The panel preferences can be opened by going to <guiseq>
      <gui>Settings</gui><gui>Panel</gui></guiseq> in your applications menu. 
      You can also access panel preferences by right clicking on your panel
      and going to <gui>Panel Settings</gui>. If you right click on space occupied by a 
      panel plugin, you can access panel preferences by going to <guiseq><gui>Panel</gui>
      <gui>Panel Preferences...</gui></guiseq>.
    </p>
  </section>
  
  <section>
    <title>Selecting a panel</title>
    
    <p>
      You can select a panel from the drop down list at the top of the dialog.
      Next to this are two buttons that can be used to remove (-) the currently 
      selected panel or add (+) a new empty panel.
    </p>
    
    <p>
      The panel selected in the dialog should also show a selection around
      the panel, so it is clear which panel you are editing.
    </p>
  </section>
  
  <section>
    <title>Display</title>
     
    <p>
      This tab hold the settings how the panel is positioned on the
      screen.
    </p>
    
    <section>
      <title>General</title>
      
      <terms>
        <item>
          <title><gui>Orientation</gui></title>
          <p>
            Set the panel orientation to horizontal or vertical.
          </p>
        </item>
        
        <item>
          <title><gui>Output</gui></title>
          <p>
            Select the output (such as an secondary monitor) on which this panel should appear. 
          If the output is not connected, the panel will not be shown.
          </p>
        </item>
        
        <item>
          <title><gui>Span monitors</gui></title>
          <p>
            If you have multiple monitors connected to the computer, this
            option will appear in the properties dialog. This will tell the panel
            to stretch across multiple monitors instead of only being restricted to
            one monitor. It look at the total screen size instead of the size of
            an individual monitor.
          </p>
        </item>
        
        <item>
          <title><gui>Lock panel</gui></title>
          <p>
            Don't show the handles on the panel which allow you to move
            the panel. When this option is disabled, you can drag the panel 
            anywhere you want on your screen. The panel will also snap to the 
            edges of your screen.
          </p>
        </item>
        
        <item>
          <title><gui>Automatically show and hide the panel</gui></title>
          <p>
            Automatically hide the panel if the mouse is not hovering over it.
          </p>
        </item>
      </terms>
    </section>
    
    <section>
      <title>Measurements</title>
      
      <terms>
        <item>
          <title><gui>Size</gui></title>
          <p>
            Change the height (or width if the orientation is vertical) 
            of the panel. The size is in pixels.
          </p>
        </item>
      
        <item>
          <title><gui>Length</gui></title>
          <p>
            Change the width (or height if the orientation is vertical) 
            of the panel. The size is a percentage of the monitor or
            screen size.
          </p>
        </item>
        
        <item>
          <title><gui>Automatically increase length</gui></title>
          <p>
            Increase the panel size to fit the contents of the panel. Is
            work with expanding plugins, like the <link xref="tasklist">
            window buttons</link> plugins.
          </p>
        </item>
      </terms>
    </section>
  </section>
  
  <section id="appearance">
    <title>Appearance</title>
    
    <p>
      This tab contains the style settings of the currently selected panel.
    </p>
    
    <section>
      <title>Background</title>
      
      <terms>
        <item>
          <title><gui>Style</gui></title>

          <p>
          This allows you to change the transparency, color, and background
          image of the panel. You have three options to choose from.
          </p>
        
          <terms>
            <item>
              <title><gui>None (user system style)</gui></title>
              <p>
                The panel inherits colors from the currently selected GTK+
                theme. You can view and change the current GTK+ theme by going to
                <guiseq><gui>Settings</gui><gui>Appearance</gui></guiseq>.
              </p>
            </item>
            
            <item>
              <title><gui>Solid Color</gui></title>
              <p>
                You can select a color using the provided color picker. 
                The color you select will be applied to the panel.
              </p>
            </item>
            
            <item>
              <title><gui>Background Image</gui></title>
              <p>
                Select a background for your panel.
              </p>
            </item>
          </terms>
        </item>
        
        <item>
          <title><gui>Alpha</gui></title>
          <p>
            Change the alpha transparency of the panel.
            Some panel plugins may still retain a non-transparent background.
            This option is only available if your panel style is set to <gui>None</gui>
            or <gui>Solid Color</gui>.
          </p>
          
          <note>
            <p>
              The opacity and alpha settings are only available if the X server supports
              compositing and this is enabled in the window manager. To enabled this in Xfwm4
              activate <guiseq><gui>Settings</gui><gui>Window Manager Tweaks</gui>
              <gui>Compositor</gui><gui>Enable display compositing</gui></guiseq>
              from the applications menu.
            </p>
          </note>
        </item>
        
        <item>
          <title><gui>Color</gui></title>
          <p>
            Clicking this activates a color picker. You can select a color
            by using the color wheel, entering a hex value, or entering a color
            name. This option is only available if your panel style is set to
            <gui>Solid Color</gui>.
          </p>
        </item>
        
        <item>
          <title><gui>File</gui></title>
          <p>
            This allows you to select a background for the panel using
            a file browser. This option is only available if your panel style
            is set to <gui>Background Image</gui>.
          </p>
        </item>
      </terms>
    </section>
    
    <section>
      <title>Opacity</title>
      <p>
        These options set the transparency of the entire panel.
      </p>
      <terms>
        <item>
          <title><gui>Enter</gui></title>
          <p>
            This controls the transparency of the panel when a mouse pointer is
            not hovering over it. Ranges from 0 (fully transparent) and 100 (fully opaque).
            All panel plugins will be affected by this setting.
          </p>
        </item>
      
        <item>
          <title><gui>Leave</gui></title>
          <p>
            This controls the transparency of the panel when a mouse pointer is
            not hovering over it. Ranges from 0 (fully transparent) and 
            100 (fully opaque). All panel plugins will be affected by this setting.
          </p>
        </item>
      </terms>
    </section>
  </section>
  
  <section>
    <title>Items</title>
    
    <p>
      This shows the items that are placed on the currently selected panel.
      In case items are hard to move or edit on the panel using the
      right-click menu, this tab allows you to move, add, remove and access
      the preferences of the items on the panel.
    </p>
    
    <p>
      This tab contains a row of buttons that allow you to manipulate the items
      on the panel.
    </p>
    
    <p>
      With the <gui>up</gui> and <gui>down</gui> buttons you can move the currently selected 
      item in the panel.
    </p>
    
    <p>
      The <gui>add</gui> button opens the <link xref="add-new-items">add new items
      dialog</link>. With the <gui>remove</gui> button you can remove the currently
      selected item from the panel.
    </p>
    
    <p>
      The <gui>preferences</gui> and <gui>about</gui> buttons are only active if the plugin
      support these features. It will open the selected items' settings.
    </p>
    
    <p>
      Only limitation in this dialog, compared to mouse handling, is that
      you cannot move items between panels and access custom menu items
      a plugin can add in the item menu.
    </p>
  </section>

  <section>
    <title>Hidden Properties</title>
    
    <terms>
      <item>
        <title>disable-struts</title>
        <p>
          When the panel is snapped to a monitor edge and it is not between
          two monitors on the same screen, it will avoid windows from overlapping
          the panel (ie. the window manager will reserve space for the panel).
        </p>
        
        <p>
          This behavior can be disabled per-panel with the xfconf property
          <var>disable-struts</var>. This can be changed with <app>xfconf-query</app>
          like the command below. Remember to replace <var>panel-0</var> with the
          appropriate panel number, which is the number of the panel in the preferences
          dialog minus one.
        </p>
        
        <p>
          <cmd>xfconf-query -c xfce4-panel -p /panels/panel-0/disable-struts -t bool -n -s true</cmd>
        </p>
      </item>
    </terms>
  </section>
  
  <section>
    <title>Style Settings</title>
    
    <terms>
      <item>
        <title>Class <em>PanelWindow</em></title>
        <terms>
          <item>
            <title><var>popup-delay</var></title>
            <p>Control the popup delay of a hidden panel in milliseconds. Defaults to 225.</p>
          </item>
          <item>
            <title><var>popdown-delay</var></title>
            <p>Control the popdown delay of a hidden panel in milliseconds. Defaults to 350.</p>
          </item>
        </terms>
      </item>
    </terms>
  </section>
</page>