Surface Finish Plugin Updates

Introduction
New finish idioms and behaviors
Updating Plugins

Also see :

Quick Notes
Surface Finish (topic)
General Settings (member general settings)
Text editor (for entering assembly module code)

Introduction

In SDS2 2023, new features for material ﬁnishes were introduced. To fully take advantage of these features and provide a consistent user experience, plugins should be updated to employ new ﬁnish idioms and use new ﬁnish widgets that support these idioms.

New ﬁnish idioms and behaviors

Formerly, the value of a ﬁnish ﬁeld was one of a ﬁxed set of strings like “Red Oxide” or “Yellow Zinc”. Now ﬁnish ﬁelds are integers that index into the user-modiﬁable ﬁnish table in setup.

Members now have a primary ﬁnish, and may have secondary ﬁnishes. On member edit windows, a “Reset” button is placed next to the primary ﬁnish. When Reset is checked, process will change the ﬁnish of all the material on the member to “Auto”, forcing the material to use whatever ﬁnish is speciﬁed by the member or component that created the material, rather than whatever ﬁnish a user may have manually set on the material via material edit. When a user has changed the ﬁnish on a material created by the member, an indicator will appear next to the member’s Reset checkbutton with a tooltip that states “Submaterials have user ﬁnishes”.

Secondary ﬁnish ﬁelds on members such as Stair or HandRail as well as ﬁnish ﬁelds on material will have an “Auto” checkbox next to the ﬁnish combobox. When Auto is checked on member secondary ﬁnishes, the ﬁnish ﬁeld will use whatever is speciﬁed for the member’s primary ﬁnish. When Auto is checked on a ﬁnish ﬁeld in a material edit dialog, it will use whatever ﬁnish is speciﬁed by the member when the member is reprocessed.

Members that add material to a diﬀerent member should use the default ﬁnish on that other member when adding material to that other member. Secondary ﬁnishes on members have formerly been used to set color and provide the aesthetically pleasing contrast between diﬀerent parts of a member. Use of secondary ﬁnishes for this purpose is deprecated. If parts on a member typically all use the same ﬁnish, consider removing the unnecessary secondary ﬁnishes.

On all edit windows, the ﬁnish combobox should be placed directly beneath the grade combobox.

Members should no longer use the galvanized attribute or have a galvanized checkbox in the member edit dialog. The ﬁnish attribute is used instead.

Updating plugins with the new finish idioms

Update or add primary ﬁnish widget on Member Edit dialog

If there is an existing ﬁnish widget that speciﬁes the primary ﬁnish to be used on a member, delete that widget. Add or replace the ﬁnish widget with this:

from dialog.choose_file import ForceChooseFinish
...
primary_finish_widget = ForceChooseFinish(parent_widget)

No other arguments to ForceChooseFinish() should be necessary.

The ﬁnish widget should be placed directly underneath the grade widget. The galvanized widget should be removed.

Update member material creation code to use primary ﬁnish

Materials that are created with a hard-coded ﬁnish or use the old primaryﬁnish now need to use the new primary ﬁnish. To do this, assign Member-Base.default_ﬁnish_id to the material ﬁnish attribute.

For example, this:

pl = RectPlate()
pl.SurfaceFinish = self.my_old_primary_finish

or this:

pl = RectPlate()
pl.SurfaceFinish = 'Red Oxide'

or this:

pl = RectPlate()
# No finish attribute assignment

The following should be changed for a plate created in a custom member method:

pl = RectPlate()
pl.SurfaceFinish = self.default_finish_id

Remove or replace any code that uses the galvanized attribute.

Update member secondary ﬁnish widgets

from dialog.choose_file import ForceChooseFinish, AutoChooseFinish
...
primary_finish_widget = ForceChooseFinish(parent_widget)
...
myfinishfield_widget = AutoChooseFinish(parent_widget, auto_name='auto_myfinishfield', combobox_name='myfinishfield')

#Add rules to update the secondary finish widget when
#it is set to auto or the primary finish is changed.

def enforce_auto_finish(auto_finish_widget, primary_finish_widget):
	if auto_finish_widget.checkbox.Get():
		auto_finish_widget.Set(primary_finish_widget.Get())
