home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / dev / cmanual-3.0.lha / CManual / Amiga / Appendices / FunctionsAndLibraries / IntuitionLibrary.doc < prev    next >
Text File  |  1993-10-12  |  43KB  |  1,363 lines
  1. 1    INTUITION LIBRARY
  2.  
  3.  
  4. 1.1  OPEN THE INTUITION LIBRARY
  5.  
  6. The Intuition Library must have been opened before you may use
  7. the functions listed in this file.
  8.  
  9.   /* Include the intuition definitions: */
  10.   #include <intuition/intuition.h>
  11.  
  12.   /* Declare a pointer to the Intuition Library: */
  13.   struct IntuitionBase *IntuitionBase;
  14.  
  15.   /* Open the Intuition Library: */
  16.   IntuitionBase = (struct IntuitionBase *)
  17.     OpenLibrary( "intuition.library", 0 );
  18.   
  19.   if( !IntuitionBase )
  20.     exit(); /* Could NOT open the Intuition Library! */
  21.  
  22.  
  23.   /* ... */
  24.  
  25.  
  26.   /* Close the Intuition Library: */
  27.   CloseLibrary( IntuitionBase );
  28.  
  29.  
  30.  
  31. 1.2  FUNCTIONS
  32.  
  33. ActivateGadget()
  34.  
  35.   This function is used to activate a string or integer gadget,
  36.   although other gadgets too can be activated (selected) with
  37.   this function. This function can be used to make it easier
  38.   for the user to input text or values. Since the function will
  39.   automatically activate (select) a specified gadget can the
  40.   user continue to keep his/her fingers on the keyboard and
  41.   does not have to fiddle around with the mouse each time he/
  42.   she wants to input some values.
  43.  
  44.   Synopsis:   ActivateGadget( gadget, window, requester );
  45.  
  46.   gadget:    (struct Gadget *) Pointer to the gadget which
  47.              should be selected.
  48.  
  49.   window:    (struct Window *) Pointer to the window which the
  50.              gadget is connected to.
  51.   
  52.   requester: (struct Requester *) If the gadget is connected to
  53.              a requester, set this pointer to point to that
  54.              requester, else NULL. Important, if this gadget is
  55.              connected to a requester, it must be displayed
  56.              when you execute this command! (See chapter 5
  57.              REQUESTERS for more information about requesters.)
  58.  
  59.  
  60.  
  61. ActivateWindow()
  62.  
  63.   This function is used to activate a specified window.
  64.   
  65.   Synopsis: ActivateWindow( window );
  66.   
  67.   window:   (struct Window *) Pointer to the window which
  68.             should be activated. Note! The window must be open
  69.             when you call the function!
  70.  
  71.  
  72.  
  73. AddGadget()
  74.  
  75.   This function adds a gadget to the gadget list.
  76.  
  77.   Synopsis: result = AddGadget( window, gadget, position );
  78.   
  79.   result:   (long) The actual position of the gadget when it
  80.             has been added.
  81.  
  82.   window:   (struct Window *) Pointer to the window, to which
  83.             the gadget should be added.
  84.  
  85.   gadget:   (struct Gadget *) Pointer to the gadget which will
  86.             be added.  
  87.  
  88.   position: (long) Position in the gadget list. (Starts from
  89.             zero). Eg:
  90.               0 -> Before all other gadgets.
  91.               1 -> After the first gadget, but before the
  92.                    second.
  93.               If a too big value is entered (or -1), the gadget
  94.               will be placed last in the list.
  95.  
  96.  
  97.   Important, after your program has added the necessary
  98.   gadgets, you need to call the function RefreshGadgets() in
  99.   order to see your changes. You may add (or take away) several
  100.   gadgets, but when you are finished you must call that
  101.   function.
  102.  
  103.  
  104.  
  105. AddVSprite()
  106.  
  107.   This function will add a VSprite to the VSprite list.
  108.  
  109.   Synopsis: AddVSprite( vsprite, rp );
  110.  
  111.   vsprite:  (struct VSprite *) Pointer to an initialized
  112.             VSprite structure.
  113.  
  114.   rp:       (struct RastPort *) Pointer to the RastPort.
  115.  
  116.  
  117.  
  118. AllocRemember()
  119.  
  120.   This function allocates both memory (same as AllocMem), but
  121.   will also allocate space for a Remember structure which are
  122.   initialized with the size of the allocated memory, and a
  123.   pointer to that memory. Each time the program allocates
  124.   memory with this function, the Remember structures are linked
  125.   together.
  126.   
  127.   Since the Remember structures contains all necessary
  128.   information about the memory, and are linked together, all
  129.   memory can be deallocated with one single function call
  130.   (FreeRemember()).
  131.  
  132.   Synopsis: memory = AllocRemember( remember, size, type );
  133.  
  134.   memory:   (char *) Pointer to the new allocated memory, or
  135.             NULL if no memory could be allocated. Remember!
  136.             Never use memory which you have not successfully
  137.             allocated.
  138.  
  139.   remember: (struct Remember **) Address of a pointer to a
  140.             Remember structure. Before you call the
  141.             AllocRemember() function for the first time you
  142.             should set this pointer to NULL. (Note that it is
  143.             a pointer to a pointer!)
  144.  
  145.   size:     (long) The size (in bytes) of the memory you want.
  146.             (AllocMem() always allocates memory in multiples of
  147.             eight bytes. So if you only ask for 9 bytes, Exec
  148.             would actually give you 16 Bytes (2*8).)
  149.  
  150.   type:     (long) You need to choose one of the three
  151.             following types of memory (see chapter 0
  152.             INTRODUCTION for more information about Chip and
  153.             Fast memory):
  154.  
  155.             MEMF_CHIP   Chip memory. This memory can be
  156.                         accessed by both the main processor, as
  157.                         well as the Chips. Graphics/Sound data
  158.                         MUST therefore be placed in Chip memory.
  159.                         If it does not matter what type of 
  160.                         memory you get (Fast or Chip), you
  161.                         should try to allocate Fast memory
  162.                         before you allocate Chip memory. (Chip
  163.                         memory is more valuable than Fast
  164.                         memory.)
  165.  
  166.             MEMF_FAST   Fast memory. This memory can only be
  167.                         accessed by the main processor.
  168.                         (Graphics and Sound data can NOT be
  169.                         stored in Fast memory, use Chip memory.)
  170.                         This memory is normally a little bit
  171.                         faster than Chip memory, since only the
  172.                         main processor is working with it, and
  173.                         it is not disturbed by the Chips.
  174.  
  175.             MEMF_PUBLIC If it does not matter what type of
  176.                         memory you get (you do not intend to
  177.                         use the memory for Graphics/Sound data),
  178.                         you should use Fast memory. However,
  179.                         all Amigas do not have Fast memory,
  180.                         since you need to by a memory expansion
  181.                         in order to get it. If want to tell
  182.                         Exec that you would like to use Fast
  183.                         memory if there is any, else use Chip
  184.                         memory, you should ask for MEMF_PUBLIC.
  185.  
  186.             If you want the allocated memory to be cleared
  187.             (initialized to zeros), you should set the flag
  188.             MEMF_CLEAR.
  189.  
  190.  
  191.  
  192. AutoRequest()
  193.  
  194.   This function opens a Simple requester. Intuition will
  195.   automatically activate it and take care of the response from
  196.   the user. It will return TRUE if the left gadget was
  197.   selected, and FALSE if the right gadget was selected.
  198.  
  199.   Synopsis:  result = AutoRequest( my_window, info_txt, pos_txt,
  200.                                    neg_txt, pos_IDCMP, neg_IDCMP,
  201.                                    width, height );
  202.  
  203.   my_window: (struct Window *) Pointer to a window if there
  204.              exist one, else NULL.
  205.  
  206.   info_txt:  (struct IntuiText *) Pointer to an IntuiText
  207.              structure containing the "body text".
  208.  
  209.   pos_txt:   (struct IntuiText *) Pointer to an IntuiText
  210.              structure containing the "positive text". Eg:
  211.              "TRUE", "YES", "RETRY" etc. (Optional)
  212.  
  213.   neg_txt:   (struct IntuiText *) Pointer to an IntuiText
  214.              structure containing the "negative text". Eg:
  215.              "FALSE", "NO", "CANCEL" etc.
  216.  
  217.   pos_IDCMP: (long) IDCMP flags which satisfy the "positive"
  218.              gadget. (The flag RELVERIFY is already set.)
  219.  
  220.   pos_IDCMP: (long) IDCMP flags which satisfy the "negative"
  221.              gadget. (The flag RELVERIFY is already set.)
  222.  
  223.   width:     (long) How many pixels wide the requester should
  224.              be.
  225.  
  226.   height:    (long) How many lines high the requester should
  227.              be.
  228.  
  229.   result:    (long) Boolean value. The function returns TRUE if
  230.              the positive gadget was satisfied, and FALSE if
  231.              the negative gadget was satisfied.
  232.  
  233.  
  234.  
  235. BeginRefresh()
  236.  
  237.   This f