docs(qt.py): Add comprehensive documentation for BalWizardDialog class

VERSION

@@ -1 +1 @@
-0.2.10
+0.2.8

manifest.json

@@ -1,7 +1,7 @@
 {
  "name": "BAL",
  "fullname": "Bitcoin After Life",
- "description": "Provides free and decentralized inheritance support<br> Version: 0.2.10",
+ "description": "Provides free and decentralized inheritance support<br> Version: 0.2.7",
  "author":"Svatantrya",
  "available_for": ["qt"],
  "icon":"icons/bal32x32.png"

qt.py

@@ -390,26 +390,6 @@ class shown_cv:
 
 
 class BalWindow(Logger):
-    """Main application window for Bitcoin After Life inheritance management.
-
-    This class provides the primary UI for:
-    - Managing inheritance plans
-    - Building Wills
-    - Handling heir configurations
-    - Network operations
-    - Transaction signing and broadcasting
-
-    Attributes:
-        bal_plugin (BalPlugin): Reference to the plugin instance
-        config (dict): Application configuration
-        network (Network): Network interface
-        wallet (Abstract_Wallet): Wallet interface
-        heirs (list): List of heir configurations
-        will (Will): Current Will being managed
-        building_will (bool): Flag indicating Will construction in progress
-        stop_build (bool): Flag to stop Will construction
-    """
-
     def __init__(self, bal_plugin: "BalPlugin", window: "ElectrumWindow"):
         Logger.__init__(self)
         self.bal_plugin = bal_plugin
@@ -1291,18 +1271,42 @@ class _LockTimeEditor:
         return cls.min_allowed_value <= x <= cls.max_allowed_value
 
 
-class HeirsLockTimeEdit(QWidget, _LockTimeEditor):
-    """HeirsLockTimeEdit class for Bitcoin After Life.
+<<<<<<< HEAD
+=======
+    """
+    HeirsLockTimeEdit - A custom QWidget for editing locktime values in the context of heirs distribution.
 
-    This class provides functionality for managing various Bitcoin After Life features.
+    This widget combines raw locktime editing with date-based selection and provides
+    additional functionality for managing locktime values in a heir inheritance scenario.
+
+    Features:
+    - Supports both raw locktime values and human-readable date formats
+    - Emits valueEdited signal when the locktime value is edited
+    - Provides threshold-based validation for locktime values
+    - Integrates with heir distribution workflows
+
+    Behavior:
+    The class handles three types of locktime values:
+    1. **Timestamps**: Raw integer values representing Unix timestamps
+    2. **Day intervals**: Values ending with 'd' (e.g., '3d' = 3 days from now)
+    3. **Year intervals**: Values ending with 'y' (e.g., '2y' = 2 years from now)
+
+    Only these formats are valid:
+    - Examples: '1609459200', '3d', '2y'
+    - Invalid: 'invalid', '5m', '10x'
+
+    The widget automatically converts day/year intervals to appropriate timestamps.
 
     Attributes:
-        See class implementation for attributes
+        valueEdited (pyqtSignal): Signal emitted when the locktime value is edited
+        locktime_threshold (int): Minimum threshold value for locktime (default: 50000000)
 
-    Example:
-        instance = HeirsLockTimeEdit(required parameters)
+    Args:
+        parent: Optional parent QWidget
+        default_index (int): Default index for the combo box (default: 1)
     """
 
+class HeirsLockTimeEdit(QWidget, _LockTimeEditor):
     valueEdited = pyqtSignal()
     locktime_threshold = 50000000
 
@@ -1365,17 +1369,6 @@ class HeirsLockTimeEdit(QWidget, _LockTimeEditor):
         self.editor.set_locktime(x, force)
 
 
-    """LockTimeRawEdit class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = LockTimeRawEdit(required parameters)
-    """
-
 class LockTimeRawEdit(QLineEdit, _LockTimeEditor):
     def __init__(self, parent=None, time_edit=None):
         QLineEdit.__init__(self, parent)
@@ -1460,17 +1453,6 @@ class LockTimeRawEdit(QLineEdit, _LockTimeEditor):
             out = min(out, self.max_allowed_value)
         self.setText(str(out))
 
-    """LockTimeHeightEdit class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = LockTimeHeightEdit(required parameters)
-    """
-
 
 class LockTimeHeightEdit(LockTimeRawEdit):
     max_allowed_value = NLOCKTIME_BLOCKHEIGHT_MAX
@@ -1501,17 +1483,6 @@ def get_max_allowed_timestamp() -> int:
         ts = 2**31 - 1  # INT32_MAX
         datetime.fromtimestamp(ts)  # test if raises
     return ts
-    """LockTimeDateEdit class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = LockTimeDateEdit(required parameters)
-    """
-
 
 
 class LockTimeDateEdit(QDateTimeEdit, _LockTimeEditor):
@@ -1543,25 +1514,6 @@ class LockTimeDateEdit(QDateTimeEdit, _LockTimeEditor):
         self.setDateTime(dt)
 
 
-    """Widget for editing percentage amounts.
-
-    Extends BTCAmountEdit to provide:
-    - Percentage-based input (0-100%)
-    - Validation of percentage values
-    - Conversion between percentage and satoshis
-    - Formatting for display
-
-    Attributes:
-        min_value (float): Minimum percentage (default 0.0)
-        max_value (float): Maximum percentage (default 100.0)
-        step (float): Increment step for percentage values
-
-    Methods:
-        value(): Return current percentage as float
-        setValue(): Set percentage value
-        validate(): Validate percentage range
-    """
-
 _NOT_GIVEN = object()  # sentinel value
 
 
@@ -1628,35 +1580,6 @@ class PercAmountEdit(BTCAmountEdit):
                 painter.drawText(
                     textRect,
                     int(Qt.AlignmentFlag.AlignRight | Qt.AlignmentFlag.AlignVCenter),
-    """Base class for dialog windows in Bitcoin After Life.
-
-    Provides common functionality for all dialog windows including:
-    - Window modal behavior
-    - Standard button layouts (OK, Cancel)
-    - Size policy management
-    - Parent window handling
-
-    Subclasses should implement:
-    - __init__: Initialize dialog components
-    - setup_ui: Create and configure UI elements
-    - connect_signals: Connect signal-slot connections
-
-    Attributes:
-        parent (QWidget): Parent window
-        plugin (BalPlugin): Plugin reference
-        title (str): Dialog window title
-
-    Methods:
-        exec_(): Show dialog modally
-        accept(): Handle dialog acceptance
-        reject(): Handle dialog rejection
-
-    Example:
-        dialog = BalDialog(parent, plugin, "My Dialog")
-        if dialog.exec_() == QDialog.Accepted:
-            # Handle acceptance
-    """
-
                     self.base_unit() + " or perc value",
                 )
 
@@ -1664,38 +1587,43 @@ class PercAmountEdit(BTCAmountEdit):
 class BalDialog(WindowModalDialog):
     def __init__(self, parent, bal_plugin, title=None, icon="icons/bal32x32.png"):
         self.parent = parent
-    """Base class for multi-step wizard dialogs.
-
-    Provides infrastructure for:
-    - Multi-page workflows
-    - Navigation between steps
-    - Progress tracking
-    - Validation at each step
-    - Final submission
-
-    Subclasses implement specific wizards:
-    - BalWizardHeirsWidget: Heir configuration
-    - BalWizardWEDownloadWidget: Wallet export download
-    - BalWizardWEWidget: Wallet export configuration
-    - BalWizardLocktimeAndFeeWidget: Locktime and fee setup
-
-    Attributes:
-        current_page (int): Current step index
-        total_pages (int): Total number of steps
-        data (dict): Collected data across steps
-
-    Methods:
-        next_page(): Move to next step
-        prev_page(): Move to previous step
-        validate_current(): Validate current step
-        finish(): Complete the wizard
-    """
-
         WindowModalDialog.__init__(self, parent, title)
         # WindowModalDialog.__init__(self,parent)
         self.setWindowIcon(read_QIcon_from_bytes(bal_plugin.read_file(icon)))
 
 
+    """
+    BalWizardDialog - A custom QDialog that implements a multi-step wizard interface.
+
+    This dialog provides a structured, step-by-step workflow for complex operations
+    in the Bal Electrum plugin, guiding users through a sequence of pages with
+    forward/backward navigation and validation.
+
+    Features:
+    - Multi-page navigation with Previous/Next buttons
+    - Automatic validation before proceeding to next page
+    - Progress tracking with visual indicators
+    - Customizable page flow and validation rules
+    - Integration with BalDialog base class for consistent styling
+
+    Usage:
+    The wizard follows a standard pattern:
+    1. Initialize with a list of page constructors
+    2. Each page is responsible for its own setup and validation
+    3. The dialog manages navigation and state between pages
+    4. Finalize action is triggered when all pages are completed
+
+    Attributes:
+        pages (list): List of page constructors for the wizard
+        current_page (int): Index of the currently displayed page
+        page_widgets (list): List of instantiated page widgets
+
+    Args:
+        parent: Optional parent QWidget
+        title (str): Title to display in the dialog header
+        pages (list): List of page constructors (callables) for each step
+    """
+
 class BalWizardDialog(BalDialog):
     def __init__(self, bal_window: "BalWindow"):
         assert bal_window
@@ -1779,17 +1707,6 @@ class BalWizardDialog(BalDialog):
         self.bal_window.update_all()
         pass
 
-    """BalWizardWidget class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = BalWizardWidget(required parameters)
-    """
-
     def closeEvent(self, event):
 
         self.bal_window.heir_list_widget.update_will_settings()
@@ -1855,17 +1772,6 @@ class BalWizardWidget(QWidget):
     def _on_previous(self):
         self.on_previous()
 
-    """BalWizardHeirsWidget class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = BalWizardHeirsWidget(required parameters)
-    """
-
     def get_content(self):
         pass
 
@@ -1900,17 +1806,6 @@ class BalWizardHeirsWidget(BalWizardWidget):
     def export_to_file(self):
         self.bal_window.export_heirs()
 
-    """BalWizardWEDownloadWidget class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = BalWizardWEDownloadWidget(required parameters)
-    """
-
     def add_heir(self):
         self.bal_window.new_heir_dialog()
         self.heir_list_widget.update()
@@ -1998,17 +1893,6 @@ class BalWizardWEDownloadWidget(BalWizardWidget):
         if self.validate():
             return self.on_next()
 
-    """BalWizardWEWidget class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = BalWizardWEWidget(required parameters)
-    """
-
     def import_json_file(self, path):
         data = read_json_file(path)
         data = self._validate(data)
@@ -2025,17 +1909,6 @@ class BalWizardWEWidget(BalWizardWidget):
     def get_content(self):
         widget = QWidget()
         vbox = QVBoxLayout(widget)
-    """BalWizardLocktimeAndFeeWidget class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = BalWizardLocktimeAndFeeWidget(required parameters)
-    """
-
         vbox.addWidget(
             WillExecutorWidget(
                 self,
@@ -2145,30 +2018,6 @@ class BalWizardLocktimeAndFeeWidget(BalWizardWidget):
                 _("Fees(sats/vbyte):"),
                 self.heir_tx_fees,
                 ("Fee to be used in the transaction"),
-    """Non-blocking progress dialog for long operations.
-
-    Provides:
-    - Indeterminate progress bar
-    - Status messages
-    - Cancel button for interruption
-    - Automatic cleanup
-    - Thread-safe operation
-
-    Used for operations like:
-    - Blockchain synchronization
-    - Transaction broadcasting
-    - Will construction
-    - Data loading
-
-    Attributes:
-        message (str): Current status message
-        can_cancel (bool): Whether operation can be cancelled
-
-    Methods:
-        update_message(): Update status message
-        cancel(): Interrupt the operation
-    """
-
             )
         )
 
@@ -2233,17 +2082,6 @@ class BalWaitingDialog(BalDialog):
         self.thread.stop()
 
     def update_message(self, msg):
-    """BalBlockingWaitingDialog class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = BalBlockingWaitingDialog(required parameters)
-    """
-
         self.message_label.setText(msg)
 
     def update(self, msg):
@@ -2263,17 +2101,6 @@ class BalBlockingWaitingDialog(BalDialog):
         vbox = QVBoxLayout(self)
         vbox.addWidget(self.message_label)
         self.finished.connect(self.deleteLater)  # see #3956
-    """bal_checkbox class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = bal_checkbox(required parameters)
-    """
-
         # show popup
         self.show()
         # refresh GUI; needed for popup to appear and for message_label to get drawn
@@ -2309,6 +2136,8 @@ class BalBuildWillDialog(BalDialog):
     COLOR_OK = "#05ad05"
 
     def __init__(self, bal_window, parent=None):
+<<<<<<< HEAD
+=======
         """Initialize the Build Will dialog.
 
         Args:
@@ -2321,6 +2150,7 @@ class BalBuildWillDialog(BalDialog):
             - Layout management
             - Network connection
         """
+>>>>>>> origin/doc
         if not parent:
             parent = bal_window.window
         BalDialog.__init__(self, parent, bal_window.bal_plugin, _("Building Will"))
@@ -2328,6 +2158,18 @@ class BalBuildWillDialog(BalDialog):
         self.updatemessage.connect(self.msg_update)
         self.bal_window = bal_window
         self.bal_plugin = bal_window.bal_plugin
+<<<<<<< HEAD
+        self.message_label = QLabel(_("Building Will:"))
+        self.vbox = QVBoxLayout(self)
+        self.vbox.addWidget(self.message_label,0)
+        self.qwidget = QWidget(self)
+        self.vbox.addWidget(self.qwidget,1)
+        self.labelsbox=QVBoxLayout(self.qwidget)
+        self.setMinimumWidth(600)
+        self.setMinimumHeight(100)
+        self.setSizePolicy(QSizePolicy.Policy.Expanding, QSizePolicy.Policy.Preferred)
+        self.labels = []
+=======
 
         # Main message label
         self.message_label = QLabel(_("Building Will:"))
@@ -2365,6 +2207,7 @@ class BalBuildWillDialog(BalDialog):
         self.network = Network.get_instance()
         self._stopping = False
 
+>>>>>>> origin/doc
         self.check_row = None
         self.inval_row = None
         self.build_row = None
@@ -2814,6 +2657,15 @@ class BalBuildWillDialog(BalDialog):
                 w.deleteLater()
 
     def msg_update(self):
+<<<<<<< HEAD
+        self.clear_layout(self.labelsbox)
+        for label in self.labels:
+            label=label.replace("\n","<br>")
+            qlabel=QLabel(label)
+            self.labelsbox.addWidget(QLabel(label),1)
+        self.setMinimumHeight(30*(len(self.labels)+2))
+        
+=======
         """Updates the UI with new messages using a debounced queue system.
 
         This method implements the following logic:
@@ -2874,36 +2726,6 @@ class BalBuildWillDialog(BalDialog):
 
             except Exception as e:
                 # Log errors without interrupting processing
-    """Table widget for managing heir configurations.
-
-    Provides a tabular interface for:
-    - Adding, editing, and removing heirs
-    - Configuring inheritance percentages
-    - Setting heir addresses and conditions
-    - Validating heir configurations
-    - Sorting and filtering heir list
-
-    Inherits from MyTreeView for:
-    - Column-based data display
-    - Sorting functionality
-    - Filtering capabilities
-    - Model-view architecture
-
-    Attributes:
-        bal_window (BalWindow): Reference to main window
-        main_window (QMainWindow): Parent window
-        model (QStandardItemModel): Data model for heirs
-
-    Columns:
-        NAME: Heir name
-        ADDRESS: Bitcoin address
-        AMOUNT: Inheritance percentage
-
-    Example:
-        widget = HeirListWidget(window, parent)
-        widget.update()  # Refresh heir list
-    """
-
                 import logging
                 logging.error(f"Error creating label in BalBuildWillDialog: {e}")
 
@@ -2911,6 +2733,7 @@ class BalBuildWillDialog(BalDialog):
         self._message_queue = []
         self.setMinimumHeight(min(30 * (len(self.labels) + 2), 400))  # Max height limit
 
+>>>>>>> origin/doc
 
     def get_text(self):
         return self.message_label.text()
@@ -3183,34 +3006,6 @@ class HeirListWidget(MyTreeView, MessageBoxMixin):
 
         return toolbar
 
-    """Widget for previewing Will documents before signing.
-
-    Provides functionality to:
-    - Render Will in human-readable format
-    - Highlight important clauses and conditions
-    - Show inheritance distribution
-    - Validate Will structure
-    - Generate PDF preview
-
-    Uses MyTreeView for:
-    - Column-based preview display
-    - Sorting and filtering
-    - Efficient rendering of large documents
-
-    Attributes:
-        bal_window (BalWindow): Reference to main window
-        main_window (QMainWindow): Parent window
-
-    Methods:
-        update(): Refresh preview display
-        validate(): Check Will structure
-        export_pdf(): Generate PDF document
-
-    Example:
-        preview = PreviewList(window, parent)
-        preview.update()
-    """
-
     def update_will_settings(self):
         try:
             self.heir_locktime.set_locktime(self.bal_window.will_settings["locktime"])
@@ -3488,17 +3283,6 @@ class PreviewList(MyTreeView):
         close_window.build_will_task()
 
         will = {}
-    """PreviewDialog class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = PreviewDialog(required parameters)
-    """
-
         for wid, w in self.bal_window.willitems.items():
             if (
                 w.get_status("VALID")
@@ -3580,17 +3364,6 @@ class PreviewDialog(BalDialog, MessageBoxMixin):
     def update(self):
         self.transactions_list.update()
 
-    """WillDetailDialog class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = WillDetailDialog(required parameters)
-    """
-
     def is_hidden(self):
         return self.isMinimized() or self.isHidden()
 
@@ -3691,17 +3464,6 @@ class WillDetailDialog(BalDialog):
             toggle = _("Unhide")
         self.toggle_replace_button.setText(f"{toggle} {_('replaced')}")
         self.update()
-    """WillWidget class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = WillWidget(required parameters)
-    """
-
 
     def toggle_invalidated(self):
         self.bal_window.bal_plugin.hide_invalidated()
@@ -3793,17 +3555,6 @@ class WillWidget(QWidget):
                     decoded_amount = Util.decode_amount(
                         self.will[w].we["base_fee"], self.parent.decimal_point
                     )
-    """WillExecutorListWidget class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = WillExecutorListWidget(required parameters)
-    """
-
 
                     detaillayout.addWidget(
                         qlabel(
@@ -4035,31 +3786,6 @@ class WillExecutorListWidget(MyTreeView):
                 items[self.Columns.BASE_FEE].setData(
                     url, self.ROLE_HEIR_KEY + self.Columns.BASE_FEE
                 )
-    """Widget for executing Will transactions.
-
-    Handles:
-    - Transaction construction
-    - Fee calculation
-    - Signature collection
-    - Transaction broadcasting
-    - Status monitoring
-
-    Coordinates with:
-    - WillExecutorListWidget: List of executors
-    - WillExecutorDialog: Detailed executor configuration
-    - BalWindow: Main application window
-
-    Attributes:
-        will (Will): Will being executed
-        executors (list): List of executor configurations
-        network (Network): Network interface
-
-    Methods:
-        execute(): Start transaction execution
-        stop(): Interrupt execution
-        validate(): Check transaction validity
-    """
-
                 items[self.Columns.INFO].setData(
                     url, self.ROLE_HEIR_KEY + self.Columns.INFO
                 )
@@ -4164,17 +3890,6 @@ class WillExecutorWidget(QWidget, MessageBoxMixin):
             self.willexecutors_list.update,
         )
 
-    """WillExecutorDialog class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = WillExecutorDialog(required parameters)
-    """
-
     def update_willexecutors(self, wes=None):
         if not wes:
             wes = self.willexecutors_list
@@ -4210,17 +3925,6 @@ class WillExecutorDialog(BalDialog, MessageBoxMixin):
         self.setMinimumSize(1000, 200)
 
         vbox = QVBoxLayout(self)
-    """CheckAliveException class for Bitcoin After Life.
-
-    This class provides functionality for managing various Bitcoin After Life features.
-
-    Attributes:
-        See class implementation for attributes
-
-    Example:
-        instance = CheckAliveException(required parameters)
-    """
-
         self.will_executor_list_widget = WillExecutorWidget(
             self, self.bal_window, self.willexecutors_list
         )
@@ -4247,6 +3951,8 @@ class CheckAliveException(Exception):
     def __init__(self,timestamp_to_check):
             self.timestamp_to_check = timestamp_to_check
     def __str__(self):
+<<<<<<< HEAD
+=======
 
     def __del__(self):
         """Explicit cleanup to prevent memory leaks.
@@ -4263,4 +3969,5 @@ class CheckAliveException(Exception):
             self._message_timer.deleteLater()
         self.clear_layout(self.labelsbox)
 
+>>>>>>> origin/doc
         return "Check alive expired please update it: {}".format(datetime.fromtimestamp(self.timestamp_to_check).isoformat())