EPOC Tools & Utilities

EPOC provides a number of programming language-neutral tools which support application development, localisation, and deployment.

These include the Aleppo Help authoring tool, which is used to create and localise application help files; and the Makesis application packaging tool, which is used to simplify application installation and removal for end users.

C++, Java, and OPL developers will all use the application resource tools to create resources for EPOC applications. These tool include rcomp, the resource compiler, and aiftool, the application information file compiler.

Finally, the file conversion utilities may be useful to anyone needing to provide conversions between EPOC, Windows, and other standard file formats.

This documentation, current to EPOC Release 5, provides a complete guide to using these tools. It includes overviews, step-by-step examples, and comprehensive command and syntax references.

Release 017
Copyright (c) 1997-1999 Symbian Ltd. All rights reserved.


Help Authoring with Aleppo

The aleppo Help authoring tool is used to create and structure EPOC help files.

The guide material includes an introduction to aleppo, example projects and a topic on issues related to localising aleppo Help databases. The reference material covers aleppo’s command line syntax, and the file format of each of its source documents.

Users should start by reading the guide material, and refer to the reference sections as necessary.


Aleppo Guide

  • Introduction to aleppo
  • Aleppo example projects
  • EPOC help project localisation issues


Introduction to aleppo

Contents

  • Overview
  • The help authoring process
  • Styled markup
  • Aleppo quick start
    • Creating aleppo source documents
    • Running aleppo

Overview

EPOC help is delivered in the form of a database of help topics, as shown in the following example — topic list on right hand side of diagram. Each topic has a title, body text, application name, and some synonyms to aid in topic searching. Aleppo generates help databases from source documents in which each of these fields is identified by style marked paragraphs.

Example help database

Groups of applications released simultaneously may, optionally, share a help database. This is the method used to provide Help for the standard EPOC applications. The application name can be used to locate all the topics belonging to a specific application. Synonyms provide alternative keywords for locating a topic during a search. For more information on Help file structure see Help database structure.

Aleppo supports various localisation and customisation options that can be used to change the topic order and appearance of the final help database. The following sections explain help file generation in greater detail.

The help authoring process

The process of aleppo help authoring is illustrated in the following diagram:

Operation of aleppo

Aleppo is invoked with a single command, that specifies the type of output file to be produced and the name of a project file. The project file, see Project files, defines the location of all project resources needed to generate the help database, including source files, source directories, graphics directories, working directories and output files/directories.

The project file must specify a source rich-text file for every application to be stored in the database. Topic fields in the final database, e.g. topic title, body text, synonyms etc., are represented by style-marked paragraphs in each rich-text file.

The project file may also, optionally, specify the location of an order file and/or a customisation file. These files determine the order of selected topics, and the appearance of text in the final database, respectively.

The process of help authoring is thus:

  1. edit rich-text source files using a word processor that can generate the styles used by aleppo e.g. Microsoft Word for Windows documents based on the epochelp.dot template
  2. create project, customisation and order files
  3. invoke aleppo to convert to a target format
  4. check the generated help database
  5. if changes are required, make them in the word processor and re-run aleppo.

Styled markup

In order to use aleppo successfully, it is important to know something about how rich-text files are used in the conversion process. The conversion is based on styled markup. It conveys no formatting information from the rich-text file, except for bold, italic, subscript and superscript, and the style names of paragraphs and characters. It does not convey tabs, hard line breaks (shift+enter), or any other formatting information such as fonts, underline, margin settings, borders etc. This means that character and paragraph styles must be used to convey all formatting information to aleppo.

Aleppo is supplied with a document template for Microsoft Word, which contains all the styles needed for EPOC help authoring.

Aleppo quick start

Section Contents

  • Creating aleppo source documents
  • Running aleppo

Creating aleppo source documents

Source .rtf files

To create an aleppo rich-text source file using Microsoft Word:

  1. do File | New, and select the epochelp template
  2. enter the application name in Heading 1 style at the top of the document
  3. enter topic titles in Heading 2 style
  4. enter topic body text below each title, in Normal style.
  5. do File | Save As, and select Rich Text Format (*.rtf) as the type of file

For more information on the format of aleppo RTF files, see RTF file format.

Project files

To create an aleppo project file:

  1. copy an existing project file e.g. \aleppo\projdir\boss.alp
  2. change fields to reflect the structure of the current project.

For more information on the format of aleppo project files, see Project files.

Optional files

An order file can be created to specify the order that topics appear in the help database. If no order file is defined, topics are displayed alphabetically. For more information on order files, see Order files.

A customisation file can be created to specify the appearance of the help database, including the font used for text, its size, and the appearance of tip, important and note effects. If no customisation file is specified, a default appearance is applied. For more information on customisation files, see Customisation files.

Running aleppo

To run aleppo,

  1. bring up a command prompt, or MS-DOS window
  2. ensure that all source files have been saved
  3. either type aleppo -epoc project-file for help database output or aleppo -html project-file to make a html proof of the help. Note that the project-file must include the extension, as the suggested extension .alp is not enforced.
  4. inspect the output
EPOC SDK Home Glossary Indexes Previous Next Up


Aleppo example projects

Contents

  • Overview
  • About the example projects
  • Help project configuration
    • Standard directory structure
    • Aleppo source files — Boss Puzzle
  • Inserting new topics
  • Formatting text using style marking
  • Graphics within topics
  • Changing the topic display order
  • Improved topic searching using synonym style-marking
  • Customising the appearance of topic text
  • Compiling help databases
  • Delivering help databases

Overview

This section describes the configuration of a typical project, including directory structure and source files. Furthermore, it demonstrates how styles are used to create new topics, format topic text, insert graphics and set keywords for topic searching.

The chapter makes use of examples from the Boss Puzzle and Aleppo Help EPOC Help projects, which are located in the directory \aleppo\projdir\.

About the example projects

The Boss Puzzle game was popularised in the late 1800s by the American businessman Samuel Lloyd. It consists of a 4x4 grid of tiles, one of which is missing. The object of the game is to correctly re-order the 15 tiles (in the original form, tiles 14 and 15 were swapped round).

Boss ordered board

The Boss puzzle game is the application developed in the EPOC Tutorial. The example help project, BossPuzzle.hlp, is its supporting help database.

The Aleppo Help database (AleppoHelp.hlp) is an EPOC based guide for using aleppo, which will run on either the Emulator or a target device. It contains useful information on how to configure aleppo source files, and can be used as an additional reference by help authors. Unlike most help files, it is not directly associated with an EPOC application.

The rich-text, project, customisation, and order source files for both projects are stored in the project directory \aleppo\projdir\. The files should be used as a further reference of aleppo project source documents, and/or as the basis for new projects. In addition, compiled reference help files are provided, and are located in the directory \aleppo\projdir\releases\.

Help project configuration

Section Contents

  • Standard directory structure
  • Aleppo source files — Boss Puzzle
    • Project source file
    • Rich-Text source file

Standard directory structure

Aleppo Help projects are built on a PC under Windows. Every help project must be contained within a project directory (e.g. projdir\), which should be located in the \aleppo\ directory.

aleppo project directory structure

As shown in the preceding figure, it is good practice for projdir\ to contain the three sub-directories:

  • Pictures\ - contains the pictures used in the help file (.mbm files).
  • Releases\ - contains generated help files.
  • Temp\ - for holding aleppo working files.

The project’s source files are typically stored in the projdir\ directory. They consist of the Project File, Order File, Customisation file and RTF Source files.

Aleppo source files — Boss Puzzle

The mandatory source files needed to generate the Boss Puzzle help database are the project file Boss.alp, and the rich-text source file BossPuzzle.rtf. The order (BossPuzzle.order) and customisation files (uk.alc) are optional, and are hence discussed under the relevant sections (see Changing the topic display order and Customising the appearance of topic text, respectively).

Project source file

Boss.alp project file, shown below, defines the location of all resources used by the project. The Boss Puzzle help project follows the standard structure (e.g. the project is contained in the directory \aleppo\projdir\, which itself contains temp\, releases\, and pictures\ directories). Boss.alp is the second parameter passed to aleppo when the boss puzzle help database is compiled (see topic Compiling help databases).

    inputdirectory \aleppo\projdir\
    outputdirectory \aleppo\projdir\releases\
    outputfile BossPuzzle.hlp
    sourcefile BossPuzzle
    orderfile BossPuzzle.order
    graphicsdirectory \aleppo\projdir\
    workingdirectory \aleppo\projdir\temp\
    customizationfile \aleppo\projdir\uk.alc

The project file syntax is described in the topic Project files.

Rich-Text source file

The rich-text source files used for aleppo development are based on the EPOCHelp.dot MSWord template. The template has been set up to mimic the appearance of the output help database on the series 5. This aids previewing during development, and highlights the constraints imposed by limited screen size.

The following example shows a segment of the BossHelp.rtf rich-text source file, which is based on the EPOCHelp.dot MSWord template. The styles applied to each section of text are shown in the left hand column. The first lines of text form an introduction to the document (Comment style). Text marked in the Comment style is not converted by aleppo, so the document introduction does not appear in the final database.

The text marked with Heading 1 and Heading 2 styles are the application and topic names, respectively. In a stand-alone help database the application name need not be defined, however in a database containing topics for several applications, the name can be used to group each application’s topics. The text marked in Normal style forms the main body text for the topic.

The Hypertext Anchor style is used to mark a topic’s order-name (see topic Changing the topic display order) while the Graphic Link style indicates to aleppo that a picture is to be inserted in the output database (see topic Graphics within topics).

The file fragment, when compiled, appears in EPOC as below:

Inserting new topics

Topics have mandatory heading and body fields, and optional order and synonym fields. To create a new topic requires only that the author mark the title text with the Heading 2 style. The body text is then all following text up until the next topic title (excluding text marked in the Hypertext Anchor or Synonym styles).

Topic title fields must occupy a single paragraph. A title field of multiple paragraphs defines empty topics (e.g. in the code below, Topic Title 1 is an empty topic).

Selecting New Topic from the EPOC menu on the EPOCHelp.dot template automatically inserts the fields for a new topic, including the optional topic name for sorting (order-name) and synonym fields.

Formatting text using style marking

Styles are applied by selecting the text to be marked, and then applying a format from the template’s style-list. It is important to note that except for bold, italic, subscript and superscript, styles that are not in the style-list are not converted by aleppo. An implication of this is that, for example, bullets created using the List Bullet style are compiled, while those created using the MSWord bullet button are not.

E.g. to produce a bulleted list, use the style-marking:

to produce:

The EPOCHelp.dot template has been configured so that the text in source rich-text files looks similar to how it will appear in the final help database. It is important to note that the similarity is merely a convenience to users, since aleppo compiles solely on the basis of styled markup and customisation file settings. Hence, for example, doubling the font size of the Normal style in a source .rtf file does not double the font size in the output database.

Graphics within topics

Graphics can be inserted into topic body text during aleppo conversion. Aleppo uses references in Graphic Link style to determine which images to load (pictures must be stored in the .mbm multiple bitmap file format, generated from Windows bitmaps using the bmconv tool).

Consider the text fragment below, which is used to insert a picture of the Boss Puzzle board into the topic. The text specifies that the picture is called Ordered-Board.mbm, and is stored in the directory Pictures\. The archive directory must be contained within the folder specified in the graphicsdirectory field of the project file (\aleppo\projdir\).

Note
  • Aleppo also checks the files for an alternative definition of the graphic style mark, in which the archive is a multi-bitmap file, and the picture to be inserted is the name of one of its contained bitmaps. In this case, the graphicsdirectory field of the project file is the directory in which the multi-bitmap archive is stored.

Changing the topic display order

Topics are ordered by the position of their order-name within the Order File (rather than the sequence in which they appear in the rich-text source file). The order-name for a topic is defined in Hypertext Anchor style, and appears directly below the topic title.

In the example above, taken from the source file AleppoHelp.rtf, the topic Elements of a Help Project has the order-name aleppo.project-elements. The order file AleppoHelp.order lists this name second, and hence the topic Elements of a Help Project will appear second in the final database.

    aleppo.quick-start
    aleppo.project-elements
    aleppo.set-up
    aleppo.project_file
    aleppo.rtf_source
    aleppo.order_file
    aleppo.custom_file
    aleppo.running

Order names can be in any language or format, and need not be related to the topic title. Consequently, Order Files are largely immune to localisation issues. Topics which have no order name, or which have an order name which is not used in the order file, are ranked alphabetically in the final database (after the ordered topics).

Improved topic searching using synonym style-marking

The ease with which a specific topic can be located within an EPOC help database may be improved by adding synonyms, or additional keywords, to the topic. These keywords are defined in Synonym style, and appear before topic body text in the rich-text source file.

Topic keywords typically include synonyms, alternative spellings, and even common misspellings. In the file AleppoHelp.rtf, the topic Creating a Customisation File has keywords: Localisation, Localization, Localise, Localize, Customise, Customize, Customization, and source. Hence in addition to searching for the words Creating, Customisation and File, the database engine also searches for the US spelling Customize, the alternate topic Localise (and its US spelling), and under the general topic source. The keywords might also have included Making, Generating and Building, to provide some alternative for Creating.

There is a 254 character database limit for the synonym field associated with each topic. Users may specify more than this number of synonym characters, however all text after the 254th character is ignored by aleppo.

Customising the appearance of topic text

The appearance of text within a help database is dependent on the text file declared after the Project File’s customizationfile field. If no file is declared, or if a file cannot be found at the specified location, a default set of style definitions are applied. The default style (Default customisation file) is similar to that declared in the customisation file \epoc32\tools\aleppo\uk.alc, below, and results in an output which is similar in appearance to text in the EPOCHelp.dot template.

    <bodystyle fontstyle=sansserif size=10>
    <titlestyle fontstyle=sansserif size=14>
    <listbullet1style bulletchar=149>
    <listbullet2style bulletchar=45>
    <tipeffects text="Tip:" bold=yes leftindent=36>
    <noteeffects text="Note:" bold=yes leftindent=36>
    <importanteffects text="Important:" bold=yes leftindent=60>

The first word in each line defines the text type to which the style definition is applied. In the example above, the body style is defined as fontstyle=sansserif and size=10. This means that topic body text (marked as Normal style in the source rich-text file) is displayed in 10pt San Serif in the database. Similarly the title style (Heading 2 style in the source file) is displayed as 14pt San Serif.

Text in List Bullet style is displayed in the help database with a preceding bullet symbol. This symbol is taken from position 149 in the symbol table, as defined by the line: listbullet1style bulletchar=149. Similarly, text in List Bullet 2 style is preceded by character 45 in the final help database.

The tipeffects, noteeffects and importanteffects keywords apply style definitions to text marked as Tip, Note, and Important styles, respectively, in the rich-text source file. When aleppo encounters these style marks it inserts the appropriate text (e.g. Tip) in front of the marked text, as shown below.

Any text can be used for these effects, as long as it is placed between the inverted commas in the style definition text=“any-text”. The text below results when the customisation file replaces Note with AnyText.

It is also possible to precede text marked with Tip, Note, and Important styles with an icon (graphic). However this is not generally recommended, because it increase the size of the generated help file. Inserting graphics is discussed in greater detail in the reference topic (see Customisation files).

Text following the tip, note or important identifier is indented by an amount defined in the leftindent= field. In the example above, Tip, Note and Important text are all indented by 36 twips. For graphics this field is optional. If not defined, text is indented by an amount equal to the width of the graphic.

Compiling help databases

When all of the project source files have been created, the help database is compiled using the following command.

    aleppo -epoc Project-File

The -epoc keyword informs aleppo that the output is to be an EPOC help database rather than a proofing HTML version. The command could also specify -unicode and -compress options to generate unicode and/or compressed help databases. The Project File defines the source documents and graphics used by the project.

An example project file for the stand-alone help file BossPuzzle.hlp was given in a previous topic, see Aleppo source files. The source file is stored in the project directory \aleppo\projdir\ and can be used to compile the database into \aleppo\projdir\release\. To view the compilation process, go to \aleppo\projdir\ and enter the following text on the command line.

    aleppo -epoc Boss.alp

A similar example project file is given below for the Aleppo Help project, \aleppo\projdir\aleppohelp.alp. The main difference between this and the Boss Puzzle help file, is that the source, order, and output files are different. The file can be compiled by entering the following text on the command line.

    aleppo -epoc AleppoHelp.alp

A help database combining the topics for both applications may be generated by invoking aleppo using the comb.alp project file below, which is also stored in \aleppo\projdir\. Note that the sourcefile keyword is followed by both BossPuzzle and AleppoHelp rich-text source files and that the orderfile used is AleppoHelp.order. This means that the compiled file will contain all the topics from both files, and will have the same initial topic order as the stand-alone AleppoHelp.hlp database. In a normal help database an alternative order file would be used to order the combined topics.

    inputdirectory \aleppo\projdir\
    outputdirectory \aleppo\projdir\releases\
    outputfile BossAleppo.hlp
    sourcefile AleppoHelp BossPuzzle
    orderfile AleppoHelp.order
    graphicsdirectory \aleppo\projdir\
    workingdirectory \aleppo\projdir\temp\
    customizationfile \aleppo\projdir\uk.alc

Delivering help databases

Help databases are normally delivered to the target system as part of an EPOC .sis installation file. Files are typically placed in the same folder as the application with which they are associated. There is no standard location for help databases which are not associated with an application.

During development, authors can alternatively copy files to the EPOC system directly, using EPOC Connect.

Notes:
  • Help databases are, by default, read-only. Hence users must change the file properties, in the EPOC File | Properties menu, to overwrite previous versions of a help database on an EPOC machine.
EPOC SDK Home Glossary Indexes Previous Next Up


EPOC help project localisation issues

Contents

  • Overview
  • Localisation issues

Overview

There are several aleppo localisation issues/limitations of which authors should be aware. These are discussed in the following paragraphs.

Localisation issues

Firstly, the EPOC help database has traditionally used the CP1252 character set. This set can display all of the characters used in most European languages, but cannot be used to represent all of the characters which appear in other languages. While future releases of EPOC are expected to have support for the much larger 16 bit Unicode character set, users should be aware that:

  • Systems based on current and previous EPOC releases will not accurately display the characters.
  • Only 8 bit customisation files can be processed by aleppo. The main implication of this is that the text in tipeffects, noteffects and importanteffects cannot be in a far eastern language, e.g. Japanese. This is because Japanese has more characters than can be represented in an 8 bit character set. For the customisation file format see Customisation files.
  • The customisation file could use a definition for the body text of <bodystyle fontstyle=sansserif size=10>. This makes perfect sense for English characters, however it is not clear how aleppo should interpret a far-eastern character as san serif.
EPOC SDK Home Glossary Indexes Previous Up


Aleppo Reference

  • Command line syntax — aleppo
  • Rich-text source file — .rtf
  • Project file — .alp
  • Order file — .order
  • Customisation file — .alc
  • Help database structure
  • SGML file format


Command line syntax — aleppo

Contents

  • Purpose
  • Command line syntax

Purpose

Creates EPOC help databases based on information contained in a project file, order file, customisation file and rich text file.

For more information about these source files and:

  • Configuring a Help Project see Project files
  • Changing the topic display order see Order files
  • Customising the appearance of help files see Customisation files
  • Editing Rich text source files see RTF files

For examples demonstrating how to use aleppo, see Aleppo example projects.

Command line syntax

aleppo -epoc [-compress ] [-unicode] | -html project-file

For information about how to interpret the syntax, see BNF grammars.

Arguments
project-file | Defines the location of all source files used by the project, working directories, and target directories. Users should specify the project filename with extension. The extension .alp is suggested but not enforced.
-epoc | EPOC Help Database. Generate output database. Used with switch options compress and/or unicode.
-compress | Compressed. Generate both compressed and uncompressed databases.
-unicode | Unicode. Generate Unicode help database.
-html | HTML. Generate HTML Proofing copy.
Compatibility

