from __future__ import annotations
import re
import sys
import FreeCAD
from FreeCADGui import _error_text
_PROVIDERS: dict = {}
_PROVIDER_APPLIED: dict = {}
_PROVIDER_DOCUMENT = None
_PROVIDER_SERIAL: int = 0
_PROVIDER_REPORTED: set = set()
PROVIDER_PREFERENCES = "User parameter:BaseApp/Preferences/Mods"
_SETTING_KINDS = ("text", "bool", "int", "float", "quantity", "enum", "color")
_SETTING_TYPES = {
"text": "App::PropertyString",
"bool": "App::PropertyBool",
"int": "App::PropertyInteger",
"float": "App::PropertyFloat",
"quantity": "App::PropertyQuantity",
"enum": "App::PropertyEnumeration",
"color": "App::PropertyString",
}
_SETTING_DEFAULTS = {
"text": "",
"bool": False,
"int": 0,
"float": 0.0,
"quantity": 0.0,
"color": "#000000",
}
_SETTING_REPORTED: set = set()
_DOCUMENT_LISTENERS: list = []
_OBSERVER_REPORTED: set = set()
_DOCUMENT_HOOKS = {
"created": "onDocumentCreated",
"activated": "onDocumentActivated",
"deactivated": "onDocumentDeactivated",
"closed": "onDocumentClosed",
}
_COLOR_RE = re.compile(r"#[0-9a-fA-F]{6}\Z")
def addDocumentListener(observer) -> None:
if any(existing is observer for existing in _DOCUMENT_LISTENERS):
return
_DOCUMENT_LISTENERS.append(observer)
def removeDocumentListener(observer) -> bool:
for index, existing in enumerate(_DOCUMENT_LISTENERS):
if existing is observer:
del _DOCUMENT_LISTENERS[index]
_OBSERVER_REPORTED.difference_update(
{key for key in _OBSERVER_REPORTED if key[0] == id(observer)}
)
return True
return False
def _report_observer(observer, hook: str, exc: BaseException) -> None:
key = (id(observer), hook)
if key in _OBSERVER_REPORTED:
return
_OBSERVER_REPORTED.add(key)
label = getattr(observer, "__name__", None) or type(observer).__name__
print(
f"FerroCADGui: document observer {label!r} {hook} raised: "
f"{_error_text(exc)}",
file=sys.stderr,
)
def _document_event(event: str, name: str) -> None:
hook = _DOCUMENT_HOOKS[event]
for observer in list(_DOCUMENT_LISTENERS):
callback = getattr(observer, hook, None)
if not callable(callback):
continue
try:
callback(name)
except Exception as exc: _report_observer(observer, hook, exc)
if event == "closed":
gui = sys.modules.get("FreeCADGui")
forget = getattr(gui, "_forget_document", None) if gui is not None else None
if forget is not None:
try:
forget(name)
except Exception as exc: _report_observer(gui, "_forget_document", exc)
def _provider_prefs():
return FreeCAD.ParamGet(PROVIDER_PREFERENCES).GetGroup("Providers")
def _report_provider(feature, backend, hook: str, exc: BaseException) -> None:
key = (feature, backend, hook)
if key in _PROVIDER_REPORTED:
return
_PROVIDER_REPORTED.add(key)
print(
f"FerroCADGui: provider {backend!r} for {feature!r} {hook} raised: "
f"{_error_text(exc)}",
file=sys.stderr,
)
def _report_setting(feature, backend, name: str, exc: BaseException) -> None:
key = (feature, backend, name)
if key in _SETTING_REPORTED:
return
_SETTING_REPORTED.add(key)
print(
f"FerroCADGui: setting {name!r} of provider {backend!r} for {feature!r} "
f"raised: {_error_text(exc)}",
file=sys.stderr,
)
def registerProvider(
feature: str,
backend: str,
label: str,
command=None,
priority: int = 0,
activate=None,
deactivate=None,
refresh=None,
settings=None,
skin=None,
):
global _PROVIDER_SERIAL
if not isinstance(feature, str) or not feature:
raise ValueError("a provider feature must be a non-empty string")
if not isinstance(backend, str) or not backend:
raise ValueError("a provider backend must be a non-empty string")
if command is not None and not isinstance(command, str):
raise TypeError("a provider command must be a command id string or None")
if activate is not None and not callable(activate):
raise TypeError(f"provider {feature!r}/{backend!r} activate is not callable")
if deactivate is not None and not callable(deactivate):
raise TypeError(f"provider {feature!r}/{backend!r} deactivate is not callable")
if refresh is not None and not callable(refresh):
raise TypeError(f"provider {feature!r}/{backend!r} refresh is not callable")
schema = _validate_settings(feature, backend, settings)
if skin is not None and not isinstance(skin, str):
raise TypeError(f"provider {feature!r}/{backend!r} skin must be WGSL source text")
source = None if skin is None else skin.strip()
if source == "":
raise ValueError(f"provider {feature!r}/{backend!r} skin is empty")
text = str(label if label is not None else backend).strip()
records = _PROVIDERS.get(feature)
if records is None:
records = _PROVIDERS.setdefault(feature, {})
before = _selected(feature)
existing = records.get(backend)
order = existing["order"] if existing is not None else _PROVIDER_SERIAL
if existing is None:
_PROVIDER_SERIAL += 1
records[backend] = {
"feature": feature,
"backend": backend,
"label": text or backend,
"command": command,
"priority": int(priority),
"order": order,
"activate": activate,
"deactivate": deactivate,
"refresh": refresh,
"settings": schema,
"skin": source,
}
_PROVIDER_REPORTED.difference_update(
{key for key in _PROVIDER_REPORTED if key[0] == feature and key[1] == backend}
)
_SETTING_REPORTED.difference_update(
{key for key in _SETTING_REPORTED if key[0] == feature and key[1] == backend}
)
for spec in schema:
if spec["kind"] not in _SETTING_KINDS:
_report_setting(
feature,
backend,
spec["name"],
ValueError(
f"unknown kind {spec['kind']!r}; the row is read-only"
),
)
selected = _selected(feature)
if selected == backend and before is not None and before != backend:
outgoing = records.get(before)
if outgoing is not None:
_deactivate_on_takeover(outgoing, feature)
if _PROVIDER_APPLIED.get(feature) == before:
_PROVIDER_APPLIED.pop(feature, None)
return _manifest(records[backend], feature)
def refreshProviders(feature: str) -> dict:
result = {
"ok": True,
"feature": feature,
"backend": None,
"view": {},
"status": "",
"errors": [],
}
records = _PROVIDERS.get(feature)
if not records:
return result
backend = _selected(feature)
result["backend"] = backend
statuses = []
_invoke_provider(records[backend], feature, "refresh", result, statuses)
if statuses:
result["status"] = "; ".join(statuses)
return result
def _deactivate_on_takeover(record, feature) -> None:
callback = record.get("deactivate")
if callback is None:
return
try:
callback()
except Exception as exc: _report_provider(feature, record["backend"], "deactivate", exc)
def unregisterProvider(feature: str, backend: str) -> bool:
records = _PROVIDERS.get(feature)
if not records or backend not in records:
return False
del records[backend]
if not records:
_PROVIDERS.pop(feature, None)
if _PROVIDER_APPLIED.get(feature) == backend:
_PROVIDER_APPLIED.pop(feature, None)
_PROVIDER_REPORTED.difference_update(
{key for key in _PROVIDER_REPORTED if key[0] == feature and key[1] == backend}
)
_SETTING_REPORTED.difference_update(
{key for key in _SETTING_REPORTED if key[0] == feature and key[1] == backend}
)
return True
def _manifest(record, feature, active=None):
if active is None:
active = _selected(feature)
return {
"feature": feature,
"backend": record["backend"],
"label": record["label"],
"command": record["command"],
"priority": record["priority"],
"active": record["backend"] == active,
}
def _selected(feature):
records = _PROVIDERS.get(feature)
if not records:
return None
saved = _provider_prefs().GetString(feature, "")
if saved in records:
return saved
return max(
records.values(),
key=lambda record: (record["priority"], -record["order"]),
)["backend"]
def providers(feature=None) -> list:
if feature is not None:
records = _PROVIDERS.get(feature)
if not records:
return []
active = _selected(feature)
return [_manifest(record, feature, active) for record in records.values()]
entries = []
for name in _PROVIDERS:
active = _selected(name)
entries.extend(
_manifest(record, name, active) for record in _PROVIDERS[name].values()
)
return entries
def activeProvider(feature):
return _selected(feature)
def providerSkin(feature, backend=None):
records = _PROVIDERS.get(feature)
if not records:
return None
if backend is None:
backend = _selected(feature)
record = records.get(backend)
if record is None:
return None
return record.get("skin")
def setActiveProvider(feature: str, backend: str) -> dict:
global _PROVIDER_DOCUMENT
records = _PROVIDERS.get(feature)
if not records:
raise ValueError(f"no provider is registered for feature {feature!r}")
if backend not in records:
raise ValueError(f"{backend!r} does not provide feature {feature!r}")
declared = _selected(feature)
applied = _PROVIDER_APPLIED.get(feature)
outgoing_backend = applied if applied is not None else declared
_provider_prefs().SetString(feature, backend)
result = {
"ok": True,
"feature": feature,
"backend": backend,
"previous": declared,
"view": {},
"status": "",
"errors": [],
}
statuses = []
if outgoing_backend != backend:
outgoing = records.get(outgoing_backend) if outgoing_backend is not None else None
if outgoing is not None:
_invoke_provider(outgoing, feature, "deactivate", result, statuses)
_invoke_provider(records[backend], feature, "activate", result, statuses)
elif applied is None:
_invoke_provider(records[backend], feature, "activate", result, statuses)
_PROVIDER_APPLIED[feature] = backend
document = FreeCAD.activeDocument()
if document is not None:
_PROVIDER_DOCUMENT = document.Name
message = f"{feature}: {backend} is the active provider"
if statuses:
message = "; ".join(statuses) + "; " + message
if result["errors"]:
message += " (reported: " + "; ".join(result["errors"]) + ")"
result["status"] = message
return result
def _invoke_provider(record, feature, hook, result, statuses) -> None:
callback = record.get(hook)
if callback is None:
return
try:
value = callback()
except Exception as exc: _report_provider(feature, record["backend"], hook, exc)
result["errors"].append(f"{hook}: {_error_text(exc)}")
return
if not isinstance(value, dict):
return
view = value.get("view")
if isinstance(view, dict):
result["view"].update(view)
status = value.get("status")
if status:
statuses.append(str(status))
class _ProviderDocumentObserver:
def onDocumentActivated(self, name) -> None:
_activate_document_providers(name)
def onDocumentDeactivated(self, name) -> None:
_deactivate_document_providers(name)
def onDocumentClosed(self, name) -> None:
_deactivate_document_providers(name)
def _activate_document_providers(name) -> None:
global _PROVIDER_DOCUMENT
if not isinstance(name, str) or not name:
return
if _PROVIDER_DOCUMENT == name:
return
if _PROVIDER_DOCUMENT is not None:
_deactivate_document_providers(_PROVIDER_DOCUMENT)
for feature, records in list(_PROVIDERS.items()):
backend = _selected(feature)
record = records.get(backend)
if record is None:
continue
result = {
"ok": True,
"feature": feature,
"backend": backend,
"view": {},
"status": "",
"errors": [],
}
_invoke_provider(record, feature, "activate", result, [])
_PROVIDER_APPLIED[feature] = backend
_PROVIDER_DOCUMENT = name
def _deactivate_document_providers(name) -> None:
global _PROVIDER_DOCUMENT
if _PROVIDER_DOCUMENT != name:
return
_PROVIDER_DOCUMENT = None
for feature, backend in list(_PROVIDER_APPLIED.items()):
_PROVIDER_APPLIED.pop(feature, None)
records = _PROVIDERS.get(feature)
record = records.get(backend) if records else None
if record is None:
continue
result = {
"ok": True,
"feature": feature,
"backend": backend,
"view": {},
"status": "",
"errors": [],
}
_invoke_provider(record, feature, "deactivate", result, [])
addDocumentListener(_ProviderDocumentObserver())
def _settings_group(feature, backend):
return FreeCAD.ParamGet(f"{PROVIDER_PREFERENCES}/{feature}/{backend}")
def _validate_settings(feature, backend, settings) -> list:
if settings is None:
return []
if not isinstance(settings, (list, tuple)):
raise TypeError(
f"provider {feature!r}/{backend!r} settings must be a list of dicts"
)
schema = []
names = set()
for index, entry in enumerate(settings):
if not isinstance(entry, dict):
raise TypeError(
f"provider {feature!r}/{backend!r} setting #{index} is not a dict"
)
name = entry.get("name")
if not isinstance(name, str) or not name.strip():
raise ValueError(
f"provider {feature!r}/{backend!r} setting #{index} needs a "
"non-empty 'name'"
)
name = name.strip()
if name in names:
raise ValueError(
f"provider {feature!r}/{backend!r} declares setting {name!r} twice"
)
names.add(name)
kind = entry.get("kind")
if not isinstance(kind, str) or not kind.strip():
raise ValueError(
f"provider {feature!r}/{backend!r} setting {name!r} needs a 'kind'"
)
spec = {
"name": name,
"kind": kind.strip(),
"label": str(entry.get("label") or name),
}
unit = entry.get("unit")
if unit is not None:
if not isinstance(unit, str) or not unit.strip():
raise ValueError(
f"provider {feature!r}/{backend!r} setting {name!r} has a "
"non-string 'unit'"
)
spec["unit"] = unit.strip()
choices = entry.get("choices")
if choices is not None:
if not isinstance(choices, (list, tuple)) or not all(
isinstance(choice, str) and choice for choice in choices
):
raise ValueError(
f"provider {feature!r}/{backend!r} setting {name!r} needs "
"'choices' to be a list of non-empty strings"
)
spec["choices"] = list(choices)
if spec["kind"] == "enum" and not spec.get("choices"):
raise ValueError(
f"provider {feature!r}/{backend!r} setting {name!r} has kind "
"'enum' but no 'choices'"
)
for bound in ("min", "max"):
value = entry.get(bound)
if value is None:
continue
if isinstance(value, bool) or not isinstance(value, (int, float)):
raise TypeError(
f"provider {feature!r}/{backend!r} setting {name!r} "
f"'{bound}' must be a number"
)
spec[bound] = float(value)
if "min" in spec and "max" in spec and spec["min"] > spec["max"]:
raise ValueError(
f"provider {feature!r}/{backend!r} setting {name!r} has "
f"min > max ({spec['min']:g} > {spec['max']:g})"
)
for hook in ("get", "set"):
callback = entry.get(hook)
if callback is None:
continue
if not callable(callback):
raise TypeError(
f"provider {feature!r}/{backend!r} setting {name!r} "
f"'{hook}' is not callable"
)
spec[hook] = callback
if "default" in entry:
default = entry["default"]
if spec["kind"] in _SETTING_KINDS:
default = _coerce_setting(spec, default)
spec["default"] = default
elif spec["kind"] == "enum":
spec["default"] = spec["choices"][0]
else:
spec["default"] = _SETTING_DEFAULTS.get(spec["kind"], "")
schema.append(spec)
return schema
def _coerce_setting(spec, value):
kind = spec["kind"]
name = spec["name"]
if kind == "text":
result = value if isinstance(value, str) else str(value)
elif kind == "bool":
if isinstance(value, bool):
result = value
elif isinstance(value, (int, float)):
result = bool(value)
elif isinstance(value, str):
text = value.strip().lower()
if text in ("1", "true", "yes", "on"):
result = True
elif text in ("0", "false", "no", "off", ""):
result = False
else:
raise ValueError(f"setting {name!r} expects true or false")
else:
raise ValueError(f"setting {name!r} expects true or false")
elif kind == "int":
if isinstance(value, bool):
raise ValueError(f"setting {name!r} expects an integer")
try:
number = float(value) if isinstance(value, str) else value
except (TypeError, ValueError):
raise ValueError(f"setting {name!r} expects an integer") from None
if isinstance(number, float) and not number.is_integer():
raise ValueError(f"setting {name!r} expects an integer")
try:
result = int(number)
except (TypeError, ValueError):
raise ValueError(f"setting {name!r} expects an integer") from None
elif kind == "float":
if isinstance(value, bool):
raise ValueError(f"setting {name!r} expects a number")
try:
result = float(value)
except (TypeError, ValueError):
raise ValueError(f"setting {name!r} expects a number") from None
elif kind == "quantity":
result = _quantity_value(spec, value)
elif kind == "enum":
text = value if isinstance(value, str) else str(value)
if text not in spec["choices"]:
choices = ", ".join(repr(choice) for choice in spec["choices"])
raise ValueError(
f"setting {name!r} must be one of {choices}; got {text!r}"
)
result = text
elif kind == "color":
text = str(value).strip()
if not _COLOR_RE.match(text):
raise ValueError(
f"setting {name!r} expects a colour as #rrggbb; got {text!r}"
)
result = text.lower()
else:
raise ValueError(f"setting {name!r} has unsupported kind {kind!r}")
if kind in ("int", "float", "quantity"):
minimum = spec.get("min")
maximum = spec.get("max")
if minimum is not None and result < minimum:
raise ValueError(
f"setting {name!r} must be at least {minimum:g}; got {result:g}"
)
if maximum is not None and result > maximum:
raise ValueError(
f"setting {name!r} must be at most {maximum:g}; got {result:g}"
)
return result
def _quantity_value(spec, value) -> float:
name = spec["name"]
unit = spec.get("unit")
if isinstance(value, FreeCAD.Units.Quantity):
quantity = value
elif isinstance(value, bool):
raise ValueError(f"setting {name!r} expects a quantity")
elif isinstance(value, (int, float)):
quantity = (
FreeCAD.Units.Quantity(float(value), unit)
if unit
else FreeCAD.Units.Quantity(float(value))
)
else:
text = str(value).strip()
try:
number = float(text)
except ValueError:
number = None
if number is not None:
quantity = (
FreeCAD.Units.Quantity(number, unit)
if unit
else FreeCAD.Units.Quantity(number)
)
else:
try:
quantity = FreeCAD.Units.Quantity(text)
except Exception as exc:
raise ValueError(
f"setting {name!r} expects a quantity: {exc}"
) from None
if not unit:
return quantity.Value
try:
return quantity.getValueAs(unit).Value
except Exception as exc:
raise ValueError(
f"setting {name!r} expects a quantity in {unit!r}: {exc}"
) from None
def _display_setting(spec, value) -> str:
if spec["kind"] != "quantity":
return str(value)
if isinstance(value, FreeCAD.Units.Quantity):
return str(value)
unit = spec.get("unit")
if not unit:
return str(value)
try:
return str(FreeCAD.Units.Quantity(float(value), unit))
except Exception:
return str(value)
def _read_setting(spec, group):
getter = spec.get("get")
if getter is not None:
return getter(), "computed"
kind = spec["kind"]
name = spec["name"]
default = spec["default"]
if kind not in _SETTING_KINDS:
return default, "unsupported kind"
if kind == "bool":
return group.GetBool(name, bool(default)), "provider"
if kind == "int":
return group.GetInt(name, int(default)), "provider"
if kind in ("float", "quantity"):
return group.GetFloat(name, float(default)), "provider"
return group.GetString(name, str(default)), "provider"
def _write_setting(spec, group, value) -> None:
kind = spec["kind"]
name = spec["name"]
if kind == "bool":
group.SetBool(name, bool(value))
elif kind == "int":
group.SetInt(name, int(value))
elif kind in ("float", "quantity"):
group.SetFloat(name, float(value))
else:
group.SetString(name, str(value))
def settings(feature: str, backend=None) -> list:
records = _PROVIDERS.get(feature)
if not records:
return []
if backend is None:
backend = _selected(feature)
record = records.get(backend)
if record is None:
return []
schema = record.get("settings") or []
if not schema:
return []
group = _settings_group(feature, backend)
rows = []
for spec in schema:
try:
raw, status = _read_setting(spec, group)
except Exception as exc: _report_setting(feature, backend, spec["name"], exc)
raw, status = spec["default"], "error"
kind = spec["kind"]
has_get = spec.get("get") is not None
has_set = spec.get("set") is not None
row = {
"name": spec["name"],
"label": spec["label"],
"type": _SETTING_TYPES.get(kind, ""),
"value": _display_setting(spec, raw),
"status": status,
"editable": kind in _SETTING_KINDS and (has_set or not has_get),
"kind": kind,
}
if "unit" in spec:
row["unit"] = spec["unit"]
if "choices" in spec:
row["choices"] = list(spec["choices"])
rows.append(row)
return rows
def setSetting(feature: str, name: str, value) -> dict:
records = _PROVIDERS.get(feature)
if not records:
return {
"ok": False,
"error": f"no provider is registered for feature {feature!r}",
}
backend = _selected(feature)
schema = records[backend].get("settings") or []
spec = next((entry for entry in schema if entry["name"] == name), None)
if spec is None:
return {
"ok": False,
"error": f"no setting {name!r} for feature {feature!r}",
}
kind = spec["kind"]
if kind not in _SETTING_KINDS:
return {
"ok": False,
"error": f"setting {name!r} has unsupported kind {kind!r}",
}
setter = spec.get("set")
if spec.get("get") is not None and setter is None:
return {"ok": False, "error": f"setting {name!r} is read-only"}
try:
coerced = _coerce_setting(spec, value)
except Exception as exc: return {"ok": False, "error": str(exc)}
if setter is not None:
try:
setter(coerced)
except Exception as exc: _report_setting(feature, backend, name, exc)
return {"ok": False, "error": _error_text(exc)}
else:
try:
_write_setting(spec, _settings_group(feature, backend), coerced)
except Exception as exc: return {"ok": False, "error": _error_text(exc)}
refresh = refreshProviders(feature)
display = _display_setting(spec, coerced)
return {
"ok": True,
"feature": feature,
"backend": backend,
"name": name,
"value": display,
"status": f"{feature}: {name} = {display}",
"view": refresh.get("view", {}),
"errors": list(refresh.get("errors", [])),
}
def _coin_module():
try:
from pivy import coin
except ImportError as exc: raise RuntimeError(
"overlays need the Coin facade (pivy.coin) in this build"
) from exc
return coin
def addOverlay(node) -> None:
return _coin_module().addOverlay(node)
def removeOverlay(node) -> bool:
return _coin_module().removeOverlay(node)
class _ViewState:
grid = False
axis_cross = True
projection = "persp"
grid_minor = 10.0
grid_major = 100.0
grid_radius = None
ViewState = _ViewState()
__all__ = [
"addDocumentListener",
"removeDocumentListener",
"registerProvider",
"unregisterProvider",
"providers",
"providerSkin",
"activeProvider",
"setActiveProvider",
"refreshProviders",
"settings",
"setSetting",
"addOverlay",
"removeOverlay",
"ViewState",
"PROVIDER_PREFERENCES",
]