Maliang

https://xiaokang2022.github.io/maliang/
Admin
Maliang is a modern Python GUI library for Tkinter that provides enhanced virtual widgets,...
Tokens:238,396
Snippets:3,082
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Maliang (Pure Installation)

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_01/1

Use this command for a basic installation of the maliang library. It automatically installs necessary dependencies like python/typing_extensions.

```bash
pip install maliang
```

--------------------------------

### Automatically Adapt to System Theme

Source: https://xiaokang2022.github.io/maliang-docs/3.1/tutorials/chapter_06/1

This example demonstrates automatic theme adaptation by allowing the user to select between 'light', 'system', and 'dark' themes. The 'system' option enables automatic switching based on the OS theme, provided `darkdetect` is installed.

```python
import maliang
from maliang import theme


def _set_color_mode(index: int) -> None:
    theme.set_color_mode(["light", "system", "dark"][index])


root = maliang.Tk()
canvas = maliang.Canvas()
canvas.pack(fill="both", expand=True)

maliang.SegmentedButton(canvas, (20, 20), text=("light", "system", "dark"), default=1, command=_set_color_mode)
```

--------------------------------

### Install Maliang (Full Installation)

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_01/1

Install maliang with all optional dependencies for complete functionality. This includes packages for operating system theme detection, image manipulation, and Windows-specific window effects.

```bash
pip install maliang[opt]
```

```bash
pip install maliang[ext]
```

--------------------------------

### Install Maliang (Full with Extension Packages)

Source: https://xiaokang2022.github.io/maliang-docs/3.1/tutorials/chapter_01/1?q=

Install Maliang along with its official extension packages for added capabilities.

```bash
pip install maliang[ext]
```

--------------------------------

### Install Maliang from Source (Gitee Mirror)

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_01/1

If GitHub is inaccessible, use this command to clone the maliang repository from the Gitee mirror and install the latest development version.

```bash
git clone https://gitee.com/Xiaokang2022/maliang.git
```

```bash
cd maliang
```

```bash
pip install .
```

--------------------------------

### Install Maliang from Source (GitHub)

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_01/1

Clone the maliang repository from GitHub and install the latest development version. Note that the latest version might encounter build failures.

```bash
git clone https://github.com/Xiaokang2022/maliang.git
```

```bash
cd maliang
```

```bash
pip install .
```

--------------------------------

### Install Maliang

Source: https://xiaokang2022.github.io/maliang

Install the Maliang package. Requires Python 3.10 or higher.

```bash
pip install maliang

```

--------------------------------

### Install Maliang from Source (GitCode Mirror)

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_01/1

Alternatively, use this command to clone the maliang repository from the GitCode mirror and install the latest development version if GitHub or Gitee are not suitable.

```bash
git clone https://gitcode.com/Xiaokang2022/maliang.git
```

```bash
cd maliang
```

```bash
pip install .
```

--------------------------------

### Verify Maliang Installation

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_01/1

Run this command after installation to check if maliang is installed correctly. A successful execution will display the installed version of maliang in the terminal output.

```bash
pip show maliang
```

--------------------------------

### Animation Start Method

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/animation/animations

Starts the animation. An optional delay can be specified before the animation begins.

```python
start()
-> None
```

```python
start(*, delay: int) -> str
```

```python
start(*, delay: int = 0) -> str | None
```

--------------------------------

### Recommended Maliang Installation

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_01/1

This command installs maliang with recommended optional dependencies for an enhanced user experience. It ensures better type hinting and includes useful features.

```bash
pip install maliang[opt]
```

--------------------------------

### Install Optional Packages for Maliang

Source: https://xiaokang2022.github.io/maliang

Install all optional packages for Maliang to enable additional features. These packages enhance functionality but are not required for basic operation.

```bash
pip install maliang[opt]

```

--------------------------------

### Animation.start()

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/animation/animations?q=

Starts the animation with an optional delay.

