• 40
• Objects Within Oracle Power Objects
• Overview of Objects
• Events, Methods, and Properties
• Common Properties
• Common Methods
• Application-Level Objects
• Form Objects
• Report Objects
• Class Objects
• Bitmap Resource Objects
• OLE Objects
• Objects for Building Applications
• Chart Object
• Checkbox Object
• Combo Box Object
• Current Row Pointer Object
• DBRecordset Object
• Embedded Form Object
• Field Object
• Horizontal and Vertical Scrollbar Objects
• Line Object
• List Box Object
• Menu Bar, Menu, and Menu Item Objects
• OCX Object
• Oval Object
• Picture Object
• Pop-up Object
• Radio Button and Radio Button Frame Objects
• Rectangle Object
• Repeater and Repeat Panel Objects
• Static Text Object
• Status Line Object
• Toolbar Object
• Summary

40

Objects Within Oracle Power Objects

This chapter provides detailed information on each of the object types within Oracle Power Objects (OPO). Many of these objects are visible during design time; some are visible only during run time. Some objects are non-visual. This chapter defines the methods and properties associated with each object and documents which methods and properties OPO version 1.0 does not use.

Overview of Objects

The Oracle Power Objects product is completely structured around the concept of objects. The highest level of object classification consists of applications, libraries, and database sessions. Figure 40.1 illustrates the icons for these objects.

Figure 40.1. OPO objects.

The application object is what the developer uses to interface between the user, the database, and any other peripheral devices. The application object contains the objects required to implement the level of interaction necessary for the given set of related tasks comprising the application. Library objects consist of bitmap resource objects and class objects. Each of these object types is covered in detail in the following application-level objects sections. The only difference between the objects found in a library those found in an application is that the library objects can be shared from a library and cannot be shared from an application. For more information on database session objects, refer to Chapter 37, "Connecting to Database Sources Through Sessions."

Events, Methods, and Properties

Objects within the OPO framework have predefined behaviors and characteristics. Behaviors represent the mapping of system- and user-generated events into methods. These methods also represent behaviors that respond to programmatic references to themselves and that respond to previously referenced methods (a chain of sequential events). Objects within Power Objects also have characteristics that are represented by the concept of properties. Examples of properties are FontName, SizeX, SizeY, PositionX, PositionY, and so on. All of the properties and methods for an application are listed in alphabetical order on its property sheet. Figure 40.2 shows an open property sheet for the Finance sample application from OPO. A diamond object in the leftmost column denotes properties. A pointer object in the leftmost column denotes methods.

Figure 40.2. A example of a property sheet.

Although this chapter does not cover of all of the various properties and methods for each object in OPO, it does present a summary of the most frequently used properties and methods. If you need more detailed information, refer to OPO online documentation.

Common Properties

Many objects in OPO have the same properties. For example, a button object and a field object each have a FontName property. Although OPO has a predefined default FontName value for each of these objects, often a developer wants to change the predefined value to a new value. If you select both the field object and the button object, the property sheet is labeled Multiple Selection Properties and only displays those properties and methods that all the selected objects have in common. In Figure 40.3, button1 and field1 are selected and the FontName property has been expanded. Notice that <multiple> is the current value of the FontName property. The developer can select a name from the list, such as Arial, to change the FontName value to that name.

Figure 40.3. A Multiple Selection Properties property sheet.

The following paragraphs highlight and discuss those properties that are common to most of the objects within Power Objects. Not all objects have these properties, but many objects do. These properties are those that are most likely to be changed by a developer.

The Bitmap property specifies the name of a bitmap resource object that should be displayed on the specified control. Although the online OPO help says this property has a string data type and is readable and writeable at run time, these statements are not entirely true. For example, reading the value of the Bitmap property should work with the following Basic statement:

msgbox form1.Bitmap

This statement works if the value is NULL, but it yields the following Basic error if the Bitmap value is specified:

BAS-01023: Invalid type for built-in function

The data type for Bitmap is string, supposedly. The following statement works:

form1.Bitmap = Flowers

Flowers is the name of a bitmap resource object within the active application. Notice that the word Flowers is not surrounded by quotation marks. Quotation marks imply a string. Although the Bitmap property may be of a string data type, setting its value programmatically requires a reference to an existing bitmap resource object, not a string reference.

The BitmapTiled property specifies whether the bitmap should be tiled across the control. The data type is boolean. This property is readable and writeable at run time. If the value is False, the bitmap is centered across either the width and/or height of the control provided that either of these control dimensions is as large or larger than the corresponding bitmap dimensions; otherwise, it is top-left justified in the control. If the value is True, the bitmap is tiled across the control with clipping applied to the right and bottom limits of the control.

The DataSize property is the number of bytes set aside for a bound control. The data type is integer. This property is readable at run time. The displayed default value is zero. This value is not the actual default value, however. The long integer, double, and date data types ignore the DataSize setting. The DataSize for string data types represents the exact number of bytes or characters that the control can contain. The default value for the string data type is 41. If the developer drags either one or more columns or the entire table onto a container, the DataSize for the string data type is set to the actual number of characters specified in the database table, and the DataSize for the date data type is set to 11.

Suppose that a column from a table in the database has a VarChar2 type and a size of 50. If the developer has a control bound to that column and sets the DataSize to 0, the following problem could occur. The end user of the application can enter up to 41 characters in the control. Entering more than 41 characters but less than 51 characters is valid from the perspective of the database, but is not acceptable for the OPO application. The opposite is also true. Suppose that a column from a table in the database is of the type VarChar2 and has a size of 10, and the developer binds a control to the column and sets the DataSize to 0. The user can enter more than 10 and less than 42 characters into the field, and the OPO application will accept the entry. The database will not accept the entry, however, and an error will be generated for the end user. The developer should take care to avoid both of these problems and specify the actual DataSize for the bound control that is specified in the database.

The DataSource property determines whether the control is bound to a database table column or to a derived value. The data type is string. This property is readable at run time. If the control is bound to a database table column, the value is the name of the column. If the database table column is using case-sensitive names, surround the DataSource value with double quotation marks. If the control is bound to a derived value, the first character of the DataSource value is an equal sign. The remainder of the value must evaluate to a valid OPO equation or literal. Finally, an empty DataSource property implies that the control is not bound to data. The user can enter data into an unbound control, the record manager can manage the data, and validation methods can be applied to the value, but the data is not stored in the database. Derived values are similar to these unbound data controls. The data specified by a derived control cannot be directly stored in the database.

