home *** CD-ROM | disk | FTP | other *** search
/ Amiga Developer CD v1.2 / amidev_cd_12.iso / inc&ad2.0 / text_autodocs / gadtools.doc < prev    next >
Text File  |  1992-09-01  |  36KB  |  1,100 lines
  1. TABLE OF CONTENTS
  2.  
  3. gadtools.library/CreateContext
  4. gadtools.library/CreateGadgetA
  5. gadtools.library/CreateMenusA
  6. gadtools.library/DrawBevelBoxA
  7. gadtools.library/FreeGadgets
  8. gadtools.library/FreeMenus
  9. gadtools.library/FreeVisualInfo
  10. gadtools.library/GetVisualInfoA
  11. gadtools.library/GT_BeginRefresh
  12. gadtools.library/GT_EndRefresh
  13. gadtools.library/GT_FilterIMsg
  14. gadtools.library/GT_GetIMsg
  15. gadtools.library/GT_PostFilterIMsg
  16. gadtools.library/GT_RefreshWindow
  17. gadtools.library/GT_ReplyIMsg
  18. gadtools.library/GT_SetGadgetAttrsA
  19. gadtools.library/LayoutMenuItemsA
  20. gadtools.library/LayoutMenusA
  21. gadtools.library/CreateContext                 gadtools.library/CreateContext
  22.  
  23.    NAME
  24.     CreateContext -- Create a place for GadTools context data. (V36)
  25.  
  26.    SYNOPSIS
  27.     gad = CreateContext(glistpointer);
  28.     D0                  A0
  29.  
  30.     struct Gadget *CreateContext(struct Gadget **);
  31.  
  32.    FUNCTION
  33.     Creates a place for GadTools to store any context data it might
  34.     need for your window.  In reality, an unselectable invisible
  35.     gadget is created, with room for the context data.
  36.     This function also establishes the linkage from a glist type
  37.     pointer to the individual gadget pointers.  Call this function
  38.     before any of the other gadget creation calls.
  39.  
  40.    INPUTS
  41.     glistptr - Address of a pointer to a Gadget, which was previously
  42.         set to NULL.  When all the gadget creation is done, you may
  43.         use that pointer as your NewWindow.FirstGadget, or
  44.         in intuition.library/AddGList(), intuition.library/RefreshGList(),
  45.         FreeGadgets(), etc.
  46.  
  47.    RESULT
  48.     gad - Pointer to context gadget, or NULL if failure.
  49.  
  50.    EXAMPLE
  51.  
  52.     struct Gadget *gad;
  53.     struct Gadget *glist = NULL;
  54.     gad = CreateContext(&glist);
  55.     /*  Other creation calls go here */
  56.     if (gad)
  57.     {
  58.         myNewWindow.FirstGadget = glist;
  59.         if ( myWindow = OpenWindow(&myNewWindow) )
  60.         {
  61.         GT_RefreshWindow(win);
  62.         /* other stuff */
  63.         CloseWindow(myWindow);
  64.         }
  65.     }
  66.     FreeGadgets(glist);
  67.  
  68.    NOTES
  69.  
  70.    BUGS
  71.  
  72.    SEE ALSO
  73.  
  74. gadtools.library/CreateGadgetA                 gadtools.library/CreateGadgetA
  75.  
  76.    NAME
  77.     CreateGadgetA -- Allocate and initialize a gadtools gadget. (V36)
  78.     CreateGadget -- Varargs stub for CreateGadgetA(). (V36)
  79.  
  80.    SYNOPSIS
  81.     gad = CreateGadgetA(kind, previous, newgad, taglist)
  82.     D0                  D0    A0        A1      A2
  83.     
  84.     struct Gadget *CreateGadgetA(ULONG, struct Gadget *,
  85.         struct NewGadget *, struct TagItem *);
  86.  
  87.     gad = CreateGadget(kind, previous, newgad, firsttag, ...)
  88.     
  89.     struct Gadget *CreateGadget(ULONG, struct Gadget *,
  90.         struct NewGadget *, Tag, ...);
  91.  
  92.    FUNCTION
  93.     CreateGadgetA() allocates and initializes a new gadget of the
  94.     specified kind, and attaches it to the previous gadget.  The
  95.     gadget is created based on the supplied kind, NewGadget structure,
  96.     and tags.
  97.  
  98.    INPUTS
  99.     kind - to indicate what kind of gadget is to be created.
  100.     previous - pointer to the previous gadget that this new gadget
  101.         is to be attached to.
  102.     newgad - a filled in NewGadget structure describing the desired
  103.         gadget's size, position, label, etc.
  104.     taglist - pointer to a TagItem list.
  105.  
  106.    TAGS
  107.     All kinds:
  108.     GT_Underscore (GadTools V37 and higher only).
  109.         Indicates the symbol that precedes the character in the gadget
  110.         label to be underscored.  This would be to indicate keyboard
  111.         equivalents for gadgets (note that GadTools does not process
  112.         the keys - it just displays the underscore).
  113.         Example: To underscore the "M" in "Mode"...
  114.         ng.ng_GadgetText = "_Mode:";
  115.         gad = CreateGadget(..._KIND, &ng, prev,
  116.             GT_Underscore, '_',
  117.             ...
  118.             );
  119.  
  120.     BUTTON_KIND (action buttons):
  121.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  122.         (defaults to FALSE).
  123.  
  124.     CHECKBOX_KIND (on/off items):
  125.     GTCB_Checked (BOOL) - Initial state of checkbox, defaults to FALSE.
  126.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  127.         (defaults to FALSE).
  128.  
  129.     CYCLE_KIND (multiple state selections):
  130.     GTCY_Labels (STRPTR *) - Pointer to NULL-terminated array of strings
  131.         that are the choices offered by the cycle gadget (required).
  132.     GTCY_Active (UWORD) - The ordinal number (counting from zero) of
  133.         the initially active choice of a cycle gadget (defaults to zero).
  134.     GA_Disabled (BOOL) - (GadTools V37 and higher only)
  135.         Set to TRUE to disable gadget, FALSE otherwise
  136.         (defaults to FALSE).
  137.  
  138.     INTEGER_KIND (numeric entry):
  139.     GTIN_Number (ULONG) - The initial contents of the integer gadget
  140.         (default zero).
  141.     GTIN_MaxChars (UWORD) - The maximum number of digits that the
  142.         integer gadget is to hold (defaults to 10).
  143.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  144.         (defaults to FALSE).
  145.     STRINGA_ExitHelp (BOOL) - (New for V37) Set to TRUE to have the
  146.         help-key cause an exit from the integer gadget.  You will
  147.         then receive a GADGETUP with code = 0x5F (rawkey for help).
  148.     GA_TabCycle (BOOL) - (New for V37) Set to TRUE so that pressing
  149.         <TAB> or <Shift-TAB> will activate the next or previous
  150.         such gadget. (defaults to TRUE, unlike regular Intuition string
  151.         gadgets, which default to FALSE).
  152.     GTST_EditHook (struct Hook *) - (new for V37) Hook to use as a custom
  153.         integer gadget edit hook (StringExtend->EditHook) for this gadget.
  154.         GadTools will allocate the StringExtend->WorkBuffer for you.
  155.         Defaults to NULL.
  156.     STRINGA_Justification - (new for V37) Controls the justification of
  157.         the contents of an integer gadget.  Choose one of STRINGLEFT,
  158.         STRINGRIGHT, or STRINGCENTER.  (Defaults to STRINGLEFT).
  159.     STRINGA_ReplaceMode (BOOL) - (new for V37) If TRUE, this integer gadget
  160.         is in replace-mode.  Defaults to FALSE (insert-mode).
  161.  
  162.     LISTVIEW_KIND (scrolling list):
  163.     GTLV_Top (WORD) - Top item visible in the listview.  This value
  164.         will be made reasonable if out-of-range (defaults to zero).
  165.     GTLV_Labels (struct List *) - List of labels whose ln_Name fields
  166.         are to be displayed in the listview.
  167.     GTLV_ReadOnly (BOOL) - If TRUE, then listview is read-only.
  168.     GTLV_ScrollWidth (UWORD) - Width of scroll bar for listview.
  169.         Must be greater than zero (defaults to 16).
  170.     GTLV_ShowSelected (struct Gadget *) - NULL to have the currently
  171.         selected item displayed beneath the listview, or pointer to
  172.         an already-created GadTools STRING_KIND gadget to have an
  173.         editable display of the currently selected item.
  174.     GTLV_Selected (UWORD) - Ordinal number of currently selected
  175.         item, or ~0 to have no current selection (defaults to ~0).
  176.     LAYOUTA_Spacing - Extra space to place between lines of listview
  177.         (defaults to zero).
  178.  
  179.     MX_KIND (mutually exclusive, radio buttons):
  180.     GTMX_Labels (STRPTR *) - Pointer to a NULL-terminated array of
  181.         strings which are to be the labels beside each choice in a
  182.         set of mutually exclusive gadgets.
  183.     GTMX_Active (UWORD) - The ordinal number (counting from zero) of
  184.         the initially active choice of an mx gadget (Defaults to zero).
  185.     GTMX_Spacing (UWORD) - The amount of space between each choice
  186.         of a set of mutually exclusive gadgets.  This amount is added
  187.         to the font height to produce the vertical shift between
  188.         choices. (defaults to one).
  189.     LAYOUTA_Spacing - FOR COMPATIBILITY ONLY.  Use GTMX_Spacing instead.
  190.         The number of extra pixels to insert between
  191.         each choice of a mutually exclusive gadget.  This is added
  192.         to the present gadget image height (9) to produce the
  193.         true spacing between choices.  (defaults to 
  194.         FontHeight-8, which is zero for 8-point font users).
  195.  
  196.     NUMBER_KIND (read-only numeric):
  197.     GTNM_Number - A signed long integer to be displayed as a read-only
  198.          number (default 0).
  199.     GTNM_Border (BOOL) - If TRUE, this flag asks for a recessed
  200.         border to be placed around the gadget.
  201.  
  202.     PALETTE_KIND (color selection):
  203.     GTPA_Depth (UWORD) - Number of bitplanes in the palette
  204.         (defaults to 1).
  205.     GTPA_Color (UBYTE) - Initially selected color of the palette
  206.         (defaults to 1).
  207.     GTPA_ColorOffset (UBYTE) - First color to use in palette
  208.         (defaults to zero).
  209.     GTPA_IndicatorWidth (UWORD) - The desired width of the current-color
  210.         indicator, if you want one to the left of the palette.
  211.     GTPA_IndicatorHeight (UWORD) - The desired height of the current-color
  212.         indicator, if you want one above the palette.
  213.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  214.         (defaults to FALSE).
  215.  
  216.     SCROLLER_KIND (for scrolling through areas or lists):
  217.     GTSC_Top (WORD) - Top visible in area scroller represents
  218.         (defaults to zero).
  219.     GTSC_Total (WORD) - Total in area scroller represents
  220.         (defaults to zero).
  221.     GTSC_Visible (WORD) - Number visible in scroller (defaults to 2).
  222.     GTSC_Arrows (UWORD) - Asks for arrows to be attached to the scroller.
  223.         The value supplied will be taken as the width of each arrow button
  224.         for a horizontal scroller, or the height of each button for a
  225.         vertical scroller (the other dimension will match the whole
  226.         scroller).
  227.     PGA_Freedom - Whether scroller is horizontal or vertical.
  228.         Choose LORIENT_VERT or LORIENT_HORIZ (defaults to horiz).
  229.     GA_Immediate (BOOL) - Hear every IDCMP_GADGETDOWN event from scroller
  230.         (defaults to FALSE).
  231.     GA_RelVerify (BOOL) - Hear every IDCMP_GADGETUP event from scroller
  232.         (defaults to FALSE).
  233.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  234.         (defaults to FALSE).
  235.  
  236.     SLIDER_KIND (to indicate level or intensity):
  237.     GTSL_Min (WORD) - Minimum level for slider (default 0).
  238.     GTSL_Max (WORD) - Maximum level for slider (default 15).
  239.     GTSL_Level (WORD) - Current level of slider (default 0).
  240.     GTSL_MaxLevelLen (UWORD) - Max. length in characters of level string
  241.         when rendered beside slider.
  242.     GTSL_LevelFormat (STRPTR) - C-Style formatting string for slider
  243.         level.  Be sure to use the 'l' (long) modifier.  This string
  244.         is processed using exec/RawDoFmt(), so refer to that function
  245.         for details.
  246.     GTSL_LevelPlace - One of PLACETEXT_LEFT, PLACETEXT_RIGHT,
  247.         PLACETEXT_ABOVE, or PLACETEXT_BELOW, indicating where the level
  248.         indicator is to go relative to slider (default to PLACETEXT_LEFT).
  249.     GTSL_DispFunc ( LONG (*function)(struct Gadget *, WORD) ) - Function
  250.         to calculate level to be displayed.  A number-of-colors slider
  251.         might want to set the slider up to think depth, and have a
  252.         (1 << n) function here.  Defaults to none.  Your function must
  253.         take a pointer to gadget as the first parameter, the level
  254.         (a WORD) as the second, and return the result as a LONG.
  255.     GA_Immediate (BOOL) - If you want to hear each slider IDCMP_GADGETDOWN
  256.         event.
  257.     GA_RelVerify (BOOL) - If you want to hear each slider IDCMP_GADGETUP
  258.         event.
  259.     PGA_Freedom - Set to LORIENT_VERT or LORIENT_HORIZ to have a
  260.         vertical or horizontal slider.
  261.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  262.         (defaults to FALSE).
  263.  
  264.     STRING_KIND (text-entry):
  265.     GTST_String (STRPTR) - The initial contents of the string gadget,
  266.          or NULL (default) if string is to start empty.
  267.     GTST_MaxChars (UWORD) - The maximum number of characters that the
  268.         string gadget is to hold.
  269.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  270.         (defaults to FALSE).
  271.     STRINGA_ExitHelp (BOOL) - (New for V37) Set to TRUE to have the
  272.         help-key cause an exit from the string gadget.  You will
  273.         then receive a GADGETUP with code = 0x5F (rawkey for help).
  274.     GA_TabCycle (BOOL) - (New for V37) Set to TRUE so that pressing
  275.         <TAB> or <Shift-TAB> will activate the next or previous
  276.         such gadget. (defaults to TRUE, unlike regular Intuition string
  277.         gadgets, which default to FALSE).
  278.     GTST_EditHook (struct Hook *) - (new for V37) Hook to use as a custom
  279.         string gadget edit hook (StringExtend->EditHook) for this gadget.
  280.         GadTools will allocate the StringExtend->WorkBuffer for you.
  281.         Defaults to NULL.
  282.     STRINGA_Justification - (new for V37) Controls the justification of
  283.         the contents of a string gadget.  Choose one of STRINGLEFT,
  284.         STRINGRIGHT, or STRINGCENTER.  (Defaults to STRINGLEFT).
  285.     STRINGA_ReplaceMode (BOOL) - (new for V37) If TRUE, this string gadget
  286.         is in replace-mode.  Defaults to FALSE (insert-mode).
  287.  
  288.     TEXT_KIND (read-only text):
  289.     GTTX_Text - Pointer to a NULL terminated string to be displayed,
  290.         as a read-only text-display gadget, or NULL. defaults to NULL.
  291.     GTTX_CopyText (BOOL) -    This flag instructs the text-display gadget
  292.         to copy the supplied text string, instead of using only 
  293.         pointer to the string.  This only works for the initial value
  294.         of GTTX_Text set at CreateGadget() time.  If you subsequently
  295.         change GTTX_Text, the new text will be referenced by pointer,
  296.         not copied.  Do not use this tag with a NULL GTTX_Text.
  297.     GTTX_Border (BOOL) - If TRUE, this flag asks for a recessed
  298.         border to be placed around the gadget.
  299.  
  300.  
  301.    RESULT
  302.     gad - pointer to the new gadget, or NULL if the allocation failed
  303.         or if previous was NULL.
  304.  
  305.    EXAMPLE
  306.  
  307.    NOTES
  308.     Note that the ng_VisualInfo and ng_TextAttr fields of the
  309.     NewGadget structure must be set to valid VisualInfo and
  310.     TextAttr pointers, or this function will fail.
  311.  
  312.     Starting with V37, string and integer gadgets have the GFLG_TABCYCLE
  313.     feature automatically.  If the user presses Tab or Shift-Tab while
  314.     in a string or integer gadget, the next or previous one in
  315.     sequence will be activated.  You will hear a GADGETUP with a code
  316.     of 0x09.  Use {GA_TabCycle, FALSE} to supress this.
  317.     
  318.  
  319.    BUGS
  320.  
  321.    SEE ALSO
  322.     FreeGadgets(), GT_SetGadgetAttrs(), GetVisualInfo().
  323.  
  324. gadtools.library/CreateMenusA                   gadtools.library/CreateMenusA
  325.  
  326.    NAME
  327.     CreateMenusA -- Allocate and fill out a menu structure. (V36)
  328.     CreateMenus -- Varargs stub for CreateMenus(). (V36)
  329.  
  330.    SYNOPSIS
  331.     menu = CreateMenusA(newmenu, taglist)
  332.     D0                  A0       A1
  333.  
  334.     struct Menu *CreateMenusA(struct NewMenu *, struct TagItem *);
  335.  
  336.     menu = CreateMenus(newmenu, firsttag, ...)
  337.  
  338.     struct Menu *CreateMenus(struct NewMenu *, Tag, ...);
  339.  
  340.    FUNCTION
  341.     CreateMenusA() allocates and initializes a complete menu
  342.     structure based on the supplied array of NewMenu structures.
  343.     Optionally, CreateMenusA() can allocate and initialize a complete
  344.     set of menu items and sub-items for a single menu title.  This
  345.     is dictated by the contents of the array of NewMenus.
  346.  
  347.    INPUTS
  348.     newmenu - Pointer to an array of initialized struct NewMenus.
  349.     taglist - Pointer to a TagItem list.
  350.  
  351.    TAGS
  352.     GTMN_FrontPen (UBYTE) - Pen number to be used for menu text.
  353.         (defaults to zero).
  354.     GTMN_FullMenu (BOOL) - (GadTools V37 and higher only)
  355.         Requires that the NewMenu specification describes a complete
  356.         menu strip, not a fragment.  If a fragment is found,
  357.         CreateMenusA() will fail with a secondary error of
  358.         GTMENU_INVALID.  (defaults to FALSE).
  359.     GTMN_SecondaryError (ULONG *) - (GadTools V37 and higher only)
  360.         Supply a pointer to a NULL-initialized ULONG to receive a
  361.         descriptive error code.  Possible values:
  362.         GTMENU_INVALID - NewMenu structure describes an illegal
  363.             menu.  (CreateMenusA() will fail with a NULL result).
  364.         GTMENU_TRIMMED - NewMenu structure has too many menus, items,
  365.             or subitems (CreateMenusA() will succeed, returning a
  366.             trimmed-down menu structure).
  367.         GTMENU_NOMEM - CreateMenusA() ran out of memory.
  368.  
  369.    RESULT
  370.     menu - Pointer to the resulting initialized menu structure (or
  371.         the resulting FirstItem), with all the links for menu items
  372.         and subitems in place.
  373.         The result will be NULL if CreateMenusA() could not allocate
  374.         memory for the menus, or if the NewMenu array had an
  375.         illegal arrangement (eg. NM_SUB following NM_TITLE).
  376.         (see also the GTMN_SecondaryError tag above).
  377.  
  378.    EXAMPLE
  379.  
  380.    NOTES
  381.     The strings you supply for menu text are not copied, and must
  382.     be preserved for the life of the menu.
  383.     The resulting menus have no positional information.  You will
  384.     want to call LayoutMenusA() (or LayoutMenuItemsA()) to supply that.
  385.     CreateMenusA() automatically provides you with a UserData field
  386.     for each menu, menu-item or sub-item.  Use the GTMENU_USERDATA(menu)
  387.     or GTMENUITEM_USERDATA(menuitem) macro to access it.
  388.  
  389.    BUGS
  390.     At present, if you put images into menus using IM_ITEM
  391.     or IM_SUB for a NewMenu->Type, the image you supply must
  392.     be an ordinary struct Image.  You may not use a 'custom
  393.     image' (eg. one obtained from a boopsi image-class).
  394.  
  395.    SEE ALSO
  396.     LayoutMenusA(), FreeMenus(), gadtools.h/GTMENU_USERDATA(),
  397.     gadtools.h/GTMENUITEM_USERDATA()
  398.  
  399. gadtools.library/DrawBevelBoxA                 gadtools.library/DrawBevelBoxA
  400.  
  401.    NAME
  402.     DrawBevelBoxA -- Draws a bevelled box. (V36)
  403.     DrawBevelBox -- Varargs stub for DrawBevelBox(). (V36)
  404.  
  405.    SYNOPSIS
  406.     DrawBevelBoxA(rport, left, top, width, height, taglist)
  407.                   A0     D0    D1   D2     D3      A1
  408.  
  409.     VOID DrawBevelBoxA(struct RastPort *, WORD, WORD, WORD, WORD,
  410.         struct TagItem *taglist);
  411.  
  412.     DrawBevelBox(rport, left, top, width, height, firsttag, ...)
  413.  
  414.     VOID DrawBevelBox(struct RastPort *, WORD, WORD, WORD, WORD,
  415.         Tag, ...);
  416.  
  417.    FUNCTION
  418.     DrawBevelBoxA() renders a bevelled box of specified dimensions
  419.     into the supplied RastPort.
  420.  
  421.    INPUTS
  422.     rport - The RastPort into which the box is to be drawn.
  423.     left - The left edge of the box.
  424.     top - The top edge of the box.
  425.     width - The width of the box.
  426.     height - The height of the box.
  427.     taglist - Pointer to a TagItem list.
  428.  
  429.    TAGS
  430.     GTBB_Recessed (BOOL):  Set to anything for a recessed-looking box.
  431.         If absent, the box defaults, it would be raised.
  432.     GT_VisualInfo (APTR):  You MUST supply the value you obtained
  433.         from an earlier call to GetVisualInfoA().
  434.  
  435.    RESULT
  436.     None.
  437.  
  438.    EXAMPLE
  439.  
  440.    NOTES
  441.     DrawBevelBox() is a rendering operation, not a gadget.  That
  442.     means you must refresh it at the appropriate time, like any
  443.     other rendering operation.
  444.  
  445.    BUGS
  446.  
  447.    SEE ALSO
  448.     GetVisualInfoA()
  449.  
  450. gadtools.library/FreeGadgets                     gadtools.library/FreeGadgets
  451.  
  452.    NAME
  453.     FreeGadgets -- Free a linked list of gadgets. (V36)
  454.  
  455.    SYNOPSIS
  456.     FreeGadgets(glist)
  457.                 A0
  458.  
  459.     VOID FreeGadgets(struct Gadget *glist);
  460.                      A0
  461.  
  462.    FUNCTION
  463.     Frees any GadTools gadgets found on the linked list of gadgets
  464.     beginning with the specified one.  Frees all the memory that was
  465.     allocated by CreateGadgetA().  This function will return safely
  466.     with no action if it receives a NULL parameter.
  467.  
  468.    INPUTS
  469.     glist - pointer to first gadget in list to be freed.
  470.  
  471.    RESULT
  472.     none
  473.  
  474.    EXAMPLE
  475.  
  476.    NOTES
  477.  
  478.    BUGS
  479.  
  480.    SEE ALSO
  481.     CreateGadgetA()
  482.  
  483. gadtools.library/FreeMenus                         gadtools.library/FreeMenus
  484.  
  485.    NAME
  486.     FreeMenus -- Frees memory allocated by CreateMenusA(). (V36)
  487.  
  488.    SYNOPSIS
  489.     FreeMenus(menu)
  490.               A0
  491.  
  492.     VOID FreeMenus(struct Menu *);
  493.  
  494.    FUNCTION
  495.     Frees the menus allocated by CreateMenusA().  It is safe to
  496.     call this function with a NULL parameter.
  497.  
  498.    INPUTS
  499.     menu - Pointer to menu structure (or first MenuItem) obtained
  500.     from CreateMenusA().
  501.  
  502.    RESULT
  503.     None.
  504.  
  505.    EXAMPLE
  506.  
  507.    NOTES
  508.  
  509.    BUGS
  510.  
  511.    SEE ALSO
  512.     CreateMenusA()
  513.  
  514. gadtools.library/FreeVisualInfo               gadtools.library/FreeVisualInfo
  515.  
  516.    NAME
  517.     FreeVisualInfo -- Return any resources taken by GetVisualInfo. (V36)
  518.  
  519.    SYNOPSIS
  520.     FreeVisualInfo(vi)
  521.                    A0
  522.  
  523.     VOID FreeVisualInfo(APTR);
  524.  
  525.    FUNCTION
  526.     FreeVisualInfo() returns any memory or other resources that
  527.     were allocated by GetVisualInfoA().  You should only call this function
  528.     once you are done with using the gadgets (i.e. after CloseWindow()),
  529.     but while the screen is still valid (i.e. before CloseScreen() or
  530.     UnlockPubScreen()).
  531.  
  532.    INPUTS
  533.     vi - Pointer that was obtained by calling GetVisualInfoA().
  534.  
  535.    RESULT
  536.     None.
  537.  
  538.    EXAMPLE
  539.  
  540.    NOTES
  541.  
  542.    BUGS
  543.  
  544.    SEE ALSO
  545.     GetVisualInfoA()
  546.  
  547. gadtools.library/GetVisualInfoA               gadtools.library/GetVisualInfoA
  548.  
  549.    NAME
  550.     GetVisualInfoA -- Get information GadTools needs for visuals. (V36)
  551.     GetVisualInfo -- Varargs stub for GetVisualInfoA(). (V36)
  552.  
  553.    SYNOPSIS
  554.     vi = GetVisualInfoA(screen, taglist)
  555.     D0                  A0      A1
  556.  
  557.     APTR vi = GetVisualInfoA(struct Screen *, struct TagItem *);
  558.  
  559.     vi = GetVisualInfo(screen, firsttag, ...)
  560.  
  561.     APTR vi = GetVisualInfo(struct Screen *, Tag, ...);
  562.  
  563.    FUNCTION
  564.     Get a pointer to a (private) block of data containing various bits
  565.     of information that GadTools needs to ensure the best quality
  566.     visuals.  Use the result in the NewGadget structure of any gadget
  567.     you create, or as a parameter to the various menu calls.  Once the
  568.     gadgets/menus are no longer needed (after the last CloseWindow),
  569.     call FreeVisualInfo().
  570.  
  571.    INPUTS
  572.     screen - Pointer to the screen you will be opening on.
  573.     taglist - Pointer to list of TagItems.  
  574.  
  575.    RESULT
  576.     vi - Pointer to private data.
  577.  
  578.    EXAMPLE
  579.  
  580.    NOTES
  581.  
  582.    BUGS
  583.  
  584.    SEE ALSO
  585.     FreeVisualInfo(), intuition/LockPubScreen(),
  586.     intuition/UnlockPubScreen()
  587.  
  588. gadtools.library/GT_BeginRefresh             gadtools.library/GT_BeginRefresh
  589.  
  590.    NAME
  591.     GT_BeginRefresh -- Begin refreshing friendly to GadTools. (V36)
  592.  
  593.    SYNOPSIS
  594.     GT_BeginRefresh(win)
  595.                     A0
  596.  
  597.     VOID GT_BeginRefresh(struct Window *);
  598.  
  599.    FUNCTION
  600.     Invokes the intuition.library/BeginRefresh() function in a manner
  601.     friendly to the Gadget Toolkit.  This function call permits the
  602.     GadTools gadgets to refresh themselves at the correct time.
  603.     Call GT_EndRefresh() function when done.
  604.  
  605.    INPUTS
  606.     win - Pointer to Window structure for which a IDCMP_REFRESHWINDOW
  607.         IDCMP event was received.
  608.  
  609.    RESULT
  610.     None.
  611.  
  612.    EXAMPLE
  613.  
  614.    NOTES
  615.     The nature of GadTools precludes the use of the IDCMP flag
  616.     WFLG_NOCAREREFRESH.  You must handle IDCMP_REFRESHWINDOW events
  617.     in at least the minimal way, namely:
  618.  
  619.         case IDCMP_REFRESHWINDOW:
  620.             GT_BeginRefresh(win);
  621.             GT_EndRefresh(win, TRUE);
  622.             break;
  623.  
  624.    BUGS
  625.  
  626.    SEE ALSO
  627.     intuition.library/BeginRefresh()
  628.  
  629. gadtools.library/GT_EndRefresh                 gadtools.library/GT_EndRefresh
  630.  
  631.    NAME
  632.     GT_EndRefresh -- End refreshing friendly to GadTools. (V36)
  633.  
  634.    SYNOPSIS
  635.     GT_EndRefresh(win, complete)
  636.                   A0   D0
  637.  
  638.     VOID GT_EndRefresh(struct Window *, BOOL complete);
  639.  
  640.    FUNCTION
  641.     Invokes the intuition.library/EndRefresh() function in a manner
  642.     friendly to the Gadget Toolkit.  This function call permits
  643.     GadTools gadgets to refresh themselves at the correct time.
  644.     Call this function to EndRefresh() when you have used
  645.     GT_BeginRefresh().
  646.  
  647.    INPUTS
  648.     win - Pointer to Window structure for which a IDCMP_REFRESHWINDOW
  649.         IDCMP event was received.
  650.     complete - TRUE when done with refreshing.
  651.  
  652.    RESULT
  653.     None.
  654.  
  655.    EXAMPLE
  656.  
  657.    NOTES
  658.  
  659.    BUGS
  660.  
  661.    SEE ALSO
  662.     intuition.library/EndRefresh()
  663.  
  664. gadtools.library/GT_FilterIMsg                 gadtools.library/GT_FilterIMsg
  665.  
  666.    NAME
  667.     GT_FilterIMsg -- Filter an IntuiMessage through GadTools. (V36)
  668.  
  669.    SYNOPSIS
  670.     modimsg = GT_FilterIMsg(imsg)
  671.     D0                      A1
  672.  
  673.     struct IntuiMessage *GT_FilterIMsg(struct IntuiMessage *);
  674.  
  675.    FUNCTION
  676.     NOTE WELL:  Extremely few programs will actually need this function.
  677.     You almost certainly should be using GT_GetIMsg() and GT_ReplyIMsg()
  678.     only, and not GT_FilterIMsg() and GT_PostFilterIMsg().
  679.  
  680.     GT_FilterIMsg() takes the supplied IntuiMessage and asks the
  681.     Gadget Toolkit to consider and possibly act on it.  Returns
  682.     NULL if the message was only of significance to a GadTools gadget
  683.     (i.e. not to you), else returns a pointer to a modified IDCMP
  684.     message, which may contain additional information.
  685.     You should examine the Class, Code, and IAddress fields of
  686.     the returned message to learn what happened.  Do not make
  687.     interpretations based on the original imsg.
  688.     You should use GT_PostFilterIMsg() to revert to the original
  689.     IntuiMessage once you are done with the modified one.
  690.  
  691.    INPUTS
  692.     imsg - An IntuiMessage you obtained from a Window's UserPort.
  693.  
  694.    RESULT
  695.     modimsg - A modified IntuiMessage, possibly with extra information
  696.         from GadTools, or NULL.
  697.  
  698.    EXAMPLE
  699.  
  700.    NOTES
  701.  
  702.    BUGS
  703.  
  704.    SEE ALSO
  705.     GT_GetIMsg(), GT_PostFilterIMsg()
  706.  
  707. gadtools.library/GT_GetIMsg                       gadtools.library/GT_GetIMsg
  708.  
  709.    NAME
  710.     GT_GetIMsg -- Get an IntuiMessage, with GadTools processing. (V36)
  711.  
  712.    SYNOPSIS
  713.     imsg = GT_GetIMsg(intuiport)
  714.     D0                A0
  715.  
  716.     struct IntuiMessage *GT_GetIMsg(struct MsgPort *);
  717.  
  718.    FUNCTION
  719.     Use GT_GetIMsg() in place of the usual exec.library/GetMsg() when
  720.     reading IntuiMessages from your window's UserPort.  If needed,
  721.     the GadTools dispatcher will be invoked, and suitable processing
  722.     will be done for gadget actions.  This function returns a pointer
  723.     to a modified IntuiMessage (which is a copy of the original,
  724.     possibly with some supplementary information from GadTools).
  725.     If there are no messages (or if the only messages are meaningful
  726.     only to GadTools, NULL will be returned.
  727.  
  728.    INPUTS
  729.     intuiport - The Window->UserPort of a window that is using the
  730.         Gadget Toolkit.
  731.  
  732.    RESULT
  733.     imsg - Pointer to modified IntuiMessage, or NULL if there are
  734.         no applicable messages.
  735.  
  736.    EXAMPLE
  737.  
  738.    NOTES
  739.     Be sure to use GT_ReplyIMsg() and not exec.library/ReplyMsg() on
  740.     messages obtained with GT_GetIMsg().
  741.     If you intend to do more with the resulting message than read
  742.     its fields, act on it, and reply it, you may find GT_FilterIMsg()
  743.     more appropriate.
  744.  
  745.    BUGS
  746.  
  747.    SEE ALSO
  748.     GT_ReplyIMsg(), GT_FilterIMsg()
  749.  
  750. gadtools.library/GT_PostFilterIMsg         gadtools.library/GT_PostFilterIMsg
  751.  
  752.    NAME
  753.     GT_PostFilterIMsg -- Return the unfiltered message after
  754.         GT_FilterIMsg() was called, and clean up. (V36)
  755.  
  756.    SYNOPSIS
  757.     imsg = GT_PostFilterIMsg(modimsg)
  758.     D0                       A1
  759.  
  760.     struct IntuiMessage *GT_PostFilterIMsg(struct IntuiMessage *);
  761.  
  762.    FUNCTION
  763.     NOTE WELL:  Extremely few programs will actually need this function.
  764.     You almost certainly should be using GT_GetIMsg() and GT_ReplyIMsg()
  765.     only, and not GT_FilterIMsg() and GT_PostFilterIMsg().
  766.  
  767.     Performs any clean-up necessitated by a previous call to
  768.     GT_FilterIMsg().  The original IntuiMessage is now yours to handle.
  769.     Do not interpret the fields of the original IntuiMessage, but
  770.     rather use only the one you got from GT_FilterIMsg().  You
  771.     may only do message related things at this point, such as queueing
  772.     it up or replying it.  Since you got the message with
  773.     exec.library/GetMsg(), your responsibilities do include replying
  774.     it with exec.library/ReplyMsg(). This function may be safely
  775.     called with a NULL parameter.
  776.  
  777.    INPUTS
  778.     modimsg - A modified IntuiMessage obtained with GT_FilterIMsg().
  779.  
  780.    RESULT
  781.     imsg - A pointer to the original IntuiMessage, if GT_FilterIMsg()
  782.         returned non-NULL.
  783.  
  784.    EXAMPLE
  785.  
  786.    NOTES
  787.     Be sure to use exec.library/ReplyMsg() on the original IntuiMessage
  788.     you obtained with GetMsg(), (which is the what you passed to
  789.     GT_FilterIMsg()), and not on the parameter of this function.
  790.  
  791.    BUGS
  792.  
  793.    SEE ALSO
  794.     GT_FilterIMsg()
  795.  
  796. gadtools.library/GT_RefreshWindow           gadtools.library/GT_RefreshWindow
  797.  
  798.    NAME
  799.     GT_RefreshWindow -- Refresh all the GadTools gadgets. (V36)
  800.  
  801.    SYNOPSIS
  802.     GT_RefreshWindow(win, req)
  803.                      A0   A1
  804.  
  805.     VOID GT_RefreshWindow(struct Window *, struct Requester *);
  806.  
  807.    FUNCTION
  808.     Perform the initial refresh of all the GadTools gadgets you have
  809.     created.  After you have opened your window, you must call this
  810.     function.  Or, if you have opened your window without gadgets,
  811.     you add the gadgets with intuition.library/AddGList(),
  812.     refresh them using intuition.library/RefreshGList(), then call
  813.     this function.
  814.     You should not need this function at other times.
  815.  
  816.    INPUTS
  817.     win - Pointer to the Window containing GadTools gadgets.
  818.     req - Pointer to requester, or NULL if not a requester (currently
  819.         ignored - use NULL).
  820.  
  821.    RESULT
  822.     None.
  823.  
  824.    EXAMPLE
  825.  
  826.    NOTES
  827.     req must currently be NULL.  GadTools gadgets are not supported
  828.     in requesters.  This field may allow such support at a future date.
  829.  
  830.    BUGS
  831.  
  832.    SEE ALSO
  833.     GT_BeginRefresh()
  834.  
  835. gadtools.library/GT_ReplyIMsg                   gadtools.library/GT_ReplyIMsg
  836.  
  837.    NAME
  838.     GT_ReplyIMsg -- Reply a message obtained with GT_GetIMsg(). (V36)
  839.  
  840.    SYNOPSIS
  841.     GT_ReplyIMsg(imsg)
  842.                  A1
  843.  
  844.     VOID GT_ReplyIMsg(struct IntuiMessage *);
  845.  
  846.    FUNCTION
  847.     Reply a modified IntuiMessage obtained with GT_GetIMsg().
  848.     If you use GT_GetIMsg(), use this function where you would normally
  849.     have used exec.library/ReplyMsg().
  850.     You may safely call this routine with a NULL pointer (nothing
  851.     will be done).
  852.  
  853.    INPUTS
  854.     imsg - A modified IntuiMessage obtained with GT_GetIMsg().
  855.  
  856.    RESULT
  857.     None.
  858.  
  859.    EXAMPLE
  860.  
  861.    NOTES
  862.     When using GadTools, you MUST explicitly GT_ReplyIMsg()
  863.     all messages you receive.  You cannot depend on CloseWindow()
  864.     to handle messages you have not replied.
  865.  
  866.    BUGS
  867.  
  868.    SEE ALSO
  869.     GT_GetIMsg()
  870.  
  871. gadtools.library/GT_SetGadgetAttrsA       gadtools.library/GT_SetGadgetAttrsA
  872.  
  873.    NAME
  874.     GT_SetGadgetAttrsA -- Change the attributes of a GadTools gadget. (V36)
  875.     GT_SetGadgetAttrs -- Varargs stub for GT_SetGadgetAttrsA(). (V36)
  876.  
  877.    SYNOPSIS
  878.     GT_SetGadgetAttrsA(gad, win, req, taglist)
  879.                        A0   A1   A2   A3
  880.  
  881.     VOID GT_SetGadgetAttrsA(struct Gadget *, struct Window *,
  882.         struct Requester *, struct TagItem *);
  883.  
  884.     GT_SetGadgetAttrs(gad, win, req, firsttag, ...)
  885.  
  886.     VOID GT_SetGadgetAttrs(struct Gadget *, struct Window *,
  887.         struct Requester *, Tag, ...);
  888.  
  889.    FUNCTION
  890.     Change the attributes of the specified gadget, according to the
  891.     attributes chosen in the tag list.
  892.  
  893.    INPUTS
  894.     gad - Pointer to the gadget in question.
  895.     win - Pointer to the window containing the gadget.
  896.     req - Pointer to the requester containing the gadget, or NULL if
  897.         not in a requester.  (Not yet implemented, use NULL).
  898.     taglist - Pointer to TagItem list.
  899.  
  900.    TAGS
  901.     BUTTON_KIND:
  902.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  903.         (defaults to FALSE).
  904.  
  905.     CHECKBOX_KIND:
  906.     GTCB_Checked (BOOL) - Initial state of checkbox, defaults to FALSE.
  907.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  908.         (defaults to FALSE).
  909.  
  910.     CYCLE_KIND:
  911.     GTCY_Active (UWORD) - The ordinal number (counting from zero) of
  912.         the active choice of a cycle gadget (defaults to zero).
  913.     GTCY_Labels (STRPTR *) - (GadTools V37 and higher only)
  914.         Pointer to NULL-terminated array of strings
  915.         that are the choices offered by the cycle gadget.
  916.     GA_Disabled (BOOL) - (GadTools V37 and higher only)
  917.         Set to TRUE to disable gadget, FALSE otherwise
  918.         (defaults to FALSE).
  919.  
  920.     INTEGER_KIND:
  921.     GTIN_Number (ULONG) - The initial contents of the integer gadget
  922.         (default zero).
  923.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  924.         (defaults to FALSE).
  925.  
  926.     LISTVIEW_KIND:
  927.     GTLV_Top (WORD) - Top item visible in the listview.  This value
  928.         will be made reasonable if out-of-range (defaults to zero).
  929.     GTLV_Labels (struct List *) - List of labels whose ln_Name fields
  930.         are to be displayed in the listview.  Use a value of ~0 to
  931.         "detach" your List from the display.  You must detach your list
  932.         before modifying the List structure, since GadTools reserves
  933.         the right to traverse it on another task's schedule.  When you
  934.         are done, attach the list by using the tag pair
  935.         {GTLV_Labels, list}.
  936.     GTLV_Selected (UWORD) - Ordinal number of currently selected
  937.         item (defaults to zero if GTLV_ShowSelected is set).
  938.  
  939.     MX_KIND:
  940.     GTMX_Active (UWORD) - The ordinal number (counting from zero) of
  941.         the active choice of an mx gadget (Defaults to zero).
  942.  
  943.     NUMBER_KIND:
  944.     GTNM_Number - A signed long integer to be displayed as a read-only
  945.          number (default 0).
  946.  
  947.     PALETTE_KIND:
  948.     GTPA_Color (UBYTE) - Initially selected color of the palette
  949.         (defaults to 1).
  950.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  951.         (defaults to FALSE).
  952.  
  953.     SCROLLER_KIND:
  954.     GTSC_Top (WORD) - Top visible in scroller (defaults to zero).
  955.     GTSC_Total (WORD) - Total in scroller area (defaults to zero).
  956.     GTSC_Visible (WORD) - Number visible in scroller (defaults to 2).
  957.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  958.         (defaults to FALSE).
  959.  
  960.     SLIDER_KIND:
  961.     GTSL_Min (WORD) - Minimum level for slider (default 0).
  962.     GTSL_Max (WORD) - Maximum level for slider (default 15).
  963.     GTSL_Level (WORD) - Current level of slider (default 0).
  964.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  965.         (defaults to FALSE).
  966.  
  967.     STRING_KIND:
  968.     GTST_String (STRPTR) - The initial contents of the string gadget,
  969.          or NULL (default) if string is to start empty.
  970.     GA_Disabled (BOOL) - Set to TRUE to disable gadget, FALSE otherwise
  971.         (defaults to FALSE).
  972.  
  973.     TEXT_KIND:
  974.     GTTX_Text - Pointer to a NULL terminated string to be displayed,
  975.         as a read-only text-display gadget, or NULL. defaults to NULL.
  976.  
  977.    RESULT
  978.     None.
  979.  
  980.    EXAMPLE
  981.  
  982.    NOTES
  983.     req must currently be NULL.  GadTools gadgets are not supported
  984.     in requesters.  This field may allow such support at a future date.
  985.  
  986.     This function may not be called inside of a GT_BeginRefresh() /
  987.     GT_EndRefresh() session.  (As always, restrict yourself to simple
  988.     rendering functions).
  989.  
  990.    BUGS
  991.  
  992.    SEE ALSO
  993.  
  994. gadtools.library/LayoutMenuItemsA           gadtools.library/LayoutMenuItemsA
  995.  
  996.    NAME
  997.     LayoutMenuItemsA -- Position all the menu items. (V36)
  998.     LayoutMenuItems -- Varargs stub for LayoutMenuItemsA(). (V36)
  999.  
  1000.    SYNOPSIS
  1001.     success = LayoutMenuItemsA(menuitem, vi, taglist)
  1002.     D0                         A0        A1  A2
  1003.  
  1004.     BOOL LayoutMenuItemsA(struct MenuItem *, APTR, struct TagItem *);
  1005.  
  1006.     success = LayoutMenuItems(menuitem, vi, firsttag, ...)
  1007.  
  1008.     BOOL LayoutMenuItemsA(struct MenuItem *, APTR, Tag, ...);
  1009.  
  1010.    FUNCTION
  1011.     Lays out all the menu items and sub-items according to
  1012.     the supplied visual information and tag parameters.  You would use this
  1013.     if you used CreateMenusA() to make a single menu-pane (with sub-items,
  1014.     if any), instead of a whole menu strip.
  1015.     This routine attempts to columnize and/or shift the MenuItems in
  1016.     the event that a menu would be too tall or too wide.
  1017.  
  1018.    INPUTS
  1019.     menuitem - Pointer to first MenuItem in a linked list of
  1020.         items.
  1021.     vi - Pointer returned by GetVisualInfoA().
  1022.     taglist - Pointer to a TagItem list.
  1023.  
  1024.    TAGS
  1025.     GTMN_TextAttr (struct TextAttr *) - Text Attribute to use for
  1026.         menu-items and sub-items.  If not supplied, the screen's
  1027.         font will be used.  This font must be openable via OpenFont()
  1028.         when this function is called.
  1029.     GTMN_Menu (struct Menu *) - Pointer to the Menu structure whose
  1030.         FirstItem is the MenuItem supplied above.  If the menu items are
  1031.         such that they need to be columnized or shifted, the Menu
  1032.         structure is needed to perform the complete calculation.
  1033.         It is suggested you always provide this information.
  1034.  
  1035.    RESULT
  1036.     success - TRUE if successful, false otherwise (signifies that
  1037.         the TextAttr wasn't openable).
  1038.  
  1039.    EXAMPLE
  1040.  
  1041.    NOTES
  1042.  
  1043.    BUGS
  1044.     If a menu ends up being wider than the whole screen, it will
  1045.     run off the right-hand side.
  1046.  
  1047.    SEE ALSO
  1048.     CreateMenusA(), GetVisualInfoA()
  1049.  
  1050. gadtools.library/LayoutMenusA                   gadtools.library/LayoutMenusA
  1051.  
  1052.    NAME
  1053.     LayoutMenusA -- Position all the menus and menu items. (V36)
  1054.     LayoutMenus -- Varargs stub for LayoutMenusA(). (V36)
  1055.  
  1056.    SYNOPSIS
  1057.     success = LayoutMenusA(menu, vi, taglist)
  1058.     D0                     A0    A1  A2
  1059.  
  1060.     BOOL LayoutMenusA(struct Menu *, APTR, struct TagItem *);
  1061.  
  1062.     success = LayoutMenus(menu, vi, firsttag, ...)
  1063.  
  1064.     BOOL LayoutMenus(struct Menu *, APTR, Tag, ...);
  1065.  
  1066.    FUNCTION
  1067.     Lays out all the menus, menu items and sub-items in the supplied
  1068.     menu according to the supplied visual information and tag parameters.
  1069.     This routine attempts to columnize and/or shift the MenuItems in
  1070.     the event that a menu would be too tall or too wide.
  1071.  
  1072.    INPUTS
  1073.     menu - Pointer to menu obtained from CreateMenusA().
  1074.     vi - Pointer returned by GetVisualInfoA().
  1075.     taglist - Pointer to a TagItem list.
  1076.  
  1077.    TAGS
  1078.     GTMN_TextAttr (struct TextAttr *) - Text Attribute to use for
  1079.         menu-items and sub-items.  If not supplied, the screen's
  1080.         font will be used.  This font must be openable via OpenFont()
  1081.         when this function is called.
  1082.  
  1083.    RESULT
  1084.     success - TRUE if successful, false otherwise (signifies that
  1085.         the TextAttr wasn't openable).
  1086.  
  1087.    EXAMPLE
  1088.  
  1089.    NOTES
  1090.     When using this function, there is no need to also call
  1091.     LayoutMenuItemsA().
  1092.  
  1093.    BUGS
  1094.     If a menu ends up being wider than the whole screen, it will
  1095.     run off the right-hand side.
  1096.  
  1097.    SEE ALSO
  1098.     CreateMenusA(), GetVisualInfoA()
  1099.  
  1100.