home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / programming / vista_1 / !Manual_manual_icon < prev    next >
Encoding:
Text File  |  1996-01-09  |  14.9 KB  |  529 lines
  1. <html>
  2. <title>Icon</title>
  3. <h1>Icon</h1>
  4.  
  5. An Icon is an object which represents a WIMP icon.  The reason for having a
  6. separate C++ object is to allow manipulation of the icon by use of C++
  7. member function calls.  It also allows the definition of composite icons
  8. which appear like a single Icon.
  9. <p>
  10. It is <em>not</em> necessary to create an Icon object for every icon in a window.  When
  11. an icon is clicked, the task will invoke a member function for an Icon object
  12. if the object exists, otherwise the window will be informed of the click.
  13. <p>
  14. Two classes are defined here.  The Icon itself represents a single icon.  The
  15. IconSet class is used when multiple icons are present and need to be manipulated
  16. as a single icon.
  17.  
  18. <h2>Synopsis</h2>
  19.  
  20. <pre>
  21.  
  22.       class Icon
  23.          {
  24.          friend class Window ;
  25.       
  26.          public:
  27.             enum <a href="file:icon#iconflags">iconflags</a> ;
  28.             enum <a href="file:icon#buttontype">buttontype</a> ;
  29.             enum <a href="file:icon#direction">Direction</a> ;
  30.             enum <a href="file:icon#colourmask">ColourMask</a> ;
  31.          public:
  32.             <a href="file:icon#ct1">Icon</a>(int priority, int window, int x0, int y0, int x1, int y1, iconflags flags, IconData *data, 
  33.                  void *ref = 0) ;
  34.             <a href="file:icon#ct2">Icon</a>(Window *w, int iconnum = -1, void *ref = 0, char *menu = 0) ;
  35.             <a href="file:icon#ct3">Icon</a>() ;
  36.             <a href="file:icon#ct4">Icon</a>(Window *w,Icon *temp, Direction direction = DOWN, int gap = 0, void *ref = 0, char *menu = 0) ;
  37.             <a href="file:icon#ct5">Icon</a>(Window *w,Icon *temp, int x, int y, void *ref = 0, char *menu = 0) ;
  38.             virtual <a href="file:icon#dt">~Icon</a>() ;
  39.       
  40.             void <a href="file:icon#attach">attach</a> (Window *w, int iconnum) ;
  41.             void <a href="file:icon#move1">move</a> (int dx, int dy) ;
  42.             void <a href="file:icon#move2">move</a> (Direction direction, int dist) ;
  43.             void <a href="file:icon#move_to">move_to</a> (int x, int y) ;
  44.             void <a href="file:icon#resize">resize</a> (int width, int height) ;
  45.             void <a href="file:icon#read_position">read_position</a> (Box &pos) ;
  46.             void <a href="file:icon#plot">plot</a>() ;
  47.             virtual void <a href="file:icon#set_caret">set_caret</a>() ;
  48.             virtual void <a href="file:icon#drag">drag</a> (int mx, int my, int buttons) ;
  49.             virtual void <a href="file:icon#redraw">redraw</a> (int x0, int y0, int x1, int y1) ;
  50.             virtual void <a href="file:icon#click">click</a>(int mx, int my, int button, int icon) ;
  51.             virtual void <a href="file:icon#key">key</a> (int icon,  int x, int y, int height, int index, int code) ;
  52.             virtual void <a href="file:icon#select">select</a>() ;
  53.             virtual void <a href="file:icon#unselect">unselect</a>() ;
  54.             virtual void <a href="file:icon#fade">fade</a>() ;
  55.             virtual void <a href="file:icon#unfade">unfade</a>() ;
  56.             virtual void <a href="file:icon#set_fore_colour">set_fore_colour</a> (int colour) ;
  57.             virtual void <a href="file:icon#set_fore_colour">set_back_colour</a> (int colour) ;
  58.             virtual int <a href="file:icon#is_writeable">is_writeable</a>() ;
  59.             virtual int <a href="file:icon#is_selected">is_selected</a>() ;
  60.             virtual void <a href="file:icon#print">print</a> (char *format,...) ;
  61.             virtual void <a href="file:icon#change_sprite">change_sprite</a> (char *sprite_name, int area = 1) ;
  62.             virtual void <a href="file:icon#read_sprite">read_sprite</a> (char *sprite_name) ;
  63.             virtual void <a href="file:icon#reads">read</a> (char *s) ;
  64.             virtual void <a href="file:icon#readi">read</a> (int &n) ;
  65.             virtual void <a href="file:icon#readf">read</a> (float &n) ;
  66.             virtual void <a href="file:icon#readd">read</a> (double &n) ;
  67.             virtual void <a href="file:icon#writes">write</a> (char *s) ;
  68.             virtual void <a href="file:icon#writei">write</a> (int &n) ;
  69.             virtual void <a href="file:icon#writef">write</a> (float &n) ;
  70.             virtual void <a href="file:icon#writed">write</a> (double &n) ;
  71.       
  72.             virtual int <a href="file:icon#compare1">compare</a>(int icon) ;
  73.             virtual int <a href="file:icon#compare2">compare</a> (Icon *icon) ;
  74.  
  75.             Menu *<a href="file:icondisplay_menu">#display_menu</a> (int x, int y, int button, int icon) ;
  76.             virtual void <a href="file:icon#pre_menu">pre_menu</a>(Menu *m, int x, int y, int button, int icon) ;
  77.             virtual char *<a href="file:icon#get_menu">get_menu</a> (int x, int y, int button, int icon) ;
  78.             virtual void <a href="file:icon#menu">menu</a>(MenuItem items[]) ;
  79.         virtual char *<a href="file:icon#help">help</a> (int mx, int my, int buttons) ;  
  80.          public:
  81.             int <a href="file:icon#handle">handle</a> ;
  82.             Window *<a href="file:icon#window">window</a> ;
  83.             void *<a href="file:icon#user_ref">user_ref</a> ;
  84.          } ;
  85.  
  86.  
  87.  
  88.       class IconSet
  89.          {
  90.          public:
  91.             IconSet (int num_icons) ;
  92.             ~IconSet() ;
  93.             int compare(int icon) ;
  94.             void add_icon(int icon) ;
  95.             virtual void select (int icon) ;
  96.             virtual void select();
  97.             virtual void fade(int icon) ;
  98.             virtual void fade() ;
  99.             virtual void unselect (int icon) ;
  100.             virtual void unselect();
  101.             virtual void unfade(int icon) ;
  102.             virtual void unfade() ;
  103.          protected:
  104.             int max_icons ;
  105.             int num_icons ;
  106.             int *icons ;         // dynamic array
  107.          } ;
  108.  
  109. </pre>
  110.  
  111. <h2>Description</h2>
  112.  
  113. Icons are things in windows which can be clicked and dragged by the user.  They consist
  114. of the above class which is mapped to one or more WIMP icons (referred to by a number).
  115. You should derive new classes from the base class Icon (or IconSet) when you want an
  116. icon to do something (like react to a click for example).  The function 'click'
  117. is called when the user clicks on (one of) the WIMP icon(s) in the window.  by default,
  118. the Icon class ignored clicks.
  119. <p>
  120. For example, the following Icon is a button which calls the function 'do_compile'
  121. when the icon is clicked.  It is created within a window (called w) and is mapped
  122. onto an icon number within that window (set up by a template editor).
  123. <pre>
  124.  
  125. class Compile : public Icon
  126.    {
  127.    public:
  128.       Compile(Window *w, int icon) ;
  129.       void click(int mx, int my, int button, int icon) ;
  130.    } ;
  131.  
  132. Compile::Compile(Window *w, int icon) : Icon (w,icon)
  133.    {
  134.    }
  135.  
  136. void Compile::click(int mx, int my, int button, int icon)
  137.    {
  138.    do_compile() ;
  139.    }
  140.  
  141. </pre>
  142.  
  143. <h2>Members</h2>
  144.  
  145. <p>
  146. <a name="iconflags"></a>
  147. <h3>Icon::iconflags</h3>
  148.  
  149. This enumeration contains the defined flags for an icon.
  150.  
  151.  
  152. <p>
  153. <a name="buttontype"></a>
  154. <h3>Icon::buttontype</h3>
  155.  
  156. This enumeration contains defintions for the icon button types.
  157.  
  158.  
  159. <p>
  160. <a name="direction"></a>
  161. <h3>Icon::Direction</h3>
  162.  
  163. This enumeration defines values for the 'direction' parameter for one of
  164. the constructors.
  165.  
  166.  
  167. <p>
  168. <a name="colourmask"></a>
  169. <h3>Icon::ColourMask</h3>
  170.  
  171. This enumeration defines values for masking with the icon flags in order
  172. to set or read the icon colour.
  173.  
  174.  
  175. <p>
  176. <a name="ct1"></a>
  177. <h3>Icon::Icon (int priority, int window, int x0, int y0, int x1, int y1, 
  178.             iconflags flags, IconData *data, 
  179.             void *ref = 0)</h3>
  180.  
  181. This constructor create an icon given the raw data as required by Wimp_CreateIcon.
  182.  
  183.  
  184. <p>
  185. <a name="ct2"></a>
  186. <h3>Icon::Icon (Window *w, int iconnum = -1, void *ref = 0)</h3>
  187.  
  188. This constructor creates an icon in a window.  The 'iconnum' parameter is the
  189. icon number within the window definition.
  190.  
  191.  
  192. <p>
  193. <a name="ct3"></a>
  194. <h3>Icon::Icon()</h3>
  195.  
  196. This is the default constructor and does nothing.
  197.  
  198.  
  199. <p>
  200. <a name="ct4"></a>
  201. <h3>Icon::Icon (Window *w,Icon *temp, Direction direction = DOWN, int gap = 0, void *ref = 0)</h3>
  202.  
  203. This constructor creates an icon which is based on an existing icon.  It will
  204. copy the icon passed in 'temp' (for template) and move it either up, down,
  205. left or right depending on the value of 'direction'.  The amount to
  206. move is given in 'gap' and is on OS units.
  207.  
  208.  
  209. <p>
  210. <a name="ct5"></a>
  211. <h3>Icon::Icon (Window *w,Icon *temp, int x, int y, void *ref = 0)</h3>
  212.  
  213. This constructor will create a new icon by copying that passed in 'temp' (for
  214. template) and olace it at the coordinates passed in 'x' and 'y' (both in 
  215. window coordinates).
  216.  
  217.  
  218. <p>
  219. <a name="dt"></a>
  220. <h3>Icon::~Icon()</h3>
  221.  
  222. The iconic destructor (sounds sinister).
  223.  
  224.  
  225. <p>
  226. <a name="attach"></a>
  227. <h3>Icon::attach (Window *w, int iconnum)</h3>
  228.  
  229. This is used to attach a new icon to a window.
  230.  
  231.  
  232. <p>
  233. <a name="move1"></a>
  234. <h3>Icon::move (int dx, int dy)</h3>
  235.  
  236. Move the icon given the deltas 'dx' and 'dy'.  The icon is moved the
  237. appropriate distance and redrawn.
  238.  
  239.  
  240. <p>
  241. <a name="move2"></a>
  242. <h3>Icon::move (Direction direction, int dist)</h3>
  243.  
  244. Move the icon in a certain direction for a certain distance.
  245.  
  246.  
  247. <p>
  248. <a name="move_to"></a>
  249. <h3>Icon::move_to (int x, int y)</h3>
  250.  
  251. Move the icon to a certain position in the window.  I would have liked to
  252. call this function 'move' but C++ won't let me.
  253.  
  254.  
  255. <p>
  256. <a name="resize"></a>
  257. <h3>Icon:resize (int width, int height)</h3>
  258.  
  259. Change the size of the icon.  At present this uses the RISC OS 3.1 method
  260. or resizing by deleting and recreating the icon.
  261.  
  262.  
  263. <p>
  264. <a name="read_position"></a>
  265. <h3>Icon::read_position (Box &pos)</h3>
  266.  
  267. Read the position of the icon into the 4 word structure passed.
  268.  
  269.  
  270. <p>
  271. <a name="plot"></a>
  272. <h3>Icon::plot()</h3>
  273.  
  274. Plot the icon using Wimp_PlotIcon.
  275.  
  276.  
  277. <p>
  278. <a name="set_caret"></a>
  279. <h3>Icon::set_caret()</h3>
  280.  
  281. Set the caret inside the icon.  The icon should be writeable.
  282.  
  283.  
  284. <p>
  285. <a name="drag"></a>
  286. <h3>Icon::drag (int mx, int my, int buttons)</h3>
  287.  
  288. Begin a drag of the icon.  The parameters are in OS units.
  289.  
  290.  
  291. <p>
  292. <a name="redraw"></a>
  293. <h3>Icon::redraw (int x0, int y0, int x1, int y1)</h3>
  294.  
  295. Redraw the icon.  The parameters are in window coordinates.
  296.  
  297.  
  298. <p>
  299. <a name="click"></a>
  300. <h3>Icon::click (int mx, int my, int button, int icon)</h3>
  301.  
  302. The user has clicked on the icon.  The coordinates are in window
  303. coordinates.
  304.  
  305.  
  306. <p>
  307. <a name="key"></a>
  308. <h3>Icon::key (int icon,  int x, int y, int height, int index, int code)</h3>
  309.  
  310. A key has been pressed on the icon.
  311.  
  312.  
  313. <p>
  314. <a name="select"></a>
  315. <h3>Icon::select()</h3>
  316.  
  317. Select the icon.
  318.  
  319.  
  320. <p>
  321. <a name="unselect"></a>
  322. <h3>Icon::unselect()</h3>
  323.  
  324. Unselect the icon.
  325.  
  326.  
  327. <p>
  328. <a name="fade"></a>
  329. <h3>Icon::fade()</h3>
  330.  
  331. Fade the icon.
  332.  
  333.  
  334. <p>
  335. <a name="unfade"></a>
  336. <h3>Icon::unfade()</h3>
  337.  
  338. Unfade the icon.
  339.  
  340.  
  341. <p>
  342. <a name="set_fore_colour"></a>
  343. <h3>Icon::set_fore_colour(int colour), Icon::set_back_colour(int colour)</h3>
  344.  
  345. Set the foreground and background colour for the icon.
  346.  
  347.  
  348. <p>
  349. <a name="is_writeable"></a>
  350. <h3>Icon::is_writeable()</h3>
  351.  
  352. Returns whether the icon is writeable or not.  Non-zero means yes.
  353.  
  354.  
  355. <p>
  356. <a name="is_selected"></a>
  357. <h3>Icon::is_selected()</h3>
  358.  
  359. Returns whether the icon is selected or not.  Non-zero means yes.
  360.  
  361.  
  362. <p>
  363. <a name="print"></a>
  364. <h3>Icon::print (char *format...)</h3>
  365.  
  366. Write a string into the icon.  The parameter 'format' is a printf style format
  367. string and additional parameters contain the values to print.  The icon
  368. must be indirected.
  369.  
  370.  
  371. <p>
  372. <a name="change_sprite"></a>
  373. <h3>Icon::change_sprite (char *sprite_name, int area = 1)</h3>
  374.  
  375. Change the sprite of an icon to that named.  'area' is the
  376. sprite area in which the sprite resides, or the WIMP pool
  377. if it is 1.
  378.  
  379.  
  380. <p>
  381. <a name="read_sprite"></a>
  382. <h3>Icon::read_sprite (char *sprite_name)</h3>
  383.  
  384. Read the name of the sprite into the buffer passed.  The buffer must be 
  385. long enough.
  386.  
  387.  
  388. <p>
  389. <a name="reads"></a>
  390. <h3>Icon::read (char *s)</h3>
  391.  
  392. Read the contents of the icon into the buffer passed.  The buffer must be
  393. long enough.
  394.  
  395.  
  396. <p>
  397. <a name="readi"></a>
  398. <h3>Icon::read (int &n)</h3>
  399.  
  400. Read the contents of an icon containing an integer into the variable
  401. passed.
  402.  
  403.  
  404. <p>
  405. <a name="readf"></a>
  406. <h3>Icon::read (float &n)</h3>
  407.  
  408. Read the contents of an icon containing a single precision floating
  409. point number into the variable passed.
  410.  
  411.  
  412. <p>
  413. <a name="readd"></a>
  414. <h3>Icon::read (double &n)</h3>
  415.  
  416. Read the contents of an icon containing a double precision floating point
  417. number into the variable passed.
  418.  
  419.  
  420. <p>
  421. <a name="writes"></a>
  422. <h3>Icon::write (char *s)</h3>
  423.  
  424. Write the string passed into the icon's value.  The icon must
  425. be indirect and the value must be long enough to hold the string.
  426. long enough.
  427.  
  428.  
  429. <p>
  430. <a name="writei"></a>
  431. <h3>Icon::write (int &n)</h3>
  432.  
  433. Write an integer into the icon value.
  434.  
  435.  
  436. <p>
  437. <a name="writef"></a>
  438. <h3>Icon::write (float &n)</h3>
  439.  
  440. Write a single precision floating point number into the icon value.
  441.  
  442.  
  443. <p>
  444. <a name="writed"></a>
  445. <h3>Icon::write (double &n)</h3>
  446.  
  447. Write a double precision floating point number into the icon value.
  448.  
  449.  
  450.  
  451. <p>
  452. <a name="compare1"></a>
  453. <h3>Icon::compare (int icon)</h3>
  454.  
  455. Compare the icon number passed with my icon number.  Return non-zero if
  456. a match is found.
  457.  
  458.  
  459. <p>
  460. <a name="compare2"></a>
  461. <h3>Icon::compare (Icon *icon)</h3>
  462.  
  463. Compare the contents of the icon passed with my contents.  Both icons
  464. must be indirected.  The comparison is done by case insensitive
  465. string comparison.  The value returned is the difference between the
  466. first non matching characters.  This allows for sorting icons.  The
  467. value returned is similar to the C library strcmp function except case
  468. is not taken into account.
  469.  
  470. <p>
  471. <a name="display_menu"></a>
  472. <h3>Icon::display_menu (int x, int y, int button, int icon)</h3>
  473.  
  474. This function is the same as <a href="file:window#display_menu">Window::display_menu.</a>
  475. It is called when a menu is to be displayed for an Icon.
  476.  
  477. <p>
  478. <a name="pre_menu"></a>
  479. <h3> Window::pre_menu (Menu *m, int x, int y, int button, int icon)</h3>
  480.  
  481. This virtual function is called just before a menu is displayed on the
  482. screen.  The purpose is to allow the user to change the contents of the
  483. menu.
  484.  
  485.  
  486. <p>
  487. <a name="get_menu"></a>
  488. <h3> Window::get_menu (int x, int y, int button, int icon)</h3>
  489.  
  490. This is called when there was no default menu provided to the constructor.
  491. It is a virtual function which should be supplied by a derived class
  492. if it needs to decide on a number of menus.  It returns the name
  493. of the menu to display.
  494.  
  495. <p>
  496. <a name="help"></a>
  497. <h3> Icon::help (int mx, int my, int buttons)</h3>
  498.  
  499. This function is called when help is being requested.  The default
  500. action is to return NULL, meaning that the icon is not prepared
  501. to give anything away.  Derived classes may provide their own
  502. help function.  The function return a string (char *) which
  503. is a pointer to the help text.
  504. <p>
  505. The function will be called when the mouse is over the Icon.
  506.  
  507.  
  508. <p>
  509. <a name="handle"></a>
  510. <h3>Icon::handle</h3>
  511.  
  512. This is the WIMP handle for the icon.
  513.  
  514.  
  515. <p>
  516. <a name="window"></a>
  517. <h3>Icon::window</h3>
  518.  
  519. This is the window to which the icon belongs.  NULL means that it is a
  520. free standing icon.
  521.  
  522.  
  523. <p>
  524. <a name="user_ref"></a>
  525. <h3>Icon::user_ref</h3>
  526.  
  527. This is a void * pointer holding a user supplied reference for the icon.
  528.  
  529.