'From etoys3.0 of 21 February 2008 [latest update: #1926] on 20 March 2008 at 2:51:18 am'!
"Change Set:		evtTheatreTransl-sw
Date:			20 March 2008
Author:			Scott Wallace

Addresses most issues in TRAC 6725.
Make many button labels and help messages involved in the Event Theatre and the Event Roll be set up for translatability.
Hide various development-related menu items when the new 'debugging' preference is false.
Brings the explanation about publishing alternatives up to date.
Provides a s;ummary of terms in the help-window for the event theatre.
"
!


!EventRecordingSpace methodsFor: 'access' stamp: 'sw 3/20/2008 02:49'!
helpString
	"Answer a help string for the Event Theatre."

	^ 'The Event Theatre provides a framework for authoring "event-movies".  It uses custom variants of the Navigator, the Supplies flap, the painting system, property sheets, Viewer flaps, etc., all of which reside within the controlled confines of the Theatre.

To author an event-movie, get a  new Event Theatre from the Objects catalog or from the "open..." branch of the desktop menu.

1. Resize the Theatre, using the halo, to the delivery size desired for playback.

2. Use the menu in the controls panel to add or delete Supplies and Navigator flaps as desired.

3. Edit the "caption" by clicking on the text that says "Untitled" and typing your desired caption.  This caption is affixed to playback buttons, and, generally, provides a way to identify the event-movie.

4. Set up the "initial conditions" for the event-movie you''re about to record (e.g., paint a background, provide some explanatory text, add objects you want to be present at the start of the movie.) When the recording is first opened by the user for playback, and whenever the recording has been rewound, this is exactly what it will look like.

5. When ready to start the recording, press the "Record" button. A red border will be seen around the recorder, to indicate that recording is in progress.  Recording will continue until you hit the ESC key.

6. Note that if you  want to include sound in your recording, you can add it directly during playback, or you can produce voiceover externally and add it in later using the Event Roll.

7. Now proceed to "do", with the mouse and keyboard, whatever you wish to record.   For best results, all mouse gestures should be made within the interior of the Theatre.

8. Hit ESC when done recording.

9. To review what you''ve recorded, press "Play". If unhappy with the result, repeat steps 1-8.

10.  If you''re happy with the result, and now wish to add a sound, open the sound panel, then click Play to replay the recording, and whenever you wish to add a snippet of voiceover, click on the "Start Recording Voiceover" button, and start talking, and when done with that snippet click the "Stop Recording Voiceover" button.  Once the playback finishes, the added voiceover(s) will become part of the event tape, and will be seen in the event roll.

11. When you''re happy with the result, hit the "Publish" button, to get a playback button. There are currently two choices:

a. Iconic Button - Initially provides a picture of the initial scene of the movie, scaled 0.3x, and overlaid with the word HINT.  When the user clicks on such a button, the event-movie is played back in an ephemeral "playback theatre", and after the playback is done, the playback theatre shrinks down to a 0.5x scale-downed picture of the *final* scene of the movie.  Subsequent hitting of the button will again invoke a playback.

b. Textual Button - a simple labeled button which, when pressed, triggers playback of the event tape.

12. The playback buttons you obtain when you "Publish" can be placed anywhere, such as on the page of a book. You can control, via a playback-button''s halo menu, whether or not it should be "auto-start", and whether or not "auto-dismiss". When the user presses the button, a "Playback" space will open, which resembles an Event Theatre, but has only playback-relevant controls.   A playback set up for both auto-start and auto-dismiss comes without any controls.

13.  To edit the "event tape" of a recording you have made in an Event Theatre, and for a generally good time, click on the interlocking-circles icon to obtain a tool that allows you to visualize and to edit a "score" or "piano roll" of the event tape.


Summary of terms

Event Theatre
  The main tool for creating an Event Tape.

Event Roll
  An auxiliary tool showing the full "score" of an Event Tape. 

Event Tape
  The results of an event-theatre session;  an interaction sequence that can be played back.

Event Recording
  A term interchangeable with "Event Tape."