myfinishfield_widget.checkbox.AddRule(Always, lambda _: enforce_auto_finish(myfinishfield_widget, primary_finish_widget)
primary_finish_widget.AddRule(Modified, lambda _: enforce_auto_finish(myfinishfield_widget, primary_finish_widget)

Update other ﬁnish widgets

Non-primary ﬁnish widgets include any ﬁnish ﬁelds on dialogs for custom components, material, setup, and tools.

Note the ﬁeld name used by the ﬁnish widget you are replacing (hereafter “myﬁnishﬁeld”), delete that widget, and replace it thusly:

 from dialog.choose_file import AutoChooseFinish
...
myfinishfield_widget = AutoChooseFinish(parent_widget, auto_name='auto_myfinishfield', combobox_name='myfinishfield')

Update secondary ﬁnish material other material creation code

pl = RectPlate()
if self.auto_myfinishfield:
	pl.SurfaceFinish = self.default_finish_id
else:
	pl.SurfaceFinish = self.myfinishfield

Update initialization, serialization, and convert

Classes that use StateAccessor or Metamorphoses for serialization (and sometimes classes that use other serialization schemes) have “versions” which are lists of attribute names with their default values. Create a new version where the ﬁnish ﬁelds have integer default values rather than string default values. Also, add any new “auto_myﬁnishﬁeld” attributes to the new version.

If your class provides an __init__() method, make sure that any ﬁnish ﬁelds are initialized to integers rather than strings and new auto ﬁelds are initialized to True. If your class uses StateAccessor or Metamorphoses for serialization, the __init__() method is typically generated for you using the current serialization version, and adding a new version will automatically update your __init__().

Since objects (members, components, setup, etc) in existing jobs were serialized with string ﬁnishes, they need to be converted to the most recent serialization version that uses integer ﬁnishes. If they are not converted properly, errors will occur when ﬁnish attributes are accessed.

Also, auto ﬁnish attributes (e.g., auto_myﬁnishﬁeld) should be set to False by convert so that ﬁnishes on existing objects are not changed unexpectedly.

The way a convert is implemented is dependent on the serialization scheme (StateAccessor, Metamorphoses, etc). For classes that do not use StateAccessor or Metamorphoses, converts are ad hoc. You must store a version number in your object and add code to update the version number and do other convert tasks in __setstate__(). For StateAccessor, you must create or update the __convert__() method on your class. For Metamorphoses, you must create or update the convert() method on your Metamorphoses-derived class.

Here is an example of a Metamorphoses convert method:

import job
...
@classmethod
def convert(cls, obj, old_version_id, new_version_id):
	updated_finishes_version_id = 3
	
	if old_version_id < updated_finishes_version_id:
	
		# Initially set the primary finish to the default job finish.
		obj.default_finish_id = Job().surface_finish
	
		# Find string finishes in setup finish table.
		finish_names = [finish.display_name.lower() for finish in 
				job.Job().surface_finishes()]
		finish_values = range(len(finish_names))
	
		for name, value in zip(finish_names, finish_values):
			if obj.old_primary_finish.lower() == name:
				obj.default_finish_id = value
				del obj.old_primary_finish
				break
	
		for name, value in zip(finish_names, finish_values):
			if obj.myfinishfield.lower() == name:
				obj.myfinishfield = value
				break
	
		# If the old finish field was not found in the setup finish table,
		# set it to the job default finish.
		if type(obj.myfinishfield) == str:
				obj.myfinishfield = job.Job().surface_finish
					
		# Don't change secondary finishes
		obj.myfinishfield_auto = False
		
	Here is an example of a StateAccessor convert method:
	
	def __convert__(self, old_version_id):
		updated_finishes_version_id = 3
	
		if old_version_id < updated_finishes_version_id:
		
		# Set the primary finish to the default job finish.
		self.default_finish_id = Job().surface_finish
		
		# Find string finishes in setup finish table.
		finish_names = [finish.display_name.lower() for finish in 
				job.Job().surface_finishes()]
		finish_values = range(len(finish_names))
		
		for name, value in zip(finish_names, finish_values):
			if self.old_primary_finish.lower() == name:
				self.default_finish_id = value
				del self.old_primary_finish
				break
		
		for name, value in zip(finish_names, finish_values):
			if self.myfinishfield.lower() == name:
				self.myfinishfield = value
				break
			
		# If the old finish field was not found in the setup finish table,
		# set it to the job default finish.
		if type(self.myfinishfield) == str:
			self.myfinishfield = job.Job().surface_finish
		
		# Don't change secondary finishes
		self.myfinishfield_auto = False

Setup

If there are custom setup classes for your plugin, remember to ﬁx gui and serialization issues for those in similar fashion.