.. index:: Layout; Scale bar, Map scalebar
.. _layout_scalebar_item:

The Scale Bar Item
==================

.. only:: html

   .. contents::
      :local:

Scale bars provide a visual indication of the size of features, and distance
between features, on the map item. A scale bar item requires a map item.
Use the |scaleBar| :guilabel:`Add Scale Bar` tool following :ref:`items creation
instructions <create_layout_item>` to add a new scale bar item that you can
later manipulate the same way as exposed in :ref:`interact_layout_item`.

By default, a new scale bar item shows the scale of the map item over which
it is drawn. If there is no map item below, the :ref:`reference map <reference_map>` is
used. You can customize it in the :guilabel:`Item Properties` panel.
Other than the :ref:`items common properties <item_common_properties>`, this
feature has the following functionalities (see figure_layout_scalebar_):

.. _figure_layout_scalebar:

.. figure:: img/scalebar_properties.png
   :align: center

   Scale Bar Item Properties Panel

Main properties
---------------

The :guilabel:`Main properties` group of the scale bar
:guilabel:`Item Properties` panel provides the following functionalities
(see figure_layout_scalebar_ppt_):

.. _figure_layout_scalebar_ppt:

.. figure:: img/scalebar_mainproperties.png
   :align: center

   Scale Bar Main properties group

#. First, choose the map the scale bar will be attached to
#. Then, choose the style of the scale bar. Six styles are available:

   * **Single box** and **Double box** styles, which contain one or two lines
     of boxes alternating colors;
   * **Middle**, **Up** or **Down** line ticks;
   * **Numeric**, where the scale ratio is printed (e.g., ``1:50000``).
#. Set properties as appropriate

Units and Segments
------------------

The :guilabel:`Units` and :guilabel:`Segments` groups of the scale bar
:guilabel:`Item Properties` panel (not available for the **Numeric** style)
provide the following functionalities (see figure_layout_scalebar_units_):

.. _figure_layout_scalebar_units:

.. figure:: img/scalebar_units.png
   :align: center

   Scale Bar Units and Segments groups

In these two groups, you can set how the scale bar will be represented.

* Select the units you want to use with :guilabel:`Scalebar units`. There are
  many possible choices: **Map Units** (the default one), **Meters**, **Feet**,
  **Miles** or **Nautical Miles**... which may force unit conversions.
* The :guilabel:`Label unit multiplier` specifies how many scale bar units per
  labeled unit. Eg, if your scale bar units are set to "meters", a multiplier of
  1000 will result in the scale bar labels in "kilometers".
* The :guilabel:`Label for units` field defines the text used to describe the
  units of the scale bar, eg ``m`` or ``km``. This should be matched to reflect
  the multiplier above.
* You can define how many :guilabel:`Segments` will be drawn on the left and on
  the right side of the scale bar.
* You can set how long each segment will be (:guilabel:`Fixed width`), or limit
  the scale bar size in ``mm`` with :guilabel:`Fit segment width` option. In the
  latter case, each time the map scale changes, the scale bar is resized (and
  its label updated) to fit the range set.
* :guilabel:`Height` is used to define the height of the bar.

Display
--------

The :guilabel:`Display` group of the scale bar :guilabel:`Item Properties`
panel provides the following functionalities (see
figure_layout_scalebar_display_):

.. _figure_layout_scalebar_display:

.. figure:: img/scalebar_display.png
   :align: center

   Scale Bar Display group

You can define how the scale bar will be displayed in its frame.

* :guilabel:`Box margin` : space between text and frame borders
* :guilabel:`Label margin` : space between text and scale bar drawing
* :guilabel:`Vertical label placement`: it can be above or below the scale bar
  segment
* :guilabel:`Horizontal label placement`: which would be centered at the scale
  bar segment's edge or center
* :guilabel:`Line width` : line width of the scale bar drawing
* :guilabel:`Join style` : Corners at the end of scale bar in Bevel, Miter or
  Round style (only available for Scale bar style Single Box & Double Box)
* :guilabel:`Cap style` : End of all lines in style Square, Round or Flat
  (only available for Scale bar style Line Ticks Up, Down and Middle)
* :guilabel:`Alignment` : Puts text on the left, center or right side of the
  frame (works only for Scale bar style Numeric)

Fonts and colors
-----------------

The :guilabel:`Fonts and colors` group of the scale bar
:guilabel:`Item Properties` panel provides the following functionalities
(see figure_layout_scalebar_fonts_):

.. _figure_layout_scalebar_fonts:

.. figure:: img/scalebar_fonts.png
   :align: center

   Scale Bar Fonts and colors groups

You can define the :ref:`fonts <font_selector>` and :ref:`colors <color-selector>`
used for the scale bar. These properties are data-definable.

* Use the :guilabel:`Font` button to set the :ref:`properties <text_format>`
  (size, font, color, letter spacing, shadow, background...) of the scale bar
  label.

  Example: The following code applied to the bold property of the scale labels
  will display texts in bold when they are a multiple of 500:

  ::

     -- returns True (or 1) if the value displayed on the bar
     -- is a multiple of 500

     @scale_value % 500 = 0

* :guilabel:`Fill color`: set the first fill color
* :guilabel:`Secondary fill color`: set the second fill color
* :guilabel:`Line color`: set the color of the lines of the Scale Bar

Fill colors are only used for *Single Box* and *Double Box* styles.


.. Substitutions definitions - AVOID EDITING PAST THIS LINE
   This will be automatically updated by the find_set_subst.py script.
   If you need to create a new substitution manually,
   please add it also to the substitutions.txt file in the
   source folder.

.. |scaleBar| image:: /static/common/mActionScaleBar.png
   :width: 1.5em