.. index::
   single: SCALEBAR

.. _scalebar:

*****************************************************************************
 SCALEBAR
*****************************************************************************

Scalebars currently do not make use of TrueType fonts. The size of the 
scalebar image is NOT known prior to rendering, so be careful not to 
hard-code width and height in the <IMG> tag in the template file. Future 
versions will make the image size available.

.. index::
   pair: SCALEBAR; ALIGN

ALIGN [left|center|right]
    Defines how the scalebar is aligned within the scalebar image. Default 
    is center. Available in versions 5.2 and higher.
    
    .. versionadded:: 5.2

.. index::
   pair: SCALEBAR; BACKGROUNDCOLOR

BACKGROUNDCOLOR [r] [g] [b]
    Color to use for scalebar background, not the image background.

.. index::
   pair: SCALEBAR; COLOR

COLOR [r] [g] [b]
    Color to use for drawing all features if attribute tables are not used.

.. index::
   pair: SCALEBAR; IMAGECOLOR

IMAGECOLOR [r] [g] [b]
    Color to initialize the scalebar with (i.e. background).

INTERLACE [true|false]
    Should output images be interlaced? Default is [on]. This keyword is 
    now deprecated in favour of using the FORMATOPTION "INTERLACE=ON" line 
    in the :ref:`OUTPUTFORMAT` declaration.
    
    .. deprecated:: 4.6

.. index::
   pair: SCALEBAR; INTERVALS

INTERVALS [integer]
    Number of intervals to break the scalebar into. Default is 4.

.. index::
    pair: SCALEBAR; LABEL

:ref:`LABEL`
    Signals the start of a :ref:`LABEL` object.

.. index::
   pair: SCALEBAR; OUTLINECOLOR

OUTLINECOLOR [r] [g] [b]
    Color to use for outlining individual intervals. Set any component 
    to -1 for no outline which is the default.

.. index::
   pair: SCALEBAR; POSITION

POSITION [ul|uc|ur|ll|lc|lr]
    Where to place an embedded scalebar in the image. Default is lr.

.. index::
   pair: SCALEBAR; POSTLABELCACHE

POSTLABELCACHE [true|false]
    For use with embedded scalebars only. Tells the MapServer to embed the 
    scalebar after all labels in the cache have been drawn. Default is false.

.. index::
   pair: SCALEBAR; SIZE

SIZE [x][y]
    Size in pixels of the scalebar. Labeling is not taken into account.

.. index::
   pair: SCALEBAR; STATUS

STATUS [on|off|embed]
    Is the scalebar image to be created, and if so should it be embedded into 
    the image? Default is off. (Please note that embedding scalebars require 
    that you define a markerset. In essence the scalebar becomes a custom 
    marker that is handled just like any other annotation.) 

.. index::
   pair: SCALEBAR; STYLE

STYLE [integer]
    Chooses the scalebar style. Valid styles are 0 and 1.

TRANSPARENT [on|off]
    Should the background color for the scalebar be transparent. This flag is 
    now deprecated in favor of declaring transparency within :ref:`OUTPUTFORMAT`
    declarations. Default is off.
    
    .. deprecated:: 4.6

.. index::
   pair: SCALEBAR; UNITS

.. index::
   triple: SCALEBAR; UNITS; feet

.. index::
   triple: SCALEBAR; UNITS; inches

.. index::
   triple: SCALEBAR; UNITS; kilometers

.. index::
   triple: SCALEBAR; UNITS; meters

.. index::
   triple: SCALEBAR; UNITS; miles

.. index::
   triple: SCALEBAR; UNITS; nauticalmiles

UNITS [feet|inches|kilometers|meters|miles|nauticalmiles]
    Output scalebar units, default is miles. Used in conjunction with the 
    map's units to develop the actual graphic. Note that decimal degrees 
    are not valid scalebar units. `Nauticalmiles` was added in MapServer 5.6.