Oracle Forms Developer and Reports Developer Release 6i: Guidelines for Building Applications A73073-01 |

|  | Contents | Index

# 5
Designing Portable Applications

With both Forms Developer and Reports Developer, deploying a single application on multiple platforms--Windows, Motif, the Web, even character-mode--is simply a matter of re-compiling. Both Forms Developer and Reports Developer automatically translate the standard control objects (buttons, check boxes, radio buttons, and so on) to the appropriate format for your target platforms. With careful pre-development planning, you can create a single application that satisfies users across environments, providing each with the native look and feel they expect.

This chapter helps you anticipate the issues you will face when developing portable applications and provides suggestions for ensuring that you can move your application across platforms with ease

#####

Section | Description
--- | ---
Section 5.1, "Before You Begin" | Presents some high-level questions you should answer before developing a portable application.
Section 5.2, "Designing Portable Forms" | Addresses issues of portability with respect to the GUI and the operating system. Also discusses an approach for cross-platform development, as well as considerations unique to the character-mode environment.
Section 5.3, "Designing Portable Reports" | Discusses developing a report for maximum portability.
Section 5.4, "Designing Portable Displays" | Discusses developing a display for maximum portability.

.

If you're using Project Builder to manage your application, see Section 1.2.4, "Managing projects and project documents across multiple platforms" in Chapter 1.

## 5.1 Before You Begin

Before you begin designing any application--not just those you intend to port--it's important that you take time to think about the needs you are trying to address with your application. At a minimum, you should have answers to the following questions:

- Which platforms are you supporting? If you plan to deploy on more than one platform, you must consider issues such as fonts, colors, layout, screen size, and screen resolution, to name a few. Section 5.2.1, "Considering the GUI" helps you tackle these issues.

- Is character-mode support required? If so, your options are considerably limited. Consult Section 5.2.4, "Designing forms for character-mode" or Section 5.3.1, "Designing a report for character-mode environments" for some recommendations.

- What displays must you accommodate? Displays can vary a great deal, even on the same deployment platform. See Section 5.2.1.2, "Considering monitors" for a discussion on the limitations monitors can impose.

- Will your application rely on user exits or foreign functions? You'll probably have to rewrite them for each of your target platforms. Section 5.2.2.1, "Including user exits" offers some suggestions and workarounds.

## 5.2 Designing Portable Forms

Whether you're designing a new form for multiple platforms or preparing an existing form for a new environment, the issues you face fall into the same two key areas, described in the following sections:

- Section 5.2.1, "Considering the GUI"

- Section 5.2.2, "Considering the operating system"

If you've never developed for multiple platforms before, you may also wish to read Section 5.2.3, "Strategies for developing cross-platform forms" for some recommendations on how to approach cross-platform development. If you're developing for character-mode, see Section 5.2.4, "Designing forms for character-mode" for considerations unique to that environment.

### 5.2.1 Considering the GUI

When developing a portable application, the first thing you must decide is whether the GUI should look the same across all platforms, or if your users expect the application to inherit the native look-and-feel of their own environment. In most cases, you'll probably opt for the latter approach. However, if users are likely to use the application on multiple platforms, they'll probably want it to look the same on all of them, ignoring local conventions. The only way to determine this is to interview your users, paying close attention to how they work and which tasks they're trying to perform. (See Section 2.1.2, "Defining user requirements" for suggestions on how to determine users' needs.)

Once you've made your decision, the next step is to create an object library for each platform you're supporting. An object library is a set of objects and standards that you create; each object or standard can determine the appearance and layout of an entire frame, window, or region. When housed in an object library, these objects become available to all the developers on your project or site, thus ensuring that even developers working at different locations can produce an application--or different modules within the same application--with a common look and feel.

To fully exploit the power of the object library, it's a good idea to create one library for each of your target platforms. To help you populate your libraries, Form Builder provides the Oracle Applications Object Library, a set of layouts and items that function well in all of Forms Developer's GUI deployment environments (Windows 95, Motif), as well as character-mode. Test these items and objects one by one on each of your platforms. You should be able to add most of the objects to your libraries without modification, although some may need slight adjustment to meet platform-specific requirements.

Section 5.2.3, "Strategies for developing cross-platform forms" provides more details on how to incorporate your object libraries into an overall development strategy.

#### 5.2.1.1 Choosing a coordinate system