Databases generated using the -epoc argument are compatible with all previous releases of EPOC.

The new aleppo features allow compressed and Unicode databases to be generated from the same source files as used to produce the standard database. These databases are not compatible with releases prior to EPOC Release 5.

Notes
  • The command line syntax may be obtained by typing aleppo on the command line.
  • Compressed databases, produced by specifying -compress on the command line, have a .c appended to the filename e.g. the compressed form of file.hlp is file.hlp.c.
  • Compression is only available for non-Unicode databases.
EPOC SDK Home Glossary Indexes Previous Next Up


Rich-text source file — .rtf

Contents

  • Overview
  • RTF file format
    • Topic elements
    • Paragraph styles
    • Character styles
    • Lists
  • Hypertext anchor
  • Graphics
    • EPOC help database
    • HTML proofing

Overview

This section describes the structure of an aleppo rich-text source file. In particular, it covers the different styles that can be used in the source rich-text file, and how they map text into each element of the final help database.

RTF file format

Section Contents

  • Topic elements
  • Paragraph styles
  • Character styles
  • Lists
    • Bulleted and numbered lists
    • Definition lists

A .rtf source file for EPOC help must have the following structure:

  • The first paragraph in Heading 1 style: its text will be the application name for all topics in the source file
  • each topic must begin with a Heading 2 style paragraph, and continue with other paragraphs as described below: the text of the Heading 2 paragraph will be the topic title

Comment style can be used anywhere within the source file to indicate author, date, or other such notes which should not be converted into the target format.

Topic elements

The main elements in a topic are

  • the title: comes from the text of the Heading 2 paragraph which begins the topic
  • the hypertext anchor name: this is represented by a paragraph in Hypertext Anchor style, which must occur immediately after the Heading 2 paragraph. The hypertext anchor name is used for the topic ordering list. The hypertext anchor need not be translated during localisation. This topic element is only required for those topics that are to appear in a defined order in the help database.
  • any synonyms: these come from the content of paragraphs in Topic Synonym style. A synonym paragraph may be placed anywhere within the topic, however only one synonym paragraph is allowed in each topic.
  • the body text: this comes from all other paragraphs in the topic

Paragraph styles

The paragraph styles provided by the epochelp template, and recognised by aleppo, are documented below.

Style | Keyboard Shortcut | Description
Heading 1 | ctrl+alt+1 | application name
Heading 2 | ctrl+alt+2 | topic title
Synonyms | ctrl+shift+S | words in this paragraph form a synonym list
Hypertext Anchor | cntl+shift+A | hypertext anchor name
Normal | ctrl+shift+N | normal body text
List Bullet |  | bulleted list item
List Number |  | auto-numbered list item
List Manual |  | manually-numbered list item
List Continue |  | continuation paragraph for a list item
List Bullet 2 |  | second-level bulleted list item
List Number 2 |  | second-level auto-numbered list item
List Manual 2 |  | second-level manually-numbered list
List Continue 2 |  | continuation paragraph for a second-level list item
Definition Term |  | an item to be defined
Definition Definition |  | defines an item
Tip | ctrl+shift+T | a tip
Note | ctrl+shift+O | a note; perhaps a warning
Important | ctrl+shift+I | important information; warning which must be heeded
Comment |  | notes that the author wishes to leave in the file — ignored by aleppo when processing the file

Apart from the names of these paragraph styles, no paragraph formatting information is conveyed from an RTF source document by aleppo.

Character styles

The character styles provided by the epochelp template, and recognised by aleppo, are documented below.

App Text | ctrl+shift+P | Application text, used for text on menus, dialogs, buttons, application views
Key Name | ctrl+shift+K | Used for keys which must be pressed by the user. This is not for entire strings entered by the user: see App Text for that.
Graphic Link | ctrl+shift+G | contains a directive which will be replaced by a graphic in the help database

Apart from the names of these character styles, and manually-applied bold, italic, subscript and superscript attributes, no character formatting information is conveyed by aleppo from an RTF source document.

Lists

Aleppo supports the following kinds of list

auto-bulleted | a suitable bullet character, e.g. blob or dash, picks out the head paragraph in each list item
auto-numbered | an auto-generated number, and optional punctuation, picks out the head paragraph in each list item
manually numbered | a manually entered number picks out the head paragraph in each list item
definition | a special kind of list used for a series of terms and their definitions

Bulleted and numbered lists

Auto-bulleted and auto-numbered lists are supported directly by Microsoft Word, and RTF. Use the List Bullet and List Number styles for the head paragraphs of each item. Word and aleppo choose the bullet type for you, and in the case of auto-numbered lists, manages the sequencing. This makes it easy to produce consistent and correct lists.

An item in an auto-bulleted list may have continuation paragraphs, in List Continue style, or nested lists, in one of the List ... 2 styles. This is not possible in Word, because the numbering on the head paragraphs is lost.

Aleppo also supports manually numbered lists. To enter a head paragraph in a manually numbered list, use the paragraph style List Manual; type the number, a tab, and then the text of the paragraph. Type the number in Roman format only, and do not type any punctuation: aleppo will generate the correct numbering and punctuation.

Definition lists

A definition list is used when a number of items need to be defined or explained. It is like a two-column table. The first column is a sequence of terms to be defined; the second is a sequence of definitions. The terms are quite short, and cannot be more than a single paragraph. The definitions are potentially long, containing multiple paragraphs. The table of list types above, for instance, would be a natural use of a definition list.

To enter a definition list, use paragraphs with style sequences of the form

Definition list styles

Hypertext anchor

A hypertext anchor may be defined by marking text below the topic heading in Hypertext Anchor style. The anchor can then be used by the order file to define the display order of the topic in the final database, see Order files. A hypertext anchor need not be defined, and if defined need not be used.

Topics for which it would be appropriate to have a hypertext anchor are those which it would be natural for a user to browse first, e.g. for quick start sections.

Notes
  • Hypertext anchors must be unique within an entire help database.
  • Hypertext anchors should be combinations of alphanumeric characters, periods and hyphens. An anchor such as agenda.entering-day-notes relates meaningfully to the application and the topic title, and shows a convention that can easily be adapted and followed.
  • Topics which are not referred to from the order list do not need hypertext anchors.
  • Hypertext anchors are unique identifiers for a topic, and need not be translated when the help source is localised.

Graphics

Section Contents

  • EPOC help database
  • HTML proofing

Graphics are indicated, in the RTF source, by a directive in Graphic Link character style. The directive is used to locate a graphic. The graphic will appear like a single, potentially large, character in the help database.

The form of the graphic link directive is illustrated in the following sentence: press archive=eikon name=darrow to scroll down. The directive specifies an archive, and a name.

The content of a Graphic Link directive is not subject to localisation.

EPOC help database

For the EPOC help database, the archive refers to an EPOC multi-bitmap file, and the name refers to the name of a bitmap within it. The name must be looked up in a .mbg. The algorithm used is as follows:

  • the archive is graphics-directory\archive.mbm, with its associated graphics-directory\archive.mbg header file
  • the name is looked up in the .mbg header file, and used to determine the index of the bitmap
  • the index is looked up in the .mbm to extract the bitmap data

If the relevant archive and name cannot be found in this way, another check is made:

  • the archive is a directory, graphics-directory\archive\
  • the name is looked up as a .mbm in that directory: graphics-directory\archive\name.mbm
  • the first bitmap from this .mbm is used

The graphics-directory is specified in the aleppo project file: see Project files.

More than one graphics directory may be specified in the project file: each one is searched for the graphic in turn.

HTML proofing

HTML requires JPEG files. These are generated by aleppo from .mbm files, as required. The .mbm bitmaps are found in the same way as for EPOC help databases.

EPOC SDK Home Glossary Indexes Previous Next Up


Project file — .alp

An aleppo project file specifies various files and directories as follows:

inputdirectory input-directory
outputdirectory output-directory
outputfile output-file
sourcefile source-file-list
[orderfile order-file]
graphicsdirectory graphics-directory
[workingdirectory working-directory]
[customizationfile customisation-file]

For information about how to interpret the syntax, see BNF grammars.

Arguments

input-directory

The directory containing all source RTF files.

output-directory

The target output directory for the new EPOC help database. Any directory may be specified. Typically \epoc32\wins\c\documents\ is used, so that Help databases can be viewed using an EPOC emulator.

output-file

The help database generated by aleppo. It is created in output-directory.

source-file-list

The rich-text source file/s to be compiled, which are located in input-directory.

One or more source files may be specified. The order of specification is irrelevant. The application name for each source file must, however, be unique. The names are specified without their .rtf extension.

order-file

The text file that defines the display order of topics in the output database, see Order files. The order file must be located in the input-directory. If no order file is defined, topics are ordered alphabetically.

graphics-directory

specifies a directory containing .mbm graphics, which are searched for using the algorithm described in Graphics.

An arbitrary number of graphics directories may be specified. An individual graphic is searched using the order specified in the project file.

working-directory

Directory for storage of temporary files created during aleppo conversion. If not specified, temporary files are generated in the same directory as the project file.

Temporary files are not deleted after aleppo is run.

customisation-file

The text file that defines how aleppo interprets styles in the rich-text source file, see Customisation files. If not defined, aleppo uses a default customisation file.
Notes
  • If any file name or directory is specified as a relative path, such as ..\graphics\, or \help\agenda\, then it is resolved against the drive and directory which was current when the aleppo command was issued.
  • All directories must be specified with a trailing \.
  • The order of the lines is not important, however it is important that the text file should not have any additional lines — this restriction includes empty lines.
  • The target format of the conversion is supplied to aleppo as a command line argument, see Aleppo command line syntax.
EPOC SDK Home Glossary Indexes Previous Next Up


Order file — .order

The order file specifies the order that selected topics are displayed in the output EPOC help database. Other topics are displayed alphabetically by topic title, and are displayed after the ordered topics.

The order file is a plain text file consisting of a list of order names.

order.name
another.order-name
something.else
...
topic_anchor.n

Each topic may, or may not, have an order name defined in the source .rtf — see Hypertext anchor. When the help file is generated, topics are re-ordered according to the position of their order name in the order file.

Notes
  • Topics referred to in the order list must have a hypertext anchor in the source rich text file.
  • Any text may be used for the order name.
EPOC SDK Home Glossary Indexes Previous Next Up


Customisation file — .alc

Contents

  • Overview
  • Customisation file syntax
  • Customisation file syntax — line by line
    • Body and title styles
    • List styles
    • Tip, note and important effects
  • Default customisation file
  • Conversion to HTML

Overview

The customisation file controls the appearance of the generated database. The following sections define the customisation file structure, and list the default customisation settings.

Customisation file syntax

[ <bodystyle [ fontstyle=font-style] [ size=font-size ] > ]
[ <titlestyle [ fontstyle=font-style] [ size=font-size]> ]
[ <listbullet1style bulletchar=bullet-symbol > ]
[ <listbullet2style bulletchar=bullet-symbol > ]
[ <tipeffects
 [text=”text” leftindent=indent [bold=yes | no] ]
| [archive=archive-name name=picture-name [leftindent= indent] ]> ]
[ <noteeffects
 [text=”text” leftindent=index [ bold=yes | no ] ]
| [archive=archive-name name=picture-name [leftindent=indent] ]> ]
[ <importanteffects
 [text=”text” leftindent=indent [ bold=yes | no ] ]
| [archive=archive-name name=picture-name [leftindent= indent] ]> ]

For information about how to interpret the syntax, see BNF grammars.

Arguments
font-style | The font style, must be either serif or sansserif.
font-size | The font size, in points.
bullet-symbol | The character value of the symbol to be used as the bullet.
text | Any text appropriate for the type of tip, note or important effect
indent | The amount of indent from the left hand edge of the topic window.
archive-name | The name of the graphic archive in which the effects graphic is stored.
picture-name | The name of the graphic to precede text style marked with one of the effects styles
Notes
  • All lines of the file, and indeed the file itself, are optional. The default customisation file settings are defined in a following section.
  • Graphics may be inserted in place of tip, important and note effects using the syntax above. However this will considerably increase the size of the final help database.

Customisation file syntax — line by line

Section Contents

  • Body and title styles
  • List styles
  • Tip, note and important effects

This section details the syntax of each line of the customisation file.

Body and title styles

Use the <bodystyle> tag to specify body style attributes.

<bodystyle
[ fontstyle= serif | sansserif ]
[ size=font-size ] >

This specifies the style of all text in body of a help topic, unless overridden by special effects as described below. fontstyle= allows you to specify either serif or sansserif. size= allows you to specify a size, in points.

The default is

    <bodystyle fontstyle=sansserif size=10>

Use the <titlestyle> tag to specify all attributes of the topic title style.

<titlestyle
[ fontstyle= serif | sansserif ]
[ size=font-size ]>

This specifies the style of title lines only. The fontstyle= and size= attributes have the same meaning as on the <bodystyle> tag.

The default is

    <titlestyle fontstyle=sansserif size=14>

List styles

Use the <listbullet1style> tag to specify attributes of first-level bulleted lists.

<listbullet1style [ bulletchar=bullet-symbol ] >

This specifies the bullet character and font to be used on all first-level bulleted lists. The default is

    <listbullet1style bulletchar=149>

which is a blob, in the standard paragraph font.

Use the <listbullet2style> tag to specify attributes of second-level bulleted lists.

<listbullet2style [ bulletchar= bullet-symbol ] >

This specifies the bullet character and font to be used on all first-level bulleted lists. The default is

    <listbullet2style bulletchar=149>

which is a blob, in the standard paragraph font.

Tip, note and important effects

The <tipeffects> tag specifies the effects for a paragraph in Tip style.

<tipeffects text="text" leftindent=index [bold=yes | no] >

Use text= to specify text, such as Tip:, to be used to indicate a tip. Use bold= to indicate whether this text should appear in bold, and use leftindent= to set the indentation of the paragraph text from the left margin: this indent should be a little bigger than the length of the word specified in the tip text.

The default is

    <tipeffects text="Tip:" bold=yes leftindent=36>

giving the text Tip: in bold, with a half-inch indent.

The <noteeffects> tag specifies the effects for a paragraph in Note style.

<noteeffects text="text" leftindent=index [ bold=yes | no ] >

Use text= to specify text, such as Note:, to be used to indicate a note. Use bold= to indicate whether this text should appear in bold, and use leftindent= to set the indentation of the paragraph text from the left margin: this indent should be a little bigger than the length of the word specified in the note text.

The default is

    <noteeffects text="Note:" bold=yes leftindent=36>

giving the text Note: in bold, with a half-inch indent.

The <importanteffects> tag to specifies the effects for a paragraph in Important style.

<importanteffects text="text" leftindent=index [ bold=yes | no ]>

Use text= to specify text, such as Important:, to be used to indicate an important note. Use bold= to indicate whether this text should appear in bold, and use leftindent= to set the indentation of the paragraph text from the left margin: this indent should be a little bigger than the length of the word specified in the important note text.

The default is

    <importanteffects text="Important:" bold=yes leftindent=60>

giving the text Important: in bold, with a 5/6-inch indent.

In EPOC release 5 and greater; paragraphs marked with effect styles may alternatively be preceded by a graphic (rather than text). The help database stores a graphic for every paragraph marked with an effects style. Hence the benefits of using a graphic must be weighed against the resulting increase in help database size, prior to using this feature.

The effect definitions are as shown below, where the graphic definition is the same as used for inserting a graphic in the source rich-text file.

<tipeffects archive=archive-name name=picture-name [leftindent=index]>
<noteeffects archive=archive-name name=picture-name [leftindent=index]>
<importanteffects archive=archive-name name=picture-name [leftindent=index]>

The leftindent= field defines the indentation of the paragraph text from the left margin. The field is optional, and defaults to a width equal to that of the graphic. leftindent=0 implies that the text is flush with the left margin.

Note:
  • Graphics defined in the customisation file for Tip, Important and Note effects are not shown in HTML output format.

Default customisation file

The following file contains all aleppo’s defaults. It is suitable for running aleppo to generate help text in UK or US English locales.

    <bodystyle fontstyle=sansserif size=10>
    <titlestyle fontstyle=sansserif size=14>
    <listbullet1style bulletchar=149>
    <listbullet2style bulletchar=149>
    <tipeffects text="Tip:" bold=no leftindent=36>
    <noteeffects text="Note" bold=yes leftindent=36>
    <importanteffects text="Important" bold=yes leftindent=60>

Conversion to HTML

This format is available for proof-reading only. No customisation is possible.

EPOC SDK Home Glossary Indexes Previous Next Up


Help database structure

Contents

  • Overview
  • Database Components

Overview

This topic discusses, in detail, the structure of an EPOC help database.

Database Components

An EPOC help database has the following structure

  • a database is a collection of topics
  • each topic has a title, a body which explains the topic, an application name, and some synonyms to aid in look-up
  • topics associated with no particular application are artificially given the application name General
  • all the topics for a particular application are built into one database; one database may contain topics for one or more applications
  • the first few topics in a database have a customised order, so that users can see the most important things first by browsing through the database
  • after the first few ordered topics, all other topics are ordered alphabetically, which makes them more suitable for searching than for browsing
  • help is not context sensitive e.g. the help system does not automatically associate the desired help information with the currently open program/s.

The database is designed to be searched. Thus, a search on free form will produce a list of all help topics with the phrase free form in either the title, the synonym list, the body text, or the application name. The application name is stored in the database with an exclamation mark after it, so that a search on Agenda! will find only topics whose application name is Agenda.

The elements of a topic merit more explanation:

application name

the application associated with a help topic. Stored in an invisible column in the database, with an exclamation mark following. Allows all topics referring to a given application to be found by searching on the name, followed by an exclamation mark.

All topics must have an application name. An application name such as General is used to describe topics not associated with any application.

title

a single paragraph giving the title of the topic. Topic titles must be unique within the context of a particular application.

body

the body text, description or explanation of the topic. The body can be composed of any number of paragraphs, whose formatting is controlled by paragraph style name. A paragraph may contain ordinary characters, or graphics — see Graphics.

synonyms

other words which a user might use for searching, that are not given in the body text, or title of the topic. Stored in an invisible column in the database, synonyms are used for words that the user may associate with a particular feature, but that may not be required or suitable in the topic’s text, e.g. diary for Agenda.

The structure is represented by an SGML format which is documented in SGML file format. For a help author, the more relevant format is the RTF source.

EPOC SDK Home Glossary Indexes Previous Next Up


SGML file format

Contents

  • Overview
  • Source files
  • epochelp doctype
    • Topic structure
    • Body
    • Paragraph text
  • Graphics

Overview

This chapter is superfluous to the needs of most help authors. It defines the epochelp SGML doctype, for the following purposes:

  • to act as a reference for the capabilities of aleppo
  • to define implicitly the functions of the RTF-to-SGML converter
  • to define implicitly the input data used by the SGML-to-target database converters

The specification attempts to be exhaustive.

Example SGML pipeline

For information about how to interpret the syntax, see BNF grammars.

Source files

The epochelp SGML source comprises

  • one or more files of the epochelp SGML doctype, each of which contains a list of topics
  • one or more .mbm files
  • an auxiliary file which lists all .mbm files used by the SGML-to-target converter

epochelp doctype

Section Contents

  • Topic structure
  • Body
  • Paragraph text

A file in the epochelp doctype has one or more help topics in it. Each topic has title, application name, synonyms, possibly order information, and a body.

Topic structure

Each help topic contains the following tags:

<topic application=appname [ order=number ] >
<topic-title>paragraph-text</topic-title>
topic-body
[ <synonyms>words</synonyms> ]
</topic>

