Tutorial – Getting Started
So, you want to make a Silica application? Good choice. If you need a bit more convincing of why Silica is awesome before you get started, check out Why Silica?
This tutorial will make a very, very simple application. Once you begin to decide what you want to make take a look at the other topics and pages.
The first step is to open a blank computer and install Silica. TODO
Silica has a fairly straight forward folder structure, you can read about it in detail by looking at the Folder Structure page. However, to keep this tutorial as simple as possible we won't go in to that.
Your program will just need two folders, classes and interfaces. They should be in the same folder as the Silica file is. Your folder tree should look like this:
classes/
interfaces/
Silica
Silica has an amazing class engine. You can read more about them on the Classes page, but the most important thing to know is normal Lua script conventions are impossible. You must use classes. Trust me, it makes for far neater and maintainable code.
Silica revolves entirely around classes. If you've never used object oriented programming before you might want to find some tutorials for a more common object oriented language. None of the documentation will outline how to use object oriented programming, only features of Silica, so you're best learning elsewhere.
The first thing you always need to do when creating a Silica application is to subclass Application, so let's do that now!
The
Applicationclass (and hence, your subclass) is in charge of receiving events from the computer (it is the one that calls os.pullEvent). It is also in charge of changing and loading the interface.
Create a new file in the classes folder called ExampleApplication.lua, or another name of your choosing. Do note, however, class names should be in Pascal case. You can read more about this in the Style Guide.
Open the file you just created and add the following code, we'll explain what's happening next.
class "ExampleApplication" extends "Application" {
name = "Example";
interfaceName = "example";
}You must name your class the exact same name as your file. An error will be raised if you don't.
So, what's this doing?
-
classdefines a class (likefunctiondefines a function) with the name after it as a string. -
extendsstates that we are subclassingApplication. In circumstances where you are not subclassing this can be omitted. - The properties table is the supplied. This declares all the properties (i.e., variables each class instance will have). Functions should not be here. This is always needed, even if you don't have any properties.
That's a very brief outline of what's happening, you can read in far more in-depth explanation on the Classes page.
You'll notice that we have two properties in the properties table. They are both properties defined by Application that we are assigning values to.
name is the application's human readable name. For example, Google Chrome, Sublime Text or iTunes.
interfaceName is the name of the interface that should be shown when your program starts, we'll talk about that soon. 😉
Running your programs requires one 'normal' script file. Call this file whatever you what to type in to the shell to start it. Alternatively, call it startup so it will run when the computer turns on.
Enter this code in to that file.
dofile( "Silica" )
Application.load( "/" )
ExampleApplication():run( ... )dofile loads the prepackaged Silica classes, themes and other goodies. Make sure you always use dofile, using os.loadAPI will not work!
Application.load loads all of your classes. Do not use ExampleApplication.load, that isn't loaded yet! The supplied string is the folder to load from, in this case root. If you files are in another folder change this.
Loading via
Application.loadis ideal for development and released programs, but if you want to release your program as a single file you can also use a Silica package, look at the Packages page for how to do that.
ExampleApplication():run( ... ) creates an instance of your Application subclass and then runs it. The ... are the command line arguments given to your program and should always be used. These can be useful for programs that open files, for example.
We're not quite ready to run our program yet, but we're not too far. Let's check everything is as it should be. Try running your program now by typing in the name of the 'normal' Lua file you created in to the shell and hit enter.
If you've done everything correctly you should see this error:
Interface file not found: example.sinterface
If you don't see that, trying and figure out what's wrong based on the error, we've tried to make them as helpful as possible. Take a look over the tutorial again and if you're still stuck Get Help.
The final step is the most exciting, designing your interface!
An interface defines what you see on the screen. The size, position, text and other attributes of buttons, text boxes, etc. are defined in the interface file.
In Silica, interfaces are defined using an XML subset (Silica Markup Langauge), the file extension for an interface is .sinterface (Silica Interface).
Create a file called example.sinterface in the interfaces folder you created earlier. Your application will load the interface file named whatever value you used for the interfaceName property, in this case example. Make sure you change the name if you used another value.
Interface markup files are pretty simple, but again, we'll only mention the bare specifics. If you want to read more about interfaces, check out the Interfaces page.
Start off by adding this code to your file.
<ApplicationContainer>
<Button x=10 y=10 text="Hello there!" />
</ApplicationContainer>As you can probably guess, this will add a button that says 'Hello World!'
You'll notice that, unlike regular XML, quotation marks are not required for an attribute value if there are no special characters or spaces. This can be used for both text and numbers. You can have them if you wish, however.
Trying firing up your program now. If everything's correct you should see a button!
If something isn't working, try to figure out what's wrong based on the error and look back over the tutorial. If you're still lost Get Help.
See if you can make another button in another location with different text.
Once you've sorted that out, try to figure out how to add a label to your interface. Hint: you'll want to use Label
That's it for the Getting Started guide. Hopefully you've got a grasp on how to make a really basic program.
From here you can do anything! The next IDE? The best image editor 16 colours have ever seen? It's up to you!
There are endless of things you can do with Silica. To get started, I would take a look at the basic sections of each of these pages (probably in the given order) and then move on to specific areas you want to know more about.