2.4 Layout Objects

The topics in this section build on the basic concepts discussed in Section 1.8, "Layout Objects".

2.4.1 About layout objects

Several important concepts and properties apply to layout objects:

  • the frequency with which you want the object to appear in the report, specified by the Print Object On property

  • how Oracle Reports Builder fetches and formats data for instances of repeating frames, specified by the Column Mode property

  • whether to keep an object and the object to which it is anchored on the same logical page, specified by the Keep With Anchoring Object property

  • whether to try to keep the entire object and its contents on the same logical page, specified by the Page Protect property

  • format triggers, which are PL/SQL functions executed before an object is formatted that can dynamically change the formatting attributes of objects

  • report layout, generated by defaulting applied by Oracle Reports Builder, modified in the Paper Layout view, or created from scratch.

See also

Section 4.5.4, "Creating a default layout for a report"

Section 4.10.2, "Creating a default layout for a section"

Section 2.6.13.2, "About format triggers"

The Properties section of the Oracle Reports online Help

2.4.2 About layout defaulting

When you select one of the default layout styles in the Report Wizard, Oracle Reports Builder creates the necessary layout objects, based upon the report's data model. For example, if you want to build a mailing label report and have defined an appropriate data model, simply choose the mailing label default style. Oracle Reports Builder automatically creates the report's layout objects and displays them in the Layout Model view. You can completely customize any default layout you create. You can cut, copy, paste, move, resize, and edit each layout object that Oracle Reports Builder generates for you.

Layout defaulting is governed by the following rules:

  • All previously-defined layout objects for the report will be overwritten (including format triggers) unless you define the area in which you wish to create the layout as one which does not already contain layout objects.

  • One report can have any number of different formats. For example, you can build a report that has a tabular format on the top of the first page, and a matrix format on the bottom of the same page by creating an additional report layout (see Section 4.5.5, "Creating an additional report layout").

  • Once you have created a report layout, any further changes you make to the data model will not automatically be included in the layout. For example, if you create a query after you have created a report layout and then run your report, the data from the new query will not appear in the report output. To incorporate your changes, you need to either redefault or modify the layout.

Oracle Reports Builder defaults report layout according to the following rules:

  1. Unless otherwise noted, a group with a Print Direction of Across defaults identically to a group with a Print Direction of Down, except that the default format is transposed. To quickly determine the defaulting of an Across group, do the following:

    • Draw the down layout for the group on translucent paper.

    • Turn the page over as if it was a page in a book.

    • Rotate the page counter-clockwise 90 degrees.

  2. In form letter reports, all default fields are hidden, and have a Horizontal Elasticity property setting of Variable and a Vertical Elasticity property setting of Fixed. In all other reports, all default fields have a Horizontal and Vertical Elasticity property setting of Fixed.

    Exception: For tabular, form-like, group left/above, and matrix reports, the default for CHAR (if you reduce the default width) and LONG fields have a Horizontal Elasticity property setting of Fixed and a Vertical Elasticity property setting of Variable. As a result, all of the field's value will be displayed, instead of truncated, by word-wrapping any data to the next lines.

    Caution:

    For form letter and mailing label reports, the default for CHAR (if you reduce the default width) and LONG fields have a Horizontal Elasticity and Vertical Elasticity property setting of Fixed. As a result, the field value will be truncated if the size of the data is greater than the size of the field.

  3. Summaries that are owned by the report, not by a group, are allowed in all report layout styles. They are all formatted in the following way:

    • If the layout style is form-like, form letter, or mailing label, the summary is a report column. A report column is formatted like any other database column for that report style.

    • If the layout style is tabular, group left/above, or matrix, and the column on which the summary performs its function is not selected, the summary is a report column. (It is formatted as stated in the bullet above.) Otherwise, the summary is a report summary. It is formatted left-justified at the end of the report, with the label to the left of the field (if there is room).

  4. If the layout style is tabular, group left/above, or matrix, a summary is defaulted like a database column if the column it summarizes is not selected. Otherwise, a summary is defaulted like summaries (that is, appearing inside the M_groupname_FTR frames).

  5. If the layout style is tabular, group left/above, or matrix, Oracle Reports Builder places one summary type per line, in the following order:

    • SUM

    • AVERAGE

    • MINIMUM

    • MAXIMUM

    • COUNT

    • FIRST

    • LAST

    • % OF TOTAL

    • STANDARD DEVIATION

    • VARIANCE

  6. If the layout style is tabular, group left/above, or matrix, the summary label will appear to the far-left of the group footer frame (M_groupname_FTR). If there is not room for the full label, the label will be truncated.

