This documentation relates to previous versions of Titanium.

To see the latest documentation, visit docs.appcelerator.com.

This space has been migrated to https://techweb.axway.com/confluence/display/dr and will be removed from the Appcelerator wiki on August 9th, 2018

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Type

Notes

Object

Please don't misuse. We wish to emphasize the use of strong types.

Titanium.XX.XX

This is shorthand to signify the types that are defined within the documentation. In fact, they don't have to be the Titanium.XX namespace; any fully-qualified name defined within the set of documentation being parsed can be used as a type name. But since this specification will first be used for Titanium Mobile, Titanium.XX is used here as the example.

Dictionary<[type]>

A special type+syntax indicating a dictionary – i.e., an object literal – whose members can be the properties of the specified [type]. Example: Dictionary<Titanium.UI.Window>. You might use this if you provide your own documentation for a proxy-creation method such as Titanium.UI.createWindow rather than rely on the auto-generated documentation for proxy-creation methods. In that case, you would use Dictionary<Titanium.UI.Window> for the type of the single parameter that createWindow takes.

Callback<[type]>

A special type+syntax indicating a function used as a callback, whose single callback argument (the info passed to the callback) is of type [type], where [type] can be a type that you define elsewhere. We'll see examples of this in the special section on callbacks. The angle bracket notation is optional: Callback by itself signifies simply a function that gets called, with no precise information concerning what is passed to it, if anything.

...

Additionally, other "pseudo-types" (for lack of a better term) may be defined inside the documents as stand-ins for things like callback arguments, object literals that are passed as parameters, or objects that implement a particular interface. We'll see examples of this in the special sections on callbacks and object literals and interfaces.

Inheritance

The specification supports what might be called "multiple documentation inheritance", whereby a Titanium type that is being documented (i.e., a proxy or module) has an extends property that can be set to a single qualified type name or an array of type names, thereby giving the child type all of the method, property and event documentation defined in the super types. Example:

...

Key

Notes

Example

name

A fully-qualified name for the type

name: Titanium.Do.Hicky

summary

A short, "one-liner" summary of the type, in Markdown format. Keep it short, as it will often be generated next to the type name in lists, for example. Deeper information about the type should go into the description property. Please start summaries with a capital letter and end with a period.

summary: View which automatically renders as an octagon.

description

(Optional) Free-form , longer format text description of the Type, in Markdown format, or "file:" followed by the name of a file which contains the description. If an external file is used, the contents should be in Markdown format and the file extension should be .md.

See Free-Form Text Values below.

createable

(Optional) Applicable only to "proxy" types (types having Titanium.Proxy as an ancestor). This indicates whether a standard createXXXX method is supported to create an instance of the proxy from the module in which it is located. The default is true since almost all proxies can be created in that way.

createable: false

platforms

(Optional) Array of supported platforms. If missing, it is to be assumed that all platforms are supported. Note that ipad is its own platform. As the example shows, a simple YAML array syntax is to enclose a comma-separated list in square brackets.

platforms: [android, iphone, ipad]

extends

(Optional). Either a single fully-qualified type name, or an array of fully-qualified type names from which the documented Type inherits.

extends: Titanium.UI.View

excludes

(Optional). For excluding inherited methods, properties or events. Can have one or more of these members: methods, properties, events. Each of those is an array of strings indicating which methods (or properties, or events) to exclude.

excludes: {methods: [add, remove], events: [click]}

since

Indicates in which Titanium version the Type first appeared. Either a single value if the Type appeared at the same time on all platforms, or a dictionary object with keys per platform and values containing the relevant version number. NOTE: YAML will interpret values such as 0.8 as numbers, which can lead to parser libraries ending up with values such as 0.800000000001 because of floating points. Enclose version numbers in full-quotations so as to avoid this.

since: "0.8" or since: {android: "1.6.0", iphone: "0.8", ipad: "1.4.2"}

deprecated

(Optional) A simple dictionary object with keys since and removed, whose values should hold Titanium version numbers indicating since when the type was deprecated and when (if ever) it will be removed. since should always be present. removed is optional.

deprecated: {since: "1.6.0", removed: "1.8.0"}

osver

