tutorial "To Do List"

prologue
	In this tutorial we will create a simple To Do List.

	The finished app can be built into a self-contained app that can be shared
	with anyone, even if they don't have LiveCode.
image
	ToDoListScreenshot.png
end prologue

step "Tutorial Intro I"
	In creating this app you will learn:

	- How to build the User Interface(UI) of an app by dragging and dropping objects

	- The basics of coding in LiveCode to add user interactivity to your app

	- How to use the features of the LiveCode Integrated Development Environment (IDE)

	- How to build your app as a self contained application. In LiveCode we call this a standalone.
action
	interlude
	go to step "Tutorials Intro"
end step

step "Tutorials Intro"
	You can keep track of how much of the tutorial you have completed
	with this progress bar, and exit the tutorial at any time by
	clicking on the stop button.

	Clicking the fast-forward button will skip to the next important
	concept being introduced in the tutorial. Use this if you've got the
	idea about something and don't want to have to create every last
	part of the user interface, for example.

	The tutorial will also help you out by disabling the parts of the IDE you
	don't need for the current step.
action
	interlude
	highlight toolbar "tutorial"
	go to step "Stack Interlude"
end step

skip point

step "Stack Interlude"
	In this first section of the tutorial, we will create the User
	Interface (UI) for the To Do List app.

	The first step in creating a LiveCode application is creating a
	stack. A stack is the canvas for your app. Every window you see in LiveCode
	is a stack.

	In this tutorial we will create our stack at iPhone 5 size.
action
	interlude
	go to step "Create Mainstack"
end step

step "Create Mainstack"
	Click on the File menu, and select 'New Stack' → 'iPhone 5 (320x568)'.
action
    highlight menu item "iPhone 5 (320x568)" of menu item "New Stack" of menu "File"
    capture the next new stack as "Mainstack"
    capture the next new card of stack "Mainstack" as "ToDoList"
    wait until there is a stack "Mainstack"
	go to step "Set Stack Rect"
end step

step "Set Stack Rect"
	Resize the stack so that it has width 320 and height 568.
action
	add guide "Stack" with rect "0,0,320,568" to stack "Mainstack"
	highlight guide "Stack"
	wait until stack "Mainstack" fits guide "Stack" with tolerance 5
	go to step "Properties interlude"
end step

step "Properties interlude"
	Every object in LiveCode has a set of properties associated with it. These
	properties control the appearance, location and behavior of the objects
	in your app.

	The Property Inspector is a window that allows you to control these properties.
action
	interlude
	go to step "Select Stack For Inspector"
end step

step "Select Stack For Inspector"
	Ensure this is the active stack, by clicking on it.
action
	highlight stack "Mainstack"
	wait until stack "Mainstack" is selected
	go to step "Set Stack Properties"
end step

step "Set Stack Properties"
	Click on the Inspector icon on the Toolbar to open the Property
	Inspector.
action
	highlight toolbar "Inspector"
	wait until there is an inspector for stack "Mainstack"
	go to step "Property Inspector Interlude"
end step

step "Property Inspector Interlude"
	Properties of objects are grouped into sections. You can hover over
	the icons at the top of the Property Inspector to see what each section is
	called.
action
	interlude
	highlight inspector for stack "Mainstack"
	go to step "Set Stack Title"
end step

skip point

step "Set Stack Title"
	The first property we will set is the 'Title' of the stack. You will see the
	title of the stack change after you set the property.

	Set the 'Title' of the stack to "To Do List" and press the 
	<Return> key.
action
	highlight property "title" of section "basic"
	wait until the title of stack "Mainstack" is "To Do List"
	go to step "Tools Palette Interlude"
end step

skip point

step "Tools Palette Interlude"
	The next step is to add some objects to your stack.

	This is the Tools Palette. It contains all the built-in objects that
	you can drag out onto your stack, such as buttons, text fields and
	scrollbars. It also contains more complex controls including a header bar,
	navigation bar, browser and line graph.
