Brew Resource Editor Guide

QUALCOMM Incorporated 5775 Morehouse Drive San Diego, CA. 92121-1714 U.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

Contents Introducing the BREW Resource Editor Guide, 5 BREW documentation set, 6 BREW acronyms and terms, 6 Requesting new BREW features, 6 For more information, 7

BREW Resource Editor Overview, 8 Types of resources, 8 Controls, 8 File formats, 9 Role of the Resource Editor, 10 Running applications on various devices in different languages, 11 Running applets on an actual device, 11

Creating Resources, 12 Running the Resource Editor, 12 Creating string resources, 13 Creating image resources, 15 Creating dialog resources, 17

Creating Dialog Controls, 20 Menus, 21 Menu control, 22 Soft Key control, 22 List control, 23 Icon View control, 23 Creating Menus, 24 Managing list items, 25 Date display and entry, 28 Date control, 29 Date Pick control, 29

iii

Contents

Time display and entry, 31 Clock control, 32 Stopwatch control, 32 Countdown control, 33 Text entry, 35 Text control, 35

Compiling Resource Files, 38 Types of output files, 38 Compiling BREW resource files, 38

Index, 40

iv

Introducing the BREW 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.

5

Introducing the BREW Resource Editor Guide

BREW documentation set The BREW documentation set includes the following documents: 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 BREWenabled 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 Image Authoring Guide

Describes how to use the BREW Compressed Image Authoring Tool to create files for displaying and animating images in your applications.

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.

6

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.

7

BREW Resource Editor Overview 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: 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.

Controls Following are the types of controls supported by the Resource Editor: 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.

8

BREW Resource Editor Overview

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.

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

9

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.

10

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.

11

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.

12

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 . 3. Type the following command: BREW_Res [-f ]

where: , 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.

13

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.

14

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.

15

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.

16

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:

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.

To create dialog resources 1. From the BREW Resource Editor window, choose Resource > New Dialog.

The Dialog Resource dialog box opens.

17

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.

18

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.

19

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 Stop Watch Control New Clock Control New Countdown Control New Text Control New Icon View Control

New Date Control New Date Pick Control New List Control New Soft Key Control New Menu Control

20

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

21

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.

22

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.

23

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).

24

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

Text Images

25

Creating Dialog Controls

Control type

Types of list items you can use

SoftKey Ctl

Text Images

List Ctl

Text

Icon View Ctl

Images

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:

26

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.

27

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

28

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.

29

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.

30

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

31

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).

32

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.

33

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.

34

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.

35

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.

36

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.

37

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.

38

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.

39

Index A

Dialog controls icon view, 23 list, 23 menu, 21 menu item, 17 soft key, 22 types of, 20 Dialog resource creating, 17 description, 8 Documentation set, 6 dwParam, double-word parameter, 27 Dynamic-link library file (DLL file), 10, 11

Acronyms and terms, 6 ARM compiler, 11 ASCII (ISOLATIN1) character string, 13

B BREW Applet Resource file (BAR file), 9, 11, 38 BREW features, how to request new ones, 6 BREW Resource header file (See RES.H file), 9 BREW Resource Intermediate file (BRI file), 9, 38

C

E

Clock control description, 8 how to use, 32 Compiling Resource files, 39 Control Flags fields, 25 Control type descriptions, 8 Countdown control description, 9 how to use, 33 CreateDialog function, 11, 17 Creating dialog resources, 17 image resources, 15 interface for date display and entry, 30 interface for text entry, 35 interface for time display and entry, 33 menu, 24 string resources, 13

Emulator, 11 EndDialog function, 17 EVT_COMMAND command, 27

F File formats, BAR, BRI, _RES.H, 9

I Icon view control description, 9 when to use, 23 IDateCtl interface, 17 Image resource creating, 15 description, 8 dialog box, 15 IMenuCtl, interface, 17 IShell interface, 11, 17 ISOLATIN1 (ASCII) character string, 13 ITextCtl interface, 17 ITimeCtl interface, 17

D Date control description, 8 how to use, 29 Date display and entry control date control, 29 date pick control, 29 how it functions, 17 types of, 28 Date pick control description, 8 how to use, 29

L LIB file, 11 List control description, 8 when to use, 23

40

Index

Resource files compiling, 38 using on an actual device, 11 Resource files, compiling, 39 Resource type descriptions, 8

List items, managing, 25 LoadRes function, 11

M Managing list items, 25 Menu control creating a menu, 24 description, 8 how it functions, 17 managing list items, 25 when to use, 22 Menu types of control, 21 Menu, creating, 24 MIF and MIF directories, 10 MOD file, 11

S S-JIS character string, 13 Soft key control description, 8 when to use, 22 Stopwatch control description, 8 how to use, 32 String resource creating, 13 description, 8

N New BREW features, how to request, 6

T

O

Technical support, 7 Text control description, 9 how to use, 35 Text entry control, how it functions, 17 Time display and entry control clock, 32 countdown, 33 how it functions, 17 stopwatch, 32 types of, 31 Types of controls, descriptions, 8 Types of menu controls, 21

Output file types _RES.H file, 38 BREW Applet Resource file (BAR file), 38 BREW Resource Intermediate file (BRI file), 38

P Properties date display and entry controls, 30 menus, soft keys, lists, and icon views, 24 stopwatch, clock, and countdown controls, 33 text control, 35

U Unicode character string, 13

R

W

Requesting new BREW features, how to, 6 RES.H file, 9, 10 Resource Compiler, 9 Resource Editor creating dialog resources, 17 creating image resources, 15 creating string resources, 13 file formats, 9 main window description, 12 overview, 8 resource types, 11 role in the BREW SDK, 10 supporting different devices, 11 supporting different languages, 11 the process, 9

Web site address, 7

41