basis/models/models-docs.factor

   1 USING: help.syntax help.markup kernel math classes classes.tuple
   2 calendar sequences growable ;
   3 IN: models
   4
   5 HELP: model
   6 { $class-description "A mutable cell holding a single value. When the value is changed, a sequence of connected objects are notified. Models have the following slots:"
   7     { $slots
   8         { "value" "the value of the model. Use " { $link set-model } " to change the value." }
   9         { "connections" "a sequence of objects implementing the " { $link model-changed } " generic word, to be notified when the model's value changes." }
  10         { "dependencies" "a sequence of models which should have this model added to their sequence of connections when activated." }
  11         { "ref" "a reference count tracking the number of models which depend on this one." }
  12         { "locked?" "a slot set by " { $link with-locked-model } " to ensure that the model doesn't get changed recursively" }
  13     }
  14 "Other classes may inherit from " { $link model } "."
  15 } ;
  16
  17 HELP: <model>
  18 { $values { "value" object } { "model" "a new " { $link model } } }
  19 { $description "Creates a new model with an initial value." } ;
  20
  21 HELP: add-dependency
  22 { $values { "dep" model } { "model" model } }
  23 { $description "Registers a dependency. When " { $snippet "model" } " is activated, it will be added to " { $snippet "dep" } "'s connections and notified when " { $snippet "dep" } " changes." }
  24 { $notes "This word should not be called directly unless you are implementing your own model class." } ;
  25
  26 { add-dependency remove-dependency activate-model deactivate-model } related-words
  27
  28 HELP: remove-dependency
  29 { $values { "dep" model } { "model" model } }
  30 { $description "Unregisters a dependency." }
  31 { $notes "This word should not be called directly unless you are implementing your own model class." } ;
  32
  33 HELP: model-activated
  34 { $values { "model" model } }
  35 { $contract "Called after a model has been activated." } ;
  36
  37 { model-activated activate-model deactivate-model } related-words
  38
  39 HELP: activate-model
  40 { $values { "model" model } }
  41 { $description "Increments the reference count of the model. If it was previously zero, this model is added as a connection to all models registered as dependencies by " { $link add-dependency } "." }
  42 { $warning "Calls to " { $link activate-model } " and " { $link deactivate-model } " should be balanced to keep the reference counting consistent, otherwise " { $link model-changed } " might be called at the wrong time or not at all." } ;
  43
  44 HELP: deactivate-model
  45 { $values { "model" model } }
  46 { $description "Decrements the reference count of the model. If it reaches zero, this model is removed as a connection from all models registered as dependencies by " { $link add-dependency } "." }
  47 { $warning "Calls to " { $link activate-model } " and " { $link deactivate-model } " should be balanced to keep the reference counting consistent, otherwise " { $link model-changed } " might be called at the wrong time or not at all." } ;
  48
  49 HELP: model-changed
  50 { $values { "model" model } { "observer" object } }
  51 { $contract "Called to notify observers of a model that the model value has changed as a result of a call to " { $link set-model } ". Observers can be registered with " { $link add-connection } "." } ;
  52
  53 { add-connection remove-connection model-changed } related-words
  54
  55 HELP: add-connection
  56 { $values { "observer" object } { "model" model } }
  57 { $contract "Registers an object interested in being notified of changes to the model's value. When the value is changed as a result of a call to " { $link set-model } ", the " { $link model-changed } " word is called on the observer." } ;
  58
  59 HELP: remove-connection
  60 { $values { "observer" object } { "model" model } }
  61 { $contract "Unregisters an object no longer interested in being notified of changes to the model's value." } ;
  62
  63 HELP: update-model
  64 { $values { "model" model } }
  65 { $description "Notifies the model that its " { $slot "value" } " slot has been updated by " { $link set-model } "." } ;
  66
  67 HELP: set-model
  68 { $values { "value" object } { "model" model } }
  69 { $description "Changes the value of a model, calls " { $link update-model } " to notify it, then calls " { $link model-changed } " on all observers registered with " { $link add-connection } "." } ;
  70
  71 HELP: ?set-model
  72 { $values { "value" object } { "model" model } }
  73 { $description "Similar to " { $link set-model } ", but only sets the value if the new value is different." } ;
  74
  75 { set-model ?set-model change-model change-model* (change-model) push-model pop-model } related-words
  76
  77 HELP: change-model
  78 { $values { "model" model } { "quot" { $quotation ( ..a obj -- ..b newobj ) } } }
  79 { $description "Applies the quotation to the current value of the model to yield a new value, then changes the value of the model to the new value, and calls " { $link model-changed } " on all observers registered with " { $link add-connection } "." } ;
  80
  81 HELP: change-model*
  82 { $values { "model" model } { "quot" { $quotation ( ..a obj -- ..b ) } } }
  83 { $description "Applies the quotation to the current value of the model and calls " { $link model-changed } " on all observers registered with " { $link add-connection } " without actually changing the value of the model. This is useful for notifying observers of operations that mutate a value, as in " { $link push-model } " and " { $link pop-model } "." } ;
  84
  85 HELP: (change-model)
  86 { $values { "model" model } { "quot" { $quotation ( ..a obj -- ..b newobj ) } } }
  87 { $description "Applies the quotation to the current value of the model to yield a new value, then changes the value of the model to the new value without notifying any observers registered with " { $link add-connection } "." }
  88 { $notes "There are very few reasons for user code to call this word. Instead, call " { $link change-model } ", which notifies observers." } ;
  89
  90 HELP: push-model
  91 { $values { "value" object } { "model" model } }
  92 { $description { $link push } "es " { $snippet "value" } " onto the " { $link growable } " sequence stored as the value of " { $snippet "model" } " and calls " { $link model-changed } " on all observers registered for the model with " { $link add-connection } "." } ;
  93
  94 HELP: pop-model
  95 { $values { "model" model } { "value" object } }
  96 { $description { $link pop } "s the topmost " { $snippet "value" } " off of the " { $link growable } " sequence stored as the value of " { $snippet "model" } " and calls " { $link model-changed } " on all observers registered for the model with " { $link add-connection } "." } ;
  97
  98 HELP: range-value
  99 { $values { "model" model } { "value" object } }
 100 { $contract "Outputs the current value of a range model." } ;
 101
 102 HELP: range-page-value
 103 { $values { "model" model } { "value" object } }
 104 { $contract "Outputs the page size of a range model." } ;
 105
 106 HELP: range-min-value
 107 { $values { "model" model } { "value" object } }
 108 { $contract "Outputs the minimum value of a range model." } ;
 109
 110 HELP: range-max-value
 111 { $values { "model" model } { "value" object } }
 112 { $contract "Outputs the maximum value of a range model." } ;
 113
 114 HELP: range-max-value*
 115 { $values { "model" model } { "value" object } }
 116 { $contract "Outputs the slider position for a range model. Since the bottom of the slider cannot exceed the maximum value, this is equal to the maximum value minus the page size." } ;
 117
 118 HELP: set-range-value
 119 { $values { "value" object } { "model" model } }
 120 { $description "Sets the current value of a range model." }
 121 { $side-effects "model" } ;
 122
 123 HELP: set-range-page-value
 124 { $values { "value" object } { "model" model } }
 125 { $description "Sets the page size of a range model." }
 126 { $side-effects "model" } ;
 127
 128 HELP: set-range-min-value
 129 { $values { "value" object } { "model" model } }
 130 { $description "Sets the minimum value of a range model." }
 131 { $side-effects "model" } ;
 132
 133 HELP: set-range-max-value
 134 { $values { "value" object } { "model" model } }
 135 { $description "Sets the maximum value of a range model." }
 136 { $side-effects "model" } ;
 137
 138 ARTICLE: "models" "Models"
 139 "The " { $vocab-link "models" } " vocabulary provides basic support for dataflow programming. A model is an observable value. Changing a model's value notifies other objects which depend on the model automatically, and models may depend on each other's values."
 140 $nl
 141 "The class of models:"
 142 { $subsections model }
 143 "Creating models:"
 144 { $subsections <model> }
 145 "Adding and removing connections:"
 146 { $subsections
 147     add-connection
 148     remove-connection
 149 }
 150 "Generic word called on model connections when the model value changes:"
 151 { $subsections model-changed }
 152 "When using models which are not associated with controls (or when unit testing controls), you must activate and deactivate models manually:"
 153 { $subsections
 154     activate-model
 155     deactivate-model
 156     "models-impl"
 157     "models.arrow"
 158     "models.product"
 159     "models.range"
 160     "models.delay"
 161 } ;
 162
 163 ARTICLE: "models-impl" "Implementing models"
 164 "New types of models can be defined, for example see " { $vocab-link "models.arrow" } "."
 165 $nl
 166 "Models can execute hooks when activated:"
 167 { $subsections model-activated }
 168 "To avoid recursive updating and do proper notifications, you should set the model values via:"
 169 { $subsections set-model }
 170 "Models are notified when their values are changed:"
 171 { $subsections update-model } ;
 172
 173 ABOUT: "models"