```APIDOC
## start

### Description
Start the animation.

### Parameters
- **delay** (int) - Optional - length of the delay before the animation starts

### Returns
- `None` if delay is not specified or is 0.
- `str` if delay is specified and greater than 0.
```

--------------------------------

### Start Animation

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/animation?q=

Starts the animation. Can optionally include a delay before starting. Returns a task identifier if a delay is specified.

```python
start() -> None
```

```python
start(*, delay: int) -> str
```

--------------------------------

### Install All Official Extension Packages for Maliang

Source: https://xiaokang2022.github.io/maliang

Install all official extension packages for Maliang to add specific functionalities like matplotlib support, media handling, 3D drawing, and table controls.

```bash
pip install maliang[ext]

```

--------------------------------

### VideoCanvas.open Method

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/media/main

Opens a video file and starts playback. Allows control over auto-play and initial mute state.

```APIDOC
## open

### Description
Open a video file and play.

### Parameters
- **file** (str) - Required - the video file path
- **auto_play** (bool) - Optional - whether to start playing the video automatically
- **muted** (bool) - Optional - whether or not to mute the video at the start

### Returns
- **None**
```

--------------------------------

### Slider get() Method

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/standard?q=

Retrieves the current value of the slider. No specific setup is required beyond having a slider instance.

```python
get() -> float
```

--------------------------------

### get

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/standard/widgets

Get the text of the widget.

```APIDOC
## get

### Description
Get the text of the widget.

### Method Signature
```python
get() -> str
```
```

--------------------------------

### Automatic System Theme Adaptation

Source: https://xiaokang2022.github.io/maliang-docs/3.1/tutorials/chapter_06/1?q=

This example demonstrates automatic theme switching based on the system's theme. It includes a segmented button to manually select 'light', 'system', or 'dark' modes.

```python
import maliang
from maliang import theme


def _set_color_mode(index: int) -> None:
    theme.set_color_mode(["light", "system", "dark"][index])


root = maliang.Tk()
cavas = maliang.Canvas()
cavas.pack(fill="both", expand=True)

maliang.SegmentedButton(canvas, (20, 20), text=("light", "system", "dark"), default=1, command=_set_color_mode)
```

--------------------------------

### Create a Main Window with Size, Position, and Title

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_02/1

Initializes a Tk window with specified dimensions, screen position, and title. This sets the initial appearance of the main window.

```python
import maliang

size = 1600, 900
position = 100, 50
title = "My Window"

maliang.Tk(size, position, title=title).mainloop()
```

--------------------------------

### Start Animation with Delay

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/animation

Starts the animation after a specified delay. If a delay is provided, it returns a task identifier; otherwise, it returns None.

```python
start(*, delay: int) -> str


```

--------------------------------

### Initialize Toplevel Window

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents?q=

Creates a new Toplevel window, which can serve as a pop-up or a customizable independent window. It accepts parameters for master, size, position, title, icon, and focus.

```python
Toplevel(
    master: Tk | Toplevel | None = None,
    size: tuple[int, int] = (960, 540),
    position: tuple[int, int] | None = None,
    *,
    title: str | None = None,
    icon: str | enhanced.PhotoImage | None = None,
    grab: bool = False,
    focus: bool = True,
    **kwargs: Any,
)


```

--------------------------------

### Create a Main Window with Event Loop

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_02/1

Generates a main window and enters the event loop. Code after root.mainloop() will not execute until the window is closed.

```python
import maliang

root = maliang.Tk()
root.mainloop()

print("Done!")
```

--------------------------------

### Initialize TextStyle

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/standard/styles?q=

Used to initialize the style for text elements. It inherits from virtual.Style.

```python
TextStyle(widget: Widget, *, auto_update: bool | None = None)
```

--------------------------------

### Maliang Pseudo-RGBA Example

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_05/1

Demonstrates the use of pseudo-RGBA color strings in Maliang. Note that this feature provides limited transparency effects and is dynamic with system themes.

