jface

Package Specification

Three specific contribution managers are provided: a status line manager (StatusLineManager), a tool bar manager (ToolBarManager), and a hierarchical menu manager (MenuManager).

Actions (IAction) are commands which can be triggered from the UI, like the ones found in menus, toolbars, and buttons. Menus and tools bars are typically populated with contribution items that delegate to actions (ActionContributionItem).

Note: None of the classes in this package maintain global state.
 

Provides support for bindings between commands and various user input events (e.g., keyboard shortcuts).

Package Specification

This package provides the common classes and abstract classes required to provide binding support.

All the real work in this package is carried out by the BindingManager, and most work with bindings can be carried out directly with it. The binding manager manages a collection of bindings, and decides which bindings are active at any point in time. By changes the various properties of the manager, the active bindings will change. The binding manager implements a caching scheme that is optimized for an infreqeuntly changing set of bindings, but frequently changing properties.

The binding manager also manages schemes. A scheme is a grouping of bindings. To create a scheme, use BindingManager.getScheme(String). The scheme must then be defined before it can be used.

If you wish to implement your own type of binding, then you must subclass Trigger and TriggerSequence. Then, simply use these subclasses with the BindingManager.

Provides support for bindings between commands and keys.

Package Specification

This just a key-specific implementation of the generic bindings and trigger support. This package provides an abstraction layer between the SWT key events and key bindings within JFace.

KeySequence is a TriggerSequence that has KeyStroke instances as triggers. A KeyStroke is composed of one or more keys held down at the same time. A key stroke ends when the keys are released. A key stroke can contain zero or more modifiers keys, but it always contains exactly one natural key. A modifier key is one of Ctrl, Shift, Alt, or Command. A natural key is anything else.

Natural keys are further subdivided into special keys and character keys. Character keys are keys that have an ASCII representation (e.g., Space, 'A' and Backspace). Special keys are ones that do not (e.g., Arrow Up, F11, and NumLock).

SWTKeySupport is a static class that provides the link between SWT and these internal representations. It has methods for converting between SWT key events and the internal representation, and vice versa. It also provides access to the native-style key formatting facilities.

Provides support for formatting key sequences.

Package Specification

This is a collection fo various formatters for key sequences. The formatters are accessible through the KeyFormatterFactory. To change how keys are formatted in the user interface, call KeyFormatterFactory.setDefault(IKeyFormatter). They provided formatters are:

FormalKeyFormatter

Provides a formal grammar for reading and writing key sequences.

NativeKeyFormatter

Provide a native-looking, human-readable format for keys.

CompactKeyFormatter

A variation of the native formatter that provides a more compact representation.

EmacsKeyFormatter

An Xemacs-style formatter (e.g., C^x C^x).

Provides JFace-specific support for commands.

Package Specification

This package provides a handler that wraps a legacy instance of IAction, as well as a manager for associating images with commands.

Package Specification

Provides JFace-specific support for contexts.

Package Specification

This package provides some context identifiers that have special meaning in the context of JFace.

Package Specification

This package provides classes that can be used to observe changes in SWT widgets.

Package Specification

This package provides classes that can be used to observe the JFace Viewer framework.

Package Specification

This package provides classes that bridge between data binding and the JFace Wizard framework.

Package Specification

The dialog framework consists of an abstract base class (Dialog), along with more concrete dialog subclasses for displaying messages (MessageDialog), soliciting text input (InputDialog), and displaying progress during a long-running operation (ProgressMonitorDialog).

Dialog stores (IDialogStore, DialogStore) provide a general framework for organizing a dialog's settings into key/value pairs. Multi-page dialogs are made easier through the use of dialog pages (IDialogPage, DialogPage).

Note: None of the classes in this package maintain global state.
 
 
 

Package Specification

This package provides classes that can be used to guide a dialog user through choosing appropriate content for fields in a dialog or wizard.

A ContentProposalAdapter can be attached to an arbitrary control to provide a popup showing content proposals. These proposals appear when the defined assist keystroke is invoked. The ContentProposalAdapter manages the creation, hiding, and showing of the proposal popup, as well as the proper handling of key events between the adapted control and its popup. Implementors of IControlContentAdapter allow the adapter to set and retrieve the contents of the supplied control.

