home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / vista_1 / !Manual_manual_window < prev    next >
Encoding:
Text File  |  1996-01-11  |  27.6 KB  |  800 lines
  1. <html>
  2. <title>Window</title>
  3.  
  4. <h1>Window</h1>
  5.  
  6. <h2>Synopsis</h2>
  7.  
  8. <pre>
  9.  
  10.       class Window : virtual public DeferredDelete
  11.          {
  12.          friend class Task ;
  13.          friend class Icon ;
  14.       
  15.          public:
  16.             enum <a href="file:window#wflags">wflags</a> ;
  17.             enum <a href="file:window#wanchor">wanchor</a> ;
  18.             struct <a href="file:window#state1">State</a> ;
  19.             struct <a href="file:window#info1">Info</a> ;
  20.       
  21.          public:
  22.             int <a href="file:window#handle">handle</a> ;
  23.             int <a href="file:window#is_open">is_open</a> ;
  24.             int <a href="file:window#anchor">anchor</a> ;
  25.             Task *<a href="file:window#task">task</a> ;
  26.             Window *<a href="file:window#next">next</a> ;
  27.             Window *<a href="file:window#next">prev</a> ;
  28.             Window *<a href="file:window#sub">sub_windows, *last_sub_window</a> ;
  29.             Window *<a href="file:window#parent">parent</a> ;
  30.             int <a href="file:window#x0">x0</a> ;
  31.             int <a href="file:window#x0">y0</a> ;
  32.             int <a href="file:window#x0">x1</a> ;
  33.             int <a href="file:window#y0">y1</a> ;
  34.             int <a href="file:window#scx">scx</a> ;
  35.             int <a href="file:window#scx">scy</a> ;
  36.             Menu *<a href="file:window#default_menu">default_menu</a> ;
  37.             Icon *<a href="file:window#icons">icons, *last_icon</a> ;
  38.             Object *<a href="file:window#objects">objects, *last_object</a> ;
  39.             MouseTracker *<a href="file:window#tracker">tracker</a> ;
  40.       
  41.          public:
  42.             <a href="file:window#ct1">Window</a>(Task *task, char *tname, char *menu = 0) ;
  43.             <a href="file:window#ct2">Window</a>(Window *w, char *tname, int anchor = A_NONE, char *menu = 0) ;
  44.             virtual <a href="file:window#dt">~Window</a>() ;
  45.       
  46.       //
  47.       // command functions
  48.       //
  49.       
  50.             virtual void <a href="file:window#do_open1">do_open</a>(int x0, int y0, int x1, int y1, int scx = 0, int scy = 0, int behind = -1) ;
  51.             virtual void <a href="file:window#do_open2">do_open</a>(int behind = -1) ;
  52.             virtual void <a href="file:window#do_open3">do_open</a>(int x0, int y0, int behind = -1) ;
  53.             virtual void <a href="file:window#do_close">do_close</a>() ;
  54.             virtual void <a href="file:window#do_redraw1">do_redraw</a>(int x0, int y0, int x1, int y1) ;
  55.             virtual void <a href="file:window#do_redraw2">do_redraw</a>() ;
  56.             virtual void <a href="file:window#do_update1">do_update</a>(int x0, int y0, int x1, int y1) ;
  57.             virtual void <a href="file:window#do_update2">do_update</a>() ;
  58.             virtual void <a href="file:window#do_drag">do_drag</a> (int type, int x0, int y0, int x1, int y1,
  59.                                   int px0 = -1, int py0 = -1,
  60.                                   int px1= -1, int py1 = -1) ;
  61.             State *<a href="file:window#state2">state</a>() ;
  62.             Info *<a href="file:window#info2">info</a>() ;
  63.             void <a href="file:window#read_position">read_position</a>() ;
  64.             virtual void <a href="file:window#set_extent1">set_extent</a>(int x0, int y0, int x1, int y1) ;
  65.             virtual void <a href="file:window#set_extent2">set_extent</a> (int width, int height) ;
  66.             virtual void <a href="file:window#set_width1">set_width</a> (int x0, int x1) ;
  67.             virtual void <a href="file:window#set_height1">set_height</a> (int y0, int y1) ;
  68.             virtual void <a href="file:window#set_width2">set_width</a> (int width) ;
  69.             virtual void <a href="file:window#set_height2">set_height</a> (int height) ;
  70.             virtual void <a href="file:window#get_outline">get_outline</a>(int &x0, int &y0, int &x1, int &y1) ;
  71.             virtual void <a href="file:window#set_title">set_title</a> (char *format...) ;
  72.             virtual char *<a href="file:window#title">title</a>() ;
  73.             Menu *<a href="file:window#display_menu">display_menu</a>(int x, int y, int button, int icon) ;
  74.             virtual void <a href="file:window#pre_menu">pre_menu</a>(Menu *m, int x, int y, int button, int icon) ;
  75.             virtual char *<a href="file:window#get_menu">get_menu</a> (int x, int y, int button, int icon) ;
  76.             int <a href="file:window#coords">xtoscreen</a> (int wx) { return (parent == NULL?x0:parent->subx0(this)) + wx - scx ; }
  77.             int <a href="file:window#coords">ytoscreen</a> (int wy) { return (parent == NULL?y1:parent->suby1(this)) + wy - scy ; }
  78.             int <a href="file:window#coords">xtowindow</a> (int sx) { return sx + scx - (parent==NULL?x0:parent->subx0(this)) ; }
  79.             int <a href="file:window#coords">ytowindow</a> (int sy) { return sy + scy - (parent==NULL?y1:parent->suby1(this)) ; }
  80.  
  81.             int subx0(Window *w) ;          // sub window's x0 coordinate in screen coords
  82.             int suby1(Window *w) ;          // sub window's y1 coordinate in screen coords
  83.       
  84.       //
  85.       // event functions - sent to object by WIMP
  86.       //
  87.             virtual void <a href="file:window#redraw">redraw</a>() ;
  88.             virtual void <a href="file:window#open">open</a>(int x0, int y0, int x1, int y1, int scx, int scy, int behind) ;
  89.             virtual void <a href="file:window#close">close</a>() ;
  90.             virtual void <a href="file:window#pointer">pointer</a>(int entering) ;
  91.             virtual void <a href="file:window#click">click</a>(int mx, int my, int buttons, int icon) ;
  92.             virtual void <a href="file:window#drag">drag</a>(int x0, int y0, int x1, int y1, int id) ;
  93.             virtual void <a href="file:window#key">key</a>(int icon, int x, int y, int height, int index, int code) ;
  94.             virtual void <a href="file:window#menu">menu</a>(MenuItem items[]) ;       // menu hit
  95.             virtual void <a href="file:window#scrol">scroll</a>(int x0, int y0, int x1, int y1, int scx, int scy, int behind, int xdir, int ydir) ;
  96.             virtual void <a href="file:window#caret">caret</a>(int gaining, int icon, int x, int y, int height, int index) ;
  97.             virtual void <a href="file:window#mode_change">mode_change</a>() ;
  98.             virtual char *<a href="file:window#help">help</a> (int mx, int my, int buttons, int icon) ;  // give help
  99.  
  100.          } ;
  101.  
  102. </pre>
  103.  
  104. <h2>Description</h2>
  105.  
  106. A Window represents a window which appears on the screen.  This is a fairly
  107. complex class but normally a class is derived from it which is much simpler.
  108. The idea of this class is that it provides all the basic functions
  109. necessary to draw a window on the screen and maintain it.  This means that
  110. with no other work it would be possible to use this class to create
  111. a window which can be dragged about the screen, resized, redrawn and closed.
  112. It can also display a menu (but not act on clicks on it).
  113. <p>
  114. Of course, there are other things necessary to make the window usable.  
  115. These other things cannot be provided by this class directly, but you 
  116. should derive a new class from this one and provide new functions to 
  117. override the default actions.  Indeed, Vista contains a number of 
  118. classes which do just this.  They are described later.
  119. <p>
  120. In order to understand the descriptions given for this class it is
  121. necessary that you understand the fundamental concepts of the behaviour
  122. of windows under RISC OS.  This information can be obtained in the
  123. Acorn Programmers Reference Manuals (PRM).
  124. <p>
  125. Once a Window class is created it can be opened on the screen.  While open
  126. it is vulnerable to user activities which will cause it to receive commands
  127. in order to make it respond as the user wishes.  A Window is an object 
  128. which provides a set of methods (functions) which will be invoked (called)
  129. when certain conditions arise.  The set of methods provided by the
  130. Window class split into 2 camps:
  131. <p>
  132. <ol>
  133. <li>Command methods
  134. <p>
  135.    These are function which the user can call to make the window do
  136.    something.  Exmples are: <a href="file:window#do_open1">do_open</a>,
  137.    <a href="file:window#do_close">do_close</a>, 
  138.    <a href="file:window#do_redraw1">do_redraw</a> etc.
  139. <p>   
  140. <li>Event methods
  141. <p>
  142.  
  143.    These are functions (virtual) which are called by Vista when something
  144.    has happened to the window about which the user needs to know.  Although
  145.    these functions are provided by the Window class, the idea is that you
  146.    should replace them with your own functions if you want to override
  147.    their default functionality (which may be to do nothing).
  148. </ol>   
  149. <p>   
  150. Windows contain a set of <a href="file:icon">Icons</a>.  These are classes that
  151. represent WIMP icons.  A window needs to known what icons exist within
  152. it so that it may act appropriately when user user activates one of them.
  153. <p>
  154. Windows also contain a set of <a href="file:window#object">Objects.</a>  
  155. These are things which exist
  156. inside a window, but are not part of the window.  An example would
  157. be an object which consists of a block of text, or an object which
  158. draws a 3D representation of a space ship.  Objects receive a request
  159. to redraw themselves when the Window is redrawn.  They are passed the
  160. coordinates of the area to be redrawn.  Vista contains set of
  161. useful objects which can be used as an example when writing your own.
  162. <p>
  163. Finally, windows contain a set of <a href="file:window#subwins">sub-windows.</a>  
  164. A sub-window is simply
  165. another window which has been created using the appropriate constructor.
  166. A window containing sub-windows automatically takes care of keeping them
  167. in the same relative position when the main window is moved.  Sub-windows
  168. can be used to provide the 'panes' described in the PRM.
  169. <p>
  170. Like Tasks, the Windows in Vista can display <a href="file:menu">menus</a>.  
  171. The way in which
  172. menus are handled is the same as for a Task.  On creation, the user
  173. may supply the name of a default menu which will be displayed automatically
  174. when the user clicks 'menu' over the window.  The tailoring of the menus
  175. and handling clicks is exactly the same as the Task class.
  176.  
  177.  
  178. <p>
  179. <a name="object"></a>
  180. <h3>Objects</h3>
  181.  
  182. A Window in Vista can contain a number of 'Objects'.  These are things which reside
  183. inside the window are need to be redrawn.  Icons are effectively objects which are
  184. handled by the WIMP.  An object is created inside a window and every time the
  185. window needs redrawn (for a resize or scroll) the objects are asked to redraw
  186. themselves by the Window.  They are passed the WORK AREA coordinates within the
  187. window which needs updated.  They can be used to perform clipping of the
  188. redraw in order to make it more efficient.
  189. <p>
  190. All objects in a window are derived from the class <a href="file:objects">Object</a>:
  191.  
  192. This is an abstract class from which all useful object are derived.  Each object exists
  193. inside a window at a certain position.  The position of the object is in 'window
  194. coordinates' which have their origin at the top left of the window.  The object 
  195. has a bounding box that specifies its size.  Because of the use of window
  196. coordinates, the Y coordinates for an object will mostly be negative.
  197. <p>
  198. Objects behave like icons.  They can receive clicks and key presses, be selected
  199. and be dragged around the screen.  An object knows how to redraw itself and
  200. is given this opportunity when requested by the WIMP.
  201. <p>
  202. Objects are told when the mouse pointer has entered or left the bounding 
  203. box of the object.  This enables the object to become active when the mouse
  204. is over it.
  205. <p>
  206. Each object has a priority associated with it.  The priority of an object
  207. determines how it behaves in the situation of overlapping objects.  The
  208. higher the priority an object has, the further up the 'stack' it appears
  209. as far as key presses, mouse events, and so on.  The default priority is
  210. 1.
  211.  
  212.  
  213. <p>
  214. <a name="subwins"></a>
  215. <h3>Sub Windows</h3>
  216.  
  217. A window can contain other windows.  This is not really nesting (as in Microsoft
  218. Windows), but is an implementation of what are known as 'panes'.  Subwindows
  219. can be 'anchored' or free within the parent window.  If the subwindow is
  220. anchored, it will not scroll with the parent window and can be used for
  221. toolbars.  The anchor can have 4 positions: A_LEFT, A_RIGHT, A_TOP
  222. and A_BOTTOM.  These refer to the left, right, top and bottom edges of
  223. the parent window respectively.  Anchored subwindows always move with the
  224. parent window and will stay attached to the appropriate edge when the
  225. parent is resized.
  226. <p>
  227. A free subwindow will scroll with the parent, but since these are not
  228. nested windows, will appear to leave the parent if scrolled beyond the
  229. edge of the parent window.
  230. <p>
  231. To create a subwindow it is a simple matter of placing the window in 
  232. the appropriate position using a template editor and using the
  233. window constructor:
  234. <pre>
  235.  
  236. Window::Window (Window *w, char *tname, int anchor = A_NONE, char *menu = 0)
  237.  
  238. </pre>
  239.  
  240. The first parameter is the parent window.  The 'anchor' parameter specifies
  241. whether the window is anchored or not and, if so, where.
  242.  
  243. <p>
  244. <h2>Members</h2>
  245.  
  246. <p>
  247. <a name="wflags"></a>
  248. <h3>Window::wflags</h3>
  249.  
  250. This enumeration contains values for the various flags within a window.  Each
  251. flag begins with an upper case 'W'.
  252.  
  253.  
  254. <p>
  255. <a name="wanchor"></a>
  256. <h3>Window::wanchor</h3>
  257.  
  258. This enumeration holds the values for the anchors in subwindows.
  259.  
  260.  
  261. <p>
  262. <a name="state1"></a>
  263. <h3>Window::State</h3>
  264.  
  265. This is a structure which is returned from the state() function.  It is defined as:
  266.  
  267.       struct State
  268.          {
  269.          int handle ;
  270.          Box box ;
  271.          int scx ;
  272.          int scy ;
  273.          int behind ;
  274.          wflags flags ;
  275.          } ;
  276.  
  277. and is exactly as returned from the WIMP.
  278.  
  279.  
  280. <p>
  281. <a name="info1"></a>
  282. <h3>Window::Info</h3>
  283.  
  284. This structure is returned from the info() function and contains the
  285. current information returned from the WIMP for the window.  It is
  286. defined as:
  287.  
  288.       struct Info
  289.          {
  290.          int handle ;
  291.          Box box ;
  292.          int scx ;
  293.          int scy ;
  294.          int behind ;
  295.          wflags flags ;
  296.          char colours[8] ;
  297.          Box extent ;
  298.          Icon::iconflags titleflags ;
  299.          Icon::iconflags workflags ;
  300.          void *sprite_area ;
  301.          int min_size ;
  302.          IconData title ;
  303.          int num_icons ;
  304.          } ;
  305.  
  306.  
  307. <p>
  308. <a name="handle"></a>
  309. <h3>Window::handle</h3>
  310.  
  311. This is the handle assigned by the WIMP for this window.
  312.  
  313.  
  314. <p>
  315. <a name="is_open"></a>
  316. <h3>Window::is_open</h3>
  317.  
  318. This holds whether the window is open or closed.
  319.  
  320.  
  321. <p>
  322. <a name="anchor"></a>
  323. <h3>Window::anchor</h3>
  324.  
  325. This is anchor value for a subwindow.
  326.  
  327.  
  328. <p>
  329. <a name="task"></a>
  330. <h3> Window::task</h3>
  331.  
  332. This is the task to which the window belongs
  333.  
  334.  
  335. <p>
  336. <a name="next"></a>
  337. <h3> Window::next, Window::prev</h3>
  338.  
  339. These are pointers to the next and previous windows in the task.
  340.  
  341.  
  342. <p>
  343. <a name="sub"></a>
  344. <h3> Window::sub_windows, Window::last_sub_window</h3>
  345.  
  346. These are pointers to the subwindows within this window.
  347.  
  348.  
  349. <p>
  350. <a name="parent"></a>
  351. <h3> Window::parent</h3>
  352.  
  353. This is a pointer to the parent if the window is a subwindow.
  354.  
  355.  
  356. <p>
  357. <a name="x0"></a>
  358. <h3> Window::x0, Window::y0, Window::x1, Window::y1</h3>
  359.  
  360. These are the bounding coordinates for the window.  What they mean
  361. depends on whether the window is a subwindow or not.  If the window
  362. is not a subwindow, they are the screen coordinates at which the window
  363. is open.  If the window is a subwindow, they are the coordinates of the
  364. pane relative to the window origin.  Note that this means that the
  365. Y coordinates will be negative.
  366.  
  367.  
  368. <p>
  369. <a name="scx"></a>
  370. <h3> Window::scx, Window::scy</h3>
  371.  
  372. These are the scroll position of the window.
  373.  
  374.  
  375. <p>
  376. <a name="default_menu"></a>
  377. <h3> Window::default_menu</h3>
  378.  
  379. This is a pointer to the manu to be used by default when the menu
  380. button is pressed over the window.
  381.  
  382.  
  383. <p>
  384. <a name="icons"></a>
  385. <h3> Window::icons, Window::last_icon</h3>
  386.  
  387. These are pointers to the list of icons in the window.
  388.  
  389.  
  390. <p>
  391. <a name="objects"></a>
  392. <h3> Window::objects, Window::last_object</h3>
  393.  
  394. These are pointers to the list of objects in the window.
  395.  
  396.  
  397. <p>
  398. <a name="tracker"></a>
  399. <h3> Window::tracker</h3>
  400.  
  401. When the mouse enters a window, a MouseTracker thread is created to track
  402. the mouse and inform each of the objects when the mouse is over them.  The 
  403. MouseTracker thread is defined as:
  404. <pre>
  405.  
  406. class MouseTracker : public Thread
  407.    {
  408.    public:
  409.       MouseTracker (Window *w) ;
  410.       ~MouseTracker() ;
  411.       void run() ;
  412.    private:
  413.       Window *window ;
  414.    } ;
  415.  
  416. </pre>
  417.  
  418. and simply loops reading the mouse position and checking for the mouse
  419. entering and leaving an object.  The tracker is deleted when the mouse
  420. exits the window again.
  421.  
  422.  
  423. <p>
  424. <a name="ct1"></a>
  425. <h3>Window::Window (Task *task,
  426.                        char *tname,
  427.                        char *menu = 0)</h3>
  428.                        
  429. This constructor creates a new window within a task.  The 'tname' parameter is
  430. the name of the template to use when creating the window.  This must exist
  431. in the Templates file.  The 'menu' parameter is the name of the menu to display
  432. when the menu button is pressed over the window.  A value of NULL (0) indicates
  433. that there is no default menu, in which case the 'get_menu' function will
  434. be used.
  435.  
  436.  
  437. <p>
  438. <a name="ct2"></a>
  439. <h3>Window::Window (Window *w,
  440.                        char *tname,
  441.                        int anchor = A_NONE,
  442.                        char *menu = 0)</h3>
  443.                        
  444. This constructor is used to create a subwindow.  The 'w' parameter specifies
  445. the parent for the window.  The 'tname' is the template to be used from
  446. the Templates file.  'anchor' is a value to indicate whether the window
  447. is anchored to the parent or not (see the section on Sub Windows above).
  448. The 'menu' parameter is the menu to display when the menu button is
  449. pressed over the window.  If the value is NULL (0) then the
  450. get_menu function will be used to get a menu.
  451.  
  452.  
  453.  
  454. <p>
  455. <a name="dt"></a>
  456. <h3> Window::~Window()</h3>
  457.  
  458. This is the window destructor which is called when the window is deleted.
  459.  
  460.  
  461. <p>
  462. <a name="do_open1"></a>
  463. <h3>Window::do_open (int x0, int y0, int x2, in y1,
  464.                         int scx = 0, int scy = 0,
  465.                         int behind = -1)</h3>
  466.                         
  467. This function causes the window to appear on the screen at the given coordinates.  The 
  468. coordinates are screen coordinates whose origin is the bottom left of the screen.  The
  469. 'scx', 'scy' and 'behind' parameters are as specified in the PRM.  Opening a window
  470. will cause all the subwindows to open also.
  471.  
  472.  
  473. <p>
  474. <a name="do_open2"></a>
  475. <h3> Window::do_open (int behind = -1)</h3>
  476.  
  477. This causes the window to appear on the screen at the current position.  The 'behind'
  478. parameter can be used to specify the window to open behind.  The current position 
  479. begins at that set by the template editor.  All sub windows will open also.  Ths position
  480. of the subwindows is set by the template editor and will always be in the same position
  481. relative to the main window.
  482.  
  483. <p>
  484. <a name="do_open3"></a>
  485. <h3> Window::do_open (int x0, int y0, int behind = -1)</h3>
  486.  
  487. This function causes the window to open at the given coordinates.  The
  488. (x,y) coordinates given are screen coordinates and are the bottom
  489. left corner of the window.  The 'behind'
  490. parameter can be used to specify the window to open behind.
  491.  
  492.  
  493. <p>
  494. <a name="do_close"></a>
  495. <h3> Window::do_close()</h3>
  496.  
  497. This causes the window, and all sub windows, to disappear from the screen.
  498.  
  499.  
  500. <p>
  501. <a name="do_redraw1"></a>
  502. <h3> Window::do_redraw (int x0, int y0, int x1, int y1)</h3>
  503.  
  504. Redraw part of a window.  The coordinates are window coordinates relative to the
  505. window origin (top left).
  506.  
  507.  
  508.  
  509. <p>
  510. <a name="do_redraw2"></a>
  511. <h3> Window::do_redraw()</h3>
  512.  
  513. Redraw the whole window.
  514.  
  515.  
  516. <p>
  517. <a name="do_update1"></a>
  518. <h3> Window::do_update (int x0, int y0, int x1, int y1)</h3>
  519.  
  520. Update part of a window.  The coordinates are window coordinates relative
  521. to the window origin (top left).
  522.  
  523.  
  524. <p>
  525. <a name="do_update2"></a>
  526. <h3> Window::do_update()</h3>
  527.  
  528. Update the whole window.
  529.  
  530.  
  531. <p>
  532. <a name="do_drag"></a>
  533. <h3>Window::do_drag (int type, int x0, int y0, int x1, int y1,
  534.                                   int px0 = -1, int py0 = -1,
  535.                                   int px1= -1, int py1 = -1) </h3>
  536.                                   
  537. Begin a new drag operation.  See the PRM for full information about
  538. Wimp_DragBox.
  539.  
  540.  
  541. <p>
  542. <a name="state2"></a>
  543. <h3> Window::state()</h3>
  544.  
  545. This returns a pointer to a variable of type Window::State.  This is held 
  546. within the window and will be overwritten on the next call to state().  This
  547. function calls Wimp_GetWindowState.
  548.  
  549.  
  550. <p>
  551. <a name="info2"></a>
  552. <h3> Window::info()</h3>
  553.  
  554. This returns a pointer to the current window information.  The information
  555. is returned by a call to Wimp_GetWindowInfo and is held in the window
  556. class.  It will be overwritten by another call to this function.
  557.  
  558.  
  559. <p>
  560. <a name="read_position"></a>
  561. <h3> Window::read_position()</h3>
  562.  
  563. This call reads the position for a window and stores it in the internal
  564. variables.  It is used to update the known position after a window has
  565. been moved.
  566.  
  567.  
  568. <p>
  569. <a name="set_extent1"></a>
  570. <h3> Window::set_extent (int x0, int y0, int x1, int y1)</h3>
  571.  
  572. Set the 'extent' for the window to the coordinates given (in window
  573. units).
  574.  
  575.  
  576. <p>
  577. <a name="set_extent2"></a>
  578. <h3> Window::set_extent (int width, int height)</h3>
  579.  
  580. Set the extent of a window to a given width and height.
  581.  
  582.  
  583. <p>
  584. <a name="set_width1"></a>
  585. <h3> Window::set_width (int x0, int x1)</h3>
  586.  
  587. Set the extent of the window to the given width.  The parameters specify the
  588. minimum and maximum values for the extent.
  589.  
  590.  
  591. <p>
  592. <a name="set_height1"></a>
  593. <h3> Window::set_height (int y0, int y1)</h3>
  594.  
  595. Set the extent of the window to the given height.  The parameters specify the
  596. minimum and maximum values for the extent.
  597.  
  598.  
  599. <p>
  600. <a name="set-width2"></a>
  601. <h3> Window::set_width (int width)</h3>
  602.  
  603. Set the extent of the window to the given width.  The minimum X value remains
  604. the same.
  605.  
  606.  
  607. <p>
  608. <a name="set_height2"></a>
  609. <h3> Window::set_height (int height)</h3>
  610.  
  611. Set the extent of the window to the given height.  The minimum Y value remains
  612. the same.
  613.  
  614.  
  615. <p>
  616. <a name="get_outline"></a>
  617. <h3> Window::get_outline (int &x0, int &y0, int &x1, int &y1)</h3>
  618.  
  619. Read the outline of the window into the reference variables passed.
  620.  
  621.  
  622. <p>
  623. <a name="set_title"></a>
  624. <h3> Window::set_title (char *format...)</h3>
  625.  
  626. Set the title of the window.  The 'format' is a printf style format
  627. string with additional parameters passed after it.  The window must
  628. have an indirected title in order for this to work.
  629.  
  630. <p>
  631. <a name="title"></a>
  632. <h3> Window::title()</h3>
  633.  
  634. Read the title of a window.  The value returned is a pointer to the
  635. indirected title string.
  636.  
  637. <p>
  638. <a name="display_menu"></a>
  639. <h3> Window::display_menu (Menu *m, int x, int y, int button, int icon)</h3>
  640.  
  641. This function is used to display a menu for this window.  If the window
  642. has been created with a default menu, this will be displayed.  Otherwise
  643. the function get_menu will be called.  If the default menu is being
  644. displayed, the function pre_menu will be called in order to allow the user
  645. to change the default menu.
  646.  
  647. <p>
  648. <a name="pre_menu"></a>
  649. <h3> Window::pre_menu (Menu *m, int x, int y, int button, int icon)</h3>
  650.  
  651. This virtual function is called just before a menu is displayed on the
  652. screen.  The purpose is to allow the user to change the contents of the
  653. menu.
  654.  
  655.  
  656. <p>
  657. <a name="get_menu"></a>
  658. <h3> Window::get_menu (int x, int y, int button, int icon)</h3>
  659.  
  660. This is called when there was no default menu provided to the constructor.
  661. It is a virtual function which should be supplied by a derived class
  662. if it needs to decide on a number of menus.  It returns the name
  663. of the menu to display.
  664.  
  665.  
  666. <p>
  667. <a name="redraw"></a>
  668. <h3> Window::redraw()</h3>
  669.  
  670. This is invoked when the task received a redraw event from the WIMP.  The default
  671. function runs though the objects and redraws them by invoking their redraw
  672. functions.  Multi-threading is disabled throughout this process.
  673.  
  674.  
  675. <p>
  676. <a name="open"></a>
  677. <h3> Window::open (int x0, int y0, int x1, int y1, int scx, int scy, int behind)</h3>
  678.  
  679. This is invoked when the WIMP sends an open request to the task.  The default
  680. action is to open the window at the requested coordinates.
  681.  
  682. <p>
  683. <a name="close"></a>
  684. <h3> Window::close()</h3>
  685.  
  686. This is invoked when the WIMP sends a close request to the task.  The default
  687. action is to close the window.
  688.  
  689.  
  690. <p>
  691. <a name="pointer"></a>
  692. <h3> Window::pointer (int entering)</h3>
  693.  
  694. This is invoked when the WIMP detects the mouse entering or leafing the task.  
  695. The parameter tells the function whether the mouse is entering or leaving the
  696. window.  If it is entering the default action is to create a MouseTracker
  697. thread.  if it is leaving the window, the MouseTracker thread is deleted.
  698.  
  699.  
  700. <p>
  701. <a name="click"></a>
  702. <h3> Window::click (int mx, int my, int buttons, int icon)</h3>
  703.  
  704. This is invoked when the WIMP detects a mouse click in a window belonging
  705. to the task.  The default action is to do nothing.
  706.  
  707.  
  708. <p>
  709. <a name="drag"></a>
  710. <h3> Window::drag(int x0, int y0, int x1, int y1, int id)</h3>
  711.  
  712. This is invoked when the WIMP detects a drag operation has terminated.
  713. The default action is to do nothing.
  714.  
  715.  
  716.  
  717. <p>
  718. <a name="key"></a>
  719. <h3> Window::key(int icon, int x, int y, int height, int index, int code)</h3>
  720.  
  721. This is invoked when the WIMP detects a key press in a window belonging
  722. to the task.  The default action is to do nothing.
  723.  
  724.  
  725.  
  726. <p>
  727. <a name="menu"></a>
  728. <h3> Window::menu(MenuItem items[])</h3>
  729.  
  730. This is invoked when the user has made a menu selection from a menu belonging
  731. to the window.  If the program wishes to deal with menu hits, this function
  732. must be provided by a derived class.  The function is passed an array of
  733. MenuItem structures which detail the selection made.  It is up to the
  734. function to determine the action based on the selection.
  735.  
  736. <p>
  737. <a name="scroll"></a>
  738. <h3> Window::scroll(int x0, int y0, int x1, int y1, int scx, int scy, int behind, int xdir, int ydir)</h3>
  739.  
  740. This is invoked when the WIMP detects a scroll request in a window belonging
  741. to the task.  The default action is to do nothing.
  742.  
  743.  
  744. <p>
  745. <a name="caret"></a>
  746. <h3> Window::caret(int gaining, int icon, int x, int y, int height, int index)</h3>
  747.  
  748. This is invoked when a window belonging to the task either gains or loses
  749. the caret.  The 'gaining' parameter says whether the caret has been
  750. gained or lost (non zero = gain).  The default action is to do nothing.
  751.  
  752.  
  753. <p>
  754. <a name="mode_change"></a>
  755. <h3> Window::mode_change()</h3>
  756.  
  757. This is invoked when the screen mode has been changed.  The default action is
  758. to cycle through the objects informing them of the mode change.  
  759.  
  760. <p>
  761. <a name="coords"></a>
  762. <h3> Window::xtoscreen(int wx), ytoscreen (int wy), xtowindow (int sx), ytowindow (int sy)</h3>
  763.  
  764. These functions convert between the two coordinate systems.  Window coordinates are
  765. relative to the window origin which is the top left of the window.  This means that 
  766. the Y coordinate is always negative inside a window.  Screen coordinates are
  767. relative to the screen origin which is (normally) the bottom left of the
  768. screen.
  769. <p>
  770. The 4 functions provided are:
  771. <ul>
  772. <li><b>xtoscreen</b>: Convert a window X coordinate to screen coordinate
  773. <li><b>ytoscreen</b>: Convert a window Y coordinate to screen coordinate
  774. <li><b>xtowindow</b>: Convert a screen X coordinate to window coordinate
  775. <li><b>ytowindow</b>: Convert a screen X coordinate to window coordinate
  776. </ul>
  777. <p>
  778. The functions are defined 'inline' so they will not result in a function
  779. call being generated and will therefore be quick to execute.  They
  780. take care of any scroll offsets in the window (scx snd scy).
  781. <p>
  782. They also take care of any nesting of windows.
  783.  
  784.  
  785. <p>
  786. <a name="help"></a>
  787. <h3> Window::help (int mx, int my, int buttons, int icon)</h3>
  788.  
  789. This function is called when help is being requested.  The default
  790. action is to return NULL, meaning that the window is not prepared
  791. to give anything away.  Derived classes may provide their own
  792. help function.  The function return a string (char *) which
  793. is a pointer to the help text.
  794. <p>
  795. This function is called if all of the icons and objects within the
  796. window refuse to offer any help.  Of course it will also
  797. be called if there are no objects or icons, or if the mouse
  798. pointer is not over an object or icon.
  799.  
  800.