(Optional). Can be used to specify operating system version number requirements for the given type. This should be a dictionary with keys for each OS whose version needs to be specified (ios/android). The key values should then also be dictionaries with the keys min, max and/or versions, each of which is optional. min and max should have stringified version numbers, whereas versions, if present, should be an array of stringified version numbers.

osver: {android: {min: "2.1"}} or osver: {ios: {max: "3.2"}} or osver: {android: {versions: ["1.6", "2.1"]}}

examples

(Optional). An array of objects wherein each element has title and example properties. The title property should briefly describe the particular example. The example property should be a free-form text block in Markdown format for showing code examples, or "file:" followed by the name of a file which contains the code examples. If an external file is used, the contents should be in Markdown format and the file extension should be .md. In the text block or external file, the blocks of code themselves should be indented four spaces to follow the Markdown standard and guarantee that generated HTML will include <pre> and <code> tags. So-called "fenced code blocks" (~~~) are not supported, as they are non-standard and not all Markdown parsers support them.

See #Code Examples below.

methods

(Optional). An array of method definitions describing the type's methods.

See #Method Specification below.

properties

(Optional). An array of property definitions describing the type's methods.

See #Property Specification below.

events

(Optional). An array of event definitions describing the type's events.

See #Event Specification below.

Our running example so far:

...

Key

Notes

Examples

name

The method name.

name: doSomething

summary

A short, "one-liner" summary of the method, in Markdown format. Keep it short, as it will often be generated next to the method name in lists, for example. Deeper information about the method should go into the description property. Please start summaries with a capital letter and end with a period.

summary: Does something on the view.

description

(Optional) Free-form , longer format text description of the method, in Markdown format, or "file:" followed by the name of a file which contains the description. If an external file is used, the contents should be in Markdown format and the file extension should be .md.

See Free-Form Text Values below.

returns

(Optional). A dictionary object with type and description keys and their values. The description key is optional. The type key's value should be a type identifier. If it is possible for the method to return different types, set this to an array of these dictionaries. This key is optional in the sense that if it is missing, then it is assumed that there is no return value. There is no need to specify void return types.

returns: {type: "String", description: "The system's locale"} or, in the case of multiple possible return types, returns: [{type: "String", description: "The system's locale"}, {type: "Object", description: "A locale object"}].

platforms

(Optional). Identical to the platforms key defined in the #Valid Keys in a Type's Documentation section, but applied here to a method. This is optional. If missing it is assume that the value would be the same as the type's platforms value.

platforms: [android, iphone, ipad]

since

(Optional). Identical to the since key defined in the #Valid Keys in a Type's Documentation section, but applied here to a method. This is optional. If missing, it is assumed that the value would be the same as the type's since value.

since: "0.8" or since: {android: "1.6.0", iphone: "0.8", ipad: "1.4.2"}

deprecated

(Optional) A simple dictionary object with keys since and removed, whose values should hold Titanium version numbers indicating since when the method was deprecated and when (if ever) it will be removed. since should always be present. removed is optional.

deprecated: {since: "1.6.0", removed: "1.8.0"}

osver

(Optional). Can be used to specify operating system version number requirements for the given method. This should be a dictionary with keys for each OS whose version needs to be specified (ios/android). The key values should then also be dictionaries with the keys min, max and/or versions, each of which is optional. min and max should have stringified version numbers, whereas versions, if present, should be an array of stringified version numbers.

osver: {android: {min: "2.1"}} or osver: {ios: {max: "3.2"}} or osver: {android: {versions: ["1.6", "2.1"]}}

examples

(Optional). Identical to the examples key defined in the #Valid Keys in a Type's Documentation section, but in this case to show examples specifically for the method.

See #Code Examples below.

parameters

(Optional). An array of parameter definitions documenting the method parameters.

See #Method Parameter Specification below.

Method Parameter Specification

...

Key

Notes

Examples

name

The property name.

name: x

summary

A short, "one-liner" summary of the property, in Markdown format. Keep it short, as it will often be generated next to the property name in lists, for example. Deeper information about the property should go into the description property. Please start summaries with a capital letter and end with a period.

summary: X-axis of the dohicky.

description