See also

Section 4.5.4, "Creating a default layout for a report"

Section 4.10.2, "Creating a default layout for a section"

2.4.3 About images

You can add an image to a report by:

The first method (using the Import Image dialog box) provides for including images in the following formats: TIFF, JFIF, BMP, TGA, PCX, PICT, GIF, CALS, RAS, OIF, PCD.

The other two methods (creating a file link object, and selecting a column in the database) provide for including additional formats supported by Oracle Reports, including JPEG (all types, such as Progressive JPEG and Exif JPEG), PNG, BMP, TIFF, GIF, and CGM.

By default, images display in fields so that they appear in the printed report, not only in the Previewer.

Enhanced imaging support is provided by the REPORTS_OUTPUTIMAGEFORMAT environment variable and OUTPUTIMAGEFORMAT command line keyword. The enhancements in imaging support provide the capability to generate complex graphics-intensive reports with high fidelity image output. Additionally on UNIX, the dependency on a windowing system for displaying images is removed; the PostScript printer driver screenprinter.ppd provides surface resolution for images.

You can include an unlimited number of image objects without running out of local disk space by using non-caching references. A non-caching reference causes objects to be read from the database only when needed while a report is processing. You must be connected to an ORACLE V7.1 or later database to use this feature.

If you reference a URL for an image, the image is displayed when you format your report for HTML output. For other output formats, the URL text displays in the Paper Design view; in the output destination (for example, a file or PDF document), nothing is displayed. It is your responsibility to verify that the URL exists; Oracle Reports Builder does not validate the existence of the resource nor the syntax of the protocol. The size of the object that contains the URL defines the size of the image in the HTML output. Any elasticity properties applied to the object are ignored.

Limitations

  • If the input image includes more than 256 colors, and the output image format is set to GIF (with the OUTPUTIMAGEFORMAT command line keyword or the REPORTS_OUTPUTIMAGEFORMAT environment variable), Oracle Reports implements a color reduction to 256 colors to successfully generate the GIF.

  • On UNIX, CGM format is not supported in HTML output. This limitation does not apply on the Windows platform.

2.4.4 About anchors

Anchors fasten an edge of one object to an edge of another object, ensuring that they maintain their relative positions. For example, you can anchor boilerplate text to the edge of a variable-sized repeating frame, guaranteeing the boilerplate's distance and position in relation to the repeating frame, no matter how the frame's size might change.

Anchors determine the vertical and horizontal positioning of a child object relative to its parent. The child object may be either outside of or contained within the parent.

Since the size of some layout objects may change when the report runs (and data is actually fetched), you need anchors to define where you want objects to appear relative to one another. An anchor defines the relative position of an object to the object to which it is anchored. Positioning is based on the size of the objects after the data has been fetched rather than on their size in the editor. It should also be noted that the position of the object in the Paper Layout view affects the final position in the report output. Any physical offset in the layout is incorporated into the percentage position specified in the Anchor properties.