The DataType property indicates the type of data that the control contains from the perspective of the application. These DataType values are independent of the database back end. The data type is long integer. This property is readable at run time. Values are as follows:

3 = Long Integer

5 = Double

8 = String

7 = Date

The DrawStyle property determines whether the control uses the 3-D sculpted look and feel. The data type is long integer. This property is not readable nor writeable at run time. The default DrawStyle for all controls in OPO is Standard Control (a 2-D display modality). In OPO version 1.0, the alternative DrawStyle setting is 3D Control. The following controls respect the DrawStyle setting: field, rectangle, frame, and button. Although many of the OPO controls respect the 3D Control DrawStyle, the following controls do not actually display in a 3-D mode: line, oval, pop-up, combo box, and list box. The following controls do not have a DrawStyle property: chart, horizontal and vertical scrollbars, embedded form, repeater, bitmap, OLE, report group, current row pointer, and static text. Scroll bars and buttons do not display in a 2-D mode.

The data type for the Enabled property is string. This property is readable and writeable at run time.

Text for the control is displayed using the font indicated in the FontName property. The data type for this property is string. This property is readable and writeable at run time. If a font specified for FontName in the OPO design environment is not available on the target client environment, OPO uses the closest matching available font based on font name and font characteristics. If no matching font is found, the default font is used. System Font is the default font for button, chart, static field, checkbox, list box, and pop-up controls. Application Font is the default font for field, combo, and frame controls.

---

You can set the FontName property during run time as follows:

button1.FontName = "Times New Roman"

OPO intelligently maps the supplied name against the list of available font names and picks the closest matching name. In a Microsoft Windows environment, for example, Times New Roman, Times Roman, Times, and Roman all yield the same font, Times New Roman. Remember that this FontName change is only valid during the active run-time mode for the affected objects. When the developer returns to the design-time environment, the change is lost and the FontName property is returned to its original design-time value.

---

The HelpText property sets the text that is displayed in the active status line object when the cursor is moved over the object. The data type for this property is string. This property is readable and writeable at run time.

---

OPO version 1.0 does not display the HelpText property during run time.

---

The ReadOnly property determines whether the user can enter/edit the value of data in a control. The data type is long integer. This property is readable and writeable at run time. If the value of ReadOnly is True, the user cannot tab to the control or set the focus to the control.

The ScrollWithRow property determines whether a value specified for an unbound data control should scroll with each record in the active record manager. The data type is long integer. This property is readable at runtime. By default, ScrollWithRow is True, which implies that the record manager has a value for the unbound data control for each record in the table. If ScrollWithRow is False, the unbound data control is acting independently of the record manager and has only one value. This property is extremely valuable for controls that are used to limit the display of data within other record manager sets. For example, a pop-up could list all of the available departments in a company. Choosing a department from the pop-up could limit the list of employees displayed in a repeater to only those employees working in that department.

The TabEnabled property determines whether the user can set the focus to the specified control using the Tab key. The data type is long integer. This property is readable and writeable at run time. The default value is True. If TabEnabled is True, pressing the Tab key navigates to this control in the order specified by the TabOrder property. Pushbuttons, radio buttons, and checkbox buttons are not tab-enabled on the Macintosh, although they are in the Microsoft Windows environment. If TabEnabled is False, the user cannot use the Tab key to navigate to the control. A False value for the TabEnabled property does not affect other methods or properties of the specified control.

The TabOrder property specifies the order in which controls will be navigated to when the user uses the Tab key. The data type is long integer. This property is readable and writeable at run time.

The Value property specifies the data stored in a control. The data type is specified by the control. This property is readable and writeable at run time. This property does not show up on the property sheet.

The Visible property specifies whether the user can view the control. The data type for this property is long integer. This property is readable and writeable at run time. If the Visible property's value is False, the user cannot tab to the control or edit data in the control with the keyboard. Setting the Visible property of a container control also affects the visibility of the contained controls. Setting the Visible property of an embedded form, for example, hides the embedded form and all of the controls contained within the embedded form.

---

The ZOrder property is not one of the properties for OPO controls that is displayed in the property sheet. The ZOrder represents the graphical redraw order when OPO redraws the screen. Objects are drawn starting with the lowest Zorder up through the highest ZOrder. The developer can manipulate the ZOrder property from the design environment through the Design menu, however. Under the Object menu item you will find the Further front, Bring to front, Further back, and Send to back options. These menu options, as well as the Bring to front and Send to Back toolbar icons, provide the developer with the ability to control the ZOrder of the currently selected controls. This property is not readable or writeable during run time.

---

Common Methods

Not only do many of the OPO objects have properties in common, they also have several common methods. For example, a button and a field object each have a Click() method. The default action associated with the Click() method varies according to the type of object, but generally the object receives a mouse down event followed by a mouse up event, and then receives the focus. Often a developer will want to perform special actions associated with the Click() method. A simple example would be to have the object issue a Beep command. If you select the field object and the button object on a form, the property sheet is titled Multiple Selection Properties and only displays the properties and methods that all the selected objects have in common. In Figure 40.3, button1 and field1 are selected and the Click() method is visible. If the developer opens the Click() method script window and enters the Beep command, clicking in the field or on the button causes a beep to be heard when the form is run.

The following paragraphs highlight and discuss those methods that are common to most of the objects within Power Objects. Not all objects have these methods, but many objects do. These methods are those that are most likely to be changed by a developer.

The Click() method responds to programmatic references and a specific series of user-generated events, mouse down followed by mouse up. This method returns no data. If the developer doesn't override the Click() method, the click event propagates up the hierarchical containment to the object's container's ChildClick() method.

The DoubleClick() method responds to programmatic references and a specific series of user-generated events: mouse down, mouse up, click, mouse down, and mouse up. The data type is long integer. If the developer specifies a non-zero return value, the Click() method is triggered after the DoubleClick() method is processed. Normally, the Click() method is not processed after the DoubleClick() method.

The MouseDown() method responds to the user-generated event of mouse down and to programmatic references. This method returns no data.