(Optional) Free-form , longer format text description of the property, in Markdown format, or "file:" followed by the name of a file which contains the description. If an external file is used, the contents should be in Markdown format and the file extension should be .md.

See Free-Form Text Values below.

type

A data type specifier indicating the type of the parameter, or an array of data type specifiers in case multiple types are allowed for the parameter. A view dimension is a typical use-case for the latter, since we support numeric values (interpreted as pixels) or string values ("auto", "10dp", etc.).

type: Number

platforms

(Optional). Identical to the platforms key defined in the #Valid Keys in a Type's Documentation section, but applied here to a property.

platforms: [android, iphone, ipad]

since

(Optional). Identical to the since key defined in the #Valid Keys in a Type's Documentation section, but applied here to a property.

since: "0.8" or since: {android: "1.6.0", iphone: "0.8", ipad: "1.4.2"}

deprecated

(Optional) A simple dictionary object with keys since and removed, whose values should hold Titanium version numbers indicating since when the property was deprecated and when (if ever) it will be removed. since should always be present. removed is optional.

deprecated: {since: "1.6.0", removed: "1.8.0"}

osver

(Optional). Can be used to specify operating system version number requirements for the given property. This should be a dictionary with keys for each OS whose version needs to be specified (ios/android). The key values should then also be dictionaries with the keys min, max and/or versions, each of which is optional. min and max should have stringified version numbers, whereas versions, if present, should be an array of stringified version numbers.

osver: {android: {min: "2.1"}} or osver: {ios: {max: "3.2"}} or osver: {android: {versions: ["1.6", "2.1"]}}

examples

(Optional). Identical to the examples key defined in the #Valid Keys in a Type's Documentation section, but in this case to show examples specifically for the property.

See #Code Examples below.

permission

(Optional). One of read-only, write-only or read-write. If missing, the value is assumed to be read-write.

permission: read-only

availability

(Optional). When the property can be written to, in the sense that some of our proxy properties can only be set in the dictionary object passed to a createXXX({...}) method. Valid values here are always, creation and not-creation. creation means it can (or should – this is a cue to the SDK user) only be set in the dictionary object passed to createXXX({...}), whereas not-creation means it can only be set directly on the proxy object and not via the createXXX({...}) method. If missing, the value is assumed to be always.

availability: always

accessors

(Optional). Whether a getter and setter method exist for the property (true/false, default true).

accessors: false to indicate that there is no setter/getter for the property.

optional

(Optional). Whether it's considered optional to have the property set in the object. The default is true (i.e., not every object property needs to have a value). There may be cases where it is useful to set this to false to indicate that a value is required, for example when passing an object (see pseudo-object discussion below) as a paramater to a method.

optional: false

value

(Optional). The fixed value of the property. Particularly useful to express that something is a constant, such as by setting permission: read-only and by setting a value.

value: 0

default

(Optional). The default value of a property. You can use this to set a specific value (such as 0) or free text explaining how the default value is determined.

default: 0 or default: <Titanium.Codec.CHARSET_UTF8> or default: The device's current locale

Multiple property documentation definitions can be put together into a YAML sequence by following the same syntax as for multiple methods.

Our running example so far, which includes a sequence of property definitions:

...

Key

Notes

Examples

name

The event name.

name: flummered

summary

A short, "one-liner" summary of the event, in Markdown format. Keep it short, as it will often be generated next to the event name in lists, for example. Deeper information about the event should go into the description property. Please start summaries with a capital letter and end with a period.

summary: Fires when something happens.

description

(Optional) Free-form , longer format text description of the event, in Markdown format, or "file:" followed by the name of a file which contains the description. If an external file is used, the contents should be in Markdown format and the file extension should be .md.

See Free-Form Text Values below.

extends

(Optional). Either a single fully-qualified type name, or an array of fully-qualified type names from which the event object inherits. As a convenience, this can be omitted and it will then be assumed that the event object extends Titanium.Event, which only contains the standard type and source properties.

extends: Titanium.Event

platforms

(Optional). Identical to the platforms key defined in the #Valid Keys in a Type's Documentation section, but applied here to an event.

platforms: [android, iphone, ipad]

since

(Optional). Identical to the since key defined in the #Valid Keys in a Type's Documentation section, but applied here to an event.

