Chart

morphui.uix.visualization.chart

MorphChartInfoLabel(**kwargs)

Bases: MorphSimpleLabel

Label to show chart information in a MorphChartCard.

MorphChartNavigationButton(**kwargs)

Bases: MorphIconButton

Button for chart navigation in a MorphChartCard

MorphChartNavigationToggleButton(**kwargs)

Bases: MorphToggleButtonBehavior, MorphChartNavigationButton

Toggle button for chart navigation in a MorphChartCard.

MorphChartToolbarMenu(*args, caller, **kwargs)

Bases: MorphMenuMotionBehavior, MorphBoxLayout

Toolbar menu container for MorphChartCard.

default_config = dict(theme_color_bindings={'normal_surface_color': 'transparent_color'}, orientation='vertical', auto_size=True, spacing=(dp(4)), padding=[dp(0), dp(4)]) class-attribute instance-attribute

Container for toolbar menu items in MorphChartCard.

on_dismiss(*args)

Handle actions after the dropdown menu is dismissed.

If the caller button has an active property and is not in the middle of a ripple animation, it sets active to False to indicate that the dropdown is no longer active.

MorphChartToolbar(**kwargs)

Bases: MorphToggleButtonBehavior, MorphChartNavigationButton

Toolbar button for MorphChartCard that opens a menu.

plot_widget = ObjectProperty(None) class-attribute instance-attribute

Reference to the associated MorphPlotWidget.

This property must be set to link the toolbar to its corresponding MorphPlotWidget for chart interactions.

:attr:plot_widget is a :class:~kivy.properties.ObjectProperty and defaults to None.

navigation = ObjectProperty(None) class-attribute instance-attribute

Reference to the Navigation instance.

This property holds the :class:~morphui.uix.visualization.backend.Navigation instance for managing chart navigation actions.

:attr:navigation is a :class:~kivy.properties.ObjectProperty and defaults to None.

info_label = ObjectProperty(None) class-attribute instance-attribute

Reference to the chart info label.

This property holds the info label associated with the toolbar.

:attr:info_label is a :class:~kivy.properties.ObjectProperty and defaults to None.

menu = kwargs.pop('menu', MorphChartToolbarMenu(MorphChartNavigationButton(identity='chart_toolbar_home_button', icon='home-outline'), MorphChartNavigationButton(identity='chart_toolbar_undo_button', icon='undo-variant'), MorphChartNavigationButton(identity='chart_toolbar_redo_button', icon='redo-variant'), MorphChartNavigationToggleButton(identity='chart_toolbar_coordinate_button', group='chart_toolbar_navigation_tools', icon='map-marker-radius-outline', on_release=(self.show_coordinates)), MorphChartNavigationToggleButton(identity='chart_toolbar_pan_button', group='chart_toolbar_navigation_tools', icon='arrow-all'), MorphChartNavigationToggleButton(identity='chart_toolbar_zoom_button', group='chart_toolbar_navigation_tools', icon='selection-drag'), MorphChartNavigationButton(identity='chart_toolbar_save_button', icon='content-save-outline'), identity='chart_toolbar_menu', caller=self)) class-attribute instance-attribute

Reference to the toolbar menu.

This property holds the menu associated with the toolbar button.

:attr:menu is a :class:~kivy.properties.ObjectProperty and defaults to None.

on_plot_widget(instance, plot_widget)

Bind the toolbar buttons to the plot widget actions.

This method sets up the necessary bindings between the toolbar buttons and the corresponding actions on the associated MorphPlotWidget.

PARAMETER	DESCRIPTION
instance	The instance of the toolbar. TYPE: Any
plot_widget	The associated MorphPlotWidget. TYPE: MorphPlotWidget

show_coordinates(*args)

Toggle the display of coordinates on the plot widget.

This method is called when the coordinate button in the toolbar is toggled. It updates the show_info property of the associated MorphPlotWidget to show or hide coordinate information.

PARAMETER	DESCRIPTION
*args	Additional arguments passed by the button event. DEFAULT: ()

MorphChart(kw_savefig={}, **kwargs)

Bases: MorphFloatLayout

Chart component for data visualization within MorphUI.

This class integrates a MorphPlotWidget with a toolbar for interactive chart navigation and manipulation.

Usage

To use MorphChart, simply create an instance and set the :attr:figure attribute to a matplotlib Figure. Everything else is handled automatically:

import matplotlib.pyplot as plt
from morphui.uix.visualization import MorphChart

# Create your matplotlib figure
fig, ax = plt.subplots()
ax.plot([1, 2, 3], [4, 5, 6])

# Create chart and set figure - that's it!
chart = MorphChart()
chart.figure = fig  # This automatically sets up all navigation

When you set chart.figure = fig, the following happens automatically: 1. The figure is passed to the internal plot widget 2. A figure canvas is created for rendering 3. Navigation tools are initialized and bound to toolbar buttons 4. All interactive features (zoom, pan, save, etc.) become available