The MouseMove() method responds to user-generated events focused around changing the position of the mouse following a mouse down event. This method returns no data. The MouseMove() method fires for every position update inside and outside of the original object dimensions until the user releases the mouse, which forces a mouse up event. Visual effects are possible from within the MouseMove() method due to the inherent screen refresh after each pass through of the method code.

The MouseUp() method responds to the user-generated event of mouse up and to programmatic references. This method returns no data.

The OnLoad() method responds to an application-generated event. The event is the action of the OPO environment loading an object into active memory in order to process it or other related objects. This method returns no data. The OnLoad() method is a good place to put initialize code specific to an object. Exceptions to this rule include objects that have Initialize() or InitializeWindow() methods.

The PostChange() method responds to the event of data being changed in a control through editing and scrolling of the record manager. Programmatic changing of data in a control does not fire the PostChange() method. This method returns no data. The PostChange() method is triggered after the Validate() method returns True.

The RevertValue() method responds to the Esc key or to a programmatic reference. This method returns no data. The purpose of this method is to return the value of a control to its value prior to any editing.

The Validate() method responds to the user editing the data in a control and attempting to force the data to update. The data type is long integer. If the Validate() method returns False, the focus remains in the control until a True result is returned for the Validate() method. The developer should take care to ensure that a True value can be returned; otherwise, an infinite loop will exist once the user edits the related control.

Application-Level Objects

The objects found within the application level form the basis for all interactions between the user, the database, and any other peripherals. These objects and their methods and properties are combined to build a series of screens and reports that approximate the set of related tasks that form the application. A form object is a screen or window. A report object can provide both a visual report and a printed report. Other application-level objects include bitmap resource objects, class objects, and OLE objects. Figure 40.4 displays the icons for each of these application-level objects.

Figure 40.4. Application-level objects.

Form Objects

The form object is the object that an OPO developer uses most often. The form is the window or screen that the developer designs to interact with the user. The form is also the primary object for interfacing to the database. The form can contain other objects, except for other forms, reports, and report groups. The form is useful for displaying data, manipulating data, navigating to other forms, and linking to other applications through embedded OLE objects and OCX objects. Figure 40.5 displays a blank form with its accompanying property sheet. The remaining paragraphs within this section discuss the various properties and methods that are relevant to a form object.

Figure 40.5. A form object.

The CloseWindow() method responds to the action of closing a window both programmatically and through user events such as the System Menu Close menu item. This method returns no data. This method must be inherited in order for the window to close. For example if the developer places code in the CloseWindow() method, the code must also include inherited.CloseWindow().

The CommitForm() method responds to the Commit toolbar icon and to programmatic references. This method returns no data. The purpose of this method is to commit or save all outstanding changes associated with the Database Session associated with the form's RecordSource. If the developer places code in this method, then inherited.CommitForm() must be included or the commit action will never successfully complete for the specified form.

The DefaultButton method specifies the button that should accept the default behavior for a pressed Enter or Return key when the active focus is not in a field control. The data type is string. This method is not readable or writeable at run time.

The DefaultCondition method specifies the limiting condition to apply to the record manager for the specified form. The data type is string. This method is readable and writeable at run time. The DefaultCondition is synonymous to the where condition in a SQL statement.

The DefaultMenuBar() method initializes a menu bar with the system default menus and application default menus appropriate to the form or report. This method deletes any existing menus before initializing the menu bar.

The DefaultToolbar() method initializes the toolbar with the application default buttons appropriate to the form or report. This method deletes any existing buttons before initializing the toolbar.

The DoCommand() method responds to programmatic references and user-generated events of menu and toolbar selections. The data type is long integer. DoCommand() passes the cmdCode up to the application level from the form or report level if the form or report does not process the cmdCode. The proper method for ensuring that the form- and report-level processing is completed prior to escalating to application-level processing is to assign the return value of True for the cmdCode.

The GetMenuBar() method returns a reference to the menu bar associated with the form or report. The data type is object.

The GetRecordset() method returns a handle or pointer to the record manager of the specified control. The data type is object. This method is readable at run time. This method is required for processing the data within a record manager programmatically and for DBRecordsets that have no controls associated with them for point-and-click interfacing.

The GetStatusLine() method returns a handle to the status line object associated with the form. The data type is object.

The GetToolbar() method returns a reference to the toolbar associated with the form. The data type is object.

The InitializeWindow() method is used primarily for the creation of menus, toolbars, and status lines relevant to the active form. This method returns no data. The developer should create custom menus, toolbars, and status lines in this method.

The Label property specifies the title to display in the window frame title bar, if the WindowStyle option has a title bar. The data type is string. This method is readable and writeable at run time.

The LinkDetailColumn property specifies the name of the column from the detail table to use when performing master-detail linking relationships. The data type is string. This method is readable at run time.

The LinkMasterColumn property specifies the name of the column from the master table to use when performing master-detail linking relationships. The data type is string. The method is readable at run time.

The LinkMasterDel property specifies what the default action will be with respect to detail (foreign key) records when the master (primary key) records are deleted. The data type is long integer. This method is readable and writeable at run time. This property helps to ensure and enforce the application's referential integrity. The values range from Refuse if children present, to Delete cascade, to Orphan details.

The LinkMasterForm property specifies the name of the object that has the record manager for the master in the master-detail relationship. The data type is string. This method is readable at run time.

The LinkMasterUpd property specifies what the default action will be with respect to detail (foreign key) records when the master (primary key) records are updated. The data type is long integer. This method is readable and writeable at run time. This property helps to ensure and enforce an application's referential integrity. The values range from Refuse if children present, to Update cascade, to Orphan details.

The OpenWindow() method responds to programmatic references. This method returns no data. This method is responsible for displaying the form and its contained controls on-screen. If the developer places code in this method, the developer also needs to place inherited.OpenWindow() in the code so that the form draws on-screen.

The Query() method responds to programmatic references and to the default menu and toolbar query commands. This method returns no data. The Query() method is responsible for updating the set of records being managed by the record manager that the Query() method is attached to. Query() also propagates to the session associated with the record manager. If the developer places code in this method, the record manager is not updated unless inherited.Query() is also placed in the code. This method respects the settings specified by the DefaultCondition for limiting the records that are brought into the record manager.

