001package votorola.s.gwt.stage.vote; // Copyright 2012, Michael Allan.  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Votorola Software"), to deal in the Votorola Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicence, and/or sell copies of the Votorola Software, and to permit persons to whom the Votorola Software is furnished to do so, subject to the following conditions: The preceding copyright notice and this permission notice shall be included in all copies or substantial portions of the Votorola Software. THE VOTOROLA SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE VOTOROLA SOFTWARE OR THE USE OR OTHER DEALINGS IN THE VOTOROLA SOFTWARE.
002
003import com.google.gwt.core.client.JavaScriptObject;
004import votorola.a.count.XCastRelation;
005import votorola.g.lang.Typifier;
006import votorola.g.web.gwt.JavaScriptObjectX;
007
008
009/** A difference that is lightable by a DifferenceLight.  It corresponds to the difference
010  * (perhaps empty) between a position represented in the vote track and that of the
011  * {@linkplain VoteTrack#anchor() anchoring author}.  Difference lighting in general is
012  * mediated by style classes set on the #{@linkplain votorola.s.gwt.stage.StageV
013  * StageV-top} element and the document body.  The <code>#StageV-top</code> element gets
014  * classes for all differences (up to {@linkplain DifferenceLight#MAX_DIFFS MAX_DIFFS})
015  * that have representation in the track, each class being named after the cast relation
016  * of the {@linkplain votorola.s.gwt.stage.light.PositionSensor#personName() other
017  * author} in regard to the {@linkplain VoteTrack#anchor() anchoring author}.  At most
018  * one of these differences is spotlit at a given time, the spotlight being implemented
019  * by two or three classes set on document body as detailed in the following table.
020  *
021  * <table class='definition' style='margin:1em; vertical-align:middle'>
022  *     <tr>
023  *         <th>Relation</th>
024  *         <th>{@linkplain #stageRelClass() stageRelClass}</th>
025  *         <th>{@linkplain #bodyRelClass() bodyRelClass}</th>
026  *         <th>{@linkplain #bodySecClass() bodySecClass}</th>
027  *         <th>Ordinal</th>
028  *         <th>{@linkplain #bodyOrdClass() bodyOrdClass}</th>
029  *         </tr>
030  *     <tr><td>{@linkplain XCastRelation#VOTER Voter}</td>
031  *
032  *                    <td>v<var>DS</var></td>
033  *
034  *         <td>voLiDi-rel-v</td>
035  *
036  *         <td>voLiDi-<var>DS</var></td>
037  *
038  *         <td>a</td>
039  *
040  *         <td>voLiDi-ord-a</td>
041  *
042  *         </tr>
043  *     <tr><td rowspan='2' style='vertical-align:middle'>
044  *         {@linkplain XCastRelation#CO_VOTER Co-voter}</td>
045  *
046  *                    <td rowspan='2' style='vertical-align:middle'>o<var>DS</var></td>
047  *
048  *         <td rowspan='2' style='vertical-align:middle'>voLiDi-rel-o</td>
049  *
050  *         <td rowspan='2'>voLiDi-<var>DS</var></td>
051  *
052  *         <td>a</td>
053  *
054  *         <td>voLiDi-ord-a</td>
055  *
056  *         </tr>
057  *     <tr><td>b</td>
058  *
059  *         <td>voLiDi-ord-b</td>
060  *
061  *         </tr>
062  *     <tr><td rowspan='2' style='vertical-align:middle'>
063  *         <a href='../../../../../../../d/theory.xht#cycle' target='_top'>Tight cycler</a></td>
064  *
065  *                    <td rowspan='2' style='vertical-align:middle'>y</td>
066  *
067  *         <td rowspan='2' style='vertical-align:middle'>voLiDi-rel-y</td>
068  *
069  *         <td rowspan='2'><em>none</em></td>
070  *
071  *         <td>a</td>
072  *
073  *         <td>voLiDi-ord-a</td>
074  *
075  *         </tr>
076  *     <tr><td>b</td>
077  *
078  *         <td>voLiDi-ord-b</td>
079  *
080  *         </tr>
081  *     <tr><td rowspan='2' style='vertical-align:middle'>
082  *         {@linkplain XCastRelation#CO_BASE Base co-candidate}</td>
083  *
084  *                    <td rowspan='2' style='vertical-align:middle'>o<var>DS</var></td>
085  *
086  *         <td rowspan='2' style='vertical-align:middle'>voLiDi-rel-o</td>
087  *
088  *         <td rowspan='2'>voLiDi-<var>DS</var></td>
089  *
090  *         <td>a</td>
091  *
092  *         <td>voLiDi-ord-a</td>
093  *
094  *         </tr>
095  *     <tr><td>b</td>
096  *
097  *         <td>voLiDi-ord-b</td>
098  *
099  *         </tr>
100  *     <tr><td>{@linkplain XCastRelation#CANDIDATE Candidate}</td>
101  *
102  *                    <td>c</td>
103  *
104  *         <td>voLiDi-rel-c</td>
105  *
106  *         <td><em>none</em></td>
107  *
108  *         <td>b</td>
109  *
110  *         <td>voLiDi-ord-b</td>
111  *
112  *         </tr>
113  *     </table>
114  *
115  * The variable <var>DS</var> is the other author's dart sector, from 0 to {@value
116  * votorola.a.count.CountNode#DART_SECTOR_MAX}.
117  */
118public interface LightableDifference
119{
120
121
122    /** The base {@value} for all values of {@linkplain #actorLinkVariant()
123      * actorLinkVariant}(), which is itself a valid default variant.
124      */
125    public static final String ACTOR_LINK_VARIANT_BASE = "VoteTrack-spotlit";
126
127
128
129    /** The common prefix {@value} for all values of the {@linkplain #bodyRelClass()
130      * bodyRelClass}().
131      */
132    public static final String BODY_REL_PREFIX = "voLiDi-rel-";
133
134
135
136    /** The common prefix {@value} for all values of the {@linkplain #bodyRelClass()
137      * bodyRelClass}().
138      */
139    public static final String BODY_SEC_PREFIX = "voLiDi-";
140
141
142
143    /** The style symbol 'c' for the candidate cast relation.
144      */
145    public static final char REL_CANDIDATE = XCastRelation.CANDIDATE.symbol();
146
147
148
149    /** The style symbol 'o' for the co-voter and base co-candidate cast relations.
150      */
151    public static final char REL_CO = XCastRelation.CO_VOTER.symbol();
152
153
154
155    /** The style symbol 'y' for the base co-candidate cast relation when there is a tight
156      * cycle between the anchor and the other person.
157      */
158    public static final char REL_TIGHT_CYCLE = 'y';
159
160
161
162    /** The style symbol 'u' for the unknown cast relation.
163      */
164    public static final char REL_UNKNOWN = 'u';
165
166
167
168    /** The style symbol 'v' for the voter cast relation.
169      */
170    public static final char REL_VOTER = XCastRelation.VOTER.symbol();
171
172
173
174   // - L i g h t a b l e - D i f f e r e n c e ------------------------------------------
175
176
177    /** The style variant for actor dependent links in the {@linkplain
178      * votorola.s.gwt.stage.link.LinkTrackV#getActorLinkVariant() link track}.
179      */
180    public String actorLinkVariant();
181
182
183
184    /** The name of the ordinal style class to set on the document body when this
185      * lightable difference is lit.
186      *
187      *     @see <a href='../../../../a/diff/DiffKey.html#ord'>Normal order</a>
188      */
189    public String bodyOrdClass(); // used by TYPIFIER
190
191
192
193    /** The name of the {@linkplain XCastRelation cast-relational} style class to set on
194      * the document body when this lightable difference is lit.
195      */
196    public String bodyRelClass();
197
198
199
200    /** The name of the {@linkplain votorola.a.count.CountNode#dartSector() dart-sectoral}
201      * style class to set on the document body when this lightable difference is lit, or
202      * null of there is none.
203      */
204    public String bodySecClass();
205
206
207
208    /** The name of the {@linkplain votorola.s.gwt.stage.light.PositionSensor#personName()
209      * other author}, as opposed to the {@linkplain VoteTrack#anchor() anchoring author}.
210      */
211    public String personName();
212
213
214
215    /** The name of the poll.
216      */
217    public String pollName(); // used by TYPIFIER
218
219
220
221    /** The name of the {@linkplain XCastRelation cast-relational} style class to set on
222      * the #{@linkplain votorola.s.gwt.stage.StageV StageV-top} element, indicating the
223      * existence of this lightable difference.
224      */
225    public String stageRelClass();
226
227
228
229    /** A typifier for LightableDifference.
230      */
231    public static final Typifier TYPIFIER = new Typifier()
232    {
233        public boolean isInstance( final Object o )
234        {
235            return o instanceof JavaScriptObject?
236              JavaScriptObjectX._isDuckType((JavaScriptObject)o, "bodyOrdClass", "pollName"):
237              o instanceof LightableDifference;
238        }
239    };
240
241
242
243   // ====================================================================================
244
245
246    /** A routine that runs in the context of a lightable difference.
247      */
248    public interface Runner<D extends LightableDifference>
249    {
250
251       // - L i g h t a b l e - D i f f e r e n c e . R u n n e r ------------------------
252
253
254        /** Runs this routine in the context of the specified difference.
255          */
256        public void run( final D diff );
257
258    }
259
260
261
262}
263
264