المكونات

المكونات هي عناصر واجهة تفاعلية تتيح للمستخدمين تكوين المعاملات (المدخلات) أو عرض النتائج داخل الكتلة المخصصة الخاصة بك.

يتم بناء المكونات عبر وسائط اسم-قيمة (keyword arguments).

Generic Arguments

تنطبق الوسائط العامة على جميع المكونات المخصصة. يمكنك تمريرها كوسائط مسماة إلى البانيين.

بدلاً من تكرارها تحت كل مكون، فيما يلي مرجع صغير بأسلوب “pyi”:

# Common keyword arguments (supported by all components)
class _CommonComponentKwargs:
    def __init__(
        self,
        *,
        tool_tip: str = "",
        enabled: bool = True,
        hidden: bool = False,
        fixed_width: int = 0,
        fixed_height: int = 0,
        minimum_width: int = 0,
        minimum_height: int = 0,
        maximum_width: int = 0,
        maximum_height: int = 0,
        serializable: bool = True,
        stylesheet: str = "",
        font_size: int = -1,
        font_bold: bool = False,
        alignment: str = "AlignLeft",
        **kwargs,
    ) -> None: ...

ملاحظات:

• tool_tip يتحكم بالنص التوضيحي الذي يظهر عند تحويم الماوس فوق المكون.

• fixed_width / fixed_height بوحدة البيكسل. استخدم 0 للقيمة “تلقائي”.

• بعض المكونات تغير القيم الافتراضية (مثلاً DropDown غير قابل للتسلسل؛ وImage غير قابل للتسلسل بشكل افتراضي).

Text Input

يتيح للمستخدمين إدخال نص/أرقام عبر سطر واحد.

# pyi-style reference
class TextInput:
    def __init__(
        self,
        *,
        text: str = "",
        place_holder: str = "",
        check_type: type = str,
        password: bool = False,
        tool_tip: str = "",
        **kwargs,
    ) -> None: ...

    @property
    def value(self) -> str: ...

    @property
    def text(self) -> str: ...  # same as .value

    def toInt(self) -> int: ...
    def toFloat(self) -> float: ...

ملاحظات:

• استخدم check_type=int أو check_type=float لتقييد ما يمكن للمستخدم كتابته.

• استخدم .toInt() / .toFloat() عندما تريد أن تظهر أخطاء التحويل كاستثناء واضح (بدون تراجع صامت).

مثال:

class Example_Block(Block):
    ...
    def init(self):
        ...
        self.param["text1"] = TextInput(
            text="5",
            place_holder="Enter an integer",
            check_type=int,
            tool_tip="Defines constant",
        )
    
    def run(self):
        ...
        constant: int = self.param["text1"].toInt()
        ... 

Drop Down List

تسمح القوائم المنسدلة للمستخدمين باختيار خيار من قائمة نصوص متوفرة.

# pyi-style reference
class DropDown:
    serializable: bool = False

    def __init__(
        self,
        *,
        items: list[str] | dict[str, object] = ["item1", "item2", "item3"],
        selected_index: int = 0,
        tool_tip: str = "",
        **kwargs,
    ) -> None: ...

    @property
    def selected_item(self) -> str: ...

    @property
    def selected_index(self) -> int: ...

ملاحظات:

• إذا مررت items كـ dict[str, object]، يمكنك الوصول إلى القيمة المرتبطة عبر .getCurrentMatch().

DropDown معلمة حالياً غير قابلة للتسلسل. إذا أردت أن يبقى الاختيار محفوظًا في السيناريوهات المحفوظة، احفظ selected_index بنفسك (مثلاً باستخدام register_ser_value() أو serialize_node()).

مثال:

class Example_Block(Block):
    ...
    def init(self):
        ...
        self.param['drop_down'] = DropDown(items=['Method 1', 'Method 2', 'Method 3'], 
                                        tool_tip='Choose Method')
    
    def run(self):
        ...
        method_index: int = self.param['drop_down'].selected_index
        method_name: str = self.param['drop_down'].selected_item
        if method_index == 0:
            ... 

Label

الملصقات عبارة عن مكونات نصية بسيطة لعرض نص ثابت أو ديناميكي على الكتلة المخصصة الخاصة بك.

كما تُستخدم لتقديم معلومات حول المكونات التفاعلية:

# pyi-style reference
class Label:
    def __init__(self, *, text: str = "", tool_tip: str = "", **kwargs) -> None: ...
    def set_text(self, text: str) -> None: ...

مثال:

class Example_Block(Block):
    ...
    def init(self):
        ...
        self.param['label'] = Label(text='Result is: Not Set', 
                                        tool_tip='Shows mean value')
    
    def run(self):
        ...
        self.param['label'].set_text(f'Result is: {n}')
        ... 

Slider

يقيد إدخال المستخدم إلى مدى من الأعداد.

# pyi-style reference
class Slider:
    def __init__(
        self,
        *,
        min: int = 0,
        max: int = 100,
        val: int = 50,
        tool_tip: str = "",
        **kwargs,
    ) -> None: ...

    @property
    def value(self) -> float | int: ...

