Index: doc/property.man.inc =================================================================== diff -u -r904ff24ee84cffe6fa24e00dc75bfe6872d18cf6 -ra6fc3eb51bd42559b91e0bceb468b402a0abae83 --- doc/property.man.inc (.../property.man.inc) (revision 904ff24ee84cffe6fa24e00dc75bfe6872d18cf6) +++ doc/property.man.inc (.../property.man.inc) (revision a6fc3eb51bd42559b91e0bceb468b402a0abae83) @@ -15,54 +15,30 @@ 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 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 -[option -accessor] is set, the property can be accessed and modified via -the getter/setter methods. Alternatively, the object variable, which -is represented by the property, can always be accessed and modified -directly, e.g., using [method eval]. By default, [option -configurable] is -[const true]. - -[para] - -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] - -The [arg spec] provides the [term property] specification as a [cmd list] holding -at least one element or, maximum, two elements: [emph propertyName][opt ":[emph typeSpec]"] [opt [emph defaultValue]]. The [arg propertyName] sets +Defines a [term property] for the scope of the [vset SCOPE]. The [arg spec] provides +the [term property] specification as a [cmd list] holding at least one +element or, maximum, two elements: +[emph propertyName][opt ":[emph typeSpec]"] [opt [emph defaultValue]]. The [arg propertyName] sets the name of the property and the corresponding object variable(s). It is, optionally, equipped with a [emph typeSpec] following a colon delimiter which specifies a [term "value checker"] for the values which become assigned to the property. The second, optional element sets a [emph defaultValue] for this property. -[para] +[para] -The last argument [arg initBlock] accepts an optional Tcl script which is passed into -the initialization procedure (see [method configure]) of the [term property]'s [term "slot object"]. See -also [sectref description "[arg initBlock] for [method create] and [method new]"]. +If [option "-accessor"] is set, a property will provide for +a pair of getter and setter methods: +[list_begin definitions] +[def "[arg obj] [arg propertyName] [method set] [arg value]"] +Sets the [term property] [arg propertyName] to [arg value]. +[def "[arg obj] [arg propertyName] [method get]"] +Returns the current value of [term property] [arg propertyName]. +[list_end] +The option value passed along [option "-accessor"] sets the level of +[term "call protection"] for the generated getter and setter methods: [term public], +[term protected], or [term private]. By default, no getter and setter +methods are created. [para] @@ -71,10 +47,10 @@ 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 +list. A [term multiplicity] of [const 1..*] 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: +additional setter methods become available: [list_begin definitions] [def "[arg obj] [arg propertyName] [method add] [arg element] [opt [arg index]]"] @@ -83,10 +59,38 @@ 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: + +[para] + +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], no configuration option +will become available via [method cget] and [method configure]. +[para] +If neither [option -accessor] nor [option -configurable] are +requested, the value managed by the [term property] will have to be accessed +and modified directly. If the property manages an object variable, its +value will be readable and writable using [cmd set] and [method eval]. + +[para] + +A [term property] becomes implemented by a [term "slot object"] 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] +Assuming default settings, every [term property] is realized by a +[term "slot object"]. +[para] +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] + +The last argument [arg initBlock] accepts an optional Tcl script which is passed into +the initialization procedure (see [method configure]) of the [term property]'s [term "slot object"]. See +also [sectref description "[arg initBlock] for [method create] and [method new]"].