🌐 AI搜索 & 代理 主页
Skip to content

DOC: Clarify and unify set_linestyle #30855

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
timhoffm wants to merge 1 commit into
base: main
Choose a base branch
from
+108 −54
Open

DOC: Clarify and unify set_linestyle #30855

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 33 additions & 17 deletions lib/matplotlib/collections.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
46 changes: 30 additions & 16 deletions lib/matplotlib/inset.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand Down
20 changes: 15 additions & 5 deletions lib/matplotlib/lines.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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`.
"""
Expand Down
46 changes: 30 additions & 16 deletions lib/matplotlib/patches.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand Down
Loading