مثال:

class Example_Block(Block):
    ...
    def init(self):
        ...
        self.param['slider'] = Slider(min=-5, max=5, val=3)
    
    def run(self):
        ...
        threshold: int = self.param['slider'].value
        ... 

Slider Labeled

مماثل لـ Slider لكنه يضيف تسمية تعرض تلقائيًا القيمة المعروضة في المكون.

# pyi-style reference
class SliderLabeled:
    def __init__(
        self,
        *,
        min: int = 0,
        max: int = 100,
        val: int = 50,
        label: str = "Value",
        multiplier: float | int = 1,
        add: float | int = 0,
        tool_tip: str = "",
        **kwargs,
    ) -> None: ...

    @property
    def value(self) -> float | int: ...

    @property
    def modifiedValue(self) -> float | int: ...

مثال:

class Example_Block(Block):
    ...
    def init(self):
        ...
        self.param['threshold_odd'] = SliderLabeled(min= -5, max= 5, val= 3, label="Value", multiplier = 2, add = -1)
    
    def run(self):
        ...
        threshold_odd: int = self.param['threshold_odd'].modifiedValue
        ... 

CheckBox

يسمح بإدخال حالة منطقية (صح/خطأ).

# pyi-style reference
class CheckBox:
    def __init__(
        self,
        *,
        text: str = "",
        init_state: bool = False,
        tool_tip: str = "",
        **kwargs,
    ) -> None: ...

    @property
    def is_checked(self) -> bool: ...

مثال:

class Example_Block(Block):
    ...
    def init(self):
        ...
        self.param['gray_mode'] = CheckBox(text=': Gray Mode')
    
    def run(self):
        ...
        flag_gray: bool = self.param['gray_mode'].is_checked
        ... 

Button

يؤدي حدثًا في سكربتك عند النقر بالماوس. هذا المكون مفيد أيضًا لإدارة الموارد للكتل المخصصة داخل السيناريو الخاص بك.

# pyi-style reference
from collections.abc import Callable

class Button:
    def __init__(self, *, text: str = "", tool_tip: str = "", **kwargs) -> None: ...
    def set_clicked_callback(self, callback: Callable[[], None]) -> None: ...

استخدم set_clicked_callback(...) داخل init().

مثال:

...
class Example_Block(Block):
    ...
    file_path: str = ''
    def init(self):
        ...
        self.param['Choose File'] = Button(text= 'Choose File')
        self.param['Choose File'].set_clicked_callback(self.load_image)
    
    def load_image(self):
        path = QAFileDialog.getOpenFileName(caption='Load Image', 
                                        directory='C:/Images', 
                                        filter='Image Files (*.png *.jpg *.bmp)')
        self.file_path = self.register_resource('image-path', path)
        
    def run(self):
        image_path = self.get_resource('image-path')
    

المثال أعلاه يستخدم ردود النداء مع register_resource و get_resource.

Image

# pyi-style reference
import numpy as np
import numpy.typing as npt

class Image:
    def __init__(
        self,
        *,
        fixed_width: int = 80,
        fixed_height: int = 80,
        tool_tip: str = "",
        serializable: bool = False,
        **kwargs,
    ) -> None: ...

    def update(self, img: npt.NDArray[np.uint8]) -> None: ...

مثال:

...
class Example_Block(Block):
    def init(self):
        ...
        self.param['Result'] = Image(
            fixed_width=self.width - 40,
            fixed_height=self.height - 80,
        )

    def run(self):
        ...
        self.param['Result'].update(np.zeros((60, 60, 3), dtype=np.uint8))
        ...

Table

يسمح باختيار عناصر/وضعيات متعددة في نفس الوقت.

# pyi-style reference
class Table:
    def __init__(
        self,
        *,
        header_label: str = "table",
        items: list[str] | dict[str, bool] = ["item1", "item2", "item3"],
        tool_tip: str = "",
        **kwargs,
    ) -> None: ...

    @property
    def items(self) -> list[str]: ...

    @property
    def selected_items(self) -> list[str]: ...

    def set_items(self, items: list[str]) -> None: ...

مثال:

...
class Example_Block(Block):
    def init(self):
        ...
        self.param['Detection List'] = Table(items=['Human', 'Cat', 'Dog'])

    def run(self):
        ...
        detection_list: list[str, ...] = self.param['Detection List'].selected_items
        ...

Text Edit

Text Edit هو حقل نص متعدد الأسطر.

# pyi-style reference
class TextEdit:
    def __init__(self, *, text: str = "", tool_tip: str = "", **kwargs) -> None: ...

    @property
    def value(self) -> str: ...

    @property
    def text(self) -> str: ...  # same as .value

مثال:

class Example_Block(Block):
    def init(self):
        self.param['notes'] = TextEdit(tool_tip='Write notes here')

    def run(self):
        notes: str = self.param['notes'].value