-- GO MARKER BUTTON --
-- 
-- © July 2000, James Newton <newton@planetb.fr> 



-- PROPERTY DECLARATIONS --

-- author-defined parameters:
property markerName -- #previous|#loop|#next|name of marker to jump to
property jumpMode   -- "Go to" | "Play and return"



-- EVENT HANDLERS --

on beginSprite(me)
  call(#checkMarkerName, [me])
end beginSprite



on mouseUp(me)
  me.jump()
end prepareFrame




-- PRIVATE METHODS --

on jump(me) ---------------------------------------------------------
  -- sent by mouseUp()
  --
  -- * Jumps the playback head to the chosen marker... if it exists
  -------------------------------------------------------------------
  
  -- Determine which frame is indicated by markerName
  case markerName of
    #previous: frameNumber = marker(-1)
    #loop:     frameNumber = marker(0)
    #next:     frameNumber = marker(1)
    otherwise:
      frameNumber = marker(markerName)
  end case
  
  if frameNumber then
    if jumpMode = "Go to" then
      go frameNumber
    else -- play => play done
      play frameNumber
    end if
  else
    -- markerName no longer exists
  end if
end jump




-- < ERROR DETECTION (OPTIONAL HANDLERS) > --

-- This section is only useful for troubleshooting.  It contains no
-- code that is essential for the behavior.  You can delete this 
-- section if you wish.  The behavior will continue to function
-- correctly.
--
-- All calls to the these handlers use the following syntax:
--
--   call(#handler, [me], {parameters})
--
-- No error will occur if one of these handlers is not present.
-- (See the entry for "call" in the Lingo Dictionary for details).


on getDuplicateMarkersList(me, duplicatesList) -----------------------
  -- Sent by getPropertyDescriptionList()
  --
  -- * Returns a list of all the duplicate marker names in the movie.
  --   Duplicate detection is done using string comparisons, so that
  --   names which differ only by case will be treated as identical.
  --------------------------------------------------------------------
  
  markerString    = RETURN&the labelList
  
  markerCount =  markerString.line.count - 1
  repeat with i = 2 to markerCount
    theMarker = markerString.line[2]
    delete markerString.line[2]
    if offset(RETURN&theMarker&RETURN, markerString) then
      -- Duplicate marker name
      if not duplicatesList.getPos(theMarker) then
        duplicatesList.append(theMarker)
      end if
    end if
  end repeat
  
  return duplicatesList
end getDuplicateMarkersList



on checkMarkerName(me) -----------------------------------------------
  -- Sent by beginSprite()
  --
  -- * Checks if markerName is still valid: it should exist and be
  --   unique.  If not, an authortime-only alert will appear.  The
  --   movie will continue to function, but the behavior may not work
  --   as expected.
  --------------------------------------------------------------------
  
  if not [#next, #previous, #loop].getPos(markerName) then
    -- Does markerName still exist?
    theMarkerList = RETURN&the labelList
    markerExists = offset(RETURN&markerName&RETURN, theMarkerList)
    if not markerExists then
      call(#errorAlert, [me], #markerMissing, markerName)
    else
      -- Is markerName still unique?
      delete char 1 to markerExists of theMarkerList
      if offset(RETURN&markerName&RETURN, theMarkerList) then
        call(#errorAlert, [me], #runtime_DuplicateMarkers, markerName)
      end if
    end if
  end if
end checkMarkerName



property alertFlag

on errorAlert(me, theError, data) ------------------------------------
  -- Send by getPropertyDescriptionList, checkMarkerName()
  --
  -- * Displays an authortime-only alert to help the author deal
  --   troubleshoot the movie
  --------------------------------------------------------------------
  
  -- Determine the behavior's name
  behaviorName = string(me)
  delete word 1 of behaviorName
  behaviorName = value(behaviorName)
  
  -- Convert #data to useful value
  case data.ilk of
    #void: data = "<void>"
    #symbol: data = "#"&data
  end case
  
  case theError of
    #duplicateMarkers:
      if (the ticks - alertFlag > 2) then
        alert \
"Two or more markers in this movie have the same name."&RETURN&\
"This could lead to confusion if you use this behavior to go to a "&\
"named marker."&RETURN&RETURN&\
"Duplicate marker(s) = "&data
        alertflag = the ticks
      end if
      
    #markerMissing:
      if the runMode = "Author" then
        alert \
"BEHAVIOR ERROR: Frame "&the frame&", Sprite "&me.spriteNum&RETURN&\
"Behavior "&behaviorName&RETURN&RETURN&\
"The chosen marker no longer exists.  Choose a valid marker in the "&\
"Behavior Parmeters dialog."&RETURN&RETURN&\
"Current marker = "&data
      end if
      
    #runtime_DuplicateMarkers:
      if the runMode = "Author" then
        alert \
"BEHAVIOR ERROR: Frame "&the frame&", Sprite "&me.spriteNum&RETURN&\
"Behavior "&behaviorName&RETURN&RETURN&\
"The chosen marker does not have a unique name."&RETURN&\
"The playback head will jump to the first marker with this name:"&\
RETURN&RETURN&\
"Duplicate marker name = "&data
      end if
  end case
end errorAlert

-- < END OF OPTIONAL HANDLERS > --




-- BEHAVIOR DESCRIPTION AND PARAMETERS --

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



on getPropertyDescriptionList(me)
  -- Check if there are any duplicate marker names (optional code) 
  if the currentSpriteNum then
    duplicateMarkersList = []
    call(#getDuplicateMarkersList, [me], duplicateMarkersList)
    if duplicateMarkersList.count() then
      call(#errorAlert, [me], #duplicateMarkers, duplicateMarkersList)
    end if
  end if
  -- (End of optional code)
  
  propertiesList = [:]
  propertiesList[ \
#markerName] = [ \
 #comment: "On mouseUp, go to marker:", \
 #format:  #marker, \
 #default: #next \
]
  propertiesList[ \
#jumpMode] = [ \
 #comment: "Jump mode:", \
 #format:  #string, \
 #range:  ["Go to", "Play and Return"], \
 #default: "Go to" \
]
  return propertiesList
end getPropertyDescriptionList



on getBehaviorTooltip
  return \
"Use with graphic members."&RETURN&RETURN&\
"When you drop this behavior on a sprite,"&RETURN&\
"you will be invited to choose which marker"&RETURN&\
"in the current movie to jump to on mouseUp."&RETURN&\
"You can also choose 'previous' or 'next'."&RETURN&RETURN&\
"Use this behavior with the 'History Button'"&RETURN&\
"to allow the user to return to visited"&RETURN&\
"sequences."
end getBehaviorTooltip



on getBehaviorDescription
  return \
"GO MARKER BUTTON"&RETURN&RETURN&\
"© July 2000, James Newton <newton@planetb.fr>"&RETURN&RETURN&\
"A click on the sprite makes the playback head jump to a chosen "&\
"marker in the same movie.  (Use the 'Go Movie Button' behavior to "&\
"jump to a marker in a different movie). You can choose between:"&\
RETURN&\
" -> previous marker"&RETURN&\
" -> next marker"&RETURN&\
" -> any named marker in the movie"&RETURN&RETURN&\
"If more than one marker has the same name as the chosen marker, "&\
"the playback head will jump to the first marker with that name in "&\
"the movie.  If you need to use duplicate names, try adding a "&\
"different number of spaces at the end of each, so that they "&\
"appear the same but are in fact different."&RETURN&RETURN&\
"In order to make use of the Play and Return option, place a "&\
"Play Done command in the destination movie.  If you do not do "&\
"this, your movie will use more memory than is necessary."&\
RETURN&RETURN&\
"PERMITTED MEMBER TYPES"&RETURN&"Graphic members"&RETURN&RETURN&\
"PARAMETERS:"&RETURN&\
" * Jump to marker in this movie"&RETURN&\
" * 'Go to' or 'Play and return'?"&RETURN&\
"ASSOCIATED BEHAVIORS:"&RETURN&\
"+ Go Movie button"&RETURN&\
"+ History Button"&RETURN&\
"+ Resume Button"&RETURN&\
"+ Mouse States (to alter rollover / mouseDown states)"
end getBehaviorDescription