An AutoCompleteField configures a ContentProposalAdapter in a manner that supports automatic field completion popups that filter based on the control's contents.

ControlDecoration can be used to decorate an arbitrary control with an image that communicates information about the control's content. Decorations can be used to show additional information about a field, such as its status, or a cue that shows availability of content proposals. Decorations are defined in pre-defined locations relative to the control, and can be set up to show at all times, or only when the control has focus. It is up to the client to ensure there is enough space allocated to render the control decoration. Decorations can optionally show descriptive text when the user hovers over them.

DecoratedField can also be used to decorate a control. The main difference is that decorated fields reserve space for multiple decorations in particular locations around the control. To do this, the field manages the creation of the field's control, using a specialized layout to ensure there is adequate space reserved for decorations around the control. Other than using the field to manage the decorations themselves, clients are expected to interact directly with the control.

Note: None of the classes in this package maintain global state.

Internal classes and helpers to implement the revision model and its UI presentation. See the org.eclipse.jface.text.revisions package for the API classes implementing the revision model.

• paint revision information in the vertical ruler
• adapt the revision information to (quick) diff scripts

This package is internal and may be subject to change without notice.

Internal support classes and helpers for the org.eclipse.jface.text.source package.

Package Specification

This package provides classes that can be used to generate layouts.

Package Specification

This package provides classes for trim widgets.

Package Specification

The IRunnableWithProgress interface should be implemented by any class whose instances are intended to be executed as long-running operations. These objects can then be run in any runnable context (IRunnableContext), including such standard JFace UI components as application windows (ApplicationWindow), wizard dialogs (WizardDialog), and progress monitor dialogs (ProgressMonitorDialog). The utility class ModalContext defines the basic mechanism and UI event loop for modal operations.

Package Specification

The individual preference values are maintained in a preference store (IPreferenceStore). Each preference has a current value and a default value use to (re-)initialize it. The framework provides a concrete preference store implementation (PreferenceStore) based on an internal java.util.Properties object, with support for persisting the non-default preference values to files or streams.

A field editor presents the value of a single preference to the end user. The value is loaded from the preference store; if modified by the end user, the value is validated and eventually stored back to the preference store.

This package contains ready-to-use field editors for various types of preferences:

• BooleanFieldEditor - booleans
• IntegerFieldEditor - integers
• StringFieldEditor - text strings
• RadioGroupFieldEditor - enumerations
• ColorFieldEditor - RGB colors
• FontFieldEditor - fonts
• DirectoryFieldEditor - directories
• FileFieldEditor - files
• PathEditor - paths

Note: None of the classes in this package maintain global state.
 

Package Specification

• font registries (FontRegistry) - for hanging on to the SWT font objects needed by an application
• color registries (ColorRegistry) - for hanging on to the SWT color objects needed by an application
• image registries (ImageRegistry) - for hanging on to the SWT image objects needed by an application
• image descriptors (ImageDescriptor) - surrogate object for creating SWT images
• string conversion (StringConverter) - for parsing property files

Image descriptors are objects that knows how to create an image on demand. They serve as a lightweight representation of images in situations where no SWT display exists yet, and are used mainly in conjunction with image registries. This package contains the image descriptor framework, which is a simple hierarchy rooted at the abstract class ImageDescriptor. The framework includes abstract subclasses for composing images (CompositeImageDescriptor) as well as a ready-made concrete subclass for loading images from files (FileImageDescriptor).

The class JFaceResources maintains global state on behalf of JFace itself consisting of JFace's own image registry, font registry, resource bundle, and preference store.
 

Package Specification

The packages defines and implements a viewer for text documents.

ITextViewer defines the concept of a document based, editiable viewer. ITextViewer offers the following functionality:

• present a document
• event consumption (IEventConsumer)
• viewport tracking and notification (IIViewportListener)
• change notification (ITextListener, ITextInputListener)
• listeners (combined view/model notification, input document)
• standard text editing functions plus text hover support
• visual region support

• IUndoManager for the undo/redo mechanism
• IDoubleClickStrategy for partition type specific behavior on mouse double click
• IAutoIndentStrategy  for content type specific behavior on inserting a line break
• ITextHover for content type specific behavior when overing over text

Package Specification

Package Specification

To set up a proper working text edit based content formatter, the following steps are needed:

• Create an instance of IFormattingContext. The default implementation FormattingContext already provides support for the conversion of preferences from a preference store to a map and vice versa. The method getPreferenceKeys usually has to be overridden to return the appropriate keys of the preferences used during the formatting process. Then register a map of preferences with the formatting context by calling setProperty(String, Object) with the property identifier FormattingContextProperties.CONTEXT_PREFERENCES.
• Create an instance of the text edit based content formatter class MultiPassContentFormatter. The document partitioning and its associated default content type have to be passed to the constructor. This information is needed since the content formatter is able to format documents according to arbitrary partitionings and default content types.
• Register the formatting strategies for the content types that have to be formatted. If a formatting strategy is registered as master strategy, it is automatically associated with the default content type of the specified partitioning. If the formatting strategy is registered as slave strategy, it is associated with the indicated content type during the registration. Note that the master strategy can also be registered as a slave strategy for a content type other than the default content type.
• Specify the proper formatting mode (see FormattingContextProperties):
  • For whole document formatting set the property CONTEXT_DOCUMENT of the created formatting context to true. This is equivalent to setting CONTEXT_REGION with a region spanning the whole document.
  • For multiple region formatting set the property CONTEXT_REGION of the formatting context. Note that the content formatter automatically aligns the offset of a region to a line start for the master formatting strategy, it also completes eventual partitions covered only partially by the region for the slave formatting strategies.
  • For explicit formatting of a partition with the formatting strategy registered for a certain content type use the property CONTEXT_PARTITION. Note that the region denoted by this property must correspond to a partition relative to the specified partitioning in the document to be formatted. The content type of this property overrides the content type of the partition in the document.
• Call the method MultiPassContentFormatter#format(IDocument, IFormattingContext) with the created formatting context and the document to be formatted.

SourceViewer supports hyperlinked text regions inline in the displayed text. It delegates the detection and presentation of hyperlinks to IHyperlinkDetector and IHyperlinkPresenter, respectively.

Override the following methods in SourceViewerConfiguration to customize the hyperlink behavior of a source viewer:

• getHyperlinkDetectors() to specify the set of hyperlink detectors used by the viewer
• getHyperlinkPresenter() to specify the set of hyperlink presenters used by the viewer
• getHyperlinkStateMask() to specify when hyperlinks are activated

Package Specification

Classes

• LinkedPositionGroup: a set of linked positions. Add positions to a group using the addPosition method. See LinkedPosition and ProposalPosition for a position type that lets one attach ICompletionProposals to be shown when the position is hit.
• LinkedModeModel: umbrellas several LinkedPositionGroups, e.g. in a template that has several groups of linked positions. Handles the forwarding of updates received via an IDocumentListener. Add LinkedPositionGroups to an model using the addGroup method. Existence of a LinkedModeModel can be tested by one of the static methods.
  
• LinkedModeUI: The UI for linked mode (for one model, to be precise). Monitors key etc. activity, monitors exit conditions, creates a painter etc.
  Properties:
  • cycling mode (whether to jump to the first position after the last): either of CYCLE_ALWAYS, CYCLE_NEVER and CYCLE_WHEN_NO_PARENT (default).
  • exit position: where to jump upon leaving the linked mode (e.g. using Enter, or Tab from the last position when not cycling). Set isTabStop to true if tabbing should stop over when cycling.
  • position listener: extending classes may register a position listener which will get notified whenever the focus position changes. An example is org.eclipse.ui.texteditor.link.EditorLinkedModeUI.EditorHistoryUpdater which will store the edit location in the editor navigation history.

Example

	IDocument doc1, doc2;
	ITextViewer viewer1, viewer2;

	/* create groups - this step is independent of the linked mode */
	LinkedPositionGroup group1= new LinkedPositionGroup();
	group1.addPosition(new LinkedPosition(doc1, 3, 4));
	group1.addPosition(new LinkedPosition(doc1, 7, 8));

	LinkedPositionGroup group2= new LinkedPositionGroup();
	group2.addPosition(new LinkedPosition(doc1, 15, 25));
	group2.addPosition(new LinkedPosition(doc2, 0, 10));

	/* set up linked mode */
	LinkedModeModel model= new LinkedModeModel();
	model.addGroup(group1);
	model.addGroup(group2);
	model.forceInstall();

	/* create UI */
	LinkedModeUI ui= new LinkedModeUI(model, new ITextViewer[] { viewer1, viewer2 });
	ui.enter();

