Defining Nonvisual part Interfaces for OASearch

Once you have thought through the design of your nonvisual parts, you define their interfaces to VisualAge. This example takes you through step-by-step through the definition of the OAContractor part using the Part Interface Editor. To define the interfaces for other nonvisual OASearch parts, follow the same procedure using the interface information provided.

Before you define the interface for a nonvisual part, you have to create it. Then, open the part. Switch to the Part Interface Editor.

  1. First, define the attributes. On the Attribute page, do the following:

  2. Next, define the actions. On the Action page, do the following:

  3. The OAContractor part has one event that is not associated with an attribute, called queryFound. On the Event page, do the following:

  4. Select Save from the File menu to save your work.

To define interfaces for the remaining nonvisual parts, use the information found in Design of Nonvisual Parts for OASearch.

The next step for this partis Generating Feature Code for the OASearch Nonvisual Parts.


Related concepts
Part Design Guidelines
Part Implementation

Related procedures
Defining Part Interfaces for Visual Composition

Related references
Design of Nonvisual Parts for OASearch

Creating the OAMorphableSpinButton Part

OAMorphableSpinButton illustrates the creation of a custom visual part. In this case, the class is derived from INumericSpinButton.

  1. Create a visual part as follows:

    The part opens in the Composition Editor.

  2. In the Part Interface Editor, add the valueAsString attribute.

  3. In the Class Editor. set the following generation options:

  4. Generate feature code for the new attribute.

  5. Generate interface source code for the interface DLL.

  6. To keep the value and valueAsString attributes synchronized, add the following code (shown in bold) to the attribute's set member function:
    iValueAsString = aValueAsString;                 
                                                     
    if ( !(aValueAsString.asInt() == value() ) ) {   
                                                     
    // Sync value with valueAsString                 
    // This call will signal a valueId event         
    setValue( aValueAsString.asInt() );              
    }                                                
    

  7. To complete the synchronization, you must also override the base class' setValue( ) function. This additional code can be found in oamrfbtn.cpv and the corresponding header file.

  8. Generate part source.

  9. Build the interface DLL.


Related concepts
About Implementing Custom Visual Parts
Generated Interface Code

Related procedures
Deriving from Visual Classes
Generating Code


Related references
Design for the OAMorphableSpinButton Part

Generating Feature Code for the OASearch Nonvisual Parts

To generate feature code for the OAContractor part, follow these steps. This example assumes that you have already defined the interface for the OAContractor part.

  1. Open the part. Switch to the Class Editor by selecting the ocecledi icon in the lower-right corner of the window.

  2. In the Base name for other files field, enter contrctr

  3. Select the Generate code (.hpp and .cpp) check box; then check C++ header file (.hpv) and C++ code file (.cpv).

  4. Select File, Save and generate, and Feature source.

  5. Generate the feature code using one of the following methods:

    The first time you will probably want to generate code for all of your features. Then, you can generate code for other features as you add them. For this example, select the Generate all push button.

    The generated feature code is stored in the files you specified in the Class Editor, contrctr.hpv and contrctr.cpv. If these files already exist, the code you just generated is appended to the ends of these files.

    You must also generate feature code for OAContract, OASkill, and OASkillBase to complete the sample application.

    For most parts, you must modify the code to make your part fully functional. For this part, the next step is Modifying Generated Feature Code for OA Nonvisual Parts.


Related concepts
Generated Feature Code

Related procedures
Generating Feature Code
Defining Part Interfaces for Visual Composition

Related references
Design of Nonvisual Parts for OASearch

Modifying Generated Feature Code for OA Nonvisual Parts

After you have VisualAge generate the feature code, review it. Does it do what you need it to do? If not, modify the code.

The OAContractor part's feature code needs the following changes:


Related concepts
Generated Feature Code

Related procedures
Generating Feature Code
Generating Feature Code for the OASearch Nonvisual Parts

Related references
Design of Nonvisual Parts for OASearch

Adding Logic to the Database Actions

This version of the OASearch application uses an IProfile-based database to retrieve and store information about OA contractors. You must add this logic to generated feature code.

Code for OAContractor

To modify feature code, edit the code files using the syntax text editor provided by VisualAge or your favorite editor. Code for the getContractor and putContractor actions is found in contrctr.cpv.

The getContractor action does the following:

  1. Prime the database.
  2. If the contractor ID is not valid, refresh it.
  3. Check the database for the designated contractor. If it is not found, throw an exception and return.
  4. Otherwise, retrieve the contractor information, populate the instance, and notify observers that the information has been found.

The putContractor action does the following:

  1. Prime the database.
  2. If the contractor ID is not valid, refresh it.
  3. If there is data to save, save it.

The primeData function is necessary for the Windows version of this application. It loads database values into the registry. This public member function is not defined as a feature in the OAContractor part interface. You must add code for this function yourself. For details, see contrctr.cpv and contrctr.hpv.

Code for OAContract