The QueryWhere() method responds to programmatic references only. This method returns no data. QueryWhere() is very similar to the Query() method with the following exception. QueryWhere() includes the condition that is to be applied to the affected record manager in place of the DefaultCondition. As with many critical methods, if the developer overrides the processing of the QueryWhere() method by placing code in the method, the method does not execute unless inherited.QueryWhere( condition ) is also in the method code.

The RecordSource property specifies the name of the database object, table, view, synonym, and so on that is being controlled by the record manager associated with the control. The data type is string. This method is readable at run time.

The RecSrcSession property specifies the name of the database session object that links to the database objects used by the container. The data type is string. This method is not readable or writeable at run time. If the RecSrcSession is empty, the application's DefaultSession is used.

The RollbackForm() method responds to the Rollback toolbar icon and to programmatic references. This method returns no data. The purpose of this method is to discard all outstanding changes associated with the database session associated with the form's RecordSource. If the developer places code in this method, inherited.RollbackForm() must also be included; otherwise, the rollback action will never successfully complete for the specified form.

The RowFetchMode property specifies how the record manager retrieves records from the database. The data type is long integer. This method is readable and writeable at run time. The three possible values are Fetch As Needed, Fetch Count First, and Fetch All Immediately. This property exists to permit the developer to fine tune the performance of the application with respect to fetching records from the database.

---

RowFetchMode defaults to Fetch As Needed. This mode is the preferred fetch mode for client/server database applications. Typically, OPO fetches the same number of records from the database as are visible at one time. For example, it fetches one record for a form or embedded form and fetches multiple records for repeaters. Disk caching is minimized and performance (responsiveness) is maximized. Fetch All Immediately causes all records from the database to be fetched prior to returning control to the user. Disk caching is maximized and performance is minimized whenever the database size grows to be large. However, performance can be improved significantly if the database size is relatively small. A common pitfall for developers who rapidly prototype applications against a small, sample database is to set RowFetchMode to Fetch All Immediately to improve performance of the prototype, and then deploy the prototype as the production application without converting the RowFetchMode to Fetch As Needed.

---

The SetMenuBar() method associates a menu bar with a form or report.

The SetStatusLine() method sets the default status line object associated with the form through the status_line parameter. This method returns no data. If this method is not called, the form will not have a status line.

The SetToolbar() method associates the specified toolbar with the form.

The TestCommand() method polls to determine whether the user has interacted with the menu or toolbar. The data type is long integer. If TestCommand() does not return a value, OPO processes the cmdCode internally as appropriate. If TestCommand_Enabled is returned, TestCommand() calls DoCommand() with the cmdCode.

The ValidateRow() method responds to the user actions that force a flushing of the record to the record manager or database. These actions include inserting a new record, committing changes to the database, and moving to another record manager. The data type is long integer. If the ValidateRow() method returns False, the focus will remain in the current control until a ValidateRow() True result is returned. The developer should take care to ensure that a True value can be returned; otherwise, an infinite loop will exist once the user edits the related control.

The WindowStyle property specifies the style of framing placed around a form. The data type is long integer. This method is readable at run time. Nine styles are available. The default WindowStyle is Standard Document. The developer should take care to use the appropriate style based on the intended use of the form. For example, if the developer is going to use the form in a modal dialog functionality, the developer should use a dialog-based style. Although this recommendation is not enforced, the end user will be considerably confused to see a Standard Document window style on a modal dialog window.

Report Objects

The report object provides a mechanism for displaying data in a WYSIWYG preview mode and printing a hard copy image. The report cannot be linked in relationships to forms or any other objects that have record managers. A report is essentially a standalone unit connecting to the database independently of the other parts of the application. A report can use any object from the tool palette. Note that the repeater control will only be able to display records up to the number of visible panels in the repeater. Also, buttons and all other objects on the report are in a view-only mode when you preview the report; they do not respond to user-generated events, including mouse-related events. Figure 40.6 displays a blank report with its accompanying property sheet. The remaining paragraphs within this section discuss the various properties and methods that are relevant to a report object.

Figure 40.6. A report object.

The OpenPreview() method must be called programmatically. This method returns no data. This method opens the form or report in a WYSIWYG preview mode. Normally a user is only allowed to open reports. The primary reason for opening a form is for documentation.

The OpenPrint() method must be called programmatically. This method returns no data. The printer redirection dialog box open for the user to selection among printer options. OK causes a dialog box to appear that indicates that the report or form is printing.

There are seven kinds of report objects:

• The ReportHeader Band object displays data at the top of the report that is considered global to the overall report.
  
  
• The PageHeader Band object displays data at the top of each printed page of a report. The FirstPgHdr property specifies whether the PageHeader band will be printed on the first page. The data type is long integer. This property is not readable nor writeable at run time.
  
  
• The developer creates the GroupHeader Band object by dropping the Report Group control onto a report. This band is used to display data at the top of each grouped area. The GroupCol property specifies the database column that the report uses for grouping. The data type is string. This property is not readable nor writeable at run time. The PageOnBreak property specifies whether the report should begin a new page with every new group. The data type is long integer. This property is neither readable nor writeable at run time.
  
  
• The Detail Band object displays the bulk of data related to the report. The detail band is effectively like the repeat_panel of the repeater object in that it repeats once for each record in the database object being reported on. The OrderBy property specifies the column or columns that the report should use to order the data. The data type is string. This property is not readable nor writeable at run time.
  
  
• The developer creates the GroupFooter Band object by dropping the Report Group control onto a report. This band is used to display data at the bottom of each grouped area.
  
  
• The PageFooter Band object displays data at the bottom of each printed page of a report. The FirstPgFtr property specifies whether a page footer should be displayed on the first page of the report. The data type is long integer. This property is not readable nor writeable at run time. The LastPgFtr property specifies whether a page footer should be displayed on the last page of the report. The data type is long integer. This property is not readable nor writeable at run time.
  
  
• The ReportFooter Band object displays data at the bottom of the report that is considered global to the overall report.
  
  

Class Objects

The class object provides a mechanism for creating reusable objects. Class objects can be as simple as an OK button or as complex as the calendar class that ships with the OPO Sample Applications. Class objects are instanced into an application by dragging them from the application or library window onto the form or report. These instances are linked to the parent at the property and method level. This implies that code written for a parent method will not be shown in the instance but will be executed unless overridden. Figure 40.7 illustrates four classes that are provided with the OPO Sample Applications: the form control, the record control, the meter control, and the calendar class.

