Index: doc/Object.man =================================================================== diff -u -N -re1afe57982f40b4886fa025fb48e2f0cc833c026 -ra2fc04fd98cd2b3474742190887d1258a70ec164 --- doc/Object.man (.../Object.man) (revision e1afe57982f40b4886fa025fb48e2f0cc833c026) +++ doc/Object.man (.../Object.man) (revision a2fc04fd98cd2b3474742190887d1258a70ec164) @@ -5,6 +5,10 @@ [keywords NX] [keywords "mixin class"] +[vset SCOPE "object"] +[vset CMD "::obj"] +[vset SCOPEMODIFIER "object"] + [copyright {2014 Stefan Sobernig , Gustaf Neumann }] [titledesc {nx::Object API Reference}] @@ -315,7 +319,7 @@ Evaluates a special Tcl script for the scope of [arg obj] in the style of Tcl's [cmd eval]. There are, however, notable differences to the -standard [cmd eval]: In this script, the colon-prefix notation to +standard [cmd eval]: In this script, the colon-prefix notation is available to dispatch to methods and to access variables of [arg obj]. Script-local variables, which are thrown away once the evaluation of the script has completed, can be defined to store intermediate results. @@ -592,70 +596,8 @@ [list_end] -[list_begin commands] +[include property.man.inc] -[cmd_def property] - -[list_begin definitions] - -[call [arg obj] [const object] [cmd property] [opt "-accessor public|private|protected"] [opt "-configurable [arg trueFalse]"] [opt -incremental] [opt "-class [arg className]"] [opt -nocomplain] [arg spec] [opt [arg initBlock]]] - -Defines a per-object <<@gls property>>. For every property, a <<@gls -slotobject>> is created. A property also provides for a pair of -getter and setter methods, automatically. - -[list_begin options] - -[opt_def [option -accessor] "public|private|protected"] - -If set, a getter/setter method having the specified call-protection -level ([const public], [const private], or [const protected]) will be -defined automatically. -[para] -Type: an empty string (""), meaning no getter/setter method will be provided for the property -[para] -Default value: an empty string (""), meaning no getter/setter method will be provided for the property - -[list_end] - -[list_begin arguments] - - -[arg_def boolean -configurable in] -If set to [const true], the property can be configured through [cmd configure] and [cmd cget], respectively. If [const false], the property's value can be accessed and modified via the getter/setter method, if available (see [arg -accessor]), or by using the object variable managed by the property directly. -[para] -Default value: [const true] - -[arg_def switch -incremental in] ... - -[arg_def "" "-class [arg className]" in] Allows for specifying a slot class, from which the slot object realizing the property is instantiated. -[para] -Default value: [cmd ::nx::VariableSlot] - -[arg_def switch -nocomplain in] -If set, an existing object variable by the property name will not -be overwritten. Instead, an error exception is thrown. - -[arg_def "" spec in] - -The property specification can be a list of, at -least, one or two elements, maximum. The first element -specifies the property name, optionally followed by -parameter types after a colon delimiter. If provided, -the second element sets the default value for this -property. - -[arg_def "" initblock in] - -A script which is evaluated for the scope of the property's slot -object during its initialization. - -[list_end] - - - -[list_end] - [cmd_def alias] [list_begin definitions] @@ -735,7 +677,6 @@ [list_end] -[list_end] [section {Internally called Methods}] Index: doc/property.man.inc =================================================================== diff -u -N --- doc/property.man.inc (revision 0) +++ doc/property.man.inc (revision a2fc04fd98cd2b3474742190887d1258a70ec164) @@ -0,0 +1,93 @@ +[comment {-*- tcl -*- manpage fragment for property method}] + +[keywords property] +[keywords "slot object"] +[keywords "call protection"] +[keywords "public"] +[keywords "protected"] +[keywords "private"] +[keywords "switch"] +[keywords "value checker"] + +[cmd_def property] + +[list_begin definitions] + +[call [arg obj] [const [vset SCOPE]] [method property] [opt "-accessor public|private|protected"] [opt "-configurable [arg trueFalse]"] [opt -incremental] [opt "-class [arg className]"] [opt -nocomplain] [arg spec] [opt [arg initBlock]]] + +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 +methods: [term public], [term protected], or [term private]. + +[para] + +By setting [option -configurable] to [const true], 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] + +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]. + +[para] + +By default, the [term property] will ascertain that no (potentially) +pre-existing and equally named object variable will be overwritten +when defining the property. In case of a conflict, an error exception +is thrown: + +[example { +% Object create obj { set :x 1 } +::obj +% ::obj object property {x 2} +object ::obj has already an instance variable named 'x' +}] + +If the [term switch] [option -nocomplain] is on, this check is omitted (continuing the above example): + +[example { +% ::obj object property -nocomplain {x 2} +% ::obj eval {set :x} +2 +}] + +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] + +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]"]. + +[list_begin arguments] +[arg_def switch -incremental in] ... + + + + + +[list_end] + + + +[list_end]