action
	interlude
	highlight tools
	go to step "Create Add Icon"
end step

step "Create Add Icon"
	The first object we will add is an 'add' icon. The user will click on this to
	add a new item to the list.

	Drag an SVG Icon from the Tools Palette onto your stack.
action
	highlight tool "Create com.livecode.widget.svgpath"
	capture the next new widget of stack "Mainstack" as "add"
	wait until there is a widget "add"
	go to step "Select SVG Icon 1"
end step

step "Select SVG Icon 1"
	Select the SVG Icon by clicking on it.

	The selection handles will show around the icon.
action
	highlight widget "add"
	wait until widget "add" is selected
	go to step "Set Add Location"
end step

step "Set Add Location"
	Resize and position the icon, as shown.
action
	add guide "addLoc" with rect "280,10,310,40" to stack "Mainstack"
	highlight guide "addLoc"
	wait until widget "add" fits guide "addLoc" with tolerance 5
	go to step "Select SVG Icon For Inspector"
end step

step "Select SVG Icon For Inspector"
	Select the SVG Icon by clicking on it.

	The selection handles will show around the icon.
action
	highlight widget "add"
	wait until widget "add" is selected
	go to step "Open Property Inspector"
end step

step "Open Property Inspector"
	Next we need to set some properties of the icon.

	Click on the Inspector icon in the Toolbar to open the Property Inspector for the
	icon.
action
	highlight toolbar "Inspector"
	wait until there is an inspector for widget "add"
	go to step "Set add name"
end step

step "Set add name"
	The 'Name' property is used when we refer to an object in the code. We want to
	use short, unique, descriptive names to make it easier when we start writing
	code.

	Set the name property of the SVG Icon to "Add" and press the 
	<Return> key.
action
	highlight property "name" of section "Basic"
	wait until the name of widget "add" is "Add"
	go to step "Set add icon"
end step

step "Set add icon"
	The 'Preset' property of SVG icon lets you choose the icon you want to show,
	in this case we want a '+' symbol.

	Click on the 'Preset' property where it shows a star. This will pop up a
	set of icons for you to choose from. Choose the plus icon, its name in the
	list is 'plus'. You might need to scroll the list of icons to find the one you want.
action
	highlight property "iconPresetName" of section "Basic"
	wait until the iconPresetName of widget "add" is "plus"
	go to step "Create task list"
end step

skip point

step "Create task list"
	Next we want to add a list field. This will be used to display the list of tasks.

	Drag a list field from the Tools Palette onto your stack.
action
	highlight tool "Create list field"
	capture the next new field of stack "Mainstack" as "TaskList"
	wait until there is a field "TaskList"
	go to step "Select Field 1"
end step

step "Select Field 1"
	Select the field by clicking on it.

	The selection handles will show around the field.
action
	highlight field "TaskList"
	wait until field "TaskList" is selected
	go to step "Set task list Location"
end step

step "Set task list Location"
	Resize and position the field, as shown.
action
	add guide "taskListLoc" with rect "0,60,320,568" to stack "Mainstack"
	highlight guide "taskListLoc"
	wait until field "taskList" fits guide "taskListLoc" with tolerance 5
	go to step "Select Field For Inspector"
end step

step "Select Field For Inspector"
	Select the field by clicking on it.

	The selection handles will show around the field.
action
	highlight field "TaskList"
	wait until field "TaskList" is selected
	go to step "Task List PI"
end step

step "Task List PI"
	As before we need to set some properties of the field.

	Click on the Inspector icon in the Toolbar to open the Property Inspector for the
	field.
action
	highlight toolbar "Inspector"
	wait until there is an inspector for field "taskList"
	go to step "Set task list name"
end step

step "Set task list name"
	Again, we want to give the field a short descriptive name to make things
	easier when we write code.

	Set the name of the field to "TaskList" and press the <Return> key.
action
	highlight property "name" of section "Basic"
	wait until the name of field "taskList" is "TaskList"
	go to step "Set task list contents"
