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