Figure 40.7. Class objects.

Each of the OPO Sample Application classes illustrated in Figure 40.7 is well documented in the OPO Sample Application online help. If the developer uses the class model illustrated in the OPO Sample help, the developed classes are more usable and maintainable. Class objects represent the real reusable power behind OPO. Class objects support the concepts of encapsulation, inheritance, nested instancing, and polymorphism. You can embed custom business logic and rules within class objects and then standardize them through libraries for use in corporate-wide application development and deployment. A mechanism for embedding custom logic is provided through the capability to create user-defined properties and methods. All the sample class objects provided with the OPO Sample Applications use user-defined properties and methods at various levels.

Bitmap Resource Objects

The bitmap resource object provides a mechanism for displaying graphic images on buttons, forms, embedded forms, and user-defined classes. There are no properties that can be changed or methods that execute with respect to bitmap resource objects. These objects are not editable or scaleable. Perhaps the best use of bitmap resource objects is for standardization of backgrounds and button icons in corporate-wide applications. Bitmap resource objects stored in an OPO library perform just this function. The OPO Sample Applications provide two libraries dedicated to bitmap resource objects. The Bitmaps library contains 68 bitmaps and the OPOICONS library contains 96 bitmaps. Figure 40.8 illustrates a few of the bitmap resources available from the Bitmaps library.

Figure 40.8. Bitmap resource objects.

OLE Objects

OLE objects provide a mechanism for using the Object Linking and Embedding (OLE) technology developed by Microsoft. You can only use these objects in the Microsoft Windows version of OPO. You can insert the OLE object from the design time menu or instance it from an application or a library. Figure 40.9 displays two OLE objects in the untitled OPO application and instanced onto a form. OLE5 is a PC Paintbrush object. OLE11 is a Microsoft Word 6.0 object with an embedded picture object. OLE objects permit other applications to be embedded within OPO. OPO version 1.0 doesn't have a mechanism for tying the functionality of the OLE object to the database or even to a programmatic reference from within OPO. Due to this interaction limitation, OLE objects in OPO are of minimal value.

Figure 40.9. OLE objects.

Objects for Building Applications

Objects for building applications include data-bound and graphical objects. These building blocks or objects used in conjunction with the application-level objects enable the developer to build custom database applications. Each of these objects is described in the remainder of this section. Each description lists the object's most common uses, its significant properties and methods, and any areas of concern that a developer should be aware of with respect to using the object.

Chart Object

The chart object is a bindable control for displaying data as a vertical bar, horizontal bar, line graph, or pie graph. The developer cannot drag-and-drop columns from a table onto the chart object because the object would not know whether these columns were x- or y-axis columns. The chart object is not editable in any way with respect to the data it displays. Figure 40.10 displays chart objects displaying the same employee data in various formats.

Figure 40.10. Chart objects.

You can link the chart object to other record manager objects in master-detail relationships. The developer can make the chart object a detail view of data by setting the LinkDetailColumn, LinkMasterColumn, and LinkMasterForm properties of the chart object. One simple example to set up is to drop the familiar SCOTT/TIGER DEPT table onto a form. Create a chart object with ENAME as ChartXCol and SAL as ChartYCols, set the link properties appropriately on the chart object, and then run the form. The chart object will be the detail of employees per department. Figure 40.10 illustrates this master-detail relationship with the form as master to four detail chart objects. The chart object has many other properties similar to the form object. The following are chart-specific properties of interest:

The ChartAutoFormat property specifies whether the y-axis scales to the actual minimum and maximum values or uses the specified minimum and maximum values. The data type is boolean. This property is readable and writeable at run time.

The ChartGap property specifies the gap in pixels between groups of bars in horizontal and vertical bar graphs. The data type is long integer. This property is readable and writeable at run time.

The ChartLabelStyle property specifies the type of labels beside each bar in a horizontal or vertical bar graph. The data type is long integer. This property is readable and writeable at run time. Possible values are none, values, labels, or categories.

The ChartLegendHAlign property specifies that the chart legend should be aligned on the left or right side of the chart object. The data type is long integer. This property is readable and writeable at run time.

The ChartLegendVAlign property specifies that the chart legend should be aligned on the top or bottom side of the chart object. The data type is long integer. This property is readable and writeable at run time.

The ChartLineStyle property specifies the style of line to use in drawing the chart object. The data type is long integer. This property is readable and writeable at run time. In OPO version 1.0, this property has no effect.

The ChartMaxValue property specifies the maximum y-axis value for a vertical bar, horizontal bar, and line graph chart object. The data type is long integer. This property is readable and writeable at run time. The ChartAutoFormat property must be False for this value to have meaning.

The ChartMinValue property specifies the minimum y-axis value for a vertical bar, horizontal bar, and line graph chart object. The data type is long integer. This property is readable and writeable at run time. The ChartAutoFormat property must be False for this value to have meaning.

The ChartOverlap property specifies the amount of overlap in pixels between the bars in the same group for horizontal and vertical bar graphs. The data type is long integer. This property is readable and writeable at run time.

The ChartPieCircle property specifies whether the chart object displays pies as circles or as ovals conforming to the dimensions of the chart object. The data type is boolean. This property is readable and writeable at run time.

The ChartRowCount property specifies the maximum number of rows that the chart object will display. The data type is long integer. This property is readable at run time. The default value is zero, which implies all rows will be displayed. Any non-zero value, represented by n, causes the first n records to be displayed.

The ChartShowGrid property specifies the type of grid that the chart object should display. The data type is long integer. This property is readable and writeable at run time. Possible values are none, horizontal, vertical, or both.

The ChartShowLegend property specifies whether the chart object should display a legend. The data type is boolean. This property is readable and writeable at run time.

The ChartStacked property specifies whether vertical and horizontal bar graphs should display data in groups or as a single stacked value. The data type is boolean. This property is readable and writeable at run time.

The ChartStyle property specifies the type of chart or graph. The data type is long integer. This property is readable and writeable at run time. Possible values include Vertical Bar, Horizontal Bar, Line, or Pie.

