home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Workbench / Libs / GADUTIL.LHA / GadUtil / Docs / GadUtil.doc < prev    next >
Encoding:
Text File  |  1995-10-16  |  61.1 KB  |  2,245 lines
  1. TABLE OF CONTENTS
  2.  
  3. gadutil.library/GU_LayoutGadgetsA
  4. gadutil.library/GU_FreeLayoutGadgets
  5. gadutil.library/GU_CreateGadgetA
  6. gadutil.library/GU_SetGadgetAttrsA
  7. gadutil.library/GU_GetIMsg
  8. gadutil.library/GU_CountNodes
  9. gadutil.library/GU_GadgetArrayIndex
  10. gadutil.library/GU_BlockInput
  11. gadutil.library/GU_FreeInput
  12. gadutil.library/GU_FreeGadgets
  13. gadutil.library/GU_SetGUGadAttrsA
  14. gadutil.library/GU_CoordsInGadBox
  15. gadutil.library/GU_GetGadgetPtr
  16. gadutil.library/GU_TextWidth
  17. gadutil.library/GU_GetLocaleStr
  18. gadutil.library/GU_CreateLocMenuA
  19. gadutil.library/GU_OpenCatalog
  20. gadutil.library/GU_CloseCatalog
  21. gadutil.library/GU_DisableGadget
  22. gadutil.library/GU_SetToggle
  23. gadutil.library/GU_RefreshBoxes
  24. gadutil.library/GU_RefreshWindow
  25. gadutil.library/GU_OpenFont
  26. gadutil.library/GU_NewList
  27. gadutil.library/GU_ClearList
  28. gadutil.library/GU_DetachList
  29. gadutil.library/GU_AttachList
  30. gadutil.library/GU_AddTail
  31. gadutil.library/GU_ChangeStr
  32. gadutil.library/GU_CreateContext
  33. gadutil.library/GU_GetGadgetAttrsA
  34. gadutil.library/GU_CreateMenusA
  35. gadutil.library/GU_FreeMenus
  36. gadutil.library/GU_LayoutMenuItemsA
  37. gadutil.library/GU_LayoutMenusA
  38. gadutil.library/GU_GetVisualInfoA
  39. gadutil.library/GU_FreeVisualInfo
  40. gadutil.library/GU_BeginRefresh
  41. gadutil.library/GU_EndRefresh
  42. gadutil.library/GU_FilterIMsg
  43. gadutil.library/GU_PostFilterIMsg
  44. gadutil.library/GU_ReplyIMsg
  45. gadutil.library/GU_DrawBevelBoxA
  46. gadutil.library/GU_FindNode
  47. gadutil.library/GU_NodeUp
  48. gadutil.library/GU_NodeDown
  49. Œ gadutil.library/GU_LayoutGadgetsA              gadutil.library/LayoutGadgetsA
  50.  
  51.    NAME
  52.     GU_LayoutGadgetsA -- Formats an array of GadTools gadgets.
  53.  
  54.    SYNOPSIS
  55.     gad_info = GU_LayoutGadgetsA(gad_list, gadgets, screen, taglist)
  56.     D0,A0                        A0        A1       A2      A3
  57.  
  58.     APTR GU_LayoutGadgetsA(struct Gadget **, struct LayoutGadget *,
  59.         struct Screen *, struct TagItem *);
  60.  
  61.    FUNCTION
  62.     Creates a laid-out gadget list from a LayoutGadget array, which
  63.     describes each gadget you want to create. Gadgets you create can
  64.     be any of the gadget kinds supported by GadTools, as well as any
  65.     of the extended gadget kinds provided by GadUtil.
  66.     The gadgets created by this routine, can easily be defined so that
  67.     they adjust their sizes and positions to accomodate fonts of any
  68.     size, and also adapt to different locale strings.
  69.     
  70.    INPUTS
  71.     gad_list - a pointer to the gadget list pointer. This will be
  72.            ready to pass to OpenWindowTagList() or AddGList().
  73.  
  74.     gadgets - an array of LayoutGadget structures. Each element in
  75.           the array describes one of the gadgets that you will
  76.           be creating. Each LayoutGadget structure in the array
  77.           should be initialized as follows:
  78.  
  79.           lg_GadgetID - the ID for this gadget. An ID of -1
  80.                 terminates the array.
  81.  
  82.           lg_LayoutTags - tags that describes each gadget to
  83.                   create. These tags is used to calculate
  84.                   positions, sizes and other attributes
  85.                   of the created gadgets.
  86.  
  87.           lg_GadToolsTags - additional tags for GadTools gadgets.
  88.                     This would be the same set of tags that
  89.                     you might pass to CreateGadgetA() if
  90.                     you were using GadTools directly.
  91.  
  92.           lg_Gadget - the pointer to the Gadget structure created
  93.                   for this gadget will be placed here. You
  94.                   should initialize this field to NULL. The
  95.                   gadget structure created should be considered
  96.                   READ ONLY! This field will contain a pointer
  97.                   to a struct BBoxData, if the created gadget
  98.                   kind is a BEVELBOX_KIND.
  99.  
  100.           Assembly language programmers can use the macro GADGET:
  101.  
  102.             GADGET GadgetID, Gad_LayoutTags, Gad_GadToolsTags
  103.  
  104.     screen - a pointer to the screen that the gadgets will be created
  105.          for. This is required, so that the layuot routines can
  106.          get display info about the screen where the rendering
  107.          will be done. Use LockPubScreen() to use a public screen,
  108.          or OpenScreenTagList(), if you want to use your own screen.
  109.  
  110.     taglist - pointer to a taglist (see in a later release of this
  111.           library for allowed tags, or click here to jump to the
  112.           PRELIMINARY DOCS for this function).
  113.  
  114.    RESULT
  115.     gad_info - a pointer to a private structure. You must keep this
  116.            value and pass it to GU_FreeLayoutGadgets() later on
  117.            in order to free up all resources used by your gadgets.
  118.            This pointer is also used in a lot of other functions
  119.            in this library.
  120.  
  121.    NOTES
  122.     You must be careful with the taglist in the lg_LayoutTags field.
  123.     Tags are processed sequentally in the order you give them in, and
  124.     if a tag references another gadget (eg. the GL_TopRel tag), then
  125.     processing of the current gadget halts while the referenced gadget
  126.     is processed (if it has not already been processed). Problems can
  127.     occur if this gadget refers back to the original gadget that
  128.     referenced if, if it is referring to a field that has not yet been
  129.     processed in that gadget.
  130.  
  131.    SEE ALSO
  132.     GU_FreeLayoutGadgets(), GU_CreateGadgetA(), gadtools/CreateGadgetA()
  133.                                 GadUtil tags
  134.                                ~~~~~~~~~~~~~~
  135. Tags to use for the yet undocumented function GU_LayoutGadgetsA().
  136.  
  137. Tags to use in the tag lists for each gadget to create. Note that
  138. you do not have to specify any tags that not change from gadget to
  139. gadget.
  140.  
  141. GU_GadgetKind (ULONG)
  142.     Can be any of the standard GadTools gadget kinds, or one of the
  143.     extensions provided by GadUtil. Currently extended types are:
  144.  
  145.     IMAGE_KIND
  146.         A gadget that uses an Intuition Image structure for its
  147.         contents. Selected and unselected states can use different
  148.         images. The images are centered automatically.
  149.  
  150.         Extra tags for IMAGE_KIND:
  151.  
  152.             GUIM_Image (struct Image *)
  153.                 Image for the gadget in its unselected state. This is
  154.                 the only required (extra) tag for IMAGE_KIND gadgets.
  155.  
  156.             GUIM_SelectImg (struct Image *)
  157.                 Image for the gadget in its selected state. If this tag
  158.                 is omitted, the selected image will be the same as the
  159.                 unselected, and only the border and the background color
  160.                 will change (depending on the GUIM_BOOPSILook tag).
  161.  
  162.             GUIM_ReadOnly (BOOL)
  163.                 TRUE to create a read-only image gadget.
  164.  
  165.             GUIM_BOOPSILook (BOOL)
  166.                 This tag will allow the programmer to select how the
  167.                 secondary image should be shown, if only one image is
  168.                 used for the gadget. Defaults to TRUE, which means that
  169.                 the background color will change when the user selects
  170.                 the gadget.
  171.  
  172.     DRAWER_KIND
  173.         A "select drawer" image button. This can be used to select
  174.         a path, but is often used to select files.
  175.  
  176.     FILE_KIND
  177.         A "select file" image button. This can be used to allow the
  178.         user to select a file. Most programs uses the DRAWER_KIND
  179.         for both file and path selection.
  180.  
  181.     BEVELBOX_KIND
  182.         A GadTools bevelbox. Use this to avoid the use of absolute
  183.         sizing of bevelboxes. All bevel box kinds from OS3.0 is
  184.         supported, even if the computer only has OS2.0.
  185.  
  186.         Extra tags for BEVELBOX_KIND:
  187.  
  188.             GUBB_Recessed (BOOL)
  189.                 Create a recessed ("pushed in") bevel box. Differs from
  190.                 the GadTools tag GTBB_Recessed, in that it works with
  191.                 both TRUE and FALSE as parameter. GadTools creates a
  192.                 recessed box independent from the given value.
  193.  
  194.                 Defaults to FALSE.
  195.  
  196.             GUBB_FrameType (ULONG)
  197.                 Determines what kind of box this function renders. The
  198.                 current available alternatives are:
  199.  
  200.                     BFT_BUTTON - Generates a box like what is used around
  201.                                  a GadTools BUTTON_KIND gadget.
  202.  
  203.                     BFT_RIDGE - Generates a box like what is used around
  204.                                 a GadTools STRING_KIND gadget.
  205.  
  206.                     BFT_DROPBOX - Generates a box suitable for a standard
  207.                                   icon drop box imagery.
  208.  
  209.                     BFT_HORIZBAR - Generates a horizontal shadowed line.
  210.                                    Can also be used to draw a normal line,
  211.                                    using 1 for the line's height.
  212.  
  213.                     BFT_VERTBAR - Generates a vertical shadowed line. Can
  214.                                   also be used to draw a normal line, using
  215.                                   1 for the line's width.
  216.  
  217.                 Defaults to BFT_BUTTON.
  218.  
  219.             GUBB_TextColor (ULONG)
  220.                 Selects which color to print the title text in. Only useful
  221.                 for a bevelbox with a title. Defaults to the color of the
  222.                 TEXTPEN.
  223.  
  224.             GUBB_TextPen (ULONG)
  225.                 Selects which pen to print the title text in. Only
  226.                 useful for a bevelbox with a title. Defaults to TEXTPEN.
  227.                 This tag overrides the GUBB_TextColor tag.
  228.  
  229.             GUBB_Flags (ULONG)
  230.                 Currently, only text placement flags are defined. These are:
  231.  
  232.                 Y-pos flags
  233.                 ~~~~~~~~~~~
  234.                     BB_TEXT_ABOVE - Places the bevel box text above the upper
  235.                                     border of the box           ___Example___
  236.  
  237.                     BB_TEXT_IN    - Places the bevel box text at the upper
  238.                                     border of the box           ---Example---
  239.  
  240.                     BB_TEXT_BELOW - Places the bevel box text below the upper
  241.                                     border of the box           ___       ___
  242.                                                                    Example
  243.                 X-pos flags
  244.                 ~~~~~~~~~~~
  245.                     BB_TEXT_CENTER - Places the bevel box text in the middle
  246.                                      of the upper border        ---Example---
  247.  
  248.                     BB_TEXT_LEFT   - Places the bevel box text 8 pixels from
  249.                                      the left edge of the box   -Example-----
  250.  
  251.                     BB_TEXT_RIGHT  - Places the bevel box text 8 pixels from
  252.                                      the right edge of the box  -----Example-
  253.  
  254.                 Combined flags
  255.                 ~~~~~~~~~~~~~~
  256.                     BB_TEXT_ABOVE_CENTER - BB_TEXT_ABOVE + BB_TEXT_CENTER
  257.                     BB_TEXT_ABOVE_LEFT   - BB_TEXT_ABOVE + BB_TEXT_LEFT
  258.                     BB_TEXT_ABOVE_RIGHT  - BB_TEXT_ABOVE + BB_TEXT_RIGHT
  259.  
  260.                     BB_TEXT_IN_CENTER    - BB_TEXT_IN + BB_TEXT_CENTER
  261.                     BB_TEXT_IN_LEFT      - BB_TEXT_IN + BB_TEXT_LEFT
  262.                     BB_TEXT_IN_RIGHT     - BB_TEXT_IN + BB_TEXT_RIGHT
  263.  
  264.                     BB_TEXT_BELOW_CENTER - BB_TEXT_BELOW + BB_TEXT_CENTER
  265.                     BB_TEXT_BELOW_LEFT   - BB_TEXT_BELOW + BB_TEXT_LEFT
  266.                     BB_TEXT_BELOW_RIGHT  - BB_TEXT_BELOW + BB_TEXT_RIGHT
  267.  
  268.                 Default if BB_TEXT_ABOVE|BB_TEXT_CENTER. Combine the x and y
  269.                 position flags by OR:ing them together. Don't combine two X
  270.                 or two Y flags together.
  271.                 
  272.                 Shadow placement flags
  273.                 ~~~~~~~~~~~~~~~~~~~~~~
  274.                     BB_SHADOW_DR - Places the bevel box text shadow one pixel
  275.                                    below and to the right of the text. 
  276.  
  277.                     BB_SHADOW_UR - Places the bevel box text shadow one pixel
  278.                                    above and to the right of the text. 
  279.  
  280.                     BB_SHADOW_DL - Places the bevel box text shadow one pixel
  281.                                    below and to the left of the text. 
  282.  
  283.                     BB_SHADOW_UL - Places the bevel box text shadow one pixel
  284.                                    above and to the left of the text. 
  285.  
  286.                     BB_SUNAT_UL  - Another name for BB_SHADOW_DR
  287.                     BB_SUNAT_DL  - Another name for BB_SHADOW_UR
  288.                     BB_SUNAT_UR  - Another name for BB_SHADOW_DL
  289.                     BB_SUNAT_DR  - Another name for BB_SHADOW_UL
  290.  
  291.                 Default if BB_SHADOW_DR (BB_SUNAT_UL).
  292.  
  293.             GUBB_3DText (BOOL)
  294.                 Enables the shadow on the bevel box text. This tag must be
  295.                 used if GUBB_ShadowColor or GUBB_ShadowPen isn't used.
  296.  
  297.             GUBB_ShadowColor (ULONG)
  298.                 Selects which color to print the shadow text in. Only useful
  299.                 for a bevelbox with a title. Defaults to the color of the
  300.                 SHADOWPEN.
  301.  
  302.             GUBB_ShadowPen (ULONG)
  303.                 Selects which pen to print the shadow text in. Only useful
  304.                 for a bevelbox with a title. Defaults to SHADOWPEN.
  305.                 This tag overrides the GUBB_ShadowColor tag.
  306.  
  307.     PROGRESS_KIND:
  308.         Gadget used to display a value out of a total. Can be used to
  309.         display the progress of a search, a diskcopy or anything else.
  310.  
  311.         Extra tags for PROGRESS_KIND:
  312.  
  313.             GUPR_FillColor (ULONG)
  314.                 Selects which color to use to paint the current value of
  315.                 the progress requester with. Defaults to the color of the
  316.                 FILLPEN.
  317.  
  318.             GUPR_FillPen (ULONG)
  319.                 Selects which pen to use to paint the current value of
  320.                 the progress requester with. Defaults to the FILLPEN.
  321.                 This tag overrides the GUPR_FillColor tag.
  322.  
  323.             GUPR_BackColor (ULONG)
  324.                 Selects which color to fill the background of the progress
  325.                 requester with. Defaults to the color of the BACKGROUNDPEN.
  326.  
  327.             GUPR_BackPen (ULONG)
  328.                 Selects which pen to fill the background of the progress
  329.                 requester with. Defaults to the BACKGROUNDPEN.
  330.                 This tag overrides the GUPR_BackColor tag.
  331.  
  332.             GUPR_Current (ULONG)
  333.                 The initial current value of the progress requester. The
  334.                 gadget's current value may be changed later by directly
  335.                 modifying the pg_Current field of the ProgressGad structure.
  336.                 Use GU_UpdateProgress to redraw the progress requester with
  337.                 the new value. The pg_Current field must not be larger than
  338.                 4.294.967.295 / the width of the progress gadget. A "normal"
  339.                 width of 410 pixels allows a current value of 10.737.418.
  340.         Defaults to 0.
  341.  
  342.             GUPR_Total (ULONG)
  343.                 The initial total value of the progress requester. The
  344.                 gadget's total value may be changed later by directly
  345.                 modifying the pg_Total field of the ProgressGad structure.
  346.                 Use GU_UpdateProgress to redraw the progress requester with
  347.                 the new value. The total value can be as large as a longword
  348.                 allows (4.294.967.295), but you can't display a current value
  349.                 larger than 4.294.967.295 / the width of the progress gadget.
  350.         Defaults to 100.
  351.  
  352.     Changed tags, and additions to GadTools:
  353.  
  354.     LISTVIEW_KIND:
  355.  
  356.         GTLV_ShowSelected (UWORD id)
  357.  
  358.             This tag was changed, so that you don't have to create the
  359.             string gadget before all other gadgets. The difference from
  360.             this tag in GadTools, is that we now have to give the ID of
  361.             the string gadget to use to show the selected item.
  362.  
  363.             An example of a valid (and probably most useful) gadget to
  364.             use for GTLV_ShowSelected:
  365.  
  366.             ShowSelGad:
  367.                 dc.l    GU_GadgetKind,  STRING_KIND,    GU_AutoHeight,  4
  368.                 dc.l    GU_DupeWidth,   GAD_LISTVIEW,   GU_GadgetText,  NULL
  369.                 dc.l    TAG_DONE
  370.  
  371.             This gadget MUST be before the LISTVIEW gadget in the LayoutGadget
  372.             array.
  373.  
  374.             Special:
  375.  
  376.             ti_Data = -1    Creates a read-only gadget below the listview,
  377.                             same as for GTLV_ShowSelected, 0  for GadTools.
  378.  
  379.             ti_Data =  x    Gadget ID for the gadget that the selected item
  380.                             should be displayed in. Same as GadTools reaction
  381.                             on a gadget pointer in ti_Data.
  382.  
  383.             This gadget's ti_Data field will be changed during the creation
  384.             of the gadget, but will be changed back before GU_LayoutGadgets
  385.             returns.
  386.  
  387.     MX_KIND:
  388.  
  389.         The gng_GadgetText field in the NewGadget structure can be used even
  390.         with MX_KIND gadgets. This should have been included in GadTools.
  391.         The gadget text will always be placed ABOVE the gadget, on the same
  392.         side as the other texts for the gadget. Positions are checked against
  393.         WBPattern & SerialPrefs to get them "right". The GU_GadgetText and
  394.         GU_LocaleText tags are used to access this field.
  395.  
  396. Tags for all gadget kinds:
  397.  
  398. Gadget width control:
  399.  
  400.     GU_Width (UWORD wid)
  401.         Absolute width of the gadget. Not recommended to use for other
  402.         gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  403.  
  404.     GU_DupeWidth (UWORD id)
  405.         Duplicate the width of another gadget.
  406.  
  407.     GU_AutoWidth (WORD add)
  408.         Width = length of text label + ti_Data. For CYCLE_KIND gadgets,
  409.     the gadget width will be calculated by checking the length of
  410.     all alternatives and using the one that is widest + 26 as width.
  411.  
  412.     GU_Columns (UWORD numcols)
  413.         Set the gadget width so that approximately ti_Data columns of
  414.         text will fit.
  415.  
  416.     GU_AddWidth (WORD add)
  417.         Add ti_Data to the total width calculation.
  418.  
  419.     GU_MinWidth (UWORD wid)
  420.         Make the gadget at least ti_Data pixels wide.
  421.  
  422.     GU_MaxWidth (UWORD wid)
  423.         Make the gadget at most ti_Data pixels wide.
  424.  
  425.     GU_AddWidChar (WORD chars)
  426.         Add the length of ti_Data characters to the total width calculation.
  427.  
  428. Gadget height control:
  429.  
  430.     GU_Height (UWORD hei)
  431.         Absolute height of the gadget. Not recommended to use for other
  432.         gadgets than IMAGE_KIND, DRAWER_KIND and FILE_KIND.
  433.         
  434.     GU_DupeHeight (UWORD id)
  435.         Duplicate the height of another gadget.
  436.  
  437.     GU_AutoHeight (WORD add)
  438.         Height = height of the gadget's font + ti_Data. This tag doesn't
  439.         work as it should with MX_KIND gadgets. Will be fixed later.
  440.         Use GU_HeightFactor or GU_Height for MX_KIND until this is fixed.
  441.  
  442.     GU_HeightFactor (UWORD numlines)
  443.         Set the gadget height to approximately ti_Data lines.
  444.  
  445.     GU_AddHeight (WORD add)
  446.         Add ti_Data to the total height calculation.
  447.  
  448.     GU_MinHeight (UWORD wid)
  449.         Make the gadget at least ti_Data pixels high.
  450.  
  451.     GU_MaxHeight (UWORD wid)
  452.         Make the gadget at most ti_Data pixels high.
  453.  
  454.     GU_AddHeiLines (WORD numlines)
  455.         Add the height of ti_Data/2 lines to the final height calculation.
  456.         The numlines argument is given in units of 1/2 lines to get
  457.         better resolution (ti_Data of 4 means that the height of 2
  458.         lines should be added).
  459.  
  460. Gadget top edge control:
  461.  
  462.     GU_Top, GU_TopRel and GU_AlignTop locks the top edge of the gadget, and
  463.     allows any bottom edge control tag to adjust the height, so that both
  464.     top and bottom edges will be correct.
  465.  
  466.     GU_Top (UWORD ypos)
  467.         Absolute top edge of the gadget. Not recommended to use for other
  468.         gadgets than the top-most gadgets.
  469.  
  470.     GU_TopRel (UWORD id)
  471.         Make the top edge relative to another gadgets bottom edge. This
  472.         gadget will be placed BELOW the given gadget.
  473.  
  474.     GU_AddTop (WORD add)
  475.         Add ti_Data to the final top edge calculation.
  476.  
  477.     GU_AlignTop (UWORD id)
  478.         Align the top edge of the gadget with another gadgets top edge.
  479.  
  480.     GU_AdjustTop (WORD add)
  481.         Add the height of the text font + ti_Data to the top edge.
  482.  
  483.     GU_AddTopLines (WORD numlines)
  484.         Add the height of ti_Data/2 lines to the final top edge. The
  485.         numlines argument is given in units of 1/2 lines to get better
  486.         resolution (ti_Data of 4 means that the height of 2 lines
  487.         should be added).
  488.  
  489. Gadget bottom edge control:
  490.  
  491.     GU_Bottom, GU_BottomRel and GU_AlignBottom locks the bottom edge of the
  492.     gadget, and allows any top edge control tag to adjust the height, so that
  493.     both top and bottom edges will be correct.
  494.  
  495.     GU_Bottom (UWORD ypos)
  496.         Absolute bottom edge of the gadget. Not recommended to use for other
  497.         gadgets than the bottom-most gadgets. Should not be necessary to use
  498.         at all.
  499.  
  500.     GU_BottomRel (UWORD id)
  501.         Make the bottom edge relative to another gadgets top edge. This
  502.         gadget will be placed ABOVE the given gadget.
  503.  
  504.     GU_AddBottom (WORD add)
  505.         Add ti_Data to the final bottom edge calculation.
  506.  
  507.     GU_AlignBottom (UWORD id)
  508.         Align the bottom edge of the gadget with another gadgets bottom edge.
  509.  
  510.     GU_AdjustBottom (WORD add)
  511.         Subtract the height of the gadget's font + ti_Data from the top edge.
  512.         This will move the gadget UPWARDS (ti_Data + font height) pixels.
  513.  
  514. Gadget left edge control:
  515.  
  516.     GU_Left, GU_LeftRel and GU_AlignLeft locks the left edge of the gadget,
  517.     and allows any right edge control tag to adjust the width, so that both
  518.     left and right edges will be correct.
  519.  
  520.     GU_Left (UWORD xpos)
  521.         Absoulute left edge of the gadget. Not recommended to use for other
  522.         gadgets than the left-most gadgets.
  523.  
  524.     GU_LeftRel (UWORD id)
  525.         Make the left edge relative to another gadgets right edge. This
  526.         gadget will be placed TO THE RIGHT of the given gadget.
  527.  
  528.     GU_AddLeft (WORD add)
  529.         Add ti_Data to the final left edge calculation.
  530.  
  531.     GU_AlignLeft (UWORD id)
  532.         Align the left edge of the gadget with another gadgets left edge.
  533.  
  534.     GU_AdjustLeft (WORD add)
  535.         Add the width of the gadget label + ti_Data to the left edge.
  536.  
  537.     GU_AddLeftChar (WORD chars)
  538.         Add the length of ti_Data characters to the left edge.
  539.  
  540. Gadget right edge control:
  541.  
  542.     GU_Right, GU_RightRel and GU_AlignRight locks the right edge of the
  543.     gadget, and allows any left edge control tag to adjust the width, so
  544.     that both left and right edges will be correct.
  545.  
  546.     GU_Right (UWORD xpos)
  547.         Absoulute right edge of the gadget. Not recommended to use for other
  548.         gadgets than the right-most gadgets. Should not be necessary to use
  549.         at all.
  550.  
  551.     GU_RightRel (UWORD id)
  552.         Make the right edge relative to another gadgets left edge. This
  553.         gadget will be placed TO THE LEFT of the given gadget.
  554.  
  555.     GU_AddRight (WORD add)
  556.         Add ti_Data to the final right edge calculation.
  557.  
  558.     GU_AlignRight (UWORD id)
  559.         Align the right edge of the gadget with another gadgets right edge.
  560.  
  561.     GU_AdjustRight (WORD add)
  562.         Add the width of the gadget label + ti_Data to the left edge.
  563.  
  564. Other tags:
  565.  
  566.     GU_ToggleSelect (BOOL)
  567.         Create a toggle select gadget. Works with BUTTON_KIND and IMAGE_KIND
  568.         gadgets.
  569.  
  570.     GU_Selected (BOOL)
  571.         Set the initial value of a toggle select gadget.
  572.  
  573.     GU_Hotkey (CHAR)
  574.         Hotkey that should simulate a press (release) of a gadget.
  575.  
  576.     GU_HotkeyCase (BOOL)
  577.         Make the hotkey case-sensitive. Default is not case sensitive.
  578.  
  579.     GU_LabelHotkey (BOOL)
  580.         Get the hotkey directly from the gadget's label. The hotkey can
  581.         be case-sensitive, but not for CYCLE, LISTVIEW and MX gadgets.
  582.  
  583.     GU_RawKey (BYTE)
  584.         Use a rawkey as a gadget hotkey. May not be case-sensitive.
  585.         
  586. Tags that gives access to other fields in the NewGadget structure:
  587.  
  588.     GU_GadgetText (UBYTE *)
  589.         A pointer to the gadget's label. Will be copied directly into the
  590.         gng_GadgetText field of the NewGadget structure.
  591.  
  592.     GU_TextAttr (struct TextAttr *)
  593.         A pointer to an initialized TextAttr structure (to select the font).
  594.         Will be copied directly into the gng_TextAttr field of the NewGadget
  595.         structure.
  596.  
  597.     GU_Flags (ULONG)
  598.         Gadget flags. Currently available flags are as for GadTools, but
  599.         here is a short list of them:
  600.  
  601.         PLACETEXT_LEFT - Place the gadget label right aligned on the left
  602.                          side of the gadget.
  603.  
  604.         PLACETEXT_RIGHT - Place the gadget label left aligned on the right
  605.                           side of the gadget.
  606.  
  607.         PLACETEXT_ABOVE - Place the gadget label centered above the gadget.
  608.  
  609.         PLACETEXT_BELOW - Place the gadget label centered below the gadget.
  610.  
  611.         PLACETEXT_IN - Place the gadget label centered inside the gadget.
  612.  
  613.         NG_HIGHLABEL - Highlight the label (render it using SHINEPEN).
  614.  
  615.     GU_UserData (APTR)
  616.         Storage for your own data. Will probably be removed, since GadUtil
  617.         uses this filed for an internal structure (with some external
  618.         available fields).
  619.  
  620.     GU_LocaleText (ULONG stringid)
  621.         Get gadget label from a catalog. This allows easy localization of
  622.         all new programs.
  623.  
  624. Tags that should be passed directly to GU_LayoutGadgetsA():
  625.  
  626.     GU_RightExtreme (ULONG *)
  627.         A pointer to a longword that is used to store the rightmost point
  628.         that a gadget will exist in.
  629.  
  630.     GU_LowerExtreme (ULONG *)
  631.         A pointer to a longword that is used to store the lowermost point
  632.         that a gadget woll exist in.
  633.  
  634.     GU_Catalog (struct Catalog *)
  635.         A pointer to the programs translation catalog. NULL indicates that
  636.         the program should use the internal strings. You must open the
  637.         catalog by yourself (use GU_OpenCatalog() or locale/OpenCatalog).
  638.         The GU_AppStrings tag MUST be used together with this tag.
  639.  
  640.     GU_DefTextAttr (struct TextAttr *)
  641.         Specifies the default font to use with all gadgets. Can be over-
  642.         ridden with GU_TextAttr tag for each gadget.
  643.  
  644.     GU_AppStrings (struct AppString *)
  645.         A pointer to an array of AppString structures. These strutures
  646.         contains the programs internal strings.
  647.         This tag must be used together with the GU_Catalog tag.
  648.  
  649.     GU_BorderLeft (ULONG)
  650.         Size of the window's left border.
  651.  
  652.     GU_BorderTop (ULONG)
  653.         Size of the window's top border.
  654.  
  655.     GU_NoCreate (BOOL)
  656.         Don't create any gadgets. Useful to determine if the window will
  657.         fit on the screen etc.
  658.  
  659.     GU_MinimumIDCMP (ULONG *)
  660.         A pointer to a longword that is used to store the minimum required
  661.         IDCMP flags, so that all gadgets will work. The longword can already
  662.         be initialized, and any new needed IDCMP flags will be appended to
  663.         that longword.
  664. gadutil.library/GU_FreeLayoutGadgets        gadutil.library/FreeLayoutGadgets
  665.  
  666.    NAME
  667.     GU_FreeLayoutGadgets -- Frees gadgets laid out with GU_LayoutGadgetsA().
  668.  
  669.    SYNOPSIS
  670.     GU_FreeLayoutGadgets(gad_info)
  671.                              A0
  672.  
  673.     VOID GU_FreeLayoutGadgets(APTR);
  674.  
  675.    FUNCTION
  676.  
  677.    INPUTS
  678.  
  679.    TAGS
  680.  
  681.    RESULT
  682.  
  683.    EXAMPLE
  684.  
  685.    NOTES
  686.  
  687.    WARNING
  688.  
  689.    BUGS
  690.  
  691.    SEE ALSO
  692. gadutil.library/GU_CreateGadgetA                gadutil.library/CreateGadgetA
  693.  
  694.    NAME
  695.     GU_CreateGadgetA -- Create a gadget with built-in hotkey support.
  696.  
  697.    SYNOPSIS
  698.     gad = CreateGadgetA(kind, prevgad, newgad, taglist)
  699.     D0,A0               D0    A0       A1      A2
  700.  
  701.     struct Gadget *GU_CreateGadgetA(ULONG, struct Gadget *,
  702.                     struct NewGadget *, struct TagItem *);
  703.  
  704.    FUNCTION
  705.     GU_CreateGadgetA() allocates and initializes a new gadget of the
  706.     specified kind, and attaches it to the previous gadget. The gadget
  707.     is created based on the supplied kind, NewGadget structure, and
  708.     tags.
  709.  
  710.     This function differs from the GadTools equivalent by supporting
  711.     some extra tags to allow the gadget to be selected using the
  712.     keyboard.
  713.  
  714.    INPUTS
  715.     kind - kind of gadget to create. One of the XXX_KIND values
  716.            defined in <libraries/gadtools.h>.
  717.  
  718.     prevgad - pointer to the previous gadget that this new gadget
  719.           should be attached to. This function will fail if
  720.           this value is NULL.
  721.  
  722.     newgad - a filled in NewGadget structure describing the desired
  723.          gadget's size, position, label, etc.
  724.  
  725.     taglist - pointer to an array of tags providing optional extra
  726.           parameters, or NULL.
  727.  
  728.    TAGS
  729.     All kinds:
  730.  
  731.     GT_Underscore - Indicates the symbol that precedes the character
  732.         in the gadget label to be underscored. This can be to
  733.         indicate keyboard equivalents for gadgets. GadUtil has
  734.         the ability to process the keyboard equivalents if some
  735.         other tags are used.
  736.  
  737.     GU_Hotkey - This tag selects the hotkey to be used as an automatic
  738.         keyboard command for the gadget. The ti_Data field should
  739.         contain the ASCII or RAWKEY code for the hotkey.
  740.         This tag may be used together with the GU_HotkeyCase and
  741.         GU_LabelHotkey. The GU_RawKey tag requires this tag.
  742.  
  743.     GU_HotkeyCase - This tag makes the keyboard command case-sensitive.
  744.         This tag may not be used with GU_RawKey.
  745.  
  746.     GU_LabelHotkey - This tag picks the hotkey from the gadget text
  747.         field in the NewGadget structure when the gadget is created.
  748.         If no key is marked with the underscore, the GU_HotKey code
  749.         will be used.
  750.  
  751.         This tag supports and requires the GT_Underscore tag. The
  752.         character that was given in the GT_Underscore tag will be
  753.         used to find the code for the hotkey.
  754.  
  755.     GU_RawKey - This tag makes the hotkey code to a RAWKEY code. All
  756.         keys on the keyboard has one rawkey code that matches the
  757.         key.
  758.  
  759.         If your program also gets VANILLAKEY events, you must be
  760.         careful when selecting the rawkey code to be used as a
  761.         keyboard shortcut for this gadget. RAWKEY events will only
  762.         be sent for special keys (such as the HELP, Control, Alt
  763.         and function keys) that don't map to a single character. 
  764.         All keys that maps to a single character will be processed
  765.         as a VANILLAKEY event.
  766.  
  767.         This tag may not be used with (and will also disable) the
  768.         GU_HotkeyCase and GU_LabelHotkey tags.
  769.  
  770.     Kind specific tags:
  771.         See the GadTools function CreateGadgetA for all other tags.
  772.  
  773.    RESULT
  774.     gad - pointer to the new gadget, or NULL if the allocation failed
  775.           or if prevgad was NULL.
  776.  
  777.    NOTES
  778.     Note that the ng_VisualInfo and ng_TextAttr fields of the NewGadget
  779.     structure must be set to valid VisualInfo and TextAttr pointers, or
  780.     this function will fail.
  781.  
  782.    SEE ALSO
  783.     GU_FreeGadgets(), GU_SetGadgetAttrsA(), GU_GetVisualInfoA(),
  784.     GU_GetIMsg, gadtools/CreateGadgetA, <libraries/gadtools.h>
  785. gadutil.library/GU_SetGadgetAttrsA         gadutil.library/GU_SetGadgetAttrsA
  786.  
  787.    NAME
  788.     GU_SetGadgetAttrsA -- Change the attributes of a GadTools gadget.
  789.  
  790.    SYNOPSIS
  791.     GU_SetGadgetAttrsA(gad, win, req, taglist)
  792.                        A0    A1  A2   A3
  793.  
  794.     VOID GU_SetGadgetAttrsA(struct Gadget *, struct Window *,
  795.                 struct Requester *, struct TagItem *);
  796.  
  797.    FUNCTION
  798.     Change the attributes of the specified gadget, according to the
  799.     attributes chosen in the tag list. If an attribute is not provided
  800.     in the tag list, its value remains the unchanged. This function
  801.     also stores some information for the hotkey part of the library.
  802.  
  803.     Use this in place of the gadtools function GT_SetGadgetAttrsA().
  804.  
  805.    INPUTS
  806.     gad - pointer to the gadget in question. This address may be NULL,
  807.           in which case this function does nothing.
  808.  
  809.     win - pointer to the window containing the gadget. Starting with
  810.           V39 (of the OS), this value may be NULL, in which case the
  811.           internal attributes of the gadgets are altered but no
  812.           rendering occurs.
  813.  
  814.     req - reserved for future use, should always be NULL.
  815.  
  816.     taglist - pointer to an array of tags providing optional extra
  817.           parameters, or NULL.
  818.  
  819.    TAGS
  820.     See the GadTools function GT_SetGadgetAttrsA() for all tags, since
  821.     this is an extended version of that routine.
  822.  
  823.    NOTES
  824.     This function may not be called inside of a GU_BeginRefesh() /
  825.     GU_EndRefresh() session. (as always, restrict yourself to simple
  826.     rendering functions).
  827.  
  828.    SEE ALSO
  829.     gadtools/GT_SetGadgetAttrsA(), GU_GetGadgetAttrsA()
  830. gadutil.library/GU_GetIMsg                         gadutil.library/GU_GetIMsg
  831.  
  832.    NAME
  833.     GU_GetIMsg -- Get an IntuiMessage, process GadTools & Hotkey events.
  834.  
  835.    SYNOPSIS
  836.     imsg = GU_GetIMsg(intuiport)
  837.     D0,A0,SR(Z)       A0
  838.  
  839.     struct IntuiMessage *GU_GetIMsg(struct MsgPort *);
  840.  
  841.    FUNCTION
  842.     Use GU_GetIMsg() in place of the usual exec.library/GetMsg() when
  843.     reading IntuiMessages from your window's UserPort. If needed, the
  844.     GadTools dispatcher will be invoked, and suitable processing will
  845.     be done for gadget actions.
  846.     If the message is an IDCMP_VANILLAKEY or an IDCMP_RAWKEY, this
  847.     routine will search through all gadgets    for that key, and if it is
  848.     found, the message will change to the type of message that gadget
  849.     is supposed to send. If the key is not used as a hotkey, the
  850.     message will not change. 
  851.     If there are no messages (or if the only messages are meaningful
  852.     only to GadTools/GadUtil), NULL will be returned.
  853.  
  854.    INPUTS
  855.     intuiport - the Window->UserPort of a window that is using the
  856.         GadUtil library.
  857.  
  858.    RESULT
  859.     imsg - pointer to modified IntuiMessage, or NULL if there are
  860.            no applicable messages.
  861.  
  862.     SR (Z) - the zero flag will be set if there was no message. This
  863.            is probably only useful for assembly language programmers.
  864.  
  865.    NOTES
  866.     Be sure to use GU_ReplyIMsg() and not exec.library/ReplyMsg() on
  867.     messages obtained with GU_GetIMsg().
  868.     If you intend to do more with the resulting message than read its
  869.     fields, act on it, and reply it, you may find GU_FilterIMsg()
  870.     more appropriate.
  871.  
  872.     Starting with V39 (of the OS), this function actually returns a
  873.     pointer to an ExtIntuiMessage structure, but the prototype was
  874.     not changed for source code compatibility with older software.
  875.  
  876.    SEE ALSO
  877.     GU_ReplyIMsg(), GU_FilterIMsg()
  878. gadutil.library/GU_CountNodes                   gadutil.library/GU_CountNodes
  879.  
  880.    NAME
  881.     GU_CountNodes -- Count number of nodes in a list.
  882.  
  883.    SYNOPSIS
  884.     numnodes = GU_CountNodes(list)
  885.     D0                       A0
  886.  
  887.     ULONG GU_CountNodes(struct List *);
  888.  
  889.    FUNCTION
  890.     This function will count the number of nodes attached to a list.
  891.  
  892.    INPUTS
  893.     list - a pointer to the list to get the number of nodes in
  894.  
  895.    RESULT
  896.     numnodes - number of nodes that was in the list for the moment.
  897.  
  898.    NOTES
  899.     Use Forbid() and Permit() around a call to this function if you
  900.     are using it on a list that can change at any time (e.g. a list
  901.     that wasn't created by yourself). This function may not be accurate
  902.     when you are using it on a system list.
  903. gadutil.library/GU_GadgetArrayIndex       gadutil.library/GU_GadgetArrayIndex
  904.  
  905.    NAME
  906.     GU_GadgetArrayIndex -- Get a gadget's index in the LayoutGadget array.
  907.  
  908.    SYNOPSIS
  909.     index = GU_GadgetArrayIndex(id, gadgets)
  910.     D0,D1,SR(Z)                 D0  A0
  911.  
  912.     WORD GU_GadgetArrayIndex(WORD, struct LayoutGadget *);
  913.  
  914.    FUNCTION
  915.  
  916.    INPUTS
  917.  
  918.    TAGS
  919.  
  920.    RESULT
  921.  
  922.    EXAMPLE
  923.  
  924.    NOTES
  925.  
  926.    WARNING
  927.  
  928.    BUGS
  929.  
  930.    SEE ALSO
  931. gadutil.library/GU_BlockInput                   gadutil.library/GU_BlockInput
  932.  
  933.    NAME
  934.     GU_BlockInput -- Block all input to a window.
  935.  
  936.    SYNOPSIS
  937.     GU_BlockInput(window)
  938.                   A0
  939.  
  940.     VOID GU_BlockInput(struct Window *);
  941.  
  942.    FUNCTION
  943.     Changes the window's pointer to the standard wait pointer (OS 2.0)
  944.     or the preferred wait pointer (OS 3.0+) and opens a requester to
  945.     block the user input of the given window. The requester that is
  946.     opened is not visible.
  947.  
  948.    INPUTS
  949.     window - the parent window for the requester. This is the window
  950.          that will be blocked for user input.
  951.  
  952.    EXAMPLE
  953.  
  954.     BlockInput(myWin);
  955.     About();
  956.     FreeInput();
  957.  
  958.     Will block the parent window for user input while displaying the
  959.     About requester of a program.
  960.  
  961.    SEE ALSO
  962.     GU_FreeInput()
  963. gadutil.library/GU_FreeInput                     gadutil.library/GU_FreeInput
  964.  
  965.    NAME
  966.     GU_FreeInput -- Unblock input to a blocked window.
  967.  
  968.    SYNOPSIS
  969.     GU_FreeInput(window)
  970.                  A0
  971.  
  972.     VOID GU_FreeInput(struct Window *);
  973.  
  974.    FUNCTION
  975.     Unblock a window's user input. Call this function after blocking
  976.     the input with GU_BlockInput().
  977.  
  978.    INPUTS
  979.     window - the window that was blocked with GU_BlockInput().
  980.  
  981.    EXAMPLE
  982.  
  983.     BlockInput(myWin);
  984.     About();
  985.     FreeInput();
  986.  
  987.     Will block the parent window for user input while displaying the
  988.     About requester of a program.
  989.  
  990.    SEE ALSO
  991.     GU_BlockInput()
  992. gadutil.library/GU_FreeGadgets                 gadutil.library/GU_FreeGadgets
  993.  
  994.    NAME
  995.     GU_FreeGadgets -- Free a linked list of gadgets.
  996.  
  997.    SYNOPSIS
  998.     GU_FreeGadgets(glist)
  999.                    A0
  1000.  
  1001.     VOID GU_FreeGadgets(struct Gadget *);
  1002.  
  1003.    FUNCTION
  1004.     Frees all gadgets found on the linked list of gadgets beginning
  1005.     with the specified one. Frees all the memory that was allocated
  1006.     by GU_CreateGadgetA(). This function will return safely with no
  1007.     action if it recieves a NULL parameter.
  1008.  
  1009.     Use this function in place of gadtools/FreeGadgets().
  1010.  
  1011.    INPUTS
  1012.     glist - pointer to the first gadget in list to be freed
  1013.  
  1014.    SEE ALSO
  1015.     GU_CreateGadgetA()
  1016. gadutil.library/GU_SetGUGadAttrsA           gadutil.library/GU_SetGUGadAttrsA
  1017.  
  1018.    NAME
  1019.     GU_SetGUGadAttrsA -- Change the attributes of a GadUtil gadget.
  1020.  
  1021.    SYNOPSIS
  1022.     GU_SetGUGadAttrsA(gad_info, gad, win, taglist)
  1023.                          A0        A1   A2   A3
  1024.  
  1025.     VOID GU_SetGadAttrsA(APTR, struct Gadget *, struct Window *,
  1026.                 struct TagItem *);
  1027.  
  1028.    FUNCTION
  1029.  
  1030.    INPUTS
  1031.  
  1032.    TAGS
  1033.  
  1034.    RESULT
  1035.  
  1036.    EXAMPLE
  1037.  
  1038.    NOTES
  1039.  
  1040.    WARNING
  1041.  
  1042.    BUGS
  1043.  
  1044.    SEE ALSO
  1045. gadutil.library/GU_CoordsInGadBox           gadutil.library/GU_CoordsInGadBox
  1046.  
  1047.    NAME
  1048.     GU_CoordsInGadBox -- Check if a coordinate pair is within a gadget.
  1049.  
  1050.    SYNOPSIS
  1051.     IsInBox = GU_CoordsInGadBox(coords, gad)
  1052.     D0,SR(Z)                    D0      A0
  1053.  
  1054.     BOOL GU_CoordsInGadBox(ULONG, struct Gadget *);
  1055.  
  1056.    FUNCTION
  1057.     Check if a coordinate pair is within a gadget's border. This
  1058.     function may be used to make coordinate sensitive AppWindows
  1059.     (allows the user to drop a file on a string gadget etc.).
  1060.     To use this function, you must save the coordinates from the
  1061.     recieved message (AppMessage, IntuiMessage) to have something
  1062.     to compare against.
  1063.  
  1064.    INPUTS
  1065.     coords - a combined LONG of both the X and Y coordinates to
  1066.          compare against. The X coordinate should be in the
  1067.          upper word of the parameter.
  1068.  
  1069.     gad - the gadget to check the coordinates against.
  1070.  
  1071.    RESULT
  1072.     IsInBox - TRUE if both given coordinates was within the gadget's
  1073.           outer box (X coord is between gadx and gadx+gadw,
  1074.           Y coord is between gady and gady+gadh). Otherwise this
  1075.           function will return FALSE.
  1076.  
  1077.    EXAMPLES
  1078.     Assembly language:
  1079.         move.l    am_MouseX(a0),d0    ; Get X and Y coordinates
  1080.         move.l    mystrgad(pc),a0
  1081.         move.l    GadUtilBase(pc),a6
  1082.         jsr    _LVOGU_CoordsInGadBox(a6)
  1083.         beq.b    .notinbox        ; Not in gadget box
  1084.     
  1085.         ; Do what you want to do if the coordinates are
  1086.         ; within the gadget box
  1087.     .notinbox:
  1088.         ; Here, you may want to check for some other gadgets
  1089.  
  1090.  
  1091.     C:
  1092.         long coords;
  1093.         coords = (LONG)appmsg->MouseX << 16 | appmsg->MouseY;
  1094.         if (CoordsInGadBox(coords,mystrgad) = TRUE)
  1095.         {
  1096.             /* Do what you want to do if the coordinates
  1097.                are within the gadget box */
  1098.         }
  1099.         else
  1100.         {
  1101.             /* Here, you may want to check for some other
  1102.                gadgets */
  1103.         }
  1104. gadutil.library/GU_GetGadgetPtr               gadutil.library/GU_GetGadgetPtr
  1105.  
  1106.    NAME
  1107.     GU_GetGadgetPtr -- Get a pointer to a gadget's gadget structure.
  1108.  
  1109.    SYNOPSIS
  1110.     gad = GU_GetGadgetPtr(id, gadgets)
  1111.     D0,SR(Z)              D0  A0
  1112.  
  1113.     struct Gadget *GU_GetGadgetPtr(UWORD, struct LayoutGadget *);
  1114.  
  1115.    FUNCTION
  1116.     Find a gadget's gadget structure by giving its ID. The gadget
  1117.     pointer is always found last in the LayoutGadget structure. You
  1118.     can use this function to get that pointer.
  1119.     It is also possible to get the gadget structure by taking it
  1120.     directly from the LayoutGadget structure array, but then you
  1121.     must know exactly in which structure it is located. Assembly
  1122.     language programmers can use a PC relative pointer to get the
  1123.     gadget pointer.
  1124.     
  1125.    INPUTS
  1126.     id - the ID of the gadget to search for
  1127.  
  1128.     gadgets - a pointer to the array of LayoutGadget structures.
  1129.  
  1130.    RESULT
  1131.     gad - pointer to the requested gadget. For bevelboxes, this
  1132.           function will return a BBoxData structure.
  1133.  
  1134.    EXAMPLE
  1135.  
  1136.      Some of the LayoutGadget structures from BetterTest.c:
  1137.  
  1138.      struct LayoutGadget gadgets[] = {
  1139.     { MSG_NEXTDRIVE, NextDriveGad, StdGTTags,   NULL },
  1140.     { MSG_PREVDRIVE, PrevDriveGad, StdGTTags,   NULL },
  1141.     { MSG_DRIVE,     DriveGad,     DriveGTTags, NULL },
  1142.     { MSG_REQUESTER, ReqGad,       StdGTTags,   NULL },
  1143.     { MSG_CHECKME,   CheckBoxGad,  StdGTTags,   NULL },
  1144.     { MSG_FILENAME,  FileNameGad,  StdGTTags,   NULL },
  1145.     { -1,            NULL,         NULL,        NULL }
  1146.      };
  1147.  
  1148.     The examples should get the gadget structure of the Requester
  1149.     gadget (not assuming that ID's begin with 0).
  1150.     There is two methods you can use to get a gadgets structure:
  1151.  
  1152.     1. Use the pointer in the array directly:
  1153.  
  1154.     thegadget = gadgets[3].lg_Gadget
  1155.  
  1156.     This will only work if you know in which LayoutGadget structure
  1157.     the gadget is in.
  1158.  
  1159.     2. Use this library function:
  1160.  
  1161.     thegadget = GU_GetGadgetPtr(MSG_REQUESTER, gadgets);
  1162.  
  1163.     This will always work if all gadgets have a unique ID.
  1164.  
  1165.  
  1166.      Some of the LayoutGadget structures from BetterTest.s:
  1167.  
  1168.     gadgets:
  1169.      GADGET  MSG_NEXTDRIVE,  NextDriveGad,   StdGTTags
  1170.      GADGET  MSG_PREVDRIVE,  PrevDriveGad,   StdGTTags
  1171.      GADGET  MSG_DRIVE,      DriveGad,       DriveGTTags
  1172.      GADGET  MSG_REQUESTER,  ReqGad,         StdGTTags
  1173.      GADGET  MSG_CHECKME,    CheckBoxGad,    StdGTTags
  1174.      GADGET  MSG_FILENAME,   FileNameGad,    StdGTTags
  1175.      GADGET  -1,NULL,NULL
  1176.  
  1177.      Assembly language programmers can use three methods to get the
  1178.      pointer:
  1179.  
  1180.     1. Use the pointer in the array directly:
  1181.  
  1182.         lea.l    gadgets(pc),a0    ; Get array
  1183.         moveq.l    #lg_SIZEOF,d0    ; Get the size of the LayoutGadget
  1184.         mulu    #3,d0        ;  struct and calculate offset to
  1185.                     ;  the right structure in the array
  1186.         move.l    lg_Gadget(a0,d0.l),d0    ; Get the gadget pointer
  1187.  
  1188.     This will only work if you know in which LayoutGadget structure
  1189.     the gadget is in.
  1190.  
  1191.     2. Use this library function:
  1192.  
  1193.         lea.l    gadgets(pc),a0    ; Get array
  1194.         moveq.l    #MSG_REQUESTER,d0    ; Gadget to search for
  1195.         jsr    _LVOGU_GetGadgetPtr    ; Get gadget, result in D0
  1196.  
  1197.     This will always work if all gadgets have a unique ID.
  1198.  
  1199.     3. Use an extra label for each gadget that should be easy to
  1200.        access:
  1201.  
  1202.     gadgets:
  1203.      GADGET  MSG_NEXTDRIVE,  NextDriveGad,   StdGTTags
  1204.      GADGET  MSG_PREVDRIVE,  PrevDriveGad,   StdGTTags
  1205.      GADGET  MSG_DRIVE,      DriveGad,       DriveGTTags
  1206.      GADGET  MSG_REQUESTER,  ReqGad,         StdGTTags
  1207.     reqgad:        equ    *-4
  1208.      GADGET  MSG_CHECKME,    CheckBoxGad,    StdGTTags
  1209.      GADGET  MSG_FILENAME,   FileNameGad,    StdGTTags
  1210.     filenamegad:    equ    *-4
  1211.      GADGET  -1,NULL,NULL
  1212.  
  1213.         move.l    reqgad(pc),d0        ; Get the gadget
  1214.  
  1215.     This will always work.
  1216. gadutil.library/GU_TextWidth                     gadutil.library/GU_TextWidth
  1217.  
  1218.    NAME
  1219.     GU_TextWidth -- Calculate the pixel length of a text string.
  1220.  
  1221.    SYNOPSIS
  1222.     textwidth = GU_TextWidth(string, textattr)
  1223.     D0                       A0      A1
  1224.  
  1225.     ULONG GU_TextWidth(STRPTR, struct TextAttr *);
  1226.  
  1227.    FUNCTION
  1228.     Calculate the length of the text, using the specified font. This
  1229.     function will open the required font, if it isn't opened before.
  1230.  
  1231.    INPUTS
  1232.     string - NULL terminated text to calculate width of.
  1233.  
  1234.     textattr - a filled in TextAttr structure. Only the IText and
  1235.            ITextFont fields of the structure have to be filled in.
  1236.  
  1237.    RESULT
  1238.     textwidth - pixel length of the text
  1239. gadutil.library/GU_GetLocaleStr               gadutil.library/GU_GetLocaleStr
  1240.  
  1241.    NAME
  1242.     GU_GetLocaleStr -- Get a localized string from a catalog.
  1243.  
  1244.    SYNOPSIS
  1245.     string = GU_GetLocaleStr(stringID, catalog, defstrings)
  1246.     D0,A0                    D0        A0       A1
  1247.  
  1248.     STRPTR GU_GetLocaleStr(ULONG, struct Catalog *, struct AppString *);
  1249.  
  1250.    FUNCTION
  1251.     Get a localized string, or the default string, from a catalog or from
  1252.     the programs built-in strings.
  1253.  
  1254.    INPUTS
  1255.     stringID - the ID of the string to get
  1256.  
  1257.     catalog - the opened catalog for the program
  1258.  
  1259.     defstrings - an array of AppString structures, the programs built-in
  1260.              strings and ID's.
  1261.  
  1262.    RESULT
  1263.     string - the address of the localized string, or if the catalog was not
  1264.          available (or if the selected language was the programs built-
  1265.          ins), a pointer to the default string with the given ID.
  1266.  
  1267.    SEE ALSO
  1268.     GU_OpenCatalog(), GU_CloseCatalog()
  1269. gadutil.library/GU_CreateLocMenuA           gadutil.library/GU_CreateLocMenuA
  1270.  
  1271.    NAME
  1272.     GU_CreateLocMenuA -- Create a menu with localized items.
  1273.  
  1274.    SYNOPSIS
  1275.     menu = GU_CreateLocMenuA(newmenu, gad_info, createtags, layouttags)
  1276.     D0                       A0       A1        A2             A3
  1277.  
  1278.     struct Menu *GU_GetLocaleStr(struct NewMenu *, APTR,
  1279.                 struct TagItem *, struct TagItem *);
  1280.  
  1281.    FUNCTION
  1282.     Create and layout a localized menu. This function replaces both
  1283.     the gadtools/CreateMenusA and gadtools/LayoutMenusA functions. See
  1284.     those functions for a more in-depth description of this function.
  1285.  
  1286.    INPUTS
  1287.     newmenu - pointer to an array of initialized struct NewMenus. This
  1288.           differs from the GadTools function in that, instead of
  1289.           giving pointers to strings in the nm_Label and nm_CommKey
  1290.           fields of the structure, you should put a string ID in the
  1291.           nm_Label field of the structure. The string must be in the
  1292.           format "A\x00About...". The nm_CommKey field should be left
  1293.           empty.  ^^^^^^
  1294.               |    |
  1295.               |    |- nm_Label field for the NewMenu structure
  1296.               |
  1297.               |- nm_CommKey replacement. If no keyboard shortcut,
  1298.                     this field MUST CONTAIN A SPACE CHAR.
  1299.                     The \x00 is a NULL character.
  1300.  
  1301.     gad_info - the value returned from GU_LayoutGadgetsA
  1302.  
  1303.     createtags - tags for the "CreateMenusA" part of this routine. All
  1304.              gadtools tags are supported (directly passed to GT).
  1305.  
  1306.     layouttags - tags for the "LayoutMenusA" part of this routine. All
  1307.              gadtools tags are supported (directly passed to GT).
  1308.  
  1309.    TAGS
  1310.     See the gadtools functions CreateMenusA and LayoutMenusA.
  1311.  
  1312.    RESULT
  1313.     menu - pointer to the resulting initialized and laid out menu structure,
  1314.            ready to pass to the intuition function SetMenuStrip, or NULL for
  1315.            failure.
  1316.  
  1317.    SEE ALSO
  1318.     GU_FreeMenusA(), gadtools/CreateMenusA(), gadtools/LayoutMenusA(),
  1319.     gadtools/FreeMenus()
  1320. gadutil.library/GU_OpenCatalog                 gadutil.library/GU_OpenCatalog
  1321.  
  1322.    NAME
  1323.     GU_OpenCatalog -- Open a message catalog.
  1324.  
  1325.    SYNOPSIS
  1326.     catalog = GU_OpenCatalog(name, version)
  1327.     D0                       A0    D0
  1328.  
  1329.     struct Catalog *GU_OpenCatalog(STRPTR, ULONG);
  1330.  
  1331.    FUNCTION
  1332.     This function opens a message catalog. Catalogs contain all the
  1333.     text strings that an application uses. These strings can easily
  1334.     be replaced by strings in a different language, which causes the
  1335.     application to magically start operation in that new language.
  1336.  
  1337.     Catalogs originally come from disk files. This function searches
  1338.     for them in the following places:
  1339.  
  1340.         PROGDIR:Catalogs/languageName/name
  1341.         LOCALE:Catalogs/languageName/name
  1342.  
  1343.     where languageName is the name of the language associated with the
  1344.     locale parameter.
  1345.  
  1346.    INPUTS
  1347.     catalogname - the NULL terminated name of the catalog to open (just
  1348.               the name, not the complete path to it).
  1349.  
  1350.     version - required version of the catalog to open. Passign 0 as version
  1351.           number means that the program will accept any found version of
  1352.           the catalog. Other values than 0 means exactly that version.
  1353.  
  1354.    RESULT
  1355.     catalog - A message catalog to use with GU_GetLocaleStr or any of the
  1356.           Locale library functions or NULL. NULL is returned on error
  1357.           or if the application can use its built-in strings instead
  1358.           of loading a catalog from disk.
  1359.  
  1360.    EXAMPLE
  1361.     GU_OpenCatalog("myprogram.catalog",0);
  1362.  
  1363.     will open any version of the catalog file "myprogram.catalog" found
  1364.     in either PROGDIR:Catalogs/languageName/ (where the program was started
  1365.     from), or LOCALE:Catalogs/languageName/.
  1366.  
  1367.     GU_OpenCatalog("myprogram.catalog",5);
  1368.  
  1369.     will open version 5 of the catalog file. If v5 is not available, the
  1370.     program will use its internal strings.
  1371.  
  1372.    NOTES
  1373.     If you want to specify other tags than the version tag, you must
  1374.     use the Locale library OpenCatalog(). This function is generally a
  1375.     shortcut to that function. By using this routine, you may not need
  1376.     to open Locale library at all.
  1377.  
  1378.     This routine assumes that the built-in language of the program is
  1379.     english. If you write your programs in another language, you must
  1380.     open the catalog by yourself.
  1381.  
  1382.    SEE ALSO
  1383.     GU_CloseCatalog(), locale/OpenCatalog()
  1384. gadutil.library/GU_CloseCatalog               gadutil.library/GU_CloseCatalog
  1385.  
  1386.    NAME
  1387.     GU_CloseCatalog -- Close a message catalog.
  1388.  
  1389.    SYNOPSIS
  1390.     GU_CloseCatalog(catalog)
  1391.                     A0
  1392.  
  1393.     VOID GU_CloseCatalog(struct Catalog *);
  1394.  
  1395.    FUNCTION
  1396.     Concludes access to a message catalog. The usage count of the
  1397.     catalog is decremented. When this count reaches 0, the catalog
  1398.     can be expunged from system memory whenever a memory panic occurs.
  1399.  
  1400.    INPUTS
  1401.     catalog - the message catalog to close. A NULL catalog is a valid
  1402.           parameter and is simply ignored.
  1403.  
  1404.    NOTES
  1405.     This function is a shortcut to the locale/CloseCatalog() function.
  1406.  
  1407.    SEE ALSO
  1408.     GU_OpenCatalog(), GU_GetLocaleStr()
  1409. gadutil.library/GU_DisableGadget             gadutil.library/GU_DisableGadget
  1410.  
  1411.    NAME
  1412.     GU_DisableGadget -- Disable / Enable a gadget.
  1413.  
  1414.    SYNOPSIS
  1415.     GU_DisableGadget(status, gadget, window)
  1416.                      D0,     A0,     A1
  1417.  
  1418.     VOID GU_DisableGadget(BOOL, struct Gadget *, struct Window *);
  1419.  
  1420.    FUNCTION
  1421.  
  1422.    INPUTS
  1423.  
  1424.    TAGS
  1425.  
  1426.    RESULT
  1427.  
  1428.    EXAMPLE
  1429.  
  1430.    NOTES
  1431.  
  1432.    WARNING
  1433.  
  1434.    BUGS
  1435.  
  1436.    SEE ALSO
  1437. gadutil.library/GU_SetToggle                     gadutil.library/GU_SetToggle
  1438.  
  1439.    NAME
  1440.     GU_SetToggle -- Change status of a toggle-select gadget.
  1441.  
  1442.    SYNOPSIS
  1443.     GU_SetToggle(status, gadget, window)
  1444.                  D0,     A0,     A1
  1445.  
  1446.     VOID GU_SetToggle(BOOL, struct Gadget *, struct Window *);
  1447.  
  1448.    FUNCTION
  1449.  
  1450.    INPUTS
  1451.  
  1452.    TAGS
  1453.  
  1454.    RESULT
  1455.  
  1456.    EXAMPLE
  1457.  
  1458.    NOTES
  1459.  
  1460.    WARNING
  1461.  
  1462.    BUGS
  1463.  
  1464.    SEE ALSO
  1465. gadutil.library/GU_RefreshBoxes               gadutil.library/GU_RefreshBoxes
  1466.  
  1467.    NAME
  1468.     GU_RefreshBoxes -- Redraw all bevel boxes in a window.
  1469.  
  1470.    SYNOPSIS
  1471.     GU_RefreshBoxes(window, gad_info)
  1472.                     A0      A1
  1473.  
  1474.     VOID GU_RefreshBoxes(struct Window *, APTR);
  1475.  
  1476.    FUNCTION
  1477.  
  1478.    INPUTS
  1479.  
  1480.    TAGS
  1481.  
  1482.    RESULT
  1483.  
  1484.    EXAMPLE
  1485.  
  1486.    NOTES
  1487.  
  1488.    WARNING
  1489.  
  1490.    BUGS
  1491.  
  1492.    SEE ALSO
  1493. gadutil.library/GU_RefreshWindow             gadutil.library/GU_RefreshWindow
  1494.  
  1495.    NAME
  1496.     GU_RefreshWindow -- Redraw bevel boxes and gadgets in a window.
  1497.  
  1498.    SYNOPSIS
  1499.     GU_RefreshWindow(window, gad_info)
  1500.                      A0      A1
  1501.  
  1502.     VOID GU_RefreshWindow(struct Window *, APTR);
  1503.  
  1504.    FUNCTION
  1505.     Perform the initial refresh of all the GadTools gadgets you have
  1506.     created. After you have opened your window, you must call this
  1507.     function. Or, if you have opened your window without gadgets,
  1508.     you add the gadgets with intuition/AddGList(), refresh them using
  1509.     intuition/RefreshGList(), then call this function. You should not
  1510.     need this function at other times.
  1511.  
  1512.     This function differs from the gadtools/GT_RefreshWindow(), in that
  1513.     is also renders all bevelbox kind gadgets. If NULL is given in
  1514.     gad_info, no boxes will be rendered, and this function will work
  1515.     exactly as the GT_RefreshWindow().
  1516.  
  1517.    INPUTS
  1518.     window - pointer to the window containing GadTools gadgets.
  1519.  
  1520.     gad_info - the value returned from GU_LayoutGadgetsA(), or NULL.
  1521.  
  1522.    SEE ALSO
  1523.     GU_BeginRefresh()
  1524. gadutil.library/GU_OpenFont                       gadutil.library/GU_OpenFont
  1525.  
  1526.    NAME
  1527.     GU_OpenFont -- Load and get a pointer to a disk or system font.
  1528.  
  1529.    SYNOPSIS
  1530.     font = GU_OpenFont(textAttr)
  1531.     D0                 A0
  1532.  
  1533.     struct TextFont *GU_OpenFont(struct TextAttr *);
  1534.  
  1535.    FUNCTION
  1536.  
  1537.    INPUTS
  1538.  
  1539.    TAGS
  1540.  
  1541.    RESULT
  1542.  
  1543.    EXAMPLE
  1544.  
  1545.    NOTES
  1546.  
  1547.    WARNING
  1548.  
  1549.    BUGS
  1550.  
  1551.    SEE ALSO
  1552. gadutil.library/GU_NewList                         gadutil.library/GU_NewList
  1553.  
  1554.    NAME
  1555.     GU_NewList -- Initialize a list header for use.
  1556.  
  1557.    SYNOPSIS
  1558.     GU_NewList(list)
  1559.                A0
  1560.  
  1561.     VOID GU_NewList(struct List *);
  1562.  
  1563.    FUNCTION
  1564.  
  1565.    INPUTS
  1566.  
  1567.    TAGS
  1568.  
  1569.    RESULT
  1570.  
  1571.    EXAMPLE
  1572.  
  1573.    NOTES
  1574.  
  1575.    WARNING
  1576.  
  1577.    BUGS
  1578.  
  1579.    SEE ALSO
  1580. gadutil.library/GU_ClearList                     gadutil.library/GU_ClearList
  1581.  
  1582.    NAME
  1583.     GU_ClearList -- Clear a listview gadget and deallocate all its nodes.
  1584.  
  1585.    SYNOPSIS
  1586.     GU_ClearList(gad, win, list)
  1587.                  D0   A0   A1
  1588.  
  1589.     VOID GU_ClearList(struct Gadget *, struct Window *, struct List *);
  1590.  
  1591.    FUNCTION
  1592.  
  1593.    INPUTS
  1594.  
  1595.    TAGS
  1596.  
  1597.    RESULT
  1598.  
  1599.    EXAMPLE
  1600.  
  1601.    NOTES
  1602.  
  1603.    WARNING
  1604.  
  1605.    BUGS
  1606.  
  1607.    SEE ALSO
  1608. gadutil.library/GU_DetachList                   gadutil.library/GU_DetachList
  1609.  
  1610.    NAME
  1611.     GU_DetachList -- Disconnect the list from a listview gadget.
  1612.  
  1613.    SYNOPSIS
  1614.     GU_DetachList(gad, win)
  1615.                   D0   A0
  1616.  
  1617.     VOID GU_DetachList(struct Gadget *, struct Window *);
  1618.  
  1619.    FUNCTION
  1620.  
  1621.    INPUTS
  1622.  
  1623.    TAGS
  1624.  
  1625.    RESULT
  1626.  
  1627.    EXAMPLE
  1628.  
  1629.    NOTES
  1630.  
  1631.    WARNING
  1632.  
  1633.    BUGS
  1634.  
  1635.    SEE ALSO
  1636. gadutil.library/GU_AttachList                   gadutil.library/GU_AttachList
  1637.  
  1638.    NAME
  1639.     GU_AttachList -- Change a listview's current list.
  1640.  
  1641.    SYNOPSIS
  1642.     GU_AttachList(gad, win, list)
  1643.                   D0   A0   A1
  1644.  
  1645.     VOID GU_AttachList(struct Gadget *, struct Window *, struct List *);
  1646.  
  1647.    FUNCTION
  1648.  
  1649.    INPUTS
  1650.  
  1651.    TAGS
  1652.  
  1653.    RESULT
  1654.  
  1655.    EXAMPLE
  1656.  
  1657.    NOTES
  1658.  
  1659.    WARNING
  1660.  
  1661.    BUGS
  1662.  
  1663.    SEE ALSO
  1664. gadutil.library/GU_AddTail                         gadutil.library/GU_AddTail
  1665.  
  1666.    NAME
  1667.     GU_AddTail -- Add a node to the end of a listview's list.
  1668.  
  1669.    SYNOPSIS
  1670.     node = GU_AddTail(gad, string, list)
  1671.     D0                D0   A0      A1
  1672.  
  1673.     struct Node *GU_AddTail(struct Gadget *, STRPTR, struct List *);
  1674.  
  1675.    FUNCTION
  1676.  
  1677.    INPUTS
  1678.  
  1679.    TAGS
  1680.  
  1681.    RESULT
  1682.  
  1683.    EXAMPLE
  1684.  
  1685.    NOTES
  1686.  
  1687.    WARNING
  1688.  
  1689.    BUGS
  1690.  
  1691.    SEE ALSO
  1692. gadutil.library/GU_ChangeStr                     gadutil.library/GU_ChangeStr
  1693.  
  1694.    NAME
  1695.     GU_ChangeStr -- Change the contents of string gadget.
  1696.  
  1697.    SYNOPSIS
  1698.     GU_ChangeStr(gad, string, win)
  1699.                  D0   A0      A1
  1700.  
  1701.     VOID GU_ChangeStr(struct Gadget *, struct Window *, STRPTR);
  1702.  
  1703.    FUNCTION
  1704.  
  1705.    INPUTS
  1706.  
  1707.    TAGS
  1708.  
  1709.    RESULT
  1710.  
  1711.    EXAMPLE
  1712.  
  1713.    NOTES
  1714.  
  1715.    WARNING
  1716.  
  1717.    BUGS
  1718.  
  1719.    SEE ALSO
  1720. gadutil.library/GU_CreateContext             gadutil.library/GU_CreateContext
  1721.  
  1722.    NAME
  1723.     GU_CreateContext -- Create a space for GadTools context data.
  1724.  
  1725.    SYNOPSIS
  1726.     gad = GU_CreateContext(glistptr)
  1727.     D0                     A0
  1728.  
  1729.     struct Gadget *GU_CreateContext(struct Gadget **);
  1730.  
  1731.    FUNCTION
  1732.  
  1733.    INPUTS
  1734.  
  1735.    TAGS
  1736.  
  1737.    RESULT
  1738.  
  1739.    EXAMPLE
  1740.  
  1741.    NOTES
  1742.  
  1743.    WARNING
  1744.  
  1745.    BUGS
  1746.  
  1747.    SEE ALSO
  1748.     gadtools/CreateContext()
  1749. gadutil.library/GU_GetGadgetAttrsA         gadutil.library/GU_GetGadgetAttrsA
  1750.  
  1751.    NAME
  1752.     GU_GetGadgetAttrsA -- Request the attributes of a GadTools gadget.
  1753.  
  1754.    SYNOPSIS
  1755.     numProcessed = GU_GetGadgetAttrsA(gad, win, req, taglist)
  1756.     D0                                A0   A1   A2   A3
  1757.  
  1758.     LONG *GU_GetGadgetAttrsA(struct Gadget *, struct Window *,
  1759.                  struct Requester *, struct TagItem *);
  1760.  
  1761.    FUNCTION
  1762.  
  1763.    INPUTS
  1764.  
  1765.    TAGS
  1766.  
  1767.    RESULT
  1768.  
  1769.    EXAMPLE
  1770.  
  1771.    NOTES
  1772.  
  1773.    WARNING
  1774.  
  1775.    BUGS
  1776.  
  1777.    SEE ALSO
  1778.     GU_SetGadgetAttrsA(), gadtools/GT_GetGadgetAttrsA()
  1779. gadutil.library/GU_CreateMenusA               gadutil.library/GU_CreateMenusA
  1780.  
  1781.    NAME
  1782.     GU_CreateMenusA -- Allocate and fill out a menu structure.
  1783.  
  1784.    SYNOPSIS
  1785.     menu = GU_CreateMenusA(newmenu, taglist)
  1786.     D0                     A0       A1
  1787.  
  1788.     struct Menu *GU_CreateMenusA(struct NewMenu *, struct TagItem *);
  1789.  
  1790.    FUNCTION
  1791.  
  1792.    INPUTS
  1793.  
  1794.    TAGS
  1795.  
  1796.    RESULT
  1797.  
  1798.    EXAMPLE
  1799.  
  1800.    NOTES
  1801.  
  1802.    WARNING
  1803.  
  1804.    BUGS
  1805.  
  1806.    SEE ALSO
  1807.     GU_LayoutMenusA(), GU_FreeMenus(), gadtools/CreateMenusA()
  1808. gadutil.library/GU_FreeMenus                     gadutil.library/GU_FreeMenus
  1809.  
  1810.    NAME
  1811.     GU_FreeMenus -- Frees memory allocated by GU_CreateMenusA().
  1812.  
  1813.    SYNOPSIS
  1814.     GU_FreeMenus(menu)
  1815.                  A0
  1816.  
  1817.     VOID GU_FreeMenus(struct Menu *);
  1818.  
  1819.    FUNCTION
  1820.  
  1821.    INPUTS
  1822.  
  1823.    TAGS
  1824.  
  1825.    RESULT
  1826.  
  1827.    EXAMPLE
  1828.  
  1829.    NOTES
  1830.  
  1831.    WARNING
  1832.  
  1833.    BUGS
  1834.  
  1835.    SEE ALSO
  1836.     GU_CreateMenusA(), gadtools/FreeMenus()
  1837. gadutil.library/GU_LayoutMenuItemsA       gadutil.library/GU_LayoutMenuItemsA
  1838.  
  1839.    NAME
  1840.     GU_LayoutMenuItemsA -- Position all the menu items.
  1841.  
  1842.    SYNOPSIS
  1843.     success = GU_LayoutMenuItemsA(menuitem, vi, tags)
  1844.     D0                            A0        A1  A2
  1845.  
  1846.     BOOL GU_LayoutMenuItemsA(struct MenuItem *, APTR, struct TagItem *);
  1847.  
  1848.    FUNCTION
  1849.  
  1850.    INPUTS
  1851.  
  1852.    TAGS
  1853.  
  1854.    RESULT
  1855.  
  1856.    EXAMPLE
  1857.  
  1858.    NOTES
  1859.  
  1860.    WARNING
  1861.  
  1862.    BUGS
  1863.  
  1864.    SEE ALSO
  1865.     GU_CreateMenusA(), GU_GetVisualInfoA(), gadtools/LayoutMenuItemsA()
  1866. gadutil.library/GU_LayoutMenusA       gadutil.library/GU_LayoutMenusA
  1867.  
  1868.    NAME
  1869.     GU_LayoutMenusA -- Position all the menus and menu items.
  1870.  
  1871.    SYNOPSIS
  1872.     success = GU_LayoutMenusA(menu, vi, taglist)
  1873.     D0                        A0    A1  A2
  1874.  
  1875.     BOOL GU_LayoutMenusA(struct Menu *, APTR, struct TagItem *);
  1876.  
  1877.    FUNCTION
  1878.  
  1879.    INPUTS
  1880.  
  1881.    TAGS
  1882.  
  1883.    RESULT
  1884.  
  1885.    EXAMPLE
  1886.  
  1887.    NOTES
  1888.  
  1889.    WARNING
  1890.  
  1891.    BUGS
  1892.  
  1893.    SEE ALSO
  1894.     GU_CreateMenusA(), GU_GetVisualInfoA(), gadtools/LayoutMenusA()
  1895. gadutil.library/GU_GetVisualInfoA           gadutil.library/GU_GetVisualInfoA
  1896.  
  1897.    NAME
  1898.     GU_GetVisualInfoA -- Get information GadTools needs for visuals.
  1899.  
  1900.    SYNOPSIS
  1901.     vi = GU_GetVisualInfoA(screen, taglist)
  1902.     D0                     A0      A1
  1903.  
  1904.     APTR GU_GetVisualInfoA(struct Screen *, struct TagItem *);
  1905.  
  1906.    FUNCTION
  1907.  
  1908.    INPUTS
  1909.  
  1910.    TAGS
  1911.  
  1912.    RESULT
  1913.  
  1914.    EXAMPLE
  1915.  
  1916.    NOTES
  1917.  
  1918.    WARNING
  1919.  
  1920.    BUGS
  1921.  
  1922.    SEE ALSO
  1923.     GU_FreeVisualInfo(), gadtools/FreeVisualInfo(), intuition(/LockPubScreen(),
  1924.     intuition/UnlockPubScreen()
  1925. gadutil.library/GU_FreeVisualInfo           gadutil.library/GU_FreeVisualInfo
  1926.  
  1927.    NAME
  1928.     GU_FreeVisualInfo -- Return any resources taken by GU_GetVisualInfoA
  1929.  
  1930.    SYNOPSIS
  1931.     GU_FreeVisualInfo(vi)
  1932.                       A0
  1933.  
  1934.     VOID GU_FreeVisualInfo(APTR);
  1935.  
  1936.    FUNCTION
  1937.  
  1938.    INPUTS
  1939.  
  1940.    TAGS
  1941.  
  1942.    RESULT
  1943.  
  1944.    EXAMPLE
  1945.  
  1946.    NOTES
  1947.  
  1948.    WARNING
  1949.  
  1950.    BUGS
  1951.  
  1952.    SEE ALSO
  1953.     GU_GetVisualInfoA(), gadtools/FreeVisualInfo()
  1954. gadutil.library/GU_BeginRefresh               gadutil.library/GU_BeginRefresh
  1955.  
  1956.    NAME
  1957.     GU_BeginRefresh -- Begin refreshing friendly to GadTools.
  1958.  
  1959.    SYNOPSIS
  1960.     GU_BeginRefresh(win)
  1961.                     A0
  1962.  
  1963.     VOID GU_BeginRefresh(struct Window *);
  1964.  
  1965.    FUNCTION
  1966.  
  1967.    INPUTS
  1968.  
  1969.    TAGS
  1970.  
  1971.    RESULT
  1972.  
  1973.    EXAMPLE
  1974.  
  1975.    NOTES
  1976.  
  1977.    WARNING
  1978.  
  1979.    BUGS
  1980.  
  1981.    SEE ALSO
  1982.     GU_EndRefresh(), gadtools/GT_BeginRefresh, intuition/BeginRefresh()
  1983. gadutil.library/GU_EndRefresh                   gadutil.library/GU_EndRefresh
  1984.  
  1985.    NAME
  1986.     GU_EndRefresh -- End refreshing friendly to GadTools.
  1987.  
  1988.    SYNOPSIS
  1989.     GU_EndRefresh(win, complete)
  1990.                   A0   D0
  1991.  
  1992.     VOID GU_EndRefresh(struct Window *, BOOL);
  1993.  
  1994.    FUNCTION
  1995.  
  1996.    INPUTS
  1997.  
  1998.    TAGS
  1999.  
  2000.    RESULT
  2001.  
  2002.    EXAMPLE
  2003.  
  2004.    NOTES
  2005.  
  2006.    WARNING
  2007.  
  2008.    BUGS
  2009.  
  2010.    SEE ALSO
  2011.     GU_BeginRefresh(), gadtools/GT_EndRefresh(), intuition/EndRefresh()
  2012. gadutil.library/GU_FilterIMsg                   gadutil.library/GU_FilterIMsg
  2013.  
  2014.    NAME
  2015.     GU_FilterIMsg -- Filter an IntuiMessage through GadTools.
  2016.  
  2017.    SYNOPSIS
  2018.     modimsg = GU_FilterIMsg(imsg)
  2019.     D0                      A1
  2020.  
  2021.     struct IntuiMessage *GU_FilterIMsg(struct IntuiMessage *);
  2022.  
  2023.    FUNCTION
  2024.  
  2025.    INPUTS
  2026.  
  2027.    TAGS
  2028.  
  2029.    RESULT
  2030.  
  2031.    EXAMPLE
  2032.  
  2033.    NOTES
  2034.  
  2035.    WARNING
  2036.  
  2037.    BUGS
  2038.  
  2039.    SEE ALSO
  2040.     GU_GetIMsg(), GU_PostFilterIMsg(), gadtools/GT_FilterIMsg()
  2041. gadutil.library/GU_PostFilterIMsg           gadutil.library/GU_PostFilterIMsg
  2042.  
  2043.    NAME
  2044.     GU_PostFilterIMsg -- Return the unfiltered message after
  2045.                  GU_FilterIMsg() was called, and clean up.
  2046.  
  2047.    SYNOPSIS
  2048.     imsg = GU_PostFilterIMsg(modimsg)
  2049.     D0                       A1
  2050.  
  2051.     struct IntuiMessage *GU_PostFilterIMsg(struct IntuiMessage *);
  2052.  
  2053.    FUNCTION
  2054.  
  2055.    INPUTS
  2056.  
  2057.    TAGS
  2058.  
  2059.    RESULT
  2060.  
  2061.    EXAMPLE
  2062.  
  2063.    NOTES
  2064.  
  2065.    WARNING
  2066.  
  2067.    BUGS
  2068.  
  2069.    SEE ALSO
  2070.     GU_FilterIMsg(), gadtools/GT_PostFilterIMsg()
  2071. gadutil.library/GU_ReplyIMsg                     gadutil.library/GU_ReplyIMsg
  2072.  
  2073.    NAME
  2074.     GU_ReplyIMsg -- Reply a message obtained with GU_GetIMsg().
  2075.  
  2076.    SYNOPSIS
  2077.     GU_ReplyIMsg(imsg)
  2078.                  A1
  2079.  
  2080.     VOID GU_ReplyIMsg(struct IntuiMessage *);
  2081.  
  2082.    FUNCTION
  2083.     Return a modified IntuiMessage obtained with GU_GetIMsg(). If you
  2084.     use GU_GetIMsg(), use this function where you would normally have
  2085.     used exec/ReplyIMsg() or gadtools/GT_ReplyIMsg(). You may safely
  2086.     call this function with a NULL pointer (nothing will be done).
  2087.  
  2088.    INPUTS
  2089.     imsg - a modified IntuiMessage obtained with GT_GetIMsg(), or NULL
  2090.            in which case this function does nothing.
  2091.  
  2092.    NOTES
  2093.     When using GadUtil, you MUST explicitly GU_ReplyIMsg() all messages
  2094.     you receive. You cannot depend on CloseWindow() to handle messages
  2095.     you have not replied.
  2096.  
  2097.     Starting with V39, this function actually expects a pointer to an
  2098.     ExtIntuiMessage structure, but the prototype was not changed for
  2099.     source code compatibility with older software.
  2100.  
  2101.    SEE ALSO
  2102.     GU_GetIMsg()
  2103. gadutil.library/GU_DrawBevelBoxA             gadutil.library/GU_DrawBevelBoxA
  2104.  
  2105.    NAME
  2106.     GU_DrawBevelBoxA -- Draw a bevelled box.
  2107.  
  2108.    SYNOPSIS
  2109.     GU_DrawBevelBoxA(rport, left, top, width, height, taglist)
  2110.                      A0     D0    D1   D2     D3      A1
  2111.  
  2112.     VOID GU_DrawBevelBoxA(struct RastPort *, WORD, WORD, WORD, WORD,
  2113.                   struct TagItem *);
  2114.  
  2115.    FUNCTION
  2116.  
  2117.    INPUTS
  2118.  
  2119.    TAGS
  2120.  
  2121.    RESULT
  2122.  
  2123.    EXAMPLE
  2124.  
  2125.    NOTES
  2126.  
  2127.    WARNING
  2128.  
  2129.    BUGS
  2130.  
  2131.    SEE ALSO
  2132.     GU_GetVisualInfoA(), gadtools/DrawBevelBoxA()
  2133. gadutil.library/GU_FindNode                       gadutil.library/GU_FindNode
  2134.  
  2135.    NAME
  2136.     GU_FindNode -- Find the node structure of a given node number
  2137.  
  2138.    SYNOPSIS
  2139.     node = GU_FindNode(list, number)
  2140.     D0                 A0    D0
  2141.  
  2142.     struct Node *GU_FindNode(struct List *, WORD);
  2143.  
  2144.    FUNCTION
  2145.  
  2146.    INPUTS
  2147.  
  2148.    TAGS
  2149.  
  2150.    RESULT
  2151.  
  2152.    EXAMPLE
  2153.  
  2154.    NOTES
  2155.  
  2156.    WARNING
  2157.  
  2158.    BUGS
  2159.  
  2160.    SEE ALSO
  2161. gadutil.library/GU_NodeUp                           gadutil.library/GU_NodeUp
  2162.  
  2163.    NAME
  2164.     GU_NodeUp -- Move a node one step towards the top of the list
  2165.  
  2166.    SYNOPSIS
  2167.     success = GU_NodeUp(node, list)
  2168.     D0                  A0    A1
  2169.  
  2170.     BOOL GU_NodeUp(struct Node *, struct List *);
  2171.  
  2172.    FUNCTION
  2173.  
  2174.    INPUTS
  2175.  
  2176.    TAGS
  2177.  
  2178.    RESULT
  2179.  
  2180.    EXAMPLE
  2181.  
  2182.    NOTES
  2183.  
  2184.    WARNING
  2185.  
  2186.    BUGS
  2187.  
  2188.    SEE ALSO
  2189. gadutil.library/GU_NodeDown                       gadutil.library/GU_NodeDown
  2190.  
  2191.    NAME
  2192.     GU_NodeDown -- Move a node one step towards the end of the list
  2193.  
  2194.    SYNOPSIS
  2195.     success = GU_NodeDown(node, list)
  2196.     D0                    A0    A1
  2197.  
  2198.     BOOL GU_NodeDown(struct Node *, struct List *);
  2199.  
  2200.    FUNCTION
  2201.  
  2202.    INPUTS
  2203.  
  2204.    TAGS
  2205.  
  2206.    RESULT
  2207.  
  2208.    EXAMPLE
  2209.  
  2210.    NOTES
  2211.  
  2212.    WARNING
  2213.  
  2214.    BUGS
  2215.  
  2216.    SEE ALSO
  2217. gadutil.library/GU_UpdateProgress           gadutil.library/GU_UpdateProgress
  2218.  
  2219.    NAME
  2220.     GU_UpdateProgress -- Redraw all or specified progress gadget(s).
  2221.  
  2222.    SYNOPSIS
  2223.     GU_UpdateProgress(window, gad_info, gadget)
  2224.                       A0      A1        A2
  2225.  
  2226.     VOID GU_UpdateProgress(struct Window *, APTR, struct ProgressGad *);
  2227.  
  2228.    FUNCTION
  2229.         Redraws all or one specified PROGRESS_KIND gadget in a window.
  2230.  
  2231.    INPUTS
  2232.         window - the window that the progress gadget is in.
  2233.  
  2234.         gad_info - the value returned from GU_LayoutGadgetsA()
  2235.  
  2236.         gadget - NULL, or a pointer to a specified progress gadget to
  2237.                  redraw. If NULL is given, all progress gadgets will be
  2238.                  redrawn. Use this function to redraw the progress gad
  2239.                  after changing the total or current value.
  2240.                  This function is called automatically from GU_Refresh-
  2241.                  Boxes.
  2242.  
  2243.    SEE ALSO
  2244.         GU_RefreshBoxes(), GU_RefreshWindow()
  2245.