home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / v / vista / !Manual / manual / objects < prev    next >
Text File  |  1996-01-27  |  19KB  |  554 lines
  1. <html>
  2. <title>Objects</title>
  3.  
  4. <h1>Objects</h1>
  5.  
  6. A Window in Vista can contain a number of 'Objects'.  These are things which reside
  7. inside the window are need to be redrawn.  Icons are effectively objects which are
  8. handled by the WIMP.  An object is created inside a window and every time the
  9. window needs redrawn (for a resize or scroll) the objects are asked to redraw
  10. themselves by the Window.  They are passed the <b>WORK AREA</b> coordinates within the
  11. window which needs updated.  They can be used to perform clipping of the
  12. redraw in order to make it more efficient.
  13. <p>
  14. Objects in a window has a priority assicoated with them.  This is to allow
  15. objects to overlap.  A higher priority object will receive events
  16. such as mouse clicks and key presses before lower priority ones.  
  17. <p>
  18. <h2>Synopsis</h2>
  19.  
  20. <pre>
  21.  
  22. class Object
  23.    {
  24.    public:
  25.       <a href="file:objects#ct">Object</a> (Window *w, char *name, int priority = 0, char *menu = 0) ;
  26.       virtual <a href="file:objects#dt">~Object</a>() ;
  27.       virtual void <a href="file:objects#redraw">redraw</a> (int x0, int y0, int x1, int y1) ;
  28.       virtual void <a href="file:objects#update">update</a> (int x0, int y0, int x1, int y1) ;
  29.       virtual int <a href="file:objects#compare">compare</a> (int x, int y) ;
  30.       virtual void <a href="file:objects#move1">move</a> (int x0, int y0, int x1, int y1) ;
  31.       virtual void <a href="file:objects#move2">move</a> (int dx, int dy) ;
  32.       virtual void <a href="file:objects#drag">drag</a> (int mx, int my, int buttons) ;
  33.       virtual void <a href="file:objects#end_drag">end_drag</a> (int x0, int y0, int x1, int y1, int id) ;
  34.       virtual void <a href="file:objects#click">click</a>(int mx, int my, int button) ;
  35.       virtual void <a href="file:objects#key">key</a> (int x, int y, int height, int index, int code) ;
  36.       virtual void <a href="file:objects#double_click">double_click</a> (int mx, int my, int buttons) ;
  37.       virtual void <a href="file:objects#select">select</a>() ;
  38.       virtual void <a href="file:objects#unselect">unselect</a>() ;
  39.       virtual int <a href="file:objects#width">width</a>() ;
  40.       virtual int <a href="file:objects#height">height</a>() ;
  41.       virtual void <a href="file:objects#pointer">pointer</a> (int entering) ;
  42.       virtual void <a href="file:objects#mode_change">mode_change</a>() ;
  43.       Menu *<a href="file:objects#display_menu">display_menu</a> (int x, int y, int button, int icon) ;
  44.       virtual void <a href="file:objects#pre_menu">pre_menu</a>(Menu *m, int x, int y, int button, int icon) ;
  45.       virtual char *<a href="file:objects#get_menu">get_menu</a> (int x, int y, int button, int icon) ;
  46.  
  47.       virtual void <a href="file:objects#menu">menu</a> (MenuItem items[]) ;
  48.       virtual char (<a href="file:objects#help">help</a> (int mx, int my, int buttons) ;
  49.       int <a href="file:objects#x0">x0</a> ;
  50.       int <a href="file:objects#x0">y0</a> ;
  51.       int <a href="file:objects#x0">x1</a> ;
  52.       int <a href="file:objects#x0">y1</a> ;
  53.       Window *<a href="file:objects#window">window</a> ;
  54.       Menu *<a href="file:objects#default_menu">default_menu</a> ;
  55.       Object *<a href="file:objects#next">next, *prev</a> ;
  56.       char <a href="file:objects#name">name</a>[32] ;
  57.       int <a href="file:objects#priority">priority</a> ;
  58.       int <a href="file:objects#selected">selected</a> ;
  59.    } ;
  60.  
  61. </pre>
  62. <p>
  63. <h2>Members</h2>
  64.  
  65. <p>
  66. <a name="ct"></a>
  67. <h3>Object::Object (Window *w, char *name, int priority = 0, char *menu = 0)</h3>
  68.  
  69. This is the Object constructor.  The parameters are:
  70. <p>
  71. <ul>
  72. <li><b>w</b>: The window in which the object exists
  73. <li><b>name</b>: The name of the object (a text string - may be "")
  74. <li><b>priority</b>: The priority of the object.  This determines the
  75. order in which the object is placed in the window.  Higher priority
  76. objects are handled as if they are "on top" of other objects and therefore
  77. are first to be given mouse clicks.  They are also the first to be redrawn.
  78. <li><b>menu</b>: A menu to use as default if the object responds to menu
  79. clicks.
  80. </ul>
  81.  
  82. <p>
  83. <a name="dt"></a>
  84. <h3>Object::~Object()</h3>
  85.  
  86. This is the object destructor.  It will remove the object from the
  87. window.
  88.  
  89. <p>
  90. <a name="redraw"></a>
  91. <h3>Object::redraw (int x0, int y0, int x1, int y1)</h3>
  92.  
  93. This function is called when the object may need to be redrawn.  The
  94. function should check if the object boundary box lies within the
  95. coordinates passed before redrawing itself.  The background
  96. has already been cleared by the WIMP.
  97. <p>
  98. The object can check the coordinates using the following code:
  99. <pre>
  100.  
  101. if (x0 <= this->x1 && x1 >= this->x0 && y0 <= this->y1 && y1 >= this->y0)
  102.    {
  103.    // redraw the object
  104.    }
  105.    
  106. </pre>
  107.  
  108. The coordinates passed are window coordinates (not screen coordinates),
  109. but can be converted to screen coordinates by code such as:
  110. <pre>
  111.  
  112. sx = window->x0 + this->x0 - window->scx ;        // screen x
  113. sy = window->y1 + this->y0 - window->scy ;        // screen y
  114.       
  115. </pre>
  116. or by calling the Window functions <a href="file:window#coords">xtoscreen(), ytoscreen()</a>.
  117.  
  118. <p>
  119. <a name="update"></a>
  120. <h3>Object::update (int x0, int y0, int x1, int y1)</h3>
  121.  
  122. This function is called when the user has requested an update of the
  123. window by use of the Wimp_UpdateWindow call.  The coords passed are
  124. window coordinates (as in redraw).  The window is not cleared to the
  125. background colour.
  126.  
  127. <p>
  128. <a name="compare"></a>
  129. <h3>Object::compare (int x, int y)</h3>
  130.  
  131. This function is called to check if the coordinates passed (in screen coordinates
  132. this time) are within the object's boundary.
  133. <p>
  134. In the simplest case, the following code is provided as part of the
  135. Object base class.  It simply compares the bounding box of the
  136. object.  If the object is not a simple box, more complex code is
  137. required:
  138. <pre>
  139.  
  140. int Object::compare (int x, int y)
  141.    {
  142.    x = x + (window->scx - window->x0) ;   // x in window coords
  143.    y = y + (window->scy - window->y1) ;   // y in window coords
  144.    return x <= this->x1 && x >= this->x0 && y <= this->y1 && y >= this->y0 ;
  145.    }
  146.    
  147. </pre>
  148.  
  149. <p>
  150. <a name="move1"></a>
  151. <h3>Object::move (int x0, int y0, int x1, int y1)</h3>
  152.  
  153. This function moves the object to a new position (in window coordinates).
  154. It also allows the object's bounding box to be resized.
  155.  
  156. <p>
  157. <a name="move2"></a>
  158. <h3>Object::move (int dx, int dy)</h3>
  159.  
  160. This function moves the object a certain distance from its current
  161. position.  The deltas are in the x and y direction and are in
  162. window coordinates.
  163.  
  164. <p>
  165. <a name="drag"></a>
  166. <h3>Object::drag (int mx, int my, int buttons)</h3>
  167.  
  168. This function begins an object drag.  The default function as provided
  169. by the Object base class starts a drag by using the do_drag function
  170. in the window.
  171.  
  172. <p>
  173. <a name="end_drag"></a>
  174. <h3>Object::end_drag (int x0, int y0, int x1, int y1, int id)</h3>
  175.  
  176. This function is called by the Task when the drag operation has completed.
  177. It is passed the drag bounding box coordinates (screen coordinates)
  178. and an integral identifier passed to the dragger.  The default
  179. function provided by the Object base class moves the object to the
  180. new position.
  181.  
  182. <p>
  183. <a name="click"></a>
  184. <h3>Object::click(int mx, int my, int button)</h3>
  185.  
  186. This function is called when the user clicks select over the object.
  187. The parameters passed are exactly as returned from Wimp_Poll for this
  188. event.
  189. <p>
  190. Note that the window must have an appropriate button type for this
  191. event to be received.
  192.  
  193.  
  194. <p>
  195. <a name="key"></a>
  196. <h3>Object::key (int x, int y, int height, int index, int code)</h3>
  197.  
  198. This function is called when the user presses a key over the object.
  199. The paramaters passed are as returned from Wimp_Poll.
  200.  
  201. <p>
  202. <a name="double_click"></a>
  203. <h3>Object::double_click (int mx, int my, int buttons)</h3>
  204.  
  205. This function is called when the user has double-clicked the mouse
  206. over the object.  Note that the window must have an appropriate 
  207. button type for this event to be received.
  208.  
  209. <p>
  210. <a name="select"></a>
  211. <h3>Object::select()</h3>
  212.  
  213. Mark the object as selected.  The selection state can be read by
  214. accessing the variable 'selected' within the object class.
  215.  
  216. <p>
  217. <a name="unselect"></a>
  218. <h3>Object::unselect()</h3