The <topic> tag and its end-tag delimit a topic. The topic must begin with a title.

The application= attribute specifies the application name.

If the order= attribute is specified, then the topic is among the ordered topics as specified by the order file. Otherwise, the topic is unordered — i.e., it is ordered alphabetically with all other unordered topics, after all the ordered topics.

The <synonyms> tag and its content may occur anywhere within the body.

Body

The body consists of a number of paragraphs. Some paragraphs may be in lists. Definition lists are supported. Tables are not supported.

<p [ style=style-name ] >paragraph-text</p>
|
<ul> | <ol>
<li [ seq=number ] >paragraph-text</li>
[ <p>paragraph-text</p> ... ]
...
</ul> | </ol>
|
<dl>
<dt>paragraph-text</dt>
<dd>paragraph-text</dd>
[ <p>paragraph-text</p> ... ]
...
</dl>

If style-name is not specified, it defaults to normal. Other allowable values are tip, note, important.

There are two types of itemised list: unordered (automatically bulleted), and ordered (auto-numbered). Each of them consists of a sequence of items which, in addition to a head paragraph, may have continuation paragraphs — which would have been List Continue style in the original RTF.

The seq= attribute is only valid for ordered lists, and allows a sequence number for an item to be explicitly specified. In the absence of a seq= attribute, the item’s number is one greater than the previous number, or 1 for the first item.

A definition list contains entries of the form term, definition. The term may have only a single paragraph. The definition may have an arbitrary number of paragraphs. The converter may convert a definition list into either a two-column table, or some suitable list format with a small hanging indent for the definition.

Lists may be nested. Numbering in an enclosing list is not affected by a numbered nested list.

Paragraph text

Paragraph text consists of a sequence of characters. The sequence may contain whitespace, SGML entities, character formatting tags, or graphics directives. Supported entities are

&amp; | ampersand
&lt; | less-than sign
&gt; | greater-than sign
&nbspace; | non-breaking space
&nbhyphen; | non-breaking hyphen
&break; | forced line break
&tab; | tab

Supported tags are

<b> | bold
<i> | italic
<sup> | superscript
<sub> | subscript
<cs style=style-name> | character style
<graphic index=index-number> | graphic from EPOC MBM

Supported character styles are app text, key name.

Graphics are looked up by index from the graphics auxiliary file: see below.

Graphics

During conversion of source RTF into epochelp SGML, aleppo processes all graphics directives and identifies the .mbm file and the bitmap number of each graphic referred to. It also identifies the .mbm files and bitmap numbers of graphics defined in the customisation file, if any, for important, note and tip effects. The locations of the graphics are noted in a graphics auxiliary file which is, essentially, a part of the SGML help database.

This graphics auxiliary file is a text file which contains lines of the form

<graphic index=index archive=archive name=name bitmapfile=bitmap-file-name bitmapindex=bitmap-index>

In each such line,

  • the archive= and name= attributes match the attributes specified in the Graphic Link directive in the RTF source
  • the bitmapfile= attribute gives the full path to the EPOC .mbm file containing the graphic bitmap
  • the bitmapindex= attribute gives the index to the bitmap, within the .mbm file
  • the index= attribute is allocated from 1, and is the key to the entry, enabling it to be looked up efficiently from the SGML source when a <graphic> tag is processed

This information is sufficient to allow the SGML-to-target converter to process graphics without any further searching.

EPOC SDK Home Glossary Indexes Previous Up


Deploying Applications with Makesis

Makesis packages applications into EPOC installation files, which enable end users to install and remove applications using a simple and consistent interface.

The guide material includes an introduction to installation methods in EPOC, an overview of the packaging process, and a set of examples.

The reference material covers the makesis command line syntax, and the format of its project control file.

Users should start by reading the guide material, and refer to the reference as necessary.


Makesis Guide

  • Installing EPOC applications
  • Preparing applications for installation
  • Makesis example projects


Installing EPOC applications

Contents

  • Overview
  • Installation and removal from the end user's perspective
    • Installation
    • Removal
    • The Control Panel
    • EPOC Connect
    • Installation failure
  • Installation from the developer's perspective
    • EPOC Installation Files
    • Compatibility issues
    • Installation without EPOC Connect

Overview

This section provides a comprehensive discussion of the EPOC installation process. Application installation and removal are described from both the end user and application developer’s perspective.

Installation and removal from the end user's perspective

Section Contents

  • Installation
  • Removal
  • The Control Panel
  • EPOC Connect
  • Installation failure

Installation

Application installation consists of moving files from one place, e.g. on a PC or the Internet, to the correct folders on an EPOC machine. There are three ways for end users to install an application on an EPOC machine:

  • install the EPOC installation .sis file directly from a PC, using EPOC Connect
  • copy an EPOC installation file into the EPOC machine, from a PC or the Internet, then use the control panel’s Add/remove program to install components from the .sis file. Note: see The add/remove program for a discussion on compatibility issues related to the Add/remove program.
  • copy files directly into the correct target folders. This option is not recommended for end-users.

The following diagram illustrates the two recommended methods for installing applications using the EPOC installation procedure:

EPOC installation files are generated by the makesis tool, and provide the most simple method for users to install applications on EPOC machines. For documentation of the makesis command line syntax, see Create software installation file — makesis.exe.

Notes
  • Applications with high build numbers replace, without warning, applications with lower build numbers.
  • The control panel’s Add/remove program does not allow low build number versions of a program to be installed over a higher build number version. In order to do so, the installed version must first be removed.
  • Installation from a PC allows over-writing of high build number versions of an application by low build number versions, but only upon acknowledgement of a confirmation dialog.
  • Application installation information is stored in residual .sis files, or stubs, which are created in the \system\install\ folder of the EPOC machine’s destination drive during installation. These files should not be deleted by the user, as they provide the information needed by the control panel to display the list of installed programs, including program name, language, and build numbers. They also provide the dependency information required when removing programs, including information on the files which should be deleted and their location.

Removal

Application removal consists of deleting files that are no longer needed from an EPOC machine. There are two ways to remove an application:

  • if the application was installed from a .sis file using a recommended method, then it can be removed using the Add/remove icon on the control panel.
  • if the application was installed by directly copying files, the files must be specifically located and deleted.

Copying and deleting files is recommended only during application development. Normally, applications should be installed or removed using EPOC’s installation facilities.

The Control Panel

The Add/remove icon on the EPOC control panel invokes EPOC’s install/uninstall application. The application’s interface lists all installed programs, and provides options to remove installed programs, and to add new programs.

The end user may install a program by selecting the Add new button on the Add/remove dialog. This invokes a file browse dialog, which allows the user to select the EPOC installation file to install. Alternatively, users may directly install a selected installation file by opening its icon in the system screen. Both methods have the same effect.

Removing an application using the Add/remove dialog deletes all application components, excepting those required by other EPOC-installed applications. The uninstall process first ensures that a component is not used by another application. This includes applications installed on another disk. If any components are used by another application they are not deleted.

EPOC Connect

EPOC Connect can be used to install application files from a .sis file on a PC, without transferring the .sis file itself to the target machine. This provides a convenient form of installation from a PC. It also avoids the need to use target machine disk space for the .sis file.

In order to install software from a PC, all the end user must do is double-click a .sis file from Windows Explorer. EPOC Connect recognises the file type, and launches the installation program. Alternatively, EPOC Connect may be used to install the .sis file from a command line.

Installation failure

If an installation is aborted, the partially installed application will be marked as Partial in the control panel's list of installed applications. The end user can either re-install the application, or can remove it then start again. Note that when re-installing using the control panel’s Add/remove program, the user will be given the option of continuing with the installation rather than carrying out a complete re-installation.

Installation from the developer's perspective

Section Contents

  • EPOC Installation Files
  • Compatibility issues
    • epocinst
    • The add/remove program
  • Installation without EPOC Connect

EPOC Installation Files

EPOC Installation (.sis) files are the starting point of installation for end users — whether they install from a PC using EPOC Connect, or whether they upload the .sis file to their EPOC machine and install using the control panel. A developer therefore must be able to make and deliver .sis files for installation.

.sis files are constructed by the makesis tool, as described in Create software installation file — makesis.exe. They contain:

  • a compressed form of the files that are to be installed, assembled by makesis from various directories on the developer’s PC
  • specifications for the directories on the target EPOC machine to which to install these files
  • specifications about which common libraries are needed by the application: these specifications are used to ensure that, when the application is removed, common libraries are deleted only if they are not needed by the remaining applications
  • specifications about language-specific files, so that a .sis file may contain the materials needed to install in several languages, but only one language variant is installed

All these specifications are passed to makesis by a control file with a .pkg extension.

Compatibility issues

epocinst

epocinst is a component of EPOC Connect which allows the direct installation of .sis files from a PC connected to an EPOC machine. It was not available in the first release of EPOC Connect, also badged as PsiWin 2.0. To allow direct installation, users with this release of EPOC Connect must either upgrade to PsiWin version 2.1 or 2.2, or install epocinst separately. PsiWin upgrades can be download free from the Psion website.

In order to find out whether a copy of EPOC Connect needs to be upgraded, the end user should select the My EPOC machine icon in Windows Explorer. If the Install New Program option is not available under the EPOC menu, epocinst must be set up by running its installation program setup. Note that in some older versions of EPOC Connect the Windows Explorer icon is My Psion, and the menu to select is Psion.

It is recommended that setup be supplied by developers in a suitable form as part of their installation package, for example in \epocinst\setup.exe and that text be included in the installation instructions informing end users with PsiWin 2.0 who have not yet run setup that they should do so.

The add/remove program

The Add/remove program, in the EPOC machine's Control panel is supplied on the EPOC release 5 ROM. However, it is supplied for EPOC release 3 and 4 as part of the Message Suite, and it is not available on EPOC release 1 or 2.

Installation without EPOC Connect

An issue for developers is how end users without access to a PC which is capable of running PsiWin 2.x can install software.

There are several possibilities:

  • upload from Web using browser
  • copy from another EPOC machine using Infrared or a Memory disk which contains the software
  • dial-up to a BBS using the Comms application, and upload using XMODEM/YMODEM
  • use another desktop connectivity package, e.g. EPOC MacConnect
  • copy files using PsiWin 1.x

Using any of these methods, the easiest general solution to installing a complex application is for the user to:

  • copy setup, supplied with the EPOC SDK in \epoc32\release\marm\rel\, and run it on the EPOC machine. This installs the Add/remove icon on the control panel. The user may run setup by opening its icon in the system screen. This will install all necessary files into the appropriate directories. setup will delete itself after it has executed.
  • copy the software package's .sis file, and install by opening it on the EPOC machine.
EPOC SDK Home Glossary Indexes Previous Next Up


Preparing applications for installation

Contents

  • Overview
  • The process

Overview

This topic provides a brief summary of the process of preparing an application for installation.

The process

The diagram below provides a brief overview of the installation process, and shows some of the file types which might be bundled in an EPOC .sis installation file. The types of files included are dependent on the programming language, and on the nature of the application. Installation files may also bundle other installation files.

The makesis package file (.pkg) defines the location of application files on the source PC and the target EPOC folders in which they are to be installed. The process of preparing applications for installation is therefore:

  1. Develop an application using any of the EPOC SDKs, see the documentation for your development SDK.
  2. Debug/test application on EPOC emulator.
  3. Ensure that all components of the application are in native EPOC format, see sections on font, image and sound file utilities.
  4. Create a package file, see Package file format.
  5. Run makesis using the package file, see Create installation file.
EPOC SDK Home Glossary Indexes Previous Next Up


Makesis example projects

Contents

  • Overview
  • Installing a simple program
  • Installing a multi-lingual program
  • Running a file on EPOC machine during installation
  • An installation incorporating other installation files

Overview

The makesis example projects demonstrate how .sis installation files are built using the makesis tool. They are provided with all SDKs which supply the EPOC Tools and Utilities documentation, see directory \epoc32ex\adk\.

The examples are primarily concerned with the configuration of .pkg files, see Package file format, as they define the components which are bundled into the .sis file, and hence the files which are ultimately installed on the target EPOC system.

The example applications are trivial, and are included purely for the demonstration of makesis.

Installing a simple program

The minimal application ikhello is used to demonstrate the most basic makesis functionality. The application prints Hello World! on the screen in English. It is comprised of two files ikhello.app and ikhello.rsc, located in the directory \epoc32ex\adk\, which must be installed into \system\apps\ikhello\ on the target machine. Rather than manually creating this directory and copying the files into it, a .sis file may be produced to automate the installation procedure.

makesis flowchart - installation of a simple program

The package file ikhello.pkg (see Package file format) defines the source files to be bundled in the .sis file, and the folder location to which the files are to be copied.

    #{"Minimal application"},(0x01000508),1,0,0
    ; Only two files to install for the minimal application
    "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.app"
    "\epoc32ex\adk\ikhello.rsc"-"!:\system\apps\ikhello\ikhello.rsc"

The first line is the installation header, which defines the application’s name, Minimal application, UID3 (0x01000508), major and minor build numbers (1 , 0) and the variant number (0). The second line is a comment. The final two lines specify the files which should be installed and their destination on the target machine.

Notes
  • There is no initial language line because the application only supports UK English (the default language).
  • The UID is a unique number, used by EPOC to specify the application. For more information on the UID, review the documentation for your SDK (C++, OPL, Java).
  • The application's major and minor build numbers are required for version control (eg. AppName 3.1 specifies a major build 3, and minor build 1.)
  • The variant number is not currently used by makesis, and may be omitted. Eventually EPOC applications may require a variant number, to distinguish between application builds for different target platforms.
  • Lines preceded by a semicolon are comments — not used by makesis as part of the build process.
  • Since the target drive is (probably) not known by the developer, it must be selected by the user during installation. This is indicated in the .pkg file by specifying ! as the destination drive.
  • If directories in the installation path do not exist, they are automatically created by EPOC Install.

To create the installation file ikhello.sis, invoke makesis on the package file:

    makesis ikhello.pkg

ikhello.sis can then be installed on the target machine using one of the methods described in the topic Installing EPOC applications. After installation the application may be run by selecting the ikhello icon on the extras bar.

Installing a multi-lingual program

This example demonstrates how to configure a .pkg file for installing applications supporting more than one language. It uses the same application as in the previous example, but prints Hello World in English, French or Italian, depending on the language selected by the user during installation.

EPOC supports different languages through the use of resource files, see Resource compiler). Each resource file contains, in a different language, the text used by the application (e.g. in menu options). The .sis file bundles the resource files belonging to all languages, but EPOC Connect transfers only the file supporting the language selected.

The following diagrams show the process more clearly. The ikhello application file can link to one of three resource files produced by the resource compiler. When makesis is invoked with the appropriate package file, ikhellom.pkg, all four files are bundled into the ikhellom.sis file.

Installation flowchart - packaging a multi-lingual program

During installation, EPOC Connect selects the resource file associated with the user’s preferred language. Since ikhello.app can only link to a file with an extension .rsc, the file’s extension is changed when it is installed. The installation process is shown in the diagram below.

Installation flowchart - installing a localised version of a multi-lingual program

The package file ikhellom.pkg defines the source files to be bundled in the ikhellom.sis file, and the folder locations to which the files are to be (optionally) copied.

    &EN,FR,IT
    #{"Minimal application", "Application minimale", "Applicazione minima"},(0x01000508),1,0,0
    "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.app"
    {
    "\epoc32ex\adk\ikhello.ruk"
    "\epoc32ex\adk\ikhello.rfr"
    "\epoc32ex\adk\ikhello.rit"
    }-"!:\system\apps\ikhello\ikhello.rsc"

The package file is similar to that in the preceding example. The notes below cover only the additional features.

Notes
  • The first line specifies the language variants which are supported (see Languages).
  • The second line, the installation header, includes the component name, translated into the relevant languages. The order of the headings must be the same as the language declaration in the first line.
  • The third line specifies the application file to install; unlike the resource files, this does not depend on the language chosen.
  • The final component lists the resource files and their destination. Of the three files specified, only one will be installed (depending on the language chosen by the user during installation). Consequently there is only one destination file.

To create the installation file ikhellom.sis, invoke makesis on the package file:

    makesis ikhellom.pkg

Running a file on EPOC machine during installation

This example demonstrates how to configure a .pkg file so that a text file is viewed on the PC, and a file is automatically run on the target platform, during installation. It uses the same application as in the first example, but additionally displays a license agreement during installation. Also, during installation of the application, an EPOC Word document is run on the target machine.

The following diagrams show the process more clearly. The sis file bundles the same ikhello application and resource files as in the first example. It also bundles a license agreement and de-installation notice.

Installation flowchart - packaging the program and license agreement

As shown in the diagram below, the license agreement is displayed during installation, but is not copied to the target machine. The de-installation notice is transferred to the target machine, and is run when the application is installed/removed — see Installing applications.

Installation flowchart - installing the program with license agreement

This package file used for this example, ikhellol.pkg, is shown below. The following notes cover only file features which are additional to the previous examples.

    #{"Application with licence"},(0x01000508),1,0,0
    "\epoc32ex\adk\ikhellol.txt"-"",FT,TA
    ; Files to be installed - only three, no language variants
    "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.app"
    "\epoc32ex\adk\ikhello.rsc"-"!:\system\apps\ikhello\ikhello.rsc"
    "\epoc32ex\adk\ikhellod"-"!:\system\apps\ikhello\ikhello-deinstall",FR,RI
Notes
  • The second line specifies the file to be displayed during installation. The arguments specify that the file is text to be displayed during installation but not installed (FT), and that EPOC Connect should display a Yes/No dialog instead of the default Continue (TA). The dialog aborts if No is pressed. Since the file is not installed, the destination is represented by empty quotes.
  • The final line specifies a file to be installed and run on the target EPOC machine using the argument FR. The argument RI indicates that the file is to be run only during installation.
  • To run, the file specified in the final line must be in EPOC native format — e.g. an EPOC Word document.
  • It is possible to specify that an installed file should run during removal. However, since the file is deleted in the process, this facility should only be used for small, fast executing, files: for example, a file to clean up the registry or other parts of the system.

To create the installation file ikhellol.sis, invoke makesis on the package file:

    makesis ikhellol.pkg

An installation incorporating other installation files

This example demonstrates how to configure a .pkg file so that the new installation file bundles other .sis files. This feature might be used for packaging different parts of an application, e.g. user interface and engine, prior to generating a complete installation file for the whole application. It might also be used as a means of preventing components from being overwritten by earlier versions.

makesis flowchart - bundled sis file

The diagram above illustrates the bundling process. The ikhellos package file specifies an installation file which includes the BossPzzl.sis file. During installation, shown below, BossPzzl.sis is extracted from the ikhellos.sis file and its contents, BossPuzzle.hlp, automatically installed.

Installation flowchart - installation of bundled sis file

The package file used for this example, ikhellos.pkg, is shown below. The following notes cover only file features which are additional to the previous examples.

    #{"Minimal application"},(0x01000508),1,0,0
    ; Ikhello installation with an embedded .sis file
    "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.app"
    "\epoc32ex\adk\ikhello.rsc"-"!:\system\apps\ikhello\ikhello.rsc"
    ; Component .sis files
    @"\epoc32ex\adk\BossPzzl.sis",(0x01000508)
Notes
  • The final line specifies the file to be installed, BossPuzzle.sis, and a UID. A help file has no UID. Since makesis requires a UID to build the installation file, a dummy UID has been used.
  • This example is provided for illustration, and in no way demonstrates the recommended method for installing a help file.

To create the installation file ikhellos.sis, invoke makesis on the package file:

    makesis ikhellos.pkg
EPOC SDK Home Glossary Indexes Previous Up


