org.eclipse.jface.text
Class AbstractInformationControlManager

java.lang.Object
  |
  +--org.eclipse.jface.text.AbstractInformationControlManager

Direct Known Subclasses:

AbstractHoverInformationControlManager, InformationPresenter

public abstract class AbstractInformationControlManager

extends Object

Manages the life cycle, visibility, layout, and contents of an IInformationControl. This manager can be installed on and uninstalled from a control, refered to as the subject control, i.e. the one from which the subject of the information to be shown is retrieved. Also a manager can be enabled or disabled. An installed and enabled manager can be forced to show information in its information control using showInformation. An information control manager uses an IInformationControlCloser to define the behavior when a presented information control must be closed. The disposal of the subject and the information control are internally handled by the information control manager and are not the responsibility of the information control closer.

Since:

2.0

Nested Class Summary

static class	AbstractInformationControlManager.Anchor Constitues entities to enumerate anchors for the layout of the information control.
static interface	AbstractInformationControlManager.IInformationControlCloser Interface of a information control closer.

Field Summary

static AbstractInformationControlManager.Anchor	ANCHOR_BOTTOM Anchor representing the bottom of the information area
static AbstractInformationControlManager.Anchor	ANCHOR_LEFT Anchor representing the left side of the information area
static AbstractInformationControlManager.Anchor	ANCHOR_RIGHT Anchor representing the right side of the information area
static AbstractInformationControlManager.Anchor	ANCHOR_TOP Anchor representing the top of the information area

Constructor Summary

protected

AbstractInformationControlManager(IInformationControlCreator creator) Creates a new information control manager using the given information control creator.

Method Summary

protected abstract void	computeInformation() Computes the information to be displayed and the area in which the computed information is valid.
protected Point	computeInformationControlLocation(Rectangle subjectArea, Point controlSize) Computes the location of the information control depending on the subject area and the size of the information control.
protected Point	computeLocation(Rectangle subjectArea, Point controlSize, AbstractInformationControlManager.Anchor anchor) Computes the display location of the information control.
protected Point	computeSizeConstraints(Control subjectControl, IInformationControl informationControl) Computes the size constraints of the information control in points based on the default font of the given subject control as well as the size constraints in character width.
void	dispose() Disposes this manager and if necessary all dependent parts such as the information control.
void	disposeInformationControl() Disposes this manager's information control.
protected void	doShowInformation() Computes information to be displayed as well as the subject area and initiates that this information is presented in the information control.
protected IInformationControl	getInformationControl() Returns the information control.
protected AbstractInformationControlManager.Anchor	getNextFallbackAnchor(AbstractInformationControlManager.Anchor anchor) Returns the next fallback anchor from this manager's list of fallback anchors.
protected Rectangle	getSubjectArea() Returns the actual subject area.
protected Control	getSubjectControl() Returns the subject control of this manager/information control.
protected void	handleInformationControlDisposed() Handles the disposal of the information control.
protected void	handleSubjectControlDisposed() Handles the disposal of the subject control.
protected void	hideInformationControl() Hides the information control and stops the information control closer.
void	install(Control subjectControl) Installs this manager on the given control.
protected boolean	isEnabled() Returns whether this manager is enabled or not.
protected void	presentInformation() Presents the information in the information control or hides the information control if no information should be presented.
void	setAnchor(AbstractInformationControlManager.Anchor anchor) Sets the anchor used for laying out the information control relative to the subject control.
protected void	setCloser(AbstractInformationControlManager.IInformationControlCloser closer) Sets the information control closer for this manager.
void	setEnabled(boolean enabled) Deprecated. visibility will be changed to protected
void	setFallbackAnchors(AbstractInformationControlManager.Anchor[] fallbackAnchors) Sets the sequence of anchors along which the information control is tried to be laid out until it is fully visible.
protected void	setInformation(String information, Rectangle subjectArea) Sets the parameters of the information to be displayed.
void	setMargins(int xMargin, int yMargin) Sets the x- and y- margin to be used when laying out the information control relative to the subject control.
void	setSizeConstraints(int widthInChar, int heightInChar, boolean enforceAsMinimalSize, boolean enforceAsMaximalSize) Sets the width- and height constraints of the information control.
void	showInformation() Computes information to be displayed as well as the subject area and initiates that this information is presented in the information control.
protected void	showInformationControl(Rectangle subjectArea) Shows the information control and starts the information control closer.
void	takesFocusWhenVisible(boolean takesFocus) Tells the manager whether it should set the focus to the information control when made visible.
protected boolean	updateLocation(Point location, Point size, Rectangle displayArea, AbstractInformationControlManager.Anchor anchor) Checks whether a control of the given size at the given location would be completely visible in the given display area when laid out by using the given anchor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ANCHOR_TOP