The ChartXCol property specifies the name of the column from the database to be used for the x-axis. The data type is string. This property is readable at run time. You must specify this property even if the chart type does not need an x-axis variable.

The ChartYCols property specifies the names of the columns from the database to be used for the y-axis. The data type is string. This property is readable at run time.

Checkbox Object

The checkbox object is a data bound control. The checkbox is typically used to represent a toggle state of values for a particular column in the database. The checkbox is also used to represent a set of mutually exclusive values where one or more values can be chosen at a time from the set of all possible values. Checkbox-specific properties of interest are described as follows:

The ValueOff property specifies the value of the control when it is not selected. The data type is set to be the same as the radio button data type. This property is readable and writeable at run time. The default value is null.

The ValueOn property specifies the value of the control when it is selected. The data type is set to be the same as the radio button data type. This property is readable and writeable at run time.

Combo Box Object

The combo box object is a more versatile version of the pop-up object. Although each object allows the user to pick a value from a list, the combo box allows the user to enter values not already in the list. The combo box does not respect the 3D Control style for the DrawStyle property. Figure 40.11 displays three combo boxes; each displays a different type of data.

Figure 40.11. Combo box objects.

The following are combo box-specific methods and properties of interest:

The UpdateList() method must be called programmatically. This method returns no data. UpdateList() is called to update the data within a record manager for a pop-up, combo, or list box control.

The ValueList property specifies the list of values that a combo box can display. The data type is string. This property is readable and writeable at run time. There are three methods for setting the values in the ValueList property: 1) create a hard-coded list of one value per line; 2) use table column mapping, which selects all of the values for a specified column from the specified table; and 3) use queried values that a fully qualified SQL statement selects a column from a table using conditions and other SQL operators. In Figure 41.11, the ENAME combo box uses method 1, the HIREDATE combo box uses method 2, and the SAL combo box uses method 3 to populate the ValueList property.

Current Row Pointer Object

The current row pointer object is used to indicate the status of a record in relation to the database. A gray arrow indicates that the record is the current record but it is not active; a white arrow indicates a separate record. A black arrow indicates that the record is the current record and is also the active record, and a lock beside the arrow indicates that the record has changed and needs to be updated to the database. The current row pointer is of great value to a database application developer because it gives a quick visual cue indicating which records have pending changes. End users, however, are not accustomed to seeing current row pointers. The developer must use care in distributing applications to users unfamiliar with the current row pointer concept. The developer should explain what the object represents or not use it at all.

DBRecordset Object

The DBRecordset object is a non-visible object. It is a method of having a record manager that is not attached to a visible object. All the actions that are valid for the record manager of a form, embedded form, or repeater are valid for the DBRecordset object. The developer has to programmatically create and delete these objects. They use memory resources and must be deleted when the developer is finished using them.

Embedded Form Object

This object has all the properties of the form object with the exception of those methods specifically related to the style of window framing, such as WindowInitPos, WindowStyle, and so on. The embedded form is generally used for displaying a single record from a table. It is also generally used in forming master-detail relationships where the detail only needs to display one record.

Field Object

The field object carries most of the programming and database interface weight for the entire OPO product. This object enables the user to edit existing data and enter new data. You can set up counters using sequences, maximum values from a table plus a specified increment, and user-generated values. Display formats are available based on the DataType of the field. The following are field-specific methods and properties of interest:

The CounterGenKey() method responds to the need to specify a user-generated sequence. The data type is string. You must write method code to generate a sequence value. One reason for using this method over a sequence from the database is that the database may not support sequences. Another reason is to free up server-based resources.

The CounterIncBy property specifies the increment value to use in generating a new sequence value when using the "Table, MAX() + CounterIncBy" CounterType. The data type is long integer. This property is readable at run time.

The CounterSeq property specifies the name of the sequence from the database to be used for generating new values. The data type is string. This property is readable at run time.

The CounterTiming property determines when the counter value is to be generated. The data type is long integer. This property is readable at run time. Values are Immediate (upon insertion into the record manager) and Deferred (upon flushing the record to the database).

The CounterType property specifies whether the field is a counter field and how it gets its values. The data type is long integer. This property is readable at run time. Values include None, Sequence, "Table,MAX()+CounterIncBy," and "User Generated."

The HasScrollBar property specifies whether the object has a vertical scrollbar. The data type is long integer. This property is readable at run time. For field objects, the MultiLine property must be True for the scrollbar to display.

The MultiLine property specifies whether the object can handle multiline data. The data type is long integer. This property is neither readable nor writeable at run time. In the Windows version of OPO, a multiline field wraps only at carriage return linefeeds. In the Macintosh version of OPO, a field wraps when data flows beyond the right side of the field or when a linefeed is entered.

Horizontal and Vertical Scrollbar Objects

Horizontal and vertical scrollbar objects are designed to handle the scrolling of data within a record manager. Although each of these objects exists independently on the object palette, either can become visibly like the other just by changing is position and size. Each has the same methods and properties. Scrollbar-specific methods and properties of interest are described as follows:

The GoNxtLine() method responds to scrollbar requests and programmatic references. This method scrolls the record manager to the next record, if one exists, based on the ScrollAmtLine. This method returns no data.

The GoNxtPage() method responds to scrollbar requests and programmatic references. This method scrolls the record manager to the next block of records, if one exists, based on the ScrollAmtPage. This method returns no data.

The GoPos() method responds to scrollbar requests and programmatic references. This method scrolls the record manager to the next record, if one exists, based on the newpos requested. This method returns no data.

The GoPrvLine() method responds to scrollbar requests and programmatic references. This method scrolls the record manager to the previous record, if one exists, based on the ScrollAmtLine. This method returns no data.

The GoPrvPage() method responds to scrollbar requests and programmatic references. This method scrolls the record manager to the previous block of records, if one exists, based on the ScrollAmtPage. This method returns no data.

The ScrollAmtLine property specifies the amount to scroll when a GoNxtLine() or GoPrvLine() method is encountered. The data type is long integer. This property is readable and writeable at run time.

The ScrollAmtPage property specifies the amount to scroll when a GoNxtPage() or GoPrvPage() method is encountered. The data type is long integer. This property is readable and writeable at run time.