There are two types of anchors:

  • Implicit anchors. At runtime, Oracle Reports Builder generates an implicit anchor for each layout object that does not already have an explicit anchor. It determines for each layout object which objects, if any, can overwrite it, then creates an anchor from the layout object to the closest object that can overwrite it. This prevents the object from being overwritten. The implicit anchor functionality saves you from having to define the positioning of each object. Implicit anchors are not visible in the Paper Layout view. However, you can specify in the Object Navigator Options dialog box that the Object Navigator display anchoring information. By default, objects are anchored to the upper left corner of their enclosing object. If this view of the Object Navigator does not show anchoring information for an object, you can assume that the object is anchored to its enclosing object, which might be the frame or the body.

  • Explicit anchors. You can create an anchor in the Layout editor using the Anchor tool, dragging from one edge of the child to the one of the parent's edges. Any anchor you create for an object will override its implicit anchoring. Explicit anchors are always visible in the Paper Layout view unless you specify otherwise in the Layout Options dialog box.

Relative positioning of anchors

When you anchor a child object to a parent object, the x and y coordinates of the anchor's attachments are important.

If the parent object is located above or below the child object:

  • the vertical distance between the two objects is fixed. For example, in the figure below, the vertical spacing between the parent and Object 1 is fixed.

  • the horizontal positioning of the anchor's x-coordinate on the child object is relative to the anchor's x-coordinate on the parent object. For example, in the figure below, the anchor is 50% from the edge of the parent and 75% from the left edge of Object 1. Therefore, when this report is run, Oracle Reports Builder will shift Object 1 25% to the left of the center of the parent.

Figure 2-5 Parent object above child object

figure illustrating parent above child
Description of "Figure 2-5 Parent object above child object"

If the parent object is located to the right or left of the child object:

  • the vertical positioning of the two objects is relative. For example, in the figure below, both ends of the anchor are about 80% down from the top edges of the objects. Therefore, when the report is run, Oracle Reports Builder will calculate the length of the two objects (as they may expand), calculate the y coordinate that is 80% down for both objects, and position the two objects so that those two points are separated by the amount of space separating them in the Paper Layout view.

  • the horizontal positioning between the two objects is fixed. For example, in the figure below, the horizontal spacing between the parent and Object 1 is fixed.

Figure 2-6 Parent object to the right of child object

figure illustrating parent to right of child
Description of "Figure 2-6 Parent object to the right of child object"

If you need to position an object outside a repeating frame or frame, but you want the object to be "owned" by the repeating frame or frame (that is, to be formatted when its "owner" is formatted), create an anchor that is attached to an object inside the frame or repeating frame.

Collapsing Anchors

You can create anchors to be "collapsible." Collapsing anchors help avoid unnecessary empty space in your report. Such empty space can occur when the parent object does not print on the same page as the child object, either because the parent and child cannot fit on the same page or because of an assigned Print Condition. A collapsing anchor allows the child object to move into the position that would have been taken by the parent had it printed. The child object will also maintain its relative position as defined by the anchor.

2.4.4.1 Implicit anchoring algorithm

Oracle Reports Builder creates implicit anchors at runtime in the body region. The margin algorithm differs slightly.