public static final AbstractInformationControlManager.Anchor ANCHOR_TOP

Anchor representing the top of the information area

ANCHOR_BOTTOM

public static final AbstractInformationControlManager.Anchor ANCHOR_BOTTOM

Anchor representing the bottom of the information area

ANCHOR_LEFT

public static final AbstractInformationControlManager.Anchor ANCHOR_LEFT

Anchor representing the left side of the information area

ANCHOR_RIGHT

public static final AbstractInformationControlManager.Anchor ANCHOR_RIGHT

Anchor representing the right side of the information area

Constructor Detail

AbstractInformationControlManager

protected AbstractInformationControlManager(IInformationControlCreator creator)

Creates a new information control manager using the given information control creator. By default the following configuration is given:

• enabled == false
• x-margin == 5 points
• y-margin == 5 points
• width constraint == 60 characters
• height constraint == 6 characters
• enforce constraints as minimal size == false
• enforce constraints as maximal size == false
• layout anchor == ANCHOR_BOTTOM
• fallback anchors == { ANCHOR_TOP, ANCHOR_BOTTOM, ANCHOR_LEFT, ANCHOR_RIGHT }
• takes focus when visible == false

Parameters:

creator - the information control creator

Method Detail

computeInformation

protected abstract void computeInformation()

Computes the information to be displayed and the area in which the computed information is valid. Implementation of this method must finish their computation by setting the computation results using setInformation.

setInformation

protected final void setInformation(String information,
                                    Rectangle subjectArea)

Sets the parameters of the information to be displayed. These are the information itself and the area for which the given information is valid. This so called subject area is a graphical region of the information control's subject control. This method calls presentInformation() to trigger the presentation of the computed information.

Parameters:

information - the information

subjectArea - the subject area

setCloser

protected void setCloser(AbstractInformationControlManager.IInformationControlCloser closer)

Sets the information control closer for this manager.

Parameters:

closer - the information control closer for this manager

setMargins

public void setMargins(int xMargin,
                       int yMargin)

Sets the x- and y- margin to be used when laying out the information control relative to the subject control.

Parameters:

xMargin - the x-margin

yMargin - the y-Margin

setSizeConstraints

public void setSizeConstraints(int widthInChar,
                               int heightInChar,
                               boolean enforceAsMinimalSize,
                               boolean enforceAsMaximalSize)

Sets the width- and height constraints of the information control.

Parameters:

widthInChar - the width constraint in number of characters

heightInChar - the height constrain in number of characters

enforceAsMinimalSize - indicates whether the constraints describe the minimal allowed size of the control

enforceAsMaximalSize - indicates whether the constraints describe the maximal allowed size of the control

setAnchor

public void setAnchor(AbstractInformationControlManager.Anchor anchor)

Sets the anchor used for laying out the information control relative to the subject control. E.g, using ANCHOR_TOP indicates that the information control is position above the area for which the information to be displayed is valid.

Parameters:

anchor - the layout anchor

setFallbackAnchors

public void setFallbackAnchors(AbstractInformationControlManager.Anchor[] fallbackAnchors)

Sets the sequence of anchors along which the information control is tried to be laid out until it is fully visible. This fallback is initiated when the information control does not fit into the client area of the subject control's display.

Parameters:

fallbackAnchors - the list of anchors to be tried

takesFocusWhenVisible

public void takesFocusWhenVisible(boolean takesFocus)

Tells the manager whether it should set the focus to the information control when made visible.

Parameters:

takesFocus - true if information control should take focus when made visible

handleSubjectControlDisposed

protected void handleSubjectControlDisposed()

