001/* [{
002Copyright 2007, 2008, 2009 Nicolas Carranza <nicarran at gmail.com>
003
004This file is part of jpen.
005
006jpen is free software: you can redistribute it and/or modify
007it under the terms of the GNU Lesser General Public License as published by
008the Free Software Foundation, either version 3 of the License,
009or (at your option) any later version.
010
011jpen is distributed in the hope that it will be useful,
012but WITHOUT ANY WARRANTY; without even the implied warranty of
013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
014GNU Lesser General Public License for more details.
015
016You should have received a copy of the GNU Lesser General Public License
017along with jpen.  If not, see <http://www.gnu.org/licenses/>.
018}] */
019package jpen.owner;
020
021import java.util.Collection;
022import jpen.owner.PenClip;
023import jpen.PenEvent;
024import jpen.PenManager;
025import jpen.PenProvider;
026
027/**
028A PenOwner defines the available {@link PenProvider}s and unpauses/pauses the {@link PenManager} whenever the mouse cursor enters/exits the {@link PenClip}. The PenOwner allows drag-out operation.
029*/
030public interface PenOwner{
031        /**
032        Called once by the {@link PenManager#PenManager(PenOwner)} constructor to get the available {@link jpen.PenProvider.Constructor}s and use them to setup the {@link PenProvider}s.
033        */
034        Collection<PenProvider.Constructor> getPenProviderConstructors();
035
036        /**
037        Called once by the {@link PenManager#PenManager(PenOwner)} constructor to allow this PenOwner to access the PenManager through the given {@link PenManagerHandle}.
038        */
039        void setPenManagerHandle(PenManagerHandle penManagerHandle);
040
041        /**
042        Wraps a {@link PenManager} and defines extra accessor methods. See {@link #setPenManagerHandle(PenManagerHandle)}.
043        */
044        public interface PenManagerHandle{
045                PenManager getPenManager();
046                /**
047                @return synchronization lock held by the {@link PenManager} when calling {@link #isDraggingOut()}.
048                */
049                Object getPenSchedulerLock();
050                /**
051                Unpause/pause the scheduling of {@link jpen.PenEvent}s done by the {@link PenManager}'s {@link PenProvider}s.
052                */
053                void setPenManagerPaused(boolean paused);
054
055                /**
056                Retrieve the tag stored on the given {@code PenEvent}. See {@link #evalPenEventTag(PenEvent)}.
057                */
058                Object retrievePenEventTag(PenEvent ev);
059        }
060
061        /**
062        @return The PenClip associated with this PenOwner.
063        */
064        PenClip getPenClip();
065
066        /**
067        Called by the {@link PenManager} to avoid sending {@link jpen.PLevelEvent}s to clients when the location is outside the PenClip and this method returns {@code false}. The PenManager calls this method holding the {@link PenManagerHandle#getPenSchedulerLock()} synchronization lock.
068
069        @return {@code true} if this PenOwner is currently in a drag-out operation.
070        */
071        boolean isDraggingOut();
072
073        /**
074        This method is called by the {@code PenManager}'s machinary when creating a {@code PenEvent}. This method returns a tag to be stored on the given {@code PenEvent} or {@code null} if no tagging is needed  (the {@code PenManager} machinary stores this tag on the private {@code PenEvent}'s {@code penOwnerTag} field ). The tag can be later retrieved using {@link PenManagerHandle#retrievePenEventTag(PenEvent)}. 
075        */
076        Object evalPenEventTag(PenEvent ev);
077
078        /**
079        @return {@code true} if you want to allow only one {@code PenManager} per JVM---attempting to create more than one {@code PenManager} instance will cause an IllegalStateException to be thrown by the PenManager's constructor. 
080        */
081        boolean enforceSinglePenManager();
082}