Class Canvas

java.lang.Object

io.leandev.appfuse.image.Canvas

public class Canvas
extends Object

圖像畫布類別，提供繪圖操作的封裝。

此類別封裝了 Java 2D Graphics API，提供便利的方法來繪製圖形、文字和圖片。 支援使用像素或 Length 單位來指定尺寸，並可根據 PPI（每英吋像素數）自動轉換。

使用範例：

Canvas canvas = new Canvas(800, 600);
canvas.setColor(Color.RED);
canvas.fillRect(0, 0, 100, 100);
BufferedImage image = canvas.getImage();
canvas.dispose();

Constructor Summary

Constructors

Constructor	Description
Canvas(int width, int height)	以像素尺寸建立畫布。
Canvas(Length width, Length height)	以 Length 單位建立畫布，使用預設 PPI（300）。
Canvas(Length width, Length height, int ppi)	以 Length 單位建立畫布，並指定 PPI。
Canvas(BufferedImage image)	以現有的 BufferedImage 建立畫布。

Method Summary

Modifier and Type	Method	Description
Font	createFont(String fontFamily, int style, int size)	建立字體，根據 PPI 自動轉換字體大小。
Font	createFont(String fontFamily, int style, Length size)	建立字體，使用 Length 單位指定大小。
Rectangle	createRectangle(int x, int y, int width, int height)	建立矩形物件，使用像素單位。
Rectangle	createRectangle(Length width, Length height)	建立矩形物件，使用 Length 單位，位置為原點。
Rectangle	createRectangle(Length x, Length y, Length width, Length height)	建立矩形物件，使用 Length 單位。
void	dispose()	釋放繪圖資源。
void	drawImage(BufferedImage image, int left, int top)	繪製圖片至指定位置。
void	drawImage(BufferedImage image, Rectangle rect)	繪製圖片，不縮放並置中對齊。
void	drawImage(BufferedImage image, Rectangle rect, Position position)	繪製圖片，使用指定定位但不縮放。
void	drawImage(BufferedImage image, Rectangle rect, Scaling scaling)	繪製圖片，使用指定縮放模式並置中對齊。
void	drawImage(BufferedImage image, Rectangle rect, Scaling scaling, Position position)	繪製圖片，支援縮放模式與定位。
void	drawRect(int x, int y, int width, int height)	繪製矩形邊框。
void	drawRect(Rectangle rect)	繪製矩形邊框。
void	drawText(String text, Rectangle rect)	繪製文字，置中對齊。
void	drawText(String text, Rectangle rect, Position position)	繪製文字，支援定位對齊。
void	fillRect(int x, int y, int width, int height)	填滿矩形區域。
void	fillRect(Rectangle rect)	填滿矩形區域。
BufferedImage	getBufferedImage()	取得畫布的 BufferedImage。
Color	getColor()	取得目前繪圖顏色。
Font	getFont()	取得目前繪圖字體。
int	getHeight()	取得畫布高度。
BufferedImage	getImage()	取得畫布的 BufferedImage。
int	getPpi()	取得畫布的 PPI（每英吋像素數）。
int	getWidth()	取得畫布寬度。
void	setBackground(Color color)	設定畫布背景顏色。
void	setBorder(Color color)	設定畫布邊框顏色。
void	setColor(Color color)	設定繪圖顏色。
void	setFont(Font font)	設定繪圖字體。
void	setPpi(int ppi)	設定畫布的 PPI（每英吋像素數）。
void	setStroke(float width)	設定繪圖筆觸寬度。
void	setStroke(Stroke stroke)	設定繪圖筆觸樣式。

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Canvas

public Canvas(int width,
 int height)

以像素尺寸建立畫布。

Parameters:

width - 畫布寬度（像素）

height - 畫布高度（像素）

Canvas

public Canvas(Length width,
 Length height,
 int ppi)

以 Length 單位建立畫布，並指定 PPI。

Parameters:

width - 畫布寬度（Length 單位）

height - 畫布高度（Length 單位）

ppi - 每英吋像素數，用於將 Length 轉換為像素

Canvas

public Canvas(Length width,
 Length height)

以 Length 單位建立畫布，使用預設 PPI（300）。

Parameters:

width - 畫布寬度（Length 單位）

height - 畫布高度（Length 單位）

Canvas

public Canvas(BufferedImage image)

以現有的 BufferedImage 建立畫布。

Parameters:

image - 作為畫布基底的 BufferedImage

Method Details

getHeight

public int getHeight()

取得畫布高度。

Returns:

畫布高度（像素）

getWidth

public int getWidth()

取得畫布寬度。

Returns:

畫布寬度（像素）

setBackground

public void setBackground(Color color)

設定畫布背景顏色。

此方法會以指定顏色填滿整個畫布，然後還原原本的繪圖顏色。

Parameters:

color - 背景顏色

setBorder

public void setBorder(Color color)

設定畫布邊框顏色。

此方法會以指定顏色繪製畫布的邊框，然後還原原本的繪圖顏色。

Parameters:

color - 邊框顏色

drawRect

public void drawRect(int x,
 int y,
 int width,
 int height)

繪製矩形邊框。

Parameters:

x - 矩形左上角的 x 座標

y - 矩形左上角的 y 座標

width - 矩形寬度

height - 矩形高度

setStroke

public void setStroke(Stroke stroke)

設定繪圖筆觸樣式。

Parameters:

stroke - 筆觸樣式物件

setStroke

public void setStroke(float width)

設定繪圖筆觸寬度。

使用指定寬度建立基本筆觸樣式。

Parameters:

width - 筆觸寬度

drawRect

public void drawRect(Rectangle rect)