For GUI terminals, use the Real Inch, Real Centimeter, or Real Point coordinate systems. These systems allows you to size your objects to the exact shape you want instead of being snapped to the nearest character cell size.

If you're designing for character-mode, use the Character coordinate system and turn on the grid snap. This will ensure that your objects' sizes are in multiples of the character cell size. See Section 5.2.4, "Designing forms for character-mode" for more information on designing character-mode applications.

#### 5.2.1.2 Considering monitors

Even on the same platform, monitors of different sizes and resolutions can greatly impact the usability of your application. For example, while a 6 pt. font on a laptop running Windows 95 is unreadable, the same font on a 17-inch monitor is perfectly acceptable. The only way to be certain your application is truly portable is to thoroughly test your application on each of the monitors in the deployment environment.

If there are several different sized monitors in your deployment environment, design for the smallest size. Taking the time to find out which monitors your users have--and how many use each size--can help you plan your application more effectively. For example, if your mobile sales force uses laptops for lead tracking and sales management applications, but everyone else uses 17-inch SVGA terminals, you can simplify your task by restricting the window size of only the two critical laptop applications.

##### Table 5-1 Platform restrictions: Monitors

Platform | Monitor Restrictions
--- | ---
Windows | Size is determined by screen resolution, not by absolute measurement. For example, widgets developed on a 96 dots per inch (dpi) 17-inch monitor appear smaller than the same widgets displayed on a 20-inch 96 dpi monitor, even though the measurement systems appear to be the same. In other words, an inch is not always an inch on Windows.
Motif | Many Motif users are limited to gray-scale monitors, so you can't rely on color for those users.

#### 5.2.1.3 Using color

Restrain your use of color to three or four basic colors that work well together. Colors that are typically available on many platforms include blue, red, magenta, cyan, green and yellow.

Using too many colors can exceed the system's maximum color limit and cause background objects to snap to strange colors, leaving only the foreground color intact. Be sure to test your color combination on all target systems, including monochrome, gray-scale monitors, to make sure they work as expected.

##### Table 5-2 Platform restrictions: Color

Platform | Color Restrictions
--- | ---
Windows | Widgets can be one of 16 colors defined in the system color palette. If you assign another color, the widget snaps to the closest of the sixteen.
Motif | Many Motif users are limited to gray-scale monitors; do not use color to make important distinctions.

#### 5.2.1.4 Resolving font issues

Fonts play a fundamental role in the user's sense of familiarity and comfort with a GUI system. Table 5-3 lists the recommended font for each GUI platform:

##### Table 5-3 Platform recommendations: Fonts

Platform | Font
--- | ---
Windows | MS Sans Serif
Motif | Helvetica

When developing a portable application, decide early how you'll use font styles such as boldface, italics, and underlining. (In general, you shouldn't need either underlining or italics; use boldface sparingly, and only for emphasis.) You should also standardize the type size of different display objects. For example, making all labels 10 points will help if you need to translate a font on a different platform.

To meet users' expectations, a ported application must be rendered in the expected font on each platform. To achieve this, you must translate the fonts between platforms using either of these methods:

- Defining aliases for fonts on each deployment platform

- Defining port-specific classes

The next two sections briefly outline these processes.

Note: On Motif, each different size of a given font is considered a separate entity that must be explicitly installed from the font file. For example, suppose you want to port a Windows-based form containing 10, 12, and 28 point Arial fonts to Motif. Rather than simply verifying that Arial has been installed on Motif, you must ensure that each of the desired point sizes--10, 12, and 28--have been installed as well. If Forms Developer can't find the font it needs on the target platform, it substitutes another font using a platform-specific "closest match" algorithm.

##### 5.2.1.4.1 Defining font aliases

Forms Developer provides a font alias file for each platform (UIFONT.ALI,in the ORACLEHOME\TOOLS\COMMON60 directory). In most cases, the file ensures that fonts appear consistently across platforms. However, if you employ custom or non-standard fonts in your applications, some of them may not be recognized on all target platforms. You can tailor the font alias file to define substitutions for the fonts that are not recognized.

Enter each line in the file in this format:

    source_font = destination_font

For each font, you can specify these attributes:

    <face>.<size>.<style>.<weight>.<width>.<character_set>

Example:

When porting from MS Windows to Motif, change all MS Sans Serif fonts to Helvetica:

    "MS Sans Serif"=Helvetica

See the Form Builder online help for more information and examples of font mapping.

