ACAPI_GraphicalOverride_CreateOverrideRule rejects special pen values 0 and -1 for fillBackgroundPen

Mathias Jonathan — Sun, 28 Jun 2026 01:56:47 GMT

Hello,
I am developing a Tapir add-on command that reads graphical override rules and allows creating new ones programmatically. While testing, I found an inconsistency between ACAPI_GraphicalOverride_GetOverrideRuleById and ACAPI_GraphicalOverride_CreateOverrideRule regarding the fillBackgroundPenOverride field.

WHAT I FOUND
When I call GetOverrideRuleById on rules that use special fill background options set from the ArchiCAD UI, the API correctly returns the following penIndex values in the fillBackgroundPenOverride field:
penIndex 0 for "Transparent" background
penIndex -1 for "Window Background(? Not sure of term in English)"
However, when I try to call CreateOverrideRule using those exact same values, I get APIERR_BADPARS (-2130313112) for both penIndex 0 and penIndex -1.
Other values work fine:
penIndex 1 through 255 (normal pen palette): OK
penIndex 1001 (zone category color): OK
API_RGBColor (any color): OK

REPRODUCTION STEPS
In ArchiCAD UI, create a graphical override rule with fillBackgroundPenOverride set to "Transparent" (pen 0) or "Window Background" (pen -1).
Read it back with ACAPI_GraphicalOverride_GetOverrideRuleById. The value is correctly returned.
Try to create a new rule using the same API_OverrideRuleStyle. CreateOverrideRule returns APIERR_BADPARS.

Minimal C++ reproduction:
API_OverrideRuleGroup ruleGroup; ruleGroup.name = "Test Group"; ACAPI_GraphicalOverride_CreateOverrideRuleGroup(ruleGroup); API_OverrideRule rule; rule.name = "Test Rule"; rule.criterionXML = ""; rule.style.fillBackgroundPenOverride = static_cast<short>(0); // transparent -- FAILS // rule.style.fillBackgroundPenOverride = static_cast<short>(-1); // window bg -- FAILS // rule.style.fillBackgroundPenOverride = static_cast<short>(1); // normal pen -- OK GSErrCode err = ACAPI_GraphicalOverride_CreateOverrideRule(rule, ruleGroup.guid); // err == APIERR_BADPARS for penIndex 0 and -1

EXPECTED BEHAVIOR
If GetOverrideRuleById returns penIndex 0 or penIndex -1 as valid values for fillBackgroundPenOverride, then CreateOverrideRule should also accept those same values. The round-trip (read a rule, create a copy of it) should work without any special-casing.

This was tested as part of the open-source Tapir add-on project.

Thank you for looking into this.

topic ACAPI_GraphicalOverride_CreateOverrideRule rejects special pen values 0 and -1 for fillBackgroundPen in Archicad C++ API

ACAPI_GraphicalOverride_CreateOverrideRule rejects special pen values 0 and -1 for fillBackgroundPen