home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / cmanual-3.0.lha / CManual-3.0 / Amiga / Appendices / FunctionsAndLibraries / IntuitionLibrary.doc < prev    next >
Encoding:
Text File  |  1993-10-12  |  42.2 KB  |  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 function will speed up your redrawing of the window. You
  238.   should call this function before you start to refresh the
  239.   window, and only the parts that needs to be redrawn are
  240.   redrawn.
  241.  
  242.   Synopsis:  BeginRefresh( my_window );
  243.  
  244.   my_window: (struct Window *) Pointer to a Window structure
  245.              which has previously been initialized by an
  246.              OpenWindow() call.
  247.  
  248.  
  249.  
  250. ClearDMRequest()
  251.  
  252.   This function disables a Double-menu requester. The user can
  253.   not open the requester any more.
  254.   
  255.   Synopsis:     result = ClearDMRequest( my_window );
  256.  
  257.   my_window:    (struct Window *) Pointer to the Window
  258.                 structure which the requester is connected to.
  259.                 The DMRequest pointer in the Window structure
  260.                 is set to NULL.
  261.  
  262.   result:       (long) If the function could disable the
  263.                 DM-requester it returns TRUE, else (something
  264.                 went wrong, the requester is in use etc) it
  265.                 returns FALSE.
  266.  
  267.  
  268.  
  269. ClearMenuStrip()
  270.  
  271.   This function removes a menu strip from a window. Remember to
  272.   always remove the menu strip before you close the window, or
  273.   changes the menu strip.
  274.  
  275.   Synopsis:   ClearMenuStrip( my_window );
  276.  
  277.   my_window:  (struct Window *) Pointer to the window which
  278.               menu strip should be removed.
  279.  
  280.  
  281.  
  282. ClearPointer()
  283.  
  284.   This will remove the "custom" pointer, and replace it with
  285.   Intuition's default pointer.
  286.   
  287.   Synopsis:  ClearPointer( my_window );
  288.  
  289.   my_window: (struct Window *) Pointer to a Window structure
  290.              which has previously been initialized by an
  291.              OpenWindow() call.
  292.  
  293.  
  294.  
  295. CloseScreen()
  296.  
  297.   This function will close a Custom Screen which you have
  298.   previously opened.
  299.   
  300.   Synopsis:      CloseScreen( my_screen );
  301.   
  302.   my_screen:     (struct Screen *) Pointer to an already opened
  303.                  screen.
  304.  
  305.   All windows (See chapter 2 WINDOWS for more information) on
  306.   your Screen MUST have been closed before you may close the
  307.   screen. If you close a window after the screen has been
  308.   closed, the system will crash. (Not recommended.)
  309.   
  310.   If there does not exist any more screens when you close
  311.   yours, Intuition will automatically reopen the Workbench
  312.   Screen.
  313.  
  314.  
  315.  
  316. CloseWindow()
  317.  
  318.   This function will close a window you have previously opened.
  319.   Remember that you need to close all windows connected to a
  320.   screen before you may close the screen, and all opened
  321.   windows must have been closed before your program quits.
  322.  
  323.   Synopsis:  CloseWindow( my_window );
  324.  
  325.   my_window: (struct Window *) Pointer to a Window structure
  326.              which has previously been initialized by an
  327.              OpenWindow() call.
  328.  
  329.  
  330.  
  331. CloseWorkBench()
  332.  
  333.   This function will try to close the Workbench Screen if
  334.   possible. If any other programs is using the Workbench
  335.   Screen, the function can not close it. Closing the Workbench
  336.   will free some memory, and can therefore be used if your
  337.   program needs more memory.
  338.   
  339.   (Remember to reopen the Workbench Screen when your program
  340.   terminates.)
  341.  
  342.   Synopsis:      result = CloseWorkBench();
  343.   
  344.   result:        (long) A boolean value which tell us if the
  345.                  Workbench screen has been (or already was)
  346.                  closed (TRUE), or not (FALSE).
  347.  
  348.  
  349.  
  350. CurrentTime()
  351.  
  352.   This function gives the current time.
  353.  
  354.   Synopsis: CurrentTime( seconds, micros );
  355.  
  356.   seconds:  (long *) Pointer to an ULONG variable which will be
  357.             initialized with the current seconds stamp.
  358.  
  359.   micros:   (long *) Pointer to an ULONG variable which will be
  360.             initialized with the current micros stamp.
  361.  
  362.  
  363.  
  364. DisplayAlert()
  365.  
  366.   This function activates an Alert message.
  367.  
  368.   Synopsis: result = DisplayAlert( nr, message, height ); 
  369.  
  370.   nr:       (long)  Value which describes if it is a
  371.             RECOVERY_ALERT or a DEADEND_ALERT.
  372.  
  373.   message:  (char *) Pointer to an array of characters (char). It
  374.             contains the strings we want to display, and some
  375.             extra information (position etc). The string itself
  376.             is divided into substrings, which all contain
  377.             information about its position etc.
  378.           
  379.             - 2 bytes (16-bit) which are used for the x position
  380.               of the text.
  381.             - 1 byte (8-bit) which is used for the y position of
  382.               the text.
  383.             - The text string which ends with a NULL ('\0') sign.
  384.             - A Continuation byte. If it is TRUE there is another
  385.               substring after this one, else this was the last
  386.               substring.
  387.  
  388.   height:   (long) The height of the Alert box.
  389.  
  390.   result:   (long) The function DisplayAlert() returns a boolean
  391.             value. If it is a RECOVERY_ALERT and the user pressed
  392.             the left mouse button it returns TRUE else, if the
  393.             user pressed the right mouse button, it returns
  394.             FALSE. If it is a DEADEND_ALERT the function will
  395.             immediate return FALSE.
  396.  
  397.  
  398.  
  399. DisplayBeep()
  400.  
  401.   This function flashes the screen's colours. Can be used
  402.   whenever you want to catch the user's attention.
  403.  
  404.   Synopsis: DisplayBeep( screen );
  405.    
  406.   screen:   (struct Screen *) Pointer to the screen, which
  407.             colours you want to flash. If you have not opened
  408.             a screen yourself (you are using the Workbench
  409.             Screen), you can find a pointer to that screen
  410.             in the Window structure: (my_window is a pointer
  411.             to an opened window)
  412.             DisplayBeep( my_window->WScreen );
  413.  
  414.  
  415.  
  416. DoubleClick()
  417.  
  418.   This function checks if the user double-clicked on one of the
  419.   mouse buttons. You give the function the current as well as
  420.   the previous time when the button was pressed, and it will
  421.   check the preferences and return TRUE if the two button
  422.   events happened within the time limit.
  423.  
  424.   Synopsis: double = DoubleClick( sec1, mic1, sec2, mic2 );
  425.  
  426.   double:   (long) If the two button events happened within the
  427.             current time limit, the function will return TRUE,
  428.             else it will return FALSE.
  429.  
  430.   sec1:     (long) Time (seconds) when the button was pressed
  431.             for the first time.
  432.  
  433.   mic1:     (long) Time (micros) when the button was pressed
  434.             for the first time.
  435.  
  436.   sec2:     (long) Current time (seconds).
  437.  
  438.   mic2:     (long) Current Time (micros).
  439.  
  440.  
  441.  
  442. DrawBorder()
  443.  
  444.   This function draws the specified Borders into a RastPort
  445.   (Screen/Window).
  446.  
  447.   Synopsis:  DrawBorder( rast_port, border, x, y );
  448.  
  449.   rast_port: (struct RastPort *) Pointer to a RastPort.
  450.  
  451.              If the lines should be drawn in a window, and
  452.              my_window is a pointer to that window, you write:
  453.              my_window->RPort.
  454.           
  455.              If the lines should be drawn in a Screen, and
  456.              my_screen is a pointer to that screen, you write:
  457.              my_screen->RastPort.
  458.  
  459.   border:    (struct Border *) Pointer to a Border structure
  460.              which has been initialized with your requirements.
  461.  
  462.   x:         (long) Number of pixels added to the x coordinates.
  463.  
  464.   y:         (long) Number of lines added to the y coordinates.
  465.  
  466.  
  467.  
  468. DrawImage()
  469.  
  470.   This function draws the specified images into a RastPort
  471.   (Screen/Window).
  472.  
  473.   Synopsis:  DrawImage( rast_port, image, x, y );
  474.  
  475.   rast_port: (struct RastPort *) Pointer to a RastPort.
  476.  
  477.              If the images should be drawn in a window, and
  478.              my_window is a pointer to that window, you write:
  479.              my_window->RPort.
  480.  
  481.              If the images should be drawn in a Screen, and
  482.              my_screen is a pointer to that screen, you write:
  483.              my_screen->RastPort.
  484.  
  485.   image:     (struct Image *) Pointer to an Image structure
  486.              which has been initialized with your requirements.
  487.  
  488.   x:         (long) Number of pixels added to the x position of
  489.              the image.
  490.  
  491.   y:         (long) Number of lines added to the y position of
  492.              the image.
  493.  
  494.  
  495.  
  496. EndRefresh()
  497.  
  498.   This function will tell Intuition that you have finished with
  499.   your redrawings. IMPORTANT! If you receive a REFRESHWINDOW
  500.   message, you must call the functions BeginRefresh() and
  501.   EndRefresh(), even if you do not want to redraw anything.
  502.   
  503.   Synopsis:  EndRefresh( my_window );
  504.  
  505.   my_window: (struct Window *) Pointer to a Window structure
  506.              which has previously been initialized by an
  507.              OpenWindow() call.
  508.  
  509.  
  510.  
  511. EndRequest()
  512.  
  513.   This function deactivates a requester which has been
  514.   activated.
  515.   
  516.   Synopsis:     EndRequest( my_requester, my_window );
  517.  
  518.   my_requester: (struct Requester *) Pointer to the Requester
  519.                 structure which will be removed.
  520.  
  521.   my_window:    (struct Window *) Pointer to the Window
  522.                 structure which the requester is connected to.
  523.  
  524.  
  525.  
  526. FreeRemember()
  527.  
  528.   This function deallocates all memory which has been allocated
  529.   by the AllocRemember() function. Note, you can deallocate all
  530.   Remember structures only, and deallocate the memory yourself,
  531.   if you want to.
  532.  
  533.   Synopsis:   FreeRemember( remember, everything );
  534.  
  535.   remember:   (struct Remember **) Address of a pointer to the
  536.               first Remember structure (initialized by the
  537.               AllocRemember() function). (Note that it is a
  538.               pointer to a pointer!)
  539.  
  540.   everything: (long) A boolean value. If everything is equal
  541.               to TRUE, all memory (both the allocated memory
  542.               and the Remember structures) are deallocated.
  543.               However, if everything is equal to FALSE, only
  544.               the Remember structures are deallocated, and you
  545.               have to deallocate the memory yourself.
  546.  
  547.  
  548.  
  549. GetDefPrefs()
  550.  
  551.   This function makes a copy of the default Preferences
  552.   structure.
  553.  
  554.   Synopsis: pref = GetPrefs( buffer, size );
  555.  
  556.   pref:     (struct Preferences *) Pointer to the default
  557.             preferences. If the function could not make a copy
  558.             of the preferences, the function returns NULL.
  559.  
  560.   buffer:   (struct Preferences *) Pointer to the memory buffer
  561.             which should be used to store a copy of the default
  562.             preferences in.
  563.  
  564.   size:     (long) The number of bytes you want to copy to the
  565.             buffer. Important, the buffer must be at least as
  566.             big as the number of bytes you want to copy.
  567.  
  568.  
  569.  
  570. GetPrefs()
  571.  
  572.   This function makes a copy of the Preferences structure.
  573.  
  574.   Synopsis: pref = GetPrefs( buffer, size );
  575.  
  576.   pref:     (struct Preferences *) Pointer to your preferences.
  577.             Same as your memory pointer (buffer), but is
  578.             returned so you can check if you got a copy or not.
  579.             If you could not get a copy of the preferences, the
  580.             function returns NULL.
  581.  
  582.   buffer:   (struct Preferences *) Pointer to the memory buffer
  583.             which should be used to store a copy of the
  584.             preferences in.
  585.  
  586.   size:     (long) The number of bytes you want to copy to the
  587.             buffer. Important, the buffer must be at least as
  588.             big as the number of bytes you want to copy.
  589.  
  590.  
  591.  
  592. IntuiTextLength()
  593.  
  594.   This function will check a IntuiText structure to see how
  595.   many pixels long the printed text will be. This can be useful
  596.   if you want to see if a text will fit etc.
  597.  
  598.   Synopsis:      length = IntuiTextLength( my_intui_text );
  599.  
  600.   length:        (long) How many pixels long the text will be
  601.                  if printed.
  602.  
  603.   my_intui_text: (struct IntuiText *) Pointer to the IntuiText
  604.                  structure you want to check
  605.  
  606.  
  607.  
  608. ItemAddress()
  609.  
  610.   This function returns a pointer to the Menu or Item
  611.   structure which is specified by the menu number.
  612.   
  613.   Synopsis:    ItemAddress( my_menu, menu_number );
  614.   
  615.   my_menu:     (struct Menu *) Pointer to the first Menu
  616.                structure in the menu strip.
  617.  
  618.   menu_number: (USHORT) This menu number specifies a subitem/
  619.                item/menu.
  620.  
  621.  
  622.  
  623. LockIBase()
  624.  
  625.   Before you may read any values from the IntuitionBase
  626.   structure (which is defined in header file "intuition/
  627.   intuitionbase.h") you have to "lock" it. This prevents other
  628.   tasks from changing it while you are reading. Note that you
  629.   may NOT change any values directly! You may only read them,
  630.   and that firs after you have locked it.
  631.   
  632.   Do not forget to "unlock" the structure when you stop
  633.   reading. Do this by calling the UnlockIBase() function.
  634.   
  635.   Synopsis: my_lock = LockIBase( 0 );
  636.   
  637.   my_lock:  (ULONG) When you lock the IntuitionBase structure
  638.             a unique "lock" value will be returned. This value
  639.             should be used when you later unlock the structure.
  640.  
  641.  
  642.  
  643. MakeScreen()
  644.  
  645.   This function will recalculate the screen display values. 
  646.  
  647.   Synopsis: MakeScreen( screen );
  648.  
  649.   screen:   (struct Screen *) Pointer to the screen which
  650.             should be affected.
  651.  
  652.  
  653.  
  654. ModifyIDCMP()
  655.  
  656.   This function changes the Window structure's IDCMPFlags
  657.   field.
  658.  
  659.   Synopsis:  ModifyIDCMP( my_window, IDCMPFlags );
  660.   
  661.   my_window:  (struct Window *) Pointer to an already opened
  662.               window.
  663.  
  664.   IDCMPFlags: (long) None or more IDCMP flags.
  665.  
  666.   If you call this function with no IDCMP flags set, the
  667.   window's IDCMP Ports will be closed. On the other hand, if
  668.   you call this function, with one or more IDCMP flags set, a
  669.   Port will be, if necessary, opened for you.
  670.  
  671.  
  672.  
  673. ModifyProp()
  674.  
  675.   This function modifies a proportional gadget's values and
  676.   knob. For example, if your program is reading files from the
  677.   disk, VertBody was maybe equal to 0xFFFF (MAXBODY) in the
  678.   beginning, but as more files are collected from the disk, you
  679.   maybe want to change the size of the knob etc. You then
  680.   simply call this function and it will change the values as
  681.   well as redraw the gadget.
  682.   
  683.   Synopsis:    ModifyProp( gadget, window, requester, flags,
  684.                horiz_pot, vert_pot, horiz_body, vert_body ); 
  685.  
  686.   gadget:      (struct Gadget *) Pointer to the proportional
  687.                gadget which should be changed and redrawn.
  688.  
  689.   window:      (struct Window *) Pointer to the window which
  690.                the proportional gadget is connected to.
  691.   
  692.   requester:   (struct Requester *) If the gadget is connected
  693.                to a requester, set this pointer to point to
  694.                that requester, else NULL. Important, if this
  695.                gadget is connected to a requester, it must be
  696.                displayed when you execute this command!
  697.  
  698.   flags:       (long) Here is the list of all flags you may
  699.                use:
  700.   
  701.                  FREEHORIZ      Set this bit if you want the
  702.                                 user to be able to move the
  703.                                 knob horizontally.
  704.  
  705.                  FREEVERT       Set this bit if you want the
  706.                                 user to be able to move the
  707.                                 knob vertically.
  708.  
  709.                  AUTOKNOB       Set this bit if you want that
  710.                                 the size of the knob to be
  711.                                 controlled by Intuition.
  712.                                 (HorizBody and VertBody
  713.                                 affects the size of the
  714.                                 Autoknob.)
  715.  
  716.                                 - If you want to use
  717.                                 Intuition's Autoknob you
  718.                                 should give GadgetRender a
  719.                                 pointer to an Image structure.
  720.                                 (You do not need to initialize
  721.                                 the Image structure since
  722.                                 Intuition takes care of it.)
  723.  
  724.                                 - If you on the other hand
  725.                                 would like to use your own
  726.                                 knob image, you give
  727.                                 GadgetRender a pointer to your
  728.                                 Image structure, which you have
  729.                                 initialized yourself.
  730.  
  731.                  PROPBORDERLESS Set this bit if you do not
  732.                                 want any border around the
  733.                                 container. 
  734.  
  735.                (See chapter 4.7 for more information.)
  736.  
  737.   horiz_pot:   (long) This variable contains the actual
  738.                (horizontally) proportional value. If the knob
  739.                should be moved 25% to the right, HorizPot
  740.                should be set to 25% of MAXPOT (0xFFFF).
  741.                (0xFFFF * 0.25 = 0x3FFF)
  742.  
  743.   vert_pot:    (long) Same as HorizPot except that this is the
  744.                vertically proportional value.
  745.  
  746.   horiz_body:  (long) Describes how much HorizPot should change
  747.                every time the user clicks inside the container.
  748.                If the volume of a melody can be between 0-63
  749.                (64 steps), HorizPot should change 1/64 each
  750.                time. The HorizBody should therefore be set to:
  751.                1/64 * MAXBODY (0xFFFF) == 3FF
  752.  
  753.                HorizBody describes also how much the user can
  754.                see/use of the entire data. For example, if you
  755.                have a list of 32 file names, and the user only
  756.                can see 8 names at one time (25%), the knob
  757.                (AUTOKNOB) should fill 25% of the container.
  758.                HorizBody should in this case be set to:
  759.                MAXBODY * 8 / 32 (25% of 0xFFFF) == 3FFFF
  760.  
  761.  
  762.   vert_body:   Same as HorizBody except that it affects
  763.                VertPot, and the vertical size of the knob
  764.                (AUTOKNOB).
  765.  
  766.  
  767.  
  768. MoveScreen()
  769.  
  770.   This function will move the screen. For the moment you may
  771.   only move it vertically.
  772.  
  773.   Synopsis:      MoveScreen( my_screen, delta_x, delta_y );
  774.  
  775.   my_screen:     (struct Screen *) Pointer to the screen which
  776.                  you want to move.
  777.  
  778.   delta_x:       (long) Number of pixels which the screen
  779.                  should move horizontally. For the moment you
  780.                  may not move a screen horizontally, set it
  781.                  therefore to 0.
  782.  
  783.   delta_y:       (long) Number of lines which the screen should
  784.                  move vertically.
  785.  
  786.  
  787.  
  788. MoveWindow()
  789.  
  790.   This function will move a window. It has the same effect as
  791.   if the user would have moved the window by using the Drag
  792.   Gadget.
  793.  
  794.   Synopsis:  MoveWindow( my_window, delta_x, delta_y );
  795.  
  796.   my_window: (struct Window *) Pointer to a Window structure
  797.              which has previously been initialized by an
  798.              OpenWindow() call.
  799.  
  800.   delta_x:   (long) Deltamovement horizontally.
  801.  
  802.   delta_y:   (long) Deltamovement vertically.
  803.  
  804.  
  805.  
  806. OffGadget()
  807.  
  808.   This function disables a gadget (sets the GADGDISABLED bit in
  809.   the gadget structure's Flags field):
  810.   
  811.   Synopsis:  OffGadget( gadget, window, requester );
  812.  
  813.   gadget:    (struct Gadget *) Pointer to the gadget which will
  814.              be disabled.
  815.  
  816.   window:    (struct Window *) Pointer to the window that the
  817.              gadget is attached to.
  818.  
  819.   requester: (struct Requester *) If the gadget is connected to
  820.              a requester, set this pointer to point to that
  821.              requester, else NULL. Important, if this gadget is
  822.              connected to a requester, it must be displayed
  823.              when you execute this command!
  824.  
  825.  
  826.  
  827. OffMenu()
  828.  
  829.   This function can disable a subitem, an item or even a whole
  830.   menu. The image or text of the disabled items etc will be
  831.   "ghosted", and the user can not select them.
  832.   
  833.   Synopsis:    OffMenu( my_window, menu_number );
  834.  
  835.   my_window:   (struct Window *) Pointer to the window which
  836.                the menu strip is connected to.
  837.   
  838.   menu_number: (USHORT) This menu number specifies what should
  839.                be disabled. Use the macros SHIFTMENU, SHIFTITEM
  840.                and SHIFTSUB to calculate the correct menu
  841.                number. If you just specify a menu, all items
  842.                to that menu will be disabled. If you specify
  843.                a menu and an item, that item will be disabled,
  844.                and so all subitems connected to it if there are
  845.                any.
  846.  
  847.  
  848.  
  849. OnGadget()
  850.  
  851.   This function enables a gadget (removes the GADGDISABLED bit
  852.   in the gadget structure's Flags field):
  853.   
  854.   Synopsis: OnGadget( gadget, window, requester );
  855.  
  856.   gadget:     (struct Gadget *) Pointer to the gadget which
  857.               will be enabled.
  858.  
  859.   window:     (struct Window *) Pointer to the window that the
  860.               gadget is attached to.
  861.   
  862.   requester:  (struct Requester *) If the gadget is connected
  863.               to a requester, set this pointer to point to that
  864.               requester, else NULL. Important, if this gadget
  865.               is connected to a requester, it must be displayed
  866.               when you execute this command!
  867.  
  868.   Remember, as long as the gadget is disabled the user can not
  869.   select it, and it will not broadcast any messages. A disabled
  870.   gadget is drawn as usual except that it "ghosted".
  871.  
  872.  
  873.  
  874. OnMenu()
  875.  
  876.   This function can enable a subitem, an item or even a whole
  877.   menu. The image or text of the enabled items etc, will become
  878.   normal (not "ghosted") and the user can now select them.
  879.   
  880.   Synopsis:    OnMenu( my_window, menu_number );
  881.  
  882.   my_window:   (struct Window *) Pointer to the window which
  883.                the menu strip is connected to.
  884.   
  885.   menu_number: (USHORT) This menu number specifies what should
  886.                be enabled. Use the macros SHIFTMENU, SHIFTITEM
  887.                and SHIFTSUB to calculate the correct menu
  888.                number. If you just specify a menu, all items to
  889.                that menu will be enabled. If you specify a menu
  890.                and an item, that item will be enabled, so all
  891.                subitem connected to it if there are any.
  892.  
  893.  
  894.  
  895. OpenScreen()
  896.  
  897.   This function will open a Custom Screen with your
  898.   requirements.
  899.  
  900.   Synopsis:      my_screen = OpenScreen( my_new_screen );
  901.   
  902.   my_screen:     (struct Screen *) Pointer to a Screen
  903.                  structure. It will point to your newly opened
  904.                  screen or be equal to NULL if the screen could
  905.                  not be opened.
  906.  
  907.   my_new_screen: (struct NewScreen *) Pointer to a NewScreen
  908.                  structure which contains your preferences.
  909.  
  910.  
  911.  
  912. OpenWindow()
  913.  
  914.   This function will open a window with the characteristics
  915.   defined in the NewWindow structure. It returns a pointer
  916.   to a Window structure.
  917.   
  918.   If you are going to use the Workbench screen, and it has
  919.   been closed, it will automatically reopen. If you on the
  920.   other hand is going to connect the window to a Custom screen,
  921.   you need to open it yourself before calling the OpenWindow()
  922.   function.
  923.   
  924.   Synopsis:      my_window = OpenWindow( my_new_window );
  925.  
  926.   my_window:     (struct Window *) Pointer to a Window structure
  927.                  or NULL if the window could not be opened.
  928.  
  929.   my_new_window: (struct NewWindow *) Pointer to a NewWindow
  930.                  structure which has been initialized with
  931.                  your requirements.
  932.  
  933.  
  934.  
  935. OpenWorkBench()
  936.  
  937.   This function will try to open the Workbench Screen if there
  938.   exist enough memory.
  939.   
  940.   Synopsis:      result = OpenWorkBench();
  941.   
  942.   result:        (long) A boolean value which tell us if the
  943.                  Workbench Screen has been (or already was)
  944.                  opened (TRUE), or not (FALSE).
  945.  
  946.  
  947.  
  948. PrintIText()
  949.  
  950.   This function prints text into a RastPort (Screen/Window).
  951.  
  952.   Synopsis:   PrintIText( rast_port, intui_text, x, y );
  953.  
  954.   rast_port:  (struct RastPort *) Pointer to a RastPort.
  955.  
  956.               If the text should be printed in a window, and
  957.               my_window is a pointer to that window, you write:
  958.               my_window->RPort.
  959.           
  960.               If the text should be printed in a Screen, and
  961.               my_screen is a pointer to that screen, you write:
  962.               my_screen->RastPort.
  963.  
  964.   intui_text: (struct IntuiText *) Pointer to a IntuiText
  965.               structure which has been initialized with your
  966.               requirements.
  967.  
  968.   x:          (long) Number of pixels added to the x position
  969.               of the characters.
  970.  
  971.   y:          (long) Number of lines added to the y position
  972.               of the characters.
  973.  
  974.  
  975.  
  976. RefreshGadgets()
  977.  
  978.   This function redraws all the gadgets in the list, starting
  979.   by the specified gadget. If you for example has added or
  980.   deleted a gadget you need to call this function to see the
  981.   changes. On the other hand, if you have changed the imagery
  982.   of a gadget, or the gadget's image has been trashed by
  983.   something, you can also use this function to refresh the
  984.   display.
  985.   
  986.   Synopsis:  RefreshGadgets( gadget, window, requester);
  987.  
  988.   gadget:    (struct Gadget *) Pointer to the gadget where the
  989.              redrawing should start. This gadget, and all the
  990.              following gadgets in the list will be redrawn.
  991.  
  992.   window:    (struct Window *) Pointer to the window which the
  993.              gadgets are connected to.
  994.   
  995.   requester: (struct Requester *) If the gadget is connected to
  996.              a requester, set this pointer to point to that
  997.              requester, else NULL. Important, if this gadget is
  998.              connected to a requester, it must be displayed
  999.              when you execute this command! (See chapter 5
  1000.              REQUESTERS for more information about requesters.)
  1001.  
  1002.  
  1003.  
  1004. RethinkDisplay()
  1005.  
  1006.   This function will refresh the whole intuition display. If
  1007.   you are using VSprites, BOBs, Copper lists etc in a display
  1008.   created by Intuition you have to usel this function. This
  1009.   function will actually use the Graphical functions MrgCop()
  1010.   and LoadView().
  1011.   
  1012.   Note that this function takes some time to be executed, and
  1013.   should therefore only be used when really necessary.
  1014.  
  1015.   Synopsis: RethinkDisplay();
  1016.  
  1017.  
  1018.  
  1019. RemoveGadget()
  1020.  
  1021.   This function removes a gadget from the list:
  1022.   
  1023.   Synopsis: result = RemoveGadget( window, gadget );
  1024.  
  1025.   result:   (long) The position of the removed gadget or -1 if
  1026.             something went wrong.
  1027.  
  1028.   window:   (struct Window *) Pointer to the window that the
  1029.             gadget is connected to.
  1030.  
  1031.   gadget:   (struct Gadget *) Pointer to the gadget which will
  1032.             be removed.  
  1033.  
  1034.  
  1035.   Important, after your program has removed the necessary
  1036.   gadgets, you need to call the function RefreshGadgets() in
  1037.   order to see your changes. You may take away (or add) several
  1038.   gadgets, but when you are finished you must call that
  1039.   function.
  1040.  
  1041.  
  1042.  
  1043. ReportMouse()
  1044.  
  1045.   You can call this function if you want the window to start/
  1046.   stop reporting the mouse position. (See chapter 8 IDCMP for
  1047.   more information about REPORTMOUSE.)
  1048.   
  1049.   Synopsis:  ReportMouse( my_window, boolean );
  1050.  
  1051.   my_window: (struct Window *) Pointer to a Window structure
  1052.              which has previously been initialized by an
  1053.              OpenWindow() call.
  1054.  
  1055.   boolean:   (long) Set to TRUE if you want the window to start
  1056.              reporting mouse position, else set to FALSE, and
  1057.              the window will stop reporting.
  1058.  
  1059.  
  1060.  
  1061. Request()
  1062.  
  1063.   This function activates a requester connected to a window.
  1064.   
  1065.   Synopsis:     result = Request( my_requester, my_window );
  1066.  
  1067.   my_requester: (struct Requester *) Pointer to the Requester
  1068.                 structure.
  1069.  
  1070.   my_window:    (struct Window *) Pointer to the Window
  1071.                 structure which the requester should be
  1072.                 connected to.
  1073.  
  1074.   result:       (long) Boolean value returned. If Intuition
  1075.                 could successfully open the requester the
  1076.                 function returns TRUE, else (something went
  1077.                 wrong, not enough memory etc) the function
  1078.                 returns FALSE.
  1079.  
  1080.  
  1081.  
  1082. ScreenToBack()
  1083.  
  1084.   This will move the screen behind all other screens.
  1085.   
  1086.   Synopsis:      ScreenToBack( my_screen );
  1087.  
  1088.   my_screen:     (struct Screen *) Pointer to the screen which
  1089.                  you want to move.
  1090.  
  1091.  
  1092.  
  1093. ScreenToFront()
  1094.  
  1095.   This will move the screen in front of all other screens.
  1096.   
  1097.   Synopsis:      ScreenToFront( my_screen );
  1098.  
  1099.   my_screen:     (struct Screen *) Pointer to the screen which
  1100.                  you want to move.
  1101.  
  1102.  
  1103.  
  1104. SetDMRequest()
  1105.  
  1106.   This function allows the user to activate a Double-menu
  1107.   requester by clicking twice on the mouse menu button.
  1108.  
  1109.   Synopsis:  result = SetDMRequest( window, requester );
  1110.  
  1111.   window:    (struct Window *) Pointer to the Window structure
  1112.              which the requester should be connected to.
  1113.  
  1114.   requester: (struct Requester *) Pointer to the Requester
  1115.              structure.
  1116.  
  1117.   result:    (long) Boolean value returned. If Intuition could
  1118.              successfully open the requester the function
  1119.              returns TRUE, else (something went wrong, not
  1120.              enough memory or a DM requester is already
  1121.              connected to the window, etc) the function returns
  1122.              FALSE.
  1123.  
  1124.  
  1125.  
  1126. SetMenuStrip()
  1127.  
  1128.   This function connects a menu strip to a window. Remember
  1129.   that the window must have been opened before you may connect
  1130.   a menu strip to that window.
  1131.  
  1132.   Synopsis:   SetMenuStrip( my_window, my_menu );
  1133.  
  1134.   my_window:  (struct Window *) Pointer to the window which the
  1135.               menu strip should be connected to.
  1136.  
  1137.   my_menu:    (struct Menu *) Pointer to the first Menu
  1138.               structure in the menu strip.
  1139.  
  1140.  
  1141.  
  1142. SetPointer()
  1143.  
  1144.   This function allows you to change the window's pointer.
  1145.   
  1146.   Synopsis:  SetPointer( my_window, data, height, width, x, y );
  1147.  
  1148.   my_window: (struct Window *) Pointer to a Window structure
  1149.              which has previously been initialized by an
  1150.              OpenWindow() call.
  1151.  
  1152.   data:      (short *) Pointer to the Sprite data.
  1153.  
  1154.   width:     (long) The width of the pointer. Less or equal
  1155.              to 16.
  1156.  
  1157.   height:    (long) The height of the pointer. Can be any
  1158.              height.
  1159.  
  1160.   x:        (long) The pointer's "Hot Spot" x position.
  1161.  
  1162.   y:        (long) The pointer's "Hot Spot" y position.
  1163.  
  1164.  
  1165.  
  1166. SetPrefs()
  1167.  
  1168.   This function saves a modified preferences structure. Do NOT
  1169.   change the preferences unless the user really WANTS to!
  1170.  
  1171.   Synopsis: SetPrefs( pref, size, doit );
  1172.  
  1173.   pref:     (struct Preferences *) Pointer to your modified
  1174.             Preferences structure.
  1175.  
  1176.   size:     (long) The number of bytes you want to change.
  1177.  
  1178.   doit:     (long) Boolean value which if FALSE, changes the
  1179.             preferences, but will not send a NEWPREFS message.
  1180.             If doit is equal to TRUE, the settings will be
  1181.             changed, and a NEWPREFS message will be sent.
  1182.             As long as the user is changing the values, doit
  1183.             should be FALSE, but when the user has finished,
  1184.             set it to TRUE, and all programs will get a NEWPREFS
  1185.             message.
  1186.  
  1187.  
  1188.  
  1189. SetWindowTitles()
  1190.  
  1191.   This function allows you to change the window title after the
  1192.   window has been opened.
  1193.   
  1194.   Synopsis:  SetWindowTitles( my_window, window_t, screen_t );
  1195.   
  1196.   my_window: (struct Window *) Pointer to a Window structure
  1197.              which has previously been initialized by an
  1198.              OpenWindow() call.
  1199.  
  1200.   window_t:  (char *) Pointer to a NULL-terminated string which
  1201.              will become the window's title, or
  1202.                 0 : clear title bar, or
  1203.                -1 : keep the old title.
  1204.  
  1205.   screen_t:  (char *) Pointer to a NULL-terminated string which
  1206.              will become the window's screen title, or
  1207.                 0 : clear title bar, or
  1208.                -1 : keep the old title.
  1209.  
  1210.  
  1211.  
  1212. ShowTitle()
  1213.  
  1214.   This function will make the screen's Title appear above or
  1215.   behind any Backdrop Windows (See chapter 2 WINDOWS for more
  1216.   information about Backdrop Windows). (The screen's title
  1217.   appear always behind normal windows.)
  1218.  
  1219.   Synopsis:      ShowTitle( my_screen, show_it );
  1220.  
  1221.   my_screen:     (struct Screen *) Pointer to the screen.
  1222.  
  1223.   show_it:       (long) A boolean value which can be:
  1224.                  TRUE:  The title will be in front of any
  1225.                         Backdrop Windows, but behind any
  1226.                         other windows.
  1227.                  FALSE: The Title will be behind any windows
  1228.  
  1229.  
  1230.  
  1231. SizeWindow()
  1232.  
  1233.   This function will change the size of the window as desired.
  1234.   It has the same effect as if the user would have resized the
  1235.   window by using the Size Gadget.
  1236.  
  1237.   Synopsis:  SizeWindow( my_window, delta_x, delta_y );
  1238.  
  1239.   my_window: (struct Window *) Pointer to a Window structure
  1240.              which has previously been initialized by an
  1241.              OpenWindow() call.
  1242.  
  1243.   delta_x:   (long) Number of pixels the horizontally size of
  1244.              the window will change.
  1245.  
  1246.   delta_y:   (long) Number of pixels the vertically size of the
  1247.              window will change.
  1248.  
  1249.  
  1250.  
  1251. UnlockIBase()
  1252.   
  1253.   This function will "unlock" the IntuitionBase structure which
  1254.   has previously been locked. Remember to always unlock this
  1255.   structure after you have collected all desired values.
  1256.  
  1257.   Synopsis: UnlockIBase( my_lock );
  1258.   
  1259.   my_lock:  (ULONG) This value was returned by the LockIBase()
  1260.             function when you locked the structure.
  1261.  
  1262.  
  1263.  
  1264. ViewAddress()
  1265.  
  1266.   This function will return a pointer to the current View
  1267.   structure. Remember that the display consists of a view with
  1268.   one or more viewports.
  1269.   
  1270.   Synopsis: my_view = ViewAddress();
  1271.   
  1272.   my_view:  (struct View *) Pointer to the current View
  1273.             structure. As long as there exist a display will
  1274.             this function work.
  1275.  
  1276.  
  1277.  
  1278. ViewPortAddress()
  1279.  
  1280.   This function will return a pointer to the ViewPort structure
  1281.   which the window is connected to.
  1282.   
  1283.   Synopsis:     my_view_port = ViewPortAddress( my_window );
  1284.   
  1285.   my_view_port: (struct ViewPort *) The function will return a
  1286.                 a pointer to the ViewPort structure which this
  1287.                 window is connected to.
  1288.   
  1289.   my_window:    (struct Window *) Pointer to the window.
  1290.                 
  1291.  
  1292.  
  1293. WBenchToBack()
  1294.  
  1295.   This will move the Workbench Screen behind all other screens.
  1296.   
  1297.   Synopsis: result = WBenchToBack();
  1298.  
  1299.   result:   (long) A boolean value which is TRUE if the
  1300.             Workbench screen was open, or FALSE it it was not.
  1301.  
  1302.  
  1303.  
  1304. WBenchToFront()
  1305.  
  1306.   This will move the Workbench Screen in front of all other
  1307.   screens.
  1308.  
  1309.   Synopsis:      result = WBenchToFront();
  1310.  
  1311.   result:        (long) A boolean value which is TRUE if the
  1312.                  Workbench screen was open, or FALSE it it was
  1313.                  not.
  1314.  
  1315.  
  1316.  
  1317. WindowLimits()
  1318.  
  1319.   This function will change the maximum/minimum size limits of
  1320.   the window. Any values which are set to 0 will remain
  1321.   unchanged.
  1322.  
  1323.   Synopsis:  WindowLimits( my_window, min_w, min_h, max_w, max_h );
  1324.  
  1325.   my_window: (struct Window *) Pointer to a Window structure
  1326.              which has previously been initialized by an
  1327.              OpenWindow() call.
  1328.  
  1329.   min_w:     (long) Minimum width of the window.
  1330.  
  1331.   min_h:     (long) Minimum height of the window.
  1332.  
  1333.   max_w:     (long) Maximum width of the window.
  1334.  
  1335.   max_h:     (long) Maximum height of the window.
  1336.  
  1337.  
  1338.  
  1339. WindowToFront()
  1340.  
  1341.   This function will put the window in front of all other
  1342.   windows.
  1343.  
  1344.   Synopsis:  WindowToFront( my_window );
  1345.  
  1346.   my_window: (struct Window *) Pointer to a Window structure
  1347.              which has previously been initialized by an
  1348.              OpenWindow() call.
  1349.  
  1350.  
  1351.  
  1352. WindowToBack()
  1353.  
  1354.   This function will push the window behind all other windows.
  1355.  
  1356.   Synopsis:  WindowToBack( my_window );
  1357.  
  1358.   my_window: (struct Window *) Pointer to a Window structure
  1359.              which has previously been initialized by an
  1360.              OpenWindow() call.
  1361.  
  1362.  
  1363.