```python
import maliang

root = maliang.Tk()
canvas = maliang.Canvas()
canvas.place(width=1280, height=720)

maliang.Label(canvas, (20, 20), text="Label RGBA 0%").style.set(bg="#FF000000")
maliang.Label(canvas, (20, 80), text="Label RGBA 50%").style.set(bg="#FF00007F")
maliang.Label(canvas, (20, 140), text="Label RGBA 100%").style.set(bg="#FF0000FF")
maliang.Label(canvas, (20, 200), text="Label RGB").style.set(bg="#FF0000")

maliang.Label(canvas, (300, 100), text="Label RGBA").style.set(bg="#FF00007F")
maliang.Label(canvas, (320, 120), text="Label RGBA").style.set(bg="#FF00007F")

root.mainloop()
```

--------------------------------

### Example Blog Post Structure

Source: https://xiaokang2022.github.io/maliang/blog/9999/09/09/%E7%BD%91%E7%AB%99%E6%96%B0%E5%A2%9E%E5%8D%9A%E5%AE%A2%E5%8A%9F%E8%83%BD

An example of a complete blog post, including metadata, title, summary, content separator, and main body. The 'categories' field should be '用户投稿' for user submissions.

```markdown
---
comments: true
date:
    created: 2333-02-23
    updated: 6666-06-06
authors:
    - 我叫用户名
categories:
    - 用户投稿
tags:
    - 标签一
    - 标签二
    - 标签三
---

# 我是文章标题

我是文章概览

<!-- more -->

啊吧啊吧……
```

--------------------------------

### Information Class Constructor

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/standard/texts

Initializes a general information text element. Supports various text styling and positioning options.

```python
Information(
    widget: Widget,
    relative_position: tuple[int, int] = (0, 0),
    size: tuple[int, int] | None = None,
    *, 
    text: str = "",
    limit: int = -1,
    show: str | None = None,
    placeholder: str = "",
    family: str | None = None,
    fontsize: int | None = None,
    weight: Literal["normal", "bold"] = "normal",
    slant: Literal["roman", "italic"] = "roman",
    underline: bool = False,
    overstrike: bool = False,
    name: str | None = None,
    gradient_animation: bool = True,
    **kwargs: Any,
)

```

--------------------------------

### get

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/standard

Retrieves the current text content of the widget.

```APIDOC
## `get` Method

### Description
Get the text of the widget.

### Signature
```python
get() -> str
```
```

--------------------------------

### center (geometry)

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/three/engine?q=

Gets the geometric center of the geometry.

```APIDOC
## center (geometry)

### Description
Returns the geometric center of the geometry.

### Method Signature
`center()`
```

--------------------------------

### ButtonFeature Initialization with Command and Args

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/standard/features?q=

Initializes the ButtonFeature, allowing for an optional command callback and arguments. Use this for standard button interactions.

```python
ButtonFeature(widget: virtual.Widget, *, command: Callable | None = None, args: tuple = ())

```

--------------------------------

### contrast

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/color/hsl

Get the contrasting color of a HSL code.

```APIDOC
## contrast

### Description
Get the contrasting color of a HSL code.

### Method
`contrast`

### Parameters
#### Path Parameters
- **value** (tuple[float, float, float]) - Required - a HSL code.
- **channels** (tuple[bool, bool, bool]) - Optional - three color channels. Defaults to (True, True, True).

### Response
#### Success Response
- **return value** (tuple[float, float, float]) - The contrasting color of a HSL code.
```

--------------------------------

### Initialize VideoCanvas

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/media?q=

Instantiate a VideoCanvas widget, which serves as a scalable and playable canvas for videos. Configure playback options like controls, looping, and click-to-pause behavior.

```python
VideoCanvas(
    master=None,
    controls=False,
    loop=False,
    click_pause=True,
    expand="xy",
    auto_zoom=False,
    keep_ratio="min",
    free_anchor=False,
    **kwargs
)
```

--------------------------------

### Animation.active property

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/animation/animations?q=

Gets the active state of the animation.

```APIDOC
## active

### Description
Returns the active state of the animation.

### Returns
- `bool` - True if the animation is active, False otherwise.
```

