home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 4 / DATAFILE_PDCD4.iso / utilities / utilsp / pca / Docs / Remote_Msg < prev    next >
Encoding:
Text File  |  1996-08-20  |  4.8 KB  |  112 lines
  1. Plug In Compliant Application protocol
  2. ====================================== 
  3.  
  4. PCA In-place editing specification
  5. ==================================
  6.  
  7.  
  8. Author : Rob Davison (rdavison@xtra.co.nz)
  9. Date : 15/08/96
  10. Status : Release 1
  11.  
  12.  
  13. Introduction
  14. ============
  15.  
  16. The aim of this section is to define the work necessary for applications to
  17. support 'in-place' editing (applications working on an object within another
  18. application's window) within the framework supplied by the PCA itself.
  19.  
  20. This feature is an optional part of the PCA specification. All remote tasks
  21. must be able to operate according to the normal PCA specification (open
  22. their own window onto the object) if the Local task in question does not
  23. support in-place editing. Even if the Local task does support this, it is
  24. wise for the remote task to give the user the option of switching to
  25. external editing as in-place editing has its disadvantages as well as
  26. advantages. (The principal disadvantage being that only one in-place editing
  27. session per object can be undertaken at a time, for obvious reasons). 
  28.  
  29. Local task 
  30. ----------
  31.  
  32. The greatest amount of work is down to the 'Local' or object-owning
  33. application. After invoking a remote task with the PCA message DoYourStuff
  34. when bit 4 of the flags word is set, it must expect receipt of
  35. Message_HookMe from the remote task. When it gets this message it should
  36. create a transparent icon in its window which completely covers the object
  37. and send  Message_ObjectPosition . 
  38.  
  39. The button type of this icon should be taken from bits 28-31 of the flags
  40. word as sent by  Message_HookMe and the indirection string (if supported)
  41. from R1+36
  42.  
  43. Then, on receipt of the following standard Wimp messages the Local task must
  44. check to see if the message refers to an icon covering the object, and if it
  45. is, modify the message block and pass the message to the remote task using
  46. Wimp_SendMessage.
  47.  
  48. Doing this effectively cuts a 'hole' in the window where the object is.
  49. Messages into that region get shunted to the Remote task and are ignored by
  50. the Local task.
  51.  
  52.  
  53. Details of the modifications:
  54.  
  55.  
  56. 6. Button_Click 
  57.  
  58. xposition and yposition should be made relative to the object's bottom left.
  59. Window handle must be set to the one supplied in Message_HookMe . Icon
  60. handle must be set to the special value -&414350 (-"PCA")
  61.  
  62. ??? Other messages ???
  63. ??? Which to support and how to modify them ???
  64. ??? Advise us if you have any suggestions ???
  65.  
  66. On receipt of Message_OpenWindow for the window in which the object resides
  67. the Local task must send Message_ObjectPosition to the remote task so that
  68. it can open its toolbar at an appropriate place. Also, any actions which
  69. cause the position or size of the remotely linked object to change must
  70. resize and reposition the icon created above and send Message_ObjectPosition
  71. again.
  72.  
  73. On receipt of Message_UnhookMe it must delete the icon covering the object
  74. and carry out any other work necessary to restore normal access to the
  75. object. The same action should obviously also be undertaken if the object is
  76. deleted. 
  77.  
  78. Remote Task 
  79. -----------
  80.  
  81. On receipt of Message_ObjectPosition the remote task must open its toolbar
  82. at an appropriate position calculated from the data contained in the
  83. message.
  84.  
  85. This toolbar must contain at least one icon which, when clicked on, sends
  86. Message_UnhookMe to the local task, removes any references it has to the
  87. object and closes the toolbar. Model the appearance of this icon on the
  88. window close icon and position the icon at the far left horizontal toolbars
  89. or at the top left of vertical toolbars.
  90.  
  91. On receipt of Message_Do / Message_Changed the remote task must check to see
  92. if In-place editing is on (b4 of flags in Message_Do) and, if so, send
  93. Message_HookMe rather than opening its own window onto the object.
  94.  
  95. On receipt of ButtonClick messages (apparently) to its main window the
  96. remote task should check the icon handle and if it is equal to -&414350
  97. treat the coordinates passed in the ButtonClick block as 'corrected' for the
  98. position of its window, scrollbars etc as the coordinates are already
  99. relative to the objects bottom left. Modify the object data as appropriate
  100. and generate Message_UpdateArea as with standard PCA practice.
  101.  
  102. You should be able to use the same code for remote and local actions just do
  103. not convert pointer coordinates to be relative to your main window and do
  104. not redraw your main window (it should be closed anyway).
  105.  
  106. Note: For 'painting' or 'dragging' type actions it is sometimes wise to set
  107. the remote button type (in Message_HookMe) to Click and to do a tight
  108. repeating 'loop' around your redraw/paint code, reading the mouse pointer
  109. information directly until the button click stops. In this situation the
  110. Remote task should make use of the information in the last
  111. Message_ObjectPosition it receieved to work out the visible size and
  112. position of the object in the Local task's window (see the !Spaint example).