home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 361b.lha / CManual_v1.0_disk3 / Appendix / Functions.doc.pp / Functions.doc
Text File  |  1990-04-06  |  45KB  |  1,395 lines
  1. B   FUNCTIONS
  2.  
  3. B.1  INTRODUCTION
  4.  
  5. Here is the complete list of all functions described in the
  6. Manual.
  7.  
  8.  
  9.  
  10. B.2  INTUITION LIBRARY
  11.  
  12. The Intuition Library must have been opened before you may call
  13. these functions, and you will probably have to include the file
  14. "intution.h". For example:
  15.  
  16. #include <intuition/intuition.h>
  17.  
  18. struct IntuitionBase *IntuitionBase;
  19.  
  20. main()
  21. {
  22.   /* Open the Intuition Library: */
  23.   IntuitionBase = (struct IntuitionBase *)
  24.     OpenLibrary( "intuition.library", 0 );
  25.   
  26.   if( IntuitionBase == NULL )
  27.     exit(); /* Could NOT open the Intuition Library! */
  28.  
  29.  
  30.   ... ...
  31.  
  32.  
  33.   /* Close the Intuition Library: */
  34.   CloseLibrary( IntuitionBase );
  35. }
  36.  
  37.  
  38. AddGadget()
  39.  
  40.   This function adds a gadget to the gadget list.
  41.  
  42.   Synopsis: result = AddGadget( window, gadget, position );
  43.   
  44.   result:   (long) The actual position of the gadget when it
  45.             has been added.
  46.  
  47.   window:   (struct Window *) Pointer to the window, to which
  48.             the gadget should be added.
  49.  
  50.   gadget:   (struct Gadget *) Pointer to the gadget which will
  51.             be added.  
  52.  
  53.   position: (long) Position in the gadget list. (Starts from
  54.             zero). Eg:
  55.               0 -> Before all other gadgets.
  56.               1 -> After the first gadget, but before the
  57.                    second.
  58.               If a too big value is entered (or -1), the gadget
  59.               will be placed last in the list.
  60.  
  61.  
  62.   Important, after your program has added the necessary
  63.   gadgets, you need to call the function RefreshGadgets() in
  64.   order to see your changes. You may add (or take away) several
  65.   gadgets, but when you are finished you must call that
  66.   function.
  67.  
  68.  
  69.  
  70. AllocRemember()
  71.  
  72.   This function allocates both memory (same as AllocMem), but
  73.   will also allocate space for a Remember structure which are
  74.   initialized with the size of the allocated memory, and a
  75.   pointer to that memory. Each time the program allocates
  76.   memory with this function, the Remember structures are linked
  77.   together.
  78.   
  79.   Since the Remember structures contains all necessary
  80.   information about the memory, and are linked together, all
  81.   memory can be deallocated with one single function call
  82.   (FreeRemember()).
  83.  
  84.   Synopsis: memory = AllocRemember( remember, size, type );
  85.  
  86.   memory:   (char *) Pointer to the new allocated memory, or
  87.             NULL if no memory could be allocated. Remember!
  88.             Never use memory which you have not successfully
  89.             allocated.
  90.  
  91.   remember: (struct Remember **) Address of a pointer to a
  92.             Remember structure. Before you call the
  93.             AllocRemember() function for the first time you
  94.             should set this pointer to NULL. (Note that it is
  95.             a pointer to a pointer!)
  96.  
  97.   size:     (long) The size (in bytes) of the memory you want.
  98.             (AllocMem() always allocates memory in multiples of
  99.             eight bytes. So if you only ask for 9 bytes, Exec
  100.             would actually give you 16 Bytes (2*8).)
  101.  
  102.   type:     (long) You need to choose one of the three
  103.             following types of memory (see chapter 0
  104.             INTRODUCTION for more information about Chip and
  105.             Fast memory):
  106.  
  107.             MEMF_CHIP   Chip memory. This memory can be
  108.                         accessed by both the main processor, as
  109.                         well as the Chips. Graphics/Sound data
  110.                         MUST therefore be placed in Chip memory.
  111.                         If it does not matter what type of 
  112.                         memory you get (Fast or Chip), you
  113.                         should try to allocate Fast memory
  114.                         before you allocate Chip memory. (Chip
  115.                         memory is more valuable than Fast
  116.                         memory.)
  117.  
  118.             MEMF_FAST   Fast memory. This memory can only be
  119.                         accessed by the main processor.
  120.                         (Graphics and Sound data can NOT be
  121.                         stored in Fast memory, use Chip memory.)
  122.                         This memory is normally a little bit
  123.                         faster than Chip memory, since only the
  124.                         main processor is working with it, and
  125.                         it is not disturbed by the Chips.
  126.  
  127.             MEMF_PUBLIC If it does not matter what type of
  128.                         memory you get (you do not intend to
  129.                         use the memory for Graphics/Sound data),
  130.                         you should use Fast memory. However,
  131.                         all Amigas do not have Fast memory,
  132.                         since you need to by a memory expansion
  133.                         in order to get it. If want to tell
  134.                         Exec that you would like to use Fast
  135.                         memory if there is any, else use Chip
  136.                         memory, you should ask for MEMF_PUBLIC.
  137.  
  138.             If you want the allocated memory to be cleared
  139.             (initialized to zeros), you should set the flag
  140.             MEMF_CLEAR.
  141.  
  142.  
  143.  
  144. AutoRequest()
  145.  
  146.   This function opens a Simple requester. Intuition will
  147.   automatically activate it and take care of the response from
  148.   the user. It will return TRUE if the left gadget was
  149.   selected, and FALSE if the right gadget was selected.
  150.  
  151.   Synopsis:  result = AutoRequest( my_window, info_txt, pos_txt,
  152.                                    neg_txt, pos_IDCMP, neg_IDCMP,
  153.                                    width, height );
  154.  
  155.   my_window: (struct Window *) Pointer to a window if there
  156.              exist one, else NULL.
  157.  
  158.   info_txt:  (struct IntuiText *) Pointer to an IntuiText
  159.              structure containing the "body text".
  160.  
  161.   pos_txt:   (struct IntuiText *) Pointer to an IntuiText
  162.              structure containing the "positive text". Eg:
  163.              "TRUE", "YES", "RETRY" etc. (Optional)
  164.  
  165.   neg_txt:   (struct IntuiText *) Pointer to an IntuiText
  166.              structure containing the "negative text". Eg:
  167.              "FALSE", "NO", "CANCEL" etc.
  168.  
  169.   pos_IDCMP: (long) IDCMP flags which satisfy the "positive"
  170.              gadget. (The flag RELVERIFY is already set.)
  171.  
  172.   pos_IDCMP: (long) IDCMP flags which satisfy the "negative"
  173.              gadget. (The flag RELVERIFY is already set.)
  174.  
  175.   width:     (long) How many pixels wide the requester should
  176.              be.
  177.  
  178.   height:    (long) How many lines high the requester should
  179.              be.
  180.  
  181.   result:    (long) Boolean value. The function returns TRUE if
  182.              the positive gadget was satisfied, and FALSE if
  183.              the negative gadget was satisfied.
  184.  
  185.  
  186.  
  187. BeginRefresh()
  188.  
  189.   This function will speed up your redrawing of the window. You
  190.   should call this function before you start to refresh the
  191.   window, and only the parts that needs to be redrawn are
  192.   redrawn.
  193.  
  194.   Synopsis:  BeginRefresh( my_window );
  195.  
  196.   my_window: (struct Window *) Pointer to a Window structure
  197.              which has previously been initialized by an
  198.              OpenWindow() call.
  199.  
  200.  
  201.  
  202. ClearDMRequest()
  203.  
  204.   This function disables a Double-menu requester. The user can
  205.   not open the requester any more.
  206.   
  207.   Synopsis:     result = ClearDMRequest( my_window );
  208.  
  209.   my_window:    (struct Window *) Pointer to the Window
  210.                 structure which the requester is connected to.
  211.                 The DMRequest pointer in the Window structure
  212.                 is set to NULL.
  213.  
  214.   result:       (long) If the function could disable the
  215.                 DM-requester it returns TRUE, else (something
  216.                 went wrong, the requester is in use etc) it
  217.                 returns FALSE.
  218.  
  219.  
  220.  
  221. ClearMenuStrip()
  222.  
  223.   This function removes a menu strip from a window. Remember to
  224.   always remove the menu strip before you close the window, or
  225.   changes the menu strip.
  226.  
  227.   Synopsis:   ClearMenuStrip( my_window );
  228.  
  229.   my_window:  (struct Window *) Pointer to the window which
  230.               menu strip should be removed.
  231.  
  232.  
  233.  
  234. ClearPointer()
  235.  
  236.   This will remove the "custom" pointer, and replace it with
  237.   Intuition's default pointer.
  238.   
  239.   Synopsis:  ClearPointer( my_window );
  240.  
  241.   my_window: (struct Window *) Pointer to a Window structure
  242.              which has previously been initialized by an
  243.              OpenWindow() call.
  244.  
  245.  
  246.  
  247. CloseScreen()
  248.  
  249.   This function will close a Custom Screen which you have
  250.   previously opened.
  251.   
  252.   Synopsis:      CloseScreen( my_screen );
  253.   
  254.   my_screen:     (struct Screen *) Pointer to an already opened
  255.                  screen.
  256.  
  257.   All windows (See chapter 2 WINDOWS for more information) on
  258.   your Screen MUST have been closed before you may close the
  259.   screen. If you close a window after the screen has been
  260.   closed, the system will crash. (Not recommended.)
  261.   
  262.   If there does not exist any more screens when you close
  263.   yours, Intuition will automatically reopen the Workbench
  264.   Screen.
  265.  
  266.  
  267.  
  268. CloseWindow()
  269.  
  270.   This function will close a window you have previously opened.
  271.   Remember that you need to close all windows connected to a
  272.   screen before you may close the screen, and all opened
  273.   windows must have been closed before your program quits.
  274.  
  275.   Synopsis:  CloseWindow( my_window );
  276.  
  277.   my_window: (struct Window *) Pointer to a Window structure
  278.              which has previously been initialized by an
  279.              OpenWindow() call.
  280.  
  281.  
  282.  
  283. CloseWorkBench()
  284.  
  285.   This function will try to close the Workbench Screen if
  286.   possible. If any other programs is using the Workbench
  287.   Screen, the function can not close it. Closing the Workbench
  288.   will free some memory, and can therefore be used if your
  289.   program needs more memory.
  290.   
  291.   (Remember to reopen the Workbench Screen when your program
  292.   terminates.)
  293.  
  294.   Synopsis:      result = CloseWorkBench();
  295.   
  296.   result:        (long) A boolean value which tell us if the
  297.                  Workbench screen has been (or already was)
  298.                  closed (TRUE), or not (FALSE).
  299.  
  300.  
  301.  
  302. CurrentTime()
  303.  
  304.   This function gives the current time.
  305.  
  306.   Synopsis: CurrentTime( seconds, micros );
  307.  
  308.   seconds:  (long *) Pointer to an ULONG variable which will be
  309.             initialized with the current seconds stamp.
  310.  
  311.   micros:   (long *) Pointer to an ULONG variable which will be
  312.             initialized with the current micros stamp.
  313.  
  314.  
  315.  
  316. DisplayAlert()
  317.  
  318.   This function activates an Alert message.
  319.  
  320.   Synopsis: result = DisplayAlert( nr, message, height ); 
  321.  
  322.   nr:       (long)  Value which describes if it is a
  323.             RECOVERY_ALERT or a DEADEND_ALERT.
  324.  
  325.   message:  (char *) Pointer to an array of characters (char). It
  326.             contains the strings we want to display, and some
  327.             extra information (position etc). The string itself
  328.             is divided into substrings, which all contain
  329.             information about its position etc.
  330.           
  331.             - 2 bytes (16-bit) which are used for the x position
  332.               of the text.
  333.             - 1 byte (8-bit) which is used for the y position of
  334.               the text.
  335.             - The text string which ends with a NULL ('\0') sign.
  336.             - A Continuation byte. If it is TRUE there is another
  337.               substring after this one, else this was the last
  338.               substring.
  339.  
  340.   height:   (long) The height of the Alert box.
  341.  
  342.   result:   (long) The function DisplayAlert() returns a boolean
  343.             value. If it is a RECOVERY_ALERT and the user pressed
  344.             the left mouse button it returns TRUE else, if the
  345.             user pressed the right mouse button, it returns
  346.             FALSE. If it is a DEADEND_ALERT the function will
  347.             immediate return FALSE.
  348.  
  349.  
  350.  
  351. DisplayBeep()
  352.  
  353.   This function flashes the screen's colours. Can be used
  354.   whenever you want to catch the user's attention.
  355.  
  356.   Synopsis: DisplayBeep( screen );
  357.    
  358.   screen:   (struct Screen *) Pointer to the screen, which
  359.             colours you want to flash. If you have not opened
  360.             a screen yourself (you are using the Workbench
  361.             Screen), you can find a pointer to that screen
  362.             in the Window structure: (my_window is a pointer
  363.             to an opened window)
  364.             DisplayBeep( my_window->WScreen );
  365.  
  366.  
  367.  
  368. DoubleClick()
  369.  
  370.   This function checks if the user double-clicked on one of the
  371.   mouse buttons. You give the function the current as well as
  372.   the previous time when the button was pressed, and it will
  373.   check the preferences and return TRUE if the two button
  374.   events happened within the time limit.
  375.  
  376.   Synopsis: double = DoubleClick( sec1, mic1, sec2, mic2 );
  377.  
  378.   double:   (long) If the two button events happened within the
  379.             current time limit, the function will return TRUE,
  380.             else it will return FALSE.
  381.  
  382.   sec1:     (long) Time (seconds) when the button was pressed
  383.             for the first time.
  384.  
  385.   mic1:     (long) Time (micros) when the button was pressed
  386.             for the first time.
  387.  
  388.   sec2:     (long) Current time (seconds).
  389.  
  390.   mic2:     (long) Current Time (micros).
  391.  
  392.  
  393.  
  394. DrawBorder()
  395.  
  396.   This function draws the specified Borders into a RastPort
  397.   (Screen/Window).
  398.  
  399.   Synopsis:  DrawBorder( rast_port, border, x, y );
  400.  
  401.   rast_port: (struct RastPort *) Pointer to a RastPort.
  402.  
  403.              If the lines should be drawn in a window, and
  404.              my_window is a pointer to that window, you write:
  405.              my_window->RPort.
  406.           
  407.              If the lines should be drawn in a Screen, and
  408.              my_screen is a pointer to that screen, you write:
  409.              my_screen->RastPort.
  410.  
  411.   border:    (struct Border *) Pointer to a Border structure
  412.              which has been initialized with your requirements.
  413.  
  414.   x:         (long) Number of pixels added to the x coordinates.
  415.  
  416.   y:         (long) Number of lines added to the y coordinates.
  417.  
  418.  
  419.  
  420. DrawImage()
  421.  
  422.   This function draws the specified images into a RastPort
  423.   (Screen/Window).
  424.  
  425.   Synopsis:  DrawImage( rast_port, image, x, y );
  426.  
  427.   rast_port: (struct RastPort *) Pointer to a RastPort.
  428.  
  429.              If the images should be drawn in a window, and
  430.              my_window is a pointer to that window, you write:
  431.              my_window->RPort.
  432.  
  433.              If the images should be drawn in a Screen, and
  434.              my_screen is a pointer to that screen, you write:
  435.              my_screen->RastPort.
  436.  
  437.   image:     (struct Image *) Pointer to an Image structure
  438.              which has been initialized with your requirements.
  439.  
  440.   x:         (long) Number of pixels added to the x position of
  441.              the image.
  442.  
  443.   y:         (long) Number of lines added to the y position of
  444.              the image.
  445.  
  446.  
  447.  
  448. EndRefresh()
  449.  
  450.   This function will tell Intuition that you have finished with
  451.   your redrawings. IMPORTANT! If you receive a REFRESHWINDOW
  452.   message, you must call the functions BeginRefresh() and
  453.   EndRefresh(), even if you do not want to redraw anything.
  454.   
  455.   Synopsis:  EndRefresh( my_window );
  456.  
  457.   my_window: (struct Window *) Pointer to a Window structure
  458.              which has previously been initialized by an
  459.              OpenWindow() call.
  460.  
  461.  
  462.  
  463. EndRequest()
  464.  
  465.   This function deactivates a requester which has been
  466.   activated.
  467.   
  468.   Synopsis:     EndRequest( my_requester, my_window );
  469.  
  470.   my_requester: (struct Requester *) Pointer to the Requester
  471.                 structure which will be removed.
  472.  
  473.   my_window:    (struct Window *) Pointer to the Window
  474.                 structure which the requester is connected to.
  475.  
  476.  
  477.  
  478. FreeRemember()
  479.  
  480.   This function deallocates all memory which has been allocated
  481.   by the AllocRemember() function. Note, you can deallocate all
  482.   Remember structures only, and deallocate the memory yourself,
  483.   if you want to.
  484.  
  485.   Synopsis:   FreeRemember( remember, everything );
  486.  
  487.   remember:   (struct Remember **) Address of a pointer to the
  488.               first Remember structure (initialized by the
  489.               AllocRemember() function). (Note that it is a
  490.               pointer to a pointer!)
  491.  
  492.   everything: (long) A boolean value. If everything is equal
  493.               to TRUE, all memory (both the allocated memory
  494.               and the Remember structures) are deallocated.
  495.               However, if everything is equal to FALSE, only
  496.               the Remember structures are deallocated, and you
  497.               have to deallocate the memory yourself.
  498.  
  499.  
  500.  
  501. GetDefPrefs()
  502.  
  503.   This function makes a copy of the default Preferences
  504.   structure.
  505.  
  506.   Synopsis: pref = GetPrefs( buffer, size );
  507.  
  508.   pref:     (struct Preferences *) Pointer to the default
  509.             preferences. If the function could not make a copy
  510.             of the preferences, the function returns NULL.
  511.  
  512.   buffer:   (struct Preferences *) Pointer to the memory buffer
  513.             which should be used to store a copy of the default
  514.             preferences in.
  515.  
  516.   size:     (long) The number of bytes you want to copy to the
  517.             buffer. Important, the buffer must be at least as
  518.             big as the number of bytes you want to copy.
  519.  
  520.  
  521.  
  522. GetMsg()
  523.  
  524.   This function tries to get a message from a message port.
  525.  
  526.   Synopsis:        my_message = GetMsg( my_message_port );
  527.  
  528.   my_message:      (struct Message *) Pointer to a Message
  529.                    structure, in this case a pointer to an
  530.                    IntuiMessage structure, or NULL if no
  531.                    message was collected.
  532.  
  533.   my_message_port: (struct MsgPort *) Pointer to an MsgPort. If
  534.                    you have opened a window, you can find your
  535.                    window's message port in the Window
  536.                    structure. ( my_window->UserPort )
  537.  
  538.  
  539.  
  540. GetPrefs()
  541.  
  542.   This function makes a copy of the Preferences structure.
  543.  
  544.   Synopsis: pref = GetPrefs( buffer, size );
  545.  
  546.   pref:     (struct Preferences *) Pointer to your preferences.
  547.             Same as your memory pointer (buffer), but is
  548.             returned so you can check if you got a copy or not.
  549.             If you could not get a copy of the preferences, the
  550.             function returns NULL.
  551.  
  552.   buffer:   (struct Preferences *) Pointer to the memory buffer
  553.             which should be used to store a copy of the
  554.             preferences in.
  555.  
  556.   size:     (long) The number of bytes you want to copy to the
  557.             buffer. Important, the buffer must be at least as
  558.             big as the number of bytes you want to copy.
  559.  
  560.  
  561.  
  562. ItemAddress()
  563.  
  564.   This function returns a pointer to the Menu or Item
  565.   structure which is specified by the menu number.
  566.   
  567.   Synopsis:    ItemAddress( my_menu, menu_number );
  568.   
  569.   my_menu:     (struct Menu *) Pointer to the first Menu
  570.                structure in the menu strip.
  571.  
  572.   menu_number: (USHORT) This menu number specifies a subitem/
  573.                item/menu.
  574.  
  575.  
  576.  
  577. ModifyIDCMP()
  578.  
  579.   This function changes the Window structure's IDCMPFlags
  580.   field.
  581.  
  582.   Synopsis:  ModifyIDCMP( my_window, IDCMPFlags );
  583.   
  584.   my_window:  (struct Window *) Pointer to an already opened
  585.               window.
  586.  
  587.   IDCMPFlags: (long) None or more IDCMP flags.
  588.  
  589.   If you call this function with no IDCMP flags set, the
  590.   window's IDCMP Ports will be closed. On the other hand, if
  591.   you call this function, with one or more IDCMP flags set, a
  592.   Port will be, if necessary, opened for you.
  593.  
  594.  
  595.  
  596. ModifyProp()
  597.  
  598.   This function modifies a proportional gadget's values and
  599.   knob. For example, if your program is reading files from the
  600.   disk, VertBody was maybe equal to 0xFFFF (MAXBODY) in the
  601.   beginning, but as more files are collected from the disk, you
  602.   maybe want to change the size of the knob etc. You then
  603.   simply call this function and it will change the values as
  604.   well as redraw the gadget.
  605.   
  606.   Synopsis:    ModifyProp( gadget, window, requester, flags,
  607.                horiz_pot, vert_pot, horiz_body, vert_body ); 
  608.  
  609.   gadget:      (struct Gadget *) Pointer to the proportional
  610.                gadget which should be changed and redrawn.
  611.  
  612.   window:      (struct Window *) Pointer to the window which
  613.                the proportional gadget is connected to.
  614.   
  615.   requester:   (struct Requester *) If the gadget is connected
  616.                to a requester, set this pointer to point to
  617.                that requester, else NULL. Important, if this
  618.                gadget is connected to a requester, it must be
  619.                displayed when you execute this command!
  620.  
  621.   flags:       (long) Here is the list of all flags you may
  622.                use:
  623.   
  624.                  FREEHORIZ      Set this bit if you want the
  625.                                 user to be able to move the
  626.                                 knob horizontally.
  627.  
  628.                  FREEVERT       Set this bit if you want the
  629.                                 user to be able to move the
  630.                                 knob vertically.
  631.  
  632.                  AUTOKNOB       Set this bit if you want that
  633.                                 the size of the knob to be
  634.                                 controlled by Intuition.
  635.                                 (HorizBody and VertBody
  636.                                 affects the size of the
  637.                                 Autoknob.)
  638.  
  639.                                 - If you want to use
  640.                                 Intuition's Autoknob you
  641.                                 should give GadgetRender a
  642.                                 pointer to an Image structure.
  643.                                 (You do not need to initialize
  644.                                 the Image structure since
  645.                                 Intuition takes care of it.)
  646.  
  647.                                 - If you on the other hand
  648.                                 would like to use your own
  649.                                 knob image, you give
  650.                                 GadgetRender a pointer to your
  651.                                 Image structure, which you have
  652.                                 initialized yourself.
  653.  
  654.                  PROPBORDERLESS Set this bit if you do not
  655.                                 want any border around the
  656.                                 container. 
  657.  
  658.                (See chapter 4.7 for more information.)
  659.  
  660.   horiz_pot:   (long) This variable contains the actual
  661.                (horizontally) proportional value. If the knob
  662.                should be moved 25% to the right, HorizPot
  663.                should be set to 25% of MAXPOT (0xFFFF).
  664.                (0xFFFF * 0.25 = 0x3FFF)
  665.  
  666.   vert_pot:    (long) Same as HorizPot except that this is the
  667.                vertically proportional value.
  668.  
  669.   horiz_body:  (long) Describes how much HorizPot should change
  670.                every time the user clicks inside the container.
  671.                If the volume of a melody can be between 0-63
  672.                (64 steps), HorizPot should change 1/64 each
  673.                time. The HorizBody should therefore be set to:
  674.                1/64 * MAXBODY (0xFFFF) == 3FF
  675.  
  676.                HorizBody describes also how much the user can
  677.                see/use of the entire data. For example, if you
  678.                have a list of 32 file names, and the user only
  679.                can see 8 names at one time (25%), the knob
  680.                (AUTOKNOB) should fill 25% of the container.
  681.                HorizBody should in this case be set to:
  682.                MAXBODY * 8 / 32 (25% of 0xFFFF) == 3FFFF
  683.  
  684.  
  685.   vert_body:   Same as HorizBody except that it affects
  686.                VertPot, and the vertical size of the knob
  687.                (AUTOKNOB).
  688.  
  689.  
  690.  
  691. MoveScreen()
  692.  
  693.   This function will move the screen. For the moment you may
  694.   only move it vertically.
  695.  
  696.   Synopsis:      MoveScreen( my_screen, delta_x, delta_y );
  697.  
  698.   my_screen:     (struct Screen *) Pointer to the screen which
  699.                  you want to move.
  700.  
  701.   delta_x:       (long) Number of pixels which the screen
  702.                  should move horizontally. For the moment you
  703.                  may not move a screen horizontally, set it
  704.                  therefore to 0.
  705.  
  706.   delta_y:       (long) Number of lines which the screen should
  707.                  move vertically.
  708.  
  709.  
  710.  
  711. MoveWindow()
  712.  
  713.   This function will move a window. It has the same effect as
  714.   if the user would have moved the window by using the Drag
  715.   Gadget.
  716.  
  717.   Synopsis:  MoveWindow( my_window, delta_x, delta_y );
  718.  
  719.   my_window: (struct Window *) Pointer to a Window structure
  720.              which has previously been initialized by an
  721.              OpenWindow() call.
  722.  
  723.   delta_x:   (long) Deltamovement horizontally.
  724.  
  725.   delta_y:   (long) Deltamovement vertically.
  726.  
  727.  
  728.  
  729. OffGadget()
  730.  
  731.   This function disables a gadget (sets the GADGDISABLED bit in
  732.   the gadget structure's Flags field):
  733.   
  734.   Synopsis:  OffGadget( gadget, window, requester );
  735.  
  736.   gadget:    (struct Gadget *) Pointer to the gadget which will
  737.              be disabled.
  738.  
  739.   window:    (struct Window *) Pointer to the window that the
  740.              gadget is attached to.
  741.  
  742.   requester: (struct Requester *) If the gadget is connected to
  743.              a requester, set this pointer to point to that
  744.              requester, else NULL. Important, if this gadget is
  745.              connected to a requester, it must be displayed
  746.              when you execute this command!
  747.  
  748.  
  749.  
  750. OnGadget()
  751.  
  752.   This function enables a gadget (removes the GADGDISABLED bit
  753.   in the gadget structure's Flags field):
  754.   
  755.   Synopsis: OnGadget( gadget, window, requester );
  756.  
  757.   gadget:     (struct Gadget *) Pointer to the gadget which
  758.               will be enabled.
  759.  
  760.   window:     (struct Window *) Pointer to the window that the
  761.               gadget is attached to.
  762.   
  763.   requester:  (struct Requester *) If the gadget is connected
  764.               to a requester, set this pointer to point to that
  765.               requester, else NULL. Important, if this gadget
  766.               is connected to a requester, it must be displayed
  767.               when you execute this command!
  768.  
  769.   Remember, as long as the gadget is disabled the user can not
  770.   select it, and it will not broadcast any messages. A disabled
  771.   gadget is drawn as usual except that it "ghosted".
  772.  
  773.  
  774.  
  775. OffMenu()
  776.  
  777.   This function can disable a subitem, an item or even a whole
  778.   menu. The image or text of the disabled items etc will be
  779.   "ghosted", and the user can not select them.
  780.   
  781.   Synopsis:    OffMenu( my_window, menu_number );
  782.  
  783.   my_window:   (struct Window *) Pointer to the window which
  784.                the menu strip is connected to.
  785.   
  786.   menu_number: (USHORT) This menu number specifies what should
  787.                be disabled. Use the macros SHIFTMENU, SHIFTITEM
  788.                and SHIFTSUB to calculate the correct menu
  789.                number. If you just specify a menu, all items
  790.                to that menu will be disabled. If you specify
  791.                a menu and an item, that item will be disabled,
  792.                and so all subitems connected to it if there are
  793.                any.
  794.  
  795.  
  796.  
  797. OnMenu()
  798.  
  799.   This function can enable a subitem, an item or even a whole
  800.   menu. The image or text of the enabled items etc, will become
  801.   normal (not "ghosted") and the user can now select them.
  802.   
  803.   Synopsis:    OnMenu( my_window, menu_number );
  804.  
  805.   my_window:   (struct Window *) Pointer to the window which
  806.                the menu strip is connected to.
  807.   
  808.   menu_number: (USHORT) This menu number specifies what should
  809.                be enabled. Use the macros SHIFTMENU, SHIFTITEM
  810.                and SHIFTSUB to calculate the correct menu
  811.                number. If you just specify a menu, all items to
  812.                that menu will be enabled. If you specify a menu
  813.                and an item, that item will be enabled, so all
  814.                subitem connected to it if there are any.
  815.  
  816.  
  817.  
  818. OpenScreen()
  819.  
  820.   This function will open a Custom Screen with your
  821.   requirements.
  822.  
  823.   Synopsis:      my_screen = OpenScreen( my_new_screen );
  824.   
  825.   my_screen:     (struct Screen *) Pointer to a Screen
  826.                  structure. It will point to your newly opened
  827.                  screen or be equal to NULL if the screen could
  828.                  not be opened.
  829.  
  830.   my_new_screen: (struct NewScreen *) Pointer to a NewScreen
  831.                  structure which contains your preferences.
  832.  
  833.  
  834.  
  835. OpenWindow()
  836.  
  837.   This function will open a window with the characteristics
  838.   defined in the NewWindow structure. It returns a pointer
  839.   to a Window structure.
  840.   
  841.   If you are going to use the Workbench screen, and it has
  842.   been closed, it will automatically reopen. If you on the
  843.   other hand is going to connect the window to a Custom screen,
  844.   you need to open it yourself before calling the OpenWindow()
  845.   function.
  846.   
  847.   Synopsis:      my_window = OpenWindow( my_new_window );
  848.  
  849.   my_window:     (struct Window *) Pointer to a Window structure
  850.                  or NULL if the window could not be opened.
  851.  
  852.   my_new_window: (struct NewWindow *) Pointer to a NewWindow
  853.                  structure which has been initialized with
  854.                  your requirements.
  855.  
  856.  
  857.  
  858. OpenWorkBench()
  859.  
  860.   This function will try to open the Workbench Screen if there
  861.   exist enough memory.
  862.   
  863.   Synopsis:      result = OpenWorkBench();
  864.   
  865.   result:        (long) A boolean value which tell us if the
  866.                  Workbench Screen has been (or already was)
  867.                  opened (TRUE), or not (FALSE).
  868.  
  869.  
  870.  
  871. PrintIText()
  872.  
  873.   This function prints text into a RastPort (Screen/Window).
  874.  
  875.   Synopsis:   PrintIText( rast_port, intui_text, x, y );
  876.  
  877.   rast_port:  (struct RastPort *) Pointer to a RastPort.
  878.  
  879.               If the text should be printed in a window, and
  880.               my_window is a pointer to that window, you write:
  881.               my_window->RPort.
  882.           
  883.               If the text should be printed in a Screen, and
  884.               my_screen is a pointer to that screen, you write:
  885.               my_screen->RastPort.
  886.  
  887.   intui_text: (struct IntuiText *) Pointer to a IntuiText
  888.               structure which has been initialized with your
  889.               requirements.
  890.  
  891.   x:          (long) Number of pixels added to the x position
  892.               of the characters.
  893.  
  894.   y:          (long) Number of lines added to the y position
  895.               of the characters.
  896.  
  897.  
  898.  
  899. RefreshGadgets()
  900.  
  901.   This function redraws all the gadgets in the list, starting
  902.   by the specified gadget. If you for example has added or
  903.   deleted a gadget you need to call this function to see the
  904.   changes. On the other hand, if you have changed the imagery
  905.   of a gadget, or the gadget's image has been trashed by
  906.   something, you can also use this function to refresh the
  907.   display.
  908.   
  909.   Synopsis:  RefreshGadgets( gadget, window, requester);
  910.  
  911.   gadget:    (struct Gadget *) Pointer to the gadget where the
  912.              redrawing should start. This gadget, and all the
  913.              following gadgets in the list will be redrawn.
  914.  
  915.   window:    (struct Window *) Pointer to the window which the
  916.              gadgets are connected to.
  917.   
  918.   requester: (struct Requester *) If the gadget is connected to
  919.              a requester, set this pointer to point to that
  920.              requester, else NULL. Important, if this gadget is
  921.              connected to a requester, it must be displayed
  922.              when you execute this command! (See chapter 5
  923.              REQUESTERS for more information about requesters.)
  924.  
  925.  
  926.  
  927. RemoveGadget()
  928.  
  929.   This function removes a gadget from the list:
  930.   
  931.   Synopsis: result = RemoveGadget( window, gadget );
  932.  
  933.   result:   (long) The position of the removed gadget or -1 if
  934.             something went wrong.
  935.  
  936.   window:   (struct Window *) Pointer to the window that the
  937.             gadget is connected to.
  938.  
  939.   gadget:   (struct Gadget *) Pointer to the gadget which will
  940.             be removed.  
  941.  
  942.  
  943.   Important, after your program has removed the necessary
  944.   gadgets, you need to call the function RefreshGadgets() in
  945.   order to see your changes. You may take away (or add) several
  946.   gadgets, but when you are finished you must call that
  947.   function.
  948.  
  949.  
  950.  
  951. ReplyMsg()
  952.  
  953.   This function tells Intuition that you have finished reading
  954.   the message. Remember, once you have replied you may not
  955.   examine or change the IntuiMessage structure any more.
  956.   
  957.   Synopsis:   ReplyMsg( my_message );
  958.   
  959.   my_message: (struct Message *) Pointer to a Message
  960.               structure, in this case a pointer to an
  961.               IntuiMessage structure.
  962.  
  963.  
  964.  
  965. ReportMouse()
  966.  
  967.   You can call this function if you want the window to start/
  968.   stop reporting the mouse position. (See chapter 8 IDCMP for
  969.   more information about REPORTMOUSE.)
  970.   
  971.   Synopsis:  ReportMouse( my_window, boolean );
  972.  
  973.   my_window: (struct Window *) Pointer to a Window structure
  974.              which has previously been initialized by an
  975.              OpenWindow() call.
  976.  
  977.   boolean:   (long) Set to TRUE if you want the window to start
  978.              reporting mouse position, else set to FALSE, and
  979.              the window will stop reporting.
  980.  
  981.  
  982.  
  983. Request()
  984.  
  985.   This function activates a requester connected to a window.
  986.   
  987.   Synopsis:     result = Request( my_requester, my_window );
  988.  
  989.   my_requester: (struct Requester *) Pointer to the Requester
  990.                 structure.
  991.  
  992.   my_window:    (struct Window *) Pointer to the Window
  993.                 structure which the requester should be
  994.                 connected to.
  995.  
  996.   result:       (long) Boolean value returned. If Intuition
  997.                 could successfully open the requester the
  998.                 function returns TRUE, else (something went
  999.                 wrong, not enough memory etc) the function
  1000.                 returns FALSE.
  1001.  
  1002.  
  1003.  
  1004. ScreenToBack()
  1005.  
  1006.   This will move the screen behind all other screens.
  1007.   
  1008.   Synopsis:      ScreenToBack( my_screen );
  1009.  
  1010.   my_screen:     (struct Screen *) Pointer to the screen which
  1011.                  you want to move.
  1012.  
  1013.  
  1014.  
  1015. ScreenToFront()
  1016.  
  1017.   This will move the screen in front of all other screens.
  1018.   
  1019.   Synopsis:      ScreenToFront( my_screen );
  1020.  
  1021.   my_screen:     (struct Screen *) Pointer to the screen which
  1022.                  you want to move.
  1023.  
  1024.  
  1025.  
  1026. SetDMRequest()
  1027.  
  1028.   This function allows the user to activate a Double-menu
  1029.   requester by clicking twice on the mouse menu button.
  1030.  
  1031.   Synopsis:  result = SetDMRequest( window, requester );
  1032.  
  1033.   window:    (struct Window *) Pointer to the Window structure
  1034.              which the requester should be connected to.
  1035.  
  1036.   requester: (struct Requester *) Pointer to the Requester
  1037.              structure.
  1038.  
  1039.   result:    (long) Boolean value returned. If Intuition could
  1040.              successfully open the requester the function
  1041.              returns TRUE, else (something went wrong, not
  1042.              enough memory or a DM requester is already
  1043.              connected to the window, etc) the function returns
  1044.              FALSE.
  1045.  
  1046.  
  1047.  
  1048. SetMenuStrip()
  1049.  
  1050.   This function connects a menu strip to a window. Remember
  1051.   that the window must have been opened before you may connect
  1052.   a menu strip to that window.
  1053.  
  1054.   Synopsis:   SetMenuStrip( my_window, my_menu );
  1055.  
  1056.   my_window:  (struct Window *) Pointer to the window which the
  1057.               menu strip should be connected to.
  1058.  
  1059.   my_menu:    (struct Menu *) Pointer to the first Menu
  1060.               structure in the menu strip.
  1061.  
  1062.  
  1063.  
  1064. SetPointer()
  1065.  
  1066.   This function allows you to change the window's pointer.
  1067.   
  1068.   Synopsis:  SetPointer( my_window, data, height, width, x, y );
  1069.  
  1070.   my_window: (struct Window *) Pointer to a Window structure
  1071.              which has previously been initialized by an
  1072.              OpenWindow() call.
  1073.  
  1074.   data:      (short *) Pointer to the Sprite data.
  1075.  
  1076.   width:     (long) The width of the pointer. Less or equal
  1077.              to 16.
  1078.  
  1079.   height:    (long) The height of the pointer. Can be any
  1080.              height.
  1081.  
  1082.   x:        (long) The pointer's "Hot Spot" x position.
  1083.  
  1084.   y:        (long) The pointer's "Hot Spot" y position.
  1085.  
  1086.  
  1087.  
  1088. SetPrefs()
  1089.  
  1090.   This function saves a modified preferences structure. Do NOT
  1091.   change the preferences unless the user really WANTS to!
  1092.  
  1093.   Synopsis: SetPrefs( pref, size, doit );
  1094.  
  1095.   pref:     (struct Preferences *) Pointer to your modified
  1096.             Preferences structure.
  1097.  
  1098.   size:     (long) The number of bytes you want to change.
  1099.  
  1100.   doit:     (long) Boolean value which if FALSE, changes the
  1101.             preferences, but will not send a NEWPREFS message.
  1102.             If doit is equal to TRUE, the settings will be
  1103.             changed, and a NEWPREFS message will be sent.
  1104.             As long as the user is changing the values, doit
  1105.             should be FALSE, but when the user has finished,
  1106.             set it to TRUE, and all programs will get a NEWPREFS
  1107.             message.
  1108.  
  1109.  
  1110.  
  1111. SetWindowTitles()
  1112.  
  1113.   This function allows you to change the window title after the
  1114.   window has been opened.
  1115.   
  1116.   Synopsis:  SetWindowTitles( my_window, window_t, screen_t );
  1117.   
  1118.   my_window: (struct Window *) Pointer to a Window structure
  1119.              which has previously been initialized by an
  1120.              OpenWindow() call.
  1121.  
  1122.   window_t:  (char *) Pointer to a NULL-terminated string which
  1123.              will become the window's title, or
  1124.                 0 : clear title bar, or
  1125.                -1 : keep the old title.
  1126.  
  1127.   screen_t:  (char *) Pointer to a NULL-terminated string which
  1128.              will become the window's screen title, or
  1129.                 0 : clear title bar, or
  1130.                -1 : keep the old title.
  1131.  
  1132.  
  1133.  
  1134. ShowTitle()
  1135.  
  1136.   This function will make the screen's Title appear above or
  1137.   behind any Backdrop Windows (See chapter 2 WINDOWS for more
  1138.   information about Backdrop Windows). (The screen's title
  1139.   appear always behind normal windows.)
  1140.  
  1141.   Synopsis:      ShowTitle( my_screen, show_it );
  1142.  
  1143.   my_screen:     (struct Screen *) Pointer to the screen.
  1144.  
  1145.   show_it:       (long) A boolean value which can be:
  1146.                  TRUE:  The title will be in front of any
  1147.                         Backdrop Windows, but behind any
  1148.                         other windows.
  1149.                  FALSE: The Title will be behind any windows
  1150.  
  1151.  
  1152.  
  1153. SizeWindow()
  1154.  
  1155.   This function will change the size of the window as desired.
  1156.   It has the same effect as if the user would have resized the
  1157.   window by using the Size Gadget.
  1158.  
  1159.   Synopsis:  SizeWindow( my_window, delta_x, delta_y );
  1160.  
  1161.   my_window: (struct Window *) Pointer to a Window structure
  1162.              which has previously been initialized by an
  1163.              OpenWindow() call.
  1164.  
  1165.   delta_x:   (long) Number of pixels the horizontally size of
  1166.              the window will change.
  1167.  
  1168.   delta_y:   (long) Number of pixels the vertically size of the
  1169.              window will change.
  1170.  
  1171.  
  1172.  
  1173. WBenchToBack()
  1174.  
  1175.   This will move the Workbench Screen behind all other screens.
  1176.   
  1177.   Synopsis:      result = WBenchToBack();
  1178.  
  1179.   result:        (long) A boolean value which is TRUE if the
  1180.                  Workbench screen was open, or FALSE it it was
  1181.                  not.
  1182.  
  1183.  
  1184.  
  1185. WBenchToFront()
  1186.  
  1187.   This will move the Workbench Screen in front of all other
  1188.   screens.
  1189.  
  1190.   Synopsis:      result = WBenchToFront();
  1191.  
  1192.   result:        (long) A boolean value which is TRUE if the
  1193.                  Workbench screen was open, or FALSE it it was
  1194.                  not.
  1195.  
  1196.  
  1197.  
  1198. WindowLimits()
  1199.  
  1200.   This function will change the maximum/minimum size limits of
  1201.   the window. Any values which are set to 0 will remain
  1202.   unchanged.
  1203.  
  1204.   Synopsis:  WindowLimits( my_window, min_w, min_h, max_w, max_h );
  1205.  
  1206.   my_window: (struct Window *) Pointer to a Window structure
  1207.              which has previously been initialized by an
  1208.              OpenWindow() call.
  1209.  
  1210.   min_w:     (long) Minimum width of the window.
  1211.  
  1212.   min_h:     (long) Minimum height of the window.
  1213.  
  1214.   max_w:     (long) Maximum width of the window.
  1215.  
  1216.   max_h:     (long) Maximum height of the window.
  1217.  
  1218.  
  1219.  
  1220. WindowToFront()
  1221.  
  1222.   This function will put the window in front of all other
  1223.   windows.
  1224.  
  1225.   Synopsis:  WindowToFront( my_window );
  1226.  
  1227.   my_window: (struct Window *) Pointer to a Window structure
  1228.              which has previously been initialized by an
  1229.              OpenWindow() call.
  1230.  
  1231.  
  1232.  
  1233. WindowToBack()
  1234.  
  1235.   This function will push the window behind all other windows.
  1236.  
  1237.   Synopsis:  WindowToBack( my_window );
  1238.  
  1239.   my_window: (struct Window *) Pointer to a Window structure
  1240.              which has previously been initialized by an
  1241.              OpenWindow() call.
  1242.  
  1243.  
  1244.  
  1245. B.3  GRAPHICS LIBRARY
  1246.  
  1247. The Graphics Library must have been opened before you may call
  1248. these functions. For example:
  1249.  
  1250. struct GfxBase *GfxBase;
  1251.  
  1252. main()
  1253. {
  1254.   /* Open the Graphics Library: */
  1255.   GfxBase = (struct GfxBase *)
  1256.     OpenLibrary( "graphics.library", 0 );
  1257.   
  1258.   if( GfxBase == NULL )
  1259.     exit(); /* Could NOT open the Graphics Library! */
  1260.  
  1261.  
  1262.   ... ...
  1263.  
  1264.  
  1265.   /* Close the Graphics Library: */
  1266.   CloseLibrary( GfxBase );
  1267. }
  1268.  
  1269.  
  1270. For the moment we will only discuss the function SetRGB4().
  1271. In later editions I will explain more functions, especially
  1272. those in the Graphics Library.
  1273.  
  1274. SetRGB4()
  1275.  
  1276.   This function allows you to change your screen's colours.
  1277.   Each colour may be picked out of a 4096 colour palette. (16
  1278.   levels of red, 16 levels of green and 16 levels of blue;
  1279.   16*16*16 = 4096.)
  1280.  
  1281.   IMPORTANT! Before you may use this function you must have
  1282.   opened the Graphics Library. (All other functions are in the
  1283.   Intuition Library.) (See chapter 0 AMIGA for more
  1284.   information.)
  1285.  
  1286.   Synopsis:   SetRGB4( viewport, register, red, green, blue );
  1287.            
  1288.   viewport:   (struct ViewPort *) Pointer to a ViewPort which
  1289.               colour registers we are going to change. We can
  1290.               find the screen's ViewPort in the Screen
  1291.               structure. (If my_screen is a pointer to a Screen
  1292.               structure, this will get us a pointer to that
  1293.               screen's ViewPort: &my_screen->ViewPort)
  1294.  
  1295.   register:   (long) The colour register you want to change.
  1296.               The screen's Depth decides how many colour
  1297.               registers the screen have:
  1298.  
  1299.               Depth  Colour Registers
  1300.               -----------------------
  1301.               1      0 - 1
  1302.               2      0 - 3
  1303.               3      0 - 7
  1304.               4      0 - 15
  1305.               5      0 - 31
  1306.               6      0 - 63
  1307.  
  1308.   red:        Amount of red. (0 - 15)
  1309.  
  1310.   green:      Amount of green. (0 - 15 )
  1311.  
  1312.   blue:       Amount of blue. (0 - 15 )
  1313.  
  1314.   Eg: SetRGB4( &my_screen->ViewPort, 2, 15, 15, 0 ); will
  1315.   change colour register 2 to be light yellow. (Red and green
  1316.   together will be yellow.)
  1317.  
  1318.  
  1319.  
  1320. B.4  EXEC LIBRARY
  1321.  
  1322. AllocMem()
  1323.  
  1324.   This function allocates memory. You specifies what type and
  1325.   how much you want, and it returns a pointer to the allocated
  1326.   memory, or NULL if there did not exist enough memory.
  1327.  
  1328.   Synopsis: memory = AllocMem( size, type );
  1329.  
  1330.   memory:   (void *) Pointer to the new allocated memory, or
  1331.             NULL if no memory could be allocated. Remember!
  1332.             Never use memory which you have not successfully
  1333.             allocated.
  1334.  
  1335.   size:     (long) The size (in bytes) of the memory you want.
  1336.             (AllocMem() always allocates memory in multiples of
  1337.             eight bytes. So if you only ask for 9 bytes, Exec
  1338.             would actually give you 16 Bytes (2*8).)
  1339.  
  1340.   type:     (long) You need to choose one of the three
  1341.             following types of memory (see chapter 0
  1342.             INTRODUCTION for more information about Chip and
  1343.             Fast memory):
  1344.  
  1345.             MEMF_CHIP   Chip memory. This memory can be
  1346.                         accessed by both the main processor, as
  1347.                         well as the Chips. Graphics/Sound data
  1348.                         MUST therefore be placed in Chip memory.
  1349.                         If it does not matter what type of 
  1350.                         memory you get (Fast or Chip), you
  1351.                         should try to allocate Fast memory
  1352.                         before you allocate Chip memory. (Chip
  1353.                         memory is more valuable than Fast
  1354.                         memory.)
  1355.  
  1356.             MEMF_FAST   Fast memory. This memory can only be
  1357.                         accessed by the main processor.
  1358.                         (Graphics and Sound data can NOT be
  1359.                         stored in Fast memory, use Chip memory.)
  1360.                         This memory is normally a little bit
  1361.                         faster than Chip memory, since only the
  1362.                         main processor is working with it, and
  1363.                         it is not disturbed by the Chips.
  1364.  
  1365.             MEMF_PUBLIC If it does not matter what type of
  1366.                         memory you get (you do not intend to
  1367.                         use the memory for Graphics/Sound data),
  1368.                         you should use Fast memory. However,
  1369.                         all Amigas do not have Fast memory,
  1370.                         since you need to by a memory expansion
  1371.                         in order to get it. If want to tell
  1372.                         Exec that you would like to use Fast
  1373.                         memory if there is any, else use Chip
  1374.                         memory, you should ask for MEMF_PUBLIC.
  1375.  
  1376.             If you want the allocated memory to be cleared
  1377.             (initialized to zeros), you should set the flag
  1378.             MEMF_CLEAR.
  1379.  
  1380.  
  1381.  
  1382. FreeMem()
  1383.  
  1384.   This function deallocated previously allocated memory.
  1385.   Remember to deallocate all memory you have taken, and never
  1386.   deallocate memory which you have not taken.
  1387.  
  1388.   Synopsis: FreeMem( memory, size );
  1389.  
  1390.   memory    (void *) Pointer to some memory which has
  1391.             previously been allocated. Remember! never use
  1392.             memory which has been deallocated.
  1393.  
  1394.   size      (long) The size (in bytes) of the memory you want
  1395.             to deallocate.