end step

skip point

step "Set task list contents"
	We want the task list to start off empty. Delete the default contents from
	the field and click away to allow the change to take effect.
action
	highlight property "styledText" of section "contents"
	wait until the text of field "taskList" is ""
	go to step "Events and messages interlude"
end step

skip point

step "Events and messages interlude"
	Now that the first part of the UI is complete the next stage is to add code to the app
	to allow the user to interact with it.

	LiveCode apps work by responding to 'messages', which are usually triggered by
	some kind of user action. A message might tell the app that the user has
	clicked on a button or typed in a field. You add code to tell the app what
	to do when a message is received.

	Each object has its own individual code, so different buttons can respond to
	messages in different ways.
action
	interlude
	go to step "Select SVG Icon For Editor"
end step

step "Select SVG Icon For Editor"
	Select the SVG Icon by clicking on it.

	The selection handles will show around the icon.
action
	highlight widget "add"
	wait until widget "add" is selected
	go to step "Open Add Script"
end step

step "Open Add Script"
	Select the Add icon then click the Code button in the Toolbar.
action
	highlight toolbar "Code"
	wait until there is a script editor for widget "add"
	go to step "Script Editor Interlude"
end step

step "Script Editor Interlude"
	The Script Editor is a window that allows you to add code to the
	objects on your stack.

	The code you have added in the Script Editor does not become live
	until you click on the 'Apply' button. When this is clicked, you will
	get feedback about whether the code you have written has any
	errors in it or not.
action
	interlude
	highlight "Apply" of script editor for widget "header"
	go to step "mouseUp message"
end step

skip point

step "mouseUp message"
	The message we will respond to is 'mouseUp'. This message is sent when the
	user clicks on the Add icon.

	We will add code to add a new task to the list. When the user clicks
	the 'add' icon the app asks the user to enter a task and adds it to the
	bottom of the list.

	Add this handler to the script of 'add' icon.

	Don't forget to click the 'Apply' button when you have finished.
script
	on mouseUp
			ask "Please enter a task"

			if field "TaskList" is empty then
				put it into field "TaskList"
			else
				put return & it after field "TaskList"
			end if
	end mouseUp
action
	highlight script editor for widget "add"
	wait until widget "add" is scripted
	go to step "Explain ask"
end step

step "Explain ask"
	The ask command displays a dialog box with a prompt, a text box for the user
	to enter a response, and OK and Cancel buttons.

	You use the ask command when you need to get information from the user before
	continuing.
action
	interlude
	highlight line "ask" of script editor for widget "add"
	go to step "Edit Tool Interlude""
end step

skip point

step "Edit Tool Interlude"
	LiveCode has two modes: Edit mode and Run mode.

	Up until now you have been in Edit mode all the time. In Edit mode
	you can add, edit and move objects on your stack. You can also select objects
	to change their properties or add code to them.
action
	interlude
	highlight tool "Edit Mode"
	go to step "Run Tool Interlude"
end step

step "Run Tool Interlude"
	In Run mode your app is live - objects will behave as they would for
	the app user. For example, clicking on the 'Add' button will allow you to add
	a task to the list.

	To test the code you have just added, we are going to enter Run mode and try
	adding a task to the list.
action
		interlude
    highlight tool "Run Mode"
	  go to step "Test Task List"
end step

step "Test Task List"
	Select 'Run mode' in the Tools Palette.
action
    highlight tool "Run Mode"
    wait until the tool is run
	  go to step "Add task"
end step

skip point

step "Add task"
	Click the 'Add' icon and enter a task, it will appear at the bottom of the list.
action
	highlight widget "add"
	wait until the text of field "taskList" is changed with default "Buy milk"
	go to step "Return to Edit Mode"
end step

skip point

step "Return to Edit Mode"
	Change back to Edit mode to continue working on the app.
action
	highlight tool "Edit Mode"
	wait until the tool is edit
	go to step "Delete action interlude"