The ScrollMax property specifies the upper limit of the scrollbar for visually positioning the scrollbox. The data type is long integer. This property is readable and writeable at run time.

The ScrollMin property specifies the lower limit of the scrollbar for visually positioning the scrollbox. The data type is long integer. This property is readable and writeable at run time.

The ScrollObj property specifies the container whose record manager is to be controlled by the scrollbar. The data type is string. This property is readable and writeable at run time.

The ScrollPos property specifies the current record in the record manager. The data type is long integer. This property is readable and writeable at run time.

Line Object

The line object is a visual object. It cannot be bound to data. This object is useful for creating visual effects to enhance the user interface. The line does not respect the 3D Control style for DrawStyle. The Direction property specifies the direction of the line object. The data type is long integer. This property is readable and writeable at run time. Values are Upper Left to Lower Right and Lower Left to Upper Right.

List Box Object

The list box object is a version of the pop-up object where the display values are visible at all times. The list box highlights the selected value. The list box object does not respect the 3D Control style for DrawStyle. Figure 40.12 displays three list boxes; each is displaying a different type of data.

Figure 40.12. List box objects.

The Translation property specifies the list of values that map between what is displayed to the user and internal values. The data type is string. This property is readable and writeable at run time. There are three methods for setting the values in the Translation property: 1) create a hard-coded list of one display value and one internal value per line, 2) use table column mapping, which selects all the display and internal values for two specified columns from the specified table, and 3) use queried values from the display and internal value columns that a fully qualified SQL statement selects from a table using conditions and other SQL operators. In Figure 40.12, the ENAME list box uses method 1, displaying ENAME and storing ENAME; the DEPTNO list box uses method 2, displaying DNAME and storing DEPTNO; and the MGR list box uses method 3, displaying ENAME and storing MGR for populating the Translation property.

Menu Bar, Menu, and Menu Item Objects

The menu bar object contains menus, which in turn contain menu items. The menu bar is a graphical object that is not visible during design time and will not display during run time unless the developer creates one and writes method code to cause it to display and update. Each form has its own individual menu bar object. Menu bars provide a series of menus that the user can select to perform actions that the developer has associated with the particular menu items belonging to that menu. Menu bars should work for forms and reports. In OPO version 1.0, menu bars only work for forms. Menu bar-specific methods of interest are described as follows:

The AppendMenu() method appends a menu to the end of the menu bar. The menu is inserted before any system default menus that would normally appear at the end of the menu bar.

The ClearMenuBar() removes all menus from the menu bar. The menu objects are not removed from memory. You must delete the menu objects individually using the DELETE menu_object command or using the DeleteAllMenus() method.

The DeleteAllMenus() method removes all menus from the menu bar and deletes the menu objects associated with the menu bar from memory.

The GetMenu() method returns a reference to the specified menu object in the menu bar. The data type is object.

The GetMenuCount() method returns a count of all menus in the menu bar. The data type is long integer.

The InsertMenu() method inserts a menu into the specified position in the menu bar.

The RemoveMenu() method removes a menu from the specified position in the menu bar. The menu object is not removed from memory. You must delete the menu object individually by using the DELETE menu_object command or the DeleteAllMenus() method.

The SysDefaultMenuBar() method initializes a menu bar with the system default menus. This method deletes any existing menus before initializing the menu bar.

Menus represent a grouping of related topics. A File menu has Open, Close, Save, and Save As topics, for example. These topics are referred to as menu items. Menu items represent hooks into a specific subsection of code within the TestCommand() and DoCommand() methods of the form report or application. A menu bar is limited to one level of menus; a menu item cannot open a subsequent menu. The following are menu-specific methods of interest:

The AppendMenuItem() method appends a menu item to the end of the menu. The developer specifies the item's label, command code, help context, and keyboard hot key.

The DeleteMenuItem() method deletes a menu item from the specified position in the menu.

The GetItemCount() method returns a count of all items in a menu. The data type is long integer.

The GetMenuItem() method returns a specified piece of information about a specified menu item in the menu. Possible types of information include the label, command code, help context, and keyboard hot key. The data type varies depending on the type of information requested.

The InsertMenuItem() method inserts a menu item at the specified position in a menu. The developer specifies the item's label, command code, help context, and a keyboard hot key.

The SetMenuItem() method modifies a specified piece of information about a specified item in a menu.

OCX Object

An OCX object is a custom object imported into Oracle Power Objects. OCX objects are defined by Microsoft standards. The OCX object is replacing the existing VBX object definitions. OCX objects are loaded into the OPO object palette by loading the object into the OCX register. Any OCX objects that have been registered in the developer's Windows environment automatically are appended to the OPO object palette. OCX objects are available only in the Microsoft Windows version of OPO. These objects represent fully operational, self-contained applications embedded with the host application. OPO supports the concept of embedded OCX objects, but provides no programmatic interface to an OCX and provides no support for binding the OCX object to data from the database through the OPO record manager. More in-depth support for OCX objects is planned for OPO version 1.1. If you need more information, please refer to the appropriate Microsoft documentation.

Oval Object

The oval object is a visual object. It cannot be bound to data. This object is useful for creating visual effects to enhance the user interface. The oval object does not respect the 3D Control style for DrawStyle. The oval object also has another interesting characteristic—it can contain other objects. Containing another object means that the contained object is completely within the boundaries of the container object.

Picture Object

The picture object is a data bound control. It is specifically designed to handle long raw data formatted in the BMP picture format. Note the absence of the DataSize and Data type properties. These properties are not required because the picture object is designed to expect only long raw data.

Pop-up Object

The pop-up object is a data bound control that performs an inherent lookup operation that allows the developer to display one value while storing the same or different value. The pop-up does not respect the 3D Control style for DrawStyle. The pop-up also performs another very important, but no so obvious, function. Because the developer specifies the values that the pop-up can display and store, the user is guaranteed that a value chosen from a pop-up is valid. The same validity concept applies to list boxes, but not to combo boxes. Combo boxes must validate their values because the user can enter a value not in the ValueList. Figure 40.13 displays three pop-ups; each displays a different type of data.

Figure 40.13. Pop-up objects.

