wiki/racecommittee-app.md
... ...
@@ -29,11 +29,27 @@ Kuruh, Kuruh,...
29 29
30 30
## RaceState
31 31
32
-intro-text zu racestate, was ist das, wo kann ich es nutzen
32
+The _RaceState_ (and its read-only variation _ReadonlyRaceState_) should be the only way you query and change the state of race (i.e. the state of a _RaceLog_). The _RaceState_ analyzes the content of its underlying _RaceLog_ for you and provides a clear interface to several aspects of your race, including its start time, its finished time, the selected course design, etc.
33
+
34
+A _RaceState_ always has a _RacingProcedure_ attached to it. Whenever racing procedure type is set by a call to _RaceState#setRacingProcedureType# the _RacingProcedure_ object will be recreated (even when the type was not changed).
35
+
36
+See the code documentation for further details.
33 37
34 38
### Adding a new user interface
35 39
36
-text zu den listener
40
+When writing a user interface for the state of a _RaceLog_ / race you should use the _RaceState_ interface. Consult the code documentation on how to create a _RaceState_ (or _ReadonlyRaceState_).
41
+
42
+Since your UI should get all updates, you should set a _RaceStateEventScheduler_ on the _RaceState_. This enables automatic events to be triggered by the _RacingProcedure_ (e.g. when the active flags of the starting sequence have changed). See below on how to implement a _RaceStateEventScheduler_.
43
+
44
+Using a _RaceState_ for your UI you want to leverage the callback mechanisms rather than re-creating one-shot _RaceState_s and querying their status over and over again. Register your _RaceStateChangedListener_ on the _RaceState_ and your _RacingProcedureChangedListener_ on its _RacingProcedure_. You should re-register your _RacingProcedure_ listener whenever _RaceStateChangedListener#onRacingProcedureChanged_ is called. Keep in mind that depending on the type of the _RacingProcedure_ there might be additional callback methods available (e.g. for a RRS26 race there is a _RRS26ChangedListener_).
45
+
46
+The last step is to implement a _RacingProcedurePrerequisite.Resolver_ to support setting a new start time in your UI. See below for a walk-through.
47
+
48
+#### Implementing a RaceStateEventScheduler
49
+
50
+A _RaceStateEventScheduler_ is in charge of calling _RaceState#processStateEvent_ whenever a _RaceStateEvent_ passed to _RaceStateEventScheduler#scheduleStateEvents_ is due.
51
+
52
+Each _RateStateEvent_ carries a _TimePoint_. You should set a timer and call _RaceState#processStateEvent_ passing the _RaceStateEvent_ when the timer fires. Keep in mind that _RaceState_ won't do any threading/locking for you. Therefore be careful when calling _RaceState#processStateEvent_ from a background thread, because your UI listener (see above) might be called in this context!
37 53
38 54
#### Implementing a RacingProcedurePrerequisite.Resolver
39 55
... ...
@@ -53,7 +69,7 @@ This chain continues until the _RacingProcedure_ detects that there are no furth
53 69
54 70
### Adding a new racing procedure
55 71
56
-configuration!
72
+Ja.
57 73
58 74
## Configuration
59 75