Package com.ibm.lpex.alef.contentassist

This package provides code-assist support.

See:
Description

Interface Summary

ICompletionProposal	Interface for completion proposals generated by content-assist processors.
ICompletionProposalExtension	Extends ICompletionProposal with the following functions: handling of trigger characters other than ENTER completion proposal validation for a given offset context information can be freely positioned.
IContentAssistant	An IContentAssistant provides support on interactive content completion.
IContentAssistProcessor	A content assist processor proposes completions and computes context information for a particular content type.
IContextInformation	The interface for context information presented to the user and generated by content-assist processors.
IContextInformationPresenter	A context information presenter determines the presentation of context information depending on a given document location.
IContextInformationValidator	A context information validator is used to determine whether a displayed context information is still valid at the current cursor position, or should be dismissed.

Class Summary

CompletionProposal	The standard LPEX implementation of the ICompletionProposal interface.
ContentAssistant	An LPEX-based implementation of the IContentAssistant interface.
ContextInformation	A default implementation of the IContextInformation interface for LPEX.
ContextInformationValidator	A default LPEX implementation of the IContextInfomationValidator interface.

Package com.ibm.lpex.alef.contentassist Description

This package provides code-assist support. It is a version of package org.eclipse.jface.text.contentassist modified for use with LPEX. It defines a text viewer add-on for text-completion support. Popup windows are used to display a list of possible text choices to complete a phrase, based on the current document context. The user can select one of these proposals for automatic insertion in the text. Content assist also supports contextual popups for providing the user with information related to the current position in the document.

IContentAssistant is the main interface defined in this package. The default implementation ContentAssistant of this interface can be configured with various invocation and presentation options, and different phrase-completion strategies for different document content types.

Adding content assist to your document parsers

1.- The constructor of your LPEX-based editor must first set an LpexSourceViewerConfiguration which defines the content assistant (and its content-assist processors) to be registered:

 
 // set MyLpexSourceViewerConfiguration in LPEX, in order
 // to define my editor's content-assist processors
 setSourceViewerConfiguration(new MyLpexSourceViewerConfiguration()); 

Here's an example implementation of MyLpexSourceViewerConfiguration. The document type for a content-assist processor registration must match the string that the particular parser returns in method getLanguage(LpexDocumentLocation).

 
 public class MyLpexSourceViewerConfiguration extends LpexSourceViewerConfiguration
 {
  /**
   * Returns the content assistant and processors ready to be used with my
   * LPEX source viewer.
   */
  public IContentAssistant getLpexContentAssistant(ISourceViewer sourceViewer)
  {
   ContentAssistant assistant = new ContentAssistant();

   // 1.- register a content-assist processor for COBOL documents
   assistant.setContentAssistProcessor(new MyCobolCompletionProcessor(), // processor
                                       LpexCommonParser.LANGUAGE_COBOL); // document type 
                                       // IDocument.DEFAULT_CONTENT_TYPE);
   // 2.- register a content-assist processor for embedded SQL
   assistant.setContentAssistProcessor(new MySqlCompletionProcessor(),
                                       LpexCommonParser.LANGUAGE_SQL);

   // 3.- register content-assist processors for other document types and
   //     mixed-document sublanguages
   // . . .

   // define options for my editor's content assistant: popup windows orientation
   assistant.setProposalPopupOrientation(assistant.PROPOSAL_OVERLAY);
   assistant.setContextInformationPopupOrientation(assistant.CONTEXT_INFO_ABOVE);

   // auto activation
   assistant.enableAutoActivation(true);
   assistant.setAutoActivationDelay(1000);

   // additional information popup
   assistant.setInformationControlCreator(getMyInformationControl(sourceViewer));

   return assistant;
  }

  /**
   * Use a JFace DefaultInformationControl (in its simplest form)
   * to display content-assist information.
   */
  private IInformationControlCreator getMyInformationControl(ISourceViewer sourceViewer)
  {
   return new IInformationControlCreator() {
    public IInformationControl createInformationControl(Shell parent)
    {
     return new DefaultInformationControl(parent);
    }};
  }
 }