繪製矩形邊框。

Parameters:

rect - 矩形物件，定義繪製位置與尺寸

fillRect

public void fillRect(int x,
 int y,
 int width,
 int height)

填滿矩形區域。

Parameters:

x - 矩形左上角的 x 座標

y - 矩形左上角的 y 座標

width - 矩形寬度

height - 矩形高度

fillRect

public void fillRect(Rectangle rect)

填滿矩形區域。

Parameters:

rect - 矩形物件，定義填滿位置與尺寸

drawImage

public void drawImage(BufferedImage image,
 Rectangle rect,
 Scaling scaling,
 Position position)

繪製圖片，支援縮放模式與定位。

縮放模式（scaling）可設定為以下值：

• fill: 預設值，拉伸圖片以填滿內容框，不保留原始比例
• contain: 等比縮放圖片以填滿框內，保留原始比例
• cover: 等比縮放圖片以填滿框的寬高，可能裁切部分圖片
• none: 忽略框的尺寸，保持圖片原始大小
• scale-down: 比較 none 與 contain 的結果，選擇較小者

Parameters:

image - 要繪製的圖片

rect - 繪製區域，定義圖片放置的位置與可用空間

scaling - 縮放模式，參考 CSS object-fit 屬性

position - 圖片在區域內的對齊位置

drawImage

public void drawImage(BufferedImage image,
 Rectangle rect,
 Position position)

繪製圖片，使用指定定位但不縮放。

Parameters:

image - 要繪製的圖片

rect - 繪製區域

position - 圖片在區域內的對齊位置

drawImage

public void drawImage(BufferedImage image,
 Rectangle rect,
 Scaling scaling)

繪製圖片，使用指定縮放模式並置中對齊。

Parameters:

image - 要繪製的圖片

rect - 繪製區域

scaling - 縮放模式

drawImage

public void drawImage(BufferedImage image,
 Rectangle rect)

繪製圖片，不縮放並置中對齊。

Parameters:

image - 要繪製的圖片

rect - 繪製區域

drawImage

public void drawImage(BufferedImage image,
 int left,
 int top)

繪製圖片至指定位置。

Parameters:

image - 要繪製的圖片

left - 圖片左上角的 x 座標

top - 圖片左上角的 y 座標

drawText

public void drawText(String text,
 Rectangle rect,
 Position position)

繪製文字，支援定位對齊。

Parameters:

text - 要繪製的文字，若為 null 則不執行任何操作

rect - 繪製區域，定義文字放置的範圍

position - 文字在區域內的對齊位置

drawText

public void drawText(String text,
 Rectangle rect)

繪製文字，置中對齊。

Parameters:

text - 要繪製的文字

rect - 繪製區域

setColor

public void setColor(Color color)

設定繪圖顏色。

Parameters:

color - 繪圖顏色

getColor

public Color getColor()

取得目前繪圖顏色。

Returns:

目前的繪圖顏色

setFont

public void setFont(Font font)

設定繪圖字體。

Parameters:

font - 字體物件

getFont

public Font getFont()

取得目前繪圖字體。

Returns:

目前的字體物件

getImage

public BufferedImage getImage()

取得畫布的 BufferedImage。

Returns:

畫布的 BufferedImage 物件

dispose

public void dispose()

釋放繪圖資源。

使用完畫布後應呼叫此方法以釋放 Graphics2D 資源。

getBufferedImage

public BufferedImage getBufferedImage()

取得畫布的 BufferedImage。

此方法與 getImage() 功能相同。

Returns:

畫布的 BufferedImage 物件

createFont

public Font createFont(String fontFamily,
 int style,
 int size)

建立字體，根據 PPI 自動轉換字體大小。

將點數 (pt) 轉換為像素 (px)：fontSize = size * ppi / 72

Parameters:

fontFamily - 字體家族名稱（如 Font.SANS_SERIF, "Arial" 等）

style - 字體樣式（Font.PLAIN, Font.BOLD, Font.ITALIC）

size - 字體大小（點數）

Returns:

Font 物件

createFont

public Font createFont(String fontFamily,
 int style,
 Length size)

建立字體，使用 Length 單位指定大小。

Parameters:

fontFamily - 字體家族名稱

style - 字體樣式

size - 字體大小（Length 單位）

Returns:

Font 物件

createRectangle

public Rectangle createRectangle(int x,
 int y,
 int width,
 int height)

建立矩形物件，使用像素單位。

Parameters:

x - 矩形左上角的 x 座標

y - 矩形左上角的 y 座標

width - 矩形寬度

height - 矩形高度

Returns:

矩形物件

createRectangle

public Rectangle createRectangle(Length x,
 Length y,
 Length width,
 Length height)

建立矩形物件，使用 Length 單位。

根據畫布的 PPI 將 Length 轉換為像素。

Parameters:

x - 矩形左上角的 x 座標（Length 單位）

y - 矩形左上角的 y 座標（Length 單位）

width - 矩形寬度（Length 單位）

height - 矩形高度（Length 單位）

Returns:

矩形物件

createRectangle

public Rectangle createRectangle(Length width,
 Length height)

建立矩形物件，使用 Length 單位，位置為原點。

根據畫布的 PPI 將 Length 轉換為像素。矩形左上角位於 (0, 0)。

Parameters:

width - 矩形寬度（Length 單位）

height - 矩形高度（Length 單位）

Returns:

矩形物件

getPpi

public int getPpi()

取得畫布的 PPI（每英吋像素數）。

Returns:

PPI 值

setPpi

public void setPpi(int ppi)

設定畫布的 PPI（每英吋像素數）。

Parameters:

ppi - PPI 值