Handles the disposal of the subject control. By default, the information control is disposed by calling disposeInformationControl. Subclasses may extend this method.

install

public void install(Control subjectControl)

Installs this manager on the given control. The control is now taking the role of the subject control. This implementation sets the control also as the information control closer's subject control and automatically enables this manager.

Parameters:

subjectControl - the subject control

getSubjectControl

protected Control getSubjectControl()

Returns the subject control of this manager/information control.

Returns:

the subject control

getSubjectArea

protected Rectangle getSubjectArea()

Returns the actual subject area.

Returns:

the actual subject area

setEnabled

public void setEnabled(boolean enabled)

Deprecated. visibility will be changed to protected

Sets the enable state of this manager.

Parameters:

enabled - the enable state

isEnabled

protected boolean isEnabled()

Returns whether this manager is enabled or not.

Returns:

true if this manager is enabled otherwise false

computeSizeConstraints

protected Point computeSizeConstraints(Control subjectControl,
                                       IInformationControl informationControl)

Computes the size constraints of the information control in points based on the default font of the given subject control as well as the size constraints in character width.

Parameters:

subjectControl - the subject control

informationControl - the information control whose size constraints are computed

Returns:

the computed size constraints in points

handleInformationControlDisposed

protected void handleInformationControlDisposed()

Handles the disposal of the information control. By default, the information control closer is stopped.

getInformationControl

protected IInformationControl getInformationControl()

Returns the information control. If the information control has not been created yet, it is automatically created.

Returns:

the information control

computeLocation

protected Point computeLocation(Rectangle subjectArea,
                                Point controlSize,
                                AbstractInformationControlManager.Anchor anchor)

Computes the display location of the information control. The location is computed considering the given subject area, the anchor at the subject area, and the size of the information control. This method does not care about whether the information control would be completely visible when placed at the result location.

Parameters:

subjectArea - the subject area

controlSize - the size of the information control

anchor - the anchor at the subject area

updateLocation

protected boolean updateLocation(Point location,
                                 Point size,
                                 Rectangle displayArea,
                                 AbstractInformationControlManager.Anchor anchor)

Checks whether a control of the given size at the given location would be completely visible in the given display area when laid out by using the given anchor. If not, this method tries to shift the control orthogonal to the direction given by the anchor to make it visible. If possible it updates the location.

This method returns true if the potentially updated position results in a completely visible control, or false otherwise.

Parameters:

location - the location of the control

size - the size of the control

displayArea - the display area in which the control should be visible

anchor - anchor for alying out the control

Returns:

trueif the updated location is useful

getNextFallbackAnchor

protected AbstractInformationControlManager.Anchor getNextFallbackAnchor(AbstractInformationControlManager.Anchor anchor)

Returns the next fallback anchor from this manager's list of fallback anchors. If no more fallback anchor is available null is returned.

Parameters:

anchor - the current anchor

Returns:

the next fallback anchor or null if no more anchor is available

computeInformationControlLocation

protected Point computeInformationControlLocation(Rectangle subjectArea,
                                                  Point controlSize)

Computes the location of the information control depending on the subject area and the size of the information control. This method attempts to find a location at which the information control lies completely in the display's client area honoring the manager's default anchor. If this isn't possible using the default anchor, the fallback anchors are tried out.

Parameters:

subjectArea - the information area

controlSize - the size of the information control

Returns:

the computed location of the information control

showInformation

public void showInformation()

Computes information to be displayed as well as the subject area and initiates that this information is presented in the information control. This happens only if this controller is enabled.

doShowInformation

protected void doShowInformation()

Computes information to be displayed as well as the subject area and initiates that this information is presented in the information control.

presentInformation

protected void presentInformation()

Presents the information in the information control or hides the information control if no information should be presented. The information has previously been set using setInformation.

hideInformationControl

protected void hideInformationControl()

Hides the information control and stops the information control closer.

showInformationControl

protected void showInformationControl(Rectangle subjectArea)

Shows the information control and starts the information control closer. This method may not be called by clients.

Parameters:

subjectArea - the information area

disposeInformationControl

public void disposeInformationControl()

Disposes this manager's information control.

dispose

public void dispose()

Disposes this manager and if necessary all dependent parts such as the information control. For symmetry it first disables this manager.