##### 5.2.1.4.2 Using classes

When you require greater control over your font aliasing, use classes. For example, suppose you want your poplists and text items to have different fonts on Motif, rather than just imposing a strict conversion of MS Sans Serif to Helvetica. To achieve this:

1. Create two classes, one for poplists and the other for text items.

2. On MS Windows, specify that both classes use MS Sans Serif as the font in Window.olb. (See Section 5.2.3.1, "Creating a single source" for information on Window.olb.)

3. In Motif.olb, specify that the poplist class uses the Helvetica 9-point font; specify that the text item class uses Helvetica 11-point.

This approach allows you to customize the font used for each class of objects in your application, thus providing a higher level of flexibility.

#### 5.2.1.5 Using icons

Icons are platform-specific. If you use iconic buttons in your application, create a separate icon directory for each platform. Use the same names for the icons on each platform and set the respective environment variable to point to the icon directory. On MS Windows and Motif, this variable is TK25_ICON.

If you include icons in your application, keep the following in mind:

- Icons rendered on small monitors (like laptops) can be too small to read.

- Certain icons have special meanings on certain platforms.

#### 5.2.1.6 Using buttons

In MS Windows, a button's moat (the emphatic border around a button to designate a default) is very small compared to that on Motif. Therefore, buttons appear to shrink when run on Motif. On Motif, you can avoid this by modifying the Motif resource file, Tk2Motif in ORACLE_HOME/BIN. (Oracle uses Motif resource files to control the visual appearance of UNIX-based applications.)

1. Locate the Tk2Motif file for your display type:

   - .gs (gray scale)

   - .bw (black and white)

   - .rgb (color)

2. Edit the Tk2Motif file and set the Tk2Motif expandNonDefaultButtons property to True.

In general, always provide enough space in your Windows buttons to accommodate the larger button size in Motif.

To maximize portability, make all buttons non-navigable. In Windows and Motif, clicking a button means the user actually navigates to the button. Because triggers are often dependent upon button navigation, this difference across platforms can create significant behavioral differences in your application.

Note: Making Windows and Motif buttons non-navigable is an excellent example of the kind of trade-off you might have to make if consistency across platforms is more important than adhering to standard platform behavior.

#### 5.2.1.7 Creating menus

The placement and behavior of menus varies across platforms, as shown in Table 5-4:

##### Table 5-4 Platform restrictions: Menus

Platform | Menu Restrictions
--- | ---
Windows | Supports Multiple Document Interface (MDI) and Single Document Interface (SDI). In MDI, all windows belonging to an application are contained in a single window, and there is only one menu for the entire application. SDI is similar to Motif in that each window has its own menu.
Motif | Every window has a menu attached. The menu on a parent window may or may not be repeated on child windows.

If you are using a version of Windows that supports MDI and you want your applications to look the same across all platforms, specify in Motif that you do not want to repeat the parent window menu on child windows. Then you can design the parent window menu to look exactly like that on MS Windows.

Note: To prevent the screen from flashing when switching between form module windows, combine all the menu options into one single menu application and use the SET_MENU_ITEM_PROPERTY built-in to dynamically enable/disable the respective menu items accordingly.

#### 5.2.1.8 Creating the console

Like menus, the placement and behavior of the console also varies across platforms, as shown in Table 5-5:

##### Table 5-5 Platform restrictions: Console

Platform | Console Restrictions
--- | ---
Windows | Appears at the bottom of the MDI window only.
Motif | Appears on the user-specified window.

To achieve consistency across platforms, place the console on the parent window in your Motif application to emulate the behavior of MDI Windows applications.

#### 5.2.1.9 Miscellaneous

- When building a form for multiple platforms, right-align all prompts. Text often expands when ported to other platforms, and left-aligned prompts can cause fields to shift, creating a ragged margin.

- To provide complex functionality that is completely portable across platforms, employ one or more reusable components in your application. These reusable components are provided in the Demos and Add-ons, to help you build applications upon such powerful features as:

  - Navigator (Explorer) style interface

  - Wizard style interface that mimics the Wizards in Forms Developer and other Windows 95 products

  - Calendar window that automatically displays the calendar according to the NLS settings currently in effect

  - Image and icon files

  - Standard menu in the Windows style

  Refer to "Reusable Components" (under Forms Developer Demos) in the Form Builder online help for more information.

