Index: doc/property.man.inc =================================================================== diff -u -r5eaa3c085b09fc995f311d18487b3411931ab25a -r904ff24ee84cffe6fa24e00dc75bfe6872d18cf6 --- doc/property.man.inc (.../property.man.inc) (revision 5eaa3c085b09fc995f311d18487b3411931ab25a) +++ doc/property.man.inc (.../property.man.inc) (revision 904ff24ee84cffe6fa24e00dc75bfe6872d18cf6) @@ -10,19 +10,28 @@ [keywords "value checker"] [keywords "multiplicity"] -Defines a [term property] for the scope of the [vset SCOPE]. For every -property, a [term "slot object"] is created to manage the -corresponding object variable. -[para] -If [option "-accessor"] is set, a property will provide for a pair of getter -and setter methods, automatically. By default, no getter and setter -methods are created. The option value passed along [option "-accessor"] -sets the level of [term "call protection"] for the getter and setter +[comment { + At the time of writing, the only material difference between + property and variable is a different -configurable default. +}] + +Defines a [term property] for the scope of the [vset SCOPE]. By +default, a property defines a configuration option for the [vset SCOPE] to +be accessed and modified using [method cget] and [method configure], +respectively (see also [option -configurable] below). Therefore, +assuming default settings, every [term property] is managed by a [term "slot object"]. + +[para] + +If [option "-accessor"] is set explicitly, a property will provide for a pair of +getter and setter methods, automatically. By default, no getter and +setter methods are created. The option value passed along [option "-accessor"] sets +the level of [term "call protection"] for the getter and setter methods: [term public], [term protected], or [term private]. [para] -By setting [option -configurable] to [const true], the property can be +By setting [option -configurable] to [const true] (the default), the property can be accessed and modified through [method cget] and [method configure], respectively. If [const false], the interface based on [method cget] and [method configure] will not become available. In this case, and provided that @@ -34,9 +43,10 @@ [para] -A custom class for the slot object implementing the property, from -which this slot object is to be instantiated, can be provided using -[option -class]. The default value is [cmd ::nx::VariableSlot]. +Provided a [term "slot object"] managing the [term property] is to be +created, a custom class [arg className] from which this [term "slot object"] is +to be instantiated can be set using [option -class]. The +default value is [cmd ::nx::VariableSlot]. [para] @@ -59,15 +69,24 @@ Turning on the [term switch] [option -incremental] provides a refined setter interface to the value managed by the [term property]. First, setting [option -incremental] implies requesting [option -accessor] -(set to [emph public] by default, if not specified explicitly). Second, -the managed value will be considered a valid Tcl list. A [term multiplicity] of -[const 0..*] is set by default, if not specified explicitly as part of -[arg spec] (see above). Third, to manage this list value -[emph incrementally], two additional operations become available: +(set to [emph public] by default, if not specified +explicitly). Second, the managed value will be considered a valid Tcl +list. A [term multiplicity] of [const 0..*] is set by default, if not +specified explicitly as part of [arg spec] (see above). Third, to +manage this list value element-wise ([emph incrementally]), two +additional operations become available: [list_begin definitions] [def "[arg obj] [arg propertyName] [method add] [arg element] [opt [arg index]]"] Adding [arg element] to the managed list value, at the list position given by [arg index] (by default: 0). [def "[arg obj] [arg propertyName] [method delete] [arg element] [opt [arg index]]"] Removing the first occurrence of [arg value] from the managed list value, starting from list position [arg index] (by default: [const end]). [list_end] + +In summary, a [term "slot object"] for the [term property] is provided under any of the following conditions: +[list_begin itemized] +[item] [option -configurable] equals [const true] (by default). +[item] [option -accessor] is one of [const public], [const protected], or [const private]. +[item] [option -incremental] is turned on. +[item] [arg initBlock] is not an empty string. +[list_end]