--------------------------------

### Initialize LabelStyle

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/standard/styles?q=

Used to initialize the style for label elements. It inherits from virtual.Style.

```python
LabelStyle(widget: Widget, *, auto_update: bool | None = None)
```

--------------------------------

### contrast

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/color/rgb?q=

Get the contrasting color of a RGB code.

```APIDOC
## contrast

### Description
Get the contrasting color of a RGB code.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **value** (tuple[int, int, int]) - Required - a RGB code
- **channels** (tuple[bool, bool, bool]) - Optional - three color channels

### Response
#### Success Response (200)
- **return value** (tuple[int, int, int]) - The contrasting RGB code.

### Request Example
```python
contrast(value=(255, 0, 0))
```

### Response Example
```python
(0, 255, 255)
```
```

--------------------------------

### fullscreen

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents?q=

Sets or gets whether the window is in fullscreen mode.

```APIDOC
## fullscreen

```python
fullscreen(value: bool | None = True) -> bool | None
```

Set or get whether the window is full-screen.

### Parameters
#### `value`
- **value** (bool | None) - Indicates whether the window is full-screen. Defaults to `True`.

### Returns
- `bool | None` - The current full-screen state of the window if `value` is not `None`. Otherwise, returns `None`.

Note: The method should be called at the end of the code, or after some time after the program has started.
```

--------------------------------

### Environment Configurations

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core/configs

Manage default environment values such as system, theme, and auto-update settings.

```APIDOC
## Env

Configurations for default environment values.

### Attributes
- `system` (str): The system of environment, e.g., "Windows10", "Linux", "Darwin".
- `theme` (Literal['light', 'dark']): The theme of the application.
- `gradient_animation` (bool): Whether to enable gradient animation for widgets.
- `auto_update` (bool): Whether to check for updates automatically on startup.
- `root` (tkinter.Tk): The current default root window (READ-ONLY).

### Methods
#### `reset()`

```python
Env.reset()
```

Reset all environment configuration options.

#### `get_default_system()`

```python
Env.get_default_system()
```

Get the system of environment.
```

--------------------------------

### Animation.count property

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/animation/animations?q=

Gets the number of loops remaining for the animation.

```APIDOC
## count

### Description
Returns the number of loops remaining.

### Returns
- `int` - The number of loops remaining.
```

--------------------------------

### Create ComboBox Widgets with Options

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_03/3

Illustrates the creation of ComboBox widgets, which allow users to select from a list of options or edit the text directly. This example shows two ComboBox instances with the same set of text options.

```python
import maliang

root = maliang.Tk()
cv = maliang.Canvas(auto_zoom=True)
cv.place(width=1280, height=720)

maliang.ComboBox(cv, (20, 20), text=("Option1", "Option2", "Option3"))
maliang.ComboBox(cv, (200, 20), text=("Option1", "Option2", "Option3"))

root.mainloop()
```

--------------------------------

### Env Configurations

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core?q=

Configurations for default environment values, including system, theme, and update settings.

```APIDOC
## Env

Configurations for default environment values.

### Attributes
- `system` (str): The system of environment, such as "Windows10", "Windows11", "Linux", "Darwin" (macOS).
- `theme` (Literal['light', 'dark']): The theme of the application.
- `gradient_animation` (bool): Whether to enable gradient animation for widgets that support it by default.
- `auto_update` (bool): Whether to check for updates automatically on startup.
- `root` (tkinter.Tk): The current default root window. It is READ-ONLY.

### Methods
- `reset()`: Reset all configuration options.
- `get_default_system()`: Get the system of environment.

#### `reset` classmethod
```python
reset() -> None
```

Reset all configuration options.

#### `get_default_system` staticmethod
```python
get_default_system() -> str
```

Get the system of environment.
```

--------------------------------

### Animation Properties

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/animation?q=

Properties to get the current state of an animation.

```APIDOC
## Properties for Animation

### active

Returns the active state of the animation.

- `active: bool`
```

