Type annotations

dawiq.typing provides special type annotations.

class dawiq.typing.FieldWidgetProtocol(*args, **kwargs)

Bases: Protocol

Type annotation for field widget object.

fieldValue() → Any

Value that the field widget represents.

This is the API for the delegate to get the data from the field widget. For example, in BoolCheckBox this method converts the current check state to bool and returns.

If the field value is None, it typically indicates that the widget is empty and the delegate should specially handle it. One of the few exceptions is BoolCheckBox where None indicates partially checked state for fuzzy boolean value.

When the field value is changed, fieldValueChanged signal must emit the new value. When the field is edited by user, fieldEdited signal must be emitted with empty argument.

setFieldValue(value: Any)

Set the value to the field widget.

This method is the API for the delegate to set the data to the widget. For example, in BoolCheckBox this method converts bool to Qt.CheckState and sets to the widget.

For valid value, its type must be strictly checked and TypeError must be raised on invalid input.

fieldName() → str

Name of the field.

It is recommended to make this name visible in the widget without affecting the data value. Placeholder text of the line edit or title of the group box are good examples.

setFieldName(name: str)

Set the name of the field.

setRequired(required: bool)

Set if self represents a required field.

If required is True, it indicates that the field is mandatory. On such case, this methods checks the fieldValue() of self and sets requiresFieldValue property of the editor widget. If the data value of required field is missing, the property is set to be True.

widget.setProperty("requiresFieldValue", True)
widget.style().unpolish(widget)
widget.style().polish(widget)

The editor widget is usually self, but there are exceptions such as TupleGroupBox. Note that the widget needs to be re-polished.

Style sheet can be set to highlight the required field with empty widget. Common way is to set the style sheet of QApplication before starting the app.

qApp.setStyleSheet(
    "*[requiresFieldValue=true]{border: 1px solid red}"
)

Notes

This method is designed to be called by the DataclassDelegate, not directly by the user.