Makesis Reference

  • Create software installation file — makesis.exe
  • Package file format — .pkg


Create software installation file — makesis.exe

Contents

  • Purpose
  • Command line syntax

Purpose

Makesis creates software installation packages based on source PC/target EPOC file locations defined in a .pkg, package file. Unless explicitly specified, the name of the new installation file will be the same as the package file, but with the extension .sis. See Package file format for information on .pkg file format.

For more information about application installation, and for examples demonstrating how to use makesis, see Installing EPOC applications and Makesis example projects respectively.

Command line syntax

makesis [-v ] [-h ] [-s ] source [destination]

For information about how to interpret the syntax, see BNF grammars.

Arguments
-v | Verbose. Prints output from makesis to the screen
-h | Help Page. Shows makesis usage information
-s | Stub. Generates a residual .sis file for each language defined in the package file. The extension is .s xx, where xx is the number of the language, e.g. .s10.
Notes
  • EPOC uses stub files to determine the files associated with installed applications. The facility to produce stub files is needed only by ROM builders — to prevent users from installing low build number versions of an application over a higher build number version in ROM.
EPOC SDK Home Glossary Indexes Previous Next Up


Package file format — .pkg

Contents

  • Overview
  • Languages
  • Installation header
  • Language independent files
  • Language dependent files
  • Requisites
  • .sis component files
  • Comments

Overview

A .pkg file is a text file which contains installation information for applications or files. It consists of the following components, some of which may be omitted:

  • the languages supported
  • the installation header, including the name of the component to be installed and its build and version information
  • non-language dependent files to install
  • language-dependent files, of which only one will be installed
  • requisite files
  • component .sis files
  • comments

The following topics define the structure of each of these components. For information about how to interpret the syntax, see BNF grammars.

Languages

The language line specifies which languages are supported by the component. Languages are identified by a two character code. The line may be omitted; if so, UK English is assumed by default. The language line must be specified before any languages section, see Language dependent files below. Its format is as follows:

&Language_1,..., Language_n

For example:

    &EN,FR,IT

The following languages are supported:

EN | UK English | SG | Swiss German
FR | French | PO | Portuguese
GE | German | TU | Turkish
SP | Spanish | IC | Icelandic
IT | Italian | RU | Russian
SW | Swedish | HU | Hungarian
DA | Danish | DU | Dutch
NO | Norwegian | BL | Belgian Flemish
FI | Finnish | AU | Australian English
AM | US English | BF | Belgian French
SF | Swiss French |  |

Installation header

The installation header must be included before all other items, except the language line, if one is specified. Its format is:

#{"Component Name for language1",..., "Component Name for language n"},(ComponentUID),Major,Minor,Variant,Arguments
Arguments
ID | The ID flag is present but not implemented. If specified, indicates that a copy of the component may be distributed to another machine. Otherwise the component cannot be distributed.
IU | Should be specified if the application's build variant is Unicode. EPOC Install will not install IU flagged SIS files at present.

For example;

    #{"Minimal application", "Application minimale", "Applicazione minima"},(0x01000508),1,0,0

All numbers can be hexadecimal.

Notes
  • The UID identifies the sub-subtype of the component which is to be installed, that is, its final UID. For more information about the role of UIDs in EPOC, view the appropriate section in your SDK.
  • The component name is language dependent. It is used to identify the component in the installation dialogs and in the list of installed programs in the control panel's Add\remove program.
  • The number of component names must equal the number of languages specified in the languages line, and should be in the same order.
  • The variant number is currently not used by makesis, and may be omitted. For more information see Requisites, below.

Language independent files

Files which will be installed regardless of the language variant selected by the end user, are specified as follows;

"Source"-"Destination"[,Arguments]

For example:

    "\epoc32ex\adk\ikhello.app"-"!:\system\apps\ikhello\ikhello.app"

The source is the path and filename for the source file on the PC. The destination is the target path and filename on the EPOC machine. A destination must be specified unless the file is a text file. Text files, as indicated by an FT argument, are not installed. Consequently their destination is irrelevant, and may consist of empty quotes.

Note that EIKON applications must be built to \system\apps\appname\appname.app. Other component files which form part of the application, for example resource files and application information files, should reside in the same directory as the application. If the \appname\ directory does not exist, it will be created.

If the file must be installed on a specific drive, e.g. on c: for RAM, d: etc. for removable media, the drive letter should be specified. Otherwise !: may be used to indicate that the drive can be specified by the user at installation time.

Files are installed in the order in which they are specified in the .pkg file.

If the file is used by other components, e.g. if it is a shared DLL for instance, you may want to avoid the possibility of it being overwritten by an earlier version. In this case, do not specify the file in this section. Instead, create a separate .sis file for the shared file, including appropriate major, minor build numbers in the installation header, and include the new .sis file in the .sis component files section, described below.

An optional comma-separated list of arguments following the destination file may be specified, to describe the type of file and how it will affect the installation or removal process.

Use one of the following arguments to describe the type of file to install:

FF | Standard file. This is the default.
FT | Text file whose contents will be displayed in a dialog box during installation. The dialog will contain either the default Continue button, or Yes and No buttons, depending on other arguments specified. Text files are not installed on the target machine.
FN | A file which does not yet exist, so is not included in the .sis file. It is created by the running application and will be deleted when the application is removed. The name assigned to the source file is unimportant. Note that such files will not be deleted when upgrading to a later version. This ensures that such files as .ini files, which store application preferences, are not lost in an upgrade.
FR | A file which will be installed on the EPOC machine, and run during installation and/or removal — depending on arguments RI, RR, RB described later. The file could be an executable, a document or an application.

Use one of the following arguments for a text file, i.e. after FT has been specified, to determine how the text file dialog should be cancelled, and how cancellation should affect the installation:

TC | Use a Continue button in the text file dialog. When the user presses this button the dialog is cancelled and the installation continues. This is the default.
TS | Use Yes and No buttons in the text file dialog. If Yes is pressed, the dialog is cancelled and the installation continues. If No is pressed, the dialog is cancelled, and the installation will continue, but the next file specified in the .pkg file will not be installed.
TA | Use Yes and No buttons in the text file dialog. If Yes is pressed, the dialog is cancelled and the installation continues. If No is pressed, the installation is aborted.

One of the following arguments may be specified for a file which will be run during the installation or removal process, i.e. after FR has been specified. If the file is a document, the appropriate application will be launched. For example, on installation, you may want to open a Word document providing information about the new application.

RI | Run the file during installation only. This is the default.
RR | Run the file during removal only. The file is deleted during removal, and hence should be able to run quickly — e.g., to clean up registry. A document should not be run during removal, as it will be deleted before it can be displayed.
RB | Run the file during both installation and removal. The file is deleted during removal, and hence should be able to run quickly.

Language dependent files

This format is used to specify a list of files, of which only one will be installed, depending on the language selected by the user during installation:

{
"Source FileName"
...
"Source FileName"
}-"Destination"[,Arguments]
Notes
  • The opening brace denotes the start of the block of language-dependent files.
  • The order of the files should be the same as the order in which the languages were specified in the languages line
  • The number of files specified must be the same as the number of languages supported.
  • The arguments are the same as for the previous section

This format will commonly be used to specify lists of resource files. Like applications, resource files must be installed to \system\apps\appname\appname.rsc. If the appname directory does not exist, it will be created.

For example;

    {
    "\epoc32ex\adk\ikhello.ruk"
    "\ epoc32ex \adk\ikhello.rfr"
    "\ epoc32ex \adk\ikhello.rit"
    }-"!:\system\apps\ikhello\ikhello.rsc"

Here, three compiled resource files are specified, but only one will be installed on the target machine. Whichever language is chosen, the resource file will be installed as ikhello.rsc.

Requisites

A requisite file is one that is required by the component which is being installed. It must be present on the target machine and its major and minor build numbers must be the same as, or greater than, those specified — otherwise installation will fail. Its name does not need to match the name specified, as it is identified by UID.

A requisite file is specified in the following way;

(UID),Major,Minor,Variant,{"Requisite Name1", " Requisite Name2"}

For example;

    ; Depends on STDLIB being installed
    (0x100002c3), 1, 0, 14, {"Standard C Library"}
Notes
  • Installation currently ignores the variant number, and this field may be omitted in the requisite definition.
  • When de-installation of a component involves the removal of another component's requisite files, the user is warned that continuing may prevent other programs from working.
  • Requisite definitions use information specified in the installation header of the target component’s .pkg file, see Installation header.

.sis component files

One or more .sis component files may be specified, to be installed as part of the installation. They are specified in the following way;

@"ComponentFile.sis",(UID)

For example;

    @"STDLIB.SIS",(0x100002c3)

The component filename must have a .sis extension. If more than one .sis file is specified, they are installed in the order in which they are listed. The UID may be found in the installation header in the .sis file's .pkg file.

Comments

Lines of comment are preceded by a semi-colon. They are ignored by makesis.

EPOC SDK Home Glossary Indexes Previous Up


Application Resource Tools

The application resource tools include rcomp, the resource compiler, and aiftool, the application information file compiler.

The two types of resource file define the application’s properties and appearance in EPOC applications. The aiftool information is relevant to developers using any programming language. The resource compiler is useful for C++ and OPL developers, however it is of less relevance to Java developers, as they cannot access the EIKON framework to build menus, toolbars etc.

The guide section includes an overview topic covering the purpose of resource and application information files. It also contains introductory topics for resource and application information files, consisting of overview and example material.

The reference material covers the command line syntax for rcomp, its batch file wrapper eikrs.bat, and aiftool. The section also contains a definition of the file structure for the raw text resource files compiled by each tool.

Users should start by reading the guide material, and refer to the reference as necessary.


Application Resource Tools Guide

  • About application resources in EPOC
  • Resource compiler
  • Application information files
  • Examples - aiftool


About application resources in EPOC

Contents

  • Overview
  • Customise the user interface
  • User resources
  • System resources
  • Java and resource files
  • File types reference

Overview

In EPOC, much of the information that defines the appearance, behaviour and functionality of an application is stored in a resource file — external to the main body of the program. This is unlike some other programming environments, in which a single executable contains all the code and information used by the application.

The two types of resource file used in EPOC are application information files and resource files. The difference between these file types is that application information files define application behaviour within the system context, while ordinary resource files define behaviour within an application.

Resource files are accessible by developers using any of the EPOC programming environments, however they are much more useful for C++ and OPL development than for Java. The reasons for this, and the advantages gained by separating an application’s resources from its executable code, are discussed in the following sections.

Customise the user interface

The EIKON programming framework requires that some aspects of an application’s layout and behaviour, including menu, toolbar and other control structures, are defined in a resource file.

This can have powerful implications for application development. Small changes to the resource file can change an application significantly. For example, the in-built Help and Data applications are the same — except for some small changes to the menu and toolbar resources.

Localisation

Developers can localise an application by simply changing the resource file text associated with each menu item, task bar or other control. Since changes to the text do not change the symbol information in the generated header file, it is not necessary to recompile the application to use the new file. Consequently, a resource file may be generated for each language supported, and the actual resource used is determined by the end-user at installation time.

User resources

Resource files are not restricted to declaring information used by the EIKON framework. A resource file might also, for example, define resources for dialog text, error messages, and program initialisation.

Again, the advantages of declaring user information in a resource file are that information is loaded only when needed, that resource files can be compressed, and that they can be localised without recompiling the main program.

System resources

The application information file is a special type of resource file, which defines application properties within the system context. These properties include:

  • the appearance of the application icon within the system shell
  • whether the application can be embedded
  • whether the application is visible in the system shell
  • whether new documents for the application can be created from the system shell

In addition, some applications support MIME types, and this property is also defined in the .aif file.

The structure of the application information resource file is similar to that of the ordinary resource file. However, since the information to be contained is pre-defined, formatting of aif resource files is very simple.

Java and resource files

Java applications run on a Java Virtual Machine (JVM) and hence do not use the EIKON framework directly. The main implication of this is that while Java applications can read the information in EPOC style resource files, they cannot use the EIKON framework to automatically build the user interface. This is a key advantage of using resource files in C++ and OPL.

Another advantage of using resource files is that it becomes simple to localise applications. However Java has native methods for localising applications, making EPOC resource files unnecessary.

Like C++ and OPL programs, Java applications must have an .aif file to have a customised icon and caption, and the ability to be launched from the extras bar. The method used to link the .aif file to the Java application, via a .app file, is documented in the Java SDK.

File types reference

The resource compilation process uses a number of file types:

.rss | resource source file, for input to rcomp or aiftool.
.h | header file, for inclusion in C++ file
.rh | resource header, for inclusion in resource file
.hrh | common C++ or resource header, for inclusion in either type of source file
.rsg | generated resource header file, output from rcomp
.rsc | generated resource file, output from rcomp
.aif | application information file, as defined by the application architecture, output by aiftool
EPOC SDK Home Glossary Indexes Previous Next Up


Resource compiler

Contents

  • Overview
  • Integrating the resource compiler into the C++ IDE
  • The resource compilation process
  • Example

Overview

Resource files contain data in numbered resources. The index can be used to efficiently find a resource given its numeric id. There can be from 1 to 4095 resources in a resource file. A resource file has the following format:

There are four main reasons for using resource files:

  • resource files make it easier for applications to run in more than one language. The resource text may be changed and the resources recompiled, without altering or recompiling the C++ program.
  • they are convenient for specifying and modifying some aspects of application layout and design. Applications that use the EIKON framework must have a resource file.
  • keeping data in a separate resource file may reduce RAM requirements because text strings will only be loaded into RAM when needed
  • resource files may be compressed, thereby reducing program size

Resource files are produced by compiling a text source file, extension .rss, using the EPOC resource compiler, eikrs. The resource compiler also produces a header file, extension .rsg, which is required when the project is compiled using a C++ compiler.

For more information on the resource compiler invocation syntax, see the topic Simple resource compiler interface.

Integrating the resource compiler into the C++ IDE

When programming EPOC in C++, developers can integrate the resource compiler into the Visual Studio IDE. This process, which is described in the C++ SDK, allows the resource compiler to be invoked from a Visual Studio menu.

The resource compilation process

Resource compilation is a two-stage process:

  • The pre-processor stage
  • The main resource compilation stage

The pre-processing stage operates on the resource file statements and uses the cpp pre-processor supplied with the GNU C++ compiler. The GCC compiler is located in the directory \epoc32\gcc\bin, as downloaded from the SDK. If you also have a cpp from a different vendor on your system, make sure that the directory in which it resides follows \epoc32\gcc\bin in the path.

The main resource compilation stage generates:

  • the header file, extension .rsg
  • the compiled resource file, extension .rsc

The header file contains #define statements for each resource defined in the source file. In the course of project development, changes to the resource file may not always result in changes to the set of #define statements generated. Consequently eikrs.bat checks whether the set of #define statements in the header file differ from the set in the existing .rsg file. If there is no change, the .rsg file is not rebuilt, thereby avoiding unnecessary re-compilation and linking.

The compiled resource file contains the resource data, and is the file that is referred to at run-time by the application..

Example

The following example illustrates the use of the resource compiler. Consider the bahello project. The resource compiler is invoked using the eikrs.bat batch file.

    eikrs bahello xx

This takes the bahello.rss source file and converts it into two output files: the symbol file bahello.rsg, and the resource file bahello.rxx.

The two letter code passed as the second parameter to eikrs is appended to the character r to generate the file extension. Any two letters may be used in the two letter code, and these can be used as flags for conditional compilation of the resource file. For example, a source resource file containing definitions in both French and Italian can be compiled into either language, depending on the code passed to eikrs.

Whatever code is used, at run time resource files must be re-named to have the extension rsc. Where multiple resource files are provided with apps, e.g. for different languages, the required renaming is managed as part of install process.

EPOC SDK Home Glossary Indexes Previous Next Up


Application information files

Contents

  • Changes to aiftool in EPOC Release 5
  • Overview
  • Application icons
  • Application captions
  • Application capabilities
  • UIDs, extension and location
  • MIME support

Changes to aiftool in EPOC Release 5

The changes to aiftool in EPOC Release 5 are:

  • MIME type support. As detailed in the topic MIME support, .aif files now define MIME type priorities. This allows applications to be associated with, and automatically launched by, non EPOC-native documents, e.g. HTML.
  • _UNICODE switch. As detailed in the topic UIDs, extension and location, the resource file now supports a _UNICODE switch for selection between the narrow build and Unicode UID values.

Overview

Application Information Files, extension .aif, store data concerning an application. The information includes the application’s:

  • icon in various sizes
  • caption in supported languages
  • capabilities, such as embedding, new-file and hidden
  • MIME-type support priorities

The aiftool tool can be used to create .aif files, as described in the topic Creating application information files. There are also C++ reader and writer classes for manipulating the data stored in .aif files (the writer class is rarely needed).

An EPOC program can run without an .aif file. In this case; a default icon, typically a question mark, is used for the application and its documents; MIME types are not supported; embedding is not supported; and the application does not support new-file, e.g. the ability to create files from the system shell rather than from within an application. The default caption is the name of its executable, without the extension.

The following topics describe each of the application properties defined in the application information file.

Application icons

Icons are used to represent applications, and their associated files/documents, when they are embedded, or when they are shown on the extras bar or system shell.

Up to 5 icons, in a number of different sizes, can be stored — the most appropriate size for the current container zoom state is displayed. Supplying a variety of sizes helps to ensure that an icon will not have to be dynamically scaled when it is drawn at a particular size — scaling small bitmaps generally results in a marked loss of quality. Typically icons of sizes 24x24, 32x32, and 48x48 might be supplied for an EPOC program running on a ½ VGA screen. Smaller icons might also be supplied for use as iconic doors in applications, such as Word, which may be in relatively small zoom states e.g. 9x9 and 12x12.

Each icon size needs a picture bitmap, and a mask bitmap. The mask should be black for the regions which are to be selected from the picture, and white for the transparent areas where the background should show through.

Application captions

An application's caption is the text displayed below its icon. Typically it is the application's name.

Captions for multiple languages can be stored in one .aif, and the one corresponding to the current system language is used. If there is no caption matching the current system language, the .aif filename is used. This means that one .aif can be used for multiple language versions of an application, as long as the icon does not need to change across these versions.

The set of supported languages is as given in the list below. Note that a test language is also supported.

American (English) | Dutch | Icelandic | Spanish
Australian (English) | English (UK) | Italian | Swedish
Austrian (German) | French | New Zealand (English) | Swiss German
Belgian Flemish | Finnish | Norwegian | Swiss French
Belgian French | German | Portuguese | Test
Danish | Hungarian | Russian | Turkish

Application capabilities

Application capabilities are encapsulated by the TApaAppCapability class. The three file properties/capabilities defined in an .aif file are detailed below:

embeddability

An EPOC application can be defined as embeddable, not embeddable, or EmbeddableOnly. An embeddable file appears in the embeddable list (Ctrl+Shift+O in any editor, e.g. Word). A file with the property EmbeddableOnly appears in the embeddable list, but will not appear on the extras bar.

By default, files are not embeddable.

hidden

An application can be defined as Hidden or Not Hidden. The Hidden property is intended for applications which are to run in the background. Such files do not appear in the extras bar or in the embeddable applications list, however they are visible in the system task list.

By default, files are not hidden.

new-file

An application can be defined with capabilities Does Not Support New File or Supports New File. The property allows new files to be created from the system screen as well as in the program. Files supporting the property appear in the list accessed when Ctrl+N is pressed on the system screen.

By default, files do not support the New File property.

UIDs, extension and location

Application information files are located in the same directory as the application DLL with which they are associated. They are normally given the same name as the application file, extension .app, but with an extension .aif.

Like other EPOC files, application information files have a set of 3 identifying UIDs:

  • The first UID identifies the file as a stream store, see KDirectFileStoreLayoutUid, defined in s32file.h
  • The second UID identifies the DLL as an application information store , see KUidAppInfoFile, defined in apadef.h
  • The third UID associates the AIF with its parent application, e.g. KUid AppName App

When an .aif file is created using aiftool, users need only specify the third UID. Aiftool automatically inserts the others.

Narrow and Unicode application build variants cannot use each other documents, and can hence be looked upon as different applications. Consequently they must have different third UIDs. The _UNICODE flag is used to select the appropriate third UID for the current build variant, when the source .aif resource text file is compiled [image] . Note: Unicode is not supported in this release.

MIME support

Multipurpose Internet Mail Extensions, MIMEs, define a file format for transferring non-textual data, such as graphics, audio and fax, over the Internet. The datatype_list section of the aiftool resource file lists the MIME types that the application supports, and the priority of support that each type is given. When a file is to be opened, EPOC launches the application which has the highest priority support for the selected file type.

There are four priority levels, of which only EDataTypePriorityNormal or EDataTypePriorityLow should normally be used. For example, a text editor is good at editing text/plain files, and would hence be given a priority of EDataTypePriorityNormal for that file type. A web browser is less good at handling text files, and would be assigned the lower priority EDataTypePriorityLow. Hence either application can be launched to handle a text document, however if both applications are present, the text editor is launched by preference.

EDataTypePriorityHigh should only be assigned under exceptional conditions — e.g. if no other application could ever handle a particular MIME type as brilliantly.

EDataTypePriorityLastResort should also be used sparingly. Text editors are terrible at displaying HTML, and would either have the priority EDataTypePriorityLastResort, or would not support the type at all.

Notes:
  • Given two applications with the same MIME type priority, EPOC arbitrarily launches one of the applications.
  • Developers can give users the ability to set their application as the default MIME type launcher — through the user defined mapping API (datastore.h, class CTypeStoreManager). This is usually accessed via an application menu option Make me the default.
EPOC SDK Home Glossary Indexes Previous Next Up


Examples - aiftool

Contents

  • Overview
  • Example resource file for a non embeddable application
  • Creating an icon file
  • Invoking aiftool
  • Delivering an .aif file

Overview

The directory \epoc32ex\adk\ contains all the files needed to make an application information file for the Boss Puzzle application. The Boss Puzzle game is the example application developed in the EPOC Tutorial.

The files include the resource file, Bossno.rss, eight bitmaps: boss16i.bmp, boss16m.bmp, boss24i.bmp, boss24i.bmp,boss32i.bmp, boss32m.bmp, boss48i.bmp and boss48m.bmp, and a bitmap conversion control file, bossmbm.lst.

The following examples demonstrate the process of creating an application information file.

Example resource file for a non embeddable application

Prior to generating an aif file, a resource file must be specified to define the application properties. The file specifies an application with the caption Boss Puzzle in English, French, German, Italian and Turkish. It is not embeddable and has 4 different sized icons. The app_uid matches the one given in the BossPuzzle.mmp project specification.

    // BOSSNO.RSS
    //
    // Copyright (c) 1998 Symbian Ltd.  All rights reserved.
    //
    #include <aiftool.rh>

    RESOURCE AIF_DATA
    {
    app_uid=0x01000253;
    //
    caption_list=
          {
          CAPTION { code=ELangEnglish; caption="Boss Puzzle"; },
          CAPTION { code=ELangFrench; caption="Jeu de Taquin"; },
          CAPTION { code=ELangGerman; caption="Boss Spiel"; },
          CAPTION { code=ELangItalian; caption="Gioco di Boss"; },
          CAPTION { code=ELangTurkish; caption="Boss soyusu"; }
          };
    //
    num_icons=8;
    //
    embeddability=KAppNotEmbeddable;
    }
Notes
  • The Hidden capability is not specified. Hence, by default, the application is not Hidden.
  • The New File capability is not specified, Hence, by default, the application does not support new file creation from the system shell.
  • There are 8 bitmaps but only 4 icon sizes — since each icon is created from an image and a mask bitmap pair.
  • The Boss Puzzle does not have a Unicode variant, and hence does not use the _UNICODE flag to define the app_uid.
  • The Boss Puzzle doesn’t support any MIME types.

Creating an icon file

An icon file contains different size bitmaps, which can be used to display the icon under different levels of zoom. For the Boss Puzzle example, eight bitmaps have been created: boss16i.bmp, boss16m.bmp, boss24i.bmp, boss24i.bmp,boss32i.bmp, boss32m.bmp, boss48i.bmp and boss48m.bmp. The i files contain the icon images, and the m files contain mask bitmaps. The mask bitmpas define what areas of the background show through the icon bitmap. These are all converted into an EPOC multi-bitmap file using the bitmap converter bmconv, see Bitmap manipulation tools:

    bmconv bossmbm.lst

The control file, bossmbm.lst, specifies the multi-bitmap file to be created, and the windows bitmaps to be included:

    boss.mbm
    boss16i.bmp
    boss16m.bmp
    boss24i.bmp
    boss24m.bmp
    boss32i.bmp
    boss32m.bmp
    boss48i.bmp
    boss48m.bmp

The resulting multi-bitmap file, boss.mbm, can be imported into the Boss Puzzle .aif file to provide the icon information.

Invoking aiftool

Use aiftool to compile the resource file bossno.rss, together with the multi-bitmap file boss.mbm, into an .aif file:

    aiftool bossno boss.mbm

This takes the bossno.rss and boss.mbm files as input, and produces an application information file bossno.aif as output. The command runs under the EPOC Emulator, and progress messages can be viewed on the emulator.

Delivering an .aif file

Application information files are delivered, with their associated application, bundled in an EPOC installation file, see Makesis Guide. The installation file should be configured so that the aif file is copied to the same directory as its associated application file. If the application is to appear on the extras bar, this should be a sub-directory of the \system\apps\ folder.

It is also important to note that unless the icon is to change for different locales, a project will only need one aif file.

EPOC SDK Home Glossary Indexes Previous Up


Application Resource Tools Reference

  • Simple resource compiler interface — eikrs.bat
  • Resource compiler — rcomp.exe
  • Resource file format — .rss
  • Creates application information files — aiftool.exe
  • Aiftool resource file format — .rss


Simple resource compiler interface — eikrs.bat

Contents

  • Purpose
  • Command line syntax

Purpose

The file eikrs.bat provides a convenient batch wrapper to invoke the C++ pre-processor and resource compiler, see Resource compiler. It provides the most commonly used resource compiler functionality. Some rarely needed options, such as the debugging option verbose output, are only available directly through rcomp.

eikrs generates two files:

  • the .rsc resource data file. This file is the resource file that must be referred to at run-time by the application.
  • the .rsg header file, which contains #define statements for each resource defined in the source file. This file can be #included in C++ code, to provide a handle to each of the resources in the resource data file. For C++ and OPL development, see the respective SDKs for information on how to access the information within resource data files.

Command line syntax

eikrs source-filename language-variant [target-path]

For information about how to interpret the syntax, see BNF grammars.

Arguments
source-filename | specifies the name of the source file; eikrs.bat expects to find the source file source-filename.rss in the current directory.
language-variant | specifies a two letter code for the language variant.
target-path | optional but, if supplied, defines the target directory for the generated resource file. If this parameter is not supplied, the default target directory is \epoc32\release\wins\deb\z\system\apps\source-filename, if it exists; if this directory does not exist, the default target directory is \epoc32\release\wins\deb\z\system\data.
Output files
source-filename.r language-variant | The resource data referred to at run-time by the application. Note that the generated file extension is the character r followed by the two letter language-variant. Before the resource file can be used it must be renamed or copied to source-filename.rsc. See your SDK documentation for examples using this file.
source-filename.rsg, | the generated header file, which contains #define statements for each resource defined in the source file. This file is always placed into the directory \epoc32\include.
Notes
  • As part of its processing, eikrs.bat checks whether the generated set of #define statements differs in any way from the set in the existing .rsg file. If there is no change, the .rsg file is not rebuilt. This avoids unnecessary re-compilation and re-linking.
EPOC SDK Home Glossary Indexes Previous Next Up


Resource compiler — rcomp.exe

Contents

  • Purpose
  • Command line syntax

Purpose

The resource compiler, rcomp, compiles source .rss resource files into a .rsc resource data file which can be used by applications, and a .rsg resource header file. The operation of the resource compiler is usually wrapped in a batch file. The batch file, eikrs.bat, provides a simple interface to the most commonly used rcomp functionality, but does not provide some of the debugging options available directly through rcomp.

Command line syntax

rcomp [—v] | [—l] | [—m] | [—p] | [—u] —o DataOutputFile —h HeaderOutputFile —s SourceFileName [—i BaseInputFileName]

For information about how to interpret the syntax, see BNF grammars.

Arguments
—v | verbose output.
—l | log memory
—m | output memory calls
—p | parser debugging
—u | generate Unicode resource binary
—o | Specify full path and name for data output file (DataOutputFile).
—h | Specify header output file (HeaderOutputFile; name only, does not include path).
—s | Specify resource compiler source file SourceFileName (output of pre-processor BaseInputFileName.rpp)
—i | The file given to the pre-processor (this is the source file BaseInputFileName.rss)
Output files
DataOutputFile | The resource data referred to by the application at run-time. Note that the generated file can have any name. However, before the resource file can be used it must be renamed to have an extension .rsc.
HeaderOutputFile | The generated header file, which contains #define statements for each resource defined in the source file.
EPOC SDK Home Glossary Indexes Previous Next Up


Resource file format — .rss

Contents

  • Overview
  • Resource file definition
    • Lexical conventions
    • C++ pre-processor statements
    • Resource file statements
    • Generated resource ids
    • STRUCT statement
    • RESOURCE statement
    • Initialising resource members
    • NAME statement
    • CHARACTER_SET statement
    • ENUM statement
  • Compiled resource file format — .rsc

Overview

This section details the source text resource file format, and is a useful reference for developers in C++ and OPL.

Topics covered include; the lexical conventions obeyed, the C++ pre-processor statements supported, and a description of the native resource compiler statements.

Resource file definition

Section Contents

  • Lexical conventions
  • C++ pre-processor statements
    • Conditional compilation in resource files
    • Include files within a source file
  • Resource file statements
  • Generated resource ids
  • STRUCT statement
    • Struct names
    • Defining struct members
    • Arrays within structs
  • RESOURCE statement
  • Initialising resource members
    • Simple member initialisation
    • Resource identifiers for LINKs and LLINKs
    • Initialising array items
    • Initialising STRUCT items
  • NAME statement
  • CHARACTER_SET statement
  • ENUM statement

Lexical conventions

  • Whitespace, except when enclosed in quotes for strings, is ignored by the compiler.
  • Both C-style (/* */) and C++-style (//) comments are supported.
  • Strings must be enclosed with double-quotes.
  • To include a double-quote within a string, enter a double-quote preceded by a backslash. The following resource generates the output string "text" : i.e., the binary sequence: 0x22 0x74 0x65 0x78 0x74 0x22.

    • RESOURCE SIMPLE quote_example
          {
          string="\"text\"";
          }

    where string is of type BUF.

  • To include a backslash within a string, enter two backslash characters. The following resource generates the output string \text\ : i.e., the binary sequence: 0x5c 0x74 0x65 0x78 0x74 0x5c.

    • RESOURCE SIMPLE backslash_example
          {
          string="\\text\\";
          }

C++ pre-processor statements

The following pre-processor statements are supported by the resource compiler:

  • #define
  • #undef
  • #line
  • #include
  • #ifdef
  • #ifndef
  • #if
  • #else
  • #endif

Conditional compilation in resource files

The resource compiler supports conditional compilation such as

    #ifdef SOMETHING
    // do something
    #else
    // do something else
    #endif

or

    #ifndef WHATEVER
    // do something
    #endif

Include files within a source file

You can include files within the source file by using a #include directive, for example:

    #include <eikdef.rh>

or

    #include "eikdef.hrh"

The searching algorithm used by the resource compiler depends on whether the item to be included is enclosed in double-quotes or angled brackets.

If the filename is enclosed in double-quotes, the resource compiler searches for that file through the following directories in the given order:

  • the current directory
  • the relative directory ..\inc
  • the absolute directory \epoc32\include

If the filename is enclosed in angled brackets, the resource compiler searches for that file through the following directories in the given order:

  • the relative directory ..\inc
  • the absolute directory \epoc32\include

Resource file statements

source-file :
statement-list

A source file consists of any number of statements.

statement :
struct-statement
| resource-statement
| character_set-statement
| name-statement
| offset-statement
| system-statement
| enum-statement

The most usual forms of statement are a struct-statement and a resource-statement. The struct statement defines a type of resource, see STRUCT statement. The resource statement defines an actual resource instance of the type defined in a struct, gives it a resource id, see Generated resource ids, and causes it to be generated in the resource file, see RESOURCE statement.

Generated resource ids

By default, the resource ids in the generated header file are allocated from 1 in ascending sequence. The sequence can be made to begin from another value using the NAME statement, see NAME statement.

STRUCT statement

struct-statement :
STRUCT struct-name [ BYTE | WORD ] { struct-member-list }

A STRUCT statement defines the format of a struct; all resources are defined in terms of structs. The struct has a name designated by struct-name, and some items designated by struct-member-list.

The length of most structs is variable. A resource’s entire length can be deduced from the position of the next resource; this information is available in a resource file’s index. If the struct is embedded within a resource, however, its length must be identified another way.

  • Use BYTE to prefix the struct with a single byte indicating its length (zero to 255 bytes).
  • Use WORD to prefix the struct with a word indicating its length (zero to 65,535 bytes).

The following are valid STRUCT statements:

    STRUCT STRING
          {
          TEXT str;
          }
    STRUCT TEST BYTE
          {
          WORD status;
          STRUCT text;
          }

The first example defines a struct called STRING which contains a single TEXT item.

The second example defines a struct called TEST which contains a WORD and an embedded struct. The total length of TEST is unknown, but should not exceed 255 bytes: the BYTE directive in the definition indicates that, when this struct is embedded within another, it should be preceded with a byte indicating its length (zero to 255 bytes).

The struct-member-list is a sequence of struct-members where each member is terminated by a semi-colon. The complete list is enclosed within a pair of braces as demonstrated by the struct called TEST.

Struct names

The following rules must be observed for struct-names:

  • they must be given in upper case
  • they must begin with an alphabetic character, although subsequent characters may be numeric
  • they may not begin with any of the following resource compiler keywords — the 12 struct type-names, see Defining struct members, and the keywords: GLOBAL, STRUCT, LEN or RESOURCE. This restriction applies only to the struct-name, not the member-name of any individual struct members.

    • So the following struct definition will generate an error

    STRUCT BUFTHING
          {
          BUF buffer;
          }

    whereas this struct definition will compile correctly

    STRUCT ABUFTHING
          {
          BUF buffer;
          }

Defining struct members

struct-member :
member-declaration [ = initialiser ] ;
member-declaration :
type-name member-name
| [ LEN [ BYTE ] ] type-name member-name
[ ( length-limit ) ]
[ [ [array-size] ] ]
type-name :
BYTE
| WORD
|      LONG
| DOUBLE
| TEXT
|      LTEXT
|      BUF
| BUF<n>
| LINK
| LLINK
|      SRLINK
| STRUCT
  • Each member of a struct is identified by a declaration followed by an optional initialiser, and then a semi-colon.
  • The simplest form of declaration is to specify a type-name and a member-name only:
    STRUCT TEST
          {
          WORD length;
          }
  • The type-name must be in upper case (WORD in this example).
  • The member-name must be in lower case (length in this example).
  • An SRLINK member may not have an initialiser since it is self-referencing and, therefore, only takes the value of the resource id the struct is declared in. This is assigned automatically by the resource compiler.

There are twelve valid types:

BYTE | A single byte. Can be treated as a signed integer (–128 to +127) or unsigned integer (0 to 255).
WORD | Two bytes. Can be treated as a signed integer (–32,768 to +32,767) or unsigned integer (0 to 65,535).
LONG | Four bytes. Can be treated as a signed integer (–2,147,483,648 to 2147483647) or an unsigned integer (0 to 4,294,967,295).
DOUBLE | Eight byte real for double precision floating point numbers (approximately 1.7E308).
TEXT | An ASCII string, terminated by a null.
LTEXT | An ASCII string with a leading byte count, and no terminating null.
BUF | An ASCII string with no terminating null and no leading byte count.
BUF<n> | An ASCII string with no terminating null and no leading byte count but which has a maximum length n. This type is an alternative to using the length-limit with BUF types,
LINK | The id of another resource (16 bits), rather like a pointer to that resource.
LLINK | The id of another resource (32 bits).
SRLINK | A self-referencing link. This is a 32 bit link which contains the resource id of the resource it is defined in.
STRUCT | Any struct, rather like including that struct as a member in this struct. STRUCT members are useful because it means that once a struct has been defined it can be re-used for a variety of resources.
  • Numbers more than one byte long are stored little-endian: that is, their least significant byte is stored first.
  • LINK and STRUCT are not type-safe: it is the responsibility of the user of a struct to ensure that the correct resource type is linked or included. The definer of a struct should give some idea, perhaps using a comment:
    STRUCT TEST
          {
          WORD length;
          STRUCT text; // should be a STRING
          }
  • a length-limit may be specified for members of string type (BUF, TEXT and LTEXT): the length-limit is enclosed in parentheses after the member name. In the following example
    STRUCT TEST
          {
          TEXT string1(9);
          LTEXT string2(MAX);
          BUF string3;
          }

    string1 has a maximum of 9 characters, string2 a maximum of MAX characters (where MAX has been #defined elsewhere) and string3 has no maximum length. Note that this maximum applies only to the actual characters and does not take account of the terminating zero (for TEXT members) or leading byte count (for LTEXT members).

  • An alternative method to using length-limit with a BUF type is to use the type BUF<n>. For example, given the definition of TEST and the resource definitions for test1, test2 and test3:
    STRUCT TEST
          {
          BUF<4> string;
          }
    RESOURCE TEST test1
          {
          string="abcd";
          }
    RESOURCE TEST test2
          {
          string="ab";
          }
    RESOURCE TEST test3
          {
          string="abcdef";
          }

    test1 generates 0x61 0x62 0x63 0x64

    test2 generates 0x61 0x62

    but test3 generates an error because the maximum length of string permitted by the definition of the STRUCT is 4.

Arrays within structs

Recall the member-declaration syntax; look at a specific subset of this (see Defining struct members for the full syntax of a struct member:

member-declaration :
type-name member-name
| [ LEN [ BYTE ] ] type-name member-name [ [array-size] ]

A declaration of a struct member may either be a simple type-name member-name, or it may be an array of values of identical type.

Arrays are always indicated by square brackets:

    STRUCT HAS_ARRAY
          {
          STRUCT elements[];
          }

In the example above, the HAS_ARRAY struct has one array member, elements. Each member of elements is of STRUCT type.

If you specify the array size, inside the square brackets, then the generated resource will contain no count of the number of elements. So this resource:

    STRUCT FIXED_ARRAY
          {
          WORD elements[3];
          }

    RESOURCE FIXED_ARRAY example1
          {
          elements={9,8,7};
          }

will generate the output

    0x09 0x00 0x08 0x00 0x07 0x00

For variable length arrays a count of the number of elements precedes the resource. The default for this is a word, but by prefixing the struct definition with LEN BYTE it will be a byte count. So the following resource:

    STRUCT VAR_ARRAY
          {
          WORD elements [];
          }

    RESOURCE VAR_ARRAY example2
          {
          elements={9,8,7};
          }

will generate the output

    0x03 0x00 0x09 0x00 0x08 0x00 0x07 0x00

whereas this resource:

    STRUCT VAR_ARRAY2
          {
          LEN BYTE WORD elements[];
          }

    RESOURCE VAR_ARRAY2 example3
          {
          elements={9,8,7};
          }

will generate this output

    0x03 0x09 0x00 0x08 0x00 0x07 0x00

The compiler allows you to prefix LEN BYTE or LEN WORD even for fixed length arrays but it has no effect. Fixed length arrays do not generate an element count.

See also the section on initialising array items in Initialising resource members.

RESOURCE statement

resource-statement :
RESOURCE struct-name [resource-name] { resource-initialiser-list }

The RESOURCE statement is used to generate a resource in the resource file. The statement specifies three things:

  • a struct-name which denotes the structure that will be used for the resource

    • It must have been defined in a previous STRUCT statement and must be in upper case.

  • an optional resource-name which identifies the resource

    • The resource-name must be in lower case.

    The resource-name causes a symbolic constant to be generated in the resource compiler’s output header file, so that a resource

    RESOURCE TEST my_test { /* etc */ }

    will result in a definition of the form

    #define MY_TEST 1

    in the generated header file — see the .rsg file referred to in Command line syntax.

    The default id for the first resource defined in the file is one with subsequent resources’ ids generated in ascending sequence. See Generated resource ids for more information on how resource ids are generated.

    If no resource name is specified then the resource is generated in the object file and assigned a resource id as usual, but will not be published in the header file. Anonymous resources are used mainly for playback scripts where the resources are read in sequentially by default, so that assigning names to them would be superfluous.

    The resource-name may also be used by the resource compiler for LINK and LLINK members — see Resource identifiers for LINKs and LLINKs.

  • initialisation for members of the resource struct, where their default values are not appropriate

As an example, given the struct definition

    STRUCT NCEDIT
          {
          WORD current;
          WORD low;
          WORD high=65535;
          }

you could define a resource:

    RESOURCE NCEDIT MEMORY_SIZE
          {
          low=640;
          high=1024;
          }

Thus, in the resource file, current has the value compiler default value of 0, low has the value 640 (specified in the resource definition) and high has the value 1024 (specified in the resource definition, overriding the default for the struct type).

Initialising resource members

The resource initialiser has different forms depending on whether a single, simple, member is being initialised, or whether a struct or an array is being initialised:

resource-initialiser : member-name [ ( length-limit ) ] = initialiser
initialiser :
simple-initialiser
| struct-initialiser
| array-initialiser

Resource members may be initialised by default (in the struct definition) or explicitly initialised (in the resource definition).

In general,

  • If a member is initialised in a RESOURCE statement, that is its value.
  • If it is initialised in a STRUCT statement, that is its value for all resources which do not explicitly initialise it.
  • If it is neither initialised in a RESOURCE statement nor a STRUCT statement, then: BYTE, WORD and DOUBLE members contain zero; TEXT, LTEXT and BUF members contain an empty string.
  • It is an error for LINK and LLINK members to have no explicit value, so they must be initialised, either by default (in the STRUCT statement) or explicitly (in the RESOURCE statement).
  • SRLINK members may not be initialised (either in the STRUCT statement or a RESOURCE statement) since they are automatically assigned the resource id of the resource in which they appear.
  • Members which are themselves STRUCTs may not be default initialised. They can only be initialised in the RESOURCE definition. If they are not explicitly initialised they will take up zero bytes in the resource file. For example, given the following STRUCT definition:

    • STRUCT TEST2
          {
          WORD value;
          STRUCT tester;
          }

    The following RESOURCE statement only generates the two bytes 0xFF 0x00.

    RESOURCE TEST2 item
          {
          value=255;
          }

Default values can be specified for struct members by using an initialiser, for example

    STRUCT NCEDIT
          {
          WORD current;
          WORD low;
          WORD high=65535;
          }

With this specification, any NCEDIT resource will, by default, have a high member whose value is 65,535. If the RESOURCE statement specifies a different value, it will be used instead.

Simple member initialisation

simple-initialiser :
number
| string
| resource-identifier
  • A BYTE, WORD, LONG or DOUBLE member must be initialised with a number. The number can be the result of simple expressions such as 3+1 or NUM1+NUM2 where NUM1 and NUM2 have been #defined earlier on in the file.
  • A TEXT, LTEXT or BUF member must be initialised with a string. If a length-limit has been declared for that member in the STRUCT definition then an error will be generated if the string is longer than the limit. You can, however, override any maximum length declared in the struct definition by specifying a new maximum length after the member name in the resource definition. For instance the following resource
    RESOURCE THING
          {
          string(20)="Very long string";
          }

    will compile correctly even if the struct definition specified a maximum length of 10 for string.

Resource identifiers for LINKs and LLINKs

A LINK or LLINK member must be initialised with a resource-identifier. This resource identifier may be in the form of a resource name or a number.

  • If it is a resource name and it is declared in lower case, it refers to a resource in the file.

    • It is not necessary for the resource to be defined at the time the statement is processed, but an error will result if the resource is not defined in the entire file. When declared in lower case any NAME specified in the file will be added onto the resource id.

  • If the resource name is declared in upper case, it refers to a resource defined in another file.

    • To reference it you must #include the relevant header file containing the resource. All resource names are turned into upper case when their #defines are generated in the header file — this is how the resource compiler recognises that it must look for the resource in another file. If this resource does not exist in any #included file then an error is generated.

  • The resource identifier may also be specified as a number: in this case it is the resource id (including NAME).

    • If no such resource id exists either in the file or any #included header files, no error is generated by the compiler. The programmer must therefore ensure that the id is a valid reference.

See Generated resource ids for information on how resource ids are generated. See also NAME statement and related statements.

Initialising array items

array-initialiser :
{ array-initialiser-item-comma-list }
array-initialiser-item :
initialiser

To initialise a member of array type, give the items in the array in sequence. Each initialiser must be of a type compatible with the member being initialised.

Fixed-length arrays

If the member was declared as a fixed-length array (e.g., WORD elements[10]), then it is an error to specify any more items than were given in the length (either in the STRUCT or the RESOURCE definition). If fewer items are specified in the default initialisation (i.e. in the STRUCT definition) then an error also results. Note that if fewer elements are specified when initialising the array in the RESOURCE statement, then any elements not specified after the specified values will be lost, even if they have been default initialised in the STRUCT definition. Take the following example:

    STRUCT SAMPLE
          {
          BYTE bts[3]={1,2,3};
          }

In the following resource:

    RESOURCE SAMPLE default
          {}

the output will be the whole default array

    0x01 0x02 0x03

but in this resource:

    RESOURCE SAMPLE first_specified
          {
          bts={5};
          }

the output is:

    0x05

with the second and third elements lost. If you specify only the second element in the RESOURCE definition then the first element is taken from the default initialisation, the second from the explicit initialisation and the third element is lost. The following resource:

    RESOURCE SAMPLE  second_specified
          {
          bts[1]=5;
          }

results in the 2-byte output:

    0x01 0x05

If, however, you explicitly initialise an element in the middle of an array without having supplied default values for array members before it, then an error will result.

Variable length arrays

If the array was not declared fixed-length then the number of elements is worked out from the initialiser and prepended to the resource. The default for this element count is a word: you may specify it as a byte by declaring LEN BYTE in front of the array declaration in the STRUCT definition; e.g.

    STRUCT VAR_ARRAY
          {
          LEN BYTE WORD [];
          }
Using expressions to initialise array elements

You may initialise array elements with expressions. You must explicitly initialise each member component of the array otherwise the expressions will be evaluated incorrectly. The following resource:

    RESOURCE SAMPLE correct_expression
          {
          bts[0]=3+1;
          bts[1]=2;
          bts[2]=3;
          }

will generate the correct output 0x04 0x02 0x03. However, if you use the following syntax:

    RESOURCE SAMPLE incorrect_expression
          {
          bts={3+1,2,3};
          }

the output will be 0x03 0x02 0x03. This is because the pre-processor treats ‘3+1’ as a literal string which is then interpreted by the compiler as 3. In the resource correct_expression above the ‘=‘ sign forces the pre-processor to evaluate the expression.

Initialising STRUCT items

struct-initialiser :
struct-name { struct-initialiser-item-list }
struct-initialiser-item :
member-name = initialiser ;

STRUCT members may only be initialised in the resource definition.

To initialise a member of STRUCT type, give the struct-name with which you wish to initialise it, and then specify each member of that struct which you wish to initialise.

The member-names listed must be members of the struct-name struct. Each initialise must be of a type compatible with the member it is initialising.

The compiler does not enforce type safety. Any struct can be used to initialise a member declared to be of struct type. Usually, however, the designer of the struct will have intended only one or a limited number of structs ever be used to initialise a member. You should ensure that you initialise struct members with the intended struct type.

Given the previously defined struct types

    STRUCT STRINGCOUNT
          {
          BUF message;
          WORD num;
          }
    STRUCT SAMPLE
          {
          WORD anynumber;
          STRUCT text;      // should be a STRINGCOUNT
          }

the following example shows how to define the struct within a resource:

    RESOURCE SAMPLE show_how
          {
          anynumber=10;
          text=STRINGCOUNT
                {
                message="Hello"
                num=5;
                };
          }

Note the trailing semicolon after the closing } of the text struct member initialisation: this is because a semicolon follows all member initialisations. For longer, more complicated resources deciding where semicolons must be placed may become confusing. As shown in the following example, array lists are separated by commas and terminated without a semi-colon. Similarly, resources are not terminated by a semi-colon.

    RESOURCE DIALOG example_dialog
          {
          title="Example";
     topsection=DLAY_SECTION
                {
                control_list=
                      {
                 ACLIST
                       {
                       butlist_flags=BUTLIST_HORIZONTAL;
     rid=R_HCIL_BUTTONS_OK_CANCEL;
                       },                        // array member so comma needed
                      ACLIST
                       {
                       butlist_flags=BUTLIST_HORIZONTAL;
     rid=R_HCIL_BUTTONS_OK_CANCEL;
                       }      // last item in array so nothing needed
                      };      // end of struct member control_list so ‘;’ needed
                };            // end of struct member topsection so ‘;’ needed
          }                  // end of resource so nothing needed

The rules to remember are as follows:

type of entity | Punctuation needed after closing ‘}’
resource | nothing
array member (not last one) | ,
last array member | nothing
struct member | ;

See the definitions of resource-statement, struct-statement, struct-member and array-initialiser for a complete explanation of the syntax.

NAME statement

name-statement:
NAME short-name

Use this statement to ensure that the resources in the file have a unique id so that an application can use multiple resource files without resource id conflict.

This statement must the first non-comment statement in the file.

The short-name must be between one and four alphabetic characters long and be unique (no other file may use the same one). For the sake of consistency this constant should be in upper case although lower case is allowed (and will be converted to upper case by the compiler). This short-name is then converted into a number and shifted onto the leading 20 bits of the resource id, leaving the bottom 12 bits for the number of the resource in the file. This allows a maximum of 4095 resources to be defined in a source file.

So with NAME set to AAAA, if this resource is the first resource in the file

    RESOURCE STRING one
          {
          wd=5;
          }

the first entry in the generated header file will be

    #define ONE 0x04FD8001

04FD8 is the leading 20 bits for all ids in the file and 001 is the reference of that resource within the file.

Since the NAME statement maps all resource ids within the file onto 32-bit numbers, only LLINKs may be used for resource references in that file. Using the NAME statement in a resource file means that any attempt to use a LINK will generate an error.

CHARACTER_SET statement

character_set-statement :
CHARACTER_SET character_set-name

Use a CHARACTER_SET statement to define the character set to be used. The permitted values for character_set-name are defined as:

character_set-name :
ASCII
| CP1252
|      CP850
| ISOLatin1
| ShiftJIS

If the CHARACTER_SET statement is omitted from a resource file, character set CP1252 is taken as default.

ENUM statement

enum-statement :
enum [ enum-label ] { enum-list } ;
| ENUM [ enum-label ] { enum-list } ;

Use an enum (or an ENUM) statement to define a set of integer values. The values are associated with symbols defined in the enum-list; the syntax and the semantics are compatible with those of C++ enumerations.

Each member of the enum-list is followed by a comma except for the last one. The syntax of a member is defined as:

enum-member :
member-name [ =initialiser ]

The defined enumerator symbols can be used in both C++ code and resource scripts and are commonly defined in files which have the conventional file extension hrh. The .hrh files are included in both C++ files and resource source files.

For example, the enum definition:

    enum
          {
          EExampleCmdIdFirst=0x100,
          EExampleCmdIdSecond,
          EExampleCmdIdThird,
          EExampleCmdIdFourth
          };

defines the enumerators EExampleCmdIdFirst, EExampleCmdIdSecond etc. and assigns values to them.

In general, each enumerator can be assigned a specific value. If no value is explicitly assigned, the value generated by the resource compiler is the value of the previous enumerator plus one. Thus, in the above example, EExampleCmdIdFirst is assigned the value 0x100 (decimal 256), EExampleCmdIdSecond is assigned the value 0x101 (decimal 257) etc.

If the first enumerator is not assigned an explicit value, it defaults to 0.

More than one enumerator may be assigned an explicit value.

The assigned value can be coded in either hexadecimal or plain decimal notation.

    enum      {
          testvalue1=10,
          testvalue2,
          testvalue3=20,
          testvalue4
          };
    STRUCT TEST1
          {
          BYTE b1;
          BYTE b2;
          BYTE b3;
          BYTE b4;
          }
    RESOURCE TEST1 test
          {
          b1=testvalue1;
          b2=testvalue2;
          b3=testvalue3;
          b4=testvalue4;
          }

In this example the resource generated is: 0x0A 0x0B 0x14 0x15

Note that the final semi-colon in an enum may be omitted; however, to retain compatibility with the C++ compiler, it is advisable to retain it.

Compiled resource file format — .rsc

All resource files have the following format:

header

resources

index table

where:

header | is always four bytes long. It consists of two 16-bit numbers: the first gives the file offset of the start of the index table, the second gives the length in bytes of the index table
resources | are a series of variable-length data items generated in the order specified in the source file
index table | is a sequence of 16-bit numbers, the first giving the file offset of the start of the first resource, the second giving the file offset of the start of the second resource and so on up to the last resource in the file. The last 16-bit number gives the file offset of the end of the last resource (i.e. the beginning of the index table)

So for example the following source file:

    STRUCT SIMPLE
          {
          WORD wd;
          LONG lg;
          BUF name;
          }
    RESOURCE SIMPLE one
          {
          wd=5;
          lg=10000;
          name="Simon";
          }
    RESOURCE SIMPLE two
          {
          name="John";
          }

when compiled, will produce the following output resource file:

    0: 19 00 06 00 05 00 10 27 00 00 53 69 6d 6f 6e 00 .......’ ..Simon.
    10: 00 00 00 00 00 4a 6f 68  6e 04 00 0f 00 19 00    .....Joh n......
EPOC SDK Home Glossary Indexes Previous Next Up


Creates application information files — aiftool.exe

Contents

  • Purpose
  • Command line syntax

Purpose

aiftool creates an application information file, extension .aif, using information contained in a resource file and an EPOC multi-bitmap icon file.

Command line syntax

aiftool resource-file icon-file

For information about how to interpret the syntax, see BNF grammars.

Arguments
resource-file | A file that specifies the captions for all supported languages, the application capabilities, and the number of icons to be included in the .aif file.
icon-file | An EPOC multi-bitmap file that contains the icons and icon masks for displaying the application at different sizes.
Notes
  • The command line syntax and brief notes may be obtained by typing aiftool on the command line.
  • The resource-file extension, .rss, is added by aiftool, and must not be specified.
  • There is no standard filename extension for an EPOC multi-bitmap file so the icon-file extension must be specified. Usually it is specified as .mbm.
EPOC SDK Home Glossary Indexes Previous Next Up


Aiftool resource file format — .rss

Contents

  • Overview
  • Include file
  • Application UIDs
  • Caption list
  • Number of icons
  • Embeddability capability
  • Hidden capability
  • New file capability
  • Data-type list

Overview

The resource file used by aiftool specifies the application UID, captions, capabilities, the number of icons to be incorporated in the final aif file, and the priorities of supported MIME types. The structure of the resource file is as shown below. Each element of the file is described in its own section, and an example file can be viewed in the topic Examples - aiftool.

    // include file - contains enumerations and resource structure
    #include <aiftool.rh>

    RESOURCE AIF_DATA
    {
    // Application UID (for narrow and/or unicode builds)
    #ifdef _UNICODE
          app_uid=unicode_application_uid;
    #else
          app_uid=narrow_build_application_uid;
    #endif

    // Application Captions list (captions in supported languages)
    caption_list=
          {
          CAPTION { code=[ELangEnglish]; caption="Caption in English"; }, ...,
          CAPTION { code=[Enumeration_for_selected_language_n]; caption="Caption_in_selected_language_n"; },
          };

    // number of icons to be loaded from the .mbm file
    [num_icons=0; ]

    // Application Capabilities
    [embeddability= KAppNotEmbeddable | KAppEmbeddable | KAppEmbeddableOnly;]
    [hidden= KAppNotHidden | KAppIsHidden      ;]
    [newfile= KAppDoesNotSupportNewFile | KAppSupportsNewFile;]

    // MIME type priorities
    [datatype_list=
          {
          DATATYPE { priority= EDataTypePriorityHigh | EDataTypePriorityNormal | EDataTypePriorityLow | EDataTypePriorityLastResort; type="MIME_type"; },
          DATATYPE { priority=priority_enumeration; type="another_MIME_type"; }
          };]
    }

For information about how to interpret the syntax, see BNF grammars.

Include file

The resource file includes a header file aiftool.rh. Aiftool expects the file to be located in \Epoc32\Include\, when it is installed as part of an SDK).

    #include <aiftool.rh>

The file specifies:

  • an enumeration for the supported language codes
  • an enumeration for the supported application capabilities
  • an enumeration for the different MIME type priorities
  • a definition of the AIF_DATA resource structure, including default aif properties.

Application UIDs

The application UID associates the .aif file with its parent application.

    #ifdef _UNICODE
          app_uid=unicode_application_uid;
    #else
          app_uid=narrow_build_application_uid;
    #endif

The same resource file is used to produce both narrow and Unicode aif files. Hence both narrow and Unicode build UIDs are specified. For C++ SDK developers, the UIDs should match those specified in the project .mmp file.

Notes:
  • Unicode files are not supported in EPOC release 5. However the tool chain is Unicode enabled, so the functionality has been documented.
  • Narrow and Unicode builds have different UIDs/.aif files. This prevents Unicode and Narrow build applications from opening each others documents.
  • The Unicode .aif builder, aiftoolu uses the _UNICODE flag to select the Unicode UID.

Caption list

A caption is the line of text, typically the application’s name, which appears below the application icon in the system shell.

Captions are specified in the caption_list section of the resource file. Captions are typically specified for each language supported by the application.

caption_list=
      {
CAPTION { code=[ELangEnglish]; caption="Caption in English"; }, ...,
CAPTION { code=[Enumeration_for_selected_language_n]; caption="Caption_in_selected_language_n"; },
};

The enumeration for supported languages, as defined in the included file, are given below. The code=[language_enumeration] definition associates each caption with a particular system language setting.

Supported language enumeration
ELangAmerican | ELangDutch | ELangIcelandic | ELangSpanish
ELangAustrian | ELangEnglish | ELangItalian | ELangSwedish
ELangAustralian | ELangFinnish | ELangNewZealand | ELangSwissFrench
ELangBelgianFlemish | ELangFrench | ELangNorwegian | ELangSwissGerman
ELangBelgianFrench | ELangGerman | ELangPortuguese | ELangTest
ELangDanish | ELangHungarian | ELangRussian | ELangTurkish

Number of icons

The num_icons field defines the number of bitmaps to be included in the final aif file. If not specified, the number defaults to zero, and the aif file is displayed with the default icon. The default icon is typically a question mark.

    [num_icons=0;]

Embeddability capability

The file can take one of three enumerated Embeddability values, as defined in the topic Application capabilities. If undefined, the Embeddability property defaults to KAppNotEmbeddable.

    [embeddability= KAppNotEmbeddable | KAppEmbeddable | KAppEmbeddableOnly;]

Hidden capability

The file can take one of two enumerated hidden states, as defined in the topic Application capabilities. If undefined, the Hidden property defaults to KAppNotHidden.

    [hidden= KAppNotHidden | KAppIsHidden;]

New file capability

The file can have one of two enumerated new file creation properties, as defined in the topic Application capabilities. If undefined, the New File property defaults to KAppDoesNotSupportNewFile.

    [newfile= KAppDoesNotSupportNewFile | KAppSupportsNewFile];

Data-type list

MIME type priorities are specified in the datatype_list section of the resource file. The priority for each type, e.g. text/html, determines which application is launched to display a particular document. Priorities can take one of four enumerated levels, as described in the topic MIME support.

[datatype_list=
      {
      DATATYPE { priority= EDataTypePriorityHigh | EDataTypePriorityNormal | EDataTypePriorityLow | EDataTypePriorityLastResort; type="MIME_type";},
 DATATYPE { priority=priority_enumeration; type="another_MIME_type"; }
      };]

Notes:
  • Developers should only use EDataTypePriorityNormal or EDataTypePriorityLow, unless there is a very good reason to do otherwise.
EPOC SDK Home Glossary Indexes Previous Up


File Conversion Utilities

The utilities convert different file types, including font and image files, into the native format used by EPOC.

The guide section contains a brief overview of the font conversion, EPOC Connect, and an overview and examples for the bitmap conversion tool, bmconv.

The reference material covers the command line syntax for each of the utilities, and a description of the font definition file format.

Users should start by reading the guide material, and refer to the reference as necessary.


File Conversion Utilities Guide

  • Font tools
  • Bitmap manipulation tools
  • EPOC Connect


Font tools

Overview

Font files provide the pixel patterns used for drawing characters. EPOC Release 5 defines a new plug-in architecture, called the Open Font System, to provide support for arbitrary font formats; these may be outline, vector, bitmap, etc. In particular, this lays the foundation for full support of scaleable fonts.

However, until font plug-ins have been released, developers should continue to work with EPOC’s own font store file format (.gdr).

Two methods can be used to produce a .gdr file:

  • The most likely method to be used by third party developers involves coding the font specification as a .gd text file, see Font definition file. This file type can be compiled into a font store file, using the fnttran tool.
  • Existing fonts, e.g. those licensed from a supplier in EFF versions 1 or 2 or legacy font formats (.fsc), can be converted into a .gd file using the fontcomp tool. The .gd file can then be compiled into the .gdr file using fnttran. Fonts in Adobe’s Bitmap Distribution Format (.bdf files) can also be used by fnttran directly, see Bitmap distribution format files.

The font tool reference material is contained in the topics:

  • Font compiler — fnttran.exe
  • Convert font file formats — fontcomp.exe
  • Font definition file
EPOC SDK Home Glossary Indexes Previous Next Up


Bitmap manipulation tools

Contents

  • Overview
  • Changes to bmconv in EPOC Release 5
  • Examples
    • Constructing and using a file containing two EPOC format bitmaps
    • Viewing the contents of a multi-bitmap file
    • Creating Windows bitmaps from a multi-bitmap file

Overview

Bitmaps provide the pixel patterns used by pictures, icons and masks, sprites and brush styles for filling areas of the display. To optimise bitmap handling performance, EPOC uses files containing multiple bitmaps in its own EPOC bitmap format. These files are of two types:

  • ROM image bitmap files
  • file store bitmap files

The bmconv tool is used to convert bitmaps designed on a PC to EPOC bitmap format. The tool is also used to perform the reverse conversion process, so bitmaps can be created on either platform.

Note that the tools are used for converting bitmaps files prior to bundling in EPOC installation files — see Preparing applications for installation. Microsoft Windows bitmap files are automatically converted to EPOC Sketch files, and visa versa, when files are moved between EPOC and a PC using EPOC Connect.

Changes to bmconv in EPOC Release 5

The bmconv bitmap conversion tool has increased functionality, primarily to support enhancements, such as colour, to EPOC.

The new arguments available to bmconv in this release are: /n, /q, /bpp, and /v. Pre EPOC release 5, bmconv was limited to creating 1, 2 or 4 bits per pixel bitmaps. It can now create bitmaps for all the new display EPOC modes.

Examples

Section Contents

  • Constructing and using a file containing two EPOC format bitmaps
    • Designing the original Windows bitmaps
    • Combining the bitmaps into a multi-bitmap file
  • Viewing the contents of a multi-bitmap file
  • Creating Windows bitmaps from a multi-bitmap file

Constructing and using a file containing two EPOC format bitmaps

Making a file of bitmaps for use by EPOC consists of two stages:

  • designing the original Windows bitmaps, in .bmp format.
  • converting the Windows bitmaps to EPOC bitmap format and combining the EPOC format bitmaps into a multi-bitmap file

The following example shows the creation of an EPOC multi-bitmap file from three Windows bitmaps, created using Microsoft Paintbrush. They can be found in \epoc32ex\adk\.

Designing the original Windows bitmaps

The most important feature to consider when designing a bitmap is the capacity of the target system. While bmconv can convert 24-bit colour bitmaps to .mbm format, there is little point in doing so if the EPOC platform can only display 4-bit images. In addition, increased colour depth comes at the cost of increased file size, and should be used sparingly.

The smallest memory/least colour diagrams are those produced in monochrome, e.g. black and white. The diagram \epoc32ex\adk\hangman.bmp was produced in Microsoft Paintbrush, and then saved as monochrome bitmap using:

File|Save As...|Monochrome bitmap (*.BMP)

The second examples are the 16 colour bitmaps smiley.bmp and abstract.bmp. These were drawn in various colours and shades of grey, and then saved using:

File|Save As...|16 Color bitmap (*.BMP)

Combining the bitmaps into a multi-bitmap file

The .bmp files must be converted into EPOC format bitmaps and combined into a multi-bitmap file. A possible command line to use is:

    bmconv /hbmexmpl.h bmexmpl.mbm /4smiley.bmp /1hangman.bmp /c16abstract.bmp

The screen output should be:

    BMCONV version 48.
    Compiling...
    Multiple bitmap store type: File store
    Epoc file: bmexmpl.mbm

    Bitmap file 1   : Smiley.bmp
    Bitmap file 2   : Hangman.bmp
    Bitmap file 3   : Abstract.bmp
    Success.

The header file generated is as follows:

    // bmexmpl.h
    // Generated by BitmapCompiler
    // Copyright (c) 1998 Symbian Ltd
    //

    enum TMbmBmexmpl
          {
          EMbmBmexmplSmiley,
          EMbmBmexmplHangman,
          EMbmBmexmplAbstract
          };

Viewing the contents of a multi-bitmap file

The contents of a file can be viewed using the summary switch /v , as shown below:

    bmconv /v bmexmpl.mbm

This results in a screen output:

    BMCONV version 48.

    Bitmap 1 information:
    Pixel size 48 x 48
    Twips size 0 x 0
    4 Bpp Monochrome
    Bytewise RLE compression 45%

    Bitmap 2 information:
    Pixel size 33 x 33
    Twips size 49 x 49
    1 Bpp Monochrome
    Bytewise RLE compression 59%

    Bitmap 3 information:
    Pixel size 216 x 158
    Twips size 323 x 236
    16 Bpp Colour
    16 bit RLE compression 5%

    bmexmpl.mbm contains 3 bitmaps
Note
  • Files resolution is defined by the /bpp switch used during the conversion from Windows .bmp format. This is independent of the resolution of the original bitmap.

Creating Windows bitmaps from a multi-bitmap file

Windows bitmap files can be extracted from a multi-bitmap file using the /u switch, as shown below:

    bmconv /u bmexmpl.mbm smiley-out.bmp hangman-out.bmp abstract-out.bmp

This results in a screen output:

    BMCONV version 48.
    Decompiling...
    Epoc file: bmexmpl.mbm

    Bitmap file 1   : smiley-out.bmp
    Bitmap file 2   : hangman-out.bmp
    Bitmap file 3   : abstract-out.bmp
    Success.
Note
  • A name must be defined for each bitmap in the .mbm. Any name can be used, however a .bmp extension should be declared so that Windows will associate the bitmap with a viewer.
  • The output file resolution is 24 bits per pixel (colour).
  • The output file may not be a precise duplicate of the original bitmap, due to loss of information during bitmap resolution changes.
EPOC SDK Home Glossary Indexes Previous Next Up


EPOC Connect

Overview

EPOC Connect is a powerful file conversion tool. It is not shipped with any EPOC SDK, however it is re-badged by licensees, and can be obtained from their respective Web sites (e.g. versions of PsiWin can be found on the Psion Web site).

EPOC Connect can be used to convert many different file types between the native format used by Windows and that used by EPOC. In addition to the headline conversion capabilities, such as the ability to convert between EPOC and Window’s spreadsheet applications, it can also convert sound files between the EPOC format and the Windows .wav file format.

It is recommended that developers use EPOC Connect for sound file conversion.

EPOC SDK Home Glossary Indexes Previous Up


File Conversion Utilities Reference

  • Font compiler — fnttran.exe
  • Font definition file
  • Convert font file formats — fontcomp.exe
  • Convert bitmaps into EPOC format — bmconv.exe
  • The multi-bitmap header file


Font compiler — fnttran.exe

Contents

  • Purpose
  • Command line syntax

Purpose

Fnttran creates a font store file from a font definition (text) file.

Command line syntax

fnttran font-definition-file font-output-file

For information about how to interpret the syntax, see BNF grammars.

Arguments
font-definition-file | The ASCII source file containing each bitmap font, and how the bitmap fonts are collected into typefaces. The source file generally has the extension .gd or .i
font-output-file | The file to be created. The font store file, extension .gdr, that will be put into the \SYSTEM\FONTS directory on a machine running EPOC.
Notes:
  • Information about Fnttran source files can be found in the topics Font definition file and Bitmap distribution format files.
EPOC SDK Home Glossary Indexes Previous Next Up


Font definition file

Contents

  • Overview
  • Font definition file structure
  • Font bitmap definition
  • Typeface definition
  • Font store file definition
  • Bitmap distribution format files

Overview

This document describes the structure of the font definition file, including the font bitmap, typeface and font store file definitions.

Font definition file structure

A font definition file consists of a statement list, which defines bitmaps, typefaces and font store files.

whole-file :
statement-list

statement :
font-bitmap-statement
| typeface-statement
| font-store-file-statement

The font definition file is characterised by:

  • one or more font bitmap definitions font-bitmap-statement
  • one or more typeface definitions typeface-statement
  • one or more destination font store file definitions font-store-file-statement
Notes
  • Note that in all cases a string must be enclosed in quotes, e.g. "mystring".
  • Comments can be included in font definition files by using the ! character — any text appearing after a ! on a particular line is taken to be a comment.
  • The font bitmap definitions are conventionally coded in separate .gdf files and incorporated into the .gd file by using #include statements, e.g.
          #include “ari16.gdf”

    where the filename (ari16) is conventionally the font-bitmap-label from the font bitmap definition.

    BDF files can also be included in the same way, e.g.

          #include “roman11.bdf”

    Font definition files containing #include statements need to be processed by the C pre-processor before conversion with fnttran. For example, to translate tfont.gd you would type:

          cl /P /EP tfont.gd
          fnttran tfont.i tfont.gdr

Font bitmap definition

Section Contents

  • Code section
  • Pixel line definitions
  • Font bitmaps stored as .gdr files
font-bitmap-statement :
FontBitmap font-bitmap-label
Uid uid [ Bold ] [ Italic ] [ Proportional ]
MaxNormalCharWidth char-width
CellHeight cell-height
Ascent ascent
code-section-clause
EndFontBitmap

A font bitmap is characterised by:

  • a font bitmap label font-bitmap-label: this label will be used in typeface-statements to refer to the font bitmap.
  • a UID uid, which can be used in a typeface-statement to refer to a font that will be accessible to the FBSERV at run-time, but is inaccessible to the compiler at compile time. C++ developers can also use uid as a parameter to CFbsDevice::GetFontById(), CWsScreenDevice::GetFontById(), CFontStore::GetFontById(), or CFbsTypefaceStore::GetFontById() functions. NB. The UID must be specified in decimal, rather than in (OPL-style) &xxx syntax.
  • whether it is bold (Bold) and/or italic (Italic) and/or proportional (Proportional).
  • the maximum normal character width, in pixels, char-width. This is usually defined by the pixel width of the @ character.
  • the character cell height, in pixels, cell-height.
  • the character cell ascent, in pixels, ascent.

The diagram below shows the @ character (font: Arial). It has a width of 16 pixels (maximum), height 16 pixels and ascent 11 pixels.

Code section

code-section-clause :
CodeSection code-point-start:code-point-end
char-clause-list
EndCodeSection

A code section defines the bitmaps for characters in the range code-point-start to code-point-end. Each character in this range is defined by a char-clause. Successive char-clauses define successive characters in ascending numerical order through the range. There must be precisely the required number of char-clauses, (code-point-end - code-point-start + 1).

char-clause :
Char character-code [ Adjust left-adjust right-adjust ]
char-pixel-line-definition-list
EndChar

Each character is defined by an optional left adjust and/or right adjust, and then a series of pixel lines. The number of character lines defined between Char and EndChar must be equal to zero or cell-height.

Pixel line definitions

A char-pixel-line-definition consists of a sequence of period and asterisk characters. A period represents a white pixel, and an asterisk represents a pixel which forms part of the character itself.

Each pixel line definition in a char-clause must be the same length.

For example, this is the definition for the g character (Font: Times New Roman, 20 pixel, Bold Italic Proportional):

    Char 103 Adjust -1 0  ! 'g'
    ..........
    ..........
    ..........
    ..........
    ..........
    ..........
    ..........
    ....****..
    ...**..***
    ..**...**.
    ..**...**.
    ..**..***.
    ...*****..
    ..**......
    ..*****...
    .**.****..
    **....**..
    **....**..
    .*****....
    ..........
    EndChar

The char-pixel-line-definition-list always starts with the topmost row of pixels in the character cell. The lines continue downwards for every row of pixels until the definition contains cell-height rows.

Font bitmaps stored as .gdr files

A KFontStoreFileVer9Uid is used to identify the filetype. These files are conventionally incorporated in font definition files by using #include.

Typeface definition

typeface-statement :
Typeface typeface-label
Name typeface-name [ Symbol ] [ Proportional ] [ Serif ]
FontBitmaps
font-bitmap-reference-list
EndFontBitmaps
EndTypeface

The Typeface statement defines a typeface and gives it a label, typeface-label.

The typeface also has a full name typeface-name.

typeface-name :
string

The typeface may be a symbol typeface Symbol and/or proportional Proportional and/or serif Serif. If Symbol is not stated then the typeface is normal. If Proportional is not stated then the typeface is monospaced. If Serif is not stated then the typeface is sans-serif.

A typeface contains several font bitmaps, each defined by a reference:

font-bitmap-reference :
uid
| font-bitmap-label [ WidthFactor width ] [ HeightFactor height ]

The uid form refers to the font bitmap identified by its UID, as specified in the UID clause of the font-bitmap-statement. The font bitmap must be accessible to the font bitmap server when this typeface is used at run-time. Typically, the uid form is used to refer to fonts which are guaranteed to be in the ROM, but are not in this compilation unit, for example, the tiny fonts.

The font-bitmap-label form refers to a font bitmap that has previously been defined, using a FontBitmap statement with that label, in this compilation unit. The font bitmap may be algorithmically enlarged by n-tupling the width using WidthFactor width, and/or n-tupling the height using HeightFactor height. This avoids the need for too many font bitmap definitions. The example below shows a normal and WidthFactor 2 character, (font: Times New Roman, 20 pixel, Bold Italic Proportional):

Note that a font bitmap does not have to be incorporated into a typeface to be accessible to the font and bitmap server.

Font store file definition

font-store-file-statement :
FontStoreFile
CollectionUid uid
KPixelAspectRatio aspect-ratio
 CopyrightInfo
copyright-info
 EndCopyrightInfo
Typefaces
typeface-label-list
EndTypefaces
EndFontStoreFile

The FontStoreFile statement defines a destination font store file. The font store file is identified by its collection UID uid. NB. The UID must be specified in decimal, rather than in the OPL-style, &xxx syntax.

A font store file contains several typefaces, each defined by a typeface-label. The typeface-label refers to a previously defined typeface, in this compilation unit.

Copyright information is specified in the copyright clause — any number of lines of text, each of which must be surrounded by quotes ("), between the CopyrightInfo and EndCopyrightInfo keywords.

The aspect-ratio identifier gives the aspect ratio of the device for which the font is designed (1000*PixelHeightInTwips/PixelWidthInTwips).

Bitmap distribution format files

Fnttran supports BDF V2.2 but without the support for multiple writing directions as this is not supported by EPOC. The characters must be listed in order of Unicode encoding. The name of the font, following FONT, is the label used to identify the individual font bitmap when the typefaces are constructed. Some additional keyword should be supplied in the PROPERTIES section of the BDF file however.

    STARTPROPERTIES 3
    Uid 999999      // A uid enabling the font bitmap to be requested
    MaxNormalCharWidth 12 // The maximum normal width of characters in pixels.
    MaxConsecutiveFillChars 0
    ENDPROPERTIES

The final keyword (MaxConsecutiveFillChars) is optional and controls whether breaks are made between code sections when there are missing characters in the input BDF file.

See http://partners.adobe.com/supportservice/devrelations/typeforum/tchntlist.html for further details of BDF format.

EPOC SDK Home Glossary Indexes Previous Next Up


Convert font file formats — fontcomp.exe

Contents

  • Purpose
  • Command line syntax

Purpose

The purpose of fontcomp is to convert a font in EFF version1 or version 2, or FSC format, to EPOC GDR font file format.

Command line syntax

fontcomp source-file dest-file [ /e [ mapfile ] ] [ /f ]

For information about how to interpret the syntax, see BNF grammars.

Arguments
source-file | Source file to be processed.
dest-file | The file to be created (GDR format)
/e | Source file is in EFF format (default).
Mapfile | Used for alternative character sets (source file EFF format only)
/f | Source file is in FSC format

Source font file formats

Source files for the fontcomp tool can be in either FSC or the EFF format.

The production of both ANSI1 and ANSI2 (ISO LATIN1 and ISO LATIN2) fonts from a single EFF source-file is possible if two mapfiles are supplied by EFF. The fontcomp tool is then run twice - once using each mapfile.

EPOC SDK Home Glossary Indexes Previous Next Up


Convert bitmaps into EPOC format — bmconv.exe

Contents

  • Purpose
  • Command line syntax

Purpose

The bmconv tool is used to convert bitmaps between EPOC and Windows bitmap formats. EPOC bitmaps (.mbm) may be produced as either a font store file or a ROM image file — which does not use any RAM when being accessed. The conversion process specifies the number of bits per pixel for the converted bitmaps and whether they should be colour or grey-scale.

The program can also split EPOC multi-bitmap files into component bitmaps, and then convert the individual files to Microsoft Windows bitmap format.

Command line syntax

bmconv [/r] [/n] [/h header-file] [/q] epoc-file [/bpp]bmp-file_1 [... [/bpp]bmp-file_n]

or:

bmconv /u epoc-file bmp-file_1 [... bmp-file_n]

or:

bmconv /v epoc-file

or

bmconv command-file

For information about how to interpret the syntax, see BNF grammars.

Arguments
/r | Causes bmconv to generate a ROM image file. The default target is a file store bitmap.
/n | Disables the automatic compression of file store bitmaps.
/h header-file | Generates a header file that may be used in C++ code. header-file may include a path.
/q | Specifies quiet mode — only errors are reported.
epoc-file | The filename of the EPOC multi-bitmap file, which may include a path.
bmp-file_n | The filename of the nth Windows bitmap file, which may include a path.
/bpp | Specifies the number of bits per pixel to be used for each converted bitmap (bmp-file) and whether the converted bitmap should be colour or gray-scale. The default is 2 bits per pixel. Previously, the only options were /1 and /4; options now are: /1, /2, /4, /8, /c4, /c8, /c12, /c16 or /c24.
/u | Caused bmconv to convert from EPOC to Windows bitmap format. By default the conversion is from Windows to EPOC format.
/v | Prints summary information about the bitmaps in epoc-file
command-file | A file containing the command line, with commands separated by spaces or new-lines. Note that C++ style // comments may be included in command files.
Compatibility

EPOC .mbm files containing only 1, 2 and 4 bits per pixel resolution gray-scale bitmaps are fully compatible with all EPOC releases. Files containing bitmaps with a greater resolution than 4bbp are not supported by releases prior to EPOC release 5.

Notes
  • The command line syntax and brief notes may be obtained by typing bmconv on the command line.
  • The number of source files that may be included in an EPOC multi-bitmap is limited only by the PC memory, the available storage on the EPOC machine, and the number of characters available on the DOS command line.
  • File store bitmaps are compressed automatically by bmconv. File compression can be disabled using the /n switch. Note that ROM bitmaps are not compressed.
  • The name of the header file and the name of the multi-bitmap file do not have to be the same, though it may be convenient if they are.
  • There is no standard filename extension for an EPOC multi-bitmap file, but the use of .mbm is recommended for a font store file, and .mbr for a ROM image file.
  • There should be no spaces between the /bpp flag and a source filename, or between the /h flag and the header file name.
EPOC SDK Home Glossary Indexes Previous Next Up


The multi-bitmap header file

Contents

  • Overview
  • Enumeration structure

Overview

Bmconv bundles one or more Windows bitmaps into an EPOC multi bitmap file, and automatically generates a handle to each contained bitmap in a C++ multi bitmap header file. This header is a bonus for C++ developers; OPL developers must manually index the contained bitmaps.

The C++ header file contains an enumeration which identifies each of the source bitmaps within the associated multi-bitmap file. These enumerated constants can be used as parameters to the EPOC C++ SDK function CFbsBitmap::Load() when a bitmap is required by an EPOC application.

This following section describes the method used to generate the enumeration.

Enumeration structure

Each enum’s type name is generated by

  1. taking the name of the header file specified in the command line, without its extension
  2. capitalising the first letter and leaving the other characters in lower case
  3. prefixing the name with TMbm.

For example, if the header filename is head.h the enum name will be TMbmHead.

The item names are generated by

  1. taking the name of the header file specified in the command line, without its extension
  2. capitalising the first letter and leaving the other characters in lower case
  3. taking the name of the source bitmap file specified in the command line, without its extension
  4. capitalising the first letter and leaving the other characters in lower case
  5. adding the modified source bitmap filename to the end of the modified header file name
  6. prefixing the result with EMbm.

For example, if the name of the header file is head.h and the source .bmp filename is tblank the enum item name will be EMbmHeadTblank.

EPOC SDK Home Glossary Indexes Previous Up


Glossary & Indexes

The Glossary and Indexes provide alphabetical methods to find information in the EPOC Tools and Utilities.

The Glossary consists of all technical terms defined within the documentation.

Indexes list classes and other keywords. The indexes are automatically generated from the content of the documentation.


EPOC Tools & Utilities Glossary

Index A

Term | Topic | Meaning | See Also
aif file | Application Resource Tool Guide | Another name for an application information file. | application information file
aleppo | Aleppo Guide | help authoring tool | help authoring
application capabilities | Application Resource Tool Guide | Defined in the aif file, the application capabilities include the embeddable, hidden, and new file capabilities. | embeddable capability, hidden capability, new file capability, application information file
application information file | Application Resource Tool Guide | File which contains the caption, icon, capabilities, and MIME priority support information for an application. Has the file extension .aif. | aif file, icon, caption, application capabilities, MIME
application resource file | Application Resource Tool Guide | The resource file written by an application programmer as part of the application source. | resource file


EPOC Tools & Utilities Glossary

Index B

Term | Topic | Meaning | See Also
bdf file | File Conversion Utilities Guide | Binary distribution format - used in font definition files | fontcomp
bmconv | File Conversion Utilities Guide | Converts bitmaps between windows and EPOC formats |
bmp file | File Conversion Utilities Guide | extension for window bitmap. | windows bitmap
brush styles | File Conversion Utilities Guide | The style with which the brush fills fillables. This may be null, solid color, a built-in pattern or a bitmap pattern. |


EPOC Tools & Utilities Glossary

Index C

Term | Topic | Meaning | See Also
caption | Application Resource Tool Guide | An application's caption is the text (typically the application's name) displayed below its icon. | icon, application information file
code section | File Conversion Utilities Guide | A contiguous collection of character definitions covering part of the total character code range. |
compound identifier | Makesis Guide | A set of three UIDs which, in combination, identify an EPOC object; encapsulated by a TUidType. | UID
CP1252 | Aleppo Guide | Code page 1252. The code page for the windows variant of the Latin1 character set. |
customisation file | Aleppo Guide | The customisation file controls the appearance of the generated database. | order file, project file


EPOC Tools & Utilities Glossary

Index D

Term Topic Meaning See Also


EPOC Tools & Utilities Glossary

Index E

Term | Topic | Meaning | See Also
EFF | File Conversion Utilities Guide | Font format: Electronic Font Foundry format | Electronic Font Foundry format, fontcomp
eikrs | Application Resource Tool Guide | Batch tool for simplifying resource compiler interface. | rcomp, resource compiler
Electronic Font Foundry format | File Conversion Utilities Guide | Font format licensed by Symbian for use in EPOC. Also referred to as EFF. | EFF
embeddable capability | Application Resource Tool Guide | Embeddable documents can be embedded within another application. | application capabilities, application information file
EPOC sound file format | File Conversion Utilities Guide | Sound file format used in EPOC. |


EPOC Tools & Utilities Glossary

Index F

Term | Topic | Meaning | See Also
fnttran | File Conversion Utilities Guide | Creates a font store file from a font definition (text) file. |
Font Source file | File Conversion Utilities Guide | Font format: Also referred to as FSC format | fontcomp, FSC
fontcomp | File Conversion Utilities Guide | Convert a font in EFF or FSC formats to EPOC font file format. | GDR, EFF, FSC
formatting information | Aleppo Guide | The information, applied using styled markup, which defines which paragraphs in the source rich text file are used for which parts of the output help database. | styled markup
FSC | File Conversion Utilities Guide | Font format: Font Source file | fontcomp, Font Source file


EPOC Tools & Utilities Glossary

Index G

Term | Topic | Meaning | See Also
GDR | File Conversion Utilities Guide | EPOC font file format | fontcomp
generated header | Application Resource Tool Guide | rsg file, generated by rcomp, contains symbols used in resource file | resource file


EPOC Tools & Utilities Glossary

Index H

Term | Topic | Meaning | See Also
help authoring | Aleppo Guide | Process of generating a help database. In EPOC this process is implemented using aleppo. | aleppo
hidden capability | Application Resource Tool Guide | If hidden, applications run in the background. | application capabilities, application information file


EPOC Tools & Utilities Glossary

Index I

Term | Topic | Meaning | See Also
icon | Application Resource Tool Guide | Icons represent applications when embedded, or when they are shown on the extras bar or system shell. | application information file
important effect | Aleppo Guide | Style which indicates to aleppo that the marked text must be preceded by the graphic or text for an important event in the output database. | note effect, tip effect, customisation file


EPOC Tools & Utilities Glossary

Index J

Term Topic Meaning See Also


EPOC Tools & Utilities Glossary

Index K

Term Topic Meaning See Also


EPOC Tools & Utilities Glossary

Index L

Term | Topic | Meaning | See Also
left adjust | File Conversion Utilities Guide | The number of pixels to move before displaying a character. |


EPOC Tools & Utilities Glossary

Index M

Term | Topic | Meaning | See Also
major build number | Makesis Guide | The number used to represent a significantly different software release e.g. in App 3.1, the major build number is 3. | minor build number
makesis | Makesis Guide | Uses package file to create EPOC installation file (sis file) | sis file, package file
mask | File Conversion Utilities Guide | Bitmap defining transparent regions of another bitmap |
MIME | Application Resource Tool Guide | Multipurpose Internet Mail Extensions. | application information file
minor build number | Makesis Guide | The number used to represent a sub-release e.g. in App 3.1, the minor build number is 1. | major build number
Multipurpose Internet Mail Extensions | Application Resource Tool Guide | Also known as MIME. | MIME


EPOC Tools & Utilities Glossary

Index N

Term | Topic | Meaning | See Also
new file capability | Application Resource Tool Guide | Allows documents belonging to the application to be created external to the program. | application capabilities, application information file
note effect | Aleppo Guide | Style which indicates to aleppo that the marked text must be preceded by the graphic or text for a note in the output database. | important effect, tip effect, customisation file


EPOC Tools & Utilities Glossary

Index O

Term | Topic | Meaning | See Also
open font system | File Conversion Utilities Guide | New EPOC system to allow plug-in support for different font types. |
order file | Aleppo Guide | The order file specifies the order that selected topics are displayed in the output EPOC help database. | order name
order name | Aleppo Guide | Topic name for ordering the first database topics. Text marked as hypertext link style in the source rich text file. | order file


EPOC Tools & Utilities Glossary

Index P

Term | Topic | Meaning | See Also
package file | Makesis Guide | makesis project file, extension .pkg. | makesis
pkg file | Makesis Guide | makesis project file extension. | package file
pre-processor | File Conversion Utilities Guide | Prepares source files for further processing. Eg In C++ replace macro representation with code to be compiled |
project file | Aleppo Guide | The aleppo project file defines the location of all resources required to produce the help database. | order file, customisation file


EPOC Tools & Utilities Glossary

Index Q

Term Topic Meaning See Also


EPOC Tools & Utilities Glossary

Index R

Term | Topic | Meaning | See Also
rcomp | Application Resource Tool Guide | The filename of the resource compiler | eikrs, resource compiler
requisite | Makesis Guide | File which must be present, e.g. DLL, for an application to run | makesis
residual stub file | Makesis Guide | Remains of installation file (sis file) stored in system directory to prevent over-writing and assist in application removal | sis file, makesis
resource | Application Resource Tool Guide | Data defined in a resource file, externally to a program. The resource file contains language-dependent string text and specifications of user interface elements. | resource file, resource compiler, rcomp
resource compiler | Application Resource Tool Guide | A tool for creating a resource file from text input. | resource, rcomp
resource file | Application Resource Tool Guide | The file containing the resources for a particular program. |
resource header file | Application Resource Tool Guide | A file containing a definition of all the resources used by a particular control. It can be #included in a resource file and has the extension .rh. | rcomp, eikrs, resource file
right adjust | File Conversion Utilities Guide | The number of pixels to move after displaying a character |


EPOC Tools & Utilities Glossary

Index S

Term | Topic | Meaning | See Also
SDK | File Conversion Utilities Guide | Software development kit |
sis file | Makesis Guide | EPOC installation file, produced by makesis. | residual stub file, makesis
sprite | File Conversion Utilities Guide | An arbitrary-shaped bitmap which may be moved without applications having to redraw the underlying screen. Typically used for pointer cursors and for animated figures in games. |
styled markup | Aleppo Guide | Styled markup uses styles to differentiate text for the different parts of the final output database. e.g. different style are used to mark the text for synonyms, topic headings and normal text. | formatting information
synonyms | Aleppo Guide | In aleppo, taken to mean words that are not in the title, but which are useful for searching. Eg creating, making, building. |


EPOC Tools & Utilities Glossary

Index T

Term | Topic | Meaning | See Also
tip effect | Aleppo Guide | Style which indicates to aleppo that the marked text must be preceded by the graphic or text for a tip in the output database. | important effect, note effect, customisation file
twip | Aleppo Guide | 1/1440th of an inch, or 1/20th of a point. All measurements supported by the GDI are either in pixels for devices, or twips for real-world sizing. |


EPOC Tools & Utilities Glossary

Index U

Term | Topic | Meaning | See Also
UID | Makesis Guide | A UID is a globally unique 32-bit number used in a compound identifier to uniquely identify an object (see UIDs and Requesting UIDs from Symbian). When users refer to “UID” they often mean UID3, the identifier for a particular program. | UID1, UID2, UID3, compound identifier
UID1 | Makesis Guide | The first UID in a compound identifier; identifies the general type of an EPOC object and can be thought of as a system level identifier; for example executables, DLLs, and file stores are all distinguished by UID1 | UID
UID2 | Makesis Guide | The second UID in a compound identifier; distinguishes within a type(i.e. within a UID1); can be thought of as an interface identifier, for example static interface (shared library) and polymorphic interface (application or plug-in framework) DLLs are distinguished by UID2 | UID
UID3 | Makesis Guide | The third UID in a compound identifier; identifies a particular subtype and can be thought of as a project identifier (for example UID3 might be shared by all objects belonging to a given program, including library DLLs if any, framework DLLs, and all documents) | UID


EPOC Tools & Utilities Glossary

Index V

Term | Topic | Meaning | See Also
variant number | Makesis Guide | The variant number distinguishes application which implement the same functionality, but which have some platform or other dependence. e.g. Unicode. | minor build number, major build number


EPOC Tools & Utilities Glossary

Index W

Term | Topic | Meaning | See Also
windows bitmap | File Conversion Utilities Guide | Bitmap in the MSWindows file format (extension .bmp) | bmp file


EPOC Tools & Utilities Glossary

Index X

Term Topic Meaning See Also


EPOC Tools & Utilities Glossary

Index Y

Term Topic Meaning See Also


EPOC Tools & Utilities Glossary

Index Z

Term Topic Meaning See Also


Indexes

EPOC SDK Home Glossary Up
Symbian

EPOC Tools & Utilities Indexes

  • Figure index


EPOC Tools & Utilities: Figure Index

EPOC SDK Home Glossary Up

EPOC Tools & Utilities Figure Index

Figure | Topic
Example help database | Aleppo Guide
 | Aleppo Guide
Boss ordered board | Aleppo Guide
aleppo project directory structure | Aleppo Guide
Definition list styles | Aleppo-ref
Example SGML pipeline | Aleppo-ref
makesis flowchart - installation of a simple program | Makesis Guide
Installation flowchart - packaging a multi-lingual program | Makesis Guide
Installation flowchart - installing a localised version of a multi-lingual program | Makesis Guide
Installation flowchart - packaging the program and license agreement | Makesis Guide
Installation flowchart - installing the program with license agreement | Makesis Guide
makesis flowchart - bundled sis file | Makesis Guide
Installation flowchart - installation of bundled sis file | Makesis Guide

EPOC SDK Home Glossary Up


Documentation conventions

Contents

  • Overview
  • Feature level
  • Indexes and glossary
  • Headings
  • Styles
  • BNF grammars

Overview

This topic provides a quick introduction to the conventions used in this documentation.

Feature level

EPOC Release 5 adds new features to previous releases of EPOC, including new programming interfaces, and modifications to existing interfaces. The icon [image] beside a heading indicates such features.

The tool chain is similar to that used in previous releases, so the feature level icon is rarely used. Its use makes it simple to recognise new ER5 features even without checking which document you are reading — which may not be immediately clear, for example, when jumping between different documents.

Indexes and glossary

The Glossary provides definitions of important terms used in this documentation. Note that terms first used in other documentation, such as the EPOC C++ System Documentation, are defined in the glossaries belonging to those documents.

The Indexes provide lists figures used, with hyperlinks to where they are described in the documentation.

Headings

Styles

The documentation uses various typographic styles. Some styles are used to make text easier to understand, for example to highlight code fragments, intended user input, literal filenames, and other quoted text; other styles are used to flag restrictions and general applicability of text. Link styles are also used for hypertext navigation.

Style | Type
File | Open | Application text and menus
aVariable, Push(),EikColorUtils | Code. Note that where type names including class names and constants are mentioned, they are hyperlinked to their detailed discussion in the reference documentation.
note this | Emphasised text containing unusual or surprising information
euhello | Example project. This is hyperlinked to the reference page describing the example.
e32std.h | Filename
toolband | Hyperlink to definition in the glossary
dir | Input text to enter
ALT+A | Key names
WINS, ARM, M*CORE | Text only applies to the indicated platform
NUMED | Resource name, resource struct, or resource struct member
syntax | Syntax element in syntax diagrams and descriptions
Warning | Warning of an important issue

BNF grammars

Backus-Naur Form (BNF) grammars are used as a tool for describing language constructions. 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.
EPOC SDK Home Glossary Indexes Previous Up


EPOC Tools & Utilities: Glossary Index

A · B · C · D · E · F · G · H · I · J · K · L · M · N · O · P · Q · R · S · T · U · V · W · X · Y · Z · · Home


Introduction

  • Documentation conventions


  • Help Authoring with Aleppo
      • Aleppo Guide
        • Introduction to aleppo
        • Aleppo example projects
        • EPOC help project localisation issues
      • Aleppo Reference
        • Command line syntax — aleppo
        • Rich-text source file — .rtf
        • Project file — .alp
        • Order file — .order
        • Customisation file — .alc
        • Help database structure
        • SGML file format
    • Deploying Applications with Makesis
      • Makesis Guide
        • Installing EPOC applications
        • Preparing applications for installation
        • Makesis example projects
      • Makesis Reference
        • Create software installation file — makesis.exe
        • Package file format — .pkg
    • Application Resource Tools
      • Application Resource Tool Guide
        • About application resources in EPOC
        • Resource compiler
        • Application information files
        • Examples - aiftool
      • Application Resource Tool Reference
        • Simple resource compiler interface — eikrs.bat
        • Resource compiler — rcomp.exe
        • Resource file format — .rss
        • Creates application information files — aiftool.exe
        • Aiftool resource file format — .rss
    • File Conversion Utilities
      • File Conversion Utilities Guide
        • Font tools
        • Bitmap manipulation tools
        • EPOC Connect
      • File Conversion Utilities Reference
        • Font compiler — fnttran.exe
        • Font definition file
        • Convert font file formats — fontcomp.exe
        • Convert bitmaps into EPOC format — bmconv.exe
        • The multi-bitmap header file
    • Glossary & Indexes
      • Glossary
        • Glossary - A
        • Glossary - B
        • Glossary - C
        • Glossary - D
        • Glossary - E
        • Glossary - F
        • Glossary - G
        • Glossary - H
        • Glossary - I
        • Glossary - J
        • Glossary - K
        • Glossary - L
        • Glossary - M
        • Glossary - N
        • Glossary - O
        • Glossary - P
        • Glossary - Q
        • Glossary - R
        • Glossary - S
        • Glossary - T
        • Glossary - U
        • Glossary - V
        • Glossary - W
        • Glossary - X
        • Glossary - Y
        • Glossary - Z
      • Indexes
        • Figure index