SC.mixin( /** @scope SC
*/ {
/** This function is similar to SC.metricsForString, but takes an extra argument after the string and before the exampleElement. That extra argument is *maxWidth*, which is the maximum allowable width in which the string can be displayed. This function will find the narrowest width (within *maxWidth*) that keeps the text at the same number of lines it would've normally wrapped to had it simply been put in a container of width *maxWidth*. If you have text that's 900 pixels wide on a single line, but pass *maxWidth* as 800, the metrics that will be returned will specify a height of two lines' worth of text, but a width of only around 450 pixels. The width this function determines will cause the text to be split as evenly as possible over both lines. If your text is 1500 pixels wide and *maxWidth* is 800, the width you'll get back will be approximately 750 pixels, because the 1500 horizontal pixels of text will still fit within two lines. If your text grows beyond 1600 horizontal pixels, it'll wrap to three lines. Suppose you have 1700 pixels of text. This much text would require three lines at 800px per line, but this function will return you a width of approximately 1700/3 pixels, in order to fill out the third line of text so it isn't just ~100px long. A binary search is used to find the optimimum width. There's no way to ask the browser this question, so the answer must be searched for. Understandably, this can cause a lot of measurements, which are NOT cheap. Therefore, very aggressive caching is used in order to get out of having to perform the search. The final optimimum width is a result of all the following values: - The string itself - The styles on the exampleElement - The classNames passed in - Whether ignoreEscape is YES or NO The caching goes against all of these in order to remember results. Note that maxWidth, though an argument, isn't one of them; this means that the optimal width will be searched for only once per distinct *number of lines of text* for a given string and styling. However, due to the fact that a passed exampleElement can have different styles a subsequent time it's passed in (but still remains the same object with the same GUID, etc), caching will not be enabled unless you either pass in a style string instead of an element, or unless your element has *cacheableForMetrics: YES* as a key on it. In most situations, the styles on an element won't change from call to call, so this is purely defensive and for arguably infrequent benefit, but it's good insurance. If you set the *cacheableForMetrics* key to YES on your exampleElement, caching will kick in, and repeated calls to this function will cease to have any appreciable amortized cost. The caching works by detecting and constructing known intervals of width for each number of lines required by widths in those intervals. As soon as you get a result from this function, it remembers that any width between the width it returned and the maxWidth you gave it will return that same result. This also applies to maxWidths greater than the with you passed in, up until the width at which the text can fit inside maxWidth with one fewer line break. However, at this point, the function can't know how MUCH larger maxWidth can get before getting to the next widest setting. A simple check can be done at this point to determine if the existing cached result can be used: if the height of the string at the new maxWidth is the same as the cached height, then we know the string didn't fit onto one fewer line, so return the cached value. If we did this check, we could return very quickly after only one string measurement, but EACH time we increase the maxWidth we'll have to do a new string measurement to check that we didn't end up with horizontal room for one fewer line. Because of this, instead of doing the check, the function will perform its binary search to go all the way UP to the minimum maxWidth at which one fewer line can be used to fit the text. After caching this value, all subsequent calls to the function will result in no string measurements as long as all the maxWidths are within the interval determined to lead to the cached result. So, the second call can in some cases be more expensive than it needs to be, but this saves A LOT of expense on all subsequent calls. The less often one calls metricsForString, the happier one's life is. The amount of time this function will take ranges from 0 to maybe 35ms on an old, slow machine, and, when used for window resizing, you'll see 35, 20, 0, 0, 0, ..., 0, 0, 35, 0, 0, 0, ..., 0, 0, 35, 0, 0, 0, ..., 0, 0, 0, 35, 0, 0, 0, ... After resizing through all the different caching intervals, the function will always execute quickly... under 1ms nearly always. The expensive calls are when a caching interval is crossed and a new cached set of metrics for the new number of lines of text must be calculated. And in reality, the number of sub-millisecond function calls will be much greater relative to the number of expensive calls, because window resizing just works like that. @param {String} string The text whose width you wish to optimize within your maximum width preference. @param {Number} maxWidth The maximum width the text is allowed to span, period. Can have "px" afterwards. Need not be a whole number. It will be stripped of "px", and/or rounded up to the nearest integer, if necessary. @param {Element/String} exampleElement The element whose styles will be used to measure the width and height of the string. You can pass a string of CSSText here if you wish, just as with SC.metricsForString. @param {String} [classNames] Optional. Any class names you wish to also put on the measurement element. @param {Boolean} [ignoreEscape] Optional. If true, HTML in your string will not be escaped. If false or omitted, any HTML characters will be escaped for the measurement. If it's omitted where it should be true for correct results, the metrics returned will usually be much bigger than otherwise required. */ bestStringMetricsForMaxWidth: function(string,maxWidth,exampleElement,classNames,ignoreEscape) { if(!maxWidth) { SC.warn("When calling bestMetricsForWidth, the second argument, maxWidth, is required. There's no reason to call this without a maxWidth."); return undefined; } maxWidth = Math.ceil(parseFloat(maxWidth)); var me = arguments.callee, exIsElement = SC.typeOf(exampleElement||(exampleElement=""))!==SC.T_STRING, savedMaxWidth = exIsElement ? exampleElement.style.maxWidth : undefined, cache = (!exIsElement || exampleElement.cacheableForMetrics) ? SC.cacheSlotFor(exampleElement,classNames,ignoreEscape,string) : undefined, applyMax = exIsElement ? (me._applyMaxToEl||(me._applyMaxToEl=function(el,width) { el.style.maxWidth = width+"px"; return el; })) : (me._applyMaxToStr||(me._applyMaxToStr=function(str,width) { return str.replace(/max-width:[^;]*;/g,'') + " max-width:"+width+"px"; })), removeMax = exIsElement ? (me._removeMaxFromEl||(me._removeMaxFromEl=function(el) { el.style.maxWidth = "none"; return el; })) : (me._removeMaxFromStr||(me._removeMaxFromStr=function(str) { return str.replace(/max-width:[^;]*;/g,'') + " max-width:none"; })), searchingUpward = false; if(cache) { cache.list || (cache.list = [{width: Infinity, height:0}]); for(var i=1,l=cache.list.length,inner,outer,ret; i<l && !ret; i++) { inner = cache.list[i]; outer = cache.list[i-1]; if(!inner || !inner.width) continue; if(maxWidth>=inner.width) { if((outer && outer.width) || (maxWidth<=inner.maxWidth)) { // console.error('returning from cache,',CW.Anim.enumerate(inner)); return inner; } // searchingUpward = true; //commented because this is currently problematic. If this remains false, duplicate work will be done if increasing in maxWidth since previous calls, but at least the results will be correct. ret = inner; } } } var exEl = applyMax(exampleElement,maxWidth), metrics = SC.metricsForString(string,exEl,classNames,ignoreEscape), necessaryHeight = metrics.height, oneLineHeight = cache ? cache.parent.height || (cache.parent.height=SC.metricsForString('W',exEl,classNames).height) : SC.metricsForString('W',exEl,classNames).height, lines = Math.round( necessaryHeight / oneLineHeight ); if(searchingUpward) { lines--; necessaryHeight=lines*oneLineHeight; } if(necessaryHeight > oneLineHeight) { var hi = searchingUpward ? Math.ceil(metrics.width*2.5) : metrics.width, lo = searchingUpward ? metrics.width : Math.floor(metrics.width/2.5), middle , now = new Date()*1, count = 0; while(hi-lo>1 || (metrics.height>necessaryHeight&&!searchingUpward) || (metrics.height<necessaryHeight&&searchingUpward)) { count++; middle = (hi+lo)/2; exEl = applyMax(exEl,middle); metrics = SC.metricsForString(string,exEl,classNames,ignoreEscape); if(metrics.height>necessaryHeight) lo = middle; else hi = middle; } metrics.width = Math.ceil(middle); metrics.height = necessaryHeight; metrics.maxWidth = maxWidth; metrics.lineHeight = oneLineHeight; metrics.lines = lines; metrics.searchPerformed = true; metrics.searchTime = new Date()*1 - now; metrics.searchCount = count; } else { if(searchingUpward) metrics = SC.metricsForString(string,exEl=removeMax(exEl),classNames,ignoreEscape); metrics.maxWidth = maxWidth; metrics.lineHeight = oneLineHeight; metrics.lines = lines; metrics.searchPerformed = false; } metrics.browserCorrection = 0; if(SC.browser.isIE) metrics.browserCorrection = 1; if(SC.browser.isMozilla) metrics.browserCorrection = 1; metrics.width = Math.min(maxWidth,metrics.width+metrics.browserCorrection); if(cache) { var entry = cache.list[lines]; if(entry && entry.maxWidth<maxWidth) entry.maxWidth = maxWidth; if(!entry) entry = cache.list[lines] = metrics; } if(exIsElement) exEl.style.maxWidth = savedMaxWidth; ret = searchingUpward ? ret : metrics; // console.error('returning at end'+(searchingUpward?" after searching upward and finding"+CW.Anim.enumerate(metrics):"")+'. Returned value is ',CW.Anim.enumerate(ret)); return ret; }, /** Supply any number of arguments of any type, and this function will return you a hash associated with all those arguments. Call it twice with the same arguments in the same order, and the hash is the same. This is great for getting out of calculations whose answers depend on many different variables. @param {anything} your-arguments Any set of arguments whatsoever. If the FIRST argument is an array (including Arguments arrays), all other arguments will be ignored and the array will be treated as if its values at its numerical indices were passed in themselves as individual arguments. @returns {Hash} A cached workspace mapped to the ordered *n*-tuple of arguments passed into it. */ cacheSlotFor: function() { var me = arguments.callee.caller, curr = me.cache || (me.cache={}); if(!arguments[0]) return curr; var args = (arguments[0] instanceof Array || arguments[0].callee) ? arguments[0] : arguments, length = args.length, arg , i ; for(i=0; i<length; i++) { if(typeof (arg=args[i]) === "object") arg = SC.guidFor(arg); curr = curr[arg] || (curr[arg]={parent:curr}); } return curr; }, /** Returns a wrapped copy of your function that caches its results according to its arguments. This function itself is cached, so the function you receive when you pass in a particular function will always be the same function. How was does this function handle its own caching? Using itself, of course! :-D Use this only on functions without side effects you depend on, and only on functions whose outputs depend entirely on their arguments and on nothing else external to them that could change. */ cachedVersionOf: function() { var ret = function(func) { var ret = function() { var cache = SC.cacheSlotFor(arguments); return cache.result || (cache.result = arguments.callee.func.apply(this,arguments)); }; ret.func = func; return ret; }; return ret(ret); }()
});