```APIDOC
### count

Returns the number of loops remaining for the animation.

- `count: int`
```

--------------------------------

### StillImage Constructor

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/standard/images

Initializes a simple still image. Use this for static image display.

```python
StillImage(
    widget: Widget,
    relative_position: tuple[int, int] = (0, 0),
    size: tuple[int, int] | None = None,
    *,
    image: enhanced.PhotoImage | None = None,
    name: str | None = None,
    gradient_animation: bool = True,
    **kwargs
)


```

--------------------------------

### Widget Text Methods

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents

Methods for getting and setting the text of a widget.

```APIDOC
## Widget Text Methods

### `get`
```python
get() -> str
```
Get the text of the widget.

### `set`
```python
set(text: str) -> None
```
Set the text of the widget.
```

--------------------------------

### topmost

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core

Sets or gets whether the window is pinned (always on top).

```APIDOC
## topmost

```python
topmost(value: bool | None = True) -> bool | None
```

Set or get whether the window is pinned or not.

### Parameters
#### `value`
- **value** (bool | None) - Optional - Indicates whether the window is topmost. Defaults to `True`.

### Returns
- **bool | None** - The current topmost state of the window if `value` is not `None`. Otherwise, returns `None`.
```

--------------------------------

### Initialize VideoCanvas in Maliang

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/media/main

Instantiate a VideoCanvas, a scalable and playable video player. Configure playback options like controls, looping, and aspect ratio handling. Compatible with tkinter.Canvas parameters.

```python
VideoCanvas(
    master: containers.Tk | containers.Toplevel | containers.Canvas | None = None,
    *, 
    controls: bool = False,
    loop: bool = False,
    click_pause: bool = True,
    expand: typing.Literal["", "x", "y", "xy"] = "xy",
    auto_zoom: bool = False,
    keep_ratio: typing.Literal["min", "max"] | None = None,
    free_anchor: bool = False,
    **kwargs
)

```

--------------------------------

### Upgrade Maliang with Optional/Extension Packages

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_01/1

Synchronize upgrades for maliang along with its optional or extension packages to ensure all components are up-to-date.

```bash
pip install --upgrade maliang[opt]
```

```bash
pip install --upgrade maliang[ext]
```

--------------------------------

### alpha

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core

Sets or gets the transparency of the window. The value should be between 0 and 1.

```APIDOC
## alpha

```python
alpha(value: float | None = None) -> float | None
```

Set or get the transparency of the window.

### Parameters
#### `value`
- **value** (float | None) - Optional - The transparency of the window, range is `0` ~ `1`. Defaults to `None`.

### Returns
- **float | None** - The current transparency of the window if `value` is not `None`. Otherwise, returns `None`.
```

--------------------------------

### smooth

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/animation/controllers

A control function that starts slow, accelerates, and then decelerates towards the end.

```APIDOC
## smooth

### Description
Speed is slow first, then fast and then slow. (slow -> fast -> slow)

### Parameters
#### Path Parameters
- **t** (float) - Required - the percentage of time

### Response
#### Success Response (float)
- Returns a float representing the animation progress at time t.
```

--------------------------------

### Env Class Methods

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/core?q=

Provides methods for configuring default environment values and retrieving system information.

```APIDOC
## Env

Configurations for default environment values.

### Methods

* **`reset`**–
  Reset all configuration options.
* **`get_default_system`**–
  Get the system of environment.

### `reset` classmethod

```python
reset() -> None
```

Reset all configuration options.

### `get_default_system` staticmethod

```python
get_default_system() -> str
```

Get the system of environment.
```

--------------------------------

### Create a Basic SpinBox Widget

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_03/3

Shows the basic instantiation of a SpinBox widget. This widget is analogous to Tkinter's SpinBox and is used for inputting numerical values.

```python
import maliang

root = maliang.Tk()
cv = maliang.Canvas(auto_zoom=True)
cv.place(width=1280, height=720)

maliang.SpinBox(cv, (20, 20))

root.mainloop()
```

--------------------------------

