-- SELECT EYEDROPPER --
--
-- © January 2000, OpenSpark Interactive Ltd
--  <james.newton@openspark.com>
--
----------------------------------------------------------------------
-- For use with the Paint behavior.
--
-- Drop this on any graphic sprite which can act as a button.
--
-- Allows the user to select an eyedropper tool either by clicking on
-- the sprite or by pressing the Tab key.  The eyedropper tool is used
-- to modify the brush color used by the Canvas behavior.
--
-- Thanks to Ken Prat for his tip on sprite(0).cursor
----------------------------------------------------------------------




-- PROPERTY DECLARATIONS --

-- author-settable property
property useTabShortcut

-- other properties
property spriteNum

property pCallMeScript -- the mouseDownScript is set to this
property pSaveScript   -- original value of the mouseDownScript
property pSaveCursor   -- cursor to revert to after using the tool
property pMouseDown    -- TRUE if the Eyedropper tool is being used
property pActive       -- TRUE if the Eyedropper tool is active

property pTABPressed   -- TRUE if the TAB key has been pressed




-- SPRITE EVENT --

on beginSprite(me)
  me.mInitialize()
end beginSprite


on endSprite(me)
  me.mDisactivateEyedropper()
end endSprite




-- EVENT HANDLER --

on exitFrame(me)
  if pMouseDown then
    if the mouseDown then
      me.mShowBrushColor()
    else
      -- The user has released the mouse after choosing a color
      me.mSetBrushColor()
    end if
    
  else if useTabShortcut then
    me.mSetTabState()
  end if
end exitFrame



on mouseUp(me)
  me.mActivateEyedropper()
end mouseUp




-- PUBLIC METHOD --

on Paint_EyeDropper(me) ----------------------------------------------
  -- SENT BY the mouseDownScript the first time the user clicks after
  --         having clicked on this sprite.
  --
  -- * Restores and executes the original mouseDownScript, then allows
  --   the user to choose the current brush color for the Canvas
  --   behavior.
  --------------------------------------------------------------------
  
  if the mouseDownScript = pCallMeScript then
    -- The mouseDownScript was previously altered in order to call
    -- this handler: restore the original value.
    if stringP(pSaveScript) then
      the mouseDownScript = pSaveScript
    else
      -- This situation may arise at authortime due to a script error
      the mouseDownScript = ""
    end if
  end if
  
  -- Tell exitFrame() to track the color under the mouse
  pMouseDown = TRUE
end Paint_EyeDropper




-- PRIVATE METHODS --

on mInitialize(me) ----------------------------------------------------
  -- SENT BY beginSprite()
  -- ACTION: Creates a string to be used as the mouseDownScript if
  --         the user selects the eye dropper tool by clicking on
  --         this tool button.
  --------------------------------------------------------------------
  
  pCallMeScript = \
"sendSprite("&spriteNum&", #Paint_EyeDropper)"&RETURN&\
"stopEvent"
end mInitialize