Event Movie
  What you see when you play back an Event Tape.

' translated! !

!EventRecordingSpace methodsFor: 'initialization' stamp: 'sw 3/20/2008 02:19'!
makeStatusButtons
	"Build, but do not insert, the buttons that control"

	publishButton := self buttonWithLabel: 'Publish' actionSelector: #publishButtonHit balloonText: 'When you hit this, you will be handed a button which, when it is clicked,  will open up an Event Player in which the recording can be played back.' translated.

	abandonButton := self tanOButton.
	abandonButton actionSelector: #abandon.
	abandonButton  setBalloonText: 'Abandon this effort and throw away this window' translated.

	recordButton := self buttonWithLabel: 'Record' translated actionSelector: #record balloonText: 'Start Recording' translated.

	menuButton := self menuButton.
	"self buttonWithLabel: 'Options' translated actionSelector: #offerMenu balloonText: 'Offers a menu of options'."

	scriptButton :=  IconicButton new target: self;
		borderWidth: 0;
		labelGraphic: (ScriptingSystem formAtKey: #Script);
		color: Color transparent; 
		actWhen: #buttonUp;
		actionSelector: #makeHorizontalRoll;
		setBalloonText: 'show this theatre''s script in a piano-roll-like format for visualizaitoin and editing.' translated;
		yourself.

	recordAgainButton := self buttonWithLabel: 'Record Again' translated actionSelector: #recordAgain balloonText: 'Abandon existing recording and start a new one.' translated.

	recordVoiceoverButton := self buttonWithLabel: 'Start Recording Voiceover' translated actionSelector: #recordVoiceover balloonText: 'Add a voiceover to the existing event-recorded sequence ' translated.

	stopRecordingVoiceoverButton := self buttonWithLabel: 'Stop Record Voiceover' translated actionSelector: #stopRecordingVoiceover balloonText: nil  " 'Stop the recording of the voiceover segment currently being recorded' translated ".

	playButton := self buttonWithLabel: 'Play' translated actionSelector: #play balloonText: 'Replay this sequence' translated.

	rewindButton := self buttonWithLabel: 'Rewind' translated actionSelector: #rewind balloonText: 'Reset to the starting condition for this recording' translated.

	stopButton := self buttonWithLabel: 'Stop' translated actionSelector: #stopPlayback balloonText: 'Stop playing or recording this panel' translated.

	pauseButton := self buttonWithLabel: 'Pause' translated actionSelector: #pausePlayback balloonText: 'Temporarily pause this playback' translated.

	resumeButton := self buttonWithLabel: 'Resume' translated actionSelector: #resumePlayback balloonText: 'Resume playback' translated.

	captionMorph := UpdatingStringMorph contents: self captionString font: ScriptingSystem fontForTiles.
	captionMorph useStringFormat.
	captionMorph target: self.
	captionMorph getSelector: #captionString; putSelector: #captionString:; growable: true; minimumWidth: 48.

	showingSoundButton := UpdatingThreePhaseButtonMorph blackTriangularOpener.
	showingSoundButton
		target: self;
		actionSelector: #toggleShowingSoundPanel;
		getSelector: #notShowingSoundPanel.
	showingSoundButton setBalloonText: 'show/hide voice controls' translated



! !

!EventRecordingSpace methodsFor: 'menu' stamp: 'sw 3/20/2008 01:45'!
addMenuButtonItemsTo: aMenu
	"Build the contents of the menu to be presented when the menu button in my tool-bar is clicked."

	"CAUTION:  Debugging items still present."

	aMenu addTitle: 'Recording Options'.

	aMenu addTranslatedList: #(
		('set balloon help'		setBalloonHelp  'Allows you to provide a message to be presented to a user as balloon-help when the mouse lingers over buttons that trigger playback of the tape of this event theatre')
		('shrink event tape' shrinkTape)
		"('save on file...' saveSequenceOnFile)"
		-
		('revert to version...'	offerVersions)
		('delete old versions'	deleteOldVersions)
		-) translatedNoop.

	Preferences sugarNavigator
		ifTrue:
			[aMenu addTranslatedList: (self sugarNavigatorFlapOrNil
				ifNil: [#(('add sugar navigator flap' addSugarNavigatorFlap)) translatedNoop]
				ifNotNil: [#(('remove sugar navigatorFlap' removeSugarNavigatorFlap)) translatedNoop])]
		ifFalse:
			[aMenu addTranslatedList: (self navigatorFlapOrNil
				ifNil: [#(('add navigator flap' addNavigatorFlap)) translatedNoop]
				ifNotNil: [#(('remove navigatorFlap' removeNavigatorFlap)) translatedNoop]).

			aMenu addTranslatedList: (self suppliesFlapOrNil
				ifNil: [#(('add supplies flap' addSuppliesFlap)) translatedNoop]
				ifNotNil: [#(('remove suppliesFlap' removeSuppliesFlap)) translatedNoop])].

	aMenu addTranslatedList: #(
		-
		('event roll' makeHorizontalRoll 'open a horizontal piano-roll-like tool for the viewing and editing the events of this event theatre.')
		('remove event-roll' removeEventRoll  'abandon any event-roll that may be associated with this theatre.')
		-) translatedNoop.

	Preferences debugging ifTrue:
		[self addMoreSubMenuTo: aMenu]! !

!EventRecordingSpace methodsFor: 'processing' stamp: 'sw 3/19/2008 18:48'!
populateControlsPanel
	"Build the things that need to be in the controls panel."

	| neverRecorded aMorph existing |
	scriptButton ifNil: [self makeStatusButtons].

	existing := contentArea topLeft.
	controlsPanel removeAllMorphs.
	soundPanel removeAllMorphs.
	soundPanel addVariableTransparentSpacer.
	self populateSoundPanel.

	(#(recording recordingWithSound) includes: self state) ifTrue:
		[controlsPanel  addVariableTransparentSpacer.
		 aMorph := StringMorph contents: 'Hit ESC to stop recording' translated font: (StrikeFont familyName:  'Accujen' size: 24).
		self addControlWithSpacer: aMorph.
		^ self assureContentAreaStaysAt:  existing].

	(#(playback playbackAddingVoiceover) includes: self state) ifTrue:
		[self addControlWithSpacer: captionMorph lock.
		self addControlWithSpacer:  pauseButton.
		self addControlWithSpacer: stopButton.
		 ^ self assureContentAreaStaysAt: existing].

	controlsPanel  addTransparentSpacerOfSize: 6@0.
	controlsPanel addMorphBack: abandonButton.
	controlsPanel addTransparentSpacerOfSize: 12@0.
	controlsPanel addMorphBack: self helpButton.
	controlsPanel addTransparentSpacerOfSize: 12@0.
	controlsPanel addMorphBack: menuButton.

	controlsPanel  addVariableTransparentSpacer.
	neverRecorded := state = #readyToRecord.
	neverRecorded ifFalse:
		[self addControlWithSpacer: publishButton.
		self addControlWithSpacer: scriptButton].

	self addControlWithSpacer: captionMorph unlock.

	neverRecorded
		ifTrue:
			[self addControlWithSpacer: recordButton]
		ifFalse:
			[self addControlWithSpacer: recordAgainButton].


	state = #playback ifTrue: [self addControlWithSpacer: stopButton].
	state == #suspendedPlayback ifTrue:
		[self addControlWithSpacer: resumeButton].

	neverRecorded ifFalse: [self addControlWithSpacer: rewindButton].

	(#(rewound atEndOfPlayback) includes: self state) ifTrue:
		[self addControlWithSpacer: playButton].
	controlsPanel addVariableTransparentSpacer.
	controlsPanel addMorphBack: showingSoundButton.
	controlsPanel addTransparentSpacerOfSize: 6@0.
	self assureContentAreaStaysAt:  existing
! !


!EventPlaybackSpace methodsFor: 'menu' stamp: 'sw 3/20/2008 01:49'!
addMenuButtonItemsTo: aMenu
	"Subclasses wishing to partake of generic menuButton support should reimplement this, and *not* call super ;-)"

	aMenu addTranslatedList: #(
		('rewind'				rewind)
		('play again'			play)) translatedNoop.
	Preferences debugging ifTrue:
		[aMenu addTranslatedList: #(
		-
		('inspect' inspect)
		-
		('edit this menu' editMenuButtonDefinition)) translatedNoop]! !


!EventRecordingSpace class methodsFor: 'parts bin' stamp: 'sw 3/20/2008 00:04'!
descriptionForPartsBin
	"Answer a description for use in a parts bin."

	^ self partName:	'Event Theatre' translatedNoop
		categories:		{'Multimedia' translatedNoop}
		documentation:	'A framework for creating tutorial snippets' translatedNoop! !


!EventRollMorph methodsFor: 'display' stamp: 'sw 3/20/2008 02:00'!
addMenuButtonItemsTo: aMenu
	"Add menu items to the menu obtained by clicking on the menu icon"

	"CAUTION:  Debugging items still present."

	aMenu addTitle: 'Event-Roll Options' translated.

	aMenu addTranslatedList: #(
		('revert to version...'  offerVersions 'allows you to back up to any earlier version of the event tape.') ) translatedNoop.

	Preferences debugging ifTrue:
		[aMenu addTranslatedList: #(
		-

	"	('change scale...' changeScale   'allows you to supply a precise scale-factor manualliy.')
		('retrofit to event-theatre' pushChangesBackToEventTheatre  'normally not necessary, but if you suspect that edits you have made in this event roll have not been fully appreciated by the event theatre, choose this to force the event theatre to reflect what you see in the event roll.' )
		-
		('restore original event theatre'	restoreOriginalEventTheatre  'Restore the event theatre, and hence this event roll, to how they were when you first made this roll.')
		-"
		('inspect event roll' inspect  'debugging -- open an Inspector on this event roll')
		('update cursor' updateCursorFromRecordingSpace 'debugging -- update the red roll cursor')
		('update scrollbar' updateScrollbar  'debugging -- update the scrollbar')
		-
		('edit this menu' editMenuButtonDefinition 'debugging -- change the definition of this menu.')) translatedNoop]! !

!EventRollMorph methodsFor: 'processing' stamp: 'sw 3/20/2008 02:16'!
makeControlsPanel
	"One-time initialization.  Upon entry, the receiver has no submorphs; upon exit, it has one, namely its controlsPanel, which contains the scale slider, the track headings, and the control buttons."

	| topWrapper labelWrapper aMorph aPanel |
	aPanel := AlignmentMorph newColumn beTransparent.
	aPanel hResizing: #shrinkWrap; vResizing: #shrinkWrap.

	topWrapper := AlignmentMorph newRow beTransparent.
	topWrapper hResizing: #spaceFill; vResizing: #shirnkWrap.
	topWrapper rubberBandCells: true.

	labelWrapper := AlignmentMorph newColumn beTransparent.
	labelWrapper addTransparentSpacerOfSize: 0@4.
	#('mouse' 'keyboard' 'media') do:
		[:aString |
			aMorph := Morph new extent: 80@ 20.
			aMorph hResizing: #rigid; vResizing: #rigid.
			aMorph beTransparent.
			aMorph addMorphCentered: (StringMorph contents: aString translated font: (StrikeFont familyName: 'Accujen' size: 24)).
			labelWrapper addMorphBack: aMorph.
			labelWrapper addTransparentSpacerOfSize: 0@20].
	labelWrapper submorphs last delete.  "that last spacer"
	topWrapper addMorphBack:  labelWrapper.
	labelWrapper on: #mouseDown send: #grabMorph: to: self.

	topWrapper addMorphBack: self scaleSlider.

	aPanel addMorphBack: topWrapper.
	aPanel addMorphBack: self makeButtonsPanel.
	self addMorph: aPanel! !

"Postscript:"
Preferences addPreference: #debugging category: 'debug' default: false balloonHelp: 'if true, menu items intended for debugging use only are omitted from menus.'
!