Documentation Conventions

This topic describes the design and typographic conventions used in this edition of the Developer Library.

Identifies the header file which must be included to use the documented API.

Identifies the import library an application must link against to use the documented API. The specified library should be included in the LIBRARY section of an application's .mmp file.

Where no "link against" information is given, it can be assumed that no import library is needed. This is typically the case when member functions are wholly inline.

See also mmp file syntax.

The following statements are used to indicate the Symbian OS release to which the API reference documentation refers:

• Supported from Symbian OS version number

• Withdrawn in Symbian OS version number

where Symbian OS version number is one of 5.0, 5.1, 6.0 or 6.1

• 5.0 denotes Version 5, released in June 1999 and the baseline for this documentation. Note that no distinction is made between APIs present in v5 and those newly introduced in v5 - all are marked Supported from.

• 5.1 denotes the v5.1 increment which introduced Unicode support throughout the OS. No public release of v5.1 was made. Unicode support carries forward into all later releases.

• 6.0 denotes Symbian OS v6.0.

• 6.1 denotes Symbian OS v6.1.

This information is provided in reference documentation for each API item (class, enum, typedef, etc.) under the heading "Support", displayed beneath the item prototype. A "Supported from" statement may optionally be followed by a "Withdrawn in" if that API item is no longer supported. If there is no "Withdrawn in" statement, it can be assumed that the item is still available.

The information given in the "Support" section applies by default to the whole page. If an item has been added or removed since that release, the item will have its own Support section. For example if a class marked as introduced in v5 has a member function which was removed in v5.1, the function will have a "Support" section containing Withdrawn in 5.1.

As noted above, many API items marked as Supported from 5.0 were introduced before Version 5. This edition of the Developer Library does not contain any pre-Version 5 information.

Present in API reference for classes which have one or more base classes, lists in a table all the classes from which the current class is derived. The classes are ordered alphabetically. The table is followed by lists of the members which the class inherits from its base classes. The lists of members are ordered alphabetically. Note that if a base class has not been documented, its members will not appear here.

Contains links to one or more related topics.

Various typographic styles are used throughout the Developer Library. Some styles are used to make text easier to understand, for example to highlight code fragments, intended user input, literal filenames, or other quoted text; other styles are used to flag restrictions and general applicability of text. Link styles are also used for hypertext navigation. Note that reference documentation uses a limited range of available styles.

Style Type File | Open Application text and menus. aVariable, Push() Code. note this Emphasised text containing unusual or surprising information. e32std.h Name of a file or directory. toolband A term which is defined in the glossary. dir Input text to enter. ALT+A Key names. NUMED Resource name, resource struct, or resource struct member. syntax Syntax element in syntax diagrams and descriptions. Warning Warning of an important issue.

UML diagrams are used to describe relationships between classes and/or objects. Most classes in these diagrams link to the corresponding section in the API Reference. The following UML notations are used:

Notation Description Concrete Class. Abstract Class. Example Class. These are called "Implementation" in Implementation diagrams and "Client" in Usage diagrams. Interface or class acting as an interface. Package. These are used to denote APIs, subsystems or DLLs. Lists the class immediately above the current class, which is not included in the diagram. Shows derivation between classes. Denotes a relationship between objects. Specifies that an object/class can have none or up to one type of relationship with another object/class. Implies an aggregated relationship between objects.

Backus-Naur Form (BNF) grammars are used as a tool for describing language and command syntax, for example:

select-statement : SELECT select-list FROM table-name [ restriction ] [ ordering ]

restriction : WHERE search-condition

ordering : ORDER BY sort-order

A BNF definition states that the named item given before the colon is written as described after the colon. For example, an ordering is written as ORDER BY followed by a sort-order (which may be defined elsewhere).

BNF expression What it means named-construction : expression Declares that a named-construction is written as expression. named-construction : expression1 expression2 Declares that a named-construction is written as either expression1 or expression2. word The word word, written literally. exp1 exp2 exp1 followed by exp2. [ exp ] exp is optional. [ exp1 | exp2 ] Either exp1 or exp2 or nothing. exp+ expression, repeated one or more times. exp* expression, repeated zero, one or more times.