### Widget Text Operations

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents?q=

Methods for getting and setting the text content of a widget.

```APIDOC
## Widget Text Methods

### `get()`

**Description:** Get the text of the widget.

**Signature:**
```python
get() -> str
```

### `set(text: str)`

**Description:** Set the text of the widget.

**Signature:**
```python
set(text: str) -> None
```
```

--------------------------------

### ComboBox Methods

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/standard

Provides documentation for the `get` and `set` methods of the ComboBox widget.

```APIDOC
## get

### Description
Get the index of the child toggle button with a value of True. If not, None is returned.

### Method Signature
```
get() -> int | None
```
```

```APIDOC
## set

### Description
Activate the child toggle button for the specified index.

### Method Signature
```
set(value: int | None, *, callback: bool = False) -> None
```
```

--------------------------------

### Initialize and use Trigger

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/toolbox/utility?q=

Instantiate a Trigger with a callback function. Use update() to trigger the callback once. The trigger can be reset, locked, or unlocked.

```python
Trigger(command=lambda: print("Triggered!"))
```

```python
trigger.update()
```

```python
trigger.reset()
```

```python
trigger.lock()
```

```python
trigger.unlock()
```

--------------------------------

### transparent

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core

Sets or gets whether the window is transparent. This method only works on macOS.

```APIDOC
## transparent

```python
transparent(value: bool | None = None) -> bool | None
```

Set or get whether the window is transparent.

### Parameters
#### `value`
- **value** (bool | None) - Optional - Indicates whether the window is transparent. Defaults to `None`.

### Returns
- **bool | None** - The current transparent state of the window if `value` is not `None`. Otherwise, returns `None`.

Warning
This method only works on macOS!
```

--------------------------------

### on_release

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core?q=

Handles mouse button release events.

```APIDOC
## on_release

### Description
Callback function for mouse button release events.

### Parameters
- **event** (tkinter.Event) - The event object.
- **name** (str) - The name associated with the event.
```

--------------------------------

### modified

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core

Sets or gets whether the window is modified. This method only works on macOS.

```APIDOC
## modified

```python
modified(value: bool | None = None) -> bool | None
```

Set or get whether the window is modified.

### Parameters
#### `value`
- **value** (bool | None) - Optional - Indicates whether the window is modified. Defaults to `None`.

### Returns
- **bool | None** - The current modified state of the window if `value` is not `None`. Otherwise, returns `None`.

Warning
This method only works on macOS!
```

--------------------------------

### Information Class Constructor

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/standard/texts?q=

Initializes an Information text widget. Accepts various parameters for text content, appearance, and behavior.

```python
Information(
    widget: Widget,
    relative_position: tuple[int, int] = (0, 0),
    size: tuple[int, int] | None = None,
    *, 
    text: str = "",
    limit: int = -1,
    show: str | None = None,
    placeholder: str = "",
    family: str | None = None,
    fontsize: int | None = None,
    weight: typing.Literal["normal", "bold"] = "normal",
    slant: typing.Literal["roman", "italic"] = "roman",
    underline: bool = False,
    overstrike: bool = False,
    name: str | None = None,
    gradient_animation: bool = True,
    **kwargs
)

```

--------------------------------

### Canvas Initialization

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core?q=

Initializes a Canvas widget with various configuration options.

```APIDOC
## Canvas Initialization

### Description
Initializes a Canvas widget, which acts as the parent for all virtual widgets.

### Parameters
- **master** (Tk | Toplevel | Canvas | None) - Optional - The parent widget.
- **expand** (Literal["", "x", "y", "xy"]) - Optional - The mode of expand ('x' for horizontal, 'y' for vertical, 'xy' for both). Defaults to 'xy'.
- **auto_zoom** (bool) - Optional - Whether to scale items automatically. Defaults to False.
- **keep_ratio** (Literal["min", "max"] | None) - Optional - The mode of aspect ratio ('min' or 'max'). Defaults to None.
- **free_anchor** (bool) - Optional - Whether the anchor point is free-floating. Defaults to False.
- **auto_update** (bool | None) - Optional - Whether the theme manager updates automatically. Defaults to None.
- **zoom_all_items** (bool) - Optional - Whether to scale all items. Defaults to False.
- **kwargs** (Any) - Optional - Compatible with other parameters of tkinter.Canvas.
```