end step

step "Delete action interlude"
	As well as adding tasks to the list the user will also want to delete tasks
	when they are complete.

	We will add a 'Delete' option next to 'Add' to allow the user to delete a task
	from the list.
action
	interlude
	go to step "Create delete icon"
end step

step "Create delete Icon"
	To create the 'Delete' icon drag another SVG Icon from the Tools Palette onto your stack.
action
	highlight tool "Create com.livecode.widget.svgpath"
	capture the next new widget of stack "Mainstack" as "delete"
	wait until there is a widget "delete"
	go to step "Select SVG Icon 2"
end step

step "Select SVG Icon 2"
	Select the icon by clicking on it.

	The selection handles will show around the icon.
action
	highlight widget "delete"
	wait until widget "delete" is selected
	go to step "Set Delete Location"
end step

step "Set Delete Location"
	Resize and position the icon, as shown.
action
	add guide "deleteLoc" with rect "240,10,270,40" to stack "Mainstack"
	highlight guide "deleteLoc"
	wait until widget "delete" fits guide "deleteLoc" with tolerance 5
	go to step "Select Delete For Inspector"
end step

step "Select Delete For Inspector"
	Select the icon by clicking on it.

	The selection handles will show around the icon.
action
	highlight widget "delete"
	wait until widget "delete" is selected
	go to step "Open Delete Property Inspector"
end step

step "Open Delete Property Inspector"
	Next we need to set the properties of the 'Delete' icon.

	Click on the Inspector icon on the Toolbar to open the Property Inspector for the
	SVG icon.
action
	highlight toolbar "Inspector"
	wait until there is an inspector for widget "delete"
	go to step "Set delete name"
end step

step "Set delete name"
	Set the name property of the SVG Icon to "Delete" and press the 
	<Return> key.
action
	highlight property "name" of section "Basic"
	wait until the name of widget "delete" is "Delete"
	go to step "Set delete icon"
end step

step "Set delete icon"
	Next we will set the image to be shown for the 'Delete' icon.

	Click on the 'Preset' property and choose the trash bin icon, its name in the
	list is 'trash'.
action
	highlight property "iconPresetName" of section "Basic"
	wait until the iconPresetName of widget "delete" is "trash"
	go to step "Select Delete For Editor"
end step

step "Select Delete For Editor"
	Select the icon by clicking on it.

	The selection handles will show around the icon.
action
	highlight widget "delete"
	wait until widget "delete" is selected
	go to step "Open Delete script"
end step

step "Open Delete Script"
	Select the 'Delete' icon then click the Code icon in the Toolbar to open the Script Editor for the icon.
action
	highlight toolbar "Code"
	wait until there is a script editor for widget "delete"
	go to step "Delete mouseUp"
end step

step "Delete mouseUp"
	Just like for the 'Add' icon the 'Delete' icon will respond to the 
	'mouseUp' message.

	When the user clicks on the 'Delete' icon the task that is selected 
	in the list will be deleted. We will confirm the deletion with the 
	user before deleting the task.

	Add this handler to the script of the 'Delete' icon.

	Don't forget to click the 'Apply' button when you have added the code.
script
	on mouseUp

		answer "Do you want to delete this task?" with "Yes" and "No"

		if it is "Yes" then
		 	delete line (the hilitedLine of field "TaskList") of field "TaskList"
		end if
	end mouseUp
action
	highlight script editor for widget "delete"
	wait until widget "delete" is scripted
	go to step "Run mode 2"
end step

step "Run mode 2"
	To test the code you have just added enter Run mode and delete the first
	task by selecting the line in the list and clicking on the 'Delete' icon.

	Start by entering Run mode.
action
    highlight tool "Run Mode"
		wait until the tool is run
	  go to step "Test Delete Task"
end step

step "Test Delete Task"
	Select the first task and click the 'Delete' icon. Answer 'Yes' when 
	presented with the delete options.

	The task will be deleted from the list.
