001: /*
002: * GWT-Ext Widget Library
003: * Copyright(c) 2007-2008, GWT-Ext.
004: * licensing@gwt-ext.com
005: *
006: * http://www.gwt-ext.com/license
007: */
008: package com.gwtext.client.core;
009:
010: //API returns Fx and not Element because adding not Fx methosd to the chain can result in
011:
012: //unexpected side effects See http://extjs.com/forum/showthread.php?t=2647
013: /**
014: * Interface that provide basic animation and visual effects support.
015: * <br/>
016: * <br/>
017: * It is important to note that although the Fx methods and many non-Fx Element methods support
018: * "method chaining" in that they return the Element object itself as the method return value, it is
019: * not always possible to mix the two in a single method chain. The Fx methods use an internal effects
020: * queue so that each effect can be properly timed and sequenced. Non-Fx methods, on the other hand, have
021: * no such internal queueing and will always execute immediately. For this reason, while it may be possible
022: * to mix certain Fx and non-Fx method calls in a single chain, it may not always provide the expected
023: * results and should be done with care.
024: * <br/><br/>
025: */
026: public interface Fx {
027:
028: //Ext Fx API's
029:
030: /**
031: * Fade an element in (from transparent to opaque).
032: * <p/>
033: * <pre>
034: * // default: fade in from opacity 0 to 100%
035: * el.fadeIn();
036: * </pre>
037: *
038: * @return this
039: */
040: Fx fadeIn();
041:
042: /**
043: * Fade an element in (from transparent to opaque). The ending opacity can be specified using the "endOpacity" config option.
044: * <p/>
045: * <pre>
046: * // fade in from opacity 0 to 75% over 2 seconds
047: * el.fadeIn(new FxConfig() {
048: * {
049: * setEndOpacity(0.75);
050: * setDuration(2);
051: * });
052: * </pre>
053: *
054: * @param config the Fx config
055: * @return this
056: */
057: Fx fadeIn(FxConfig config);
058:
059: /**
060: * Fade an element out (from opaque to transparent) from the element's current opacity to 0.
061: *
062: * @return this
063: */
064: Fx fadeOut();
065:
066: /**
067: * Fade an element out (from opaque to transparent). The ending opacity can be specified using the "endOpacity" config option.
068: * <p/>
069: * <p/>
070: * <pre>
071: * // fade out from the element's current opacity to 25% over 2 seconds
072: * el.fadeOut(new FxConfig() {
073: * {
074: * setEndOpacity(0.25);
075: * setDuration(2);
076: * });
077: * </pre>
078: *
079: * @param config the Fx config
080: * @return this
081: */
082: Fx fadeOut(FxConfig config);
083:
084: /**
085: * Shows a ripple of exploding, attenuating borders to draw attention to an Element.
086: *
087: * @return this
088: */
089: Fx frame();
090:
091: /**
092: * Shows a ripple of exploding, attenuating borders to draw attention to an Element.
093: * <p/>
094: * <p/>
095: * <pre>
096: * // 3 red ripples lasting 3 seconds total
097: * el.frame("ff0000", 3, new FxConfig() {
098: * {
099: * setDurtion(3);
100: * }));
101: * </pre>
102: *
103: * @param color he color of the border. Should be a 6 char hex color without the leading # (defaults to light blue: 'C3DAF9').
104: * @param count The number of ripples to display (defaults to 1)
105: * @param config the Fx config
106: * @return this
107: */
108: Fx frame(String color, int count, FxConfig config);
109:
110: /**
111: * Slides the element while fading it out of view.
112: *
113: * @return this
114: */
115: Fx ghost();
116:
117: /**
118: * Slides the element while fading it out of view.
119: *
120: * @param anchorPosition the anchor position
121: * @param config the Fx config
122: * @return true
123: */
124: Fx ghost(String anchorPosition, FxConfig config);
125:
126: /**
127: * Returns true if the element has any effects actively running or queued, else returns false.
128: *
129: * @return True if element has active effects, else false
130: */
131: boolean hasActiveFx();
132:
133: /**
134: * Returns true if the element is currently blocking so that no other effect can be queued until this effect is finished,
135: * else returns false if blocking is not set. This is commonly used to ensure that an effect initiated by a user action runs to completion prior to the same effect being restarted (e.g., firing only one effect even if the user clicks several times).
136: *
137: * @return True if blocking, else false
138: */
139: boolean hasFxBlock();
140:
141: /**
142: * Highlights the Element by setting a color (applies to the background-color by default, but can be changed using the "attr"
143: * config option) and then fading back to the original color.
144: *
145: * @return this
146: */
147: Fx highlight();
148:
149: /**
150: * Highlights the Element by setting a color (applies to the background-color by default, but can be changed using the "attr" config option) and then fading back to the original color.
151: *
152: * @param color The highlight color. Should be a 6 char hex color without the leading # (defaults to yellow: 'ffff9c')
153: * @param config the Fx config
154: * @return this
155: */
156: Fx highlight(String color, FxConfig config);
157:
158: /**
159: * Highlights the Element by setting a color (applies to the background-color by default, but can be changed using the "attr" config option) and then fading back to the original color.
160: * If no original color is available, you should provide the "endColor" config option which will be cleared after the animation.
161: * <p/>
162: * <p/>
163: * <pre>
164: * // highlight foreground text to blue for 2 seconds
165: * el.highlight("0000ff", "color", "ffffff", new FxConfig() {{
166: * setDuration(3)
167: * }});
168: *
169: * @param color The highlight color. Should be a 6 char hex color without the leading # (defaults to yellow: 'ffff9c')
170: * @param attr the attribute. Can be any valid CSS property (attribute) that supports a color value. Default is 'background-color'
171: * @param endColor the end color
172: * @param config the Fx config
173: * @return this
174: */
175: Fx highlight(String color, String attr, String endColor,
176: FxConfig config);
177:
178: /**
179: * Creates a pause before any subsequent queued effects begin. If there are no effects queued after the pause it will have no effect.
180: *
181: * @param seconds The length of time to pause (in seconds)
182: * @return this
183: */
184: Fx pause(int seconds);
185:
186: /**
187: * Fades the element out while slowly expanding it in all directions. When the effect is completed, the element will be hidden (visibility = 'hidden')
188: * but block elements will still take up space in the document.
189: *
190: * @return this
191: */
192: Fx puff();
193:
194: /**
195: * Fades the element out while slowly expanding it in all directions. When the effect is completed, the element will be hidden (visibility = 'hidden') but block elements will still take up space in the document.
196: * The element can be removed from the DOM using the 'remove' config option if desired.
197: *
198: * @param remove true to remove element
199: * @param config the Fx config
200: * @return this
201: */
202: Fx puff(boolean remove, FxConfig config);
203:
204: /**
205: * Animates the transition of an element's dimensions from a starting height/width to an ending height/width.
206: *
207: * @param width The new width
208: * @param height The new height
209: * @return this
210: */
211: Fx scale(int width, int height);
212:
213: /**
214: * Animates the transition of an element's dimensions from a starting height/width to an ending height/width.
215: *
216: * @param width The new width
217: * @param height The new height
218: * @param config the Fx config
219: * @return this
220: */
221: Fx scale(int width, int height, FxConfig config);
222:
223: /**
224: * Ensures that all effects queued after sequenceFx is called on the element are run in sequence. This is the opposite of syncFx.
225: *
226: * @return this
227: */
228: Fx sequenceFx();
229:
230: /**
231: * Animates the transition of any combination of an element's dimensions, xy position and/or opacity. Any of these
232: * properties not specified in the config object will not be changed. This effect requires that at least one new dimension, position or opacity setting must be passed in on the config object in order for the function to have any effect.
233: *
234: * @param x X postionion
235: * @param y Y position
236: * @param width the new width
237: * @param height the new height
238: * @param config the Fx config
239: * @return this
240: */
241: Fx shift(int x, int y, int width, int height, FxConfig config);
242:
243: /**
244: * Slides the element into view. An anchor point can be optionally passed to set the point of origin for the slide effect.
245: * This function automatically handles wrapping the element with a fixed-size container if needed.
246: * Slides in from top by default.
247: *
248: * @return this
249: */
250: Fx slideIn();
251:
252: /**
253: * Slides the element into view. An anchor point can be optionally passed to set the point of origin for the slide effect.
254: * This function automatically handles wrapping the element with a fixed-size container if needed.
255: *
256: * @param anchorPosition the anchor position
257: * @param config the Fx config
258: * @return this
259: */
260: Fx slideIn(String anchorPosition, FxConfig config);
261:
262: /**
263: * Slides the element out of view. An anchor point can be optionally passed to set the end point for the slide effect.
264: * When the effect is completed, the element will be hidden (visibility = 'hidden') but block elements will still take up space in the document.
265: * This function automatically handles wrapping the element with a fixed-size container if needed.
266: *
267: * @return this
268: */
269: Fx slideOut();
270:
271: /**
272: * Slides the element out of view. An anchor point can be optionally passed to set the end point for the slide effect.
273: * When the effect is completed, the element will be hidden (visibility = 'hidden') but block elements will still take up space in the document.
274: * This function automatically handles wrapping the element with a fixed-size container if needed.
275: *
276: * @param remove true to remove element from the DOM
277: * @param anchorPosition the anchor position
278: * @param config the Fx config
279: * @return this
280: */
281: Fx slideOut(boolean remove, String anchorPosition, FxConfig config);
282:
283: /**
284: * Stops any running effects and clears the element's internal effects queue if it contains any additional effects
285: * that haven't started yet.
286: *
287: * @return this
288: */
289: Fx stopFx();
290:
291: /**
292: * Blinks the element as if it was clicked and then collapses on its center (similar to switching off a television).
293: * When the effect is completed, the element will be hidden (visibility = 'hidden') but block elements will still take up space in the document.
294: *
295: * @return this
296: */
297: Fx switchOff();
298:
299: /**
300: * Blinks the element as if it was clicked and then collapses on its center (similar to switching off a television).
301: * When the effect is completed, the element will be hidden (visibility = 'hidden') but block elements will still take up space in the document.
302: *
303: * @param remove true to remove element from the DOM
304: * @param config the Fx config
305: * @return this
306: */
307: Fx switchOff(boolean remove, FxConfig config);
308:
309: /**
310: * Ensures that all effects queued after syncFx is called on the element are run concurrently. This is the opposite of sequenceFx.
311: *
312: * @return this
313: */
314: Fx syncFx();
315: }
|