on mShowBrushColor(me) ------------------------------------------------
  -- SENT BY exitFrame() while the user is dragging the Eyedropper
  --         tool
  -- ACTION: Tells myCanvasInstance to change its brush color, then 
  --         switches the Eyedropper tool off.
  --------------------------------------------------------------------
  
  tColor = me.mGetColorUnderMouse()
  
  if not tColor then
    exit
  end if
  
  sendAllSprites(#Paint_ShowBrushColor, tColor)
end mShowBrushColor



on mSetBrushColor(me) ------------------------------------------------
  -- SENT BY exitFrame() after the user releases the mouse button
  -- ACTION: Tells other Paint behaviors to change the brush color, 
  --         and switches the Eyedropper tool off.
  --------------------------------------------------------------------
  
  me.mDisactivateEyedropper()
  
  tColor = me.mGetColorUnderMouse()
  
  if not tColor then
    exit
  end if
  
  sendAllSprites(#Paint_SetBrushColor, tColor)
end mSetBrushColor



on mGetColorUnderMouse(me) -------------------------------------------
  -- SENT BY mouseUp()
  -- ACTION: Intercepts the mouseDownScript so that the next click
  --         will execute the Paint_EyeDropper() handler, regardless
  --         of where the click occurs
  --------------------------------------------------------------------
  
  tMouseColor = (the stage).image.getPixel(the mouseLoc)
  
  return tMouseColor
end mGetColorUnderMouse



on mActivateEyedropper(me) --------------------------------------------
  -- SENT BY mouseUp()
  -- ACTION: Intercepts the mouseDownScript so that the next click
  --         will execute the Paint_EyeDropper() handler, regardless
  --         of where the click occurs
  --------------------------------------------------------------------
  
  if  pActive then
    -- The Eyedropper is already activated 
    exit
  end if
  
  pSaveScript         = the mouseDownScript
  the mouseDownScript = pCallMeScript
  
  -- Use the Cursor Broker to set the cursor, if it is available
  pSaveCursor = sprite(0).cursor
  tResult = sendSprite(0, #SetCursor, #dropper, #lock)
  if voidP(tResult) then
    -- The Cursor Broker is not present: use built in cursor() command
    cursor 281 -- eye dropper
  end if
  
  pActive = TRUE
end mActivateEyedropper



on mDisactivateEyedropper(me) -----------------------------------------
  -- SENT BY mSetBrushColor(), mSetTabState(), endSprite()
  -- ACTION: Reverts the mouseDownScript and the cursor
  --------------------------------------------------------------------
  
  if not pActive then
    -- The Eyedropper is already disactivated 
    exit
  end if
  
  pActive    = FALSE
  pMouseDown = FALSE
  
  if stringP(pSaveScript) then
    the mouseDownScript = pSaveScript
  end if
  
  -- Use the Cursor Broker to restore the cursor, if it is available
  tResult = sendSprite(0, #SetCursor, 0, #lock)
  if voidP(tResult) then
    -- The Cursor Broker is not present: use built in cursor() command
    cursor pSaveCursor
  end if
end mDisactivateEyedropper



on mSetTabState(me) --------------------------------------------------
  -- SENT BY exitFrame()
  -- ACTION: Detects when the user is holding down the TAB key and if
  --         so, Intercepts the mouseDownScript so that the next click
  --         will execute the Paint_EyeDropper() handler, regardless
  --         of where the click occurs
  --------------------------------------------------------------------
  
  tTABPressed = keyPressed(TAB)
  
  if pTABPressed = tTABPressed then
    exit
  end if
  
  pTABPressed = tTABPressed
  if pTABPressed then
    if pActive then
      -- The Eyedropper is already active
      exit
    end if
    
    me.mActivateEyedropper()
    
  else
    me.mDisactivateEyedropper()
  end if
end toggleTabState




-- BEHAVIOR DESCRIPTION AND PARAMETERS --

on isOKToAttach(me, spriteType, spriteNumber)
  return (spriteType = #graphic)
end isOKToAttach



on getPropertyDescriptionList(me)
  tPropertyList = [:]
  
  tPropertyList[ \
#useTabShortcut] = [ \
 #comment: "Allow the TAB key to toggle Eyedropper tool?", \
 #format:  #boolean, \
 #default:  TRUE \
]  
  
  return tPropertyList
end getPropertyDescriptionList



on getBehaviorTooltip(me)
  return \
"Use with any graphic sprite which can act as a button." & RETURN & \
"Allows the user to select an eyedropper tool either by clicking " & \
"on the sprite or by pressing the Tab key.  The eyedropper tool " & \
"is used to modify the brush color used by the Paint behavior."
end getBehaviorTooltip



on getBehaviorDescription(me)
  return \
"SELECT EYEDROPPER" & RETURN & RETURN & \
"Use with any graphic sprite which can act as a button." & \
RETURN & RETURN & \
"Allows the user to select an eyedropper tool either by clicking " & \
"on the sprite or by pressing the Tab key.  The eyedropper tool " & \
"is used to modify the brush color used by the Paint behavior." & \
RETURN & RETURN & \
"When the user next presses the mouse button, the eyedropper " & \
"starts 'reading' the color of the pixel under the mouse.  If " & \
"the user holds the mouse button down and moves the mouse, the " & \
"color value will change depending on the graphic under the mouse." &\
RETURN & RETURN & \
"When the user releases the mouse button, the brush color used by " &\
"the Paint behavior is set to the value of the pixel under the " & \
"mouse." & RETURN & RETURN & \
"PARAMETER:" & RETURN & \
" * Use tab shortcut (TRUE | FALSE]" & RETURN & RETURN & \
"ASSOCIATED SCRIPTS:" & RETURN & \
" * Paint behavior" & RETURN & \
" * Show Brush Color behavior" & RETURN & \
" * Radio Button States behavior"
end getBehaviorDescription