|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface DockStation
A DockStation
is some area (e.g. a Component
) showing
a set of Dockable
s called "children". The station is free to decide how and if to
show its children.
Although a station can take any form, there are some (optional) practices to follow:
Dockable
should be child of a DockableDisplayer
. The displayer will
paint border and title of the item.DockTheme
and use its factories and delegates whenever possible.DockController
. Methods like canDrag(Dockable)
, drag(Dockable)
,
prepareDrop(StationDropItem)
need to be implemented for this. Also accept(Dockable)
, Dockable.accept(DockStation)
,
Dockable.accept(DockStation, Dockable)
and the DockAcceptance
of the current DockController
should be checked before
allowing a drag and drop operation.DockTitle
. This station needs to derive a DockTitleVersion
from
its controller using the DockTitleManager
and its
factory method
. With the DockTitleVersion
-object one
DockTitleRequest
for each required DockTitle
can be created.DockController.setAtLeastFocusedDockable(Dockable, Component)
.PlaceholderStrategy
can be used to convert Dockable
s to placeholders.
A PlaceholderList
is a good datastructure to store Dockable
s and placeholders at the same time.DockElementRepresentative
. It
has to be installed using DockController.addRepresentative(DockElementRepresentative)
. DockFactory
will be required to persistently store the layout of this station.
Method Summary | |
---|---|
boolean |
accept(Dockable child)
Tells whether this station accepts child as a new child,
or refuses child . |
void |
addDockStationListener(DockStationListener listener)
Adds a listener to this station. |
boolean |
canDrag(Dockable dockable)
Tells whether dockable can be removed from this station or not. |
boolean |
canReplace(Dockable old,
Dockable next)
Tells whether its possible to replace the child old
with next where next is not a child of this station. |
void |
changed(Dockable dockable,
DockTitle title,
boolean active)
Called by the DockController of this station to indicate that
the active-state of title has been changed. |
void |
drag(Dockable dockable)
Removes a child from this station. |
void |
drop(Dockable dockable)
Adds dockable to this station. |
boolean |
drop(Dockable dockable,
DockableProperty property)
Tries to add dockable to this station such that the location
given by property is matched. |
DockController |
getController()
Gets the controller of this station. |
DockActionSource |
getDirectActionOffers(Dockable dockable)
Gets a list of actions which should be available for the user and affect the child dockable . |
Dockable |
getDockable(int index)
Gets the index'th child of this station. |
int |
getDockableCount()
Gets the number of children. |
DockableProperty |
getDockableProperty(Dockable child,
Dockable target)
Gets precise information about the location of a child of this station. |
Dockable |
getFrontDockable()
Gets the favorite child of this station. |
DockActionSource |
getIndirectActionOffers(Dockable dockable)
Gets a list of actions which should be available for the user and affect dockable . |
DockStationDropLayer[] |
getLayers()
Gets a description of all the areas of the screen where this DockStation can handle a drop event.Everytime the mouse is moved or released during a drag & drop operation, this method is called for all DockStation s. |
PlaceholderMap |
getPlaceholders()
Gets a snapshot of all placeholders that are currently stored in this DockStation . |
DockTheme |
getTheme()
Gets the current theme of this station. |
boolean |
isChildShowing(Dockable dockable)
Tells whether the child dockable is visible or not. |
boolean |
isStationShowing()
Tells whether this station is visible or not. |
boolean |
isStationVisible()
Deprecated. use isStationShowing() instead, this method will be removed in a future release |
boolean |
isVisible(Dockable dockable)
Deprecated. use isChildShowing(Dockable) instead, this method will be removed in a future release |
void |
move(Dockable dockable,
DockableProperty property)
Tries to move the child dockable in such a way, that
getDockableProperty(Dockable, Dockable) would return a
DockableProperty that equals property .There is no need to give a guarantee that the move successes, and clients should always be prepared for the possibility that this DockStation
does nothing at all. |
StationDragOperation |
prepareDrag(Dockable dockable)
Informs this station that a drag and drop operation is in progress and that dockable might
be removed from this station. |
StationDropOperation |
prepareDrop(StationDropItem dockable)
Prepares this station to get the new child dockable or to move around the known child dockable . |
void |
removeDockStationListener(DockStationListener listener)
Removes a listener from this station. |
void |
replace(Dockable old,
Dockable next)
Replaces the child old by next which is
not yet a child of this station. |
void |
replace(DockStation old,
Dockable next)
Replaces the child old by next which is
not yet a child of this station. |
void |
requestChildDisplayer(DisplayerRequest request)
Provides a DockableDisplayer for a child of this station. |
void |
requestChildDockTitle(DockTitleRequest request)
Provides a DockTitle for a child of this station. |
void |
setController(DockController controller)
Sets the controller of this station. |
void |
setFrontDockable(Dockable dockable)
Sets the most important child. |
void |
setPlaceholders(PlaceholderMap placeholders)
Sets an earlier snapshot of the placeholders of this station. |
void |
updateTheme()
Updates the DockTheme of this station. |
Methods inherited from interface bibliothek.gui.dock.DockElement |
---|
asDockable, asDockStation, getFactoryID |
Method Detail |
---|
void setController(DockController controller)
DockTitle
, then the titles have to be replaced
by new instances (assuming the controller is really new). The
title has to get new DockTitleVersions
through
the DockTitleManager
of controller
.null
means that this station is currently
not shown.
controller
- the owner of this station, can be null
DockController getController()
getController
in interface DockElement
null
if no controller is setsetController(DockController)
void updateTheme()
DockTheme
of this station. The new theme
has to be read from the controller
of
this station. If the controller is null
, this method
should return immediately.DockUI.updateTheme(DockStation, DockFactory)
to implement this method.
DockTheme getTheme()
null
,
but that means that the station is not fully initialized, and might not
work correct.
null
.DockActionSource getDirectActionOffers(Dockable dockable)
dockable
.
dockable
- a child of this station
dockable
, can be null
DockActionSource getIndirectActionOffers(Dockable dockable)
dockable
. The argument dockable
can be a child of this station, or a child of any station which is
below this station.
dockable
- a child of this station or a child of another station
which is below this station
dockable
or null
void addDockStationListener(DockStationListener listener)
listener
- the listener to addvoid removeDockStationListener(DockStationListener listener)
listener
- the listener to remove@Todo(compatibility=BREAK_MAJOR, priority=ENHANCEMENT, target=VERSION_1_1_3, description="remove this method") @Deprecated boolean isVisible(Dockable dockable)
isChildShowing(Dockable)
instead, this method will be removed in a future release
dockable
is visible or not. Visible
means that the component
of dockable
can be seen by the user. The result must be false
if
this station is not visible.
dockable
- the child whose visibility-state is questioned
dockable
is visible or notisStationVisible()
boolean isChildShowing(Dockable dockable)
dockable
is visible or not. Visible
means that the component
of dockable
can be seen by the user. The result must be false
if
this station is not visible.
dockable
- the child whose visibility-state is questioned
dockable
is visible or notisStationVisible()
@Deprecated @Todo(compatibility=BREAK_MAJOR, priority=ENHANCEMENT, target=VERSION_1_1_3, description="remove this method") boolean isStationVisible()
isStationShowing()
instead, this method will be removed in a future release
JFrame
is not visible if the frame is minimized.
boolean isStationShowing()
JFrame
is not visible if the frame is minimized.
int getDockableCount()
Dockable getDockable(int index)
index
- a value between 0 (incl.) and getDockableCount()
(excl.).
Dockable getFrontDockable()
null
indicates that there are no children
at all, or that there is no favorite child (all children are equal important).DockController.setFocusedDockable(Dockable, boolean)
which will then call setFrontDockable(Dockable)
. Note that the
DockController itself listens to the DockTitles, and maybe the station
doesn't need a logic to decide which child is important.
null
void setFrontDockable(Dockable dockable)
getFrontDockable()
how stations can change
this property.
dockable
- the new favorite child, can be null
getFrontDockable()
PlaceholderMap getPlaceholders()
DockStation
.
A DockStation
is free in the format it chooses to fill the map. The map is to be
created with the assumptions that getDockableCount()
is 0
, meaning
any existing Dockable
gets replaced by its placeholder. The current
PlaceholderStrategy
should be used to convert Dockable
s to placeholders.
null
if this station does not support
placeholdersvoid setPlaceholders(PlaceholderMap placeholders)
getDockableCount()
is 0
).placeholders
.
placeholders
- some set of placeholders
IllegalStateException
- if getDockableCount()
is not equal to 0
void changed(Dockable dockable, DockTitle title, boolean active)
DockController
of this station to indicate that
the active-state of title
has been changed. This station
should call the method title.changed
with an appropriate event. The station may add some additional information
to this call.
dockable
- the child whose title is changedtitle
- the changed title, may not be boundactive
- the new state of the titlevoid requestChildDockTitle(DockTitleRequest request)
DockTitle
for a child of this station. This method
must call DockTitleRequest.answer(DockTitle)
to set the result.DockStation
s won't have the need to implement this method,
leaving it empty will advice the framework to use another source for
new DockTitle
s.
request
- the request to answer, not null
void requestChildDisplayer(DisplayerRequest request)
DockableDisplayer
for a child of this station. This method
must call DisplayerRequest.answer(DockableDisplayer)
to set the result.
request
- the request to answer, not null
boolean accept(Dockable child)
child
as a new child,
or refuses child
. The user will not be able to drop
a Dockable
onto this station if this method returns
false
.
child
- a Dockable
which may become a child
true
if child
is acceptedDockableProperty getDockableProperty(Dockable child, Dockable target)
drop(Dockable, DockableProperty)
.
child
- a child of this station, this childs location is askedtarget
- an optional hint telling for which dockable the location information
will be used, can be null
. This hint can be used to find a placeholder
that should be part of the result.
DockUtilities.getPropertyChain(DockStation, Dockable)
StationDropOperation prepareDrop(StationDropItem dockable)
dockable
or to move around the known child dockable
.
The station can refuse dockable
, in this case this method just returns null
.
There are some constraints:
accept(Dockable)
and Dockable.accept(DockStation)
or Dockable.accept(DockStation, Dockable)
to ensure that the desired
drop-location is valid.DockAcceptance
of its controller
(see DockController.getAcceptance()
) to ensure that the drop/location is valid.
dockable
- information about the dockable that is going to be dropped
Dockable
can be dropped or null
if
no drop operation is possibleStationDragOperation prepareDrag(Dockable dockable)
dockable
might
be removed from this station.
dockable
- the child that might be removed in the near future
null
void drop(Dockable dockable)
dockable
to this station. The station can decide
by its own where to put dockable
.
dockable
- a new childboolean drop(Dockable dockable, DockableProperty property)
dockable
to this station such that the location
given by property
is matched. If property
has a successor
and points to
another station, just call the drop
-method of this
child-station. Note that property
can be of any type and
contain invalid information.
dockable
- the new childproperty
- the location of the child, may be invalid data
true
if property
could be read
and dockable
was dropped, false
otherwise.void move(Dockable dockable, DockableProperty property)
dockable
in such a way, that
getDockableProperty(Dockable, Dockable)
would return a
DockableProperty
that equals property
.DockStation
does nothing at all.
dockable
- a child of this stationproperty
- the preferred position of dockable
DockStationDropLayer[] getLayers()
DockStation
can handle a drop event.DockStation
s. The returned DockStationDropLayer
s are then filtered and ordered, the resulting
order defines the order in which the method prepareDrop(StationDropItem)
is called.
null
, must not contain null
,
must not contain the same entry twice. The array or the DockStationDropLayer
s may be modified,
hence this method should always create new objects.boolean canDrag(Dockable dockable)
dockable
can be removed from this station or not.
This method assumes that dockable
is a child of
this station, if not, then the behavior of this method is unspecified.
dockable
- a child of this station
true
if dockable
can be draggedvoid drag(Dockable dockable)
canDrag(Dockable)
returned false
.DockController.freezeLayout()
and DockController.meltLayout()
to ensure noone else adds or
removes Dockable
s.
dockable
- the child to removeboolean canReplace(Dockable old, Dockable next)
old
with next
where next is not a child of this station.
old
- a child of this stationnext
- the replacement of next
.
true
if the replacement is possible
IllegalArgumentException
- if next
is a child
of this stationvoid replace(Dockable old, Dockable next)
old
by next
which is
not yet a child of this station. This method should not be
called if canReplace
returned
false
.
old
- a childnext
- the replacement of old
IllegalArgumentException
- if next
is a child of
this station or if old
is not a childvoid replace(DockStation old, Dockable next)
old
by next
which is
not yet a child of this station. This method should not be
called if canReplace
returned
false
. This method can assume that next
was
a child of old
but no longer is.
old
- a dockable station that is a child of this stationnext
- the replacement of old
IllegalArgumentException
- if next
is a child of
this station, if old
is not a child or if old
is not a Dockable
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |