brew resource editor guide
TRANSCRIPT
QUALCOMM Incorporated5775 Morehouse Drive
San Diego, CA. 92121-1714U.S.A.
This manual was written for use with the BREW SDKTM for Windows, software version 1.1.0. This manual and the BREW SDK software described in it are copyrighted, with all rights reserved. This manual and the BREW SDK software may not be copied, except as otherwise provided in your software license or as expressly permitted in writing by QUALCOMM Incorporated.
Copyright 2001 QUALCOMM Incorporated
All Rights Reserved
Printed in the United States of America.
All data and information contained in or disclosed by this document are confidential and proprietary information of QUALCOMM Incorporated, and all rights therein are expressly reserved. By accepting this material, the recipient agrees that this material and the information contained therein are held in confidence and in trust and will not be used, copied, reproduced in whole or in part, nor its contents revealed in any manner to others without the express written permission of QUALCOMM Incorporated.
Export of this technology may be controlled by the United States Government. Diversion contrary to U.S. law prohibited.
Binary Runtime Environment for Wireless, BREW, BREW SDK, TRUE BREW, BREWStone, MobileShop, Eudora, and PureVoice are trademarks of QUALCOMM Incorporated.
QUALCOMM is a registered trademark and registered service mark of QUALCOMM Incorporated.
Microsoft, Windows, Visual Studio, and Sound Recorder are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.
Macintosh is a registered trademark of Apple Computer, Inc.
UNIX and X-Windows are trademarks of The Open Group.
Adobe, Acrobat, and Photoshop are trademarks of Adobe Systems Incorporated.
All trademarks and registered trademarks referenced herein are the property of their respective owners.
BREW Resource Editor Guide
December 13, 2001
iii
Contents
Introducing the BREW Resource Editor Guide, 5
BREW documentation set, 6BREW acronyms and terms, 6Requesting new BREW features, 6For more information, 7
BREW Resource Editor Overview, 8
Types of resources, 8Controls, 8File formats, 9Role of the Resource Editor, 10Running applications on various devices in different languages, 11Running applets on an actual device, 11
Creating Resources, 12
Running the Resource Editor, 12Creating string resources, 13Creating image resources, 15Creating dialog resources, 17
Creating Dialog Controls, 20
Menus, 21Menu control, 22Soft Key control, 22List control, 23Icon View control, 23Creating Menus, 24Managing list items, 25
Date display and entry, 28Date control, 29Date Pick control, 29
Contents
iv
Time display and entry, 31Clock control, 32Stopwatch control, 32Countdown control, 33
Text entry, 35Text control, 35
Compiling Resource Files, 38
Types of output files, 38Compiling BREW resource files, 38
Index, 40
5
Introducing theBREW Resource Editor Guide
The BREW Resource Editor Guide describes the Binary Runtime Environment for Wireless™
(BREW™) Resource Editor, subsequently referred to as the Resource Editor, and its role in
creating application resource files. This document explains how to create the three types of
resources:
• String resources
• Image resources
• Dialog resources
The BREW Resource Editor Guide includes the following sections:
BREW Resource Editor Overview Describes the types of files, file formats, and controls that the Resource Editor supports, and provides information to help you start using the editor.
Creating Resources Explains how to create string, image, and dialog resources using dialog boxes accessible from the main BREW Resource Editor window.
Creating Dialog Controls Explains how to create various types of controls using dialog boxes accessible from the Dialog Resource dialog box.
Compiling Resource Files Explains how to save intermediate files and BREW resource files.
6
Introducing the BREW Resource Editor Guide
BREW documentation set
The BREW documentation set includes the following documents:
BREW acronyms and terms
See the introduction to the BREW SDK User’s Guide for the definitions of acronyms and terms
used in the BREW documentation set.
Requesting new BREW features
Do you have ideas for features that would make the BREW SDK more valuable and useful to
you? If so, send us email at [email protected]. Each request is evaluated, and a
member of the New Features Response Team will respond to your email.
BREW SDK User’s Guide Introduces the components of the BREW Software Development Kit (BREW SDK™) and their relationship to one another. The document also contains general instructions for developing BREW applications and for using the BREW Emulator.
BREW API Reference Provides information about BREW functions and data structures needed to develop applications for BREW-enabled mobile platforms.
BREW Device Configurator Guide Describes how to use the BREW Device Configurator to create effective wireless devices for emulation by the BREW Emulator.
BREW Resource Editor Guide Describes how to use the BREW Resource Editor to create the text strings, images, and dialogs used by BREW applications.
BREW MIF Editor Guide Describes how to use the BREW MIF Editor to create and modify Module Information Files (MIF)—a special type of BREW resource file that contains information about the classes and applets supported by particular BREW modules.
BREW SDK Utilities Guide Describes how to use the utilities, such as the PureVoice Converter, included with the BREW SDK.
BREW Compressed ImageAuthoring Guide
Describes how to use the BREW Compressed Image Authoring Tool to create files for displaying and animating images in your applications.
7
Introducing the BREW Resource Editor Guide
For more information
Online information and support is available for BREW application developers. Please visit the
BREW web site for details: www.qualcomm.com/brew/developer.
8
BREW Resource EditorOverview
This section describes the resources, controls, and file formats supported by the Resource
Editor, and the role of the Resource Editor in the BREW SDK.
Types of resources
Using the Resource Editor, you can create, modify, or delete the following three types of
resources:
Controls
Following are the types of controls supported by the Resource Editor:
String A string resource can be made of Unicode characters, ISOLATIN 1 characters, KSC5601, or S-JIS.
Image An image resource contains a graphic image. Currently, BMP, PNG, and BCI images are supported, but other graphics formats will be supported in later releases. Check the BREW web site for current information on supported image types.
Dialog A dialog resource can be made of one or more dialog controls. The controls let the device user choose an item from a menu or enter items such as the date, time, and text.
Menu Control List of choices shown from top to bottom.
Soft Key Control List of choices shown with horizontally scrolling buttons.
List Control List of choices that shows only the currently-selected menu item on the screen.
Date Pick Control List of date choices shown in a calendar format (one week per row starting from Sunday and one month at a time).
Date Control Used for selecting dates in the “Day of Week / Month Day, Year” format.
Stopwatch Control Used for counting elapsed time from a point A to point B.
Clock Control Used for specifying time.
9
BREW Resource Editor Overview
File formats
The Resource Editor uses an intermediate file format to save its contents and can support a
number of final output formats, one of which is the format used by BREW.
The intermediate format, which has the extension BRI (BREW Resource Intermediate), is an
input to the BREW Resource Compiler to produce the final output, which has the extension
BAR (BREW Applet Resource). The BREW Resource Compiler is integral to the Resource
Editor.
A header file with the suffix and extension _RES.H, for example foobar_res.h, is produced as
part of the final output. The following diagram illustrates the process. Although the Resource
Editor and BREW Resource Compiler are parts of the same entity, they are shown separately
to emphasize the role of each module.
Resource Editor process
Countdown Control Used for counting down from a specified amount of time to 0 (zero).
Text Control Used for manipulating text entries.
Icon View Control List of choices shown with icons.
10
BREW Resource Editor Overview
Role of the Resource Editor
The following figure illustrates the relationship between the Resource Editor and the other
tools that comprise the BREW SDK. It shows how the execution of a BREW applet called “app”
emulated on a device whose configuration is defined by the file dev.qsc produced by the
BREW Device Configurator, subsequently referred to as the Configurator.
Resource Editor in the BREW SDK
You can create a MIF for the applet with the BREW MIF Editor, subsequently referred to as the
MIF Editor, and place it in the appropriate MIF directory. You use the Resource Editor to create
a resource file that contains character strings, images, and dialogs loaded at applet execution.
The Resource Editor allows you to assign IDs to these resources and create a header file
(called app_res.h in the example) that contains these IDs. This file is included in the applet
source file, app.c, which is compiled and linked to produce the applet’s dynamic-link library
(DLL), app.dll. See the BREW SDK User’s Guide for details.
As shown in the previous figure, the Resource Editor saves the entered resource information
in a BRI file. When you modify the resource file, the Resource Editor loads its contents from
the BRI file. Any changes to the BRI file are not propagated to the BAR and _RES.H files until
you rebuild using the Resource Compiler.
11
BREW Resource Editor Overview
When you launch the BREW Emulator, subsequently referred to as the Emulator, it shows the
image of the device defined in the configuration file, dev.qsc. The Emulator looks in the
specified MIF directory and shows a menu containing all the applets with MIFs in that directory,
including the applet called app. When you choose app from the menu, the Emulator loads the
app.dll and begins running the applet. As the applet runs, it uses the resource-loading
functions in the IShell interface to load the resources it needs from the file app.bar (see the
BREW API Reference for detailed descriptions of IShell’s LoadRes and CreateDialog
functions). Each call to one of these functions includes the ID of the specified resource, which
is defined in the app_res.h header file.
Running applications on various devices in different languages
You can design BREW applications to run on different devices or in different languages. The
Resource Editor lets you create resource files that support the different devices and
languages. To create a version of an application for a particular language or device, you need
to create only system resource files instead of the entire application. By decoupling resources
from your code and loading them at runtime, you can avoid cluttering your source code with a
separate compilation flag for each supported language and device.
To emulate an applet for different devices and languages, you can create multiple versions of
app.bar and store them in separate directories, then set the Emulator’s applet and MIF
directories appropriately. To emulate a different device, load a device configuration file other
than dev.qsc into the Emulator. See the BREW SDK User’s Guide for more information
Running applets on an actual device
You also use BREW resource files when an application runs on the actual device. The ARM
compiler and linker is used instead of the Windows counterparts, and the output is a MOD file
(for dynamic applets) or a LIB file (for statically linked applets), instead of the Windows DLL.
For dynamic applets, each supported device/language combination contains a separate
download bundle for the MOD executable and a BAR file tailored to that device and language.
12
Creating Resources
This section explains how to create and manage string, image, and dialog resources.
Running the Resource Editor
The Resource Editor features a main window and a number of dialog boxes. The BREW
Resource Editor window includes a menu bar, a toolbar, a left pane listing the three types of
resources that you can create, and a right pane that provides information about the resources.
At the bottom is a status bar.
There are two methods for running the Resource Editor, from the Windows Start menu and
from the command line.
To run the Resource Editor from the Start menu
1. Choose Start > Programs > BREW > BREW Resource Editor.
The BREW Resource Editor window opens.
NOTE: After you have created and saved resources, you can run the Resource
Editor by double-clicking an existing BRI file.
13
Creating Resources
2. Perform one or more of the following tasks from this window:
• Create string resources. See Creating string resources below.
• Create image resources. See Creating image resources on page 15.
• Create dialog resources. See Creating dialog resources on page 17.
To run the Resource Editor from the command line
1. If a command prompt window is not already open, do one of the following to open
one:
• For Windows 2000, choose Start > Programs > Accessories > Command Prompt.
• For Windows NT, choose Start > Programs > Command Prompt.
2. At the command prompt, navigate to <BREW\Bin>.
3. Type the following command:
BREW_Res [-f <BriFile>]
where:
<BriFile>, corresponding to the -f option, is the filename of the BRI file (including
its path).
NOTE: If the path to the BRI file contains spaces, you must enclose the path with
quotation marks. For example, if you type the path C:\Program
Files\BREW\Examples\abc.bri, all characters in the path after the word Program
would be ignored. The correct way to type the path is: “C:\Program
Files\BREW\Examples\abc.bri.”
Creating string resources
A string resource element is an array of characters, which can be Unicode, ISOLATIN 1,
KSC5601, or S-JIS. Unicode is the default. By storing all the character strings that an applet
uses in a resource file, you can easily localize the applet for different countries.
To create string resources
1. From the BREW Resource Editor window, choose Resource > New String.
The String Resource dialog box opens.
14
Creating Resources
2. In the Resource ID field, a number is assigned automatically; however, it can be
changed if you want a specific ID assigned. The valid ID range is 1 to 32767, and
the ID must be a unique integer among string resources within the same resource
file (BRI).
NOTE: Within a given BRI file, all resources of a given type (strings, images,
dialogs, and all kinds of controls) must have unique ID numbers. For example,
when you are creating a BRI file for an application, you can assign Resource IDs
001, 002, and 003 to image resources, Resource IDs 001, 002, and 003 to string
resources, and List Item IDs 001, 002, and 003 to menu control list items. You
cannot, however, assign Resource ID 001 to two Image resources within the same
BRI file.
3. In the Resource Name field, enter a unique name assigned to the resource you are
creating. The name must be an array of contiguous characters (no spaces between
characters) that is valid for variable names in C/C++.
4. In the String Format field, select the format from the drop-down list. The default is
ISOLATIN 1.
5. In the Value field, enter the actual string content for the resource.
6. When you are finished defining string resources, click OK.
The String Resource dialog box closes, and the string resources you created
appear in the right pane of the BREW Resource Editor window.
15
Creating Resources
Creating image resources
An image resource is a graphical image that can be of different formats or types.
NOTE: Check the BREW web site for current information on the actual device and Emulator
image types.
To create image resources
1. From the BREW Resource Editor window, choose Resource > New Image.
The Image Resource dialog box opens.
16
Creating Resources
2. In the Resource ID field, a number is assigned automatically; however, you can
change it if you want a specific ID assigned. The valid ID integer range is 1 to
32767, and the ID must be unique among image resources within the resource file
(BRI).
NOTE: Within a given BRI file, all resources of a given type (strings, images,
dialogs, and all kinds of controls) must have unique ID numbers. For example,
when you are creating a BRI file for an application, you can assign Resource IDs
001, 002, and 003 to image resources, Resource IDs 001, 002, and 003 to string
resources, and List Item IDs 001, 002, and 003 to menu control list items. You
cannot, however, assign Resource ID 001 to two Image resources within the same
BRI file.
3. In the Resource Name field, enter the unique name assigned to the resource you
are creating. The name must be an array of contiguous characters (no spaces
between characters) that are valid for variable names in C/C++.
4. In the Path To File field, enter location of the Image file. If needed, click Browse to
search and choose the location. The image file path can be dragged and dropped
from Windows Explorer onto the Resource Editor.
5. When you are finished creating image resources, click OK.
The Image Resource dialog box closes, and image resources you created appear in the right pane of the BREW Resource Editor window.
17
Creating Resources
Creating dialog resources
A dialog resource consists of one or more BREW controls that are shown together on the
device screen. An application defines multiple dialogs for interfaces that lead the user through
a sequence of dialog boxes that request input. BREW applications use the CreateDialog
function of the IShell interface to load a dialog from a resource file and show its controls on the
display. Use functions in the IDateCtl, IMenuCtl, ITextCtl, and ITimeCtl interfaces to modify the
appearance and behavior of the dialog’s controls after it has been loaded, and to retrieve the
data the device user has entered or selected in each control. IShell’s EndDialog function
terminates a dialog and shows the previously active dialog, if any, on the device screen.
Dialog controls fall into four categories:
To create dialog resources
1. From the BREW Resource Editor window, choose Resource > New Dialog.
The Dialog Resource dialog box opens.
Menu item selection Lets the device user make a selection from a list of items. Controls in this category include menu controls, soft key controls, list controls, and icon view controls. Use functions in the IMenuCtl interface to manipulate menu controls in your application.
Date display and entry Lets the device user enter and display date information. Date controls and date-pick controls fall into this category. Use functions in the IDateCtl interface to manipulate data and date pick controls in your application.
Time display and entry Lets the device user enter and display time information. Stopwatch, clock, and countdown controls fall into this category. Use functions in the ITimeCtl interface to manipulate these controls in your application.
Text entry Lets the device user enter text information using the device keypad. Text controls fall into this category. Use functions in the ITextCtl interface to manipulate text controls in your application.
18
Creating Resources
2. In the Resource ID field, a number is assigned automatically; however, you can
change it if you want a specific ID assigned. The valid ID integer range is 1 to
32767, and the ID must be unique among dialog resources within the resource file
(BRI).
NOTE: Within a given BRI file, all resources of a given type (strings, images,
dialogs, and all kinds of controls) must have unique ID numbers. For example,
when you are creating a BRI file for an application, you can assign Resource IDs
001, 002, and 003 to image resources, Resource IDs 001, 002, and 003 to string
resources, and List Item IDs 001, 002, and 003 to menu control list items. You
cannot, however, assign Resource ID 001 to two Image resources within the same
BRI file.
3. In the Resource Name field, enter the unique name assigned to the dialog you are
creating. The name must be an array of contiguous characters (no spaces between
characters) that are valid for variable names in C/C++.
4. In the Dialog Title field, select the title of the dialog from the drop-down list, which
must come from one of the string resource elements. These string resource
elements will become available in a future release.
19
Creating Resources
5. In the Dialog Flags field, enter the dialog property flag that determines the look of
the dialog. By default, the flags are all set to 0 (zero). Dialogs support the
CP_BORDER and CP_3D_BORDER flags, which can draw a border around the
dialog box. Please refer to the IDialog interface section in the BREW API Reference for more information on the various dialog flags available.
6. In the Initial Focus ID field, enter the control in the dialog that has the focus when
the dialog is initially shown. By default, this is the ID of the first control you create
in the dialog.
7. In the Initial Position and Initial Size fields, enter the position (coordinates of upper
left hand corner) and size (in pixels) at the startup of the dialog. The default values
are -1 in each field, which indicates that the dialog occupies the entire device
display.
NOTE: For descriptions of the Dialog Control toolbar icons, see Creating Dialog
Controls on page 20.
8. When you are finished creating the dialog resource, click OK.
The Dialog Resource dialog box closes, and the dialog resource you created appears in the right pane of the BREW Resource Editor window.
20
Creating Dialog Controls
This section explains how to create dialog controls of the following types:
• Menus
• Date display and entry
• Time display and entry
• Text display
In each category of control, the steps for creating a control in that category are identical.
You can create dialog controls using the dialog control icon buttons that appear in the Dialog
Resource dialog box. Each icon represents the type of control you want to create.
New Menu Control
New Soft Key Control
New List Control
New Date Pick Control
New Date Control
New Icon View Control
New Text Control
New Countdown Control
New Clock Control
New Stop Watch Control
21
Creating Dialog Controls
The procedures in this guide describe how to perform various tasks using the icons on the
menu bar. However, you can perform the same functions using the shortcut menu that opens
when you right-click in the Dialog Controls area of the Dialog Resource dialog box, as shown
below.
Menus
BREW provides four types of menus:
• Menu control
• Soft Key control
• List control
• Icon View control
22
Creating Dialog Controls
Menu control
Use the Menu Ctl object to create a list of choices presented as vertically scrolling text items,
similar to the list shown below.
Soft Key control
Use the SoftKey Ctl object to create a list of choices presented as horizontally scrolling
buttons, similar to the list shown below.
23
Creating Dialog Controls
List control
Use the List Ctl object to create a list of choices that shows only the currently-selected menu
item on the screen, similar to the list shown below.
Icon View control
Use the Icon View Ctl to create a list of choices presented as icons, similar to the list shown
below.
24
Creating Dialog Controls
Creating Menus
The Menu Ctl object allows you to create a list of choices presented in the standard menu
style. After you have created the menu, you can define the items to be listed in the menu.
To create a menu
1. In the Dialog Resource dialog box, do one of the following:
a. To create a menu of vertically scrolling items, click the New Menu Control icon.
b. To create a menu of horizontally scrolling buttons, click the New Soft Key
Control icon.
c. To create a menu of vertically scrolling buttons, click the New List Control icon.
d. To create a menu of icons, click the New Icon View Control icon.
A corresponding Properties dialog box opens. For this example, the Menu
Properties dialog box is shown.
2. In the Control ID field, the number is preassigned automatically; however, you can
change it if you want a specific ID assigned. The valid ID integer range is 1 to
32767, and the ID must be unique among the controls within the resource file (BRI).
25
Creating Dialog Controls
NOTE: Within a given BRI file, all resources of a given type (strings, images,
dialogs, and all kinds of controls) must have unique ID numbers. For example,
when you are creating a BRI file for an application, you can assign Resource IDs
001, 002, and 003 to image resources, Resource IDs 001, 002, and 003 to string
resources, and List Item IDs 001, 002, and 003 to menu control list items. You
cannot, however, assign Resource ID 001 to two Image resources within the same
BRI file.
3. In the Control Name field, enter the unique name assigned to the control you are
creating. The name must be an array of contiguous characters (no spaces between
characters) that are valid for variable names in C/C++.
4. In the Control Flags field, enter the control properties bit vector to alter the default
appearance and behavior of the control. See the BREW API Reference for the
properties associated with each type of control.
5. In the Control Title field, select the title from the drop-down menu to be shown with
the control, which must come from one of the string resource elements.
6. In the Initial Position and Initial Size fields, enter the position (coordinates of upper
left hand corner) and size (in pixels) at the startup of the dialog. The default values
are -1 in each field, which indicates that the dialog occupies the entire device
display. See the BREW API Reference for more information.
7. Click OK.
The Properties dialog box closes, and the new dialog control appears in the list pane of the BREW Resource Editor window.
NOTE: To delete a menu or any other dialog control, select it from the Dialog
Resource dialog box and press Delete.
Managing list items
In the List Items section of the Properties dialog boxes, a list of choices is
presented by the controls shown. The following table shows the types of list items
you can add to the control types:
Control type Types of list items you can use
Menu Ctl TextImages
26
Creating Dialog Controls
The management of the list items in the Menu Properties dialog box is used in the
following example.
To create list items
1. Open the Dialog Resource dialog box.
2. Click the New Menu Control, New Soft Key Control, New List Control, or New Icon
View Control icon. The properties dialog box opens.
3. In the List Items area, right-click and choose New List Item from the shortcut menu
as shown.
The List Item Properties dialog box opens for input. The following is a sample entry:
SoftKey Ctl TextImages
List Ctl Text
Icon View Ctl Images
Control type Types of list items you can use
27
Creating Dialog Controls
4. In the List Item ID field, the number is preassigned automatically; however, you can
change it if you want a specific ID assigned. The valid ID integer range is 1 to
32767, and the ID must be unique among the list items within the resource file
(BRI).
When the device user chooses this item from the menu, a command event
(EVT_COMMAND) is sent to the applet with the list item ID as the word parameter
(wParam).
NOTE: Within a given BRI file, all resources of a given type (strings, images,
dialogs, and all kinds of controls) must have unique ID numbers. For example,
when you are creating a BRI file for an application, you can assign Resource IDs
001, 002, and 003 to image resources, Resource IDs 001, 002, and 003 to string
resources, and List Item IDs 001, 002, and 003 to menu control list items. You
cannot, however, assign Resource ID 001 to two Image resources within the same
BRI file.
5. In the List Item Name field, enter the unique name assigned to the list item you are
creating. The name must be an array of contiguous characters (no spaces between
characters) that are valid for variable names in C/C++.
6. In the Data field, enter the hex value associated with the list item. When the device
user chooses this list item, a command event (EVT_COMMAND) is sent to the
applet with this particular value as the double-word parameter (dwParam).
Although this value need not be unique, most items have unique data values. The
valid range of this value is 0 to FFFFFFFF.
7. From the List Item Text drop-down list, select the text that you want to appear for
this item in the menu control.
8. From the List Item Image drop-down list, select the image that you want to appear
for this item in the menu control.
9. When you are finished creating list items, click OK.
The List Item Properties dialog box closes, and the new list item appears in the list pane of the BREW Resource Editor window.
To modify list items
1. From the Dialog Resource dialog box, double-click the dialog control for which you
want to modify list items.
The Properties dialog box opens.
28
Creating Dialog Controls
2. Double-click the list item you want to modify.
The List Item Properties dialog box opens for editing.
3. When you are finished modifying list items, click OK.
The List Items Properties dialog box closes.
To delete list items
1. From the Dialog Resource dialog box, double-click the dialog control from which
you want to delete list items.
The Properties dialog box opens.
2. In the List Items area, select the item you want to delete, then press Delete.
The list item is removed from the list.
Date display and entry
BREW provides two types of controls for displaying and entering date information:
• Date control
• Date Pick control
29
Creating Dialog Controls
Date control
Use the Date Ctl object to create a list of dates in the Day of Week or Month Day, Year format.
Date Pick control
Use the Date Picker Ctl object to create a list of dates from a scrolling monthly calendar. The
format is seven consecutive days, starting with Sunday.
30
Creating Dialog Controls
To create an interface for date display and entry
1. In the Dialog Resource window, do one of the following:
a. To create a list of dates from a scrolling monthly calendar, click the New Date
Pick Control icon.
b. To create a list of dates in the Day of Week or MMDDYY format, click the New
Date Control icon.
A corresponding Properties dialog box opens. For this example, the Date Pick Properties dialog box is shown.
2. In the Control ID field, the number is preassigned automatically; however, you can
be change it if you want a specific ID assigned. The valid ID integer range is 1 to
32767, and the ID must be unique among the controls within the resource file (BRI).
NOTE: Within a given BRI file, all resources of a given type (strings, images,
dialogs, and all kinds of controls) must have unique ID numbers. For example,
when you are creating a BRI file for an application, you can assign Resource IDs
001, 002, and 003 to image resources, Resource IDs 001, 002, and 003 to string
resources, and List Item IDs 001, 002, and 003 to menu control list items. You
cannot, however, assign Resource ID 001 to two Image resources within the same
BRI file.
31
Creating Dialog Controls
3. In the Control Name field, enter the unique name assigned to the control you are
creating. The name must be an array of contiguous characters (no spaces between
characters) that are valid for variable names in C/C++.
4. In the Control Flags field, enter the control properties bit vector to alter the default
appearance and behavior of the control. See the BREW API Reference for more
information.
5. In the Initial Position and Initial Size fields, enter the position (coordinates of upper
left hand corner) and size (in pixels) at the startup of the dialog. The default values
are -1 in each field, which indicates that the dialog occupies the entire device
display. See the BREW API Reference for more information.
6. Click OK.
The Properties dialog box closes, and the new dialog control appears in the list
pane of the BREW Resource Editor window.
Time display and entry
BREW provides three types of controls for showing and entering time information:
• Clock control
• Stopwatch control
• Countdown Timer control
32
Creating Dialog Controls
Clock control
Use the Clock Ctl object to create an interface that shows the time.
Stopwatch control
Use the Stopwatch Ctl object to create an interface that measures elapsed time from any
arbitrary time point (A to B).
33
Creating Dialog Controls
Countdown control
Use the Countdown Ctl object to create an interface that counts down from an arbitrary amount
of time to 0 (zero).
To create an interface for time display and entry
1. In the Dialog Resource dialog box, do one of the following:
a. To create an interface that shows the time, click the New Stop Watch Control
icon.
b. To create an interface that measures elapsed time, click the New Clock Control
icon.
c. To create an interface that counts down to zero, click the New Countdown
Control icon.
The corresponding Properties dialog box opens. For this example, the Stop Watch
Properties dialog box is shown.
34
Creating Dialog Controls
2. In the Control ID field, the number is preassigned automatically; however, you can
change it if you want a specific ID assigned. The valid ID integer range is 1 to
32767, and the ID must be unique among the controls within the resource file (BRI).
NOTE: Within a given BRI file, all resources of a given type (strings, images,
dialogs, and all kinds of controls) must have unique ID numbers. For example,
when you are creating a BRI file for an application, you can assign Resource IDs
001, 002, and 003 to image resources, Resource IDs 001, 002, and 003 to string
resources, and List Item IDs 001, 002, and 003 to menu control list items. You
cannot, however, assign Resource ID 001 to two Image resources within the same
BRI file.
3. In the Control Name field, enter the unique name assigned to the control you are
creating. The name must be an array of contiguous characters (no spaces between
characters) that are valid for variable names in C/C++.
4. In the Control Flags field, enter the control properties bit vector to alter the default
appearance and behavior of the control. See the BREW API Reference for more
information.
5. In the Initial Position and Initial Size fields, enter the position (coordinates of upper
left hand corner) and size (in pixels) at the startup of the dialog. The default is -1 in
each field, which indicates that the dialog occupies the entire device display.
6. Click OK.
The Properties dialog box closes, and the new dialog control appears in the list
pane of the BREW Resource Editor window.
35
Creating Dialog Controls
Text entry
BREW provides the following control for entering text information.
Text control
Use the Text Ctl object to create an interface for inputting, outputting, and manipulating text.
To create an interface for text entry
1. In the Dialog Resource dialog box, click the New Text Control icon.
The Text Properties dialog box opens.
36
Creating Dialog Controls
2. In the Control ID field, the number is preassigned automatically; however, you can
change it if you want a specific ID assigned. The valid ID integer range is 1 to
32767, and the ID must be unique among the controls within the resource file (BRI).
NOTE: Within a given BRI file, all resources of a given type (strings, images,
dialogs, and all kinds of controls) must have unique ID numbers. For example,
when you are creating a BRI file for an application, you can assign Resource IDs
001, 002, and 003 to image resources, Resource IDs 001, 002, and 003 to string
resources, and List Item IDs 001, 002, and 003 to menu control list items. You
cannot, however, assign Resource ID 001 to two Image resources within the same
BRI file.
3. In the Control Name field, enter the unique name assigned to the control you are
creating. The name must be an array of contiguous characters (no spaces between
characters) that are valid for variable names in C/C++.
4. In the Control Flags field, enter the control properties bit vector to alter the default
appearance and behavior of the control. See the BREW API Reference for more
information.
5. In the Initial Position and Initial Size fields, enter the position (coordinates of upper
left hand corner) and size (in pixels) at the startup of the dialog. The default values
are -1 in each field, which indicates that the dialog occupies the entire device
display. See the BREW API Reference for more information.
6. In the Control Title field, select the title to be shown with the control.
37
Creating Dialog Controls
7. In the Control Text field, select the initial text to be shown in the text control area
from the drop-down list.
8. Click OK.
The Properties dialog box closes, and the new dialog control appears in the list
pane of the BREW Resource Editor window.
38
Compiling Resource Files
This section covers the following topics:
• Types of output files
• Saving intermediate files
• Compiling BREW Resource files
Types of output files
There are three types of output files:
• The intermediate format file (BRI)
• BREW Resource file (BAR)
• BREW Resource header file (_RES.H)
All three file types (BRI, BAR, and _RES.H) are placed in the same directory. If you try to
generate the final output without saving the intermediate file, the Save dialog box prompts for
the name and directory path of the intermediate file. The same directory and root name (BRI
filename without the BRI extension) are used to generate the BAR and _RES.H files.
Conversely, if the intermediate file is saved before generating the BAR file, you are not
prompted for the name and directory path. The Resource Editor uses the stored directory
name and root name of the intermediate file to generate the final output filenames.
Compiling BREW resource files
Before you can compile BREW Resource files (BAR), the corresponding intermediate files
must be saved.
39
Compiling Resource Files
To compile BREW resource files
1. In the BREW Resource Editor window, choose Build > Build QUALCOMM
.BAR/.H files.
If you have already saved the intermediate files, the final output files are saved. If
you have not previously saved the intermediate files, the Save As dialog box opens.
2. Indicate where you want the BRI file stored, assign it a name, and click Save.
The final output files are saved.
40
Index
AAcronyms and terms, 6ARM compiler, 11ASCII (ISOLATIN1) character string, 13
BBREW Applet Resource file (BAR file), 9, 11, 38BREW features, how to request new ones, 6BREW Resource header file (See RES.H file), 9BREW Resource Intermediate file (BRI file), 9, 38
CClock control
description, 8how to use, 32
Compiling Resource files, 39Control Flags fields, 25Control type descriptions, 8Countdown control
description, 9how to use, 33
CreateDialog function, 11, 17Creating
dialog resources, 17image resources, 15interface for date display and entry, 30interface for text entry, 35interface for time display and entry, 33menu, 24string resources, 13
DDate control
description, 8how to use, 29
Date display and entry controldate control, 29date pick control, 29how it functions, 17types of, 28
Date pick controldescription, 8how to use, 29
Dialog controlsicon view, 23list, 23menu, 21menu item, 17soft key, 22types of, 20
Dialog resourcecreating, 17description, 8
Documentation set, 6dwParam, double-word parameter, 27Dynamic-link library file (DLL file), 10, 11
EEmulator, 11EndDialog function, 17EVT_COMMAND command, 27
FFile formats, BAR, BRI, _RES.H, 9
IIcon view control
description, 9when to use, 23
IDateCtl interface, 17Image resource
creating, 15description, 8dialog box, 15
IMenuCtl, interface, 17IShell interface, 11, 17ISOLATIN1 (ASCII) character string, 13ITextCtl interface, 17ITimeCtl interface, 17
LLIB file, 11List control
description, 8when to use, 23
Index
41
List items, managing, 25LoadRes function, 11
MManaging list items, 25Menu control
creating a menu, 24description, 8how it functions, 17managing list items, 25when to use, 22
Menu types of control, 21Menu, creating, 24MIF and MIF directories, 10MOD file, 11
NNew BREW features, how to request, 6
OOutput file types
_RES.H file, 38BREW Applet Resource file (BAR file), 38BREW Resource Intermediate file (BRI
file), 38
PProperties
date display and entry controls, 30menus, soft keys, lists, and icon views, 24stopwatch, clock, and countdown
controls, 33text control, 35
RRequesting new BREW features, how to, 6RES.H file, 9, 10Resource Compiler, 9Resource Editor
creating dialog resources, 17creating image resources, 15creating string resources, 13file formats, 9main window description, 12overview, 8resource types, 11role in the BREW SDK, 10supporting different devices, 11supporting different languages, 11the process, 9
Resource filescompiling, 38using on an actual device, 11
Resource files, compiling, 39Resource type descriptions, 8
SS-JIS character string, 13Soft key control
description, 8when to use, 22
Stopwatch controldescription, 8how to use, 32
String resourcecreating, 13description, 8
TTechnical support, 7Text control
description, 9how to use, 35
Text entry control, how it functions, 17Time display and entry control
clock, 32countdown, 33how it functions, 17stopwatch, 32types of, 31
Types of controls, descriptions, 8Types of menu controls, 21
UUnicode character string, 13
WWeb site address, 7