2.- Your editor may register actions to be associated with the context and/or global menus for explicit invocation of the content-assist processor in a document view. For example:

 
 /**
  * Defines content-assist actions for my editor.
  * @see com.ibm.lpex.alef.LpexAbstractTextEditor#createActions
  */
 protected void createActions()
 {
  super.createActions();

  // when this action is selected, method showPossibleCompletions()
  // in the registered content-assist processor is called
  setAction("ContentAssistProposal",                                  // action id
     new TextOperationAction(getMyResourceBundle(),                   // resource bundle
                             "ContentAssistProposal.",                // resource key prefix 
                             this,                                    // ITextEditor
                             ISourceViewer.CONTENTASSIST_PROPOSALS)); // action opcode
  // when this action is selected, method showContextInformation()
  // in the registered content-assist processor is called
  setAction("ContentAssistTip",
     new TextOperationAction(getMyResourceBundle(),
                             "ContentAssistTip.",
                             this,
                             ISourceViewer.CONTENTASSIST_CONTEXT_INFORMATION));
 }

3.- A content-assist processor implements the IContentAssistProcessor interface. Here's an example implementation of method computeCompletionProposals() in such a processor.

 
 /**
  * Returns a list of completion proposals based on the specified location
  * within the document that corresponds to the current cursor position within
  * the text viewer.  LPEX currently ignores this argument, and just assumes
  * the current cursor position.
  *
  * @param viewer    the LpexTextViewer requesting content-assist proposals
  * @param docOffset N/U
  *
  * @see IContentAssistProcessor#computeCompletionProposals(ITextViewer,int)
  */
 public ICompletionProposal[] computeCompletionProposals(ITextViewer viewer, int docOffset) 
 {
  // 1.- retrieve the incomplete text in need of assistance
  String currentText = myGetCurrentText(viewer);

  // 2.- set up a list of matching candidates
  Vector matches = new Vector();
  if (currentText.length() > 0) {
   for (int i = 0; i < myTableOfProposals.length; i++) {
    String completion = myTableOfProposals[i];
    if (completion.startsWith(currentText))
     matches.addElement(completion);
    }
   }

  // 3.- optionally sort matches
  // . . .

  // 4.- return completion proposals [each with aditional proposal & context tip info]
  ICompletionProposal[] result = new ICompletionProposal[matches.size()];
  for (int i = 0; i < matches.size(); i++) {
   // Example of content-assist activation scenario:
   //
   //  edit window:        /* ccccc */ con|          currentText
   //  replacement string:             continue      replacement offset: -3
   //
   //  applying proposal:  /* ccccc */|con           reposition replacement offset chars
   //                      /* ccccc */|              delete replacement length chars
   //                      /* ccccc */ continue|     insert replacement string
   String proposal = (String)matches.elementAt(i);
   IContextInformation info = new ContextInformation(
      proposal,
      "'" +proposal+ "' tooltip info"); // post-insertion tooltip information

   result[i] = new CompletionProposal(
      // 1.- first bundle of arguments is enough for content proposals:
      proposal,                    // replacement string to be inserted in document
      -currentText.length(),       // replacement offset relative to current cursor
      currentText.length(),        // replacement length (original text to delete)
      0,                           // cursor position after replacement (N/U)

      // 2.- optional second bundle of arguments is for additional context
      // information while showing the completion proposals, where desired:
      null,                        // optional image
      proposal,                    // display string of proposal
      info,                        // context information
      "Keyword: '" +proposal+ "'"  // additional proposal information
      );
   }
  return result;
 }

 /**
  * Returns the current whitespace-delimited document text preceding the cursor
  * for purposes of content assist.  Based on this partial text typed by the
  * user, a table of completion proposals will be built up when the user asks
  * for it (or is automatically triggered) - see #computeCompletionProposals().
  */
 private String myGetCurrentText(LpexTextViewer viewer)
 {
  // Note: trying to get the current token from LpexCommonParser first
  // (as whitespace is rarely a good delimiter) may not work as expected
  // unless parseAfterEveryKey is on.
  LpexView lpexView = viewer.getLpexView();
  String text = lpexView.elementText(lpexView.currentElement());
  StringBuffer currentText = new StringBuffer();

  // ZERO-based column preceding cursor's
  int column = lpexView.currentPosition() - 2;
  if (text != null && text.length() > column) {
   while (column >= 0) {
    char c = text.charAt(column);
    if (c == ' ' || c == '\t')
     break;
    currentText.insert(0, c);
    column--;
    }
   }
  return currentText.toString();
 }