The Translation property specifies the list of values that map between what is displayed to the user and internal values. The data type is string. This property is readable and writeable at run time. There are three methods for setting the values in the Translation property: 1) create a hard-coded list of one display value and one internal value per line; 2) use table column mapping, which selects all the display and internal values for two specified columns from the specified table; and 3) use queried values where a fully qualified SQL statement selects the display and internal value columns from a table using conditions and other SQL operators. In Figure 40.13, the ENAME pop-up uses method 1, displaying ENAME and storing ENAME; the DEPTNO pop-up uses method 2, displaying DNAME and storing DEPTNO; and the MGR pop-up uses method 3 displaying ENAME and storing MGR for populating the Translation property.

Radio Button and Radio Button Frame Objects

The radio button object is a data bound control. The radio button is used to represent a set of dependent values from which only one value can be chosen at a time from the set of all possible values.

The ValueOff property specifies the value of the radio button when it is not selected. The data type is set to be the same as the radio button data type. This property is readable and writeable at run time. The default value is null.

The ValueOn property specifies the value of the radio button when it is selected. The data type is set to be the same as the radio button data type. This property is readable and writeable at run time.

The frame object is a special purpose, data bound control. The frame object has inherent behaviors that allow it to control the mutually exclusive nature of radio buttons that are within its containment hierarchy. If the developer places a number of radio buttons within the frame object, taking care to set the ValueOn property of each radio button to a unique value, setting the value of the frame controls the behavior of the contained radio buttons. Also, clicking on a radio button within the frame sets the value of the frame and subsequently controls the behavior of the other contained radio buttons.

Rectangle Object

The rectangle object is a visual object. It cannot be bound to data. This object is useful for creating visual effects to enhance the user interface. The rectangle object also has another interesting characteristic—it can contain other objects.

Repeater and Repeat Panel Objects

The repeater object has all of the characteristics of the form object except for window-related properties. The repeater object allows the developer to design an interface in which objects are repeated. This repeating concept is implemented using the repeat_panel. The repeater is most similar to the grid control from Microsoft Visual Basic except that the repeater has built-in record manager functionality for binding data from the database to objects within the repeat_panel. Anytime that the developer needs to display more than one record at a time, that developer should choose the repeater as the primary container for the display.

The repeat_panel object forms the basis the repeater object. The panel can contain any object that can be bound to data or that is strictly a graphical object. Objects that should not be used inside the repeat_panel include embedded forms, classes tied to record managers, and other repeaters. Although these objects can be instanced and embedded within the repeat_panel, they will not function as expected. The number of visible repeat_panels determines the maximum number of records that the user sees during run time.

Static Text Object

The static text object is a visual object. It cannot be bound to data. This object is useful for creating labels and directions to aid the user in understanding what is being presented to them. Although the object implies an inability to change its display during run time by using the term static, keep in mind that you can change the Label property of the static text object during run time to reflect the message that the developer deems appropriate at the time.

Status Line Object

The status line object is a graphical object that is not visible during design time and does not display during run time unless the developer creates one and writes method code to cause it to display and update. Each form has its own individual status line object. Status line-specific methods of interest are described as follows:

The ClearStatusLine() method deletes all panels from the status line except the summary panel. This method returns no data.

The DeleteStatusPanel() method deletes the specified status panel from the status line based on the pos parameter, an integer. You cannot delete the summary panel.

The GetStatCount() method returns the number of status panels in the specified status line. The data type is long integer.

The GetStatPanel() method returns a specified piece of information about a specified panel in the status line. The data type varies depending on the type of information requested. The possible types of information that you can request include panel text, width of panel in pixels, command code, "enabled" text, "checked" text, "disabled" text, and "disabled and checked" text.

The InsertStatusPanel() method inserts a new panel at the specified position pos, width wid, and maximum message length maxMsgLen. All of the parameters are integers.

The SetStatDispList() method designates a status panel on a status line to be updated. You must specify the panel's command code and the message strings associated with the panel's status.

The SetStatusPanelMsg() method sets the text displayed in a specified panel of the status line.

The SysDefaultStatusLine() method initializes a status line with the system default panels. This method deletes any existing panels before initializing the status line.

Toolbar Object

The toolbar object is a graphical object that is not visible during design time and does not display during run time unless the developer creates one and writes method code to cause it to display and update. Each form has its own individual toolbar object. Toolbars provide a series of buttons or icons that the user can select to perform actions that the developer has associated with the particular button or icon. Toolbars should work for forms and reports. In OPO version 1.0, toolbars only work for forms. Toolbar-specific methods of interest are described as follows:

The ClearToolbar() method deletes all buttons on the toolbar.

The TBAppendButton() method appends a button to the end of the toolbar. The developer specifies the command code, a bitmap, a button style, and a help context.

---

The help context specified in the TBAppendButton() method is a help context id. OPO version 1.0 doesn't have a method for the developer to indicate the help file to look in for the help context. OPO looks in PWROBJX.HLP, the default Microsoft Window Help file for Power Objects. A developer who wants to support context-based help for an application could create a help file, name it PWROBJX.HLP, and replace the original OPO help file. This solution permits the OPO environment to resolve the application-defined help contexts. Unfortunately, this solution also disables the user's ability to search for help from the original OPO help file. This oversight should be corrected in OPO version 1.1.

---

The TBDeleteButton() method deletes a button from the specified position in the toolbar.

The TBGetButton() method returns a specified piece of information about a specific button in the toolbar. You can find out the button's command code, bitmap, the button style, or help context. The data type varies depending on the type of information requested.

The TBGetCount() method returns a count of all buttons in the toolbar, including separator buttons. The data type is long integer.

The TBInsertButton() method inserts a button at a specified position in the toolbar. The developer specifies the command code, bitmap, button style, and help context.

The TBSetButton() method modifies a specific piece of information about a specific button in a toolbar. You can set any of the button characteristics including command code, bitmap, button style, and help context.

Summary

Oracle Power Objects is a product that makes developing database applications an easier task than it has been in the past. OPO has an assortment of powerful objects. Some objects are purely graphical in nature; others are bound to data, and others handle containers and record managers. With reusable classes and libraries for storing and sharing classes, bitmaps, and OLE objects, OPO version 1.0 is a contender in today's database application development arena. The OPO Sample Applications that ship with every OPO configuration are a good place to start to explore how combining these OPO objects into forms and then combining forms into applications can effectively solve your database application development requirements.