Package Specification

A quick fix is a completion that can correct a problem reported and visible through an Annotation while a quick assist is not related to a problem or Annotation. Since quick assists can be proposed where appropriate they are normally not visible in the viewer. The quick assist assistant implementation in this package can show the quick assists that are available on the current line.

Package Specification

Package Specification

Package Specification

Package Specification

Package Specification

Packages

• org.eclipse.jface.text.templates
• org.eclipse.ui.workbench.texteditor.templates
• org.eclipse.ui.editors.templates

Introduction

if (${name} instanceof ${type}) {
    ${type} ${new_name} = (${type})${name};
    ${cursor}
}

Classes

• Template a template consists of name, context type identifier, and a pattern.
• TemplateTranslator and TemplateBuffer are used to parse the template grammar and don't need to be used usually.
• A TemplateProposal can be offered in content assist, possibly created by a subclass of TemplateCompletionProcessor.
• TemplateStore and ContextTypeRegistry manage a set of templates within a plug-in and offer ways to store them in the preferences or externally in XML streams via a TemplateReaderWriter.
  
• ContributionTemplateStore and ContributionContextTypeRegistry add awareness for the org.eclipse.ui.editors.templates extension point.
• TemplatePreferencePage allows the user to access the templates within a TemplateStore.

Example

Packages

• org.eclipse.jface.text.templates
• org.eclipse.ui.workbench.texteditor.templates
• org.eclipse.ui.editors.templates

Introduction

if (${name} instanceof ${type}) {
    ${type} ${new_name} = (${type})${name};
    ${cursor}
}

Classes

• Template a template consists of name, context type identifier, and a pattern.
• TemplateTranslator and TemplateBuffer are used to parse the template grammar and don't need to be used usually.
• A TemplateProposal can be offered in content assist, possibly created by a subclass of TemplateCompletionProcessor.
• TemplateStore and ContextTypeRegistry manage a set of templates within a plug-in and offer ways to store them in the preferences or externally in XML streams via a TemplateReaderWriter.
  
• ContributionTemplateStore and ContributionContextTypeRegistry add awareness for the org.eclipse.ui.editors.templates extension point.
• TemplatePreferencePage allows the user to access the templates within a TemplateStore.

Example

Package Specification

an input - the object that serves as the viewer's model

a widget - the SWT control through which the viewer's model is displayed

a content provider - mediates between the model and viewer

a label provider - maps model objects to displayable labels containing text and/or an image

In general terms, creating a viewer involves the following steps:

• instantiating a viewer on some pre-existing SWT widget,
• setting the viewer's content provider (an object implementing IContentProvider),
• setting the viewer's label provider (an object implementing ILabelProvider),
• and, finally, setting the viewer's input.

Note: None of the classes in this package maintain global state.
 

Package Specification

The deferred viewers are viewers that can handle concurrent updates from a variety of Threads.
 

Package Specification

This package also contains WindowManager, instance of which are used for managing a group of windows. Window managers are useful in applications which create many different windows (dialogs, wizards, etc.) in addition to a main window. Window managers are not required for simple applications.

The only global state maintained by classes in this package is a default image for window title bars (Window.setDefaultImage).

Package Specification

At the most abstract level, the protocol is given by 3 interfaces:

• IWizard - a wizard consisting of several wizard pages
• IWizardPage - an individual wizard page
• IWizardContainer - the outside world from the point of view of a wizard

Similarly, a wizard page is any object implementing IWizardPage. The abstract base class WizardPage is provided as a starting point. The main responsibility of a WizardPage subclass is providing the SWT controls and the backing logic for a single wizard page.

WizardDialog is a ready-to-use JFace dialog that is instantiated with a wizard and acts as the wizard's container. This dialog has a standard layout: an area at the top containing the wizard's title, description, and image; the actual wizard page appears in the middle; below it is a progress indicator; and at the bottom is an area with a message line and a button bar containing Next, Back, Finish, Cancel, and Help buttons.

WizardSelectionPage, a special abstract subclass of WizardPage, allows whole other wizards to be connected to a root page.

Note: None of the classes in this package maintain global state.