diff --git a/lib/matplotlib/collections.py b/lib/matplotlib/collections.py index 684e15cdf854..0eec2c7ead90 100644 --- a/lib/matplotlib/collections.py +++ b/lib/matplotlib/collections.py @@ -670,27 +670,43 @@ def set_linestyle(self, ls): """ Set the linestyle(s) for the collection. - =========================== ================= - linestyle description - =========================== ================= - ``'-'`` or ``'solid'`` solid line - ``'--'`` or ``'dashed'`` dashed line - ``'-.'`` or ``'dashdot'`` dash-dotted line - ``':'`` or ``'dotted'`` dotted line - =========================== ================= + Parameters + ---------- + ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) or list thereof + If as list, the individual elements are assigned to the elements of the + collection. - Alternatively a dash tuple of the following form can be provided:: + Possible values: - (offset, onoffseq), + - A string: - where ``onoffseq`` is an even length tuple of on and off ink in points. + ======================================================= ================ + linestyle description + ======================================================= ================ + ``'-'`` or ``'solid'`` solid line + ``'--'`` or ``'dashed'`` dashed line + ``'-.'`` or ``'dashdot'`` dash-dotted line + ``':'`` or ``'dotted'`` dotted line + ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing + ======================================================= ================ - Parameters - ---------- - ls : str or tuple or list thereof - Valid values for individual linestyles include {'-', '--', '-.', - ':', '', (offset, on-off-seq)}. See `.Line2D.set_linestyle` for a - complete description. + - A tuple describing the start position and lengths of dashes and spaxces: + + (offset, onoffseq) + + where + + - *offset* is a float specifying the offset (in points); i.e. how much + is the dash pattern shifted. + - *onoffseq* is a sequence of on and off ink in points. There can be + arbitrary many pairs of on and off values. + + Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts + at the beginning of the line. It draws a 10 point long dash, + then a 5 point long space, then a 1 point long dash, followed by a 5 point + long space, and then the pattern repeats. + + For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`. """ # get the list of raw 'unscaled' dash patterns self._us_linestyles = mlines._get_dash_patterns(ls) diff --git a/lib/matplotlib/inset.py b/lib/matplotlib/inset.py index fb5bfacff924..aae640db6f81 100644 --- a/lib/matplotlib/inset.py +++ b/lib/matplotlib/inset.py @@ -126,26 +126,40 @@ def set_linestyle(self, ls): """ Set the linestyle of the rectangle and the connectors. - ======================================================= ================ - linestyle description - ======================================================= ================ - ``'-'`` or ``'solid'`` solid line - ``'--'`` or ``'dashed'`` dashed line - ``'-.'`` or ``'dashdot'`` dash-dotted line - ``':'`` or ``'dotted'`` dotted line - ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing - ======================================================= ================ + Parameters + ---------- + ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) + Possible values: - Alternatively a dash tuple of the following form can be provided:: + - A string: - (offset, onoffseq) + ======================================================= ================ + linestyle description + ======================================================= ================ + ``'-'`` or ``'solid'`` solid line + ``'--'`` or ``'dashed'`` dashed line + ``'-.'`` or ``'dashdot'`` dash-dotted line + ``':'`` or ``'dotted'`` dotted line + ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing + ======================================================= ================ - where ``onoffseq`` is an even length tuple of on and off ink in points. + - A tuple describing the start position and lengths of dashes and spaces: - Parameters - ---------- - ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} - The line style. + (offset, onoffseq) + + where + + - *offset* is a float specifying the offset (in points); i.e. how much + is the dash pattern shifted. + - *onoffseq* is a sequence of on and off ink in points. There can be + arbitrary many pairs of on and off values. + + Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts + at the beginning of the line. It draws a 10 point long dash, + then a 5 point long space, then a 1 point long dash, followed by a 5 point + long space, and then the pattern repeats. + + For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`. """ self._shared_setter('linestyle', ls) diff --git a/lib/matplotlib/lines.py b/lib/matplotlib/lines.py index 72c57bf77b5c..8a9d35966660 100644 --- a/lib/matplotlib/lines.py +++ b/lib/matplotlib/lines.py @@ -1149,7 +1149,7 @@ def set_linestyle(self, ls): Parameters ---------- - ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} + ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) Possible values: - A string: @@ -1164,13 +1164,23 @@ def set_linestyle(self, ls): ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing ======================================================= ================ - - Alternatively a dash tuple of the following form can be - provided:: + - A tuple describing the start position and lengths of dashes and spaces: (offset, onoffseq) - where ``onoffseq`` is an even length tuple of on and off ink - in points. See also :meth:`set_dashes`. + where + + - *offset* is a float specifying the offset (in points); i.e. how much + is the dash pattern shifted. + - *onoffseq* is a sequence of on and off ink in points. There can be + arbitrary many pairs of on and off values. + + Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts + at the beginning of the line. It draws a 10 point long dash, + then a 5 point long space, then a 1 point long dash, followed by a 5 point + long space, and then the pattern repeats. + + See also :meth:`set_dashes`. For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`. """ diff --git a/lib/matplotlib/patches.py b/lib/matplotlib/patches.py index ec8f55d20ac8..9cebe14f01eb 100644 --- a/lib/matplotlib/patches.py +++ b/lib/matplotlib/patches.py @@ -468,26 +468,40 @@ def set_linestyle(self, ls): """ Set the patch linestyle. - ======================================================= ================ - linestyle description - ======================================================= ================ - ``'-'`` or ``'solid'`` solid line - ``'--'`` or ``'dashed'`` dashed line - ``'-.'`` or ``'dashdot'`` dash-dotted line - ``':'`` or ``'dotted'`` dotted line - ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing - ======================================================= ================ + Parameters + ---------- + ls : {'-', '--', '-.', ':', '', ...} or (offset, on-off-seq) + Possible values: - Alternatively a dash tuple of the following form can be provided:: + - A string: - (offset, onoffseq) + ======================================================= ================ + linestyle description + ======================================================= ================ + ``'-'`` or ``'solid'`` solid line + ``'--'`` or ``'dashed'`` dashed line + ``'-.'`` or ``'dashdot'`` dash-dotted line + ``':'`` or ``'dotted'`` dotted line + ``''`` or ``'none'`` (discouraged: ``'None'``, ``' '``) draw nothing + ======================================================= ================ - where ``onoffseq`` is an even length tuple of on and off ink in points. + - A tuple describing the start position and lengths of dashes and spaces: - Parameters - ---------- - ls : {'-', '--', '-.', ':', '', (offset, on-off-seq), ...} - The line style. + (offset, onoffseq) + + where + + - *offset* is a float specifying the offset (in points); i.e. how much + is the dash pattern shifted. + - *onoffseq* is a sequence of on and off ink in points. There can be + arbitrary many pairs of on and off values. + + Example: The tuple ``(0, (10, 5, 1, 5))`` means that the pattern starts + at the beginning of the line. It draws a 10 point long dash, + then a 5 point long space, then a 1 point long dash, followed by a 5 point + long space, and then the pattern repeats. + + For examples see :doc:`/gallery/lines_bars_and_markers/linestyles`. """ if ls is None: ls = "solid"