since: "0.8" or since: {android: "1.6.0", iphone: "0.8", ipad: "1.4.2"}

deprecated

(Optional) A simple dictionary object with keys since and removed, whose values should hold Titanium version numbers indicating since when the event was deprecated and when (if ever) it will be removed. since should always be present. removed is optional.

deprecated: {since: "1.6.0", removed: "1.8.0"}

osver

(Optional). Can be used to specify operating system version number requirements for the given event. This should be a dictionary with keys for each OS whose version needs to be specified (ios/android). The key values should then also be dictionaries with the keys min, max and/or versions, each of which is optional. min and max should have stringified version numbers, whereas versions, if present, should be an array of stringified version numbers.

osver: {android: {min: "2.1"}} or osver: {ios: {max: "3.2"}} or osver: {android: {versions: ["1.6", "2.1"]}}

properties

(Optional). A sequence of event listener object property definitions which describe the properties in the event object passed to a listener for this event.

See #Event Listener Object Property Specification.

Multiple event documentation definitions can be put together into a YAML sequence by following the same syntax as for multiple methods.

Our running example so far, which includes a sequence of event definitions:

...

Key

Notes

Examples

name

The property name.

name: x

summary

A short, "one-liner" summary of the property, in Markdown format. Please start summaries with a capital letter and end with a period.

summary: The x point of the event in receiving view coordinates.

type

A data type specifier indicating the type of the property, or an array of data type specifiers in case multiple types are allowed for the property. A view dimension is a typical use-case for the latter, since we support numeric values (interpreted as pixels) or string values ("auto", "10dp", etc.).

type: Number

platforms

(Optional). Identical to the platforms key defined in the #Valid Keys in a Type's Documentation section, but applied here to an event listener object property.

platforms: [android, iphone, ipad]

deprecated

(Optional) A simple dictionary object with keys since and removed, whose values should hold Titanium version numbers indicating since when the property was deprecated and when (if ever) it will be removed. since should always be present. removed is optional.

deprecated: {since: "1.6.0", removed: "1.8.0"}

For examples, see the YAML sample above in the #Event Specification.

Free-Form Text Values

Three of the YAML keys described in previous sections – summary, description and the example property of each member of an examples array – accept free-form text which will be processed by our scripts as Markdown. This section describes valid approaches to entering free-form text as values for YAML keys.

...

[type] should be replaced with the name of a type that you document simply for purposes of documenting this callback parameter. These can perhaps be thought of as pseudo-types, in the sense that they are only "being documented for the documentation", or to make the documentation complete.

The next section, #Documenting Object Literals and Interfaces, describes how to document these pseudo-types. For the time being, imagine you have defined a pseudo-type named ScreenshotResult to be used with the callback for Titanium.Media.takeScreenshot. In that case, the documentation for the parameters of takeScreenshot would look like this:

...

Object Literals

As the section on #Documenting Callbacks shows, there are some occasions when we wish to provide "strongly-typed documentation" for what are actually simple Javascript object literals with Java HashMap or Objective-C NSDictionary instances behind them. The single parameter accepted by callbacks is one good example; in that case, we wish to document which properties can be expected in the object literal passed to the callback, what data types should be expected for those properties, etc.

...

With YAML, you can document multiple types in a single documentation file simply by starting a new "document". You'll recall from #A Type Documentation is a YAML Document that a new document begins with three dashes (---) alone on a line. So if you wish to write documentation for a pseudo-type that is only used in one place, you can simply start a new YAML document at the bottom of the file.

...

If a pseudo-type is useful in multiple modules, it should go in a common/ folder which is at the root of the documentation directories, i.e., as a sibling to Titanium/. One example of this is the documentation definition for the Stream interface described in #Interfaces above. In that case, a file in common/ should exist – perhaps common/TiStream.yml – with contents similar to this example:

...

Markdown Links in Free-Form Text Values

As explained earlier, a few of the documentation YAML key values accept free-form text which is treated as Markdown. Backticks and double-brackets will no longer be used within these text blocks as indicators that links to type documentation should automatically be generated. Instead, Markdown shall be followed more closely. In Markdown, the backtick has no meaning with respect to linking – nor does a set of double square brackets.

...