Changeset 504

Show
Ignore:
Timestamp:
01/15/06 06:24:58 (3 years ago)
Author:
therve@gmail.com
Message:

Add docs to effects, correct a bug in ScrollTo?.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved
  • mochikit/branches/scriptaculous/MochiKit/Effects.js

    r502 r504  
    1414var Effect = { 
    1515    tagifyText: function (element) { 
     16        // XXX: what's this function for ? Doesn't work 
    1617        var tagifyStyle = 'position:relative'; 
    1718        if (MochiKit.Base.isIE()) { 
     
    3334 
    3435    multiple: function (element, effect, options) { 
     36        // XXX: what's this function for ? Doesn't work 
    3537        var elements; 
    3638        if (((typeof(element) == 'object') || 
     
    5961    }, 
    6062 
    61     toggle: function (element, effect, options) { 
     63    toggle: function (element, /* optional */effect, /* optional */options) { 
     64    /*** 
     65 
     66    Toggle an item between two state depending of its visibility, making 
     67    a effect between these states. Default  effect is 'appear', can be 
     68    'slide' or 'blind'. 
     69 
     70    ***/ 
    6271        element = MochiKit.DOM.getElement(element); 
    6372        effect = (effect || 'appear').toLowerCase(); 
     
    6675        }, options || {}); 
    6776        Effect[MochiKit.DOM.isVisible(element) ? 
    68             Effect.PAIRS[effect][1] : Effect.PAIRS[effect][0]](element, options); 
     77          Effect.PAIRS[effect][1] : Effect.PAIRS[effect][0]](element, options); 
    6978    } 
    7079}; 
    7180 
    72 /* ------------- transitions ------------- */ 
     81/*** 
     82 
     83Transitions: define functions calculating variations depending of a position. 
     84 
     85***/ 
    7386 
    7487Effect.Transitions = {} 
     
    8093    return (-Math.cos(pos*Math.PI)/2) + 0.5; 
    8194} 
    82 Effect.Transitions.reverse    = function (pos) { 
    83     return 1-pos; 
     95Effect.Transitions.reverse = function (pos) { 
     96    return 1 - pos; 
    8497} 
    8598Effect.Transitions.flicker = function (pos) { 
     
    91104Effect.Transitions.pulse = function (pos) { 
    92105    return (Math.floor(pos*10) % 2 == 0 ? 
    93         (pos*10-Math.floor(pos*10)) : 1-(pos*10-Math.floor(pos*10))); 
     106        (pos*10 - Math.floor(pos*10)) : 1 - (pos*10 - Math.floor(pos*10))); 
    94107} 
    95108Effect.Transitions.none = function (pos) { 
     
    100113} 
    101114 
    102 /* ------------- core effects ------------- */ 
     115/*** 
     116 
     117Core effects 
     118 
     119***/ 
    103120 
    104121Effect.ScopedQueue = function () { 
     
    145162        this.effects.push(effect); 
    146163        if (!this.interval) { 
    147             this.interval = setInterval(MochiKit.Base.bind(this.loop, this), 40); 
     164            this.interval = setInterval(MochiKit.Base.bind(this.loop, this), 
     165                                        40); 
    148166        } 
    149167    }, 
     
    169187Effect.Queues = { 
    170188    instances: new Array(), 
     189 
    171190    get: function (queueName) { 
    172191        if (typeof(queueName) != 'string') { 
     
    197216 
    198217Effect.Base.prototype = { 
     218    /*** 
     219 
     220    Basic class for all Effects. Define a looping mecanism called for each step 
     221    of an effect. Don't instanciate it, only subclass it. 
     222 
     223    ***/ 
    199224    position: null, 
    200225 
    201226    start: function (options) { 
    202         this.options = MochiKit.Base.setdefault(options || {}, Effect.DefaultOptions); 
     227        this.options = MochiKit.Base.setdefault(options || {}, 
     228                                                Effect.DefaultOptions); 
    203229        this.currentFrame = 0; 
    204230        this.state = 'idle'; 
     
    225251            } 
    226252            var pos = (timePos - this.startOn) / (this.finishOn - this.startOn); 
    227             var frame = Math.round(pos * this.options.fps * this.options.duration); 
     253            var frame = 
     254                Math.round(pos * this.options.fps * this.options.duration); 
    228255            if (frame > this.currentFrame) { 
    229256                this.render(pos); 
     
    275302 
    276303    __repr__: function () { 
    277         return '<Effect:' + MochiKit.Base.repr(this) + ', options:' + MochiKit.Base.repr(this.options) + '>'; 
     304        return '<Effect:' + MochiKit.Base.repr(this) + ', options:' + 
     305               MochiKit.Base.repr(this.options) + '>'; 
    278306    } 
    279307} 
     
    286314 
    287315MochiKit.Base.update(Effect.Parallel.prototype, { 
     316    /*** 
     317 
     318    Run multiple effects at the same time. 
     319 
     320    ***/ 
    288321    __init__: function (effects, options) { 
    289322        this.effects = effects || []; 
     
    317350 
    318351MochiKit.Base.update(Effect.Opacity.prototype, { 
    319     __init__: function (element, options) { 
     352    /*** 
     353 
     354    Change the opacity of an element. 
     355 
     356    @param options: 'from' and 'to' change the starting and ending opacities. 
     357    Must be between 0.0 and 1.0. Default to current opacity and 1.0. 
     358 
     359    ***/ 
     360    __init__: function (element, /* optional */options) { 
    320361        this.element = MochiKit.DOM.getElement(element); 
    321362        // make this work on IE on elements without 'layout' 
     
    342383 
    343384MochiKit.Base.update(Effect.Move.prototype, { 
    344     __init__: function (element, options) { 
     385    /*** 
     386 
     387    Move an element between its current position to a defined position 
     388 
     389    @param options: 'x' and 'y' for final positions, default to 0, 0. 
     390 
     391    ***/ 
     392    __init__: function (element, /* optional */options) { 
    345393        this.element = MochiKit.DOM.getElement(element); 
    346394        options = MochiKit.Base.update({ 
     
    353401 
    354402    setup: function () { 
    355         // Bug in Opera: Opera returns the 'real' position of a static element or 
    356         // relative element that does not have top/left explicitly set. 
    357         // ==> Always set top and left for position relative elements in your stylesheets 
    358         // (to 0 if you do not need them) 
     403        // Bug in Opera: Opera returns the 'real' position of a static element 
     404        // or relative element that does not have top/left explicitly set. 
     405        // ==> Always set top and left for position relative elements in your 
     406        // stylesheets (to 0 if you do not need them) 
    359407        MochiKit.DOM.makePositioned(this.element); 
    360         this.originalLeft = parseFloat(MochiKit.DOM.getStyle(this.element,'left') || '0'); 
    361         this.originalTop = parseFloat(MochiKit.DOM.getStyle(this.element,'top') || '0'); 
     408        this.originalLeft = parseFloat(MochiKit.DOM.getStyle(this.element, 
     409                                                             'left') || '0'); 
     410        this.originalTop = parseFloat(MochiKit.DOM.getStyle(this.element, 
     411                                                            'top') || '0'); 
    362412        if (this.options.mode == 'absolute') { 
    363413            // absolute movement, so we need to calc deltaX and deltaY 
     
    382432 
    383433MochiKit.Base.update(Effect.Scale.prototype, { 
    384     __init__: function (element, percent, options) { 
     434    /*** 
     435 
     436    Change the size of an element. 
     437 
     438    @param percent: final_size = percent*original_size 
     439 
     440    @param options: several options changing scale behaviour 
     441 
     442    ***/ 
     443    __init__: function (element, percent, /* optional */options) { 
    385444        this.element = MochiKit.DOM.getElement(element) 
    386445        options = MochiKit.Base.update({ 
     
    398457    setup: function () { 
    399458        this.restoreAfterFinish = this.options.restoreAfterFinish || false; 
    400         this.elementPositioning = MochiKit.DOM.getStyle(this.element,'position'); 
     459        this.elementPositioning = MochiKit.DOM.getStyle(this.element, 
     460                                                        'position'); 
    401461 
    402462        this.originalStyle = {}; 
     
    409469        this.originalLeft = this.element.offsetLeft; 
    410470 
    411         var fontSize = MochiKit.DOM.getStyle(this.element,'font-size') || '100%'; 
    412         MochiKit.Iter.forEach(['em','px','%'], MochiKit.Base.bind(function (fontSizeType) { 
     471        var fontSize = MochiKit.DOM.getStyle(this.element, 
     472                                             'font-size') || '100%'; 
     473        MochiKit.Iter.forEach(['em', 'px', '%'], 
     474            MochiKit.Base.bind(function (fontSizeType) { 
    413475            if (fontSize.indexOf(fontSizeType) > 0) { 
    414476                this.fontSize = parseFloat(fontSize); 
     
    433495 
    434496    update: function (position) { 
    435         var currentScale = (this.options.scaleFrom/100.0) + (this.factor * position); 
     497        var currentScale = (this.options.scaleFrom/100.0) + 
     498                           (this.factor * position); 
    436499        if (this.options.scaleContent && this.fontSize) { 
    437500            MochiKit.DOM.setStyle(this.element, { 
     
    439502            }); 
    440503        } 
    441         this.setDimensions(this.dims[0] * currentScale, this.dims[1] * currentScale); 
     504        this.setDimensions(this.dims[0] * currentScale, 
     505                           this.dims[1] * currentScale); 
    442506    }, 
    443507 
     
    486550 
    487551MochiKit.Base.update(Effect.Highlight.prototype, { 
    488     __init__: function (element, options) { 
     552    /*** 
     553 
     554    Highlight an item of the page. 
     555 
     556    @param options: 'startcolor' for choosing highlighting color, default 
     557    to '#ffff99'. 
     558 
     559    ***/ 
     560    __init__: function (element, /* optional */options) { 
    489561        this.element = MochiKit.DOM.getElement(element); 
    490562        options = MochiKit.Base.update({ 
    491             startcolor: '#ffff99', 
    492             numSteps: 16 
     563            startcolor: '#ffff99' 
    493564        }, options || {}); 
    494565        this.start(options); 
     
    503574        // Disable background image during the effect 
    504575        this.oldStyle = { 
    505             backgroundImage: MochiKit.DOM.getStyle(this.element, 'background-image') 
     576            backgroundImage: MochiKit.DOM.getStyle(this.element, 
     577                                                   'background-image') 
    506578        }; 
    507579        MochiKit.DOM.setStyle(this.element, { 
     
    510582 
    511583        if (!this.options.endcolor) { 
    512             this.options.endcolor = MochiKit.Color.Color.fromBackground(this.element).toHexString(); 
     584            this.options.endcolor = 
     585                MochiKit.Color.Color.fromBackground(this.element).toHexString(); 
    513586        } 
    514587        if(!this.options.restorecolor) { 
    515             this.options.restorecolor = MochiKit.DOM.getStyle(this.element, 'background-color'); 
     588            this.options.restorecolor = MochiKit.DOM.getStyle(this.element, 
     589                                                            'background-color'); 
    516590        } 
    517591        // init color calculations 
    518592        this._base = MochiKit.Base.map(MochiKit.Base.bind(function (i) { 
    519             return parseInt(this.options.startcolor.slice(i*2 + 1, i*2 + 3), 16); 
     593            return parseInt( 
     594                this.options.startcolor.slice(i*2 + 1, i*2 + 3), 16); 
    520595        }, this), [0, 1, 2]); 
    521596        this._delta = MochiKit.Base.map(MochiKit.Base.bind(function (i) { 
    522             return parseInt(this.options.endcolor.slice(i*2 + 1, i*2 + 3), 16) - this._base[i]; 
     597            return parseInt(this.options.endcolor.slice(i*2 + 1, i*2 + 3), 16) 
     598                - this._base[i]; 
    523599        }, this), [0, 1, 2]); 
    524600    }, 
     
    527603        var m = '#'; 
    528604        MochiKit.Iter.forEach([0, 1, 2], MochiKit.Base.bind(function (i) { 
    529             m += MochiKit.Color.toColorPart(Math.round(this._base[i] + (this._delta[i]*position))); 
     605            m += MochiKit.Color.toColorPart(Math.round(this._base[i] + 
     606                                            this._delta[i]*position)); 
    530607        }, this)); 
    531608        MochiKit.DOM.setStyle(this.element, { 
     
    535612 
    536613    finish: function () { 
    537         MochiKit.DOM.setStyle(this.element, MochiKit.Base.update(this.oldStyle, { 
     614        MochiKit.DOM.setStyle(this.element, 
     615            MochiKit.Base.update(this.oldStyle, { 
    538616            backgroundColor: this.options.endColor 
    539617        })); 
     
    548626 
    549627MochiKit.Base.update(Effect.ScrollTo.prototype, { 
    550     __init__: function (element, options) { 
     628    /*** 
     629 
     630    Scroll to an element in the page. 
     631 
     632    ***/ 
     633    __init__: function (element, /* optional */options) { 
    551634        this.element = MochiKit.DOM.getElement(element); 
    552635        this.start(options || {}); 
     
    554637 
    555638    setup: function () { 
    556         Position.prepare(); 
     639        MochiKit.Position.prepare(); 
    557640        var offsets = MochiKit.Position.cumulativeOffset(this.element); 
    558641        if (this.options.offset) { 
     
    563646            document.body.scrollHeight - 
    564647                (document.documentElement.clientHeight ? 
    565                     document.documentElement.clientHeight : document.body.clientHeight); 
     648                    document.documentElement.clientHeight : 
     649                    document.body.clientHeight); 
    566650        this.scrollStart = MochiKit.Position.deltaY; 
    567651        this.delta = (offsets[1] > max ? max : offsets[1]) - this.scrollStart; 
     
    569653 
    570654    update: function (position) { 
    571         Position.prepare(); 
    572         window.scrollTo(Position.deltaX, 
     655        MochiKit.Position.prepare(); 
     656        window.scrollTo(MochiKit.Position.deltaX, 
    573657            this.scrollStart + (position*this.delta)); 
    574658    } 
    575659}); 
    576660 
    577 /* ------------- combination effects ------------- */ 
     661/*** 
     662 
     663Combination effects. 
     664 
     665***/ 
    578666 
    579667Effect.Fade = function (element, options) {