No additional setup is required - the chart is immediately interactive and ready for user interaction.

Customizing Save Behavior

To customize where chart images are saved, override the :meth:get_save_dir method. This is the ideal place to implement a custom save directory dialog:

class CustomChart(MorphChart):
    def get_save_dir(self) -> Path:
        # Your custom logic here - e.g., open a directory dialog
        # Return the selected directory as a Path object
        return Path('/your/custom/directory')

figure = ObjectProperty(None) class-attribute instance-attribute

The matplotlib Figure associated with the chart.

This property holds the Figure instance from matplotlib that contains the chart data and visual elements.

:attr:figure is a :class:~kivy.properties.ObjectProperty and defaults to None.

padding = VariableListProperty([dp(0)], length=4) class-attribute instance-attribute

Padding around the chart components.

This property defines the padding around the chart components (plot widget, toolbar, info label) within the MorphChart. It is a list of four values representing the padding on the left, top, right, and bottom sides, respectively.

:attr:padding is a :class:~kivy.properties.VariableListProperty and defaults to [dp(0), dp(0), dp(0), dp(0)].

default_save_dir = Path.home() / 'Downloads' class-attribute instance-attribute

Default directory for saving chart images.

This attribute specifies the default directory where chart images will be saved when using the save functionality.

filename = 'morphui_chart.png' class-attribute instance-attribute

Default filename for saved chart images.

This attribute specifies the default filename used when saving chart images to a file.

initial_save_dir = Path.home() / 'Downloads' class-attribute instance-attribute

Initial directory for the save dialog.

This attribute specifies the initial directory that the save dialog will open to when saving chart images. This attribute is automatically updated to the last used directory after each save operation.

Set this attribute to customize the initial directory for saving chart images. Especially useful for guiding users to a preferred save location.

default_config = dict(theme_color_bindings=(dict(normal_surface_color='transparent_color')), size_hint=(1, 1)) class-attribute instance-attribute

Default configuration for the MorphChart.

kw_savefig = kw_savefig instance-attribute

Keyword arguments for saving the figure.

This dictionary holds any additional keyword arguments that should be passed to the :meth:savefig method of the matplotlib Figure when saving the chart to a file.

toolbar = MorphChartToolbar(info_label=(self.info_label)) class-attribute instance-attribute

The toolbar for chart navigation and actions.

This property holds the MorphChartToolbar instance that provides interactive buttons for chart navigation, zooming, panning, and other actions.

:attr:toolbar is a :class:~kivy.properties.ObjectProperty and defaults to None.

plot_widget = MorphPlotWidget(toolbar=(self.toolbar)) class-attribute instance-attribute

The plot widget used for rendering the chart.

This property holds the MorphPlotWidget instance responsible for displaying the chart data.

:attr:plot_widget is a :class:~kivy.properties.ObjectProperty and defaults to None.

on_touch_down(touch)

Callback function, called on mouse button press or touch.

This method dismisses the toolbar menu if a touch occurs outside the chart area.

on_figure(instance, figure)

Callback function, called when figure attribute changes.

This method updates the :attr:figure property of the associated :class:MorphPlotWidget whenever the :attr:figure property of the :class:MorphChart changes. This triggers the following automatic chain:

1. self.plot_widget.figure = figure - passes figure to plot.
2. Plot widget's :meth:on_figure() method creates/updates :attr:figure_canvas.
3. Toolbar's :meth:_figure_canvas_updated_() method is triggered.
4. Navigation instance is created and all toolbar buttons are bound.

After this chain completes, the chart is fully interactive with working navigation, zoom, pan, save functionality, etc.

get_save_dir()

Get the directory to save the current chart image.

This method determines the directory where the chart image should be saved. It first checks the :attr:initial_save_dir attribute, then falls back to :attr:default_save_dir, and finally defaults to the user's Downloads folder if neither directory is valid.

Override this method to implement custom save directory selection, such as opening a directory picker dialog. This is the recommended approach for providing users with interactive directory selection.

RETURNS	DESCRIPTION
Path	The directory path where the chart should be saved.

Examples:

Override to implement a custom directory dialog:

class CustomChart(MorphChart):
    def get_save_dir(self) -> Path:
        # Open your preferred directory dialog here
        # Return the selected directory
        return selected_directory_path

save_figure(*args)

Save the current chart figure to a file.

This method saves the current chart figure to a file in the directory returned by :meth:get_save_dir. The filename is determined by the :attr:filename attribute if not provided in :attr:kw_savefig. Any additional keyword arguments specified in :attr:kw_savefig are passed to the :meth:savefig method of the matplotlib Figure.

RAISES	DESCRIPTION
FileNotFoundError	If the save directory is not valid.

Warnings

UserWarning If no figure is set or :meth:get_save_dir returns None.