Body algorithm

  1. Determine which objects are not entirely enclosed by a repeating frame of frame (directly or indirectly), or explicitly anchored to an object that is enclosed by a frame or repeating frame (directly or indirectly). We'll call these objects Type A objects. (Type A objects are typically group frames, repeating frames, other objects you create that are not owned by a frame or repeating frame, and so on). An object is considered to be enclosed by another object only if all of the following are true:

    • Both objects belong to the same region (Body or Margin).

    • The outermost of the two objects is a frame or repeating frame.

    • The outermost of the two objects is behind the other object.

    • The innermost of the two objects lies entirely within the borders of the other object.

  2. Determine all children objects of a frame or repeating frame (these are the non-Type A objects). We'll call these objects Type B objects.

  3. Follow this procedure for Type A and Type B objects independently:

    • Find all objects that are of the same type (for example, Type A), and are on the same layer.

    • Determine which of those objects have potential to "push" other objects of that type. An object has potential to "push" object of that type if it has a Horizontal or Vertical Elasticity setting of Variable or Expand, and a second object is located in its "push path" (that is, in the area in which it can possibly grow). Also, a repeating frame with a Horizontal or Vertical Elasticity setting of Fixed or Contract has a "push path": its Print Direction.

    • Create pairs of objects. Each pair must contain a pusher (that is, the object that will grow) and a pushee (that is, the object that will be pushed). When creating these pairs, a pushee object cannot be a child of an explicit anchor--those objects are ignored.

    • Go through this loop. For each pair, determine the distance in the "push path" between the pusher and pushee. Next, find the pair with the shortest distance. Finally, create an implicit anchor between those two objects using this algorithm:

      If the "push path" direction is Down, anchor the pushee object's top 0% to the pusher object's bottom 0%.

      If the "push path" direction is Across, anchor the pushee object's left 0% to the pushed object's right 0%.

    • That pair is now treated like one object, and the loop continues until either all objects have one anchor, or nothing will push the remaining, unanchored objects.

    • For each remaining, unanchored object, create an implicit anchor from the top-left corner of the object to the top-left corner of the body region.

    • Move to the next layer, and follow the procedure starting at step 1.

Rules:

  • If an object is in the "push path" of two other objects and it is equidistant from the other two objects, the implicit anchoring of the object may vary between executions of the report. For example, the drawing that follows shows two cases where this could occur:

Figure 2-7 Object in push path of two other objects

graphic depicting situation described above
Description of "Figure 2-7 Object in push path of two other objects"

In the first case, M_Sums is in the "push path" of both B_Text1 and R_Ename. Because M_Sums is equidistant from B_Text1 and R_Ename, though, the normal criteria (shortest distance) for determining implicit anchors does not work in this case. Consequently, the formatting algorithm will randomly create an implicit anchor between M_Sums and either B_Text1 or R_Ename at runtime. To avoid this behavior, you could create an explicit anchor between M_Sums and B_Text1 or R_Ename.

In the second case, B_Text3 is in the "push path" of M_Emp. Since the bottom edges of M_Emp and R_Mgr are virtually in the same position, though, B_Text3 could be implicitly anchored to either M_Emp or R_Mgr. Consequently, the formatting algorithm will randomly create an implicit anchor between B_Text3 and either M_Emp or R_Mgr at runtime. To avoid this behavior, you could create an explicit anchor from B_Text3 to one of the objects or remove the explicit anchor between R_Ename and B_Text2. Removing the explicit anchor would cause R_Mgr to be treated as a descendant of M_Emp and, therefore, the implicit anchor would always be created between B_Text3 and M_Emp.

(Note that Case 2 is most likely to occur in character mode, where it is common to have the edges of objects overlap in the Paper Layout view.)

Margin algorithm

Oracle Reports Builder creates implicit anchors for all Type B objects in the margin region using the Body algorithm. For each Type A object, however, Oracle Reports Builder creates an implicit anchor from the top-left corner of the object to the top-left corner of the margin. No Type A object will be implicitly anchored to another Type A object. (This ensures that Type A objects will not be pushed off the page. However, they may be overwritten by another Type A object, if they are found on the same layer.)

See also

Section 4.9.5.1, "Anchoring objects together"

Section 4.9.5.2, "Viewing implicit anchors"

Section 4.9.5.3, "Moving an anchor"

2.4.5 About changing colors and patterns

Color and pattern selections are applied to an entire object (for example, you can apply a color to all the text in the object but not to a segment of the text).

