basis/models/models-docs.factor

   1 USING: help.syntax help.markup kernel math classes classes.tuple
   2 calendar ;
   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     { $list
   8         { { $snippet "value" } " - the value of the model. Use " { $link set-model } " to change the value." }
   9         { { $snippet "connections" } " - a sequence of objects implementing the " { $link model-changed } " generic word, to be notified when the model's value changes." }
  10         { { $snippet "dependencies" } " - a sequence of models which should have this model added to their sequence of connections when activated." }
  11         { { $snippet "ref" } " - a reference count tracking the number of models which depend on this one." }
  12     }
  13 "Other classes may delegate to " { $link model } "."
  14 } ;
  15
  16 HELP: <model>
  17 { $values { "value" object } { "model" "a new " { $link model } } }
  18 { $description "Creates a new model with an initial value." } ;
  19
  20 HELP: add-dependency
  21 { $values { "dep" model } { "model" model } }
  22 { $description "Registers a dependency. When " { $snippet "model" } " is activated, it will be added to " { $snippet "dep" } "'s connections and notified when " { $snippet "dep" } " changes." }
  23 { $notes "This word should not be called directly unless you are implementing your own model class." } ;
  24
  25 { add-dependency remove-dependency activate-model deactivate-model } related-words
  26
  27 HELP: remove-dependency
  28 { $values { "dep" model } { "model" model } }
  29 { $description "Unregisters a dependency." }
  30 { $notes "This word should not be called directly unless you are implementing your own model class." } ;
  31
  32 HELP: model-activated
  33 { $values { "model" model } }
  34 { $contract "Called after a model has been activated." } ;
  35
  36 { model-activated activate-model deactivate-model } related-words
  37
  38 HELP: activate-model
  39 { $values { "model" model } }
  40 { $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 } "." }
  41 { $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." } ;
  42
  43 HELP: deactivate-model
  44 { $values { "model" model } }
  45 { $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 } "." }
  46 { $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." } ;
  47
  48 HELP: model-changed
  49 { $values { "model" model } { "observer" object } }
  50 { $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 } "." } ;
  51
  52 { add-connection remove-connection model-changed } related-words
  53
  54 HELP: add-connection
  55 { $values { "observer" object } { "model" model } }
  56 { $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." } ;
  57
  58 HELP: remove-connection
  59 { $values { "observer" object } { "model" model } }
  60 { $contract "Unregisters an object no longer interested in being notified of changes to the model's value." } ;
  61
  62 HELP: set-model
  63 { $values { "value" object } { "model" model } }
  64 { $description "Changes the value of a model and calls " { $link model-changed } " on all observers registered with " { $link add-connection } "." } ;
  65
  66 { set-model change-model (change-model) } related-words
  67
  68 HELP: change-model
  69 { $values { "model" model } { "quot" "a quotation with stack effect " { $snippet "( obj -- newobj )" } } }
  70 { $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 } "." } ;
  71
  72 HELP: (change-model)
  73 { $values { "model" model } { "quot" "a quotation with stack effect " { $snippet "( obj -- newobj )" } } }
  74 { $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 } "." }
  75 { $notes "There are very few reasons for user code to call this word. Instead, call " { $link change-model } ", which notifies observers." } ;
  76
  77 HELP: range-value
  78 { $values { "model" model } { "value" object } }
  79 { $contract "Outputs the current value of a range model." } ;
  80
  81 HELP: range-page-value
  82 { $values { "model" model } { "value" object } }
  83 { $contract "Outputs the page size of a range model." } ;
  84
  85 HELP: range-min-value
  86 { $values { "model" model } { "value" object } }
  87 { $contract "Outputs the minimum value of a range model." } ;
  88
  89 HELP: range-max-value
  90 { $values { "model" model } { "value" object } }
  91 { $contract "Outputs the maximum value of a range model." } ;
  92
  93 HELP: range-max-value*
  94 { $values { "model" model } { "value" object } }
  95 { $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." } ;
  96
  97 HELP: set-range-value
  98 { $values { "value" object } { "model" model } }
  99 { $description "Sets the current value of a range model." }
 100 { $side-effects "model" } ;
 101
 102 HELP: set-range-page-value
 103 { $values { "value" object } { "model" model } }
 104 { $description "Sets the page size of a range model." }
 105 { $side-effects "model" } ;
 106
 107 HELP: set-range-min-value
 108 { $values { "value" object } { "model" model } }
 109 { $description "Sets the minimum value of a range model." }
 110 { $side-effects "model" } ;
 111
 112 HELP: set-range-max-value
 113 { $values { "value" object } { "model" model } }
 114 { $description "Sets the maximum value of a range model." }
 115 { $side-effects "model" } ;
 116
 117 ARTICLE: "models" "Models"
 118 "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."
 119 $nl
 120 "The class of models:"
 121 { $subsection model }
 122 "Creating models:"
 123 { $subsection <model> }
 124 "Adding and removing connections:"
 125 { $subsection add-connection }
 126 { $subsection remove-connection }
 127 "Generic word called on model connections when the model value changes:"
 128 { $subsection model-changed }
 129 "When using models which are not associated with controls (or when unit testing controls), you must activate and deactivate models manually:"
 130 { $subsection activate-model }
 131 { $subsection deactivate-model }
 132 { $subsection "models-impl" }
 133 { $subsection "models-filter" }
 134 { $subsection "models-compose" }
 135 { $subsection "models-history" }
 136 { $subsection "models-range" }
 137 { $subsection "models-delay" } ;
 138
 139 ARTICLE: "models-impl" "Implementing models"
 140 "New types of models can be defined, for example see " { $vocab-link "models.filter" } "."
 141 $nl
 142 "Models can execute hooks when activated:"
 143 { $subsection model-activated }
 144 "Models can override requests to change their value, for example to perform validation:"
 145 { $subsection set-model } ;
 146
 147 ABOUT: "models"