bundles/org.simantics.g2d/src/org/simantics/g2d/canvas/impl/AbstractCanvasParticipant.java

   1 /*******************************************************************************\r
   2  * Copyright (c) 2007, 2010 Association for Decentralized Information Management\r
   3  * in Industry THTH ry.\r
   4  * All rights reserved. This program and the accompanying materials\r
   5  * are made available under the terms of the Eclipse Public License v1.0\r
   6  * which accompanies this distribution, and is available at\r
   7  * http://www.eclipse.org/legal/epl-v10.html\r
   8  *\r
   9  * Contributors:\r
  10  *     VTT Technical Research Centre of Finland - initial API and implementation\r
  11  *******************************************************************************/\r
  12 package org.simantics.g2d.canvas.impl;\r
  13 \r
  14 import java.lang.reflect.Field;\r
  15 \r
  16 import org.simantics.g2d.canvas.ICanvasContext;\r
  17 import org.simantics.g2d.canvas.ICanvasParticipant;\r
  18 import org.simantics.g2d.canvas.IContentContext;\r
  19 import org.simantics.g2d.canvas.impl.DependencyReflection.ReferenceDefinition;\r
  20 import org.simantics.g2d.canvas.impl.DependencyReflection.ReferenceType;\r
  21 import org.simantics.g2d.canvas.impl.HintReflection.HintListenerDefinition;\r
  22 import org.simantics.g2d.canvas.impl.SGNodeReflection.CanvasSGNodeDefinition;\r
  23 import org.simantics.scenegraph.g2d.events.EventHandlerReflection;\r
  24 import org.simantics.scenegraph.g2d.events.IEventHandler;\r
  25 import org.simantics.scenegraph.g2d.events.EventHandlerReflection.EventHandlerDefinition;\r
  26 import org.simantics.utils.datastructures.context.IContext;\r
  27 import org.simantics.utils.datastructures.context.IContextListener;\r
  28 import org.simantics.utils.datastructures.hints.HintContext;\r
  29 import org.simantics.utils.datastructures.hints.IHintContext;\r
  30 import org.simantics.utils.datastructures.hints.IHintStack;\r
  31 import org.simantics.utils.datastructures.hints.IHintContext.Key;\r
  32 import org.simantics.utils.datastructures.prioritystack.IPriorityStack;\r
  33 import org.simantics.utils.threads.IThreadWorkQueue;\r
  34 import org.simantics.utils.threads.ThreadUtils;\r
  35 \r
  36 \r
  37 /**\r
  38  * AbstractCanvasParticipant is base implementation for canvas participants.\r
  39  * There is an assertion that states AbstractCanvasParticipant can be added\r
  40  * only once to a canvas.\r
  41  * \r
  42  * <p>\r
  43  * There is convenience mechanism for adding painter and event handler\r
  44  * listeners. Subclasses create listeners with usage of Painter and\r
  45  * EventHandler annotations. Listeners are automatically added and\r
  46  * removed to/from canvas context.\r
  47  * </p>\r
  48  * \r
  49  * <p>\r
  50  * Example:\r
  51  * </p>\r
  52  * <blockquote><pre>\r
  53  *   @EventHandler(priority=200)\r
  54  *   public boolean handleEvent(Event e) {\r
  55  *       return false;\r
  56  *   }\r
  57  * \r
  58  *   @EventHandler(priority=400)\r
  59  *   public boolean handleMousePressEvent(MouseButtonPressedEvent e) {\r
  60  *       return false;\r
  61  *   }\r
  62  * \r
  63  *   IG2DNode node;\r
  64  * \r
  65  *   @SGInit\r
  66  *   public void initSG(G2DParentNode parent) {\r
  67  *       // Insert a node into the scene graph rendered by the canvas\r
  68  *       // this participant is attached to and initialize it to render\r
  69  *       // something. Later on, to modify what the node will render, just\r
  70  *       // update the node's attributes.\r
  71  *       node = parent.addNode("myNode", MyNode.class);\r
  72  *       node.setZIndex(Integer.MIN_VALUE);\r
  73  *   }\r
  74  * \r
  75  *   @SGCleanup\r
  76  *   public void cleanup() {\r
  77  *       // Remove our node from the scene graph where it belonged.\r
  78  *       // The node must not be used after this anymore.\r
  79  *       if (node != null) {\r
  80  *           node.remove();\r
  81  *           node = null;\r
  82  *       }\r
  83  *   }\r
  84  * </pre></blockquote>\r
  85  * \r
  86  * <p>\r
  87  * Local fields are automatically assigned with ICanvasParticipant instances if they\r
  88  * are annotated with either <code>@Dependency</code> or <code>@Reference</code> annotation tag.\r
  89  * <code>@Depedency</code> is a requirement, <code>@Reference</code> is optional.\r
  90  * \r
  91  * assertDependencies() verifies that dependencies are satisfied.\r
  92  * Local depsSatisfied field is true when dependencies are satisfied.\r
  93  * \r
  94  * <p>\r
  95  * Example:\r
  96  * </p>\r
  97  * <blockquote><pre>\r
  98  *   class MyParticipant implements ICanvasParticipant {\r
  99  *       @Reference MouseMonitor mouseMonitor;\r
 100  *       @Dependency TimeParticipant timeParticipant;\r
 101  *\r
 102  *       @Painter(priority=100)\r
 103  *       public void paint(GraphicsContext gc) {\r
 104  *           assertDependencies(); // timeParticipant != null\r
 105  * \r
 106  *           timeParticipant.doSomething();\r
 107  * \r
 108  *           if (mouseMonitor!=null) doSomethingElse();\r
 109  *       }\r
 110  *   }</pre></blockquote>\r
 111  * \r
 112  * <p>\r
 113  * Hint listener annotation.\r
 114  * </p>\r
 115  * \r
 116  * <p>\r
 117  * Example:\r
 118  * </p>\r
 119  * <blockquote><pre>\r
 120  *   @HintListener(Class=Hints.class, Field="KEY_CANVAS_TRANSFORM")\r
 121  *   public void hintChanged(IHintObservable sender, Key key, Object oldValue, Object newValue) {\r
 122  *       ...\r
 123  *   }\r
 124  *   @HintListener(Class=Hints.class, Field="KEY_CANVAS_TRANSFORM")\r
 125  *   public void hintRemoved(IHintObservable sender, Key key, Object oldValue) {\r
 126  *       ...\r
 127  *   }\r
 128  * </pre></blockquote>\r
 129  * \r
 130  * @author Toni Kalajainen\r
 131  */\r
 132 public abstract class AbstractCanvasParticipant implements ICanvasParticipant {\r
 133 \r
 134     /** The interactor/canvas context */\r
 135     private ICanvasContext context;\r
 136 \r
 137     /** The thread used in the context */\r
 138     private IThreadWorkQueue thread;\r
 139 \r
 140     /** the local hint context */\r
 141     protected IHintContext localHintCtx = null;\r
 142     protected int localPriority = 0;\r
 143 \r
 144     /** wrapped local hint context. reads from hint stack */\r
 145     protected IHintContext hintCtx = null;\r
 146 \r
 147     /** Cached hint stack value */\r
 148     protected IHintStack hintStack;\r
 149 \r
 150     /** Painters found with reflection */\r
 151     protected CanvasSGNodeDefinition[] sghandlers;\r
 152 \r
 153     /** Painters found with reflection */\r
 154     protected EventHandlerDefinition[] eventHandlers;\r
 155 \r
 156     protected HintListenerDefinition[] hintListeners;\r
 157 \r
 158     /** Reference definitions */\r
 159     protected ReferenceDefinition[] refDefs;\r
 160     protected boolean depsSatisfied = false;\r
 161     private final IContextListener<ICanvasParticipant> ctxListener =\r
 162         new IContextListener<ICanvasParticipant>() {\r
 163         @Override\r
 164         public void itemAdded(IContext<ICanvasParticipant> sender, ICanvasParticipant item) {\r
 165             _itemAdded(sender, item);\r
 166             if (!depsSatisfied) depsSatisfied = checkDependencies();\r
 167         }\r
 168         @Override\r
 169         public void itemRemoved(IContext<ICanvasParticipant> sender, ICanvasParticipant item) {\r
 170             _itemRemoved(sender, item);\r
 171             AbstractCanvasParticipant.this.depsSatisfied = depsSatisfied;\r
 172         }\r
 173     };\r
 174     @SuppressWarnings("unchecked")\r
 175     private void _itemAdded(IContext<ICanvasParticipant> sender, ICanvasParticipant item)\r
 176     {\r
 177         // This code handles @Dependency annotation\r
 178         // Synchronizing because the calling thread may be anything\r
 179         synchronized ( ctxListener ) {\r
 180                 Class<ICanvasParticipant> c = (Class<ICanvasParticipant>) item.getClass();\r
 181                 try {\r
 182                     for (ReferenceDefinition def : refDefs)\r
 183                     {\r
 184                         Class<?>        defClass = def.requirement;\r
 185                         if (!defClass.isAssignableFrom(c)) continue;\r
 186                         Field   f = def.field;\r
 187                         Object  value = f.get(AbstractCanvasParticipant.this);\r
 188                         assert(value==null);\r
 189                         f.set(AbstractCanvasParticipant.this, item);\r
 190                     }\r
 191                 } catch (Exception e) {\r
 192                     throw new RuntimeException(e);\r
 193                 }\r
 194         }\r
 195     }\r
 196     @SuppressWarnings("unchecked")\r
 197     private void _itemRemoved(IContext<ICanvasParticipant> sender, ICanvasParticipant item)\r
 198     {\r
 199         synchronized ( ctxListener ) {          \r
 200                 Class<ICanvasParticipant> c = (Class<ICanvasParticipant>) item.getClass();\r
 201                 //boolean depsSatisfied = true;\r
 202                 try {\r
 203                     for (ReferenceDefinition def : refDefs)\r
 204                     {\r
 205                         Class<?>        defClass = def.requirement;\r
 206                         Field   f = def.field;\r
 207                         //Object        value = f.get(AbstractCanvasParticipant.this);\r
 208                         if (defClass.isAssignableFrom(c)) {\r
 209                             //value = null;\r
 210                             f.set(AbstractCanvasParticipant.this, null);\r
 211                         }\r
 212                         //depsSatisfied &= !def.dependency || value!=null;\r
 213                     }\r
 214                 } catch (Exception e) {\r
 215                     throw new RuntimeException(e);\r
 216                 }\r
 217         }\r
 218     }\r
 219 \r
 220     /**\r
 221      * AbstractInteractor adds itself to the context set in the constructor\r
 222      * argument.\r
 223      * \r
 224      * The constructor creates hint constructor and adds it into the context\r
 225      * with priority value Integer.MIN_VALUE. Generally, base service interactors\r
 226      * only read hints. Those hints are usually overrideable and thus the default\r
 227      * hint context priority is as small value as possible. Use this constructor for\r
 228      * BASE SERVICE interactors that only read values.\r
 229      * \r
 230      * @param ctx\r
 231      */\r
 232     public AbstractCanvasParticipant()\r
 233     {\r
 234         sghandlers = SGNodeReflection.getSGHandlers(this);\r
 235         eventHandlers = EventHandlerReflection.getEventHandlers(this);\r
 236         refDefs = DependencyReflection.getDependencies(this, ReferenceType.CanvasParticipant);\r
 237         hintListeners = HintReflection.getDependencies(this);\r
 238         if (refDefs.length==0) depsSatisfied = true;\r
 239     }\r
 240 \r
 241     @Override\r
 242     public void addedToContext(ICanvasContext ctx)\r
 243     {\r
 244         assert(ctx!=null);\r
 245         assert(context==null);\r
 246         this.context = ctx;\r
 247         this.hintStack = ctx.getHintStack();\r
 248         this.thread = ctx.getThreadAccess();\r
 249 \r
 250         // Add event handlers\r
 251         IPriorityStack<IEventHandler> eventHandlerStack = getContext().getEventHandlerStack();\r
 252         for (EventHandlerDefinition eventHandler : eventHandlers)\r
 253             eventHandlerStack.add(eventHandler.eventHandler, eventHandler.priority);\r
 254 \r
 255         // Fill References & Monitor for changes\r
 256         if (refDefs.length!=0) {\r
 257             getContext().addContextListener(ctxListener);\r
 258             for (ICanvasParticipant cp : getContext().toArray())\r
 259                 _itemAdded(getContext(), cp);\r
 260             depsSatisfied = checkDependencies();\r
 261         }\r
 262 \r
 263         // Add hint reflections\r
 264         IHintStack stack = getContext().getHintStack();\r
 265         IThreadWorkQueue thread = getContext().getThreadAccess();\r
 266         for (HintListenerDefinition def : hintListeners)\r
 267             stack.addKeyHintListener(thread, def.key, def);\r
 268 \r
 269 \r
 270         // Create SceneGraph nodes\r
 271         for (CanvasSGNodeDefinition sg : sghandlers) {\r
 272             if (sg.initDesignation != null) {\r
 273                 switch (sg.initDesignation) {\r
 274                     case CONTROL:\r
 275                         sg.init(ctx.getSceneGraph());\r
 276                         break;\r
 277                     case CANVAS:\r
 278                         sg.init(ctx.getCanvasNode());\r
 279                         break;\r
 280                 }\r
 281             }\r
 282         }\r
 283     }\r
 284 \r
 285     @Override\r
 286     public void removedFromContext(ICanvasContext ctx)\r
 287     {\r
 288         assert(ctx!=null);\r
 289         if (context==null)\r
 290             throw new RuntimeException("Interactor was not in any context");\r
 291 \r
 292         // Remove context listener\r
 293         if (refDefs.length!=0) {\r
 294             getContext().removeContextListener(ctxListener);\r
 295         }\r
 296 \r
 297         // Clean up SceneGraph nodes\r
 298         for (CanvasSGNodeDefinition sg : sghandlers) {\r
 299             sg.cleanup();\r
 300         }\r
 301 \r
 302         IPriorityStack<IEventHandler> eventHandlerStack = context.getEventHandlerStack();\r
 303         for (EventHandlerDefinition eventHandler : eventHandlers)\r
 304             eventHandlerStack.remove(eventHandler.eventHandler);\r
 305 \r
 306         IHintStack stack = getContext().getHintStack();\r
 307         IThreadWorkQueue thread = getContext().getThreadAccess();\r
 308         for (HintListenerDefinition def : hintListeners)\r
 309             stack.removeKeyHintListener(thread, def.key, def);\r
 310 \r
 311         if (localHintCtx!=null) {\r
 312             context.getHintStack().removeHintContext(localHintCtx);\r
 313         }\r
 314         context = null;\r
 315     }\r
 316 \r
 317     /**\r
 318      * Has this interactor been removed from the context\r
 319      * @return true if interactor has been removed from the context\r
 320      */\r
 321     public boolean isRemoved()\r
 322     {\r
 323         return context==null;\r
 324     }\r
 325 \r
 326     /**\r
 327      * Remove Self.\r
 328      * \r
 329      * Removes this interactor from its designed context.\r
 330      * This methods can be invoked only once.\r
 331      */\r
 332     public void remove()\r
 333     {\r
 334         if (isRemoved())\r
 335             throw new RuntimeException("Interactor has already been removed from the context");\r
 336         context.remove(this);\r
 337     }\r
 338 \r
 339     /**\r
 340      * Returns the hint stack of the context.\r
 341      * @return hint stack\r
 342      */\r
 343     public IHintStack getHintStack()\r
 344     {\r
 345         return hintStack;\r
 346     }\r
 347 \r
 348     /**\r
 349      * Get local hint context. This context contains all hints set by this\r
 350      * particular interactor. Modifications affect the hint stack of the\r
 351      * interaction context, although some modifications may not become effective\r
 352      * in case the key is overridden by another hint context in the stack.\r
 353      * <p>\r
 354      * Local context must be created with createLocalHintContext() method.\r
 355      * constructor has defualt value Integer.MIN_VALUE.\r
 356      * <p>\r
 357      * Reading from this context returns only the local hint and not\r
 358      * from the shared hint stack of the canvas context.\r
 359      * <p>\r
 360      * To read from the shared hint stack, use getHint() or getHintStack() instead.\r
 361      * \r
 362      * @return the local hint context\r
 363      */\r
 364     public synchronized IHintContext getLocalHintContext()\r
 365     {\r
 366         return localHintCtx;\r
 367     }\r
 368 \r
 369     /**\r
 370      * Get hint context. Read operations are to hint stack, writes to local stack.\r
 371      * \r
 372      * @return\r
 373      */\r
 374     public synchronized IHintContext getWriteableHintStack()\r
 375     {\r
 376         if (hintCtx==null)\r
 377             hintCtx = getHintStack().createStackRead(getLocalHintContext());\r
 378         return hintCtx;\r
 379     }\r
 380 \r
 381     /**\r
 382      * Get hint context; local if exists, otherwise stack's default context.\r
 383      * \r
 384      * @return\r
 385      */\r
 386     public IHintContext getWriteableHintContext()\r
 387     {\r
 388         ICanvasContext ctx = context;\r
 389         assert(ctx!=null);\r
 390         if (localHintCtx!=null) return localHintCtx;\r
 391         return ctx.getDefaultHintContext();\r
 392     }\r
 393 \r
 394     /**\r
 395      * Read hint from the hint stack.\r
 396      * \r
 397      * @param key\r
 398      * @return\r
 399      */\r
 400     public <E> E getHint(Key key)\r
 401     {\r
 402         return hintStack.getHint(key);\r
 403     }\r
 404 \r
 405     public boolean hasHint(Key key)\r
 406     {\r
 407         return hintStack.getHint(key)!=null;\r
 408     }\r
 409 \r
 410     /**\r
 411      * Set hint to the local hint stack.\r
 412      * \r
 413      * Thread safe - switches to context thread\r
 414      * \r
 415      * @param key the key\r
 416      * @param value the value\r
 417      */\r
 418     public void setHint(final Key key, final Object value)\r
 419     {\r
 420         if (getThread().currentThreadAccess())\r
 421             getWriteableHintContext().setHint(key, value);\r
 422         else {\r
 423 //                      syncExec(new Runnable() {\r
 424 //                              @Override\r
 425 //                              public void run() {\r
 426 //                                      getWriteableHintContext().setHint(key, value);\r
 427 //                              }});\r
 428             throw new IllegalStateException("illegal thread access, expected " + getThread().getThread() + ", was in "\r
 429                     + Thread.currentThread());\r
 430         }\r
 431     }\r
 432 \r
 433     /**\r
 434      * Remove hint from local hint context / stack's default context\r
 435      * \r
 436      * Thread safe - switches to context thread\r
 437      * \r
 438      * @param key the key\r
 439      */\r
 440     public void removeHint(final Key key)\r
 441     {\r
 442         if (getThread().currentThreadAccess())\r
 443             getWriteableHintContext().removeHint(key);\r
 444         else\r
 445 //                      syncExec(new Runnable() {\r
 446 //                              @Override\r
 447 //                              public void run() {\r
 448 //                                      getWriteableHintContext().removeHint(key);\r
 449 //                              }});\r
 450             throw new IllegalStateException("illegal thread access");\r
 451     }\r
 452 \r
 453 \r
 454     public void syncExec(Runnable r)\r
 455     {\r
 456         ThreadUtils.syncExec(getThread(), r);\r
 457     }\r
 458 \r
 459     public void asyncExec(Runnable r)\r
 460     {\r
 461         ThreadUtils.asyncExec(getThread(), r);\r
 462     }\r
 463 \r
 464     /**\r
 465      * Create local hint context and add it to the hint stack. It will be\r
 466      * automatically removed when this participant is removed from the canvas.\r
 467      * <p>\r
 468      * Local hint context overrides default context in the following convenience methods:\r
 469      *  getHint(), setHint(), setHintAsync()\r
 470      * <p>\r
 471      * Q: What is the purpose of local hint stack?\r
 472      * A: To override hints for the lifetime of the participant.\r
 473      *    For example, Special editing mode overrides viewport and toolmode.\r
 474      * \r
 475      * @param priority\r
 476      */\r
 477     public void createLocalHintContext(int priority)\r
 478     {\r
 479         localHintCtx = new HintContext();\r
 480     }\r
 481 \r
 482     /**\r
 483      * Set hint to the local hint stack if one exists otherwise to the default context.\r
 484      * Switches thread to the appropriate context thread.\r
 485      * \r
 486      * @param key the key\r
 487      * @param value the value\r
 488      */\r
 489     public void setHintAsync(final Key key, final Object value)\r
 490     {\r
 491         assert(context!=null);\r
 492         asyncExec(new Runnable() {\r
 493             @Override\r
 494             public void run() {\r
 495                 if (isRemoved())\r
 496                     return;\r
 497                 if (localHintCtx!=null)\r
 498                     localHintCtx.setHint(key, value);\r
 499                 else\r
 500                     context.getDefaultHintContext().setHint(key, value);\r
 501             }});\r
 502     }\r
 503 \r
 504     /**\r
 505      * Get the interactor context.\r
 506      * @return the context\r
 507      */\r
 508     public ICanvasContext getContext()\r
 509     {\r
 510         return context;\r
 511     }\r
 512 \r
 513     public IThreadWorkQueue getThread()\r
 514     {\r
 515         return thread;\r
 516     }\r
 517 \r
 518 \r
 519     /**\r
 520      * Asserts that dependencies of participants are satisfied.\r
 521      */\r
 522     public void assertDependencies()\r
 523     {\r
 524         assert(depsSatisfied);\r
 525     }\r
 526 \r
 527     private boolean checkDependencies() {\r
 528         synchronized ( ctxListener ) {          \r
 529                 try {\r
 530                     for (ReferenceDefinition rd : refDefs) {\r
 531                         if (!rd.dependency)\r
 532                             continue;\r
 533                         Field f = rd.field;\r
 534                         Object o = f.get(this);\r
 535                         if (o == null)\r
 536                             return false;\r
 537                     }\r
 538                 } catch (Exception e) {\r
 539                     throw new RuntimeException(e);\r
 540                 }\r
 541                 return true;\r
 542         }\r
 543     }\r
 544 \r
 545     public void setDirty()\r
 546     {\r
 547         ICanvasContext ctx = getContext();\r
 548         if ( ctx==null ) return;\r
 549         IContentContext cctx = ctx.getContentContext();\r
 550         if ( cctx==null ) return;\r
 551         cctx.setDirty();\r
 552     }\r
 553 \r
 554 }\r