You can change colors and patterns in your report in the following ways:

  • In the Oracle Reports Builder user interface, use the following tools in the Paper Layout view's tool palette:

    • The Line Color tool is used to customize the color of borders around layout objects.

      Note:

      The Windows platform does not support a border pattern (that is, patterns for the Line Color tool).

    • The Fill Color tool is used to fill layout objects with colors and patterns.

    • The Text Color tool is used to change the default text color.

    • The Fill/Line/Text Display, the box directly above the three Color tools, shows the currently selected fill, border, and text. The default fill and border for objects created by Oracle Reports Builder is transparent, while the default for objects you create is a black, one point line around a white fill.

  • In PL/SQL, use the following SRW packaged procedures:

    • SRW.SET_BACKGROUND_BORDER_COLOR

    • SRW.SET_BACKGROUND_FILL_COLOR

    • SRW.SET_FOREGROUND_BORDER_COLOR

    • SRW.SET_FOREGROUND_FILL_COLOR

    • SRW.SET_TEXT_COLOR

    • SRW.SET_FILL_PATTERN

    • SRW.SET_BORDER_PATTERN

  • For templates, set the following properties in the template Property Inspector:

    • The Fill Pattern property defines the pattern to use for the space enclosed by the objects. You can define the background and foreground colors of the fill pattern using the Foreground Color and Background Color properties.

    • The Edge Pattern property defines the pattern to use for the borders of the objects. You can define the background and foreground colors of the edge pattern using the Edge Foreground Color and Edge Background Color properties.

      Note:

      The Windows platform does not support a border pattern.

    • The Text Color property specifies the text color to use for the object(s).

Additionally, you can set color palette preferences to specify how it is used by a report (see Section 4.2.6, "Setting color palette preferences") and modify the color palette to change the definition of individual colors (see Section 4.9.6.5, "Modifying the color palette").

To change the color palette being used by the current report, you can import a new color palette. You can also export the current color palette for use by other reports. (See Section 4.9.6.6, "Importing or exporting a color palette".)

See also

Section 4.9.6.2, "Changing colors"

Section 4.9.6.3, "Changing patterns"

Section 4.9.6.4, "Changing colors and patterns using PL/SQL"

Section 4.9.4.2, "Changing object border attributes"

Topics "Oracle CDE1 color palette", "Default color palette", "Grayscale color palette", and "Pattern color palette" in the Reference > Color and Pattern Palettes section of the Oracle Reports online Help

Topic "SRW built-in package" in the Reference > PL/SQL Reference > Built-in Packages section of the Oracle Reports online Help

Topic "Template properties" in the Properties section of the Oracle Reports online Help

2.4.6 About resizing objects

You can resize queries, groups, frames, repeating frames, fields, matrix objects, and boilerplate objects. You cannot resize anchors. However, an anchor is automatically resized if you move one of the objects it anchors.

Caution:

When you resize boilerplate text, be very careful that all of the text fits within the object. If font descends (the space left for the lower parts of letters like g and q) do not fit, the line of text will appear in the Report Editor view, but, when the report is run, the line will not appear in the output. When you click a handle and drag it, the two edges that join at the corner will be resized; that is, the object will grow or reduce in both the x and y directions.

See also

Section 4.9.12.1, "Resizing objects"

Section 4.9.12.2, "Making multiple objects the same size"

Section 4.9.11.3, "Adjusting parent borders automatically"

2.4.7 About moving and layering objects in the Paper Layout view

In the Paper Layout view, objects must be on a layer above the objects that enclose them. For example, the fields that belong to a repeating frame must be at least one layer above the repeating frame in the Paper Layout view. If not, then they are not considered to be enclosed by the repeating frame any longer and will cause a frequency error at runtime. When you move or group objects in the Paper Layout view, it is possible to change the layering such that you will get frequency errors when you run the report. To avoid this problem, you should take advantage of Confine or Flex mode when moving objects in the Paper Layout view.

See also

Section 4.9.4.3, "Changing the current mode (Confine or Flex)"

Section 4.9.11.7, "Changing object layering"

Section 4.9.11.2, "Moving an object outside its parent"

Section 4.9.11.1, "Moving multiple objects"

Section 4.9.11.6, "Aligning objects"