- Table 5-6 lists other miscellaneous issues related to porting GUIs:

  ##### Table 5-6 Platform restrictions: General

  Platform | General Restrictions
  --- | ---
  Windows | A known positioning problem causes two lines forming a right angle on VGA screens to actually overlap on SVGA. Use bevels to avoid this problem.
  Motif | (none)

### 5.2.2 Considering the operating system

No application is truly portable if it depends on functionality unique to a particular operating system. Here are some general rules to keep in mind:

- Avoid port-specific terminology when writing messages. For example, a message like "Press F1 for help" is not portable.

- Do not hardcode path names; path names vary across platforms. Instead, use environment variables to enable Form Builder to find your files during runtime.

  Suppose you need to read an image file called OPEN.BMP from your form. In a Windows-only application, you could simply code the path name in the call to READ_IMAGE_FILE:

      Read_Image_File(`c:\orawin95\myapp\open.bmp', `BMP', `block1.image3');

  If you want the application to be portable, however, hardcoding won't work, since the name of the path is different on each platform. Instead, you can use an external variable to represent the path name.

  For example, in Windows95 or WindowsNT:

  1. Create a registry entry called path_var under the ORACLE key; in UNIX, create a shell variable also named path_var.

  2. Use the GETVAR procedure in the TOOL_ENV package to retrieve the value path_var using this platform-independent method:

         path_var varchar2(255);
         ...
         Tool_env.getvar(`MYPATH', path_var);
         Read_Image_File(path_var||'open.bmp', `BMP','block1.image3')'

     The platform-specific path name, represented by the variable path_var, is appended to the name of the image file, OPEN.BMP. On Window95, path_var resolves to the path name C:\ORAWIN95\MYAPP\. On UNIX, path_var is something like /oracle_home/myapp/.

- Anything called through the HOST built-in procedure. Host commands execute port-specific operating system commands. To make your application easier to port:

  1. Create a separate procedure library (.PLL) for each platform.

  2. Place all operating system commands in the appropriate procedure library.

  3. Create a generic procedure library.

  4. Rewrite the script file for each platform, ensuring that each script has the same name.

  5. In your form module, make sure all calls refer to the generic procedure library.

  6. Before compiling on a given platform, copy that platform's .PLL to the generic procedure library.

  7. Compile.

  Section 5.2.3, "Strategies for developing cross-platform forms" explains how this handling of procedure libraries fits into the recommended development strategy for portable applications.

- Context-sensitive help is not portable. If your application uses native context-sensitive help, replace it with Forms Developer's portable help component, the Online Help Class. This component enables you provide context-sensitive help in your application similar to Windows 95 help.

  The component is built using Form Builder and PL/SQL native capabilities, so it is portable to all Forms-supported platforms. Because the help text you create is stored in the database, it is accessible to all users, and updates are immediately available to everyone.

  To use the Online Help Class in your application:

  1. Install the database objects.

  2. Create the help text for your application.

  3. Attach a PL/SQL library and add code in your key-help trigger to call the help as required.

  Refer to the help topic About the Online Help Class" under Forms Developer Demos in the Form Builder online help for step-by-step instructions.

- Avoid including the platform-specific methods listed in Table 5-7.

  ##### Table 5-7 Platform-specific methods to avoid

  Platform | Method
  --- | ---
  Windows | VBX controls OLE containers ActiveX (OCX) DLLs (ORA_FFI)
  Motif | Calls to loadable libraries (ORA_FFI)

  These objects leave placeholders (empty spaces) on the platforms that do not support them. If you must include these objects in your application, see Section 5.2.3.4, "Hiding objects" for information on how to prevent the placeholders from appearing.

#### 5.2.2.1 Including user exits

A user exit is a 3GL program you write yourself and then link into a form at compile time. User exits are always port-specific.

Before calling a 3GL program from your portable form, verify that the information and processes on which the program relies are available on all platforms. For example, a program that depends on information from the Windows registry can't access this information on other platforms, which means you may have to re-design the program or abandon it entirely.

Rather than accessing a 3GL program through the user interface exit, consider the use of the ORA_FFI built-in package (Oracle Foreign Function Interface). If you use the user exit interface to access your foreign functions, you must re-link the user exits or replace the DLL for each platform each time a 3GL program changes. Because ORA_FFI allows you to call foreign functions through a PL/SQL interface using PL/SQL language conventions, re-linking isn't required when you modify a program. For this reason, ORA_FFI is the preferred method for accessing 3GL programs from your forms.

### 5.2.3 Strategies for developing cross-platform forms

This section introduces some techniques you can use to develop portable forms:

- Section 5.2.3.1, "Creating a single source" describes an architecture for creating a single source that delivers maximum functionality on each of your deployment platforms.

- Section 5.2.3.2, "Subclassing visual attributes" discusses the importance of explicitly subclassing the visual attributes stored in your object libraries.

- Section 5.2.3.3, "Using the get_application_property built-in" discusses the use of this Form Builder built-in when developing portable applications.

- Section 5.2.3.4, "Hiding objects" provides sample code for removing the placeholders that appear when an object is not valid on a particular platform.

#### 5.2.3.1 Creating a single source

While it may be tempting to consider creating a single source that aims at the lowest common denominator for all deployment platforms, this strategy severely limits the aesthetics you can provide in your application. A more effective strategy is to create a single source that delivers applications in each platform's native look-and-feel. The architecture depicted in illustrates how you might accomplish this:

#### Figure 5-1 Port-specific implementation

#### Figure 5-2 Port-specific implementation

To model your application on this architecture:

1. Create an object library for all standards and objects (Porting.olb). Refer to Section 2.2.2.1, "Using object libraries" in Chapter 2 for information on using object libraries.

2. Create separate object libraries for each deployment platform (Window.olb, Motif.olb, Mac.olb, Charmode.olb).

3. Create a common library for port-specific code (Porting.pll).

4. Create separate libraries for each platform's port-specific code (Window.pll, Motif.pll, Mac.pll, Charmode.pll).

5. In each platform's UI repository (.OLB) and library (.PLL), develop code to handle the application objects in the manner ideal for that particular platform. Use the same name for a given object in each UI repository and library.

6. Write your application, referring to the standards and objects in the repository and to the port-specific code in the library.

7. When you're ready to compile your application for a particular platform, copy that UI's repository and library to Porting.olb and Porting.pll and compile.

#### 5.2.3.2 Subclassing visual attributes

Visual attributes are the font, color, and pattern properties you set for form and menu objects. By carefully defining the visual attributes of your form objects, you can ensure that users on each platform enjoy the native look-and-feel unique to that environment.

Many Form Builder objects, such as items and canvases, refer to visual attributes to define their appearance. Visual attributes must be defined in the same module as the object that refers to them.

Visual attributes are usually stored in an object library. It's a good idea to create subclasses of these visual attributes in each module. When you subclass an object from an object library in your form, any changes made to the library object are automatically applied to the form object. However, this does not apply to changes made to the library object's visual attributes. So, by subclassing, rather than coping the visual attributes, you ensure that your modules always reflect the latest definition of the visual attributes.

#### 5.2.3.3 Using the get_application_property built-in

The GET_APPLICATION_PROPERTY built-in function returns information about your application, allowing you to react dynamically at runtime based on the settings of one or more of these variables:

- DISPLAY_HEIGHT and DISPLAY_WIDTH. Specifies how big the current display is. The unit depends on how you have set up the form coordinate system.

- OPERATING_SYSTEM. Specifies the name of the platform on which the application currently is running (MSWINDOWS, WIN32COMMON, SunOS, VMS, UNIX, or HP-UX).

- USER_INTERFACE: Specifies the name of the user interface technology on which the application is currently running (WEB, MOTIF, MSWINDOWS, MSWINDOWS32, PM, X, VARCHAR2MODE, BLOCKMODE, or UNKNOWN).

Depending on the value of a variable, you can dynamically hide objects that are not available on that deployment platform, reposition other objects to take up that space and, if necessary, alter the attributes of an object to suit the standards on that deployment platform. See Section 5.2.3.4, "Hiding objects" for more information.

#### 5.2.3.4 Hiding objects

To prevent users from seeing placeholders on platforms that do not support OLE, VBX, and ActiveX objects, you can put these objects in a separate window invoked from the menu or a button and dynamically enable/disable the menu item or button. Or you can use this code fragment to hide/show the port-specific objects and reposition other objects to take their place:

    WHEN-NEW-FORM-INSTANCE trigger:
    declare
    ui  varchar2(15) ;
    begin
    	ui := get_application_property (user_interface);
    if ui = `CHARMODE' or ui = `MOTIF' then
       set_item_property (`VBXOBJECT1', displayed, property_false);
       set_item_property (`OLEOBJECT1', displayed, property_false);
    	   set_item_property (`TEXTITEM1', position, 43, 4);
    end if;
    end;

Note: Item prompts are automatically hidden when you hide the associated item.

### 5.2.4 Designing forms for character-mode

If you are creating an application for both character-mode and bit-mapped environments, single-sourcing is probably not the best approach. Developing for the lowest common denominator, character-mode, deprives your GUI users of the ease of use associated with bit-mapped controls. The "Bit-map Only" column in Table 5-8 lists the functions you'd have to avoid:

##### Table 5-8 Character-mode vs. bit-mapped environments

Character Mode | Bit-map Only
--- | ---
Boxes Horizontal lines Vertical lines ASCII text Boldface text Underlines | Images Color Drawings Ellipses Drill-down buttons (reports) Italicized text Bit-map patterns Diagonal lines Multimedia support

While there are methods for disabling these GUI functions in a character-mode environment, this task can be extremely time-consuming and frustrating for you. So, if you know from the beginning that you have to support these two widely disparate sets of users, it's best for everyone--you and your users--to simply create two entirely separate applications.

It's much easier to develop for character-mode if you make Form Builder look like character-mode as much as possible. Table 5-9 lists some recommended property settings:

##### Table 5-9 Property settings that resemble character-mode

Property | Recommendations/Notes
--- | ---
Boilerplate font | Windows: FixedSys, Regular, 9 pt Motif: Font=Fixed, Size=12.0, Weight=Medium, Style=Plain
Coordinate information | Coordinate system: Real1 Real Unit: Point Character Cell Width: 6 Character Cell Height: 14
View | Grid: on Grid Snap: on Show Canvas: off
View'Settings'RulerView->Settings->Ruler | Units: Character cells Character Cell Size Horizontal: 6 Character Cell Size Vertical: 14 Grid Spacing: 1 Snap Points per Grid Spacing: 2

1 Improves portability of the form from character-mode to bit-mapped environments. If the form will be deployed in character-mode only, use the Character coordinate system.

As you develop your application strictly for character-mode, keep the following in mind:

##### Table 5-10 Recommendations for character-mode applications

Topic | Recommendations/Notes
--- | ---
General | Remember that everything is in monospace font. Create keyboard equivalents for each widget, even when the widget does not have the current focus. Avoid scrolling, as it is very hard to use. Hide OLE, VBX, and ActiveX objects if you do not want users to see their placeholders. Be sure that widgets have sufficient space to display themselves entirely, as all UI widgets are rendered in their character-mode equivalents. Because users cannot move an LOV with a mouse, use the `set_lov_property` built-in to dynamically position the LOV.
Navigation | Since the user does not have a mouse, users cannot navigate between windows or forms from within the application. Provide buttons or menu options for navigating between forms. Since windows cannot be repositioned with a mouse, ensure that a displayed window does not obscure the context required for that window. When the user is done with a window, disable the window programmatically, or set the window's Remove On Exit property to true.
Layout | There are only 80x24 character cells on the screen. The first line is used for the menu; the last two at the bottom for the console display and the message and status lines. Plan your screens carefully to fully utilize the remaining space. Fonts are monospaced and thus consume much more space on average than proportional fonts. Design your screens so that boilerplate and textual widgets can be rendered with one character per cell.
Coordinate system | Use the Character coordinate system and turn on the grid snap. This will ensure that your objects' sizes are in multiples of the character cell size.
Menus | Menus are displayed on the first line of the screen. Common menu items like Cut, Copy, and Paste not available. Define hot keys for commonly used menu items to reduce cumbersome navigation to the first line of the screen.
Bevels | Not available.
Buttons | Avoid use of button palettes; make all actions available from the menu instead. Because character-mode does not allow the user to retain context when navigating to a button, buttons do not work well in this mode.
Icons | Not available. Make sure that all iconic buttons in the GUI environment are also represented by menu options. Iconic buttons display with just the buttons' labels. Make sure the labels are meaningful and that there is sufficient space to display them.
Color | Precede negative numbers with a minus sign since color is not available. On monochrome displays, colors snap to black or white. Avoid using dark colors for both background and foreground, as both are snapped to black.

## 5.3 Designing Portable Reports

When preparing a report to run on multiple platforms, consider the following:

- Fonts. Not all font types, styles, and sizes are available on all target GUIs. You can handle this in one of two ways:

  - Use a font that you know exists on the target GUI or one that maps well to the default font of the target GUI.

  - Modify the font mapping file, UIFONT.ALI, to ensure that the fonts map correctly. See Section 5.2.1.4.1, "Defining font aliases" for more details on using the UIFONT.ALI file.

  Note: Because screen font and printer font metrics are not always the same, your printed report may not look the same as it did on the screen. In particular, text fields can expand on the printed page, causing adjacent fields to shift and possibly creating new and unpredictable page breaks. To avoid this, use expand-only fields and be sure each field is large enough to accommodate the largest font reasonably possible.

- Colors. If possible, use a color that you know exists on the target GUI; otherwise, use one that maps well to the default color of the target GUI. The following colors are typically available on many platforms: blue, magenta, red, cyan, green, yellow. See Section 5.2.1.3, "Using color" for some recommendations on including color in portable reports.

- DPI. The dots-per-inch (DPI) that your monitor uses may not be the same as the DPI used by the person who runs the report. The DPI only affects how alpha-numeric characters word-wrap on the screen. If you design a report that may be displayed in the Previewer view, try to use the same DPI as the people who will run it.

- Buttons. If you provide buttons in a report, users viewing the report through the Previewer can press the buttons to display a multimedia object (sound, video, image) or to perform an action through PL/SQL code, such as drilling down to another report. See Section 5.2.1.6, "Using buttons" for some guidelines on creating portable buttons. Note that if you run a report containing buttons in character-mode, the buttons are simply ignored; they do not create a placeholder.

### 5.3.1 Designing a report for character-mode environments

Character-mode reports are often needed in environments where users need to send their report output to bulletin boards, spreadsheets, dump files, or to character-only printers. Character-mode output also provides a number of advantages:

- Portability. Because they are strictly ASCII or EBCDIC files, character-mode reports can be printed or exported anywhere.

- Protecting printer investment. Character-mode reports require no special formatting--unlike complicated postscript output--thus protecting your investment in older printers.

- Printer code support. Reports Developer provides support for printer escape codes, which enable users to exploit printer-specific features at runtime, such as special font sizes, highlighting, and more. Refer to the Report Builder online help for information on printer definition files and printer codes.

- Performance. Character-mode reports run much faster than an equivalent bit-mapped report. Bit-mapped reports typically require more formatting time and have larger (Postscript, PCL5) output files.

#### 5.3.1.1 Design considerations

Reports built for bit-mapped environments cannot easily be adapted to character-mode. If you know you will need to run a report in a character-mode environment, it is best to build the report as a character-mode report. However, if you must convert a bit-mapped report to character mode, refer to the Report Builder online help, index entry: ASCII report, creating. You will also find step-by-step instructions there for building a character-mode report.

## 5.4 Designing Portable Displays

If you have standalone graphics--graphics that are not part of a container application such as a form or report--porting is fairly straightforward. Most graphics, however, are embedded within forms and reports, which can introduce problems when moving across platforms. When developing graphics for multiple environments, observe the following guidelines:

- To ensure that text scales uniformly--especially when the graphic is embedded in a form or report--use a scalable truetype font and set the Scalable Fonts flag to true for all text objects except chart labels. The Scalable Fonts flag is not available for text labels in a chart. As soon as a chart is updated, fonts are re-set to their original size. Thus, choose a font and size for chart labels that is legible at the greatest range of chart sizes. A good bet is small, sharp fonts that display well at 8-10 point sizes. Anything larger may cause your chart to become unreadable when embedded in a small chart area of a form or report.

- Timers and drag-and-drop code are supported only in standalone Graphics applications. If you include these functions in a form or report, they are ignored.

- Limit your use of colors to the core 16, which are available in the Designer (upper-left corner of the palette), as well as through their mnemonic names (red, green, blue, yellow, magenta, cyan, black, white, gray, darkgray, darkyellow, darkcyan, darkmagenta, darkblue, darkgreen, and darkred).

- Set colors through the layout editor, rather than through PL/SQL. Colors chosen in the layout editor are automatically adjusted to the nearest available color. Colors set through code can result in an error if the color is not available on your system at the current resolution.

- Isolate platform-dependent code with calls to the application property og_get_ap_platform, and to the built-in subprograms og_append_directory and og_append_file. Refer to the Graphics Builder online help for more information.

| Copyright © 2000 Oracle Corporation. All Rights Reserved. |
|  | Contents | Index