Metadata-Version: 2.4
Name: mdock
Version: 0.1.1
Summary: Matplotlib figure dock based on QT6
Author-email: "Mikkel N. Schmidt" <mnsc@dtu.dk>
Keywords: matplotlib,figure,dock
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: matplotlib
Requires-Dist: PyQt6Ads

# MDock

A Python package for creating dockable matplotlib figures using PyQt6. MDock provides a professional docking interface where matplotlib figures can be dynamically arranged, resized, and managed as draggable dock widgets.

## Overview

MDock integrates matplotlib's figure rendering capabilities with PyQt6's powerful docking system (via PyQt6Ads). This allows you to create sophisticated multi-figure applications where figures can be:

- **Docked and undocked** - freely arrange figure windows
- **Organized in layouts** - organize multiple figures in a tabbed or side-by-side interface
- **Saved and restored** - persist window layouts between sessions
- **Controlled programmatically** - manage figures from Python with a simple API

## Installation

Install MDock using pip:

```bash
pip install mdock
```

### Requirements

- Python 3.9 or higher
- matplotlib
- PyQt6Ads

## Quick Start

```python
import matplotlib.pyplot as plt
import mdock

# Set the dock window title (optional)
mdock.title("My Application")

# Create some matplotlib figures
fig1, ax1 = plt.subplots()
ax1.plot([1, 2, 3, 4], [1, 4, 2, 3])
ax1.set_title("Figure 1")

fig2, ax2 = plt.subplots()
ax2.scatter([1, 2, 3, 4], [1, 4, 2, 3])
ax2.set_title("Figure 2")
```

## Features

- **Docking Interface**: Dock multiple matplotlib figures in a professional Qt interface
- **Persistent Layouts**: Save and restore dock configurations between sessions
- **Toolbar Controls**: Built-in toolbar for managing dock states
- **Easy API**: Simple functions for common operations

## API Reference

### Module Functions

#### `show()`
Display the MDock window containing all docked figures.

```python
import mdock
mdock.show()
```

#### `drawnow()`
Redraw all canvas figures in the dock and flush events. Use this to update all visible plots.

```python
import mdock
mdock.drawnow()
```

#### `title(t)`
Set the title of the MDock window.

**Parameters:**
- `t` (str): The window title

```python
import mdock
mdock.title("My Dock Window")
```

#### `store_state()`
Save the current dock layout, window geometry, and perspective to persistent storage.

```python
import mdock
mdock.store_state()
```

#### `restore_state()`
Restore the previously saved dock layout and window geometry.

```python
import mdock
mdock.restore_state()
```

## Usage Examples

### Example 1: Basic Multi-Figure Application

```python
import matplotlib.pyplot as plt
import mdock

# Set window title
mdock.title("Data Visualization")

# Create multiple figures
for i in range(3):
    fig, ax = plt.subplots(num=f'Data Visualization number {i+1}')
    ax.plot(range(10), [x**i for x in range(10)])
    ax.set_title(f"Plot {i+1}")

```

### Example 2: Saving and Restoring Layouts

```python
import matplotlib.pyplot as plt
import mdock

# Create some plots
fig1, ax1 = plt.subplots(num="Plot 1")
ax1.plot([1, 2, 3], [1, 2, 3])

fig2, ax2 = plt.subplots(num="Plot 2")
ax2.plot([1, 2, 3], [3, 2, 1])

# Show the docking interface
mdock.show()

# Restore previous layout (after figures are created). 
# If a layout for these figures has been saved, it will be restored.
mdock.restore_state()

# (...)

# Later, after manually modifying the figure layout, save the current layout
mdock.store_state()
```

### Example 3: Real-time Updates

```python
import matplotlib.pyplot as plt
import mdock
import numpy as np

# Enable interactive mode
plt.ion()

# Plot data interactively - updates appear immediately
for i in range(100):
    plt.figure("My Real-Time Plot")
    plt.clf()
    x = np.linspace(0, 10, 100)
    y = np.sin(x + i/10)
    plt.plot(x, y)   
    # Update the plot     
    mdock.drawnow()
```

## Notes

- Dock perspectives and window geometry are stored using Qt's `QSettings`, which automatically uses the appropriate storage location for your OS (Registry on Windows, plist on macOS, etc.)
- The MDock class uses class variables to maintain a single shared docking interface across all figures
- The first time a figure is created, the MDock window and docking manager are initialized
- Toolbar buttons allow manual storage and restoration of dock states

## License

MIT License - See LICENSE file for details

## Author

Mikkel N. Schmidt (mnsc@dtu.dk)
