Skip to content
Browse files

Port over rest of existing topics from xml -> markdown.

  • Loading branch information...
1 parent fedb376 commit c480ad57ce733998072c9976c2f47fb739a91ace @joshthecoder joshthecoder committed
Showing with 567 additions and 2 deletions.
  1. +123 −0 Topics/application.md
  2. +7 −0 Topics/basics.md
  3. +97 −0 Topics/database.md
  4. +171 −0 Topics/menus.md
  5. +44 −0 Topics/notification.md
  6. +123 −0 Topics/windows.md
  7. +2 −2 tiapp.xml
View
123 Topics/application.md
@@ -0,0 +1,123 @@
+Application
+===========
+##Useful methods
+
+The API module also contains information about the currently-running Titanium
+application, which may be retrieved via <tt>Titanium.API.getApplication</tt>.
+The <tt>Application</tt> object that is returned by this method has a multitude of
+[useful properties](href="http://developer.appcelerator.com/apidoc/desktop/1.0/Titanium.API.Application.html").
+
+ :::javascript
+ var app = Titanium.API.application;
+ alert(app.getDataPath());
+ alert(app.getGUid());
+
+The App module also contains some very useful API points for dealing
+with the currently-running application. In particular you may wan to
+convert an <tt>app://</tt> URL into a path.
+
+ :::javascript
+ // The two alerts should be the same.
+ alert(Titanium.App.appURLToPath("app://images/kitten.png"));
+ alert(Titanium.Filesystem.getFile(Titanium.API.application.resourcesPath,
+ "images", "kitten.png"));
+
+One of the main benefits of the App module though is that it can
+return values from the <tt>tiapp.xml</tt> file. This might be useful for
+displaying the application version to the user or presenting a link to
+your URL.
+
+ :::javascript
+ alert("Welcome to " + Titanium.App.getName() +
+ " " + Titanium.App.getVersion());
+
+##Application properties
+
+Application properties provide a light-weight alternative to HTML5
+databases or the Titanium Database module. They come in two varieties:
+system properties and user properties. System properties are read-only
+properties that are defined via the <tt>tiapp.xml</tt> file, while user properties
+can be stored at any file path.
+
+###System properties
+
+In the KitchenSink <tt>tiapp.xml</tt>, the following properties are defined
+as children of the `<ti:app>` node:
+
+ :::xml
+ <property name="myString" type="string">I am a String</property>
+ <property name="myDouble" type="double">1.23</property>
+ <property name="myBool" type="boolean">true</property>
+ <property name="myInt" type="int">1</property>
+ <property name="myList" type="list">1,2,3</property>
+ <property name="myDefaultString">I am a default string</property>
+
+It is possible to access these properties by getting an instance of
+the system properties object:
+
+ :::javascript
+ var properties = Titanium.App.getSystemProperties();
+ alert(properties.getString("myString"));
+ alert(properties.getInt("myInt"));
+
+System properties are read-only, because an application may not have write
+access to it's installation directory (where <tt>tiapp.xml</tt> resides). To
+store properties, it's recommended that you write a user properties file to the
+application data directory.
+
+###User properties
+
+User properties have the same interface as system properties, but can be stored
+in any file on the filesystem. Generally speaking, it's best to store these in
+in the application data directory, which is a per-user are to store application
+files. On Linux this is in <tt>~/.titanium/appdata/</tt>, on OS X,
+<tt>~/Library/Application Support/Titanium/appdata</tt> and on Windows in
+<tt>%appdata%/Titanium/appdata</tt>.
+
+Here is an example of reading and writing to a user properties file:
+
+ :::javascript
+ var file = Titanium.Filesystem.getFile(
+ Titanium.API.application.dataPath, "demo.properties");
+
+ // Load the file if it exists.
+ var properties = null;
+ if (file.exists())
+ properties = Titanium.App.loadProperties(file);
+
+ // If the file doesn't exist, yet just create a new properties object.
+ if (properties === null)
+ properties = Titanium.App.createProperties({
+ val1: true,
+ val2: 1.1,
+ val3: ['a', 'b', 'c'],
+ val4: "123"
+ });
+
+ // Update the properties object and save it.
+ alert(properties.getString('val4'));
+ properties.setString('val4', '321');
+ properties.saveTo(file);
+
+##Exiting and restarting
+
+It is possible to exit and restart your application. This is useful
+for creating a custom exit button. The application will also exit when
+the last top-level window closes. It is alos possible to prevent your
+application from exiting by listening for the <tt>EXIT</tt> event.
+One complication with this approach is that the <tt>EXIT</tt> event is
+fired after the last window closes, so you might need to recreate the
+main window. A better approach is to simply catch <tt>CLOSE</tt> events.
+
+ :::javascript
+ // Exit KitchenSink
+ Titanium.API.addEventListener(Titanium.EXIT, function(event)
+ {
+ if (!confirm("Are you sure you want to exit?"))
+ event.preventDefault();
+ });
+ Titanium.App.exit();
+
+ // Restart KitchenSink
+ Titanium.App.restart();
+
View
7 Topics/basics.md
@@ -7,6 +7,7 @@ is an object shared between all JavaScript contexts. Each frame, including
the top-level frame of each window, has its own JavaScript context. This
makes sharing data between frames a snap:
+ :::javascript
Titanium.DataDump = {}
Titanium.DataDump.value = "foo";
alert(Titanium.DataDump.value);
@@ -19,12 +20,14 @@ Almost all instantiated objects in Titanium are accessor-objects. This means
that properties can be accessed and modified in two styles. For example, take
this use use of *API.Application.getName()*:
+ :::javascript
alert(Titanium.API.getApplication().getName());
alert(Titanium.API.getApplication().name);
alert(Titanium.API.application.name);
Likewise a similar method can be used for modifiers:
+ :::javascript
Titanium.UI.currentWindow.setTitle("Title1");
Titanium.UI.currentWindow.title = "Title2";
@@ -32,6 +35,7 @@ Likewise a similar method can be used for modifiers:
Titanium provides an API for logging. There are two supported methods.
+ :::javascript
Titanium.API.critical("critical message");
Titanium.API.debug("debug message");
Titanium.API.error("error message");
@@ -57,6 +61,7 @@ The Web Inspector only logs WARN messages or higher.
If you want to control the level of logging that is displayed via stdout,
you can set the logging level.
+ :::javascript
alert("The current log level is: " + Titanium.API.getLogLevel());
Titanium.API.setLogLevel(Titanium.API.FATAL);
alert("The current log level is: " + Titanium.API.getLogLevel());
@@ -68,6 +73,7 @@ Titanium allows you to access environment variables via the
by this function is live representation of all environment variables,
which allows you to query and update the environment easily.
+ :::javascript
var env = Titanium.API.getEnvironment();
alert(env['PATH']);
@@ -83,6 +89,7 @@ may need to inercept all events after they've bubbled up to the
top-level object. This is possible by installing an event handler
on the Titanium object.
+ :::javascript
Titanium.API.addEventListener("CustomEvent", function(event)
{
alert("Top-level got " + event.type + " event!");
View
97 Topics/database.md
@@ -0,0 +1,97 @@
+Database
+========
+##Introduction
+
+There are two ways to use databases in Titanium: HTML 5 databases
+and the database API. In some cases you access the same database
+file with both APIs as well. Currently both APIs use SQLite backends.
+
+##Opening a Database
+
+There are two ways to open Titanim databases, <tt>Titanium.Database.open</tt>
+and <tt>Titanium.Database.openFile</tt>. <tt>open</tt> will create (if necessarY0
+and open a database in the same directory and schema as WebKit HTML 5 databases.
+Use this method if you'd like to use a single database with both APIs.
+
+ :::javascript
+ // Create a WebKit-compatible database given, the database name.
+ var db = Titanium.Database.open('mydatabase');
+
+You may also create a database using <tt>Titanium.Database.openFile</tt>
+which can be given a file path or <tt>Titanium.Filesystem.File</tt> object.
+If the database file does not exist, the method will create it and open it.
+
+ :::javascript
+ var db = Titanium.Database.openFile(Titanium.Filesystem.getFile(
+ Titanium.Filesystem.getApplicationDataDirectory(), 'mydatabase.db'));
+
+Note: It's recommended that you store all data in the application data
+directory and not the application Resources or contents directory, as those
+may not be writeable.
+
+##Simple Queries
+
+Once a database is open you may execute simple queries on it. For instance,
+to create a table:
+
+ :::javascript
+ var db = Titanium.Database.openFile(Titanium.Filesystem.getFile(
+ Titanium.Filesystem.getApplicationDataDirectory(), 'mydatabase.db'));
+ db.execute("CREATE TABLE IF NOT EXISTS test(id INTEGER, name TEXT)");
+
+Note: Be sure your query is SQLite-compatible! SQLite has different data
+types than MySQL, check them out [here](http://www.sqlite.org/datatype3.html).
+
+Find a way to detect databases that already exist.
+
+Inserting and retrieving data works in a very similar way:
+
+ :::javascript
+ var db = Titanium.Database.openFile(Titanium.Filesystem.getFile(
+ Titanium.Filesystem.getApplicationDataDirectory(), 'mydatabase.db'));
+
+ db.execute("CREATE TABLE IF NOT EXISTS test(id INTEGER, name TEXT)");
+ db.execute("INSERT INTO test VALUES(123, 'a')");
+
+ var resultSet = db.execute("SELECT * FROM test");
+ alert("Found " + resultSet.rowCount() + " rows");
+ while (resultSet.isValidRow())
+ {
+ var text = "";
+ for (var i = 0; i &lt; resultSet.fieldCount(); i++)
+ text += resultSet.fieldName(i) + ":"
+ + resultSet.field(i) + " ";
+ alert(text);
+ resultSet.next();
+ }
+
+##Advanced Queries
+
+You should never used unescaped input in SQL queries. In these situations
+Titanium provides a query template mechanism:
+
+ :::javascript
+ var db = Titanium.Database.openFile(Titanium.Filesystem.getFile(
+ Titanium.Filesystem.getApplicationDataDirectory(), 'mydatabase.db'));
+
+ var id = prompt("Enter entry id");
+ if (!id)
+ return;
+ var value = prompt("Enter entry value");
+ if (!value)
+ return;
+
+ db.execute("CREATE TABLE IF NOT EXISTS test(id INTEGER, name TEXT)");
+ db.execute("INSERT INTO test VALUES(?, ?)", id, value);
+
+ var resultSet = db.execute("SELECT * FROM test");
+ alert("Found " + resultSet.rowCount() + " rows");
+ while (resultSet.isValidRow())
+ {
+ var text = "";
+ for (var i = 0; i &lt; resultSet.fieldCount(); i++)
+ text += resultSet.fieldName(i) + ":"
+ + resultSet.field(i) + " ";
+ alert(text);
+ resultSet.next();
+ }
View
171 Topics/menus.md
@@ -0,0 +1,171 @@
+Menus
+=====
+##Menu Structure
+
+Menus are composed of two different types of objects. <tt>Titanium.UI.Menu</tt>
+and <tt>Titanium.UI.MenuItem</tt>. A <tt>Menu</tt> is a container for
+<tt>MenuItem</tt>s, while <tt>MenuItems</tt>s represent a single menu entry.
+There are three types of menu items: normal menu items, check menu items and
+separator items. A check menu item is a stateful menu item that can either be
+on or off, while a separator item is a non-interactive item which simply inserts
+a separator line in the menu.
+
+Titanium menus and menu items are <em>live</em>, meaning that you can add them
+to any number of menus and use them in any number of places and all instances
+will update immediately. For instance, you may construct a menu object, set it
+on the current window and the tray item, and then update the first menu item.
+The menu item will immediately change on both the tray icon and the window.
+
+##Simple Menus
+
+Here is some code which constructs a simple menu:
+
+ :::javascript
+ var createMenuItem = Titanium.UI.createMenuItem;
+ var createMenu = Titanium.UI.createMenu;
+
+ var makeItem = function(name)
+ {
+ var item = createMenuItem(name, function()
+ {
+ alert("Selected the '" + name + "' item");
+ });
+ return item;
+ };
+
+ var mainMenu = createMenu();
+ mainMenu.appendItem(createMenuItem("Characters"));
+ mainMenu.appendItem(createMenuItem("Plot Twists"));
+ mainMenu.appendItem(createMenuItem("Endings"));
+
+ var menu = createMenu();
+ menu.appendItem(makeItem("George, the spy"));
+ menu.appendItem(makeItem("Henriette, the scientist"));
+ menu.appendItem(makeItem("Ferdinand, the politician"));
+ mainMenu.getItemAt(0).setSubmenu(menu);
+
+ var menu = createMenu();
+ menu.appendItem(makeItem("Doublecross"));
+ menu.appendItem(makeItem("Deux ex machina"));
+ menu.appendItem(makeItem("Dinosaurs"));
+ mainMenu.getItemAt(1).setSubmenu(menu);
+
+ var menu = createMenu();
+ menu.appendItem(makeItem("Sad"));
+ menu.addSeparatorItem();
+ menu.appendItem(makeItem("Happy"));
+ menu.appendItem(makeItem("Surreal"));
+ mainMenu.getItemAt(2).setSubmenu(menu);
+
+ Titanium.UI.currentWindow.menu = mainMenu;
+
+A menu can also be cleared:
+
+ :::javascript
+ Titanium.UI.currentWindow.menu = null;
+
+##Items with Icons
+
+It's pretty easy to create a menu item with an image.
+
+ :::javascript
+ var createMenuItem = Titanium.UI.createMenuItem;
+ var createMenu = Titanium.UI.createMenu;
+
+ var mainMenu = createMenu();
+ mainMenu.appendItem(createMenuItem("Characters"));
+
+ var menu = createMenu();
+ mainMenu.getItemAt(0).setSubmenu(menu);
+
+ var imageItem = createMenuItem("Swap image",
+ function()
+ {
+ if (imageItem.getIcon() == "app://images/icon1.png")
+ imageItem.setIcon("app://images/icon2.png");
+ else
+ imageItem.setIcon("app://images/icon1.png");
+ },
+ "app://images/icon1.png"
+ );
+ menu.appendItem(imageItem);
+ menu.addItem("Another item");
+ menu.addItem("Another another item");
+
+ Titanium.UI.currentWindow.setMenu(mainMenu);
+
+As you can see it's possible to set the menu image during construction
+of the menu item or to change it later via the <tt>setIcon</tt> method.
+
+##Check Menu Items
+
+Check menu items are stateful menu items which have
+distinct 'on' and 'off' states which toggle when the
+item is selected.
+
+ :::javascript
+ var createMenu = Titanium.UI.createMenu;
+ var mainMenu = createMenu();
+ mainMenu.addItem("Characters");
+ var menu = createMenu();
+ mainMenu.getItemAt(0).setSubmenu(menu);
+
+ var checkItem = Titanium.UI.createCheckMenuItem("Check state",
+ function()
+ {
+ alert("Previous state of the item: " + checkItem.getState());
+ }
+ );
+ menu.appendItem(checkItem);
+ menu.addItem("Another item");
+ menu.addSeparatorItem();
+ menu.addItem("Another another item");
+ Titanium.UI.currentWindow.setMenu(mainMenu);
+
+Sometimes you need more advanced control over whether or not the
+check should change states. There are two ways to do this. The first
+is to use event handling:
+
+ :::javascript
+ var createMenu = Titanium.UI.createMenu;
+ var mainMenu = createMenu();
+ mainMenu.addItem("Characters");
+ var menu = createMenu();
+ mainMenu.getItemAt(0).setSubmenu(menu);
+
+ var checkItem = Titanium.UI.createCheckMenuItem("Check state",
+ function(event)
+ {
+ if (!confirm("Should the item change state?"))
+ event.preventDefault();
+ }
+ );
+ menu.appendItem(checkItem);
+ menu.addItem("Another item");
+ menu.addItem("Another another item");
+ Titanium.UI.currentWindow.setMenu(mainMenu);
+
+Another approach is to disable auto-checking on the item. The essentially
+means that you'll have to manage the state of the item yourself. This is
+also useful if you'd like to turn a series of check items into radio buttons.
+
+ :::javascript
+ var createMenu = Titanium.UI.createMenu;
+ var mainMenu = createMenu();
+
+ mainMenu.addItem("Characters");
+ var menu = createMenu();
+ mainMenu.getItemAt(0).setSubmenu(menu);
+ var checkItem = Titanium.UI.createCheckMenuItem("Check state",
+ function()
+ {
+ if (confirm("Should the item change state?"))
+ checkItem.setState(!checkItem.getState())
+ }
+ );
+ checkItem.setAutoCheck(false);
+ menu.appendItem(checkItem);
+ menu.addItem("Another item");
+ menu.addItem("Another another item");
+ Titanium.UI.currentWindow.setMenu(mainMenu);
+
View
44 Topics/notification.md
@@ -0,0 +1,44 @@
+Notifications
+=============
+##Creating Notifications
+
+Desktop notifications are provided by Growl on OS X, Snarl on Windows
+and libnotify on Linux. If a notification provider cannot be found,
+notifications will be shown with an HTML / CSS backup.
+
+A simple notification:
+
+ :::javascript
+ var cb = function()
+ {
+ alert("I've been clicked.");
+ }
+
+ var notification = Titanium.Notification.createNotification({
+ 'title': "A nice notification",
+ 'message': "This notifications was brought to you by the letter 'N'.",
+ 'timeout': 10,
+ 'callback': cb
+ });
+ notification.show();
+
+Not all platforms support notification callback or specifying a custom
+timeout. You can also supply an icon with your notification:
+
+ :::javascript
+ var cb = function()
+ {
+ alert("I've been clicked.");
+ }
+
+ var notification = Titanium.Notification.createNotification({
+ 'title': "A nice notification",
+ 'message': "This notifications was brought to you by the letter 'N'.",
+ 'timeout': 10,
+ 'callback': cb,
+ 'icon': 'app://images/icon2.png'
+ });
+ notification.show();
+
+The icon supplied should be an absolute <tt>app://</tt>, <tt>ti://</tt> or <tt>file://</tt> URL.
+
View
123 Topics/windows.md
@@ -0,0 +1,123 @@
+Windows
+=======
+##The Current Window
+
+All Titanium windows are
+[UI.UserWindow](http://developer.appcelerator.com/apidoc/desktop/1.0/Titanium.UI.UserWindow)
+objects. Code running in context of an HTML page can easily access the current window:
+
+ :::javascript
+ alert(Titanium.UI.currentWindow);
+
+From there it is easy to modify the window at will:
+
+ :::javascript
+ Titanium.UI.currentWindow.setTitle(prompt("New window title:"));
+
+All Titanium applications have an initial window, which can be set up
+in the <tt>tiapp.xml</tt> file (check out KitchenSink's <tt>tiapp.xml</tt>
+file or the [guide](http://developer.appcelerator.com/doc/desktop/tiapp.xml).
+Once a window has been opened, it can be closed once, freeing its resources
+and can never be opened again. If you'd just like to hide a window, try the following:
+
+ :::javascript
+ Titanium.UI.currentWindow.hide();
+ setTimeout(function()
+ {
+ Titanium.UI.currentWindow.show();
+ }, 3000);
+
+##Modifying Windows
+
+Most window properties can be changed:
+
+ :::javascript
+ Titanium.UI.currentWindow.setFullscreen(
+ !Titanium.UI.currentWindow.isFullscreen());
+
+ var newWidth = parseInt(prompt("New window width:"));
+
+ // Keep KitchenSink functional.
+ if (!isNaN(newWidth) &amp;&amp; newWidth > 300)
+ Titanium.UI.currentWindow.setWidth(newWidth);
+
+ var newHeight = parseInt(prompt("New window height:"));
+
+ // Keep KitchenSink functional.
+ if (!isNaN(newHeight) &amp;&amp; newHeight > 300)
+ Titanium.UI.currentWindow.setHeight(newHeight);
+
+ // Modify the bounds of the window all at once
+ var bounds = Titanium.UI.currentWindow.bounds;
+ console.log("Previous bounds: " +
+ " x: " + bounds.x +
+ " y: " + bounds.y +
+ " width: " + bounds.width +
+ " height: " + bounds.height);
+
+ bounds.width = 900;
+ Titanium.UI.currentWindow.setBounds(bounds);
+
+Some properties can only be changed before a window is originally open though.
+In particular, a window may only change its use of chrome before it is opened.
+
+ :::javascript
+ // Should have no effect.
+ Titanium.UI.currentWindow.setUsingChrome(false);
+
+ // This should work.
+ var w = Titanium.UI.createWindow("app://new_window.html");
+ w.setUsingChrome(false);
+ w.open();
+
+##Transparent Windows
+
+There are two types of transparency in Titanium. Full window transparency
+specified with the transparency property and background transparency specified
+with the transparent-background property.
+
+###The Transparency Setting
+
+The transparent element should contain a value between 0.0 and 1.0 and
+specifies the opacity of the total window. A window with a transparency
+value of 0.7 would look like:
+
+ :::javascript
+ var w = Titanium.UI.createWindow({
+ url: "app://new_window.html",
+ transparency: 0.85,
+ height: 200
+ });
+ w.open();
+
+The transparency setting of a window can be modified after it has been
+opened. The following example will cause the new window to fade away when
+closed:
+
+ :::javascript
+ var w = Titanium.UI.createWindow({
+ url: "app://fading_window.html",
+ height: 200
+ });
+ w.open();
+
+###The Transparenct Background Setting
+
+The transparent-background property specifies that the WebView in a
+window has a background which is transparent. Elements in the WebView
+may specify different opacities to create non-rectangular windows. Here is
+an example of a non-rectangular Titanium window with a
+transparent-background value of true:
+
+ :::javascript
+ var w = Titanium.UI.createWindow({
+ url: "app://new_window.html",
+ transparentBackground: true,
+ height: 200
+ });
+ w.open();
+
+Note that currently the transparent-background property disables all chrome
+and overrides the transparency property. The transparent-background property
+cannot be changed once a window is open.
+
View
4 tiapp.xml
@@ -23,8 +23,8 @@
<id>initial</id>
<title>Desktop Kitchen Sink</title>
<url>app://index.html</url>
- <width>1000</width>
- <height>700</height>
+ <width>1100</width>
+ <height>800</height>
<fullscreen>false</fullscreen>
<resizable>true</resizable>
<chrome scrollbars="true">true</chrome>

0 comments on commit c480ad5

Please sign in to comment.
Something went wrong with that request. Please try again.