home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Workbench / Libs / GADUTIL.LHA / GadUtil / Docs / AutoDocs / 03.GU_CreateGadgetA < prev    next >
Encoding:
Text File  |  1995-06-17  |  3.3 KB  |  94 lines
  1. gadutil.library/GU_CreateGadgetA                gadutil.library/CreateGadgetA
  2.  
  3.    NAME
  4.     GU_CreateGadgetA -- Create a gadget with built-in hotkey support.
  5.  
  6.    SYNOPSIS
  7.     gad = CreateGadgetA(kind, prevgad, newgad, taglist)
  8.     D0,A0               D0    A0       A1      A2
  9.  
  10.     struct Gadget *GU_CreateGadgetA(ULONG, struct Gadget *,
  11.                     struct NewGadget *, struct TagItem *);
  12.  
  13.    FUNCTION
  14.     GU_CreateGadgetA() allocates and initializes a new gadget of the
  15.     specified kind, and attaches it to the previous gadget. The gadget
  16.     is created based on the supplied kind, NewGadget structure, and
  17.     tags.
  18.  
  19.     This function differs from the GadTools equivalent by supporting
  20.     some extra tags to allow the gadget to be selected using the
  21.     keyboard.
  22.  
  23.    INPUTS
  24.     kind - kind of gadget to create. One of the XXX_KIND values
  25.            defined in <libraries/gadtools.h>.
  26.  
  27.     prevgad - pointer to the previous gadget that this new gadget
  28.           should be attached to. This function will fail if
  29.           this value is NULL.
  30.  
  31.     newgad - a filled in NewGadget structure describing the desired
  32.          gadget's size, position, label, etc.
  33.  
  34.     taglist - pointer to an array of tags providing optional extra
  35.           parameters, or NULL.
  36.  
  37.    TAGS
  38.     All kinds:
  39.  
  40.     GT_Underscore - Indicates the symbol that precedes the character
  41.         in the gadget label to be underscored. This can be to
  42.         indicate keyboard equivalents for gadgets. GadUtil has
  43.         the ability to process the keyboard equivalents if some
  44.         other tags are used.
  45.  
  46.     GU_Hotkey - This tag selects the hotkey to be used as an automatic
  47.         keyboard command for the gadget. The ti_Data field should
  48.         contain the ASCII or RAWKEY code for the hotkey.
  49.         This tag may be used together with the GU_HotkeyCase and
  50.         GU_LabelHotkey. The GU_RawKey tag requires this tag.
  51.  
  52.     GU_HotkeyCase - This tag makes the keyboard command case-sensitive.
  53.         This tag may not be used with GU_RawKey.
  54.  
  55.     GU_LabelHotkey - This tag picks the hotkey from the gadget text
  56.         field in the NewGadget structure when the gadget is created.
  57.         If no key is marked with the underscore, the GU_HotKey code
  58.         will be used.
  59.  
  60.         This tag supports and requires the GT_Underscore tag. The
  61.         character that was given in the GT_Underscore tag will be
  62.         used to find the code for the hotkey.
  63.  
  64.     GU_RawKey - This tag makes the hotkey code to a RAWKEY code. All
  65.         keys on the keyboard has one rawkey code that matches the
  66.         key.
  67.  
  68.         If your program also gets VANILLAKEY events, you must be
  69.         careful when selecting the rawkey code to be used as a
  70.         keyboard shortcut for this gadget. RAWKEY events will only
  71.         be sent for special keys (such as the HELP, Control, Alt
  72.         and function keys) that don't map to a single character. 
  73.         All keys that maps to a single character will be processed
  74.         as a VANILLAKEY event.
  75.  
  76.         This tag may not be used with (and will also disable) the
  77.         GU_HotkeyCase and GU_LabelHotkey tags.
  78.  
  79.     Kind specific tags:
  80.         See the GadTools function CreateGadgetA for all other tags.
  81.  
  82.    RESULT
  83.     gad - pointer to the new gadget, or NULL if the allocation failed
  84.           or if prevgad was NULL.
  85.  
  86.    NOTES
  87.     Note that the ng_VisualInfo and ng_TextAttr fields of the NewGadget
  88.     structure must be set to valid VisualInfo and TextAttr pointers, or
  89.     this function will fail.
  90.  
  91.    SEE ALSO
  92.     GU_FreeGadgets(), GU_SetGadgetAttrsA(), GU_GetVisualInfoA(),
  93.     GU_GetIMsg, gadtools/CreateGadgetA, <libraries/gadtools.h>
  94.