--------------------------------

### transparentcolor

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core

Sets or gets the penetration color of the window. This method only works on Windows.

```APIDOC
## transparentcolor

```python
transparentcolor(value: str | None = None) -> str | None
```

Set or get the penetration color of the window.

### Parameters
#### `value`
- **value** (str | None) - Optional - The penetration color of the window. Defaults to `None`.

### Returns
- **str | None** - The current penetration color of the window if `value` is not `None`. Otherwise, returns `None`.

Warning
This method only works on Windows!
```

--------------------------------

### gradient

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/color/rgb?q=

Get a list of color gradients from one color to another proportionally.

```APIDOC
## gradient

### Description
Get a list of color gradients from one color to another proportionally.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- None

### Parameters
- **first** (tuple[int, int, int]) - Required - the first RGB code
- **second** (tuple[int, int, int]) - Required - the second RGB code
- **count** (int) - Required - the number of gradients
- **rate** (float) - Optional - transition rate, default value is 1
- **channels** (tuple[bool, bool, bool]) - Optional - three color channels
- **controller** (collections.abc.Callable[[float], float]) - Optional - control function, default value is controllers.linear

### Response
#### Success Response (200)
- **return value** (list[tuple[int, int, int]]) - A list of RGB codes representing the gradients.

### Request Example
```python
gradient(first=(255, 0, 0), second=(0, 255, 0), count=3)
```

### Response Example
```python
[(255, 0, 0), (127, 127, 0), (0, 255, 0)]
```
```

--------------------------------

### Center a Toplevel Window Relative to the Root Window

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_02/1

Creates a Toplevel window and centers it with respect to the root window using the `center` method with a `refer` parameter. This ensures the sub-window appears in the middle of the main window.

```python
import maliang

root = maliang.Tk()
tl = maliang.Toplevel()
tl.center(refer=root)
root.mainloop()
```

--------------------------------

### Information Class get() Method

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/standard/texts

Retrieves the current text value of the Information element.

```python
get() -> str

```

--------------------------------

### toolwindow

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/core

Sets or gets whether the window is a tool window. This method only works on Windows.

```APIDOC
## toolwindow

```python
toolwindow(value: bool | None = True) -> bool | None
```

Set or get whether the window is tool-window.

### Parameters
#### `value`
- **value** (bool | None) - Optional - Indicates whether the window is tool-window. Defaults to `True`.

### Returns
- **bool | None** - The current tool-window state of the window if `value` is not `None`. Otherwise, returns `None`.

Warning
This method only works on Windows!
```

--------------------------------

### ButtonFeature Initialization with Command and Args

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents/standard/features

Initializes the ButtonFeature for a widget, allowing for a command callback and its arguments. The command is a function to be executed when the button is activated, and args are the arguments passed to this function.

```python
ButtonFeature(widget: virtual.Widget, *, command: Callable | None = None, args: tuple = ())
```

--------------------------------

### Image Widget Get Method

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/standard/widgets

Retrieves the current image displayed by the Image widget.

```python
get() -> enhanced.PhotoImage


```

--------------------------------

### Create an InputBox with Placeholder Text

Source: https://xiaokang2022.github.io/maliang-docs/3.0/tutorials/chapter_03/3

Demonstrates how to create an InputBox widget with a placeholder text that appears when the input is empty and the widget is in a 'normal' state. The placeholder is displayed in gray.

```python
import maliang

root = maliang.Tk()
cv = maliang.Canvas(auto_zoom=True)
cv.place(width=1280, height=720)

maliang.InputBox(cv, (20, 20), placeholder="InputBox")

root.mainloop()
```

--------------------------------

### Text Widget Get Method

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/standard/widgets