To modify feature code, edit the code files using the syntax text editor provided by VisualAge or your favorite editor. Code for the getContract and putContract actions is found in contract.cpv.

The getContract action does the following:

  1. Prime the database.
  2. Check the database for the designated contract. If it is not found, throw an exception and return.
  3. Otherwise, retrieve the contract information, populate the instance, and notify observers that the information has been found.

The putContract action does the following:

  1. Prime the database.
  2. If there is data to save, save it.

The primeData function is necessary for the Windows version of this application. It loads database values into the registry. This public member function is not defined as a feature in the OAContract part interface. You must add code for this function yourself. For details, see contract.cpv and contract.hpv.

Code for OASkillBase

To modify feature code, edit the code files using the syntax text editor provided by VisualAge or your favorite editor. Code for the getSkill and putSkill actions is found in skillb.cpv.

The getSkill action does the following:

  1. Prime the database.
  2. Check the database for the designated skill name. If it is not found, throw an exception and return.
  3. Otherwise, retrieve all records that contain the skill name, create and populate OASkill instances as required, and notify observers that the information has been found.

The putSkill action does the following:

  1. Prime the database.
  2. If there is data to save, save it.

The primeData function is necessary for the Windows version of this application. It loads database values into the registry. This public member function is not defined as a feature in the OASkillBase part interface. You must add code for this function yourself. For details, see skillb.cpv and skillb.hpv.

No additional code is necessary for the OASkill part.


Related concepts
Generated Feature Code

Related procedures
Generating Feature Code for the OASearch Nonvisual Parts
Modifying Generated Feature Code for OA Nonvisual Parts

Related references
Design of Nonvisual Parts for OASearch

Adding Logic to the Utility Actions

The OAContractor part contains two utility actions: parseName and clear. The code for these actions is found in contrctr.cpv.

The parseName action parses input text from the Request for Contractor Information window and sets the contractor's name and ID attributes using public set member functions. This means that as a result of the updates, events for each of these attributes are signaled.

The clear action simply sets all string attributes to null strings and sets bool attributes to false.


Related concepts
Generated Feature Code

Related procedures
Generating Feature Code for the OASearch Nonvisual Parts
Modifying Generated Feature Code for OA Nonvisual Parts

Related references
Design of Nonvisual Parts for OASearch

Extending the Attribute Functions

In most cases, the code generated for attributes can be used without modification. In this application, however, the following code must be added to the setFirstName, setLastName, and setMiddleInitial member functions. This code (found in cntrctr.cpv) invalidates the current value of thecontractorID attribute so it will be recalculated before the next database access:

// Invalidate contractorID attribute
enableIDValid(false);

Now add code to derive the value of the contractorID attribute. The following example shows the code as modified in contrctr.cpv:

OAContractor& OAContractor::setContractorID(const IString& aContractorID)
{
  if (!(iContractorID == aContractorID))
  {
    iContractorID = aContractorID;
    notifyObservers(INotificationEvent(OAContractor::contractorIDId, *this));
  } // endif
 
//  Test for string with nontrivial content
    if (iContractorID.length() > 5)
       enableIDvalid(true);
 
  } // endif
 
  return *this;
}

This action sets the IDvalid attribute to true if the resulting value of contractorID is valid.

You also need to overload the setContractorID member function to accept no parameters. This version merely refreshes the value of contractorID using the current values of the name attributes. The following example shows the code as added to contrctr.cpv. Remember to add the appropriate function prototype to contrctr.hpv.

// Overloading set member function for refresh purposes                     
                                                                            
OAContractor& OAContractor::setContractorID()                               
{                                                                           
  setContractorID(firstName()+middleInitial()+lastName());                  
                                                                            
  return *this;                                                             
}                                                                           

Lastly, add code to support the activeStatus attribute. All data in the OASearch database is stored as strings, but the set member function that is generated for the activeStatus attribute takes a bool as a parameter. You must add a member function that takes a string as a parameter. Because you don't intend to connect to the member function, it is not necessary to add this to the part interface for OAContractor. However, you must add the member function prototype to the contrctr.hpv file.

The following example shows both the generated feature code and the added code in contrctr.cpv:

bool OAContractor::isActiveStatus() const
{
  return iActiveStatus;
}
 
OAContractor& OAContractor::enableActiveStatus(bool enable)
{
  if (!(iActiveStatus == enable))
  {
    iActiveStatus = enable;
    notifyObservers(INotificationEvent(OAContractor::activeStatusId, *this));
  } // endif
  return *this;
}
 
OAContractor& OAContractor::enableActiveStatus(const IString aValue)
{
  bool tempBool = (aValue.lowerCase() == "true" ? true : false)
  enableActiveStatus(tempBool);
 
  return *this;
}

No additional work on attribute code is necessary for the other nonvisual parts.


Related concepts
Generated Feature Code

Related procedures
Generating Feature Code for the OASearch Nonvisual Parts
Modifying Generated Feature Code for OA Nonvisual Parts

Related references
Design of Nonvisual Parts for OASearch