The snapshot below is from our tutorial app. I recommend you to download the source of this application ListBlocks.aia from the Downloads page and try it on an emulator or on a device so you will have better understanding of list manipulation. In the source, I have added plenty of comments for you to easily understand the implementation. You should be able to see those comments once you load the source in your block editor window.
I tried to keep the source as clean as possible without optimizing it too much for beginners to understand. Once you understand the application, trust me, you will be able to rearrange the pieces in more efficient way. Also, for some operations I tried to control it through block editor which actually you can control from designer window like checking if a text box contains only numbers which you can do by enabling the NumbersOnly option in the designer window for a TextBox component, you can specify a ListPicker's elements through ElementsFromString property in the designer window which I also implemented from block editor window. The purpose of that is to give you alternative ideas which you may need in the future. Also note that 1 and 1.25 are both numbers while list indexes are referred by only whole numbers.
Note that the comments in yellow in the image above are not part of the application.
Creating a list is as simple as this-
We have just created four empty lists above, named list1, list2, list3, and userList. "create empty list" block can be found in Lists drawer in your blocks editor. Those lists are currently empty as we haven't added any items yet. Note, you can also use "make a list" block to create an empty list. Just don't put any item when using "make a list" block for creating empty list like this-
What if you don't want to create an empty list, rather you want to create a list with items in it? Well, no worries. You can use "make a list" block to do so.
In the above image, we used "make a list" block to create a list named myList with three items - Apple, Banana, and Guava. If we didn't put any item in the make a list block, it would create an empty list just like the way we did with create empty list block. Note that, you can put as many items as you want in make a list.
Tips: When you name a variable, try naming it with a purpose. Say you need a list of prices of different fruits, you can name that list variable - fruitsPriceList so that later you don't have to recall the purpose of that list, specially when you have lots of variables in your block editor. Also by the name of the variable, one should know that variable represents a list.
Adding an item can be done different ways.
If you look at the image above, we have populated all three lists with different items. First one will have a list of three items which are Orange, Apple, and Banana; the second one is consisted of another three items - 20, 30, and 10. The last one, list3 is consisted of two items which are actually lists. Yes, you can have a list of lists. If you take the first item from list3 which is also a list, you will get a list of three items which contains Orange, Apple, and Banana.
Now, look at the image below-
The difference between add items to list and append to list is that for add items to list, you can add both individual items and lists, but for append to list, you can only add another list into a list. add items to list will consider a list as an item but append to list will take the contents from a list and add them as separate items. To make things clear, in the above image, list1 is the destination list where the contents of list2 will be added at the end of list1. That means, list1 will contain whatever items it had before plus the items from list2. Note that list2 will have no change in its contents. If things are not clear, try it for yourself and see how they behave.
Both add items to list and append to list add an item at the end of the list. What if we want to add an item in a certain position? That's when we need insert list item block. insert list item is used when you want to add an item into a list in a certain position. Let's say you want to add a new item "Grape" into list1 at position 1. This is how you will do it-
As you have noticed, insert list items takes 3 arguments - the list where the new item will be added, the index or position where the item should be added, and the new item that should be added. Since we wanted our new item "Grape" to be added at the beginning of the list, we specified 1 as the index/position. Now our list1 contains four items - Grape, Orange, Apple, and Banana. Note that Grape is the first item in list1 and everything else got moved down by 1 because of the insert operation. Before we inserted Grape, Orange was in the first position, but now Orange is in the second position.
Tips: Always apply whatever you have recently learned. Don't try to learn everything first and then apply.
How do you display all the items in a list? Believe it or not, that is very easy. In the example below, we used a Label component named FirstListContents to display the contents of list1.
for each item and for each number both can be used for iterating/looping through a list. Here we used for each item as we are not concern about the indexes/positions of an item. When we will sort a list, we will be using for each number instead as we'll need the indexes of different items in the list for manipulation. You can still use for each item for sorting, but you must define some local or global variables to access the indexes.
for each item is pretty simple. You provide a list to loop through and there's a local variable named "item" given to you that holds the value of an item. Note that you can change the name "item" to anything you like. Remember "item" is a local variable, you cannot use it outside the scope. In for each block, the scope is inside the do section of for each block.
To give you an idea, let's say you want to get the sum of all items in a list. This is how you would do it-
We have a list named numberList which contains three items - 20, 30, and 10. We wrote a procedure named CalculateSum that sums up the numbers in our list and then displays the sum. We declared a global variable named sum and initialized it to 0. Initializing means assigning a value the first time when you create a variable. Inside the procedure, we again set the value of sum to 0. You might think the initial value of sum was already 0 when we defined the sum variable outside CalculateSum procedure. Well, you may want to use the same procedure again and again. In that case, it's safe to reinitialize a global variable unless the previous value of that global variable should be retained. We used for each item block to loop through each item in our numberList and added to the value of sum. The execution of the above procedure would look like this-
sum = 0
sum = sum + value at position 1 of numberList (0 + 20 = 20)
(Now the value of sum is 20)
sum = sum + value at position 2 of numberList (20 + 30 = 50)
(Now the value of sum is 50)
sum = sum + value at position 3 of numberList (50 + 10 = 60)
(Now the value of sum is 60)
The final value of sum will be 60.
Let's say you want to display a random item from a list. That's how you would do it-
To remove an item, all you need to know is the index/position of the item you want to remove. If you want to remove number 30 from numberList below, you'll have to pass 2 as the index as you can see 30 is in position/index 2 in the numberList below.
In a real world application, you may have to validate if a certain index/position exists in a list before you actually try to remove an item. If you have already downloaded the application that I mentioned at the top of this tutorial, you should see how I validated a given index before I try to remove an item.
To remove everything from a list, simply set the value of the list variable to a make a list block without any item or just use create empty list block. In the image below, we removed all items from numberList by setting the value of numberList to create empty list block.
To replace a list item, you need to provide with three arguments - the list where you want to replace an item, the index of an existing item in the list, and the new item you want to replace an existing item with.
In the image above, initially we had three items 20, 30, and 10 in numberList. We used replace list item block to replace the item at index 1 which was 20 with a new item 100. Now our numberList contains 100, 30, and 10.
Searching for an item can be a little tricky because sometimes you will need to know if a particular item exists in a list, if it does, then you might be interested in knowing where or in which position that item exists. If you have multiple occurrences of the same item in a list, you may also need to know all the positions where the item exists in the list.
In the above image, you can see we are trying to search for the item 30 in numberList which contains three items 20, 30, and 10. Before we started searching, we used is in list? block to check if that item exists in numberList. Block index in list gives us the first occurrence of 30 in the list if it exists. If the item doesn't exist, it gives us 0. Since numberList above contains 30 in the second position, index in list will give us 2.
As of now, we only searched for the first occurrence. What if our list contained 30 two times? How can we get all two positions? Well, we have to use for each block and loop through each item in the list, then compare if the item we are searching for is the same as the item currently in the loop; if equal we get and store the index for later use. We do this for all items in the list.
As you can see above, 30 appears twice in the numberList, in the second and in the fourth positions. As usual, we first check if 30 exists by using is in list block. If it does, we use a for each block and compare each item to see if the item is 30. If it is, we store it in a global variable named resultText by appending. In this case, the final value of resultText would be   because 30 exists in 2nd and 4th positions.
The above numberList as the name implies, contains only numbers. What if we had alphanumeric/text items? In that case, we would need to use the compare texts block from text drawer. See below.
Our search above doesn't ignore casing. Meaning "apple" is not the same as "Apple". If you don't care about casing and you want "apple" to be the same as "APPLE", or "Apple", simply convert both sides of comparison to uppercase or lowercase before you compare. Choose one, if you choose upcase then use it for both sides. You can find both upcase and downcase in the Text drawer. In the above example, if you didn't want to care about casing, you would change the comparison to-
If you have noticed both sides used upcase. All we are doing is that we are converting "Apple" in the left side to "APPLE" and also converting the item in the right side to have also all uppercase letters. So, if the item in the right side was "apple", it will become "APPLE".
I used upcase, you can also use downcase as long as you use the same case for both sides in comparison.
7. Sort a List
Sorting of list is explained here.
Shuffling of lists is explained here.
Download the source ListBlocks.aia from Downloads page and try it for yourself.
Download also the source UniqueSpeedyBirds.aia from Downloads page to see how shuffling works.