Retrieves the current text content of the Text widget.

```python
get() -> str


```

--------------------------------

### Manually Set Color Theme to Light

Source: https://xiaokang2022.github.io/maliang-docs/3.1/tutorials/chapter_06/1

Use `theme.set_color_mode()` to force a specific theme like 'light'. This code sets the application theme and then builds a simple login window.

```python
import maliang
from maliang import theme

theme.set_color_mode("light")

root = maliang.Tk(title="登录")

canvas = maliang.Canvas(auto_zoom=True, keep_ratio="min", free_anchor=True)
canvas.place(width=1280, height=720, x=640, y=360, anchor="center")

maliang.Text(canvas, (640, 200), text="账 号 登 录", fontsize=48, anchor="center")

maliang.Text(canvas, (450, 300), text="账号", anchor="nw")
maliang.InputBox(canvas, (450, 340), (380, 50), placeholder="点击输入账号")
maliang.Text(canvas, (450, 400), text="密码", anchor="nw")
maliang.InputBox(canvas, (450, 440), (380, 50), show="●", placeholder="点击输入密码")

maliang.Button(canvas, (450, 540), (180, 50), text="注 册")
maliang.Button(canvas, (650, 540), (180, 50), text="登 录")

root.center()
root.mainloop()
```

--------------------------------

### Line

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/three

Represents a line segment defined by a start and end point, with customizable width and color.

```APIDOC
## Line

```python
Line(canvas, point_start, point_end, *, width=1, fill='#000000')
```

### Parameters
* `canvas`: Parent canvas.
* `point_start`: Starting point coordinates.
* `point_end`: Ending point coordinates.
* `width`: Width of the line.
* `fill`: Color of the line.

### Methods
* **`update`**: Updates the display of the object.
```

--------------------------------

### Initialize Slider Widget

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents?q=

Creates a Slider widget for visually resizing values. Configure its appearance and behavior using various parameters.

```python
Slider(
    master: containers.Canvas | virtual.Widget,
    position: tuple[int, int],
    size: tuple[int, int] = (400, 30),
    *,
    default: float | None = None,
    command: Callable[[float], Any] | None = None,
    anchor: Literal["n", "e", "w", "s", "nw", "ne", "sw", "se", "center"] = "nw",
    capture_events: bool | None = None,
    gradient_animation: bool | None = None,
    auto_update: bool | None = None,
    style: type[virtual.Style] | None = None,
)
```

--------------------------------

### VideoCanvas.open

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/media

Opens a video file and starts playing it on the VideoCanvas. Supports automatic playback and muting.

```APIDOC
## open

### Description
Open a video file and play.

### Parameters
#### Method Parameters
- **file** (str) - Required - The video file path.
- **auto_play** (bool) - Optional - Whether to start playing the video automatically. Defaults to False.
- **muted** (bool) - Optional - Whether or not to mute the video at the start. Defaults to False.

### Returns
- None
```

--------------------------------

### Font Module

Source: https://xiaokang2022.github.io/maliang-docs/3.1/documents?q=

Functions for font management, including resetting and getting default font families.

```APIDOC
## Font

### Description
Functions for font management.

#### Methods
- `reset()`: Resets font settings.
- `get_default_family()`: Retrieves the default font family.
```

--------------------------------

### Image Widget Constructor

Source: https://xiaokang2022.github.io/maliang-docs/3.0/documents/standard/widgets

Initializes an Image widget for displaying images. Requires master and position. Optional parameters include size, image source, anchor, and event/animation settings.

```python
Image(
    master: containers.Canvas | virtual.Widget,
    position: tuple[int, int],
    size: tuple[int, int] | None = None,
    *,
    image: enhanced.PhotoImage | None = None,
    anchor: typing.Literal["n", "e", "w", "s", "nw", "ne", "sw", "se", "center"] = "nw",
    capture_events: bool | None = None,
    gradient_animation: bool | None = None,
    auto_update: bool | None = None,
    style: type[virtual.Style] | None = None
)


```
Tokens:
Raw