home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / datafiles / text / c_manual / intuition / miscellaneous / miscellaneous.doc < prev    next >
Text File  |  1995-02-27  |  34KB  |  1,007 lines
  1. 9    MISCELLANEOUS
  2.  
  3. 9.1  INTRODUCTION
  4.  
  5. This is the last chapter about Intuition, and we will therefore
  6. finish of by discussing some special features.
  7.  
  8.  
  9.  
  10. 9.2  MEMORY
  11.  
  12. If you write C programs you will often need to allocate some
  13. memory. This process is normally referred as "dynamic memory
  14. allocation" and is used whenever your program needs some more
  15. memory while it is running.
  16.  
  17. When you allocate memory you need to specify how much you want,
  18. and what type of memory (Fast or Chip). "Exec" will then try to
  19. allocated the memory, and will return a pointer to the memory,
  20. or NULL if it could not find a block big enough.
  21.  
  22. Once you have allocated the memory, you can use it as much as
  23. you want. You just have to remember that before the program
  24. terminates it must have deallocated all allocated memory. If
  25. you forget to deallocate the memory when you leave, it will
  26. be lost, and the only way to get it back is to reboot.
  27.  
  28.  
  29.  
  30. 9.2.1  ALLOCATE MEMORY
  31.  
  32. You usually use the function AllocMem() if you want to allocate
  33. memory. You only need to specify how much memory you need, and
  34. what type of memory (Chip, Fast etc), and AllocMem() will
  35. return a pointer to the new memory, or NULL if no memory could
  36. be allocated.
  37.  
  38. Synopsis: memory = AllocMem( size, type );
  39.  
  40. memory:   (void *) Pointer to the new allocated memory, or NULL
  41.           if no memory could be allocated. Remember! Never use
  42.           memory which you have not successfully allocated.
  43.  
  44. size:     (long) The size (in bytes) of the memory you want.
  45.           (AllocMem() always allocates memory in multiples of
  46.           eight bytes. So if you only ask for 9 bytes, Exec
  47.           would actually give you 16 Bytes (2*8).)
  48.  
  49. type:     (long) You need to choose one of the three following
  50.           types of memory (see chapter 0 INTRODUCTION for more
  51.           information about Chip and Fast memory). (The flags
  52.           are declared in the header file "exec/memory.h".)
  53.  
  54.           MEMF_CHIP   Chip memory. This memory can be accessed
  55.                       by both the main processor, as well as
  56.                       the Chips. Graphics/Sound data MUST 
  57.                       therefore be placed in Chip memory. If it
  58.                       does not matter what type of memory you
  59.                       get (Fast or Chip), you should try to
  60.                       allocate Fast memory before you allocate
  61.                       Chip memory. (Chip memory is more valuable
  62.                       than Fast memory.)
  63.  
  64.           MEMF_FAST   Fast memory. This memory can only be
  65.                       accessed by the main processor. (Graphics
  66.                       and Sound data can NOT be stored in Fast
  67.                       memory, use Chip memory.) This memory is
  68.                       normally a little bit faster than Chip
  69.                       memory, since only the main processor is
  70.                       working with it, and it is not disturbed
  71.                       by the Chips.
  72.  
  73.           MEMF_PUBLIC If it does not matter what type of memory
  74.                       you get (you do not intend to use the
  75.                       memory for Graphics/Sound data), you
  76.                       should use Fast memory. However, all
  77.                       Amigas do not have Fast memory, since
  78.                       you need to by a memory expansion in
  79.                       order to get it. If want to tell Exec
  80.                       that you would like to use Fast memory if
  81.                       there is any, else use Chip memory, you
  82.                       should ask for MEMF_PUBLIC.
  83.  
  84.           If you want the allocated memory to be cleared
  85.           (initialized to zeros), you should set the flag
  86.           MEMF_CLEAR.
  87.  
  88. If you need to allocate 150 bytes of Chip memory, you would
  89. write:
  90.  
  91. /* Declare a pointer to the memory you are going to allocate: */
  92. CPTR memory; /* CPTR means memory pointer, declared in the    */
  93.              /* header file "exec/types.h". "exec/types.h" is */
  94.              /* automatically included when you include the   */
  95.              /* header file "intuition/intuition.h".          */
  96.  
  97. /* Allocate 150 bytes of Chip memory: */
  98. memory = (CPTR) AllocMem( 150, MEMF_CHIP );
  99.  
  100. /* Have we allocated the memory successfully? */
  101. if( memory == NULL )
  102.   /* ERROR! Have not allocated any memory! */
  103.  
  104.  
  105.  
  106. 9.2.2  DEALLOCATE MEMORY
  107.  
  108. All memory that has been allocated MUST be deallocated before
  109. your program terminates. If you forget to deallocate memory
  110. which you have allocated, that memory would be forever lost.
  111. The only way of freeing such memory is to reboot. (Not to be
  112. recommended. We are not Demo-writers, are we?)
  113.  
  114. You free allocated memory by calling the function FreeMem():
  115.  
  116. Synopsis: FreeMem( memory, size );
  117.  
  118. memory    (void *) Pointer to some memory which has previously
  119.           been allocated. Remember! Never deallocate memory,
  120.           which you have not allocated, and never use memory
  121.           which has been deallocated.
  122.  
  123. size      (long) The size (in bytes) of the memory you want to
  124.           deallocate.
  125.  
  126.  
  127. To deallocate the 150 bytes of Chip memory we have previously
  128. allocated, we write:
  129.  
  130. /* Free 150 bytes of memory: */
  131. FreeMem( memory, 150 );
  132.  
  133.  
  134.  
  135. 9.2.3  REMEMBER MEMORY
  136.  
  137. If you allocate memory several times, and in different
  138. quantities, it can be very hard to remember to deallocate all
  139. memory correctly. However, do not despair. Intuition have a
  140. solution for you. You can use the function AllocRemember()
  141. which calls the function AllocMem(), but will also allocate
  142. memory for a Remember structure which is automatically
  143. initialized for you. Every time you allocate memory with the
  144. AllocRemember() function, the Remember structures are linked
  145. together, and the information about the memory (size and
  146. position) is remembered. Once you want to deallocate the
  147. memory, you only need to call the function FreeRemember(), and
  148. all memory is deallocated for you automatically.
  149.  
  150. The Remember structure look like this:
  151.  
  152. struct Remember
  153. {
  154.   struct Remember *NextRemember;
  155.   ULONG RememberSize;
  156.   UBYTE *Memory;
  157. };
  158.  
  159.  
  160. The AllocRemember() function is called like this: (Very similar
  161. to the AllocMem() function.)
  162.  
  163. Synopsis: memory = AllocRemember( remember, size, type );
  164.  
  165. memory:   (char *) Pointer to the new allocated memory, or NULL
  166.           if no memory could be allocated. Remember! Never use
  167.           memory which you have not successfully allocated.
  168.  
  169. remember: (struct Remember **) Address of a pointer to a
  170.           Remember structure. Before you call the AllocRemember()
  171.           function for the first time you should set this
  172.           pointer to NULL. (Note that it is a pointer to a
  173.           pointer!)
  174.  
  175. size:     (long) The size (in bytes) of the memory you want.
  176.           (AllocMem() always allocates memory in multiples of
  177.           eight bytes. So if you only ask for 29 bytes, Exec
  178.           would actually give you 32 Bytes (4*8).)
  179.  
  180. type:     (long) You need to choose one of the three following
  181.           types of memory (see chapter 0 INTRODUCTION for more
  182.           information about Chip and Fast memory):
  183.  
  184.           MEMF_CHIP   Chip memory. This memory can be accessed
  185.                       by both the main processor, as well as
  186.                       the Chips. Graphics/Sound data MUST 
  187.                       therefore be placed in Chip memory. If it
  188.                       does not matter what type of memory you
  189.                       get (Fast or Chip), you should try to
  190.                       allocate Fast memory before you allocate
  191.                       Chip memory. (Chip memory is more valuable
  192.                       than Fast memory.)
  193.  
  194.           MEMF_FAST   Fast memory. This memory can only be
  195.                       accessed by the main processor. (Graphics
  196.                       and Sound data can NOT be stored in Fast
  197.                       memory, use Chip memory.) This memory is
  198.                       normally a little bit faster than Chip
  199.                       memory, since only the main processor is
  200.                       working with it, and it is not disturbed
  201.                       by the Chips.
  202.  
  203.           MEMF_PUBLIC If it does not matter what type of memory
  204.                       you get (you do not intend to use the
  205.                       memory for Graphics/Sound data), you
  206.                       should use Fast memory. However, all
  207.                       Amigas do not have Fast memory, since
  208.                       you need to by a memory expansion in
  209.                       order to get it. If want to tell Exec
  210.                       that you would like to use Fast memory if
  211.                       there is any, else use Chip memory, you
  212.                       should ask for MEMF_PUBLIC.
  213.  
  214.           If you want the allocated memory to be cleared
  215.           (initialized to zeros), you should set the flag
  216.           MEMF_CLEAR.
  217.  
  218.  
  219. When you want to deallocate the memory you only need to call
  220. the function FreeRemember() function. You can if you want,
  221. deallocate only the Remember structures, and take care of the
  222. deallocation yourself, but be careful. The FreeRemember()
  223. function is called like this:
  224.  
  225. Synopsis:   FreeRemember( remember, everything );
  226.  
  227. remember:   (struct Remember **) Address of a pointer to the
  228.             first Remember structure (initialized by the
  229.             AllocRemember() function). (Note that it is a pointer
  230.             to a pointer!)
  231.  
  232. everything: (long) A boolean value. If everything is equal to
  233.             TRUE, all memory (both the allocated memory and the
  234.             Remember structures) are deallocated. However, if
  235.             everything is equal to FALSE, only the Remember
  236.             structures are deallocated, and you have to
  237.             deallocate the memory yourself.
  238.  
  239.  
  240. Here is a short example which shows how to use the
  241. AllocRemember(), and the FreeRemember() functions:
  242.  
  243. struct Remember *remember = NULL;
  244. CPTR memory1, memory2, memory3;
  245.  
  246. /* Allocate 350 bytes of Chip memory, which is cleared: */
  247. memory1 = AllocRemember( &remember, 350, MEMF_CHIP|MEMF_CLEAR );
  248.  
  249. if( memory1 == NULL )
  250.   Clean up and leave;
  251.  
  252. /* Allocate 900 bytes of memory (any type, Fast if possible): */
  253. memory2 = AllocRemember( &remember, 900, MEMF_PUBLIC );
  254.  
  255. if( memory2 == NULL )
  256.   Clean up and leave;
  257.  
  258. /* Allocate 100 bytes of Chip memory: *
  259. memory3 = AllocRemember( &remember, 100, MEMF_CHIP );
  260.  
  261. if( memory3 == NULL )
  262.   Clean up and leave;
  263.  
  264. ...
  265.  
  266.  
  267. /* Deallocate all memory with one single call: */
  268. FreeRemember( &remember, TRUE );
  269.  
  270.  
  271. If we wanted, we could have deallocated all Remember
  272. structures, and then deallocate the memory ourself with help
  273. of the normal FreeMem() function:
  274.  
  275. /* Deallocate only the Remember structures: */
  276. FreeRemember( &remember, FALSE );
  277. FreeMem( memory1, 350 );
  278. FreeMem( memory2, 900 );
  279. FreeMem( memory3, 100 );
  280.  
  281.  
  282.  
  283. 9.3  PREFERENCES
  284.  
  285. When the system starts up, Intuition is initialized to some
  286. default values. However, if there exist a file called:
  287. "system-configuration" in the "devs" directory on the system
  288. disk, that file is used to set the system values, instead of
  289. the default values.
  290.  
  291. The user can with the "Preferences" program change the system
  292. values, and/or the "system-configuration" file. If the user
  293. selects the "USE" command, only the system values are changed,
  294. while if the user selects the "SAVE" command, both the system
  295. values, as well as the "system-configuration" file are updated.
  296.  
  297. Your program can get a copy of the system values by calling the
  298. function GetPrefs(). If you want to get a copy of the default
  299. values you use the function GetDefPrefs(). When you get a copy
  300. of the Preferences data, you can decide how much data you want
  301. copied. You can therefore, if you want, only copy parts of the
  302. structure, and do not need to allocate memory for the whole
  303. structure. The most important values are because of that placed
  304. in the beginning of the structure. The Preferences structure
  305. look like this: (See file "intuition/preferences.h" for more
  306. information. It is on the fourth Lattice C disk, in the
  307. "Compiler_Headers" directory.)
  308.  
  309. struct Preferences
  310. {
  311.   BYTE FontHeight;
  312.   UBYTE PrinterPort;
  313.   USHORT BaudRate;
  314.   struct timeval KeyRptSpeed;
  315.   struct timeval KeyRptDelay;
  316.   struct timeval DoubleClick;
  317.   USHORT PointerMatrix[POINTERSIZE];
  318.   BYTE XOffset;
  319.   BYTE YOffset;
  320.   USHORT color17;
  321.   USHORT color18;
  322.   USHORT color19;
  323.   USHORT PointerTicks;
  324.   USHORT color0;
  325.   USHORT color1;
  326.   USHORT color2;
  327.   USHORT color3;
  328.   BYTE ViewXOffset;
  329.   BYTE ViewYOffset;
  330.   WORD ViewInitX, ViewInitY;
  331.   BOOL EnableCLI;
  332.   USHORT PrinterType;
  333.   UBYTE PrinterFilename[FILENAME_SIZE];
  334.   USHORT PrintPitch;
  335.   USHORT PrintQuality;
  336.   USHORT PrintSpacing;
  337.   UWORD PrintLeftMargin;
  338.   UWORD PrintRightMargin;
  339.   USHORT PrintImage;
  340.   USHORT PrintAspect;
  341.   USHORT PrintShade;
  342.   WORD PrintThreshold;
  343.   USHORT PaperSize;
  344.   UWORD PaperLength;
  345.   USHORT PaperType;
  346.   UBYTE SerRWBits;
  347.   UBYTE SerStopBuf;
  348.   UBYTE SerParShk;
  349.   UBYTE LaceWB;
  350.   UBYTE WorkName[FILENAME_SIZE];
  351.   BYTE RowSizeChange;
  352.   BYTE ColumnSizeChange;
  353.   UWORD PrintFlags;
  354.   UWORD PrintMaxWidth;
  355.   UWORD PrintMaxHeight;
  356.   UBYTE PrintDensity;
  357.   UBYTE PrintXOffset;
  358.   UWORD wb_Width;
  359.   UWORD wb_Height;
  360.   UBYTE wb_Depth;
  361.   UBYTE ext_size;
  362. };
  363.  
  364. You call the function GetPrefs() like this:
  365.  
  366. Synopsis: pref = GetPrefs( buffer, size );
  367.  
  368. pref:     (struct Preferences *) Pointer to your preferences.
  369.           Same as your memory pointer (buffer), but is returned
  370.           so you can check if you got a copy or not. If you
  371.           could not get a copy of the preferences, the function
  372.           returns NULL.
  373.  
  374. buffer:   (struct Preferences *) Pointer to the memory buffer
  375.           which should be used to store a copy of the
  376.           preferences in.
  377.  
  378. size:     (long) The number of bytes you want to copy to the
  379.           buffer. Important, the buffer must be at least as big
  380.           as the number of bytes you want to copy.
  381.  
  382.  
  383. You call the function GetDefPrefs() like this:
  384.  
  385. Synopsis: pref = GetPrefs( buffer, size );
  386.  
  387. pref:     (struct Preferences *) Pointer to the default
  388.           preferences. If the function could not make a copy of
  389.           the preferences, the function returns NULL.
  390.  
  391. buffer:   (struct Preferences *) Pointer to the memory buffer
  392.           which should be used to store a copy of the
  393.           default preferences in.
  394.  
  395. size:     (long) The number of bytes you want to copy to the
  396.           buffer. Important, the buffer must be at least as big
  397.           as the number of bytes you want to copy.
  398.  
  399.  
  400. Here is an example on how to get a copy of the current
  401. preferences:
  402.  
  403. /* Declare a preferences structure: */
  404. struct Preferences pref;
  405.  
  406. /* Try to get a copy of the current preferences: */
  407. if( GetPrefs( &pref, sizeof(pref) ) == NULL )
  408.   /* Could not get a copy of the preferences! */
  409.  
  410.  
  411. Once you have got a copy of the current/default preferences we
  412. can start to check the settings.
  413.  
  414.  
  415. You can, if you want, change some values, and then save them
  416. as new preferences. IMPORTANT! You should never mess with the
  417. settings since it is the user's own preferences, and should
  418. therefore NOT be changed unless the user really WANT to alter
  419. them.
  420.  
  421. You set new preferences by calling the function SetPrefs():
  422.  
  423. Synopsis: SetPrefs( pref, size, doit );
  424.  
  425. pref:     (struct Preferences *) Pointer to your modified
  426.           Preferences structure.
  427.  
  428. size:     (long) The number of bytes you want to change.
  429.  
  430. doit:     (long) Boolean value which if FALSE, changes the
  431.           preferences, but will not send a NEWPREFS message.
  432.           If doit is equal to TRUE, the settings will be
  433.           changed, and a NEWPREFS message will be sent.
  434.           As long as the user is changing the values, doit
  435.           should be FALSE, but when the user has finished,
  436.           set it to TRUE, and all programs will get a NEWPREFS
  437.           message. 
  438.  
  439.  
  440.  
  441. 9.4  WARNINGS
  442.  
  443. There exist three levels of warnings you can give the user when
  444. something goes wrong:
  445.  
  446. 1. If you just want to get the users attention about something,
  447.    but nothing really dangerous has happened, you should call
  448.    the function DisplayBeep(). It will flash the colours of the
  449.    screen.
  450.    
  451.    Synopsis: DisplayBeep( screen );
  452.    
  453.    screen:   (struct Screen *) Pointer to the screen, which
  454.              colours you want to flash. If you have not opened
  455.              a screen yourself (you are using the Workbench
  456.              Screen), you can find a pointer to that screen
  457.              in the Window structure: (my_window is a pointer
  458.              to an opened window)
  459.              DisplayBeep( my_window->WScreen );
  460.  
  461.  
  462. 2. If something important has happened, or if you want the user
  463.    to take some action (select something) etc, open a Requester.
  464.    (See chapter 5 REQUESTERS for more information.)
  465.  
  466.  
  467. 3. If something TERRIBLE is happening, the system is breaking
  468.    down, open an Alert. (See chapter 6 ALERTS for more
  469.    information.)
  470.  
  471.  
  472.  
  473. 9.5  DOUBLE CLICK
  474.  
  475. There are five different mouse actions:
  476.  
  477. 1. Press a button         The user can press on a button.
  478.  
  479. 2. Release a button       The user can release a previously
  480.                           pressed button.
  481.  
  482. 3. Click a button         Quickly pressing and releasing
  483.                           a button.
  484.  
  485. 4. Double-click a button  Quickly pressing/releasing a button
  486.                           twice.
  487.  
  488. 5. Drag                   Hold a button pressed, while moving
  489.                           the mouse.
  490.  
  491.  
  492. Use the IDCMP flags SELECTDOWN, SELECTUP, MENUDOWN, and MENUUP
  493. in order to receive mouse-buttons events. (See chapter 8 IDCMP for
  494. more information.)
  495.  
  496. If you want to check if the user double-clicked one of the
  497. mouse buttons, you can use the function DoubleClick(). You give
  498. the function the current as well as the previous time when the
  499. button was pressed, and it will check the preferences and
  500. return TRUE if the two button events happened within the time
  501. limit. (The user can change the time limit for double-clicking
  502. events.)
  503.  
  504. Synopsis: double = DoubleClick( sec1, mic1, sec2, mic2 );
  505.  
  506. double:   (long) If the two button events happened within the
  507.           current time limit, the function will return TRUE,
  508.           else it will return FALSE.
  509.  
  510. sec1:     (long) Time (seconds) when the button was pressed for
  511.           the first time.
  512.  
  513. mic1:     (long) Time (micros) when the button was pressed for
  514.           the first time.
  515.  
  516. sec2:     (long) Current time (seconds).
  517.  
  518. mic2:     (long) Current Time (micros).
  519.  
  520.  
  521. Here is a short example on how to check double-click events:
  522.  
  523. struct IntuiMessage *message;
  524. ULONG sec1, mic1, sec2, mic2; 
  525.  
  526. ... ... ...
  527.  
  528. if( message->Class == MOUSEBUTTONS )
  529. {
  530.   /* A mouse button was pressed/released. */
  531.   if( message->Code == SELECTDOWN )
  532.   {
  533.     /* The left mouse button was pressed. */
  534.  
  535.     /* Save the old time: */
  536.     sec2 = sec1;
  537.     mic2 = mic1;
  538.     
  539.     /* Get the new time: */
  540.     sec1 = message->Seconds;
  541.     mic1 = message->Micros;
  542.     
  543.     /* Check if it was a double-click or not: */
  544.     if( DoubleClick( sec2, mic2, sec1, mic1 ) )
  545.     {
  546.       printf("Double-Click!\n");
  547.       /* Reset the values: */
  548.       sec1 = 0;
  549.       mic1 = 0;
  550.     }
  551.   }
  552. }
  553.  
  554.  
  555.  
  556. 9.6  TIME
  557.  
  558. You can get the current time by calling the function
  559. CurrentTime():
  560.  
  561. Synopsis: CurrentTime( seconds, micros );
  562.  
  563. seconds:  (long *) Pointer to an ULONG variable which will be
  564.           initialized with the current seconds stamp.
  565.  
  566. micros:   (long *) Pointer to an ULONG variable which will be
  567.           initialized with the current micros stamp.
  568.  
  569.  
  570. Here is a short example:
  571.  
  572. ULONG seconds, micros;
  573.  
  574. CurrentTime( &seconds, µs );
  575.  
  576.  
  577.  
  578. 9.7  STYLE
  579.  
  580. Since Intuition is the interface between computer and the user,
  581. it is important that there are some standards concerning
  582. gadgets, requesters, menus, mouse, etc. If similar programs
  583. use the same type of style, the user will much faster learn to
  584. handle them. You, as the programmer, have therefore to make sure
  585. that your program is easily understandable and foolproof. Make
  586. your program easy to learn, and fun to handle!
  587.  
  588.  
  589.  
  590. 9.7.1  GADGETS
  591.  
  592. Remember to make the gadgets easily recognizable, and
  593. understandable. Put short words like "CANCEL", "OK" in the
  594. gadget, or use graphics symbols. Remember to disable (ghosted)
  595. a gadget when it becomes nonfunctional.
  596.  
  597.  
  598.  
  599. 9.7.2  REQUESTERS
  600.  
  601. Requesters have two main functions: They can inform the user
  602. about something, and/or ask the user to take some action. It is
  603. therefore important that it is easy for the user to understand
  604. what has or will happen, and what he/she has to do. Use
  605. colourful graphics if necessary, and remember that if you want
  606. some action from the user, always give him/her a way out
  607. without affecting anything (CANCEL).
  608.  
  609. A requester which is meaningless should be taken away. Use the
  610. functions EndRequest(), ClearDMRequest().
  611.  
  612. Place the OK/YES/TRUE gadget (if there exist one) in the bottom
  613. left corner, and the CANCEL/NO/FALSE gadget in the bottom right
  614. corner. There should always be an escape (CANCEL) gadget in
  615. every requester!
  616.  
  617. ---------------------------
  618. | OK to delete file?      |
  619. |                         |
  620. | ----------   ---------- |
  621. | | DELETE |   | CANCEL | |  
  622. | ----------   ---------- |
  623. ---------------------------
  624.  
  625.  
  626.  
  627. 9.7.3  MENUS
  628.  
  629. Menu items/subitems which are nonfunctional should be disabled
  630. (ghosted). Use the function OffMenu().
  631.  
  632. There are two menus, project and edit menu, which many program
  633. will use, and should therefore look something like this:
  634.  
  635. PROJECT
  636.  
  637. Item      Function
  638. ---------------------------------------------------------------
  639. New       Creates a new project.
  640. Open      Opens an old project.
  641. Save      Saves current project.
  642. Save as   Saves current project under a new name.
  643. Print     Prints the whole project.
  644. Print as  Prints parts of a project, and/or with new settings.
  645. Quit      Quits. Remember to ask the user if he/she really
  646.           wants to quit, and if he/she wants to save the
  647.           project. 
  648.  
  649.  
  650. EDIT
  651.  
  652. Item      Function
  653. ---------------------------------------------------------------
  654.  
  655. Undo      Undoes the last operation.
  656. Cut       Cuts a part away, and stores it in the Clipboard. 
  657. Copy      Copies a part of the project into the Clipboard.
  658. Paste     Puts a copy of the Clipboard into the project.
  659. Erase     Deletes a part of the project without putting it into
  660.           the Clipboard.
  661.  
  662.  
  663. Remember to enable shortcuts for often used menu-functions.
  664. Here are some standard command key styles:
  665.  
  666. Amiga + key  Function
  667. ---------------------------------------------------------------
  668.  
  669.   N          New
  670.   O          Open
  671.   S          Save
  672.   Q          Quit
  673.  
  674.   U          Undo
  675.   X          Cut
  676.   C          Copy
  677.   P          Past
  678.  
  679.  
  680.  
  681. 9.7.4  MOUSE
  682.  
  683. The left mouse button is used for "selection", while the right
  684. mouse button is used for "information transfer". The left mouse
  685. button is therefore used for selecting gadgets etc, while menu
  686. functions and double-menu requesters etc, use the right mouse
  687. button.
  688.  
  689.  
  690.  
  691. 9.8  FUNCTIONS
  692.  
  693. AllocMem()
  694.  
  695.   This function allocates memory. You specifies what type and
  696.   how much you want, and it returns a pointer to the allocated
  697.   memory, or NULL if there did not exist enough memory.
  698.  
  699.   Synopsis: memory = AllocMem( size, type );
  700.  
  701.   memory:   (void *) Pointer to the new allocated memory, or
  702.             NULL if no memory could be allocated. Remember!
  703.             Never use memory which you have not successfully
  704.             allocated.
  705.  
  706.   size:     (long) The size (in bytes) of the memory you want.
  707.             (AllocMem() always allocates memory in multiples of
  708.             eight bytes. So if you only ask for 9 bytes, Exec
  709.             would actually give you 16 Bytes (2*8).)
  710.  
  711.   type:     (long) You need to choose one of the three
  712.             following types of memory (see chapter 0
  713.             INTRODUCTION for more information about Chip and
  714.             Fast memory):
  715.  
  716.             MEMF_CHIP   Chip memory. This memory can be
  717.                         accessed by both the main processor, as
  718.                         well as the Chips. Graphics/Sound data
  719.                         MUST therefore be placed in Chip memory.
  720.                         If it does not matter what type of 
  721.                         memory you get (Fast or Chip), you
  722.                         should try to allocate Fast memory
  723.                         before you allocate Chip memory. (Chip
  724.                         memory is more valuable than Fast
  725.                         memory.)
  726.  
  727.             MEMF_FAST   Fast memory. This memory can only be
  728.                         accessed by the main processor.
  729.                         (Graphics and Sound data can NOT be
  730.                         stored in Fast memory, use Chip memory.)
  731.                         This memory is normally a little bit
  732.                         faster than Chip memory, since only the
  733.                         main processor is working with it, and
  734.                         it is not disturbed by the Chips.
  735.  
  736.             MEMF_PUBLIC If it does not matter what type of
  737.                         memory you get (you do not intend to
  738.                         use the memory for Graphics/Sound data),
  739.                         you should use Fast memory. However,
  740.                         all Amigas do not have Fast memory,
  741.                         since you need to by a memory expansion
  742.                         in order to get it. If want to tell
  743.                         Exec that you would like to use Fast
  744.                         memory if there is any, else use Chip
  745.                         memory, you should ask for MEMF_PUBLIC.
  746.  
  747.             If you want the allocated memory to be cleared
  748.             (initialized to zeros), you should set the flag
  749.             MEMF_CLEAR.
  750.  
  751.  
  752.  
  753. FreeMem()
  754.  
  755.   This function deallocated previously allocated memory.
  756.   Remember to deallocate all memory you have taken, and never
  757.   deallocate memory which you have not taken.
  758.  
  759.   Synopsis: FreeMem( memory, size );
  760.  
  761.   memory    (void *) Pointer to some memory which has
  762.             previously been allocated. Remember! never use
  763.             memory which has been deallocated.
  764.  
  765.   size      (long) The size (in bytes) of the memory you want
  766.             to deallocate.
  767.  
  768.  
  769.  
  770. AllocRemember()
  771.  
  772.   This function allocates both memory (same as AllocMem), but
  773.   will also allocate space for a Remember structure which are
  774.   initialized with the size of the allocated memory, and a
  775.   pointer to that memory. Each time the program allocates
  776.   memory with this function, the Remember structures are linked
  777.   together.
  778.   
  779.   Since the Remember structures contains all necessary
  780.   information about the memory, and are linked together, all
  781.   memory can be deallocated with one single function call
  782.   (FreeRemember()).
  783.  
  784.   Synopsis: memory = AllocRemember( remember, size, type );
  785.  
  786.   memory:   (char *) Pointer to the new allocated memory, or
  787.             NULL if no memory could be allocated. Remember!
  788.             Never use memory which you have not successfully
  789.             allocated.
  790.  
  791.   remember: (struct Remember **) Address of a pointer to a
  792.             Remember structure. Before you call the
  793.             AllocRemember() function for the first time you
  794.             should set this pointer to NULL. (Note that it is
  795.             a pointer to a pointer!)
  796.  
  797.   size:     (long) The size (in bytes) of the memory you want.
  798.             (AllocMem() always allocates memory in multiples of
  799.             eight bytes. So if you only ask for 9 bytes, Exec
  800.             would actually give you 16 Bytes (2*8).)
  801.  
  802.   type:     (long) You need to choose one of the three
  803.             following types of memory (see chapter 0
  804.             INTRODUCTION for more information about Chip and
  805.             Fast memory):
  806.  
  807.             MEMF_CHIP   Chip memory. This memory can be
  808.                         accessed by both the main processor, as
  809.                         well as the Chips. Graphics/Sound data
  810.                         MUST therefore be placed in Chip memory.
  811.                         If it does not matter what type of 
  812.                         memory you get (Fast or Chip), you
  813.                         should try to allocate Fast memory
  814.                         before you allocate Chip memory. (Chip
  815.                         memory is more valuable than Fast
  816.                         memory.)
  817.  
  818.             MEMF_FAST   Fast memory. This memory can only be
  819.                         accessed by the main processor.
  820.                         (Graphics and Sound data can NOT be
  821.                         stored in Fast memory, use Chip memory.)
  822.                         This memory is normally a little bit
  823.                         faster than Chip memory, since only the
  824.                         main processor is working with it, and
  825.                         it is not disturbed by the Chips.
  826.  
  827.             MEMF_PUBLIC If it does not matter what type of
  828.                         memory you get (you do not intend to
  829.                         use the memory for Graphics/Sound data),
  830.                         you should use Fast memory. However,
  831.                         all Amigas do not have Fast memory,
  832.                         since you need to by a memory expansion
  833.                         in order to get it. If want to tell
  834.                         Exec that you would like to use Fast
  835.                         memory if there is any, else use Chip
  836.                         memory, you should ask for MEMF_PUBLIC.
  837.  
  838.             If you want the allocated memory to be cleared
  839.             (initialized to zeros), you should set the flag
  840.             MEMF_CLEAR.
  841.  
  842.  
  843.  
  844. FreeRemember()
  845.  
  846.   This function deallocates all memory which has been allocated
  847.   by the AllocRemember() function. Note, you can deallocate all
  848.   Remember structures only, and deallocate the memory yourself,
  849.   if you want to.
  850.  
  851.   Synopsis:   FreeRemember( remember, everything );
  852.  
  853.   remember:   (struct Remember **) Address of a pointer to the
  854.               first Remember structure (initialized by the
  855.               AllocRemember() function). (Note that it is a
  856.               pointer to a pointer!)
  857.  
  858.   everything: (long) A boolean value. If everything is equal
  859.               to TRUE, all memory (both the allocated memory
  860.               and the Remember structures) are deallocated.
  861.               However, if everything is equal to FALSE, only
  862.               the Remember structures are deallocated, and you
  863.               have to deallocate the memory yourself.
  864.  
  865.  
  866.  
  867. GetPrefs()
  868.  
  869.   This function makes a copy of the Preferences structure.
  870.  
  871.   Synopsis: pref = GetPrefs( buffer, size );
  872.  
  873.   pref:     (struct Preferences *) Pointer to your preferences.
  874.             Same as your memory pointer (buffer), but is
  875.             returned so you can check if you got a copy or not.
  876.             If you could not get a copy of the preferences, the
  877.             function returns NULL.
  878.  
  879.   buffer:   (struct Preferences *) Pointer to the memory buffer
  880.             which should be used to store a copy of the
  881.             preferences in.
  882.  
  883.   size:     (long) The number of bytes you want to copy to the
  884.             buffer. Important, the buffer must be at least as
  885.             big as the number of bytes you want to copy.
  886.  
  887.  
  888.  
  889. GetDefPrefs()
  890.  
  891.   This function makes a copy of the default Preferences
  892.   structure.
  893.  
  894.   Synopsis: pref = GetPrefs( buffer, size );
  895.  
  896.   pref:     (struct Preferences *) Pointer to the default
  897.             preferences. If the function could not make a copy
  898.             of the preferences, the function returns NULL.
  899.  
  900.   buffer:   (struct Preferences *) Pointer to the memory buffer
  901.             which should be used to store a copy of the default
  902.             preferences in.
  903.  
  904.   size:     (long) The number of bytes you want to copy to the
  905.             buffer. Important, the buffer must be at least as
  906.             big as the number of bytes you want to copy.
  907.  
  908.  
  909.  
  910. SetPrefs()
  911.  
  912.   This function saves a modified preferences structure. Do NOT
  913.   change the preferences unless the user really WANTS to!
  914.  
  915.   Synopsis: SetPrefs( pref, size, doit );
  916.  
  917.   pref:     (struct Preferences *) Pointer to your modified
  918.             Preferences structure.
  919.  
  920.   size:     (long) The number of bytes you want to change.
  921.  
  922.   doit:     (long) Boolean value which if FALSE, changes the
  923.             preferences, but will not send a NEWPREFS message.
  924.             If doit is equal to TRUE, the settings will be
  925.             changed, and a NEWPREFS message will be sent.
  926.             As long as the user is changing the values, doit
  927.             should be FALSE, but when the user has finished,
  928.             set it to TRUE, and all programs will get a NEWPREFS
  929.             message.
  930.  
  931.  
  932.  
  933. DisplayBeep()
  934.  
  935.   This function flashes the screen's colours. Can be used
  936.   whenever you want to catch the user's attention.
  937.  
  938.   Synopsis: DisplayBeep( screen );
  939.    
  940.   screen:   (struct Screen *) Pointer to the screen, which
  941.             colours you want to flash. If you have not opened
  942.             a screen yourself (you are using the Workbench
  943.             Screen), you can find a pointer to that screen
  944.             in the Window structure: (my_window is a pointer
  945.             to an opened window)
  946.             DisplayBeep( my_window->WScreen );
  947.  
  948.  
  949.  
  950. DoubleClick()
  951.  
  952.   This function checks if the user double-clicked on one of the
  953.   mouse buttons. You give the function the current as well as
  954.   the previous time when the button was pressed, and it will
  955.   check the preferences and return TRUE if the two button
  956.   events happened within the time limit.
  957.  
  958.   Synopsis: double = DoubleClick( sec1, mic1, sec2, mic2 );
  959.  
  960.   double:   (long) If the two button events happened within the
  961.             current time limit, the function will return TRUE,
  962.             else it will return FALSE.
  963.  
  964.   sec1:     (long) Time (seconds) when the button was pressed
  965.             for the first time.
  966.  
  967.   mic1:     (long) Time (micros) when the button was pressed
  968.             for the first time.
  969.  
  970.   sec2:     (long) Current time (seconds).
  971.  
  972.   mic2:     (long) Current Time (micros).
  973.  
  974.  
  975.  
  976. CurrentTime()
  977.  
  978.   This function gives the current time.
  979.  
  980.   Synopsis: CurrentTime( seconds, micros );
  981.  
  982.   seconds:  (long *) Pointer to an ULONG variable which will be
  983.             initialized with the current seconds stamp.
  984.  
  985.   micros:   (long *) Pointer to an ULONG variable which will be
  986.             initialized with the current micros stamp.
  987.  
  988.  
  989.  
  990. 9.9  EXAMPLES
  991.  
  992. Example 1
  993.   This example shows how to allocate, and deallocate memory.
  994.  
  995. Example 2
  996.   This example shows how to allocate and deallocate memory with
  997.   help of the functions AllocRemember(), and FreeRemember().
  998.  
  999. Example 3
  1000.   This example shows how to get a copy of the preferences.
  1001.  
  1002. Example 4
  1003.   This example shows how to handle double mouse button events.
  1004.  
  1005. Example 5
  1006.   This example prints out the current time.
  1007.