$$.DrawnCheck.jsxinc

/*******************************************************************************

		Name:           DrawnCheck(Factory)
		Desc:           On/off icon based on custom onDraw.
		Path:           /etc/ScriptUI/factories/$$.DrawnCheck.jsxinc
		Require:        ScriptUI/factories ; ScriptUI.builder ; ScriptUI/events [recommended]
		Encoding:       ÛȚF8
		Core:           NO
		Kind:           Snippet
		API:            ScriptUI.DrawnCheckFactory()
		DOM-access:     NO
		Todo:           ---
		Created:        220131 (YYMMDD)
		Modified:       230508 (YYMMDD)

*******************************************************************************/

	//==========================================================================
	// NOTICE
	//==========================================================================
	
	/*
	
	DrawnCheckFactory provides a CS/CC-consistent 18x18 rounded icon based on a
	custom implementation of onDraw. This component supports two-state icon buttons
	(on/off) as well as simple buttons that react to click events. It is formally
	based on a Checkbox object nested in a Group:

	      +-------+
	      ¦ +===+ ¦
	      ¦ |   | ¦
	      ¦ +===+ ¦
	      +-------+

	The Checkbox is redrawn according to a custom function that must be loaded
	in the `ScriptUI.DrawnCheckFactory.Icons` map:
	
	1. Each custom function should have a name (uppercase recommended)
	   matching the `icon` property. E.g.

	      myIconFunc = function MY_ICON(gx,pen,bh){ . . . }
	   
	   where 'MY_ICON' is the key registered in the Icons map.
	   
	   [REM] icon_key == func_name is not involved in the current implemen-
	         tation BUT could be used in the future, so we posit this
	         condition as a formal requirement.

	2. The function will be called in the context of the component, that is,
	   with this===Group[[DrawnCheck]]. This opens the option to adjust
	   drawing operation according to the component state.
	
	3. Three arguments are passed, gx::ScriptUIGraphics, pen::ScriptUIPen,
	   and bh::ScriptUIBrush (in that order.) `gx` represents the 'canvas'
	   of the inner Checkbox. Use it to create paths -- gx.newPath() --
	   and initiate drawing operations. `pen` and `bh` can be used as default
	   pen and brush, but you can create your own from within the function.
	   The area available for drawing is (1,17)×(1,17).
	
	4. The returned value of the function is not used.
	
	[REM] Thanks to ScriptUIGraphics.prototype.draw (cf. $$.factories.jsxinc)
	you can dramatically shorten the drawing procedure. Here is a function
	that draws a 'LAYER' icon:

		function LAYER(gx,pen,bh)
		//----------------------------------
		// this :: Group[[DrawnCheck]]
		{
			gx.newPath();
			gx.draw(9,3)(3,7)(9,11)(15,7)(9,3);
			gx.strokePath(pen);
			gx.fillPath(bh);

			gx.newPath();
			gx.draw(3,10)(9,14)(15,10);
			gx.strokePath(pen);
		}
	
	(a) If your icon functions are to be declared before including the DrawnCheck
	    factory, it is recommended to set you data in a MODULE (or CLASS) and use the
	    `onEngine` handler for loading the keys in `ScriptUI.DrawnCheckFactory.Icons`.
	    (Be sure then that you won't replace existing Icons keys.)
	
	(b) Othwerwise, you can use the scheme

	      ScriptUI.DrawnCheckFactory.Icons.setup
	      ({
	         ICON1: function ICON1(gx,pen,bh){ ... },
	         ICON2: function ICON2(gx,pen,bh){ ... },
	         . . .
	      })

	    as soon as the DrawnCheck factory is included (and before loading the framework.)
	
	[ADD220602] Each ICON function can provide a special `onLoad` method
	that will be triggered at loading stage.
	
	BUTTON FLAVORS
	
	1. To create a on/off icon button, just let the component toggle (based on its
	   value property.) You can preset the value and change it dynamically.
	
	2. To create a simple, one-state button, set the option `locked` to true (this
	   prevents the value to change, so the button won't toggle.) Then define the
	   `onClickChange` handler to trigger the desired action.
	
	3. You can also create a 'passive' on/off icon through the option `ignoreClick`.
	   In that case, the component won't respond to user interactions (no click, no
	   focus) but its value can be changed programmatically.

	Example in ScriptUI.builder:

	      DrawnCheckFactory$MyCheckableIcon:
	      [{
	          icon:    "LAYER",                        // ScriptUI.DrawnCheckFactory.Icons.LAYER must exist
	          help:    "Scan hidden layers.",          // helpTip
	          value:   1,                              // initial value (0|1)
	      }],

	API
	=======================================================================
	properties      obj = { kind: "DrawnCheck", IgnoreClick:0|1, Locked:0|1,
	                        NoBorder:0|1 }
	                Information properties.
	-----------------------------------------------------------------------
	value           0|1 = 0
	                Getter & setter that turns the control OFF (0) or ON (1).
	-----------------------------------------------------------------------
	icon            str | ''
	                Getter & setter ; can dynamically change the icon (key.)
	-----------------------------------------------------------------------
	extra           any = undef
	                Custom property.
	-----------------------------------------------------------------------
	helpTip         str = ""
	                Help message (getter and setter).
	=======================================================================
	onClickChange   fct( ev[[clicked]] ) = undef
	                Called back when the custom 'clicked' event has occured.
	                This mechanism is more stable than a 'click' listener:
	                it reacts *once* per click and ignore RIGHT mouse button.
	                [REM] The 'clicked' event also occurs when the user
	                      presses the [SPACE] key.
	-----------------------------------------------------------------------
	onRightClick    fct( ev[[rclicked]] ) = undef
	                Called back when the custom 'rclicked' event (right-click)
	                has occured.
	-----------------------------------------------------------------------
	onEvent         fct(ev) = undef
	                Called back when any of the following events has occured:
	                clicked | rclicked
	=======================================================================
	setValue(nv)    => nv
	                Equivalent to { this.value=nv; return this.value; }
	-----------------------------------------------------------------------
	getValue()      => (0|1)
	                Equivalent to { return this.value; }
	-----------------------------------------------------------------------
	getControl()    => Checkbox
	                Return the inner Checkbox.
	-----------------------------------------------------------------------
	popup(s,c,t)    => undef
	                Shortcut for sending a popup event in automatic mode.
	                If no Popup component is available, this method has no
	                effect.
	=======================================================================

	*/

	;if( $$.isBooting() )
	//----------------------------------
	// This condition is required for persistent engines.
	{
		ScriptUI.DrawnCheckFactory = function DrawnCheck(/*container*/parent,/*str|{icon,help,value...}*/ops,  V,DRW,r)
		//----------------------------------
		// Options (ops):
		// .icon       (key)        Icon key, ScriptUI.DrawnCheckFactory.Icons[icon] must exist and be a function.
		// .helpTip    (str='')     Help tip (`help` can be supplied as an alias.)
		// .value      (bool=0)      0:uncheked 1:checked (Bool supported.)
		// ---
		// .margins     (uint=1)    Margins around the icon.
		// .ignoreClick (bool=0)    If set, left mouse buttons are ignored.
		// .locked      (bool=0)    If set, the value cannot be changed by the user.
		// .noBorder    (bool=0)    If set, the button border is hidden.
		// ---
		// .onClickChange (?fct)    'clicked' handler.
		// .onRightClick  (?fct)    'rclicked' handler.
		// .onEvent       (?fct)    Any event handler.
		// ---
		// .extra          (any)    Any custom property. [DEPRECATED: Use `more` instead.]
		// .enabled | .visible      States.
		// .more          (?obj)    Custom options.
		// ---
		// => Group[[DrawnCheck]]  ::   G(C)
		//   .properties           ::   { kind, IgnoreClick, Locked }
		{
			// Normalize options.
			// ---
			'string' == typeof ops && (ops={icon:ops});
			ops && ops.help && !ops.helpTip && (ops.helpTip=ops.help);     // helpTip alias (help)
			ops = ScriptUI.factoryOptions(ops,callee.DEFS);                // defaults
			V = ops.value = 1*(0!=ops.value);                              // 0|1
			
			DRW = 'function' == typeof(callee.Icons[ops.icon]);

			// Create the component.
			// ---
			r = 
			{
				// --- Layout.
				margins:                ops.margins,
				spacing:                0,
				orientation:            'row',
				alignChildren:          ScriptUI.CC,
				// --- Watched.
				value:                  V,
				icon:                   DRW ? ops.icon : '',
				helpTip:                ops.helpTip,
				extra:                  ops.extra, // not watched [DEPRECATED]
				onClickChange:          void 0,
				onRightClick:           void 0,
				onEvent:                void 0,
				// --- Inner events.
				_mousedown_mouseup:     ops.ignoreClick ? void 0 : callee.HMOU,
				// --- Private
				__mouseDetails__:       '', // [ADD220520]
				// --- Public methods.
				setValue:               callee.SETV,
				getValue:               callee.GETV,
				getControl:             callee.CTRL, // ret. the main component
				popup:                  ScriptUI.POPU, // noop if Popup unavailable.
				// --- Control.
				CheckBox$0:
				{
					properties:         { text:'' },
					alignment:          ScriptUI.CC,
					value:              !!V,
					__iconKey__:        DRW ? ops.icon : '',
					_mousedown:         ops.ignoreClick ? void 0 : callee.HDWN, // [ADD220520] Only for registering the MouseEvent props
					onClick:            ops.ignoreClick ? void 0 : callee.HMOU,
					onDraw:             callee.HDRW,
					optimalSize:        callee.SIZE,
					maximumSize:        callee.SIZE,
					_blur:              callee.HBLU,
					enabled:            !ops.ignoreClick,
				},
			};

			r = ScriptUI.builder
			(
				ScriptUI.moreOptions(r, ops.more),                         // [ADD220807]
				parent.add( 'group', void 0, callee.CREA(ops) )
			);

			// Watcher.
			// ---
			ScriptUI.setWatcher
			(
				r,
				['value', 'icon', 'helpTip', 'onClickChange', 'onRightClick', 'onEvent'],
				callee.WTCH,
				ops
			);

			// States.
			// ---
			( false===ops.enabled || 0===ops.enabled ) && (r.enabled=false);
			( false===ops.visible || 0===ops.visible ) && (r.visible=false);

			return r;
		}
		.setup
		//----------------------------------
		// Static
		//----------------------------------
		({
			onLoad: function onLoad(  F,dk,d,x,t,r,g,b,o,k)
			//----------------------------------
			// (Re)set HDRW colors: CDSB, CVL0, CVL1, CINV, XVL0, XVL1, CFOC, XFOC
			// this :: ScriptUI.DrawnCheckFactory
			// => this&
			{
				F = this.HDRW;
				dk = $$.isDark;
				d = dk ? (1-$$.isHighContrast) : (2+$$.isHighContrast); // 0|1|2|3

				F.CDSB = ( (x=[.40,.48,.58,.75][d]), [x,x,x,1] );

				dk ? (x+=.1) : (x-=.1);
				F.CVL0 = [x,x,x,1];
				// ---
				t = [.75,.78,.30,.35][d];
				F.CVL1 = [t,t,t,1];
				// ---
				t = dk ? (x-.2) : (x+.2);
				F.CINV = [t,t,t,1];
				// ---
				t = dk ? (x+.4) : (x-.4);
				F.XVL0 = [t,t,t,1];
				// ---
				1 < (t+=.05)  && (t=1);
				F.XVL1 = [t,t,t,1];

				r = [.30,.30,.25,.32][d];
				g = [.60,.61,.56,.65][d];
				b = [.90,.92,.87,.98][d];
				F.CFOC = [r,g,b,1];

				1 < (r += .1)  && (r=1);
				1 < (g += .05) && (g=1);
				1 < (b += .02) && (b=1);
				F.XFOC = [r,g,b,1];
				
				// [ADD220602] Support .onLoad for each ICON function.
				// WARNING: Not supported in CS4.
				o = this.Icons;
				for( k in o )
				{
					o.hasOwnProperty(k)
					&& 'function' == typeof(t=o[k])
					&& 'function' == typeof(t.onLoad)
					&& t.onLoad();
				}

				return this;
			},
		})
		.setup
		//----------------------------------
		// Parameters, tools.
		//----------------------------------
		({
			// Container of icon functions.
			// Each function will be called with context===Group[[DrawnCheck]]
			// and arguments (ScriptUIGraphics, ScriptUIPen, ScriptUIBrush)
			// Draw your icon in (1,17)×(1,17) square.
			// ---
			Icons: {},

			SIZE: [18,18],

			DEFS:
			{
				icon:         '',
				helpTip:      '',
				value:        0,
				margins:      1,
				ignoreClick:  0,
				locked:       0,
				noBorder:     0,
				// ---
				onClickChange: void 0,
				onRightClick:  void 0,
				onEvent:       void 0,
				// ---
				more:         {},
			},
			
			CREA: function(/*{}*/ops)
			//----------------------------------
			// this :: ScriptUI.DrawnCheckFactory
			// => new {}  ; properties object
			{
				return {
					kind:          this.name,
					IgnoreClick:   ops.ignoreClick ? 1 : 0,
					Locked:        ops.locked ? 1 : 0,
					NoBorder:      ops.noBorder ? 1 : 0,
				};
			},
		})
		.setup
		//----------------------------------
		// Inner events.
		//----------------------------------
		({
			HDRW: function onDrawCheckbox(/*DrawState*/DS,  me,gx,v,k,a,p,b,f)
			//----------------------------------
			// onDraw callback of the inner Checkbox.
			// [REM] Inner colors CDSB, CVL0, CVL1, CINV, XVL0, XVL1, CFOC, XFOC
			// are now managed from onLoad.
			// this  :: Checkbox
			{
				if( (!this.visible) || !(gx=this.graphics) ) return;
				me = this.parent; // DrawnCheck component.
				v = this.value?1:0;
				
				// [CHG230508] Added dynamic __mouseOver__ and __hasFocus__ properties.
				// ---
				delete me.__mouseOver__;
				delete me.__hasFocus__;
				k = me.enabled
				? ( ((me.__mouseOver__=DS.mouseOver) ? 'X':'C') + ((me.__hasFocus__=DS.hasFocus) ? 'FOC':('VL'+v)) )
				: 'CDSB';

				a = callee[k];
				p = gx.newPen(0,a,1);
				b = gx.newBrush(0,a);
				
				gx.draw.DX = gx.draw.DY = 0;
				if( !(me.properties||0).NoBorder )
				{
					gx.newPath();
					gx.draw(17,2)(17,16)(16,17)(2,17)(1,16)(1,2)(2,1)(16,1)(17,2);
					gx.strokePath(p);
					v && gx.fillPath(b);
				}

				f = ScriptUI.DrawnCheckFactory.Icons[this.__iconKey__];
				if( 'function' != typeof f ) return;
				
				v &&
				(
					p=gx.newPen(0,callee.CINV,1),
					b=gx.newBrush(0,callee.CINV)
				);
				f.call(me,gx,p,b);
			},

			// [FIX210122] In CC most widgets have an obscure focus/blur
			// sequence that may keep them 'active' while losing the focus.
			// Forcing this.active to false seems to solve the pb.
			// ---
			HBLU: $$.inCC && function onBlurCheckbox(){ this.active=false },

			HDWN: function onMouseDown(/*mousedown*/ev)
			//----------------------------------
			// [ADD220520] This extra handler *only* registers essential mouse details.
			// It is used by HMOU to recreate an informed event when necessary.
			// Sets the `__mouseDetails__` private prop (str), structure:
			// `<ctrlKey>|<altKey>|<shiftKey>|<metaKey>|<button>|<screenX>|<screenY>|<clientX>|<clientY>`
			// all stringified from their numeric value (booleans being coerced into '0' or '1'.)
			// ---
			// this   :: Inner Checkbox
			// ev     :: mousedown
			// target :: this | Checkbox
			// => undef
			{
				ev.target===this && (this.parent.__mouseDetails__ =
				[
					(0|ev.ctrlKey),
					(0|ev.altKey),
					(0|ev.shiftKey),
					(0|ev.metaKey),
					// ---
					(0|ev.button),
					(0|ev.screenX),
					(0|ev.screenY),
					(0|ev.clientX),
					(0|ev.clientY)
				].join('|'));
			},

			HMOU: function onMouse(/*?MouseEvent*/ev,  me,t,fire)
			//----------------------------------
			// Manage both CB.onClick callback AND mouse events.
			// ---
			// this   :: Group[[DrawnCheck]]             | Checkbox
			// ev     :: mousedown | mouseup             | undef (onClick handler)
			// target :: this | Checkbox                 | ---
			{
				t = this.type;
				me = 'checkbox'==t ? this.parent : this;

				if( !ev )
				{
					// CB onClick callback. This pseudo-event also
					// occurs when the user presses the [SPACE] key.
					// ---
					fire = 'checkbox'==t;
					t = (me.__mouseDetails__||'').split('|');
					ev =
					{
						base:     'M',
						ctrlKey:   '1'===t[0],
						altKey:    '1'===t[1],
						shiftKey:  '1'===t[2],
						metaKey:   '1'===t[3],
						button:    0|parseInt(t[4],10),
						screenX:   0|parseInt(t[5],10),
						screenY:   0|parseInt(t[6],10),
						clientX:   0|parseInt(t[7],10),
						clientY:   0|parseInt(t[8],10),
					};
				}
				else
				{
					ev.stopPropagation();                                       // Don't go higher.
					
					// [FIX220522] Certain OS/laptops treat Ctrl+Click as RightClick
					// and forcibly set `ev.button` to 2. Since we want to detect Ctrl+Click
					// separately, it is necessary to exclude `ev.ctrlKey==true` below.
					// ---
					if( (t=ev.button) && !(ev.ctrlKey && 2==t) )                // Catch non-LEFT button.
					{
						ev.preventDefault();                                    // Inhibit.

						'mousedown'==ev.type
						&& 2 == t                                               // RIGHT button
						&& (this===ev.target||callee.EV_PHASE==ev.eventPhase)   // 'bubble' is allowed in CS
						&& ScriptUI.dispatch(this,'rclicked',ev);               // Notify 'rclicked'

						return;
					}

					// Since CB onClick callback is treated separately,
					// we are now addressing left mousedown/up sequence
					// outside the CB area. This means:
					// - in CS:  ev.target !== CB
					// - in CC:  ev.target === this && <firstTarget> !== CB
					//           where firstTarget can be determined using a timer.
					// ---
					// [REM] In CC mouse events are re-targeted toward the parent so
					// we have to ignore events fired at the control level. But CC's
					// Checkbox also blocks any event we would expect after mousedown,
					// so we cannot manage the sequence CB[mousedown] + NonCB[mouseup]

					t = 'mousedown' == ev.type
					? -( ev.target && callee.CAN_STAMP(ev.target,this) && new Date ) // Stamp:  0 | <0
					: +( 500 > +new Date + (this.__stamp__||0) );                    // OK-Up:  0 | +1  (<500ms)
					
					0 > t ? (this.__stamp__=t) : delete this.__stamp__;              // Arm vs. delete the timer.

					fire = 1 == t;
				}

				if( fire )
				{
					me.setValue(1-me.value);                                    // Change value and redraw (rem: won't change if locked.)
					ScriptUI.setFocus(me.getControl());                         // Forcibly focus the box.
					ScriptUI.dispatch(me,'clicked',ev||0);                      // Notify 'clicked' to listeners.
				}
			}
			.setup
			({
				EV_PHASE : $.inCC ? 'BREAK' : 'bubble',

				CAN_STAMP : $.inCC ?
				//----------------------------------
				function(tg,me)
				{
					return 'checkbox' == tg.type ?
						( (callee.TM=+new Date), false ) :
						( tg===me && 100 < (+new Date - (callee.TM||0)) );
				}:
				function(tg)
				{
					return 'checkbox' != tg.type;
				},
			}),

		})
		.setup
		//----------------------------------
		// Watcher.
		//----------------------------------
		({
			WTCH: function watcher(/*str*/k,/*any*/ov,/*any*/nv)
			//----------------------------------
			// this   :: Group[[Check]]
			//    k   :: value | helpTip | icon
			//           onClickChange | onRightClick | onEvent
			{
				if( this.hasOwnProperty('µ_'+k) ) return nv; // Temporary transparent key.

				var t,a;
				switch( k )
				{
					case 'value': // 0 | 1
						this.properties.Locked && (nv=ov);
						nv >>>= 0;
						t = this.children[0];
						t.value=!!nv;
						t.hide(),t.show(); // Refresh needed.
						break;

					case 'icon': // str
						if( 'function' != typeof(ScriptUI.DrawnCheckFactory.Icons[nv]) ) return ov;
						t = this.children[0];
						t.__iconKey__ = nv;
						t.hide(),t.show(); // Refresh needed.
						break;

					case 'helpTip': // str
						nv = String(nv||'');
						a = this.children;
						a[0].helpTip = nv;
						break;

					case 'onClickChange': // fct
						ScriptUI.callback(this,'clicked',ov,nv);
						break;

					case 'onRightClick': // fct
						ScriptUI.callback(this,'rclicked',ov,nv);
						break;

					case 'onEvent': // fct
						ScriptUI.callback(this,['clicked','rclicked'],ov,nv);
						break;

					default:;
				}
				return nv;
			},
		})
		.setup
		//----------------------------------
		// Public.
		//----------------------------------
		({
			SETV: function setValue(nv){ return (this.value=nv), this.value },
			GETV: function getValue(  ){ return this.value },
			CTRL: function getControl(){ return this.children[0] },
		});
		
		$$.domVersion(7)||ScriptUI.DrawnCheckFactory.onLoad(); // CS4 fallback
	}