action
	highlight widget "delete"
	wait until the text of field "taskList" is changed with default ""
	go to step "Return to Edit Mode 2"
end step

step "Return to Edit Mode 2"
	Change back to 'Edit' mode to continue working on the app.
action
	highlight tool "Edit Mode"
	wait until the tool is edit
	go to step "Saving Data Interlude"
end step

step "Saving Data Interlude"
	Once you have built your app into a standalone it can't be changed, 
	so any data that should persist between uses of the app has to be 
	saved outside the app itself.

	We want the tasks we add to be saved when we close the app so we 
	need to save the task list when the app is closed and read it in 
	when the app is opened.
action
	interlude
	go to step "closeStack handler"
end step

step "closeStack handler"
	When a stack is closed it receives a 'CloseStack' message. Any 
	clean-up can be done in this handler.

	In this app we will save the list of tasks before the app is closed. 
	The contents of the 'TaskList' field are saved to a text file in the 
	'Documents' folder, ready to be loaded in the next time the app is 
	opened. There is a 'Documents' folder on all platforms so this code 
	will work on desktop and mobile.
action
	interlude
	go to step "Select Stack For Editor"
end step

step "Select Stack For Editor"
	Ensure this is the active stack, by clicking on it.
action
	highlight stack "Mainstack"
	wait until stack "Mainstack" is selected
	go to step "Open Stack Script"
end step

step "Open Stack Script"
	Just like the SVG icons and other objects a Stack can have code 
	associated with it and receive messages.

	The CloseStack message is sent to the stack so will be handled on 
	the Stack Script.

	Click on the Object menu, and select 'Stack Script' to open the 
	Script Editor for the stack.
action
	highlight menu item "Stack Script" of menu "Object"
	wait until there is a script editor for stack "Mainstack"
	go to step "closeStack code"
end step

step "closeStack code"
	In the closeStack handler we work out the full path to the text 
	file that will be used to store the To Do list and save the 
	contents of the field to the text file.

	Add this handler to the Stack Script and press 'Apply'.
script
	on closeStack
		local tFile
		put specialFolderPath("documents") & "/ToDoList.txt" into tFile
		put field "TaskList" into url ("file:" & tFile)
	end closeStack
action
	highlight script editor for stack "Mainstack"
	wait until stack "Mainstack" is scripted
	go to step "preOpenStack code"
end step

step "preOpenStack code"
	When a stack is opened it receives a 'PreOpenStack' message. Any 
	set-up can be done in this handler, before the stack becomes visible 
	to the user.

	When the stack is opened we will load in the saved tasks form the 
	text file in the 'Documents' folder.

	Add this handler to the Stack Script and press 'Apply'.
script
	on preOpenStack
		local tFile
		put specialFolderPath("documents") & "/ToDoList.txt" into tFile
		put url ("file:" & tFile) into field "TaskList"
	end preOpenStack

	on closeStack
		local tFile
		put specialFolderPath("documents") & "/ToDoList.txt" into tFile
		put field "TaskList" into url ("file:" & tFile)
	end closeStack
action
	highlight script editor for stack "Mainstack"
	wait until stack "Mainstack" is scripted
	go to step "Save Standalone"
end step

step "Save Standalone"
	Before you can prepare your app for sharing you need to set is up to 
	build as a self contained, or 'standalone' app.

	You set up this up by selecting the platforms you want to build for 
	and setting some properties for the app. You then choose "Save As 
	Standalone Application..." from the File menu. This will build the 
	executable files for the selected platforms.

	For more details see this lesson
url
		http://lessons.livecode.com/m/4603/l/44282-building-standalone-applications
action
	interlude
	go to step "epilogue"
end step

skip point

epilogue
	That's it, you have finished your app. Switch back to 'Run' mode and try it out.

	Why don't you try customizing it by changing some properties such as the
	icon colors or task list font and text size.
image
		ToDoListScreenshot2.png
end epilogue
